1# Time Management 2 3 4## Basic Concepts 5 6Time management provides all time-related services for applications based on the system clock. 7 8The system clock is generated by the interrupts triggered by the output pulse of a timer or counter. The system clock is generally defined as an integer or a long integer. The period of an output pulse is a "clock tick". The system clock is also called time scale or tick. 9 10People use second or millisecond as the time unit, while the operating system uses tick. When operations such as suspending a task or delaying a task are performed, the time management module converts time between ticks and seconds or milliseconds. 11 12The time management module of the OpenHarmony LiteOS-M kernel provides time conversion and statistics functions. 13 14 15## Time Unit 16 17- Cycle 18 Cycle is the minimum time unit in the system. The cycle duration is determined by the system clock frequency, that is, the number of cycles per second. 19 20- Tick 21 Tick is the basic time unit of the operating system and is determined by the number of ticks per second configured by the user. 22 23 24## Available APIs 25 26The following table describes APIs available for OpenHarmony LiteOS-M time management. For more details about the APIs, see the API reference. 27 28**Table 1** APIs of the time management module 29 30| API| Description| 31| -------- | -------- | 32| LOS_MS2Tick | Converts milliseconds into ticks.| 33| LOS_Tick2MS | Converts ticks into milliseconds.| 34| OsCpuTick2MS | Converts cycles into milliseconds. Two UINT32 values indicate the high-order and low-order 32 bits of the result value, respectively.| 35| OsCpuTick2US | Converts cycles into microseconds. Two UINT32 values indicate the high-order and low-order 32 bits of the result value, respectively.| 36 37**Table 2** APIs for time statistics 38 39| API| Description| 40| -------- | -------- | 41| LOS_SysClockGet | Obtains the system clock.| 42| LOS_TickCountGet | Obtains the number of ticks since the system starts.| 43| LOS_CyclePerTickGet | Obtains the number of cycles for each tick. | 44| LOS_CurrNanosec | Obtains the current time, in nanoseconds. | 45 46**Table 3** API for time registration 47 48| API | Description | 49| --------------------- | ---------------------------------------------- | 50| LOS_TickTimerRegister | Re-registers the timer of the system clock and the corresponding interrupt handler.| 51 52**Table 4** APIs for delay 53 54| API | Description | 55| ---------- | ------------------------ | 56| LOS_MDelay | Delays a task, in ms.| 57| LOS_UDelay | Delays a task, in μs.| 58 59## How to Develop 60 61The typical development process of time management is as follows: 62 631. Complete board configuration and adaptation as required, and configure the system clock frequency (**OS_SYS_CLOCK** in Hz and **LOSCFG_BASE_CORE_TICK_PER_SECOND**). The default value of **OS_SYS_CLOCK** varies with the hardware platform. 64 652. Call the clock conversion and statistics APIs. 66 67>  **NOTE** 68> - The time management module depends on **OS_SYS_CLOCK** and **LOSCFG_BASE_CORE_TICK_PER_SECOND**. 69> 70> - The number of system ticks is not counted when the interrupt feature is disabled. Therefore, the number of ticks cannot be used as the accurate time. 71> 72> - The preceding configuration is in the **target_config.h** file of the development board project. The default values of some configuration items are defined in the **los_config.h** file of the kernel. 73 74 75## Development Example 76 77 78### Example Description 79 80The following example describes basic time management methods, including: 81 821. Time conversion: convert milliseconds to ticks or convert ticks to milliseconds. 83 842. Time statistics: obtain the number of cycles per tick, number of ticks since system startup, and number of delayed ticks. 85 86 87### Sample Code 88 89**Prerequisites** 90 91- The default value of **LOSCFG_BASE_CORE_TICK_PER_SECOND** is **100**. 92 93- The system clock frequency **OS_SYS_CLOCK** is configured. 94 95Time conversion: 96 97The sample code is compiled and verified in **./kernel/liteos_m/testsuites/src/osTest.c**. Call **ExampleTransformTime** and **ExampleGetTime** in **TestTaskEntry**. 98 99 100``` 101VOID ExampleTransformTime(VOID) 102{ 103 UINT32 ms; 104 UINT32 tick; 105 106 /* Convert 10000 ms to ticks. */ 107 tick = LOS_MS2Tick(10000); 108 printf("tick = %d \n", tick); 109 110 /* Convert 100 ticks to ms. */ 111 ms = LOS_Tick2MS(100); 112 printf("ms = %d \n", ms); 113} 114``` 115 116Time statistics and delay: 117 118 119``` 120VOID ExampleGetTime(VOID) 121{ 122 UINT32 cyclePerTick; 123 UINT64 tickCountBefore; 124 UINT64 tickCountAfter; 125 126 cyclePerTick = LOS_CyclePerTickGet(); 127 if (0 != cyclePerTick) { 128 printf("LOS_CyclePerTickGet = %d \n", cyclePerTick); 129 } 130 131 tickCountBefore = LOS_TickCountGet(); 132 LOS_TaskDelay(200); 133 tickCountAfter = LOS_TickCountGet(); 134 printf("LOS_TickCountGet after delay rising = %d \n", (UINT32)(tickCountAfter - tickCountBefore)); 135} 136``` 137 138 139### Verification 140 141The development is successful if the return result is as follows: 142 143Time conversion: 144 145 146``` 147tick = 1000 148ms = 1000 149``` 150 151Time statistics and delay: 152 153 154``` 155LOS_CyclePerTickGet = 250000 (The data may vary depending on the actual running environment.) 156LOS_TickCountGet after delay rising = 200 157``` 158
