Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/tickcounter_freertos_requirement.md

raw
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. **]**