应用定时器的配置和使用方法

应用定时器的概念相信大家都不陌生。它是一种内核对象，可为执行任务提供简单的事件计时方法，或者更常见的是定期执行一个活动。这篇文章我们将为大家介绍Nucleus SE中定时功能的配置、服务案例和API调用等。

定时器的使用

应用定时器可以被配置为一次性的，即它被启动后，在指定的时间段后就简单地终止了。计时器也可以配置为重复性的，即当它到期时会自动重启，重启时段的时间间隔可能与初始时间不同。定时器还可以有选择性地配置为运行一个特定功能，比如当（或每次）定时器到期时就执行一个到期例程。

定时器的配置

定时器数量

与Nucleus SE的大多数功能一样，定时器的配置主要由nuse_config.h中的#define语句控制。键设置是NUSE_TIMER_NUMBER，用来确定为应用程序配置的定时器数量。默认设置为0（即没有使用定时器），你可以将其设置为0-16之间的任意值。错误的值将导致编译时间错误，该错误由nuse_config_check.h中的测试产生（这包含在nuse_config.c内，并因此使用此模块编译），导致一个#error语句被编译。

选择非零值是定时器的“主启用”，这将导致一些数据结构被定义，大小也相应地调整，本文稍后将对其进行详细介绍。它还会激活API启用设置。

到期例程启用

在Nucleus SE中，我一直在寻找可选的功能，省略它们会节省内存。一个很好的例子是定时器到期例程的支持。除了对每个单独的计时器可选之外，还可以通过nuse_config.h中的NUSE_TIMER_EXPIRATION_ROUTINE_SUPPORT设置为整个应用程序启用（或不启用）这一工具。将此设置为FALSE会抑制两个ROM数据结构的定义，本文后面将对其进行更详细的介绍。

API启用

Nucleus SE中的每个API功能（服务调用）在nuse_config.h中都有一个启用#define符号。对于定时器，这些是：

默认情况下，所有这些都设置为FALSE，从而禁用每个服务调用并禁止包含任何实现代码。要为应用程序配置定时器，需要选择要使用的API调用，并将其启用符号设置为TRUE。

以下是默认nuse_config.h文件的摘录。

如果启用了定时器API功能但未配置定时器（除了始终允许的NUSE_Timer_Count()之外），则会产生编译时间错误。如果您的代码使用了尚未启用的API调用，则会产生链接时间错误，因为应用程序中不会包含任何实现代码。

定时服务呼叫

Nucleus RTOS支持八个与定时器相关的服务调用，它们提供以下功能：

• 控制（启动/停止）定时器。 由Nucleus SE中的NUSE_Timer_Control()实现。

• 从定时器获取剩余时间。 由Nucleus SE中的NUSE_Timer_Get_Remaining()实现。

• 将定时器恢复到未使用状态（重置）。 由Nucleus SE中的NUSE_Timer_Reset()实现。

• 提供有关指定定时器的信息。 由Nucleus SE中的NUSE_Timer_Information()实现。

• 返回为应用程序配置（当前）的计时器数量。 由Nucleus SE中的NUSE_Timer_Count()实现。

• 向应用程序添加新的定时器（创建）。未在Nucleus SE中实现。

• 从应用程序中删除定时器（删除）。 未在Nucleus SE中实现。

• 返回指向应用程序中所有定时器（当前）的指针。未在Nucleus SE中实现。

下面我们详细介绍每个服务调用的实现。

定时服务

可以在定时器上执行的基本操作是控制它，包括启动和停止，并读取其当前值。 Nucleus RTOS和Nucleus SE都为这些操作提供了两个基本的API调用，下面我们将详细讨论。

控制定时器

用于控制定时器的Nucleus RTOS API调用仅允许启用或禁用定时器（即启动或停止）。Nucleus SE提供相同的服务。

Nucleus RTOS API调用定时器的控制

服务调用原型：

STATUS NU_Control_Timer(NU_TIMER *timer, OPTION enable);
参数：

timer - 指向用户提供的定时器控制模块的指针
enable –必需的功能;可能是NU_ENABLE_TIMER或NU_DISABLE_TIMER

返回：

NU_SUCCESS –调用已成功完成
NU_INVALID_TIMER –定时器指针无效
NU_INVALID_ENABLE – 指定的功能无效

Nucleus SE API调用定时器的控制

此API调用可支持Nucleus RTOS API的全部功能。

服务调用原型：

