michaelh/zephyr
1
0
Fork 0
Code Releases Activity

clock: remove z_ from semi-public APIs

Browse source 
The clock/timer APIs are not application facing APIs, however, similar
to arch_ and a few other APIs they are available to implement drivers
and add support for new hardware and are documented and available to be
used outside of the clock/kernel subsystems.

Remove the leading z_ and provide them as clock_* APIs for someone
writing a new timer driver to use.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2021-02-25 15:33:15 -05:00
commit 9c1efe6b4b
33 changed files with 171 additions and 168 deletions
Download patch file Download diff file Expand all files Collapse all files

20
doc/reference/kernel/timing/clocks.rst
View file

@ -155,7 +155,7 @@ Kernel timing at the tick level is driven by a timer driver with a
comparatively simple API.
* The driver is expected to be able to "announce" new ticks to the
kernel via the ``z_clock_announce()`` call, which passes an integer
kernel via the ``sys_clock_announce()`` call, which passes an integer
number of ticks that have elapsed since the last announce call (or
system boot). These calls can occur at any time, but the driver is
expected to attempt to ensure (to the extent practical given
@ -164,7 +164,7 @@ comparatively simple API.
be correct over time and subject to minimal skew vs. other counters
and real world time.
* The driver is expected to provide a ``z_clock_set_timeout()`` call
* The driver is expected to provide a ``sys_clock_set_timeout()`` call
to the kernel which indicates how many ticks may elapse before the
kernel must receive an announce call to trigger registered timeouts.
It is legal to announce new ticks before that moment (though they
@ -175,10 +175,10 @@ comparatively simple API.
implementations of this function are subject to bugs where the
fractional tick gets "reset" incorrectly and causes clock skew.
* The driver is expected to provide a ``z_clock_elapsed()`` call which
* The driver is expected to provide a ``sys_clock_elapsed()`` call which
provides a current indication of how many ticks have elapsed (as
compared to a real world clock) since the last call to
``z_clock_announce()``, which the kernel needs to test newly
``sys_clock_announce()``, which the kernel needs to test newly
arriving timeouts for expiration.
Note that a natural implementation of this API results in a "tickless"
@ -191,10 +191,10 @@ counter driver can be trivially implemented also:
the OS tick rate, calling z_clock_anounce() with an argument of one
each time.
* The driver can ignore calls to ``z_clock_set_timeout()``, as every
* The driver can ignore calls to ``sys_clock_set_timeout()``, as every
tick will be announced regardless of timeout status.
* The driver can return zero for every call to ``z_clock_elapsed()``
* The driver can return zero for every call to ``sys_clock_elapsed()``
as no more than one tick can be detected as having elapsed (because
otherwise an interrupt would have been received).
@ -211,7 +211,7 @@ and minimal. But some notes are important to detail:
have every timer interrupt handled on a single processor. Existing
SMP architectures implement symmetric timer drivers.
* The ``z_clock_announce()`` call is expected to be globally
* The ``sys_clock_announce()`` call is expected to be globally
synchronized at the driver level. The kernel does not do any
per-CPU tracking, and expects that if two timer interrupts fire near
simultaneously, that only one will provide the current tick count to
@ -225,10 +225,10 @@ and minimal. But some notes are important to detail:
driver, not the kernel.
* The next timeout value passed back to the driver via
:c:func:`z_clock_set_timeout` is done identically for every CPU.
:c:func:`sys_clock_set_timeout` is done identically for every CPU.
So by default, every CPU will see simultaneous timer interrupts for
every event, even though by definition only one of them should see a
non-zero ticks argument to ``z_clock_announce()``. This is probably
non-zero ticks argument to ``sys_clock_announce()``. This is probably
a correct default for timing sensitive applications (because it
minimizes the chance that an errant ISR or interrupt lock will delay
a timeout), but may be a performance problem in some cases. The
@ -246,7 +246,7 @@ tracked independently on each CPU in an SMP context.
Because there may be no other hardware available to drive timeslicing,
Zephyr multiplexes the existing timer driver. This means that the
value passed to :c:func:`z_clock_set_timeout` may be clamped to a
value passed to :c:func:`sys_clock_set_timeout` may be clamped to a
smaller value than the current next timeout when a time sliced thread
is currently scheduled.