diff options
Diffstat (limited to 'doc/user/clock.t')
| -rw-r--r-- | doc/user/clock.t | 956 |
1 files changed, 0 insertions, 956 deletions
diff --git a/doc/user/clock.t b/doc/user/clock.t deleted file mode 100644 index f67003c5f8..0000000000 --- a/doc/user/clock.t +++ /dev/null @@ -1,956 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2008 -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Clock Manager - -@cindex clock - -@section Introduction - -The clock manager provides support for time of day -and other time related capabilities. The directives provided by -the clock manager are: - -@itemize @bullet -@item @code{@value{DIRPREFIX}clock_set} - Set date and time -@item @code{@value{DIRPREFIX}clock_get} - Get date and time information -@item @code{@value{DIRPREFIX}clock_get_tod} - Get date and time in TOD format -@item @code{@value{DIRPREFIX}clock_get_tod_timeval} - Get date and time in timeval format -@item @code{@value{DIRPREFIX}clock_get_seconds_since_epoch} - Get seconds since epoch -@item @code{@value{DIRPREFIX}clock_get_ticks_per_second} - Get ticks per second -@item @code{@value{DIRPREFIX}clock_get_ticks_since_boot} - Get current ticks counter value -@item @code{@value{DIRPREFIX}clock_tick_later} - Get tick value in the future -@item @code{@value{DIRPREFIX}clock_tick_later_usec} - Get tick value in the future in microseconds -@item @code{@value{DIRPREFIX}clock_tick_before} - Is tick value is before a point in time -@item @code{@value{DIRPREFIX}clock_get_uptime} - Get time since boot -@item @code{@value{DIRPREFIX}clock_get_uptime_timeval} - Get time since boot in timeval format -@item @code{@value{DIRPREFIX}clock_get_uptime_seconds} - Get seconds since boot -@item @code{@value{DIRPREFIX}clock_get_uptime_nanoseconds} - Get nanoseconds since boot -@item @code{@value{DIRPREFIX}clock_set_nanoseconds_extension} - Install the nanoseconds since last tick handler -@item @code{@value{DIRPREFIX}clock_tick} - Announce a clock tick -@end itemize - -@section Background - -@subsection Required Support - -For the features provided by the clock manager to be -utilized, periodic timer interrupts are required. Therefore, a -real-time clock or hardware timer is necessary to create the -timer interrupts. The @code{@value{DIRPREFIX}clock_tick} -directive is normally called -by the timer ISR to announce to RTEMS that a system clock tick -has occurred. Elapsed time is measured in ticks. A tick is -defined to be an integral number of microseconds which is -specified by the user in the Configuration Table. - -@subsection Time and Date Data Structures - -The clock facilities of the clock manager operate -upon calendar time. These directives utilize the following date -and time @value{STRUCTURE} for the native time and date format: - - -@ifset is-C -@findex rtems_time_of_day -@example -struct rtems_tod_control @{ - uint32_t year; /* greater than 1987 */ - uint32_t month; /* 1 - 12 */ - uint32_t day; /* 1 - 31 */ - uint32_t hour; /* 0 - 23 */ - uint32_t minute; /* 0 - 59 */ - uint32_t second; /* 0 - 59 */ - uint32_t ticks; /* elapsed between seconds */ -@}; - -typedef struct rtems_tod_control rtems_time_of_day; -@end example -@end ifset - -@ifset is-Ada -@example -type Time_Of_Day is - record - Year : RTEMS.Unsigned32; -- year, A.D. - Month : RTEMS.Unsigned32; -- month, 1 .. 12 - Day : RTEMS.Unsigned32; -- day, 1 .. 31 - Hour : RTEMS.Unsigned32; -- hour, 0 .. 23 - Minute : RTEMS.Unsigned32; -- minute, 0 .. 59 - Second : RTEMS.Unsigned32; -- second, 0 .. 59 - Ticks : RTEMS.Unsigned32; -- elapsed ticks between seconds - end record; -@end example -@end ifset - - -The native date and time format is the only format -supported when setting the system date and time using the -@code{@value{DIRPREFIX}clock_set} directive. Some applications -expect to operate on a "UNIX-style" date and time data structure. The -@code{@value{DIRPREFIX}clock_get_tod_timeval} always returns -the date and time in @code{struct timeval} format. The -@code{@value{DIRPREFIX}clock_get} directive can optionally return -the current date and time in this format. - -The @code{struct timeval} data structure has two fields: @code{tv_sec} -and @code{tv_usec} which are seconds and microseconds, respectively. -The @code{tv_sec} field in this data structure is the number of seconds -since the POSIX epoch of January 1, 1970 but will never be prior to -the RTEMS epoch of January 1, 1988. - -@subsection Clock Tick and Timeslicing - -@cindex timeslicing - -Timeslicing is a task scheduling discipline in which -tasks of equal priority are executed for a specific period of -time before control of the CPU is passed to another task. It is -also sometimes referred to as the automatic round-robin -scheduling algorithm. The length of time allocated to each task -is known as the quantum or timeslice. - -The system's timeslice is defined as an integral -number of ticks, and is specified in the Configuration Table. -The timeslice is defined for the entire system of tasks, but -timeslicing is enabled and disabled on a per task basis. - -The @code{@value{DIRPREFIX}clock_tick} -directive implements timeslicing by -decrementing the running task's time-remaining counter when both -timeslicing and preemption are enabled. If the task's timeslice -has expired, then that task will be preempted if there exists a -ready task of equal priority. - -@subsection Delays - -@cindex delays - -A sleep timer allows a task to delay for a given -interval or up until a given time, and then wake and continue -execution. This type of timer is created automatically by the -@code{@value{DIRPREFIX}task_wake_after} -and @code{@value{DIRPREFIX}task_wake_when} directives and, as a result, -does not have an RTEMS ID. Once activated, a sleep timer cannot -be explicitly deleted. Each task may activate one and only one -sleep timer at a time. - -@subsection Timeouts - -@cindex timeouts - -Timeouts are a special type of timer automatically -created when the timeout option is used on the -@code{@value{DIRPREFIX}message_queue_receive}, -@code{@value{DIRPREFIX}event_receive}, -@code{@value{DIRPREFIX}semaphore_obtain} and -@code{@value{DIRPREFIX}region_get_segment} directives. -Each task may have one and only one timeout active at a time. -When a timeout expires, it unblocks the task with a timeout status code. - -@section Operations - -@subsection Announcing a Tick - -RTEMS provides the @code{@value{DIRPREFIX}clock_tick} directive which is -called from the user's real-time clock ISR to inform RTEMS that -a tick has elapsed. The tick frequency value, defined in -microseconds, is a configuration parameter found in the -Configuration Table. RTEMS divides one million microseconds -(one second) by the number of microseconds per tick to determine -the number of calls to the -@code{@value{DIRPREFIX}clock_tick} directive per second. The -frequency of @code{@value{DIRPREFIX}clock_tick} -calls determines the resolution -(granularity) for all time dependent RTEMS actions. For -example, calling @code{@value{DIRPREFIX}clock_tick} -ten times per second yields a higher -resolution than calling @code{@value{DIRPREFIX}clock_tick} -two times per second. The @code{@value{DIRPREFIX}clock_tick} -directive is responsible for maintaining both -calendar time and the dynamic set of timers. - -@subsection Setting the Time - -The @code{@value{DIRPREFIX}clock_set} directive allows a task or an ISR to -set the date and time maintained by RTEMS. If setting the date -and time causes any outstanding timers to pass their deadline, -then the expired timers will be fired during the invocation of -the @code{@value{DIRPREFIX}clock_set} directive. - -@subsection Obtaining the Time - -The @code{@value{DIRPREFIX}clock_get} directive allows a task or an ISR to -obtain the current date and time or date and time related -information. The current date and time can be returned in -either native or UNIX-style format. Additionally, the -application can obtain date and time related information such as -the number of seconds since the RTEMS epoch, the number of ticks -since the executive was initialized, and the number of ticks per -second. The information returned by the -@code{@value{DIRPREFIX}clock_get} directive is -dependent on the option selected by the caller. This -is specified using one of the following constants -associated with the enumerated type -@code{@value{DIRPREFIX}clock_get_options}: - -@findex rtems_clock_get_options - -@itemize @bullet -@item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time - -@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - obtain UNIX-style -date and time - -@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - obtain number of ticks -since RTEMS was initialized - -@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - obtain number -of seconds since RTEMS epoch - -@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - obtain number of clock -ticks per second - -@end itemize - -Calendar time operations will return an error code if -invoked before the date and time have been set. - -@section Directives - -This section details the clock manager's directives. -A subsection is dedicated to each of this manager's directives -and describes the calling sequence, related constants, usage, -and status codes. - -@c -@c -@c -@page -@subsection CLOCK_SET - Set date and time - -@subheading CALLING SEQUENCE: - -@cindex set the time of day - -@ifset is-C -@findex rtems_clock_set -@example -rtems_status_code rtems_clock_set( - rtems_time_of_day *time_buffer -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Clock_Set ( - Time_Buffer : in RTEMS.Time_Of_Day; - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - date and time set successfully@* -@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL@* -@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day - -@subheading DESCRIPTION: - -This directive sets the system date and time. The -date, time, and ticks in the time_buffer @value{STRUCTURE} are all -range-checked, and an error is returned if any one is out of its -valid range. - -@subheading NOTES: - -Years before 1988 are invalid. - -The system date and time are based on the configured -tick rate (number of microseconds in a tick). - -Setting the time forward may cause a higher priority -task, blocked waiting on a specific time, to be made ready. In -this case, the calling task will be preempted after the next -clock tick. - -Re-initializing RTEMS causes the system date and time -to be reset to an uninitialized state. Another call to -@code{@value{DIRPREFIX}clock_set} is required to re-initialize -the system date and time to application specific specifications. - -@c -@c -@c -@page -@subsection CLOCK_GET - Get date and time information - -@cindex obtain the time of day - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get -@example -rtems_status_code rtems_clock_get( - rtems_clock_get_options option, - void *time_buffer -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Clock_Get ( - Option : in RTEMS.Clock_Get_Options; - Time_Buffer : in RTEMS.Address; - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@* -@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@* -@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL - -@subheading DESCRIPTION: - -This directive is deprecated. - -This directive obtains the system date and time. If -the caller is attempting to obtain the date and time (i.e. -option is set to either @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH}, -@code{@value{RPREFIX}CLOCK_GET_TOD}, or -@code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and the date and time -has not been set with a previous call to -@code{@value{DIRPREFIX}clock_set}, then the -@code{@value{RPREFIX}NOT_DEFINED} status code is returned. -The caller can always obtain the number of ticks per second (option is -@code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of -ticks since the executive was initialized option is -@code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT}). - -The @code{option} argument may taken on any value of the enumerated -type @code{rtems_clock_get_options}. The data type expected for -@code{time_buffer} is based on the value of @code{option} as -indicated below: - -@findex rtems_clock_get_options -@ifset is-C -@itemize @bullet -@item @code{@value{RPREFIX}CLOCK_GET_TOD} - (rtems_time_of_day *) - -@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - (rtems_interval *) - -@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - (rtems_interval *) - -@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - (rtems_interval *) - -@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - (struct timeval *) - -@end itemize -@end ifset - -@ifset is-Ada -@itemize @bullet -@item @code{@value{RPREFIX}Clock_Get_TOD} - Address of an variable of -type RTEMS.Time_Of_Day - -@item @code{@value{RPREFIX}Clock_Get_Seconds_Since_Epoch} - Address of an -variable of type RTEMS.Interval - -@item @code{@value{RPREFIX}Clock_Get_Ticks_Since_Boot} - Address of an -variable of type RTEMS.Interval - -@item @code{@value{RPREFIX}Clock_Get_Ticks_Per_Second} - Address of an -variable of type RTEMS.Interval - -@item @code{@value{RPREFIX}Clock_Get_Time_Value} - Address of an variable of -type RTEMS.Clock_Time_Value - -@end itemize -@end ifset - -@subheading NOTES: - -This directive is callable from an ISR. - -This directive will not cause the running task to be -preempted. Re-initializing RTEMS causes the system date and -time to be reset to an uninitialized state. Another call to -@code{@value{DIRPREFIX}clock_set} is required to re-initialize the -system date and time to application specific specifications. - -@c -@c -@c -@page -@subsection CLOCK_GET_TOD - Get date and time in TOD format - -@cindex obtain the time of day - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get_tod -@example -rtems_status_code rtems_clock_get_tod( - rtems_time_of_day *time_buffer -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Clock_Get_TOD ( - Time_Buffer : in RTEMS.Time_Of_Day; - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@* -@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@* -@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL - -@subheading DESCRIPTION: - -This directive obtains the system date and time. If the date and time -has not been set with a previous call to -@code{@value{DIRPREFIX}clock_set}, then the -@code{@value{RPREFIX}NOT_DEFINED} status code is returned. - -@subheading NOTES: - -This directive is callable from an ISR. - -This directive will not cause the running task to be -preempted. Re-initializing RTEMS causes the system date and -time to be reset to an uninitialized state. Another call to -@code{@value{DIRPREFIX}clock_set} is required to re-initialize the -system date and time to application specific specifications. - -@c -@c -@c -@page -@subsection CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format - -@cindex obtain the time of day - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get_tod_timeval -@example -rtems_status_code rtems_clock_get_tod( - struct timeval *time -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Clock_Get_TOD_Timeval ( - Time : in RTEMS.Timeval; - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@* -@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@* -@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time} is NULL - -@subheading DESCRIPTION: - -This directive obtains the system date and time in POSIX -@code{struct timeval} format. If the date and time -has not been set with a previous call to -@code{@value{DIRPREFIX}clock_set}, then the -@code{@value{RPREFIX}NOT_DEFINED} status code is returned. - -@subheading NOTES: - -This directive is callable from an ISR. - -This directive will not cause the running task to be -preempted. Re-initializing RTEMS causes the system date and -time to be reset to an uninitialized state. Another call to -@code{@value{DIRPREFIX}clock_set} is required to re-initialize the -system date and time to application specific specifications. - -@c -@c -@c -@page -@subsection CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch - -@cindex obtain seconds since epoch - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get_seconds_since_epoch -@example -rtems_status_code rtems_clock_get_seconds_since_epoch( - rtems_interval *the_interval -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Clock_Get_Seconds_Since_Epoch( - The_Interval : out RTEMS.Interval; - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@* -@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@* -@code{@value{RPREFIX}INVALID_ADDRESS} - @code{the_interval} is NULL - -@subheading DESCRIPTION: - -This directive returns the number of seconds since the RTEMS -epoch and the current system date and time. If the date and time -has not been set with a previous call to -@code{@value{DIRPREFIX}clock_set}, then the -@code{@value{RPREFIX}NOT_DEFINED} status code is returned. - -@subheading NOTES: - -This directive is callable from an ISR. - -This directive will not cause the running task to be -preempted. Re-initializing RTEMS causes the system date and -time to be reset to an uninitialized state. Another call to -@code{@value{DIRPREFIX}clock_set} is required to re-initialize the -system date and time to application specific specifications. - -@c -@c -@c -@page -@subsection CLOCK_GET_TICKS_PER_SECOND - Get ticks per second - -@cindex obtain seconds since epoch - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get_ticks_per_second -@example -rtems_interval rtems_clock_get_ticks_per_second(void); -@end example -@end ifset - -@ifset is-Ada -@example -function Clock_Get_Ticks_Per_Seconds -return RTEMS.Interval; -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -NONE - -@subheading DESCRIPTION: - -This directive returns the number of clock ticks per second. This -is strictly based upon the microseconds per clock tick that the -application has configured. - -@subheading NOTES: - -This directive is callable from an ISR. - -This directive will not cause the running task to be preempted. - -@c -@c -@c -@page -@subsection CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value - -@cindex obtain ticks since boot -@cindex get current ticks counter value - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get_ticks_since_boot -@example -rtems_interval rtems_clock_get_ticks_since_boot(void); -@end example -@end ifset - -@ifset is-Ada -@example -function Clock_Get_Ticks_Since_Boot -return RTEMS.Interval; -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -NONE - -@subheading DESCRIPTION: - -This directive returns the current tick counter value. With a 1ms clock tick, -this counter overflows after 50 days since boot. This is the historical -measure of uptime in an RTEMS system. The newer service -@code{@value{DIRPREFIX}clock_get_uptime} is another and potentially more -accurate way of obtaining similar information. - -@subheading NOTES: - -This directive is callable from an ISR. - -This directive will not cause the running task to be preempted. - -@c -@c -@c -@page -@subsection CLOCK_TICK_LATER - Get tick value in the future - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_tick_later -@example -rtems_interval rtems_clock_tick_later( - rtems_interval delta -); -@end example -@end ifset - -@subheading DESCRIPTION: - -Returns the ticks counter value delta ticks in the future. - -@subheading NOTES: - -This directive is callable from an ISR. - -This directive will not cause the running task to be preempted. - -@c -@c -@c -@page -@subsection CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_tick_later_usec -@example -rtems_interval rtems_clock_tick_later_usec( - rtems_interval delta_in_usec -); -@end example -@end ifset - -@subheading DESCRIPTION: - -Returns the ticks counter value at least delta microseconds in the future. - -@subheading NOTES: - -This directive is callable from an ISR. - -This directive will not cause the running task to be preempted. - -@c -@c -@c -@page -@subsection CLOCK_TICK_BEFORE - Is tick value is before a point in time - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_tick_before -@example -rtems_interval rtems_clock_tick_before( - rtems_interval tick -); -@end example -@end ifset - -@subheading DESCRIPTION: - -Returns true if the current ticks counter value indicates a time before the -time specified by the tick value and false otherwise. - -@subheading NOTES: - -This directive is callable from an ISR. - -This directive will not cause the running task to be preempted. - -@subheading EXAMPLE: - -@example -@group -status busy( void ) -@{ - rtems_interval timeout = rtems_clock_tick_later_usec( 10000 ); - - do @{ - if ( ok() ) @{ - return success; - @} - @} while ( rtems_clock_tick_before( timeout ) ); - - return timeout; -@} -@end group -@end example - -@c -@c -@c -@page -@subsection CLOCK_GET_UPTIME - Get the time since boot - -@cindex clock get uptime -@cindex uptime - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get_uptime -@example -rtems_status_code rtems_clock_get_uptime( - struct timespec *uptime -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Clock_Get_Uptime ( - Uptime : out RTEMS.Timespec; - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@* -@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL - -@subheading DESCRIPTION: - -This directive returns the seconds and nanoseconds since the -system was booted. If the BSP supports nanosecond clock -accuracy, the time reported will probably be different on every -call. - -@subheading NOTES: - -This directive may be called from an ISR. - -@c -@c -@c -@page -@subsection CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format - -@cindex clock get uptime -@cindex uptime - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get_uptime_timeval -@example -void rtems_clock_get_uptime_timeval( - struct timeval *uptime -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: - -NONE - -@subheading DESCRIPTION: - -This directive returns the seconds and microseconds since the -system was booted. If the BSP supports nanosecond clock -accuracy, the time reported will probably be different on every -call. - -@subheading NOTES: - -This directive may be called from an ISR. - -@c -@c -@c -@page -@subsection CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot - -@cindex clock get uptime -@cindex uptime - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get_uptime_seconds -@example -time_t rtems_clock_get_uptime_seconds(void); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: - -The system uptime in seconds. - -@subheading DESCRIPTION: - -This directive returns the seconds since the system was booted. - -@subheading NOTES: - -This directive may be called from an ISR. - -@c -@c -@c -@page -@subsection CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot - -@cindex clock get nanoseconds uptime -@cindex uptime - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_get_uptime_nanoseconds -@example -uint64_t rtems_clock_get_uptime_nanoseconds(void); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: - -The system uptime in nanoseconds. - -@subheading DESCRIPTION: - -This directive returns the nanoseconds since the system was booted. - -@subheading NOTES: - -This directive may be called from an ISR. - -@c -@c -@c -@page -@subsection CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler - -@cindex clock set nanoseconds extension -@cindex nanoseconds extension -@cindex nanoseconds time accuracy - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_set_nanoseconds_extension -@example -rtems_status_code rtems_clock_set_nanoseconds_extension( - rtems_nanoseconds_extension_routine routine -); -@end example -@end ifset - -@ifset is-Ada -@example -NOT SUPPORTED FROM Ada BINDING -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@* -@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL - -@subheading DESCRIPTION: - -This directive is used by the Clock device driver to install the -@code{routine} which will be invoked by the internal RTEMS method used to -obtain a highly accurate time of day. It is usually called during -the initialization of the driver. - -When the @code{routine} is invoked, it will determine the number of -nanoseconds which have elapsed since the last invocation of -the @code{@value{DIRPREFIX}clock_tick} directive. It should do -this as quickly as possible with as little impact as possible -on the device used as a clock source. - -@subheading NOTES: - -This directive may be called from an ISR. - -This directive is called as part of every service to obtain the -current date and time as well as timestamps. - -@c -@c -@c -@page -@subsection CLOCK_TICK - Announce a clock tick - -@cindex clock tick - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_clock_tick -@example -rtems_status_code rtems_clock_tick( void ); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Clock_Tick ( - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully - -@subheading DESCRIPTION: - -This directive announces to RTEMS that a system clock -tick has occurred. The directive is usually called from the -timer interrupt ISR of the local processor. This directive -maintains the system date and time, decrements timers for -delayed tasks, timeouts, rate monotonic periods, and implements -timeslicing. - -@subheading NOTES: - -This directive is typically called from an ISR. - -The @code{microseconds_per_tick} and @code{ticks_per_timeslice} -parameters in the Configuration Table contain the number of -microseconds per tick and number of ticks per timeslice, -respectively. |