FreeRTOS: Common I/O
AWS IoT Common I/O library
Return to main page ↑
Macros | Typedefs | Functions
Timer HAL APIs

Macros

#define IOT_TIMER_SUCCESS   ( 0 )
 Return values used by timer driver. More...
 
#define IOT_TIMER_INVALID_VALUE   ( 1 )
 
#define IOT_TIMER_FUNCTION_NOT_SUPPORTED   ( 2 )
 
#define IOT_TIMER_NOT_RUNNING   ( 3 )
 
#define IOT_TIMER_SET_FAILED   ( 4 )
 

Typedefs

typedef struct IotTimerDescriptor * IotTimerHandle_t
 IotTimerHandle_t type is the timer handle returned by calling iot_timer_open() this is initialized in open and returned to caller. Caller must pass this pointer to the rest of the APIs.
 
typedef void(* IotTimerCallback_t) (void *pvUserContext)
 timer callback notification type. This callback is used for notifying the caller when the setup timer expires. More...
 

Functions

IotTimerHandle_t iot_timer_open (int32_t lTimerInstance)
 iot_timer_open is used to initialize the timer. This function will start the timer. More...
 
void iot_timer_set_callback (IotTimerHandle_t const pxTimerHandle, IotTimerCallback_t xCallback, void *pvUserContext)
 iot_timer_set_callback is used to set the callback to be called when the timer reaches the count (delay) set by the caller. Callers can set the delay using the iot_timer_delay API. More...
 
int32_t iot_timer_start (IotTimerHandle_t const pxTimerHandle)
 iot_timer_start is used to start the timer counter. This call only makes the timer counter running, and does not setup any match values etc.. More...
 
int32_t iot_timer_stop (IotTimerHandle_t const pxTimerHandle)
 iot_timer_stop is used to stop the timer counter if the timer is running. More...
 
int32_t iot_timer_get_value (IotTimerHandle_t const pxTimerHandle, uint64_t *ullMicroSeconds)
 iot_timer_get_value is used to get the current timer value in micro seconds. More...
 
int32_t iot_timer_delay (IotTimerHandle_t const pxTimerHandle, uint32_t ulDelayMicroSeconds)
 iot_timer_delay is used to set up a delay/wake-up time in microseconds. The caller can use this API to delay current execution until the specified microSeconds. A callback is called once the delay is expired (i,e the amount of microseconds is passed from the time the API is called). If no callback is registered by the caller, then once the delay is expired, caller cannot be notified, but this mechanism can be useful to wake up the target from sleep. More...
 
int32_t iot_timer_cancel (IotTimerHandle_t const pxTimerHandle)
 iot_timer_cancel is used to cancel any existing delay call. If a call to iot_timer_delay() was made earlier, calling iot_timer_cancel will cancel that delay call, so no call-back will be called. More...
 
int32_t iot_timer_close (IotTimerHandle_t const pxTimerHandle)
 iot_timer_close is used to de-initializes the timer, stops the timer if it was started and cancels the delay calls, and resets the timer value. More...
 

Detailed Description

Macro Definition Documentation

◆ IOT_TIMER_SUCCESS

#define IOT_TIMER_SUCCESS   ( 0 )

Return values used by timer driver.

Timer operation completed successfully.

◆ IOT_TIMER_INVALID_VALUE

#define IOT_TIMER_INVALID_VALUE   ( 1 )

At least one parameter is invalid.

◆ IOT_TIMER_FUNCTION_NOT_SUPPORTED

#define IOT_TIMER_FUNCTION_NOT_SUPPORTED   ( 2 )

Timer operation not supported.

◆ IOT_TIMER_NOT_RUNNING

#define IOT_TIMER_NOT_RUNNING   ( 3 )

Timer not running.

◆ IOT_TIMER_SET_FAILED

#define IOT_TIMER_SET_FAILED   ( 4 )

Timer set failed.

Typedef Documentation

◆ IotTimerCallback_t

typedef void( * IotTimerCallback_t) (void *pvUserContext)

timer callback notification type. This callback is used for notifying the caller when the setup timer expires.

Parameters
[in]pvUserContextUser Context passed when setting the callback.

Function Documentation

◆ iot_timer_open()

IotTimerHandle_t iot_timer_open ( int32_t  lTimerInstance)

iot_timer_open is used to initialize the timer. This function will start the timer.

Parameters
[in]lTimerInstanceinstance of the timer to initialize.
Returns
  • Handle to IotTimerHandle_t on SUCCESS
  • NULL if
    • lTimerInstance is invalid
    • lTimerInstance is already open.

◆ iot_timer_set_callback()

void iot_timer_set_callback ( IotTimerHandle_t const  pxTimerHandle,
IotTimerCallback_t  xCallback,
void *  pvUserContext 
)

iot_timer_set_callback is used to set the callback to be called when the timer reaches the count (delay) set by the caller. Callers can set the delay using the iot_timer_delay API.

Note
Newly set callback overrides the one previously set
This callback is per handle. Each instance has its own callback.
Warning
This function silently does nothing if either pxTimerHandle or xCallback handle are NULL.
Parameters
[in]pxTimerHandlehandle to Timer interface returned in iot_timer_open()
[in]xCallbackThe callback function to be called.
[in]pvUserContextThe user context to be passed when callback is called.

◆ iot_timer_start()

