[PATCH v2 04/16] c-user: Split up clock manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:00:58 UTC 2020
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/clock/background.rst | 96 +++++++
.../directives.rst} | 238 ++----------------
c-user/clock/index.rst | 15 ++
c-user/clock/introduction.rst | 36 +++
c-user/clock/operations.rst | 78 ++++++
c-user/index.rst | 2 +-
6 files changed, 242 insertions(+), 223 deletions(-)
create mode 100644 c-user/clock/background.rst
rename c-user/{clock_manager.rst => clock/directives.rst} (65%)
create mode 100644 c-user/clock/index.rst
create mode 100644 c-user/clock/introduction.rst
create mode 100644 c-user/clock/operations.rst
diff --git a/c-user/clock/background.rst b/c-user/clock/background.rst
new file mode 100644
index 0000000..64e8311
--- /dev/null
+++ b/c-user/clock/background.rst
@@ -0,0 +1,96 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+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 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 ``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*.
+
+.. index:: timeslicing
+
+Clock Tick and 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 clock tick directives implement 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.
+
+.. index:: delays
+
+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.
+
+.. index:: timeouts
+
+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.
diff --git a/c-user/clock_manager.rst b/c-user/clock/directives.rst
similarity index 65%
rename from c-user/clock_manager.rst
rename to c-user/clock/directives.rst
index c825d7b..06fe38b 100644
--- a/c-user/clock_manager.rst
+++ b/c-user/clock/directives.rst
@@ -2,212 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: clock
-
-Clock Manager
-*************
-
-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_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
-
-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 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 ``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*.
-
-.. index:: timeslicing
-
-Clock Tick and 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 clock tick directives implement 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.
-
-.. index:: delays
-
-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.
-
-.. index:: timeouts
-
-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 several clock tick directives which are called from the
-user's real-time clock ISR to inform RTEMS that a tick has elapsed. Depending
-on the timer hardware capabilities the clock driver must choose the most
-appropriate clock tick directive. 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 clock tick
-directive per second. The frequency of clock tick calls determines the
-resolution (granularity) for all time dependent RTEMS actions. For example,
-calling the clock tick directive ten times per second yields a higher
-resolution than calling the clock tick two times per second. The clock tick
-directives are 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
-------------------
-
-RTEMS provides multiple directives which can be used by an application to obtain the current date and time or date and time related information. These directives allow 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 following directives are available:
-
-``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.
-
-.. _ClockManagerAdviceClockGet:
-
-Transition Advice for the Removed rtems_clock_get()
----------------------------------------------------
-
-The directive :ref:`rtems_clock_get` took an untyped pointer with an options
-argument to indicate the time information desired. This has been replaced with
-a set of typed directives:
-
-* :ref:`rtems_clock_get_seconds_since_epoch`
-
-* :ref:`rtems_clock_get_ticks_per_second`
-
-* :ref:`rtems_clock_get_ticks_since_boot`
-
-* :ref:`rtems_clock_get_tod`
-
-* :ref:`rtems_clock_get_tod_timeval`
-
-These directives directly correspond to what were previously referred to as
-*clock options*. These strongly typed directives were available for multiple
-releases in parallel with :c:func:`rtems_clock_get` until that directive was
-removed.
-
Directives
==========
@@ -219,11 +13,11 @@ related constants, usage, and status codes.
\clearpage
-.. _rtems_clock_set:
-
.. index:: set the time of day
.. index:: rtems_clock_set
+.. _rtems_clock_set:
+
CLOCK_SET - Set date and time
-----------------------------
@@ -466,10 +260,10 @@ NOTES:
\clearpage
-.. _rtems_clock_tick_later:
-
.. index:: rtems_clock_tick_later
+.. _rtems_clock_tick_later:
+
CLOCK_TICK_LATER - Get tick value in the future
-----------------------------------------------
@@ -492,10 +286,10 @@ NOTES:
\clearpage
-.. _rtems_clock_tick_later_usec:
-
.. index:: rtems_clock_tick_later_usec
+.. _rtems_clock_tick_later_usec:
+
CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
--------------------------------------------------------------------
@@ -518,10 +312,10 @@ NOTES:
\clearpage
-.. _rtems_clock_tick_before:
-
.. index:: rtems_clock_tick_before
+.. _rtems_clock_tick_before:
+
CLOCK_TICK_BEFORE - Is tick value is before a point in time
-----------------------------------------------------------
@@ -559,12 +353,12 @@ EXAMPLE:
\clearpage
-.. _rtems_clock_get_uptime:
-
.. index:: clock get uptime
.. index:: uptime
.. index:: rtems_clock_get_uptime
+.. _rtems_clock_get_uptime:
+
CLOCK_GET_UPTIME - Get the time since boot
------------------------------------------
@@ -595,12 +389,12 @@ NOTES:
\clearpage
-.. _rtems_clock_get_uptime_timeval:
-
.. index:: clock get uptime interval
.. index:: uptime
.. index:: rtems_clock_get_uptime_timeval
+.. _rtems_clock_get_uptime_timeval:
+
CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
--------------------------------------------------------------------
@@ -626,12 +420,12 @@ NOTES:
\clearpage
-.. _rtems_clock_get_uptime_seconds:
-
.. index:: clock get uptime seconds
.. index:: uptime
.. index:: rtems_clock_get_uptime_seconds
+.. _rtems_clock_get_uptime_seconds:
+
CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
-----------------------------------------------------
@@ -653,12 +447,12 @@ NOTES:
\clearpage
-.. _rtems_clock_get_uptime_nanoseconds:
-
.. index:: clock get nanoseconds uptime
.. index:: uptime
.. index:: rtems_clock_get_uptime_nanoseconds
+.. _rtems_clock_get_uptime_nanoseconds:
+
CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
-------------------------------------------------------------
diff --git a/c-user/clock/index.rst b/c-user/clock/index.rst
new file mode 100644
index 0000000..010299f
--- /dev/null
+++ b/c-user/clock/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: clock
+
+Clock Manager
+*************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/clock/introduction.rst b/c-user/clock/introduction.rst
new file mode 100644
index 0000000..e952d7d
--- /dev/null
+++ b/c-user/clock/introduction.rst
@@ -0,0 +1,36 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+The clock manager provides support for time of day
+and other time related capabilities. The directives provided by
+the clock manager are:
+
+- :ref:`rtems_clock_set`
+
+- :ref:`rtems_clock_get_tod`
+
+- :ref:`rtems_clock_get_tod_timeval`
+
+- :ref:`rtems_clock_get_seconds_since_epoch`
+
+- :ref:`rtems_clock_get_ticks_per_second`
+
+- :ref:`rtems_clock_get_ticks_since_boot`
+
+- :ref:`rtems_clock_tick_later`
+
+- :ref:`rtems_clock_tick_later_usec`
+
+- :ref:`rtems_clock_tick_before`
+
+- :ref:`rtems_clock_get_uptime`
+
+- :ref:`rtems_clock_get_uptime_timeval`
+
+- :ref:`rtems_clock_get_uptime_seconds`
+
+- :ref:`rtems_clock_get_uptime_nanoseconds`
diff --git a/c-user/clock/operations.rst b/c-user/clock/operations.rst
new file mode 100644
index 0000000..c4dd0a6
--- /dev/null
+++ b/c-user/clock/operations.rst
@@ -0,0 +1,78 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Announcing a Tick
+-----------------
+
+RTEMS provides the several clock tick directives which are called from the
+user's real-time clock ISR to inform RTEMS that a tick has elapsed. Depending
+on the timer hardware capabilities the clock driver must choose the most
+appropriate clock tick directive. 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 clock tick
+directive per second. The frequency of clock tick calls determines the
+resolution (granularity) for all time dependent RTEMS actions. For example,
+calling the clock tick directive ten times per second yields a higher
+resolution than calling the clock tick two times per second. The clock tick
+directives are 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
+------------------
+
+RTEMS provides multiple directives which can be used by an application to obtain the current date and time or date and time related information. These directives allow 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 following directives are available:
+
+``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.
+
+.. _ClockManagerAdviceClockGet:
+
+Transition Advice for the Removed rtems_clock_get()
+---------------------------------------------------
+
+The directive :ref:`rtems_clock_get` took an untyped pointer with an options
+argument to indicate the time information desired. This has been replaced with
+a set of typed directives:
+
+* :ref:`rtems_clock_get_seconds_since_epoch`
+
+* :ref:`rtems_clock_get_ticks_per_second`
+
+* :ref:`rtems_clock_get_ticks_since_boot`
+
+* :ref:`rtems_clock_get_tod`
+
+* :ref:`rtems_clock_get_tod_timeval`
+
+These directives directly correspond to what were previously referred to as
+*clock options*. These strongly typed directives were available for multiple
+releases in parallel with :c:func:`rtems_clock_get` until that directive was
+removed.
diff --git a/c-user/index.rst b/c-user/index.rst
index 39c356a..f4922da 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -32,7 +32,7 @@ RTEMS Classic API Guide (|version|).
initialization
task_manager
interrupt_manager
- clock_manager
+ clock/index
timer_manager
rate_monotonic_manager
semaphore/index
--
2.26.2
More information about the devel
mailing list