STATUS NUSE_Timer_Control(NUSE_TIMER timer, OPTION enable);

参数：

timer – 要使用的定时器索引(ID)
enable –必需的功能;可能是NUSE_ENABLE_TIMER或NUSE_DISABLE_TIMER

返回：

NUSE_SUCCESS – 调用已成功完成
NUSE_INVALID_TIMER —定时器指针无效
NUSE_INVALID_ENABLE – 指定的功能无效

Nucleus SE对定时器控制的实现

NUSE_Timer_Control() API功能的代码 - 在参数检查之后 - 相当简单：

如果指定的功能是NUSE_DISABLE_TIMER，则定时器的状态（NUSE_Timer_Status[]条目）设置为FALSE，这将导致它被时钟ISR忽略。

如果指定了NUSE_ENABLE_TIMER，则定时器计数器（NUSE_Timer_Value[]）设置为NUSE_Timer_Initial_Time[]，如果定时器自上次重置后从未到期的话。否则将其设置为NUSE_Timer_Reschedule_Time[]。然后定时器的状态（NUSE_Timer_Status[]条目）设置为TRUE，这导致它由时钟ISR处理。

读取定时器

用于从定时器获取剩余时间的Nucleus RTOS API调用就是这样，即返回它到期之前的滴答数。Nucleus SE提供相同的服务。

Nucleus RTOS API调用获取剩余时间

服务调用原型：

STATUS NU_Get_Remaining_Time (NU_TIMER *timer,
UNSIGNED *remaining_time);

参数：

timer - 指向用户提供的定时器控制模块的指针。
remaining_time - 指向剩余时间值的存储位置的指针，这是UNSIGNED类型的单变量

返回：

NU_SUCCESS – 调用已成功完成
NU_INVALID_TIMER – 定时器指针无效

此API调用可支持Nucleus RTOS API的全部功能。

服务调用原型：

STATUS NUSE_Timer_Get_Remaining(NUSE_TIMER timer,
U16 *remaining_time);

参数：

timer –要使用的定时器索引(ID)
remaining_time - 指向剩余时间值的存储位置的指针，这是U16类型的单变量

返回：

NUSE_SUCCESS – 调用已成功完成
NUSE_INVALID_TIMER – 定时器索引无效
NUSE_INVALID_POINTER – 剩余时间指针为NULL

Nucleus SE实现定时器读取

在参数检查之后，NUSE_ Timer_Get_Remaining() API功能的大部分代码几乎都很简单。NUSE_Timer_Value[]的值在关键部分获取并返回。

定时器实用服务

Nucleus RTOS有四个API调用，提供与定时器相关的实用程序功能：重置计时器、返回有关定时器的信息、返回应用程序的定时器数量，以及返回指向应用程序中所有定时器的指针。前三个在Nucleus SE中也有实现。

重置定时器

此API调用将定时器还原到其初始的未使用状态。完成此调用后，可以启用或禁用定时器。仅在禁用定时器后才可以启动该API调用（使用NUSE_Timer_Control()）。在下一次启用定时器时，将使用NUSE_Timer_Initial_Time[]的条目对其进行初始化。在重置定时器时，Nucleus RTOS允许提供新的初始化和重新安排时间，并指定到期的例程。而在Nucleus SE中，这些值在配置时已经设置好，不能更改，因为它们可能存储在ROM中。

Nucleus RTOS API调用重置定时器

服务调用原型：
STATUS NU_Reset_Timer(NU_TIMER *timer,
VOID (*expiration_routine)(UNSIGNED), UNSIGNED initial_time,
UNSIGNED reschedule_time, OPTION enable);

参数：

timer - 指向要重置的定时器的指针
expiration_routine -定时器到期时指定要执行的应用程序例程
initial_time - 定时器到期的初始计时滴答数
reschedule_time - 第一次到期后的定时器到期滴答数
enable - 复位后要求的状态；可能是NU_ENABLE_TIMER或NU_DISABLE_TIMER

返回：

NU_SUCCESS – 调用已成功完成
NU_INVALID_TIMER – 定时器控制模块指针无效
NU_INVALID_FUNCTION – 到期函数指针为NULL
NU_INVALID_ENABLE – 指定的状态无效
NU_NOT_DISABLED – 当前时间已启用（重置前需要禁用）

Nucleus SE API调用重置定时器

此API调用可支持Nucleus RTOS API的关键功能的简化版本：

STATUS NUSE_Timer_Reset(NUSE_TIMER timer, OPTION enable);

