[4b487363] | 1 | /** |
---|
| 2 | * @file rtems/rtems/ratemon.h |
---|
[067a96a] | 3 | * |
---|
[61b8e9f] | 4 | * @defgroup ClassicRateMon Rate Monotonic Scheduler |
---|
[f1eb368d] | 5 | * |
---|
[61b8e9f] | 6 | * @ingroup ClassicRTEMS |
---|
| 7 | * @brief Classic API Rate Monotonic Manager. |
---|
[ac7d5ef0] | 8 | * |
---|
[61b8e9f] | 9 | * This include file contains all the constants, structures, and |
---|
| 10 | * prototypes associated with the Rate Monotonic Manager. This manager |
---|
| 11 | * provides facilities to implement threads which execute in a periodic |
---|
| 12 | * fashion. |
---|
[ac7d5ef0] | 13 | * |
---|
[61b8e9f] | 14 | * Directives provided are: |
---|
| 15 | * |
---|
| 16 | * - create a rate monotonic timer |
---|
| 17 | * - cancel a period |
---|
| 18 | * - delete a rate monotonic timer |
---|
| 19 | * - conclude current and start the next period |
---|
| 20 | * - obtain status information on a period |
---|
[3a46b72] | 21 | * - obtain the number of postponed jobs |
---|
[067a96a] | 22 | */ |
---|
| 23 | |
---|
[815b653] | 24 | /* COPYRIGHT (c) 1989-2009, 2016. |
---|
[61b8e9f] | 25 | * On-Line Applications Research Corporation (OAR). |
---|
[d7feb86] | 26 | * COPYRIGHT (c) 2016-2017 Kuan-Hsun Chen. |
---|
[ac7d5ef0] | 27 | * |
---|
[61b8e9f] | 28 | * The license and distribution terms for this file may be |
---|
| 29 | * found in the file LICENSE in this distribution or at |
---|
[c499856] | 30 | * http://www.rtems.org/license/LICENSE. |
---|
[ac7d5ef0] | 31 | */ |
---|
| 32 | |
---|
[092f142a] | 33 | #ifndef _RTEMS_RTEMS_RATEMON_H |
---|
| 34 | #define _RTEMS_RTEMS_RATEMON_H |
---|
[ac7d5ef0] | 35 | |
---|
[ecdcf01] | 36 | #include <rtems/rtems/types.h> |
---|
| 37 | #include <rtems/rtems/status.h> |
---|
| 38 | #include <rtems/score/watchdog.h> |
---|
[a33bfb6] | 39 | |
---|
| 40 | struct rtems_printer; |
---|
[90a5d194] | 41 | |
---|
[ecdcf01] | 42 | #ifdef __cplusplus |
---|
| 43 | extern "C" { |
---|
| 44 | #endif |
---|
| 45 | |
---|
[067a96a] | 46 | /** |
---|
[c85ab23] | 47 | * @defgroup ClassicRateMon Rate Monotonic Scheduler |
---|
| 48 | * |
---|
| 49 | * @ingroup ClassicRTEMS |
---|
[067a96a] | 50 | * |
---|
[815b653] | 51 | * This encapsulates functionality related to the Classic API Rate |
---|
| 52 | * Monotonic Manager. |
---|
[eb37f9d] | 53 | * |
---|
| 54 | * Statistics are kept for each period and can be obtained or printed via |
---|
| 55 | * API calls. The statistics kept include minimum, maximum and average times |
---|
[815b653] | 56 | * for both cpu usage and wall time. The statistics indicate the execution |
---|
| 57 | * and wall time used by the owning thread between successive calls to |
---|
| 58 | * rtems_rate_monotonic_period. |
---|
[067a96a] | 59 | */ |
---|
| 60 | /**@{*/ |
---|
| 61 | |
---|
[1e039fb3] | 62 | typedef struct timespec rtems_rate_monotonic_period_time_t RTEMS_DEPRECATED; |
---|
[c3330a8] | 63 | |
---|
[067a96a] | 64 | /** |
---|
[ac7d5ef0] | 65 | * The following enumerated type defines the states in which a |
---|
| 66 | * period may be. |
---|
| 67 | */ |
---|
| 68 | typedef enum { |
---|
[8c8fd64] | 69 | /** |
---|
[33c3b54d] | 70 | * This value indicates the period is off the watchdog chain, |
---|
[8c8fd64] | 71 | * and has never been initialized. |
---|
| 72 | */ |
---|
| 73 | RATE_MONOTONIC_INACTIVE, |
---|
| 74 | |
---|
| 75 | /** |
---|
[33c3b54d] | 76 | * This value indicates the period is on the watchdog chain, and |
---|
[8c8fd64] | 77 | * running. The owner should be executed or blocked waiting on |
---|
| 78 | * another object. |
---|
| 79 | */ |
---|
| 80 | RATE_MONOTONIC_ACTIVE, |
---|
| 81 | |
---|
| 82 | /** |
---|
[33c3b54d] | 83 | * This value indicates the period is off the watchdog chain, and |
---|
[8c8fd64] | 84 | * has expired. The owner is still executing and has taken too much |
---|
| 85 | * all time to complete this iteration of the period. |
---|
| 86 | */ |
---|
[4daebbd] | 87 | RATE_MONOTONIC_EXPIRED |
---|
[113ef9fc] | 88 | } rtems_rate_monotonic_period_states; |
---|
[ac7d5ef0] | 89 | |
---|
[067a96a] | 90 | /** |
---|
[ac7d5ef0] | 91 | * The following constant is the interval passed to the rate_monontonic_period |
---|
| 92 | * directive to obtain status information. |
---|
| 93 | */ |
---|
[3a4ae6c] | 94 | #define RTEMS_PERIOD_STATUS WATCHDOG_NO_TIMEOUT |
---|
[ac7d5ef0] | 95 | |
---|
[067a96a] | 96 | /** |
---|
[9dc2c8d] | 97 | * The following defines the PUBLIC data structure that has the |
---|
| 98 | * statistics kept on each period instance. |
---|
| 99 | * |
---|
| 100 | * @note The public structure uses struct timespec while the |
---|
[33c3b54d] | 101 | * internal one uses Timestamp_Control. |
---|
[e1bce86] | 102 | */ |
---|
| 103 | typedef struct { |
---|
[8c8fd64] | 104 | /** This field contains the number of periods executed. */ |
---|
[e1bce86] | 105 | uint32_t count; |
---|
[8c8fd64] | 106 | /** This field contains the number of periods missed. */ |
---|
[e1bce86] | 107 | uint32_t missed_count; |
---|
[ebfd9ea] | 108 | |
---|
[8c8fd64] | 109 | /** This field contains the least amount of CPU time used in a period. */ |
---|
[aacc7a0] | 110 | struct timespec min_cpu_time; |
---|
[8c8fd64] | 111 | /** This field contains the highest amount of CPU time used in a period. */ |
---|
[aacc7a0] | 112 | struct timespec max_cpu_time; |
---|
[8c8fd64] | 113 | /** This field contains the total amount of wall time used in a period. */ |
---|
[aacc7a0] | 114 | struct timespec total_cpu_time; |
---|
[5fa5185] | 115 | |
---|
[8c8fd64] | 116 | /** This field contains the least amount of wall time used in a period. */ |
---|
[1e039fb3] | 117 | struct timespec min_wall_time; |
---|
[8c8fd64] | 118 | /** This field contains the highest amount of wall time used in a period. */ |
---|
[1e039fb3] | 119 | struct timespec max_wall_time; |
---|
[8c8fd64] | 120 | /** This field contains the total amount of CPU time used in a period. */ |
---|
[1e039fb3] | 121 | struct timespec total_wall_time; |
---|
[e1bce86] | 122 | } rtems_rate_monotonic_period_statistics; |
---|
| 123 | |
---|
[067a96a] | 124 | /** |
---|
[113ef9fc] | 125 | * The following defines the period status structure. |
---|
[50f32b11] | 126 | */ |
---|
[113ef9fc] | 127 | typedef struct { |
---|
[8c8fd64] | 128 | /** This is the Id of the thread using this period. */ |
---|
[d3b72ca3] | 129 | rtems_id owner; |
---|
[8c8fd64] | 130 | |
---|
| 131 | /** This is the current state of this period. */ |
---|
[5fa5185] | 132 | rtems_rate_monotonic_period_states state; |
---|
[8c8fd64] | 133 | |
---|
| 134 | /** |
---|
| 135 | * This is the length of wall time that has passed since this period |
---|
| 136 | * was last initiated. If the period is expired or has not been initiated, |
---|
| 137 | * then this field has no meaning. |
---|
| 138 | */ |
---|
[1e039fb3] | 139 | struct timespec since_last_period; |
---|
[8c8fd64] | 140 | |
---|
| 141 | /** |
---|
| 142 | * This is the amount of CPU time that has been used since this period |
---|
| 143 | * was last initiated. If the period is expired or has not been initiated, |
---|
| 144 | * then this field has no meaning. |
---|
| 145 | */ |
---|
[aacc7a0] | 146 | struct timespec executed_since_last_period; |
---|
[d7feb86] | 147 | |
---|
| 148 | /** This is the count of postponed jobs of this period. */ |
---|
| 149 | uint32_t postponed_jobs_count; |
---|
[113ef9fc] | 150 | } rtems_rate_monotonic_period_status; |
---|
| 151 | |
---|
[067a96a] | 152 | /** |
---|
[4c90eb4] | 153 | * @brief Create a Period |
---|
| 154 | * |
---|
| 155 | * Rate Monotonic Manager |
---|
[ac7d5ef0] | 156 | * |
---|
| 157 | * This routine implements the rate_monotonic_create directive. The |
---|
| 158 | * period will have the name name. It returns the id of the |
---|
| 159 | * created period in ID. |
---|
| 160 | */ |
---|
| 161 | rtems_status_code rtems_rate_monotonic_create( |
---|
[3235ad9] | 162 | rtems_name name, |
---|
[d3b72ca3] | 163 | rtems_id *id |
---|
[ac7d5ef0] | 164 | ); |
---|
| 165 | |
---|
[067a96a] | 166 | /** |
---|
[61b8e9f] | 167 | * @brief RTEMS Rate Monotonic Name to Id |
---|
[ac7d5ef0] | 168 | * |
---|
[61b8e9f] | 169 | * This routine implements the rtems_rate_monotonic_ident directive. |
---|
| 170 | * It returns the period ID associated with name. If more than one period |
---|
| 171 | * is named name, then the period to which the ID belongs is arbitrary. |
---|
[4c90eb4] | 172 | * |
---|
[61b8e9f] | 173 | * @param[in] name is the user defined period name |
---|
| 174 | * @param[in] id is the pointer to period id |
---|
[4c90eb4] | 175 | * |
---|
[61b8e9f] | 176 | * @retval This method returns RTEMS_SUCCESSFUL if there was not an |
---|
| 177 | * error. Otherwise, a status code is returned indicating the |
---|
| 178 | * source of the error. If successful, the id will |
---|
| 179 | * be filled in with the region id. |
---|
[ac7d5ef0] | 180 | */ |
---|
| 181 | rtems_status_code rtems_rate_monotonic_ident( |
---|
[3235ad9] | 182 | rtems_name name, |
---|
[d3b72ca3] | 183 | rtems_id *id |
---|
[ac7d5ef0] | 184 | ); |
---|
| 185 | |
---|
[067a96a] | 186 | /** |
---|
[61b8e9f] | 187 | * @brief RTEMS Rate Monotonic Cancel |
---|
[ac7d5ef0] | 188 | * |
---|
[61b8e9f] | 189 | * This routine implements the rtems_rate_monotonic_cancel directive. This |
---|
| 190 | * directive stops the period associated with ID from continuing to |
---|
| 191 | * run. |
---|
[4efe1955] | 192 | * |
---|
[61b8e9f] | 193 | * @param[in] id is the rate monotonic id |
---|
[4efe1955] | 194 | * |
---|
[61b8e9f] | 195 | * @retval RTEMS_SUCCESSFUL if successful and caller is not the owning thread |
---|
| 196 | * or error code if unsuccessful |
---|
[4efe1955] | 197 | * |
---|
[ac7d5ef0] | 198 | */ |
---|
| 199 | rtems_status_code rtems_rate_monotonic_cancel( |
---|
[d3b72ca3] | 200 | rtems_id id |
---|
[ac7d5ef0] | 201 | ); |
---|
| 202 | |
---|
[067a96a] | 203 | /** |
---|
[61b8e9f] | 204 | * @brief RTEMS Delete Rate Monotonic |
---|
[ac7d5ef0] | 205 | * |
---|
[61b8e9f] | 206 | * This routine implements the rtems_rate_monotonic_delete directive. The |
---|
| 207 | * period indicated by ID is deleted. |
---|
[4c90eb4] | 208 | * |
---|
[61b8e9f] | 209 | * @param[in] id is the rate monotonic id |
---|
[4c90eb4] | 210 | * |
---|
[61b8e9f] | 211 | * @retval This method returns RTEMS_SUCCESSFUL if there was not an |
---|
| 212 | * error. Otherwise, a status code is returned indicating the |
---|
| 213 | * source of the error. |
---|
[ac7d5ef0] | 214 | */ |
---|
| 215 | rtems_status_code rtems_rate_monotonic_delete( |
---|
[d3b72ca3] | 216 | rtems_id id |
---|
[ac7d5ef0] | 217 | ); |
---|
| 218 | |
---|
[067a96a] | 219 | /** |
---|
[61b8e9f] | 220 | * @brief RTEMS Rate Monotonic Get Status |
---|
[113ef9fc] | 221 | * |
---|
[61b8e9f] | 222 | * This routine implements the rtems_rate_monotonic_get_status directive. |
---|
| 223 | * Information about the period indicated by ID is returned. |
---|
[4c90eb4] | 224 | * |
---|
[61b8e9f] | 225 | * @param[in] id is the rate monotonic id |
---|
| 226 | * @param[in] status is the pointer to status control block |
---|
[4c90eb4] | 227 | * |
---|
[61b8e9f] | 228 | * @retval This method returns RTEMS_SUCCESSFUL if there was not an |
---|
| 229 | * error. Otherwise, a status code is returned indicating the |
---|
| 230 | * source of the error. |
---|
[113ef9fc] | 231 | * |
---|
| 232 | */ |
---|
| 233 | rtems_status_code rtems_rate_monotonic_get_status( |
---|
[d3b72ca3] | 234 | rtems_id id, |
---|
[113ef9fc] | 235 | rtems_rate_monotonic_period_status *status |
---|
| 236 | ); |
---|
| 237 | |
---|
[067a96a] | 238 | /** |
---|
[61b8e9f] | 239 | * @brief RTEMS Rate Monotonic Get Statistics |
---|
[e1bce86] | 240 | * |
---|
[61b8e9f] | 241 | * This routine implements the rtems_rate_monotonic_get_statistics directive. |
---|
| 242 | * Statistics gathered from the use of this period are returned. |
---|
[4efe1955] | 243 | * |
---|
[61b8e9f] | 244 | * @param[in] id is the rate monotonic id |
---|
| 245 | * @param[in] statistics is the pointer to statistics control block |
---|
[4efe1955] | 246 | * |
---|
[61b8e9f] | 247 | * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful |
---|
[e1bce86] | 248 | */ |
---|
| 249 | rtems_status_code rtems_rate_monotonic_get_statistics( |
---|
[d3b72ca3] | 250 | rtems_id id, |
---|
[e1bce86] | 251 | rtems_rate_monotonic_period_statistics *statistics |
---|
| 252 | ); |
---|
| 253 | |
---|
[067a96a] | 254 | /** |
---|
[4c90eb4] | 255 | * @brief RTEMS Rate Monotonic Reset Statistics |
---|
| 256 | * |
---|
| 257 | * Rate Monotonic Manager -- Reset Statistics |
---|
[e1bce86] | 258 | * |
---|
[eb37f9d] | 259 | * This routine allows a thread to reset the statistics information |
---|
[e1bce86] | 260 | * on a specific period instance. |
---|
| 261 | */ |
---|
| 262 | rtems_status_code rtems_rate_monotonic_reset_statistics( |
---|
[d3b72ca3] | 263 | rtems_id id |
---|
[e1bce86] | 264 | ); |
---|
| 265 | |
---|
[067a96a] | 266 | /** |
---|
| 267 | * @brief rtems_rate_monotonic_reset_all_statistics |
---|
[e1bce86] | 268 | * |
---|
[eb37f9d] | 269 | * This routine allows a thread to reset the statistics information |
---|
[e1bce86] | 270 | * on ALL period instances. |
---|
| 271 | */ |
---|
[c3330a8] | 272 | void rtems_rate_monotonic_reset_all_statistics( void ); |
---|
[e1bce86] | 273 | |
---|
[067a96a] | 274 | /** |
---|
[a6500136] | 275 | * @brief RTEMS Report Rate Monotonic Statistics |
---|
[90a5d194] | 276 | * |
---|
[eb37f9d] | 277 | * This routine allows a thread to print the statistics information |
---|
[24d0ee57] | 278 | * on ALL period instances which have non-zero counts using the RTEMS |
---|
| 279 | * printer. The implementation of this directive straddles the fence |
---|
| 280 | * between inside and outside of RTEMS. It is presented as part of |
---|
| 281 | * the Manager but actually uses other services of the Manager. |
---|
[90a5d194] | 282 | */ |
---|
| 283 | void rtems_rate_monotonic_report_statistics_with_plugin( |
---|
[a33bfb6] | 284 | const struct rtems_printer *printer |
---|
[90a5d194] | 285 | ); |
---|
| 286 | |
---|
[067a96a] | 287 | /** |
---|
[a6500136] | 288 | * @brief RTEMS Report Rate Monotonic Statistics |
---|
[e1bce86] | 289 | * |
---|
[eb37f9d] | 290 | * This routine allows a thread to print the statistics information |
---|
[e1bce86] | 291 | * on ALL period instances which have non-zero counts using printk. |
---|
| 292 | */ |
---|
[c3330a8] | 293 | void rtems_rate_monotonic_report_statistics( void ); |
---|
[e1bce86] | 294 | |
---|
[067a96a] | 295 | /** |
---|
[61b8e9f] | 296 | * @brief RTEMS Rate Monotonic Period |
---|
[ac7d5ef0] | 297 | * |
---|
[61b8e9f] | 298 | * This routine implements the rtems_rate_monotonic_period directive. When |
---|
| 299 | * length is non-zero, this directive initiates the period associated with |
---|
| 300 | * ID from continuing for a period of length. If length is zero, then |
---|
| 301 | * result is set to indicate the current state of the period. |
---|
[4efe1955] | 302 | * |
---|
[61b8e9f] | 303 | * @param[in] id is the rate monotonic id |
---|
[e858f70] | 304 | * @param[in] length is the length of period (in ticks) |
---|
[4efe1955] | 305 | * |
---|
[61b8e9f] | 306 | * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful |
---|
[ac7d5ef0] | 307 | */ |
---|
| 308 | rtems_status_code rtems_rate_monotonic_period( |
---|
[d3b72ca3] | 309 | rtems_id id, |
---|
[3a4ae6c] | 310 | rtems_interval length |
---|
[ac7d5ef0] | 311 | ); |
---|
| 312 | |
---|
[ecdcf01] | 313 | /**@}*/ |
---|
[ac7d5ef0] | 314 | |
---|
| 315 | #ifdef __cplusplus |
---|
| 316 | } |
---|
| 317 | #endif |
---|
| 318 | |
---|
| 319 | #endif |
---|
| 320 | /* end of include file */ |
---|