Timer Management

group OS_87x3e_Timer

Create and control software timer and timer callback functions.

The Timer Management function group allows to create, delete, and control software timers in the system. The software timers can be configured as one-short or periodic timers. When a timer expires, a callback function associated with the timer is executed.

Timers can be in the following two states:

Dormant The timer first enters Dormant or Inactive state when created. If a one-short timer expires but not restarts yet, or is stopped the timer will be tranformed from Active state into Dormant state.
Active The timer enters Active state If the timer starts or restarts. When expired, the callback function associcated with the timer will be executed.

../../_images/OS-timer-state-transition.jpg

Variables

bool (*os_timer_id_get)(void **pp_handle, uint32_t *p_timer_id)

Get the ID assigned to the timer when created.

os_timer.h

Example usage

// Timer callback function.
void timer_callback(void *p_handle)
{
    uint32_t timer_id;

    // Which timer expired?
    os_timer_id_get(&p_handle, &timer_id);

    if (timer_id == TIMER_ID)
    {
         // Delete the specified timer.
         os_timer_delete(&p_handle);
    }
}

#define TIMER_ID 1

// Timer to be created.
int test(void)
{
    void *p_handle = NULL;

    if (os_timer_create(&p_handle, "timer", TIMER_ID,
                       INTERVAL_MS, false, timer_callback) == true)
    {
        // Timer created successfully, start the timer.
        os_timer_start(&p_handle);
    }
    else
    {
        // Timer failed to create.
        return -1;
    }

    return 0;
}

Param pp_handle:: Pointer to the created timer handle.
Param p_timer_id:: Used to pass back the ID assigned to the timer.
Retval true:: Timer ID was got successfully.
Retval false:: Timer ID was failed to get.
Return:: The status of the timer id getting.

bool (*os_timer_create)(void **pp_handle, const char *p_timer_name, uint32_t timer_id, uint32_t interval_ms, bool reload, void (*p_timer_callback)(void*))

Create a new software timer instance. This allocates the storage required by the new timer, initializes the new timers internal state, and returns a handle by which the new timer can be referenced.

os_timer.h

Example usage

// Timer callback function.
void timer_callback(void *p_handle)
{
    uint32_t timer_id;

    // Which timer expired?
    os_timer_id_get(&p_handle, &timer_id);

    if (timer_id == TIMER_ID)
    {
         // Delete the specified timer.
         os_timer_delete(&p_handle);
    }
}

#define TIMER_ID 1

// Timer to be created.
int test(void)
{
    void *p_handle = NULL;

    if (os_timer_create(&p_handle, "timer", TIMER_ID,
                       INTERVAL_MS, false, timer_callback) == true)
    {
        // Timer created successfully, start the timer.
        os_timer_start(&p_handle);
    }
    else
    {
        // Timer failed to create.
        return -1;
    }

    return 0;
}

Param pp_handle:

Used to pass back a handle by which the created timer can be referenced.

Param p_timer_name:

A descriptive name for the timer.

Param timer_id:

An identifier that is assigned to the timer being created. Typically this would be used in the timer callback function to identify which timer expired when the same callback function is assigned to more than one timer.

Param interval_ms:

The timer period in milliseconds.

Param reload:

Used to set the timer as a periodic or one-shot timer.

true Create a periodic timer.
false Create a one-shot timer.

Param p_timer_callback:

The function to call when the timer expires. Callback functions must have the prototype defined as ‘void callback(void *)’.

Retval true:

Timer was created successfully.

Retval false:

Timer was failed to create.

Return:

The status of the timer creation.

bool (*os_timer_start)(void **pp_handle)

Start a timer that was previously created using the os_timer_create() API function. If the timer had already been started and was in the active state, then os_timer_create() has equivalent functionality to the os_timer_create() API function.

os_timer.h

Example usage

// Timer callback function.
void timer_callback(void *p_handle)
{
    uint32_t timer_id;

    // Which timer expired?
    os_timer_id_get(&p_handle, &timer_id);

    if (timer_id == TIMER_ID)
    {
         // Delete the specified timer.
         os_timer_delete(&p_handle);
    }
}

#define TIMER_ID 1

// Timer to be created.
int test(void)
{
    void *p_handle = NULL;

    if (os_timer_create(&p_handle, "timer", TIMER_ID,
                       INTERVAL_MS, false, timer_callback) == true)
    {
        // Timer created successfully, start the timer.
        os_timer_start(&p_handle);
    }
    else
    {
        // Timer failed to create.
        return -1;
    }

    return 0;
}

Param pp_handle:: Pointer to the created timer handle.
Retval true:: Timer was started successfully.
Retval false:: Timer was failed to start.
Return:: The status of the timer starting.

bool (*os_timer_restart)(void **pp_handle, uint32_t interval_ms)