参数：

timer - 要重置的定时器的索引(ID)
enable - 复位后要求的状态;可能是NUSE_ENABLE_TIMER或NUSE_DISABLE_TIMER

返回：

NUSE_SUCCESS – 调用已成功完成
NUSE_INVALID_TIMER – 定时器索引无效
NUSE_INVALID_ENABLE – 指定的状态无效
NUSE_NOT_DISABLED – 当前时间已启用（重置前需要禁用）

Nucleus SE实现定时器复位

在参数和当前状态检查之后，NUSE_Timer_Reset() API功能的大部分代码都非常简单：

NUSE_CS_Enter();
NUSE_Init_Timer(timer);
if (enable == NUSE_ENABLE_TIMER)
{
NUSE_Timer_Status[timer] = TRUE;
}
/* else enable == NUSE_DISABLE_TIMER and status remains FALSE */
NUSE_CS_Exit();

调用NUSE_Init_Timer()，初始化时间值并清除到期计数器。然后，如果需要，将检查所需状态并启用定时器。

定时器信息

该服务调用获得有关定时器的选择信息。Nucleus SE实现与Nucleus RTOS的不同之处在于它返回的信息较少，因为它不支持对象命名。

Nucleus RTOS API调用定时器信息

服务调用原型：

STATUS NU_Timer_Information(NU_TIMER *timer, CHAR *name,
OPTION *enable, UNSIGNED *expirations, UNSIGNED *id,
UNSIGNED *initial_time, UNSIGNED *reschedule_time);

参数：

timer –指向正在请求信息的定时器的指针
name - 指向定时器名称的8个字符目标区域的指针。
enable - 指向变量的指针，将接收定时器的当前启用状态：
NU_ENABLE_TIMER或NU_DISABLE_TIMER
expirations - 指向类型变量的指针，该变量将接收定时器自上次重置以来已过期的次数
id - 指向变量的指针，将接收传递给定时器到期例程的参数值
initial_time - 指向变量的指针，将接收定时器在复位时初始化的值
reschedule_time - 指向变量的指针，将接收定时器在到期时初始化的值

返回：

NU_SUCCESS – 调用已成功完成
NU_INVALID_TIMER – 定时器指针无效

Nucleus SE API调用定时器信息

此API调用可支持Nucleus RTOS API的关键功能。

服务调用原型：

STATUS NUSE_Timer_Information(NUSE_TIMER timer, OPTION *enable,
U8 *expirations, U8 *id, U16 *initial_time, U16 *reschedule_time);

参数：

timer - 请求信息的定时器的索引
enable - 指向变量的指针，根据定时器是否启用，该变量将接收TRUE或FALSE值
expirations - 指向U8类型变量的指针，它将接收定时器自上次重置以来已过期的次数
id - 指向U8类型变量的指针，它将接收传递给定时器的到期例程的参数值（如果禁用了过期例程，则不返回任何信息）
initial_time - 指向U16类型变量的指针，它将接收定时器在复位时初始化的值
reschedule_time - 指向U16类型变量的指针，它将接收定时器在到期时初始化的值

返回：

NUSE_SUCCESS – 调用已成功完成
NUSE_INVALID_TIMER – 定时器索引无效
NUSE_INVALID_POINTER – 一个或多个指针参数无效

Nucleus SE实现定时器信息

这个API调用的实现非常简单：

NUSE_CS_Enter();
if (NUSE_Timer_Status[timer])
{
*enable = NUSE_ENABLE_TIMER;
}
else
{
*enable = NUSE_DISABLE_TIMER;
}
*expirations = NUSE_Timer_Expirations_Counter[timer];
#if NUSE_TIMER_EXPIRATION_ROUTINE_SUPPORT
*id = NUSE_Timer_Expiration_Routine_Parameter[timer];
#endif
*initial_time = NUSE_Timer_Initial_Time[timer];
*reschedule_time = NUSE_Timer_Reschedule_Time[timer];
NUSE_CS_Exit();

该功能返回定时器状态。 仅当应用程序中启用了过期例程时，才会返回到期例程参数的值。

获取定时器的数量

此服务调用返回应用程序中配置的定时器数量。在Nucleus RTOS中，这将随时间变化而不同，返回值将代表当前的定时器数量。在Nucleus SE中，返回的值在构建时已经设置好，不能更改。

Nucleus RTOS API调用定时器计数

服务调用原型：

UNSIGNED NU_Established_Timers(VOID);

