[ae68ff0] | 1 | @c |
---|
[a91cc06] | 2 | @c COPYRIGHT (c) 1988-2007 |
---|
[ae68ff0] | 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
[139b2e4a] | 6 | @c $Id$ |
---|
| 7 | @c |
---|
[ae68ff0] | 8 | |
---|
| 9 | @chapter Clock Manager |
---|
[20515fc] | 10 | |
---|
[169502e] | 11 | @cindex clock |
---|
| 12 | |
---|
[ae68ff0] | 13 | @section Introduction |
---|
| 14 | |
---|
| 15 | The clock manager provides support for time of day |
---|
| 16 | and other time related capabilities. The directives provided by |
---|
| 17 | the clock manager are: |
---|
| 18 | |
---|
| 19 | @itemize @bullet |
---|
[4fa4ea65] | 20 | @item @code{@value{DIRPREFIX}clock_set} - Set system date and time |
---|
| 21 | @item @code{@value{DIRPREFIX}clock_get} - Get system date and time information |
---|
[bf4d016] | 22 | @item @code{@value{DIRPREFIX}clock_get_uptime} - Get time since boot |
---|
[a91cc06] | 23 | @item @code{@value{DIRPREFIX}clock_set_nanoseconds_extension} - Install the nanoseconds since last tick handler |
---|
[4fa4ea65] | 24 | @item @code{@value{DIRPREFIX}clock_tick} - Announce a clock tick |
---|
[ae68ff0] | 25 | @end itemize |
---|
| 26 | |
---|
| 27 | @section Background |
---|
[20515fc] | 28 | |
---|
[ae68ff0] | 29 | @subsection Required Support |
---|
| 30 | |
---|
| 31 | For the features provided by the clock manager to be |
---|
| 32 | utilized, periodic timer interrupts are required. Therefore, a |
---|
| 33 | real-time clock or hardware timer is necessary to create the |
---|
[75e22db] | 34 | timer interrupts. The @code{@value{DIRPREFIX}clock_tick} |
---|
| 35 | directive is normally called |
---|
[ae68ff0] | 36 | by the timer ISR to announce to RTEMS that a system clock tick |
---|
| 37 | has occurred. Elapsed time is measured in ticks. A tick is |
---|
| 38 | defined to be an integral number of microseconds which is |
---|
| 39 | specified by the user in the Configuration Table. |
---|
| 40 | |
---|
| 41 | @subsection Time and Date Data Structures |
---|
| 42 | |
---|
| 43 | The clock facilities of the clock manager operate |
---|
| 44 | upon calendar time. These directives utilize the following date |
---|
[7e8a1fc] | 45 | and time @value{STRUCTURE} for the native time and date format: |
---|
[ae68ff0] | 46 | |
---|
[adee5979] | 47 | |
---|
[61389eac] | 48 | @ifset is-C |
---|
[adee5979] | 49 | @findex rtems_time_of_day |
---|
[ae68ff0] | 50 | @example |
---|
| 51 | struct rtems_tod_control @{ |
---|
| 52 | rtems_unsigned32 year; /* greater than 1987 */ |
---|
| 53 | rtems_unsigned32 month; /* 1 - 12 */ |
---|
| 54 | rtems_unsigned32 day; /* 1 - 31 */ |
---|
| 55 | rtems_unsigned32 hour; /* 0 - 23 */ |
---|
| 56 | rtems_unsigned32 minute; /* 0 - 59 */ |
---|
| 57 | rtems_unsigned32 second; /* 0 - 59 */ |
---|
| 58 | rtems_unsigned32 ticks; /* elapsed between seconds */ |
---|
| 59 | @}; |
---|
| 60 | |
---|
| 61 | typedef struct rtems_tod_control rtems_time_of_day; |
---|
| 62 | @end example |
---|
[61389eac] | 63 | @end ifset |
---|
| 64 | |
---|
| 65 | @ifset is-Ada |
---|
| 66 | @example |
---|
| 67 | type Time_Of_Day is |
---|
| 68 | record |
---|
| 69 | Year : RTEMS.Unsigned32; -- year, A.D. |
---|
| 70 | Month : RTEMS.Unsigned32; -- month, 1 .. 12 |
---|
| 71 | Day : RTEMS.Unsigned32; -- day, 1 .. 31 |
---|
| 72 | Hour : RTEMS.Unsigned32; -- hour, 0 .. 23 |
---|
| 73 | Minute : RTEMS.Unsigned32; -- minute, 0 .. 59 |
---|
| 74 | Second : RTEMS.Unsigned32; -- second, 0 .. 59 |
---|
| 75 | Ticks : RTEMS.Unsigned32; -- elapsed ticks between seconds |
---|
| 76 | end record; |
---|
| 77 | @end example |
---|
| 78 | @end ifset |
---|
[ae68ff0] | 79 | |
---|
| 80 | |
---|
| 81 | The native date and time format is the only format |
---|
| 82 | supported when setting the system date and time using the |
---|
[75e22db] | 83 | @code{@value{DIRPREFIX}clock_get} directive. Some applications |
---|
| 84 | expect to operate on a "UNIX-style" date and time data structure. The |
---|
| 85 | @code{@value{DIRPREFIX}clock_get} directive can optionally return |
---|
| 86 | the current date and time in the |
---|
[7e8a1fc] | 87 | following @value{STRUCTURE}: |
---|
[ae68ff0] | 88 | |
---|
[61389eac] | 89 | @ifset is-C |
---|
[ae68ff0] | 90 | @example |
---|
| 91 | @group |
---|
| 92 | typedef struct @{ |
---|
| 93 | rtems_unsigned32 seconds; /* seconds since RTEMS epoch*/ |
---|
| 94 | rtems_unsigned32 microseconds; /* since last second */ |
---|
[61389eac] | 95 | @} rtems_clock_time_value; |
---|
[ae68ff0] | 96 | @end group |
---|
| 97 | @end example |
---|
[61389eac] | 98 | @end ifset |
---|
[ae68ff0] | 99 | |
---|
[61389eac] | 100 | @ifset is-Ada |
---|
| 101 | @example |
---|
| 102 | type Clock_Time_Value is |
---|
| 103 | record |
---|
| 104 | Seconds : Unsigned32; |
---|
| 105 | Microseconds : Unsigned32; |
---|
| 106 | end record; |
---|
| 107 | @end example |
---|
| 108 | @end ifset |
---|
[ae68ff0] | 109 | |
---|
[7e8a1fc] | 110 | The seconds field in this @value{STRUCTURE} is the number of |
---|
[ae68ff0] | 111 | seconds since the RTEMS epoch of January 1, 1988. |
---|
| 112 | |
---|
| 113 | @subsection Clock Tick and Timeslicing |
---|
| 114 | |
---|
[adee5979] | 115 | @cindex timeslicing |
---|
| 116 | |
---|
[ae68ff0] | 117 | Timeslicing is a task scheduling discipline in which |
---|
| 118 | tasks of equal priority are executed for a specific period of |
---|
| 119 | time before control of the CPU is passed to another task. It is |
---|
| 120 | also sometimes referred to as the automatic round-robin |
---|
| 121 | scheduling algorithm. The length of time allocated to each task |
---|
| 122 | is known as the quantum or timeslice. |
---|
| 123 | |
---|
| 124 | The system's timeslice is defined as an integral |
---|
| 125 | number of ticks, and is specified in the Configuration Table. |
---|
| 126 | The timeslice is defined for the entire system of tasks, but |
---|
| 127 | timeslicing is enabled and disabled on a per task basis. |
---|
| 128 | |
---|
[75e22db] | 129 | The @code{@value{DIRPREFIX}clock_tick} |
---|
| 130 | directive implements timeslicing by |
---|
[ae68ff0] | 131 | decrementing the running task's time-remaining counter when both |
---|
| 132 | timeslicing and preemption are enabled. If the task's timeslice |
---|
| 133 | has expired, then that task will be preempted if there exists a |
---|
| 134 | ready task of equal priority. |
---|
| 135 | |
---|
| 136 | @subsection Delays |
---|
| 137 | |
---|
[adee5979] | 138 | @cindex delays |
---|
| 139 | |
---|
[ae68ff0] | 140 | A sleep timer allows a task to delay for a given |
---|
| 141 | interval or up until a given time, and then wake and continue |
---|
| 142 | execution. This type of timer is created automatically by the |
---|
[75e22db] | 143 | @code{@value{DIRPREFIX}task_wake_after} |
---|
| 144 | and @code{@value{DIRPREFIX}task_wake_when} directives and, as a result, |
---|
[ae68ff0] | 145 | does not have an RTEMS ID. Once activated, a sleep timer cannot |
---|
| 146 | be explicitly deleted. Each task may activate one and only one |
---|
| 147 | sleep timer at a time. |
---|
| 148 | |
---|
| 149 | @subsection Timeouts |
---|
| 150 | |
---|
[adee5979] | 151 | @cindex timeouts |
---|
| 152 | |
---|
[ae68ff0] | 153 | Timeouts are a special type of timer automatically |
---|
| 154 | created when the timeout option is used on the |
---|
[75e22db] | 155 | @code{@value{DIRPREFIX}message_queue_receive}, |
---|
| 156 | @code{@value{DIRPREFIX}event_receive}, |
---|
| 157 | @code{@value{DIRPREFIX}semaphore_obtain} and |
---|
| 158 | @code{@value{DIRPREFIX}region_get_segment} directives. |
---|
| 159 | Each task may have one and only one timeout active at a time. |
---|
| 160 | When a timeout expires, it unblocks the task with a timeout status code. |
---|
[ae68ff0] | 161 | |
---|
| 162 | @section Operations |
---|
[20515fc] | 163 | |
---|
[ae68ff0] | 164 | @subsection Announcing a Tick |
---|
| 165 | |
---|
[75e22db] | 166 | RTEMS provides the @code{@value{DIRPREFIX}clock_tick} directive which is |
---|
[ae68ff0] | 167 | called from the user's real-time clock ISR to inform RTEMS that |
---|
| 168 | a tick has elapsed. The tick frequency value, defined in |
---|
| 169 | microseconds, is a configuration parameter found in the |
---|
| 170 | Configuration Table. RTEMS divides one million microseconds |
---|
| 171 | (one second) by the number of microseconds per tick to determine |
---|
[75e22db] | 172 | the number of calls to the |
---|
| 173 | @code{@value{DIRPREFIX}clock_tick} directive per second. The |
---|
| 174 | frequency of @code{@value{DIRPREFIX}clock_tick} |
---|
| 175 | calls determines the resolution |
---|
[ae68ff0] | 176 | (granularity) for all time dependent RTEMS actions. For |
---|
[75e22db] | 177 | example, calling @code{@value{DIRPREFIX}clock_tick} |
---|
| 178 | ten times per second yields a higher |
---|
| 179 | resolution than calling @code{@value{DIRPREFIX}clock_tick} |
---|
| 180 | two times per second. The @code{@value{DIRPREFIX}clock_tick} |
---|
| 181 | directive is responsible for maintaining both |
---|
[ae68ff0] | 182 | calendar time and the dynamic set of timers. |
---|
| 183 | |
---|
| 184 | @subsection Setting the Time |
---|
| 185 | |
---|
[75e22db] | 186 | The @code{@value{DIRPREFIX}clock_set} directive allows a task or an ISR to |
---|
[ae68ff0] | 187 | set the date and time maintained by RTEMS. If setting the date |
---|
| 188 | and time causes any outstanding timers to pass their deadline, |
---|
| 189 | then the expired timers will be fired during the invocation of |
---|
[75e22db] | 190 | the @code{@value{DIRPREFIX}clock_set} directive. |
---|
[ae68ff0] | 191 | |
---|
| 192 | @subsection Obtaining the Time |
---|
| 193 | |
---|
[75e22db] | 194 | The @code{@value{DIRPREFIX}clock_get} directive allows a task or an ISR to |
---|
[ae68ff0] | 195 | obtain the current date and time or date and time related |
---|
| 196 | information. The current date and time can be returned in |
---|
| 197 | either native or UNIX-style format. Additionally, the |
---|
| 198 | application can obtain date and time related information such as |
---|
| 199 | the number of seconds since the RTEMS epoch, the number of ticks |
---|
| 200 | since the executive was initialized, and the number of ticks per |
---|
[75e22db] | 201 | second. The information returned by the |
---|
| 202 | @code{@value{DIRPREFIX}clock_get} directive is |
---|
[adee5979] | 203 | dependent on the option selected by the caller. This |
---|
| 204 | is specified using one of the following constants |
---|
| 205 | associated with the enumerated type |
---|
| 206 | @code{@value{DIRPREFIX}clock_get_options}: |
---|
| 207 | |
---|
| 208 | @findex rtems_clock_get_options |
---|
[ae68ff0] | 209 | |
---|
| 210 | @itemize @bullet |
---|
[4fa4ea65] | 211 | @item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time |
---|
[a94c5a5d] | 212 | |
---|
[75e22db] | 213 | @item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - obtain UNIX-style |
---|
| 214 | date and time |
---|
[a94c5a5d] | 215 | |
---|
[4fa4ea65] | 216 | @item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - obtain number of ticks |
---|
[a94c5a5d] | 217 | since RTEMS was initialized |
---|
| 218 | |
---|
[75e22db] | 219 | @item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - obtain number |
---|
| 220 | of seconds since RTEMS epoch |
---|
[a94c5a5d] | 221 | |
---|
[75e22db] | 222 | @item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - obtain number of clock |
---|
| 223 | ticks per second |
---|
[a94c5a5d] | 224 | |
---|
[ae68ff0] | 225 | @end itemize |
---|
| 226 | |
---|
| 227 | Calendar time operations will return an error code if |
---|
| 228 | invoked before the date and time have been set. |
---|
| 229 | |
---|
| 230 | @section Directives |
---|
| 231 | |
---|
| 232 | This section details the clock manager's directives. |
---|
| 233 | A subsection is dedicated to each of this manager's directives |
---|
| 234 | and describes the calling sequence, related constants, usage, |
---|
| 235 | and status codes. |
---|
| 236 | |
---|
[169502e] | 237 | @c |
---|
| 238 | @c |
---|
| 239 | @c |
---|
[ae68ff0] | 240 | @page |
---|
| 241 | @subsection CLOCK_SET - Set system date and time |
---|
| 242 | |
---|
| 243 | @subheading CALLING SEQUENCE: |
---|
| 244 | |
---|
[169502e] | 245 | @cindex set the time of day |
---|
| 246 | |
---|
[61389eac] | 247 | @ifset is-C |
---|
[169502e] | 248 | @findex rtems_clock_set |
---|
[ae68ff0] | 249 | @example |
---|
| 250 | rtems_status_code rtems_clock_set( |
---|
| 251 | rtems_time_of_day *time_buffer |
---|
| 252 | ); |
---|
| 253 | @end example |
---|
[61389eac] | 254 | @end ifset |
---|
| 255 | |
---|
| 256 | @ifset is-Ada |
---|
| 257 | @example |
---|
| 258 | procedure Clock_Set ( |
---|
| 259 | Time_Buffer : in RTEMS.Time_Of_Day; |
---|
| 260 | Result : out RTEMS.Status_Codes |
---|
| 261 | ); |
---|
| 262 | @end example |
---|
| 263 | @end ifset |
---|
[ae68ff0] | 264 | |
---|
| 265 | @subheading DIRECTIVE STATUS CODES: |
---|
[4fa4ea65] | 266 | @code{@value{RPREFIX}SUCCESSFUL} - date and time set successfully@* |
---|
[f8892c9] | 267 | @code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL@* |
---|
[5003e1a] | 268 | @code{@value{RPREFIX}INVALID_TIME_OF_DAY} - invalid time of day |
---|
[ae68ff0] | 269 | |
---|
| 270 | @subheading DESCRIPTION: |
---|
| 271 | |
---|
| 272 | This directive sets the system date and time. The |
---|
[7e8a1fc] | 273 | date, time, and ticks in the time_buffer @value{STRUCTURE} are all |
---|
[ae68ff0] | 274 | range-checked, and an error is returned if any one is out of its |
---|
| 275 | valid range. |
---|
| 276 | |
---|
| 277 | @subheading NOTES: |
---|
| 278 | |
---|
| 279 | Years before 1988 are invalid. |
---|
| 280 | |
---|
| 281 | The system date and time are based on the configured |
---|
| 282 | tick rate (number of microseconds in a tick). |
---|
| 283 | |
---|
| 284 | Setting the time forward may cause a higher priority |
---|
| 285 | task, blocked waiting on a specific time, to be made ready. In |
---|
| 286 | this case, the calling task will be preempted after the next |
---|
| 287 | clock tick. |
---|
| 288 | |
---|
| 289 | Re-initializing RTEMS causes the system date and time |
---|
| 290 | to be reset to an uninitialized state. Another call to |
---|
[75e22db] | 291 | @code{@value{DIRPREFIX}clock_set} is required to re-initialize |
---|
| 292 | the system date and time to application specific specifications. |
---|
[ae68ff0] | 293 | |
---|
[169502e] | 294 | @c |
---|
| 295 | @c |
---|
| 296 | @c |
---|
[ae68ff0] | 297 | @page |
---|
| 298 | @subsection CLOCK_GET - Get system date and time information |
---|
| 299 | |
---|
[169502e] | 300 | @cindex obtain the time of day |
---|
| 301 | |
---|
[ae68ff0] | 302 | @subheading CALLING SEQUENCE: |
---|
| 303 | |
---|
[61389eac] | 304 | @ifset is-C |
---|
[169502e] | 305 | @findex rtems_clock_get |
---|
[ae68ff0] | 306 | @example |
---|
| 307 | rtems_status_code rtems_clock_get( |
---|
| 308 | rtems_clock_get_options option, |
---|
| 309 | void *time_buffer |
---|
| 310 | ); |
---|
| 311 | @end example |
---|
[61389eac] | 312 | @end ifset |
---|
| 313 | |
---|
| 314 | @ifset is-Ada |
---|
| 315 | @example |
---|
| 316 | procedure Clock_Get ( |
---|
| 317 | Option : in RTEMS.Clock_Get_Options; |
---|
| 318 | Time_Buffer : in RTEMS.Address; |
---|
| 319 | Result : out RTEMS.Status_Codes |
---|
| 320 | ); |
---|
| 321 | @end example |
---|
| 322 | @end ifset |
---|
[ae68ff0] | 323 | |
---|
| 324 | @subheading DIRECTIVE STATUS CODES: |
---|
[4fa4ea65] | 325 | @code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@* |
---|
[f8892c9] | 326 | @code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@* |
---|
| 327 | @code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL |
---|
[ae68ff0] | 328 | |
---|
| 329 | @subheading DESCRIPTION: |
---|
| 330 | |
---|
| 331 | This directive obtains the system date and time. If |
---|
| 332 | the caller is attempting to obtain the date and time (i.e. |
---|
[4fa4ea65] | 333 | option is set to either @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH}, |
---|
[75e22db] | 334 | @code{@value{RPREFIX}CLOCK_GET_TOD}, or |
---|
| 335 | @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and the date and time |
---|
| 336 | has not been set with a previous call to |
---|
| 337 | @code{@value{DIRPREFIX}clock_set}, then the |
---|
| 338 | @code{@value{RPREFIX}NOT_DEFINED} status code is returned. |
---|
| 339 | The caller can always obtain the number of ticks per second (option is |
---|
| 340 | @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of |
---|
| 341 | ticks since the executive was initialized option is |
---|
| 342 | @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT}). |
---|
[ae68ff0] | 343 | |
---|
[adee5979] | 344 | The @code{option} argument may taken on any value of the enumerated |
---|
| 345 | type @code{rtems_clock_get_options}. The data type expected for |
---|
| 346 | @code{time_buffer} is based on the value of @code{option} as |
---|
| 347 | indicated below: |
---|
[c3fec1c] | 348 | |
---|
[adee5979] | 349 | @findex rtems_clock_get_options |
---|
[c3fec1c] | 350 | @ifset is-C |
---|
| 351 | @itemize @bullet |
---|
[4fa4ea65] | 352 | @item @code{@value{RPREFIX}CLOCK_GET_TOD} - (rtems_time_of_day *) |
---|
[c3fec1c] | 353 | |
---|
[4fa4ea65] | 354 | @item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - (rtems_clock_time_value *) |
---|
[c3fec1c] | 355 | |
---|
[4fa4ea65] | 356 | @item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - (rtems_interval *) |
---|
[c3fec1c] | 357 | |
---|
[4fa4ea65] | 358 | @item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - (rtems_interval *) |
---|
[c3fec1c] | 359 | |
---|
[4fa4ea65] | 360 | @item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - (rtems_interval *) |
---|
[c3fec1c] | 361 | |
---|
| 362 | @end itemize |
---|
| 363 | @end ifset |
---|
| 364 | |
---|
| 365 | @ifset is-Ada |
---|
| 366 | @itemize @bullet |
---|
[75e22db] | 367 | @item @code{@value{RPREFIX}CLOCK_GET_TOD} - Address of an variable of |
---|
| 368 | type RTEMS.Time_Of_Day |
---|
[c3fec1c] | 369 | |
---|
[4fa4ea65] | 370 | @item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - Address of an variable of |
---|
[c3fec1c] | 371 | type RTEMS.Clock_Time_Value |
---|
| 372 | |
---|
[75e22db] | 373 | @item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - Address of an |
---|
| 374 | variable of type RTEMS.Interval |
---|
[c3fec1c] | 375 | |
---|
[75e22db] | 376 | @item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - Address of an |
---|
| 377 | variable of type RTEMS.Interval |
---|
[c3fec1c] | 378 | |
---|
[75e22db] | 379 | @item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - Address of an |
---|
| 380 | variable of type RTEMS.Interval |
---|
[c3fec1c] | 381 | |
---|
| 382 | @end itemize |
---|
| 383 | @end ifset |
---|
| 384 | |
---|
[ae68ff0] | 385 | @subheading NOTES: |
---|
| 386 | |
---|
| 387 | This directive is callable from an ISR. |
---|
| 388 | |
---|
| 389 | This directive will not cause the running task to be |
---|
| 390 | preempted. Re-initializing RTEMS causes the system date and |
---|
| 391 | time to be reset to an uninitialized state. Another call to |
---|
[75e22db] | 392 | @code{@value{DIRPREFIX}clock_set} is required to re-initialize the |
---|
| 393 | system date and time to application specific specifications. |
---|
[ae68ff0] | 394 | |
---|
[a91cc06] | 395 | @c |
---|
| 396 | @c |
---|
| 397 | @c |
---|
| 398 | @page |
---|
| 399 | @subsection CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler |
---|
| 400 | |
---|
| 401 | @cindex clock set nanoseconds extension |
---|
| 402 | @cindex nanoseconds extension |
---|
| 403 | @cindex nanoseconds time accuracy |
---|
| 404 | |
---|
| 405 | @subheading CALLING SEQUENCE: |
---|
| 406 | |
---|
| 407 | @ifset is-C |
---|
| 408 | @findex rtems_clock_set_nanoseconds_extension |
---|
| 409 | @example |
---|
| 410 | rtems_status_code rtems_clock_set_nanoseconds_extension( |
---|
| 411 | rtems_nanoseconds_extension_routine routine |
---|
| 412 | ); |
---|
| 413 | @end example |
---|
| 414 | @end ifset |
---|
| 415 | |
---|
| 416 | @ifset is-Ada |
---|
| 417 | @example |
---|
| 418 | NOT SUPPORTED FROM Ada BINDING |
---|
| 419 | @end example |
---|
| 420 | @end ifset |
---|
| 421 | |
---|
| 422 | @subheading DIRECTIVE STATUS CODES: |
---|
| 423 | @code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@* |
---|
| 424 | @code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL |
---|
| 425 | |
---|
| 426 | @subheading DESCRIPTION: |
---|
| 427 | |
---|
| 428 | This directive is used by the Clock device driver to install the |
---|
| 429 | @code{routine} which will be invoked by the internal RTEMS method used to |
---|
| 430 | obtain a highly accurate time of day. It is usually called during |
---|
| 431 | the initialization of the driver. |
---|
| 432 | |
---|
| 433 | When the @code{routine} is invoked, it will determine the number of |
---|
| 434 | nanoseconds which have elapsed since the last invocation of |
---|
| 435 | the @code{@value{DIRPREFIX}clock_tick} directive. It should do |
---|
| 436 | this as quickly as possible with as little impact as possible |
---|
| 437 | on the device used as a clock source. |
---|
| 438 | |
---|
| 439 | @subheading NOTES: |
---|
| 440 | |
---|
| 441 | This directive may be called from an ISR. |
---|
| 442 | |
---|
| 443 | This directive is called as part of every service to obtain the |
---|
| 444 | current date and time as well as timestamps. |
---|
| 445 | |
---|
[bf4d016] | 446 | @c |
---|
| 447 | @c |
---|
| 448 | @c |
---|
| 449 | @page |
---|
| 450 | @subsection CLOCK_GET_UPTIME - Get the time since booy |
---|
| 451 | |
---|
| 452 | @cindex clock get uptime |
---|
| 453 | @cindex uptime |
---|
| 454 | |
---|
| 455 | @subheading CALLING SEQUENCE: |
---|
| 456 | |
---|
| 457 | @ifset is-C |
---|
| 458 | @findex rtems_clock_get_uptime |
---|
| 459 | @example |
---|
| 460 | rtems_status_code rtems_clock_get_uptime( |
---|
| 461 | struct timespec *uptime |
---|
| 462 | ); |
---|
| 463 | @end example |
---|
| 464 | @end ifset |
---|
| 465 | |
---|
| 466 | @ifset is-Ada |
---|
| 467 | @example |
---|
| 468 | NOT SUPPORTED FROM Ada BINDING |
---|
| 469 | @end example |
---|
| 470 | @end ifset |
---|
| 471 | |
---|
| 472 | @subheading DIRECTIVE STATUS CODES: |
---|
| 473 | @code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@* |
---|
| 474 | @code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL |
---|
| 475 | |
---|
| 476 | @subheading DESCRIPTION: |
---|
| 477 | |
---|
| 478 | This directive returns the seconds and nanoseconds since the |
---|
| 479 | system was booted. If the BSP supports nanosecond clock |
---|
| 480 | accuracy, the time reported will probably be different on every |
---|
| 481 | call. |
---|
| 482 | |
---|
| 483 | @subheading NOTES: |
---|
| 484 | |
---|
| 485 | This directive may be called from an ISR. |
---|
| 486 | |
---|
[169502e] | 487 | @c |
---|
| 488 | @c |
---|
| 489 | @c |
---|
[ae68ff0] | 490 | @page |
---|
| 491 | @subsection CLOCK_TICK - Announce a clock tick |
---|
| 492 | |
---|
[169502e] | 493 | @cindex clock tick |
---|
| 494 | |
---|
[ae68ff0] | 495 | @subheading CALLING SEQUENCE: |
---|
| 496 | |
---|
[61389eac] | 497 | @ifset is-C |
---|
[169502e] | 498 | @findex rtems_clock_tick |
---|
[ae68ff0] | 499 | @example |
---|
| 500 | rtems_status_code rtems_clock_tick( void ); |
---|
| 501 | @end example |
---|
[61389eac] | 502 | @end ifset |
---|
| 503 | |
---|
| 504 | @ifset is-Ada |
---|
| 505 | @example |
---|
[a91cc06] | 506 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 507 | @end example |
---|
| 508 | @end ifset |
---|
[ae68ff0] | 509 | |
---|
| 510 | @subheading DIRECTIVE STATUS CODES: |
---|
[f8892c9] | 511 | @code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully |
---|
[ae68ff0] | 512 | |
---|
| 513 | @subheading DESCRIPTION: |
---|
| 514 | |
---|
| 515 | This directive announces to RTEMS that a system clock |
---|
| 516 | tick has occurred. The directive is usually called from the |
---|
| 517 | timer interrupt ISR of the local processor. This directive |
---|
| 518 | maintains the system date and time, decrements timers for |
---|
| 519 | delayed tasks, timeouts, rate monotonic periods, and implements |
---|
| 520 | timeslicing. |
---|
| 521 | |
---|
| 522 | @subheading NOTES: |
---|
| 523 | |
---|
| 524 | This directive is typically called from an ISR. |
---|
| 525 | |
---|
[a91cc06] | 526 | The @code{microseconds_per_tick} and @code{ticks_per_timeslice} |
---|
[ae68ff0] | 527 | parameters in the Configuration Table contain the number of |
---|
| 528 | microseconds per tick and number of ticks per timeslice, |
---|
| 529 | respectively. |
---|
| 530 | |
---|