Restart a timer that was previously created using the os_timer_create() API function. If the timer had already been started and was already in the active state, then os_timer_start() will cause the timer to re-evaluate its expiry time so that it is relative to when os_timer_start() was called. If the timer was in the dormant state then os_timer_start() has equivalent functionality to the os_timer_start() API function.

os_timer.h

Example usage

// Timer callback function.
void timer_callback(void *p_handle)
{
    uint32_t timer_id;

    // Which timer expired?
    os_timer_id_get(&p_handle, &timer_id);

    if (timer_id == TIMER_ID)
    {
         // Restart the specified timer.
         os_timer_restart(&p_handle);
    }
}

#define TIMER_ID 1

// Timer to be created.
int test(void)
{
    void *p_handle = NULL;

    if (os_timer_create(&p_handle, "timer", TIMER_ID,
                       INTERVAL_MS, false, timer_callback) == true)
    {
        // Timer created successfully, start the timer.
        os_timer_start(&p_handle);
    }
    else
    {
        // Timer failed to create.
        return -1;
    }

    return 0;
}

Param pp_handle:: Pointer to the created timer handle.
Param interval_ms:: The timer period in milliseconds.
Retval true:: Timer was restarted successfully.
Retval false:: Timer was failed to restart.
Return:: The status of the timer restarting.

bool (*os_timer_stop)(void **pp_handle)

Stop a timer that was previously started using either of the os_timer_start(), os_timer_restart() API functions. Stopping a timer ensures the timer is not in the active state.

os_timer.h

Example usage

// Timer callback function.
void timer_callback(void *p_handle)
{
    uint32_t timer_id;

    // Which timer expired?
    os_timer_id_get(&p_handle, &timer_id);

    if (timer_id == TIMER_ID)
    {
         // Delete the specified timer.
         os_timer_delete(&p_handle);
    }
}

#define TIMER_ID 1

// Timer to be created and stopped.
int test(void)
{
    void *p_handle = NULL;

    if (os_timer_create(&p_handle, "timer", TIMER_ID,
                       INTERVAL_MS, false, timer_callback) == true)
    {
        // Timer created successfully, start the timer.
        os_timer_start(&p_handle);
    }
    else
    {
        // Timer failed to create.
        return -1;
    }

    // Stop the timer before expiration.
    os_timer_stop(&p_handle);

    return 0;
}

Param pp_handle:: Pointer to the handle of timer being stopped.
Retval true:: Timer was stopped successfully.
Retval false:: Timer was failed to stop.
Return:: The status of the timer stopping.

bool (*os_timer_delete)(void **pp_handle)

Delete a timer that was previously created using the os_timer_create() API function.

os_timer.h

Example usage

// Timer callback function.
void timer_callback(void *p_handle)
{
    uint32_t timer_id;

    // Which timer expired?
    os_timer_id_get(&p_handle, &timer_id);

    if (timer_id == TIMER_ID)
    {
         // Delete the specified timer.
         os_timer_delete(&p_handle);
    }
}

#define TIMER_ID 1

// Timer to be created and deleted.
int test(void)
{
    void *p_handle = NULL;

    if (os_timer_create(&p_handle, "timer", TIMER_ID,
                       INTERVAL_MS, false, timer_callback) == true)
    {
        // Timer created successfully, start the timer.
        os_timer_start(&p_handle);
    }
    else
    {
        // Timer failed to create.
        return -1;
    }

    return 0;
}

Param pp_handle:: Pointer to the handle of timer being deleted.
Retval true:: Timer was deleted successfully.
Retval false:: Timer was failed to delete.
Return:: The status of the timer deletion.

bool (*os_timer_pend_function_call)(void (*p_pend_function)(void*, uint32_t), void *pvParameter1, uint32_t ulParameter2)

Dump all current used timers in system.

os_timer.h

Example usage

// Timer callback function.
void timer_callback(void *p_handle)
{
    uint32_t timer_id;

    // Which timer expired?
    os_timer_id_get(&p_handle, &timer_id);

    if (timer_id == TIMER_ID)
    {
         // Delete the specified timer.
         os_timer_delete(&p_handle);
    }
}

#define TIMER_ID 1

// Timer to be created and dumped.
int test(void)
{
    void *p_handle = NULL;

    if (os_timer_create(&p_handle, "timer", TIMER_ID,
                       INTERVAL_MS, false, timer_callback) == true)
    {
        // Timer created successfully, start the timer.
        os_timer_start(&p_handle);
    }
    else
    {
        // Timer failed to create.
        return -1;
    }

    // Dump all used timers.
    os_timer_dump();

    return 0;
}

Param None.:
Retval true:: Timer was dumped successfully.
Retval false:: Timer was failed to dump.
Return:: The status of the timer dump.