From 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 3 Nov 2016 16:58:08 +1100 Subject: Rename all manuals with an _ to have a -. It helps released naming of files. --- c-user/clock_manager.rst | 807 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 807 insertions(+) create mode 100644 c-user/clock_manager.rst (limited to 'c-user/clock_manager.rst') diff --git a/c-user/clock_manager.rst b/c-user/clock_manager.rst new file mode 100644 index 0000000..559864f --- /dev/null +++ b/c-user/clock_manager.rst @@ -0,0 +1,807 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Clock Manager +############# + +.. index:: clock + +Introduction +============ + +The clock manager provides support for time of day +and other time related capabilities. The directives provided by +the clock manager are: + +- rtems_clock_set_ - Set date and time + +- rtems_clock_get_ - Get date and time information + +- rtems_clock_get_tod_ - Get date and time in TOD format + +- rtems_clock_get_tod_timeval_ - Get date and time in timeval format + +- rtems_clock_get_seconds_since_epoch_ - Get seconds since epoch + +- rtems_clock_get_ticks_per_second_ - Get ticks per second + +- rtems_clock_get_ticks_since_boot_ - Get current ticks counter value + +- rtems_clock_tick_later_ - Get tick value in the future + +- rtems_clock_tick_later_usec_ - Get tick value in the future in microseconds + +- rtems_clock_tick_before_ - Is tick value is before a point in time + +- rtems_clock_get_uptime_ - Get time since boot + +- rtems_clock_get_uptime_timeval_ - Get time since boot in timeval format + +- rtems_clock_get_uptime_seconds_ - Get seconds since boot + +- rtems_clock_get_uptime_nanoseconds_ - Get nanoseconds since boot + +- rtems_clock_set_nanoseconds_extension_ - Install the nanoseconds since last tick handler + +- rtems_clock_tick_ - Announce a clock tick + +Background +========== + +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 ``rtems_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. + +.. _Time and Date Data Structures: + +Time and Date Data Structures +----------------------------- + +The clock facilities of the clock manager operate upon calendar time. These +directives utilize the following date and time structure for the native time +and date format: + +.. index:: rtems_time_of_day + +.. code-block:: c + + 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; + +The native date and time format is the only format supported when setting the +system date and time using the ``rtems_clock_set`` directive. Some +applications expect to operate on a *UNIX-style* date and time data structure. +The ``rtems_clock_get_tod_timeval`` always returns the date and time in +``struct timeval`` format. The ``rtems_clock_get`` directive can optionally +return the current date and time in this format. + +The ``struct timeval`` data structure has two fields: ``tv_sec`` and +``tv_usec`` which are seconds and microseconds, respectively. The ``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*. + +Clock Tick and Timeslicing +-------------------------- +.. index:: 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 ``rtems_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. + +Delays +------ +.. index:: 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 ``rtems_task_wake_after`` and ``rtems_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. + +Timeouts +-------- +.. index:: timeouts + +Timeouts are a special type of timer automatically created when the timeout +option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``, +``rtems_semaphore_obtain`` and ``rtems_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. + +Operations +========== + +Announcing a Tick +----------------- + +RTEMS provides the ``rtems_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 +``rtems_clock_tick`` directive per second. The frequency of +``rtems_clock_tick`` calls determines the resolution (granularity) for all time +dependent RTEMS actions. For example, calling ``rtems_clock_tick`` ten times +per second yields a higher resolution than calling ``rtems_clock_tick`` two +times per second. The ``rtems_clock_tick`` directive is responsible for +maintaining both calendar time and the dynamic set of timers. + +Setting the Time +---------------- + +The ``rtems_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 ``rtems_clock_set`` directive. + +Obtaining the Time +------------------ + +The ``rtems_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 ``rtems_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 ``rtems_clock_get_options``: + +.. index:: rtems_clock_get_options + +``RTEMS_CLOCK_GET_TOD`` + obtain native style date and time + +``RTEMS_CLOCK_GET_TIME_VALUE`` + obtain *UNIX-style* date and time + +``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` + obtain number of ticks since RTEMS was initialized + +``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` + obtain number of seconds since RTEMS epoch + +``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` + obtain number of clock ticks per second + +Calendar time operations will return an error code if invoked before the date +and time have been set. + +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. + +.. _rtems_clock_set: + +CLOCK_SET - Set date and time +----------------------------- + +**CALLING SEQUENCE:** + +.. index:: set the time of day + +.. index:: rtems_clock_set + +.. code-block:: c + + rtems_status_code rtems_clock_set( + rtems_time_of_day *time_buffer + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` + date and time set successfully + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL + +``RTEMS_INVALID_CLOCK`` + invalid time of day + +**DESCRIPTION:** + +This directive sets the system date and time. The date, time, and ticks in the +time_buffer structure are all range-checked, and an error is returned if any +one is out of its valid range. + +**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 ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. + +.. _rtems_clock_get: + +CLOCK_GET - Get date and time information +----------------------------------------- +.. index:: obtain the time of day + +.. warning:: + + This directive is deprecated and will be removed. + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get + +.. code-block:: c + + rtems_status_code rtems_clock_get( + rtems_clock_get_options option, + void *time_buffer + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` + current time obtained successfully + +``RTEMS_NOT_DEFINED`` + system date and time is not set + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL + +**DESCRIPTION:** + +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 +``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or +``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with a +previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status +code is returned. The caller can always obtain the number of ticks per second +(option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number of ticks since +the executive was initialized option is ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``). + +The ``option`` argument may taken on any value of the enumerated type +``rtems_clock_get_options``. The data type expected for ``time_buffer`` is +based on the value of ``option`` as indicated below: + +.. index:: rtems_clock_get_options + ++-----------------------------------------+---------------------------+ +| Option | Return type | ++=========================================+===========================+ +| ``RTEMS_CLOCK_GET_TOD`` | ``(rtems_time_of_day *)`` | ++-----------------------------------------+---------------------------+ +| ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)`` | ++-----------------------------------------+---------------------------+ +| ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` | ``(rtems_interval *)`` | ++-----------------------------------------+---------------------------+ +|``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` | ``(rtems_interval *)`` | ++-----------------------------------------+---------------------------+ +| ``RTEMS_CLOCK_GET_TIME_VALUE`` | ``(struct timeval *)`` | ++-----------------------------------------+---------------------------+ + +**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 ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. + +.. _rtems_clock_get_tod: + +CLOCK_GET_TOD - Get date and time in TOD format +----------------------------------------------- +.. index:: obtain the time of day + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_tod + +.. code-block:: c + + rtems_status_code rtems_clock_get_tod( + rtems_time_of_day *time_buffer + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` + current time obtained successfully + +``RTEMS_NOT_DEFINED`` + system date and time is not set + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL + +**DESCRIPTION:** + +This directive obtains the system date and time. If the date and time has not +been set with a previous call to ``rtems_clock_set``, then the +``RTEMS_NOT_DEFINED`` status code is returned. + +**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 ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. + +.. _rtems_clock_get_tod_timeval: + +CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format +----------------------------------------------------------- +.. index:: obtain the time of day + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_tod_timeval + +.. code-block:: c + + rtems_status_code rtems_clock_get_tod_interval( + struct timeval *time + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` + current time obtained successfully + +``RTEMS_NOT_DEFINED`` + system date and time is not set + +``RTEMS_INVALID_ADDRESS`` + ``time`` is NULL + +**DESCRIPTION:** + +This directive obtains the system date and time in POSIX ``struct timeval`` +format. If the date and time has not been set with a previous call to +``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status code is returned. + +**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 ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. + +.. _rtems_clock_get_seconds_since_epoch: + +CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch +------------------------------------------------------- +.. index:: obtain seconds since epoch + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_seconds_since_epoch + +.. code-block:: c + + rtems_status_code rtems_clock_get_seconds_since_epoch( + rtems_interval *the_interval + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` + current time obtained successfully + +``RTEMS_NOT_DEFINED`` + system date and time is not set + +``RTEMS_INVALID_ADDRESS`` + ``the_interval`` is NULL + +**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 ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status +code is returned. + +**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 ``rtems_clock_set`` is required to +re-initialize the system date and time to application specific specifications. + +.. _rtems_clock_get_ticks_per_second: + +CLOCK_GET_TICKS_PER_SECOND - Get ticks per second +------------------------------------------------- +.. index:: obtain seconds since epoch + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_ticks_per_second + +.. code-block:: c + + rtems_interval rtems_clock_get_ticks_per_second(void); + +**DIRECTIVE STATUS CODES:** + +NONE + +**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. + +**NOTES:** + +This directive is callable from an ISR. + +This directive will not cause the running task to be preempted. + +.. _rtems_clock_get_ticks_since_boot: + +CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value +------------------------------------------------------------ +.. index:: obtain ticks since boot +.. index:: get current ticks counter value + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_ticks_since_boot + +.. code-block:: c + + rtems_interval rtems_clock_get_ticks_since_boot(void); + +**DIRECTIVE STATUS CODES:** + +NONE + +**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 +``rtems_clock_get_uptime`` is another and potentially more accurate way of +obtaining similar information. + +**NOTES:** + +This directive is callable from an ISR. + +This directive will not cause the running task to be preempted. + +.. _rtems_clock_tick_later: + +CLOCK_TICK_LATER - Get tick value in the future +----------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_tick_later + +.. code-block:: c + + rtems_interval rtems_clock_tick_later( + rtems_interval delta + ); + +**DESCRIPTION:** + +Returns the ticks counter value delta ticks in the future. + +**NOTES:** + +This directive is callable from an ISR. + +This directive will not cause the running task to be preempted. + +.. _rtems_clock_tick_later_usec: + +CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds +-------------------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_tick_later_usec + +.. code-block:: c + + rtems_interval rtems_clock_tick_later_usec( + rtems_interval delta_in_usec + ); + +**DESCRIPTION:** + +Returns the ticks counter value at least delta microseconds in the future. + +**NOTES:** + +This directive is callable from an ISR. + +This directive will not cause the running task to be preempted. + +.. _rtems_clock_tick_before: + +CLOCK_TICK_BEFORE - Is tick value is before a point in time +----------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_tick_before + +.. code-block:: c + + rtems_interval rtems_clock_tick_before( + rtems_interval tick + ); + +**DESCRIPTION:** + +Returns true if the current ticks counter value indicates a time before the +time specified by the tick value and false otherwise. + +**NOTES:** + +This directive is callable from an ISR. + +This directive will not cause the running task to be preempted. + +**EXAMPLE:** + +.. code-block:: c + + 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; + } + +.. _rtems_clock_get_uptime: + +CLOCK_GET_UPTIME - Get the time since boot +------------------------------------------ +.. index:: clock get uptime +.. index:: uptime + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_uptime + +.. code-block:: c + + rtems_status_code rtems_clock_get_uptime( + struct timespec *uptime + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` + clock tick processed successfully + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL + +**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. + +**NOTES:** + +This directive may be called from an ISR. + +.. _rtems_clock_get_uptime_timeval: + +CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format +-------------------------------------------------------------------- +.. index:: clock get uptime interval +.. index:: uptime + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_uptime_timeval + +.. code-block:: c + + void rtems_clock_get_uptime_timeval( + struct timeval *uptime + ); + +**DIRECTIVE STATUS CODES:** + +NONE + +**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. + +**NOTES:** + +This directive may be called from an ISR. + +.. _rtems_clock_get_uptime_seconds: + +CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot +----------------------------------------------------- +.. index:: clock get uptime seconds +.. index:: uptime + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_uptime_seconds + +.. code-block:: c + + time_t rtems_clock_get_uptime_seconds(void); + +**DIRECTIVE STATUS CODES:** + +The system uptime in seconds. + +**DESCRIPTION:** + +This directive returns the seconds since the system was booted. + +**NOTES:** + +This directive may be called from an ISR. + +.. _rtems_clock_get_uptime_nanoseconds: + +CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot +------------------------------------------------------------- +.. index:: clock get nanoseconds uptime +.. index:: uptime + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_uptime_nanoseconds + +.. code-block:: c + + uint64_t rtems_clock_get_uptime_nanoseconds(void); + +**DIRECTIVE STATUS CODES:** + +The system uptime in nanoseconds. + +**DESCRIPTION:** + +This directive returns the nanoseconds since the system was booted. + +**NOTES:** + +This directive may be called from an ISR. + +.. _rtems_clock_set_nanoseconds_extension: + +CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler +--------------------------------------------------------------------------------- +.. index:: clock set nanoseconds extension +.. index:: nanoseconds extension +.. index:: nanoseconds time accuracy + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_set_nanoseconds_extension + +.. code-block:: c + + rtems_status_code rtems_clock_set_nanoseconds_extension( + rtems_nanoseconds_extension_routine routine + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` + clock tick processed successfully + +``RTEMS_INVALID_ADDRESS`` + ``time_buffer`` is NULL + +**DESCRIPTION:** + +This directive is used by the Clock device driver to install the ``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 ``routine`` is invoked, it will determine the number of nanoseconds +which have elapsed since the last invocation of the ``rtems_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. + +**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. + +.. _rtems_clock_tick: + +CLOCK_TICK - Announce a clock tick +---------------------------------- +.. index:: clock tick + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_tick + +.. code-block:: c + + rtems_status_code rtems_clock_tick( void ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` + clock tick processed successfully + +**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. + +**NOTES:** + +This directive is typically called from an ISR. + +The ``microseconds_per_tick`` and ``ticks_per_timeslice`` parameters in the +Configuration Table contain the number of microseconds per tick and number of +ticks per timeslice, respectively. -- cgit v1.2.3