[rtems-docs commit] Update due to clock manager and driver changes
sebh at rtems.org
Thu Nov 3 10:00:44 UTC 2016
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Nov 2 08:13:31 2016 +0100
Update due to clock manager and driver changes
c-user/board_support_packages.rst | 4 +-
c-user/clock_manager.rst | 112 +++++---------------------------------
c-user/configuring_a_system.rst | 2 +-
c-user/glossary.rst | 4 +-
c-user/interrupt_manager.rst | 5 +-
c-user/task_manager.rst | 2 +-
c-user/timer_manager.rst | 8 +--
7 files changed, 28 insertions(+), 109 deletions(-)
diff --git a/c-user/board_support_packages.rst b/c-user/board_support_packages.rst
index 872ff71..9a32036 100644
@@ -149,7 +149,7 @@ Clock Tick Device Driver
Most RTEMS applications will include a clock tick device driver which invokes
-the ``rtems_clock_tick`` directive at regular intervals. The clock tick is
+a clock tick directive at regular intervals. The clock tick is
necessary if the application is to utilize timeslicing, the clock manager, the
timer manager, the rate monotonic manager, or the timeout option on blocking
@@ -163,7 +163,7 @@ overhead required to manipulate the counter/timer in the clock tick ISR and
increases the accuracy of tick occurrences. The initial count can be based on
the microseconds_per_tick field in the RTEMS Configuration Table. An alternate
approach is to set the initial count for a fixed time period (such as one
-millisecond) and have the ISR invoke ``rtems_clock_tick`` on the configured
+millisecond) and have the ISR invoke a clock tick directive on the configured
``microseconds_per_tick`` boundaries. Obviously, this can induce some error if
the configured ``microseconds_per_tick`` is not evenly divisible by the chosen
clock interrupt quantum.
diff --git a/c-user/clock_manager.rst b/c-user/clock_manager.rst
index 559864f..cd9140c 100644
@@ -44,10 +44,6 @@ the clock manager are:
- 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
@@ -56,7 +52,7 @@ 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
+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
@@ -113,7 +109,7 @@ 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
+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.
@@ -145,17 +141,19 @@ 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.
+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
@@ -725,83 +723,3 @@ This directive returns the nanoseconds since the system was booted.
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
-.. 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:**
- clock tick processed successfully
- ``time_buffer`` is NULL
-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
-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.
-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
-.. index:: rtems_clock_tick
-.. code-block:: c
- rtems_status_code rtems_clock_tick( void );
-**DIRECTIVE STATUS CODES:**
- clock tick processed successfully
-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
-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.
diff --git a/c-user/configuring_a_system.rst b/c-user/configuring_a_system.rst
index e993877..55673b1 100644
@@ -4481,7 +4481,7 @@ wishes to include the Clock Device Driver.
This device driver is responsible for providing a regular interrupt which
-invokes the ``rtems_clock_tick`` directive.
+invokes a clock tick directive.
If neither the Clock Driver not Benchmark Timer is enabled and the
configuration parameter ``CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`` is
diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index e7fd794..0ec0d08 100644
@@ -673,8 +673,8 @@ Glossary
The basic unit of time used by RTEMS. It is a user-configurable number of
- microseconds. The current tick expires when the ``rtems_clock_tick``
- directive is invoked.
+ microseconds. The current tick expires when a clock tick directive is
A multiprocessor configuration system which communicates via shared memory.
diff --git a/c-user/interrupt_manager.rst b/c-user/interrupt_manager.rst
index f9a4648..0ee6a39 100644
@@ -195,8 +195,9 @@ is a list of RTEMS system calls that may be made from an ISR:
- - rtems_clock_set_nanoseconds_extension
- - rtems_clock_tick
+ - rtems_timecounter_tick
+ - rtems_timecounter_simple_downcounter_tick
+ - rtems_timecounter_simple_upcounter_tick
- Timer Management
diff --git a/c-user/task_manager.rst b/c-user/task_manager.rst
index 449ca3c..f88e660 100644
@@ -1384,7 +1384,7 @@ TASK_WAKE_AFTER - Wake up after interval
This directive blocks the calling task for the specified number of system clock
ticks. When the requested interval has elapsed, the task is made ready. The
-``rtems_clock_tick`` directive automatically updates the delay period.
+clock tick directives automatically updates the delay period.
diff --git a/c-user/timer_manager.rst b/c-user/timer_manager.rst
index 2b1f2f5..088c1b3 100644
@@ -48,10 +48,10 @@ Timers
A timer is an RTEMS object which allows the application to schedule operations
to occur at specific times in the future. User supplied timer service routines
-are invoked by either the ``rtems_clock_tick`` directive or a special Timer
+are invoked by either a clock tick directive or a special Timer
Server task when the timer fires. Timer service routines may perform any
operations or directives which normally would be performed by the application
-code which invoked the ``rtems_clock_tick`` directive.
+code which invoked a clock tick directive.
The timer can be used to implement watchdog routines which only fire to denote
that an application error has occurred. The timer is reset at specific points
@@ -129,7 +129,7 @@ Initiating an Interval Timer
The ``rtems_timer_fire_after`` and ``rtems_timer_server_fire_after`` directives
initiate a timer to fire a user provided timer service routine after the
specified number of clock ticks have elapsed. When the interval has elapsed,
-the timer service routine will be invoked from the ``rtems_clock_tick``
+the timer service routine will be invoked from a clock tick
directive if it was initiated by the ``rtems_timer_fire_after`` directive and
from the Timer Server task if initiated by the
@@ -140,7 +140,7 @@ Initiating a Time of Day Timer
The ``rtems_timer_fire_when`` and ``rtems_timer_server_fire_when`` directive
initiate a timer to fire a user provided timer service routine when the
specified time of day has been reached. When the interval has elapsed, the
-timer service routine will be invoked from the ``rtems_clock_tick`` directive
+timer service routine will be invoked from a clock tick directive
by the ``rtems_timer_fire_when`` directive and from the Timer Server task if
initiated by the ``rtems_timer_server_fire_when`` directive.
More information about the vc