int32_t iot_timer_start ( IotTimerHandle_t const  pxTimerHandle)

iot_timer_start is used to start the timer counter. This call only makes the timer counter running, and does not setup any match values etc..

Parameters
[in]pxTimerHandlehandle to Timer interface returned in iot_timer_open()
Returns
  • IOT_TIMER_SUCCESS on success
  • IOT_TIMER_INVALID_VALUE if pxTimerHandle is NULL

◆ iot_timer_stop()

int32_t iot_timer_stop ( IotTimerHandle_t const  pxTimerHandle)

iot_timer_stop is used to stop the timer counter if the timer is running.

Parameters
[in]pxTimerHandlehandle to Timer interface returned in iot_timer_open()
Returns
returns IOT_TIMER_SUCCESS on success or returns one of IOT_TIMER_INVALID_VALUE, IOT_TIMER_FUNCTION_NOT_SUPPORTED on error.
  • IOT_TIMER_SUCCESS on success
  • IOT_TIMER_INVALID_VALUE if pxTimerHandle is NULL.
  • IOT_TIMER_FUNCTION_NOT_SUPPORTED, if the free running timer on SoC cant be stopped.
  • IOT_TIMER_NOT_RUNNING if iot_timer_start has not been called.

◆ iot_timer_get_value()

int32_t iot_timer_get_value ( IotTimerHandle_t const  pxTimerHandle,
uint64_t *  ullMicroSeconds 
)

iot_timer_get_value is used to get the current timer value in micro seconds.

Parameters
[in]pxTimerHandlehandle to Timer interface returned in iot_timer_open()
[out]ullMicroSecondscurrent timer count in microseconds.
Returns
  • IOT_TIMER_SUCCESS on success
  • IOT_TIMER_INVALID_VALUE if pxTimerHandle or ulMicroSeconds pointers are NULL
  • IOT_TIMER_NOT_RUNNING if timer hasn't been started.

◆ iot_timer_delay()

int32_t iot_timer_delay ( IotTimerHandle_t const  pxTimerHandle,
uint32_t  ulDelayMicroSeconds 
)

iot_timer_delay is used to set up a delay/wake-up time in microseconds. The caller can use this API to delay current execution until the specified microSeconds. A callback is called once the delay is expired (i,e the amount of microseconds is passed from the time the API is called). If no callback is registered by the caller, then once the delay is expired, caller cannot be notified, but this mechanism can be useful to wake up the target from sleep.

Parameters
[in]pxTimerHandlehandle to Timer interface returned in iot_timer_open()
[in]ulDelayMicroSecondsdelay time in micro seconds

Example timer delay execution The callback function is called to signal when the timer reaches the count (delay) set by the caller.

IotTimerHandle_t xTimerHandle;
xTimerHandle = iot_timer_open( ltestIotTimerInstance);
// assert( xTimerHandle == NULL );
// Set the callback to call prvTimerCallbackFunction() when delay reached.
iot_timer_set_callback(xTimerHandle, prvTimerCallbackFunction, NULL);
// Set the timer delay to be TIMER_DEFAULT_DELAY_US
lRetVal = iot_timer_delay(xTimerHandle, TIMER_DEFAULT_DELAY_US );
// assert( lRetVal != IOT_TIMER_SUCCESS );
//Start the timer
lRetVal = iot_timer_start(xTimerHandle);
// assert ( lRetVal != IOT_TIMER_SUCCESS);
// Wait for the Delay callback to be called. Inside of prvTimerCallbackFunction()
// the function will use xSemaphoreGive() to signal completion.
lRetVal = xSemaphoreTake(IotTimerSemaphore, portMAX_DELAY);
// assert( lRetVal != TRUE );
lRetVal = iot_timer_close(xTimerHandle);
//assert ( lRetVal != IOT_TIMER_SUCCESS);
Returns
  • IOT_TIMER_SUCCESS on success
  • IOT_TIMER_INVALID_VALUE if pxTimerHandle or ulMicroSeconds pointers are NULL
  • IOT_TIMER_NOT_RUNNING if timer hasn't been started.
  • IOT_TIMER_SET_FAILED on error.

◆ iot_timer_cancel()

int32_t iot_timer_cancel ( IotTimerHandle_t const  pxTimerHandle)

iot_timer_cancel is used to cancel any existing delay call. If a call to iot_timer_delay() was made earlier, calling iot_timer_cancel will cancel that delay call, so no call-back will be called.

Parameters
[in]pxTimerHandlehandle to Timer interface returned in iot_timer_open()
Returns
  • IOT_TIMER_SUCCESS on success
  • IOT_TIMER_INVALID_VALUE if pxTimerHandle is NULL
  • IOT_TIMER_FUNCTION_NOT_SUPPORTED if timer can't be cancelled.
  • IOT_TIMER_NOTHING_TO_CANCEL if there is no timer running to cancel.

◆ iot_timer_close()

int32_t iot_timer_close ( IotTimerHandle_t const  pxTimerHandle)

iot_timer_close is used to de-initializes the timer, stops the timer if it was started and cancels the delay calls, and resets the timer value.

Parameters
[in]pxTimerHandlehandle to Timer interface returned in iot_timer_open()
Returns
  • IOT_TIMER_SUCCESS on success
  • IOT_TIMER_INVALID_VALUE if
    • pxTimerHandle is NULL.
    • pxTimerHandle not open (previously closed).