From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/clock_manager.rst | 746 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 746 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..900ddd0 --- /dev/null +++ b/c_user/clock_manager.rst @@ -0,0 +1,746 @@ +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 +----------------------------- + +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:: 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. + +CLOCK_SET - Set date and time +----------------------------- + +**CALLING SEQUENCE:** + +.. index:: set the time of day + +.. index:: rtems_clock_set + +.. code:: 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. + +CLOCK_GET - Get date and time information +----------------------------------------- +.. index:: obtain the time of day + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get + +.. code:: 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 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 ``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 + +- ``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. + +CLOCK_GET_TOD - Get date and time in TOD format +----------------------------------------------- +.. index:: obtain the time of day + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_tod + +.. code:: 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. + +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:: c + + rtems_status_code rtems_clock_get_tod( + 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. + +CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch +------------------------------------------------------- +.. index:: obtain seconds since epoch + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_seconds_since_epoch + +.. code:: 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. + +CLOCK_GET_TICKS_PER_SECOND - Get ticks per second +------------------------------------------------- +.. index:: obtain seconds since epoch + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_ticks_per_second + +.. code:: 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. + +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:: 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. + +CLOCK_TICK_LATER - Get tick value in the future +----------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_tick_later + +.. code:: 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. + +CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds +-------------------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_tick_later_usec + +.. code:: 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. + +CLOCK_TICK_BEFORE - Is tick value is before a point in time +----------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_tick_before + +.. code:: 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:: 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; + } + +CLOCK_GET_UPTIME - Get the time since boot +------------------------------------------ +.. index:: clock get uptime +.. index:: uptime + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_uptime + +.. code:: 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. + +CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format +-------------------------------------------------------------------- +.. index:: clock get uptime +.. index:: uptime + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_uptime_timeval + +.. code:: 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. + +CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot +----------------------------------------------------- +.. index:: clock get uptime +.. index:: uptime + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_get_uptime_seconds + +.. code:: 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. + +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:: 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. + +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:: 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. + +CLOCK_TICK - Announce a clock tick +---------------------------------- +.. index:: clock tick + +**CALLING SEQUENCE:** + +.. index:: rtems_clock_tick + +.. code:: 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. + +.. COMMENT: COPYRIGHT (c) 1988-2008. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + -- cgit v1.2.3