1 /** 2 * Copyright (c) 2015, Realtek Semiconductor Corporation. All rights reserved. 3 */ 4 5 #ifndef _OS_SCHED_H_ 6 #define _OS_SCHED_H_ 7 8 #include <stdint.h> 9 #include <stdbool.h> 10 11 #ifdef __cplusplus 12 extern "C" { 13 #endif 14 15 /** 16 * \addtogroup OS OSIF 17 * \defgroup Schedule Kernel Scheduler 18 * 19 * \brief Manage the kernel scheduler functions. 20 * 21 * \ingroup OS 22 */ 23 24 25 /** 26 * os_sched.h 27 * 28 * \brief Delay current task for a given period in milliseconds. 29 * 30 * \param[in] ms The amout of timer in milliseconds that the current task 31 * should block. 32 * 33 * \return None. 34 * 35 * <b>Example usage</b> 36 * \code{.c} 37 * // Task routine implementation. 38 * void task_routine(void *p_param) 39 * { 40 * for (;;) 41 * { 42 * // Task code goes here. 43 * os_delay(100); 44 * 45 * // Do something here per 100ms. 46 * } 47 * } 48 * \endcode 49 * 50 * \ingroup Schedule 51 */ 52 void os_delay(uint32_t ms); 53 54 /** 55 * os_sched.h 56 * 57 * \brief Get the time in milliseconds since os_sched_start() API function was called. 58 * 59 * \param None 60 * 61 * \return The time in milliseconds. Note the time represented by a 32-bit integer 62 * may be overflowed. 63 * 64 * <b>Example usage</b> 65 * \code{.c} 66 * // Task routine implementation. 67 * void task_routine(void *p_param) 68 * { 69 * uint32_t last_time; 70 * 71 * // Get the last timestamp. 72 * last_time = os_sys_time_get(); 73 * 74 * for (;;) 75 * { 76 * // Wait for the next cycle. 77 * os_delay(100); 78 * 79 * // Do something here per 100ms. 80 * } 81 * } 82 * \endcode 83 * 84 * \ingroup Schedule 85 */ 86 uint32_t os_sys_time_get(void); 87 88 /** 89 * os_sched.h 90 * 91 * \brief Start the RTOS kernel scheduler. 92 * 93 * \param None 94 * 95 * \return The status of starting kernel scheduler. 96 * \retval true Scheduler was started successfully. 97 * \retval false Scheduler was failed to start. 98 * 99 * <b>Example usage</b> 100 * \code{.c} 101 * int test(void) 102 * { 103 * // Create at least one task before starting kernel scheduler. 104 * if (os_task_create(&p_handle, "task", task_routine, 105 * NULL, STACK_SIZE, TASK_PRIORITY) == true) 106 * { 107 * // Task created successfully. 108 * } 109 * else 110 * { 111 * // Task failed to create. 112 * return -1; 113 * } 114 * 115 * // Start the kernel scheduler. 116 * os_sched_start(); 117 * 118 * // Will not get here unless a task calls os_sched_stop(). 119 * } 120 * \endcode 121 * 122 * \ingroup Schedule 123 */ 124 bool os_sched_start(void); 125 126 /** 127 * os_sched.h 128 * 129 * \brief Stop the RTOS kernel scheduler. All created tasks will be automatically 130 * deleted and multitasking (either preemptive or cooperative) stops. 131 * 132 * \param None 133 * 134 * \return The status of stopping kernel scheduler. 135 * \retval true Scheduler was stopped successfully. 136 * \retval false Scheduler was failed to stop. 137 * 138 * <b>Example usage</b> 139 * \code{.c} 140 * // Task routine implementation. 141 * void task_routine(void *p_param) 142 * { 143 * for (;;) 144 * { 145 * // Task code goes here. 146 * 147 * // At some point we want to end the real time kernel processing. 148 * os_sched_stop(); 149 * } 150 * } 151 * 152 * int test(void) 153 * { 154 * // Create at least one task before starting kernel scheduler. 155 * if (os_task_create(&p_handle, "task", task_routine, 156 * NULL, STACK_SIZE, TASK_PRIORITY) == true) 157 * { 158 * // Task created successfully. 159 * } 160 * else 161 * { 162 * // Task failed to create. 163 * return -1; 164 * } 165 * 166 * // Start the kernel scheduler. 167 * os_sched_start(); 168 * 169 * // Will not get here unless a task calls os_sched_stop(). 170 * } 171 * \endcode 172 * 173 * \ingroup Schedule 174 */ 175 bool os_sched_stop(void); 176 177 /** 178 * os_sched.h 179 * 180 * \brief Suspends the kernel scheduler without disabling interrupts. Context 181 * switches will not occur while the scheduler is suspended. After calling 182 * os_sched_suspend(), the calling task will continue to execute without 183 * risk of being swapped out until a call to os_sched_resume() has been made. 184 * 185 * \param None 186 * 187 * \return The status of suspending kernel scheduler. 188 * \retval true Scheduler was suspended successfully. 189 * \retval false Scheduler was failed to suspend. 190 * 191 * <b>Example usage</b> 192 * \code{.c} 193 * // Task routine implementation. 194 * void task_routine(void *p_param) 195 * { 196 * for (;;) 197 * { 198 * // Task code goes here. 199 * 200 * // At some point the task wants to perform a long operation, and do not 201 * // want to get swapped out. 202 * os_sched_suspend(); 203 * 204 * // The long operation. 205 * 206 * // The operation is completed, and resume the scheduler. 207 * os_sched_resume(); 208 * } 209 * } 210 * \endcode 211 * 212 * \ingroup Schedule 213 */ 214 bool os_sched_suspend(void); 215 216 /** 217 * os_sched.h 218 * 219 * \brief Resume the kernel scheduler after it was suspended by a call 220 * to os_sched_suspend(). 221 * 222 * \param None 223 * 224 * \return The status of resuming kernel scheduler. 225 * \retval true Scheduler was resumed successfully. 226 * \retval false Scheduler was failed to resume. 227 * 228 * <b>Example usage</b> 229 * \code{.c} 230 * // Task routine implementation. 231 * void task_routine(void *p_param) 232 * { 233 * for (;;) 234 * { 235 * // Task code goes here. 236 * 237 * // At some point the task wants to perform a long operation, and do not 238 * // want to get swapped out. 239 * os_sched_suspend(); 240 * 241 * // The long operation. 242 * 243 * // The operation is completed, and resume the scheduler. 244 * os_sched_resume(); 245 * } 246 * } 247 * \endcode 248 * 249 * \ingroup Schedule 250 */ 251 bool os_sched_resume(void); 252 253 #ifdef __cplusplus 254 } 255 #endif 256 257 #endif /* _OS_SCHED_H_ */ 258