| 1 |
tickcounter_freertos |
| 2 |
========= |
| 3 |
|
| 4 |
## Overview |
| 5 |
|
| 6 |
tickcounter_freertos implements the Azure IoT C Shared Utility tickcounter adapter for devices running FreeRTOS. |
| 7 |
|
| 8 |
FreeRTOS tick counting is provided by the FreeRTOS call `xTaskGetTickCount`, which requires the FreeRTOS call `vTaskStartScheduler` to be called beforehand. The call to `vTaskStartScheduler` happens during initialization for any realistic FreeRTOS application, so further system initialization in the tickcounter_freertos adapter is not required. |
| 9 |
|
| 10 |
FreeRTOS can be configured to use 16-bit ticks by setting the configUSE_16_BIT_TICKS value to '0'. This could lead to incorrect behavior due to overflow in some situations, so use caution when employing 16-bit ticks. |
| 11 |
|
| 12 |
|
| 13 |
## References |
| 14 |
[Azure IoT C Shared Utility tickcounter adapter](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/porting_guide.md#tickcounter-adapter) |
| 15 |
[tickcounter.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/tickcounter.h) |
| 16 |
|
| 17 |
|
| 18 |
|
| 19 |
## Exposed API |
| 20 |
|
| 21 |
**SRS_TICKCOUNTER_FREERTOS_30_001: [** The tickcounter_freertos adapter shall use the following data types as defined in tickcounter.h. |
| 22 |
```c |
| 23 |
// uint_fast32_t is a 32 bit uint |
| 24 |
typedef uint_fast32_t tickcounter_ms_t; |
| 25 |
// TICK_COUNTER_INSTANCE_TAG* is an opaque handle type |
| 26 |
typedef struct TICK_COUNTER_INSTANCE_TAG* TICK_COUNTER_HANDLE; |
| 27 |
``` |
| 28 |
**]** |
| 29 |
|
| 30 |
**SRS_TICKCOUNTER_FREERTOS_30_002: [** The tickcounter_freertos adapter shall implement the API calls defined in tickcounter.h: |
| 31 |
```c |
| 32 |
TICK_COUNTER_HANDLE tickcounter_create(void); |
| 33 |
void tickcounter_destroy(TICK_COUNTER_HANDLE tick_counter); |
| 34 |
int tickcounter_get_current_ms(TICK_COUNTER_HANDLE tick_counter, tickcounter_ms_t* current_ms); |
| 35 |
``` |
| 36 |
**]** |
| 37 |
|
| 38 |
|
| 39 |
### tickcounter_create |
| 40 |
The `tickcounter_create` call allocates and initializes an internally defined TICK_COUNTER_INSTANCE structure and returns its pointer as type TICK_COUNTER_HANDLE. |
| 41 |
```c |
| 42 |
TICK_COUNTER_HANDLE tickcounter_create(void); |
| 43 |
``` |
| 44 |
|
| 45 |
**SRS_TICKCOUNTER_FREERTOS_30_003: [** `tickcounter_create` shall allocate and initialize an internally-defined TICK_COUNTER_INSTANCE structure and return its pointer on success. **]** |
| 46 |
|
| 47 |
**SRS_TICKCOUNTER_FREERTOS_30_004: [** If allocation of the internally-defined TICK_COUNTER_INSTANCE structure fails, `tickcounter_create` shall return NULL. (Initialization failure is not possible for FreeRTOS.) **]** |
| 48 |
|
| 49 |
|
| 50 |
### tickcounter_destroy |
| 51 |
The `tickcounter_destroy` call releases all resources acquired by the `tickcounter_create` call. |
| 52 |
```c |
| 53 |
void tickcounter_destroy(TICK_COUNTER_HANDLE tick_counter); |
| 54 |
``` |
| 55 |
|
| 56 |
**SRS_TICKCOUNTER_FREERTOS_30_005: [** `tickcounter_destroy` shall delete the internally-defined TICK_COUNTER_INSTANCE structure specified by the `tick_counter` parameter. (This call has no failure case.) **]** |
| 57 |
|
| 58 |
**SRS_TICKCOUNTER_FREERTOS_30_006: [** If the `tick_counter` parameter is NULL, `tickcounter_destroy` shall do nothing. **]** |
| 59 |
|
| 60 |
|
| 61 |
### tickcounter_get_current_ms |
| 62 |
The `tickcounter_get_current_ms` call returns the number of milleconds elapsed since the `tickcounter_create` call. |
| 63 |
```c |
| 64 |
int tickcounter_get_current_ms(TICK_COUNTER_HANDLE tick_counter, tickcounter_ms_t* current_ms); |
| 65 |
``` |
| 66 |
|
| 67 |
**SRS_TICKCOUNTER_FREERTOS_30_007: [** If the `tick_counter` parameter is NULL, `tickcounter_get_current_ms` shall return a non-zero value to indicate error. **]** |
| 68 |
|
| 69 |
**SRS_TICKCOUNTER_FREERTOS_30_008: [** If the `current_ms` parameter is NULL, `tickcounter_get_current_ms` shall return a non-zero value to indicate error. **]** |
| 70 |
|
| 71 |
**SRS_TICKCOUNTER_FREERTOS_30_009: [** `tickcounter_get_current_ms` shall set `*current_ms` to the number of milliseconds elapsed since the `tickcounter_create` call for the specified `tick_counter` and return 0 to indicate success (In FreeRTOS this call has no failure case.) **]** |
| 72 |
|
| 73 |
**SRS_TICKCOUNTER_FREERTOS_30_010: [** If the FreeRTOS call `xTaskGetTickCount` experiences a single overflow between the calls to `tickcounter_create` and `tickcounter_get_current_ms`, the `tickcounter_get_current_ms` call shall still return the correct interval. **]** |