参数：

无

返回：

应用程序中配置的定时器数量。

定时器计数的实现

此API调用的实现几乎非常简单：返回#define符号NUSE_TIMER_NUMBER的值。

数据结构

在RAM和ROM中，定时器使用五个或七个数据结构，与其他Nucleus SE对象一样，是一系列表，根据配置的定时器数量和选择的选项确定所包含的内容和尺寸信息。

我强烈建议应用程序代码不要直接访问这些数据结构，而是使用所提供的API功能。这避免了与Nucleus SE未来版本的不兼容和不必要的副作用，并简化了将应用程序移植到Nucleus RTOS的过程。此处包含数据结构的详细信息，以便于理解服务调用代码的工作原理和调试。

RAM数据

这些数据结构是：

NUSE_Timer_Status[] - 这是一个U8类型的数组，每个配置的定时器都有一个条目，并且是存储定时器状态（运行或停止：TRUE或FALSE）的位置。

NUSE_Timer_Value [] - 这是一个U16类型的数组，每个配置的定时器有一个条目，它包含定时器计数器的当前值。

NUSE_Timer_Expirations_Counter [] - 此类型的U8数组包含定时器自上次重置以来到期次数的计数。

当Nucleus SE启动时，这些数据结构都由NUSE_Init_Timer()初始化。今后我们还会给出Nucleus SE启动程序的完整描述。

以下是nuse_init.c文件中这些数据结构的定义：

RAM U8 NUSE_Timer_Status[NUSE_TIMER_NUMBER];
RAM U16 NUSE_Timer_Value[NUSE_TIMER_NUMBER];
RAM U8 NUSE_Timer_Expirations_Counter[NUSE_TIMER_NUMBER];

ROM数据

这些数据结构是：

NUSE_Timer_Initial_Time [] - 这是一个U16类型的数组，每个配置的定时器都有一个条目，并且是存储每个定时器计数器的初始值的位置。

NUSE_Timer_Reschedule_Time [] - 这是一个U16类型的数组，每个配置的定时器都有一个条目，其中包含每个定时器的计数器应在到期时设置的值。值为零表示定时器是“一次性的”，不应自动重启。

NUSE_Timer_Expiration_Routine_Address [] - 此类型的ADDR数组包含定时器的到期例程的地址。仅当启用了定时器到期例程支持时，此数组才存在。

NUSE_Timer_Expiration_Routine_Parameter [] - 此类型U8数组包含将传递给定时器的到期例程的参数值。仅当启用了定时器到期例程支持时，此数组才存在。

这些数据结构都在nuse_config.c中声明和初始化（当然是静态的），因此：

ROM U16 NUSE_Timer_Initial_Time[NUSE_TIMER_NUMBER] =
{
/* timer initial times ------ */
};
ROM U16 NUSE_Timer_Reschedule_Time[NUSE_TIMER_NUMBER] =
{
/* timer reschedule times ------ */
};
#if NUSE_TIMER_EXPIRATION_ROUTINE_SUPPORT || NUSE_INCLUDE_EVERYTHING
/* need prototypes of expiration routines here */
ROM ADDR
NUSE_Timer_Expiration_Routine_Address[NUSE_TIMER_NUMBER] =
{
/* addresses of timer expiration routines ------ */
/* can be NULL */
};
ROM U8
NUSE_Timer_Expiration_Routine_Parameter[NUSE_TIMER_NUMBER] =
{
/* timer expiration routine parameters ------ */
};
#endif

定时器数据占用空间

与Nucleus SE中的所有内核对象一样，定时器所需的数据存储量很容易预测。

可以计算应用程序中所有定时器的RAM数据占用空间（以字节为单位）：

NUSE_TIMER_NUMBER * 4

如果不支持到期例程，则可以计算应用程序中所有定时器的ROM数据占用空间（以字节为单位）：

NUSE_TIMER_NUMBER * 4

否则，它是：

NUSE_TIMER_NUMBER * (sizeof(ADDR) + 5)

未实现的API调用

Nucleus RTOS的三个定时器API调用没有在Nucleus SE中实现：

创建定时器

此API调用会创建一个定时器。 Nucleus SE不需要它，因为定时器是静态创建的。

服务调用原型：

STATUS NU_Create_Timer(NU_TIMER *timer, CHAR *name,
VOID (*expiration_routine)(UNSIGNED), UNSIGNED id,
UNSIGNED initial_time, UNSIGNED reschedule_time, OPTION enable);

参数：

timer - 指向用户提供的定时器控制块的指针，这将用作其他API调用中定时器的“句柄”
name - 指向定时器的7个字符，以null结尾的名称的指针
expiration_routine - 指定定时器到期时要执行的应用程序例程
id - 提供给到期例程的UNSIGNED数据元素，该参数可用于帮助识别使用相同到期例程的定时器
initial_time - 指定定时器到期的初始计时器滴答数
reschedule_time - 指定第一次到期后的定时器到期滴答数，如果此参数为零，则定时器仅到期一次
enable - 此参数的有效选项为NU_ENABLE_TIMER 和NU_DISABLE_TIMER; NU_ENABLE_TIMER在创建后激活定时器; NU_DISABLE_TIMER禁用定时器;必须通过稍后调用NU_Control_Timer来启用由NU_DISABLE_TIMER创建的定时器

返回：

NU_SUCCESS – 表示服务成功完成
NU_INVALID_TIMER –表示定时器控制块指针为NULL或已在使用中
NU_INVALID_FUNCTION – 表示到期函数指针为NULL
NU_INVALID_ENABLE – 表示enable参数无效
NU_INVALID_OPERATION –表示initial_time参数为零

删除定时器

此API调用可以删除已经创建的定时器。Nucleus SE不需要它，因为定时器是静态创建的，无法删除。

服务调用原型：

UNSIGNED NU_Timer_Pointers(NU_TIMER **pointer_list,
UNSIGNED maximum_pointers);

参数：

timer - 指向定时器控制块的指针

返回：

NU_SUCCESS – 表示服务成功完成
NU_INVALID_TIMER –表示定时器指针无效
NU_NOT_DISABLED –表示未禁用指定的计时器

定时器指针

此API调用构建一个指针顺序列表，指向系统中所有定时器。 Nucleus SE不需要它，因为定时器由简单的索引而不是指针识别，它是多余的。

参数：

pointer_list - 指向NU_TIMER指针数组的指针，这个数组将填充指向系统中已建的定时器的指针
maximum_pointers - 放置在数组中的最大指针数

返回：

放入数组的NU_TIMER指针数

与Nucleus RTOS的兼容性

对于Nucleus SE的各个方面，我的目标是尽可能保持与Nucleus RTOS兼容的应用程序代码级别，定时器也不例外。从用户的角度来看，它们的实现方式与Nucleus RTOS中的实现方式大致相同。有些不兼容的地方，我已经确定这样的不兼容性是可以接受的，因为生成的代码更容易理解，或者更有可能使存储效率更高。否则，Nucleus RTOS API调用几乎可以直接映射到Nucleus SE调用。后续文章将进一步介绍有关将Nucleus SE信息用于Nucleus RTOS的内容。

对象标识符

在Nucleus RTOS中，所有对象都由数据结构（控制块）描述，这些数据结构都有特定的数据类型。指向该控制块的指针用作定时器的标识符。在Nucleus SE中，我认为需要不同的方法以提高存储效率，因此所有内核对象都由RAM和/或ROM中的许多表来描述。这些表的大小由所配置的每个对象类型的数量决定。一个特定对象的标识符只是这些表的索引。所以，我将NUSE_TIMER定义为等同于U8，然后这种类型的变量，而不是指针，就可用作定时器标识符。这是一个小的不兼容性问题，无论代码移植到Nucleus RTOS或从Nucleus RTOS移出，都可以轻松处理。对象标识符通常只是存储和传递，而不是以任何方式操作。

Nucleus RTOS还支持定时器的命名。这些名称仅用于基于目标的调试工具。我在Nucleus SE中省略了它们以节省内存。

定时器大小

在Nucleus RTOS中，定时器使用32位计数器实现。我决定在Nucleus SE中将其减少到16位。这种改变使内存和执行效率显着提高。如果应用要求的时间更长，Nucleus SE可以很容易地进行修改。

到期例程

Nucleus SE实现过期例程的方式与Nucleus RTOS大致相同，除了它们可以完全禁用（这节省了一些内存）并且是静态定义的以外。重置定时器时，无法更改过期例程。

未实现的API调用

Nucleus RTOS有八个服务调用可与定时器配合使用。 其中，有三个未在Nucleus SE中实现。 可以在本文前面“未实现的API调用”中找到这些调用以及省略它们的决定的详细信息。

本文同步刊登于2019年电子工程专辑杂志5月刊