Commit 9c1efe6b authored by Anas Nashif's avatar Anas Nashif
Browse files

clock: remove z_ from semi-public APIs



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: default avatarAnas Nashif <anas.nashif@intel.com>
parent f943a558
Loading
Loading
Loading
Loading
+4 −4
Original line number Diff line number Diff line
@@ -157,10 +157,10 @@ void timer0_nrf_isr(void *arg)
		set_absolute_ticks(last_count + CYC_PER_TICK);
	}

	z_clock_announce(IS_ENABLED(CONFIG_TICKLESS_KERNEL) ? dticks : (dticks > 0));
	sys_clock_announce(IS_ENABLED(CONFIG_TICKLESS_KERNEL) ? dticks : (dticks > 0));
}

int z_clock_driver_init(const struct device *device)
int sys_clock_driver_init(const struct device *device)
{
	ARG_UNUSED(device);

@@ -185,7 +185,7 @@ int z_clock_driver_init(const struct device *device)
	return 0;
}

void z_clock_set_timeout(int32_t ticks, bool idle)
void sys_clock_set_timeout(int32_t ticks, bool idle)
{
	ARG_UNUSED(idle);
	uint32_t cyc;
@@ -234,7 +234,7 @@ void z_clock_set_timeout(int32_t ticks, bool idle)
	NVIC_ClearPendingIRQ(TIMER0_IRQn);
}

uint32_t z_clock_elapsed(void)
uint32_t sys_clock_elapsed(void)
{
	if (!IS_ENABLED(CONFIG_TICKLESS_KERNEL)) {
		return 0;
+10 −10
Original line number Diff line number Diff line
@@ -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.

+2 −2
Original line number Diff line number Diff line
@@ -346,9 +346,9 @@ config TICKLESS_CAPABLE
	help
	  Timer drivers should select this flag if they are capable of
	  supporting tickless operation.  That is, a call to
	  z_clock_set_timeout() with a number of ticks greater than
	  sys_clock_set_timeout() with a number of ticks greater than
	  one should be expected not to produce a call to
	  z_clock_announce() (really, not to produce an interrupt at
	  sys_clock_announce() (really, not to produce an interrupt at
	  all) until the specified expiration.

endmenu
+2 −2
Original line number Diff line number Diff line
@@ -28,10 +28,10 @@ static void timer_irq_handler(const void *unused)
	/* Clear the interrupt */
	alt_handle_irq((void *)TIMER_0_BASE, TIMER_0_IRQ);

	z_clock_announce(_sys_idle_elapsed_ticks);
	sys_clock_announce(_sys_idle_elapsed_ticks);
}

int z_clock_driver_init(const struct device *device)
int sys_clock_driver_init(const struct device *device)
{
	ARG_UNUSED(device);

+8 −8
Original line number Diff line number Diff line
@@ -76,9 +76,9 @@ static uint32_t cached_icr = CYCLES_PER_TICK;

#ifdef CONFIG_TICKLESS_KERNEL

static uint64_t last_announcement;	/* last time we called z_clock_announce() */
static uint64_t last_announcement;	/* last time we called sys_clock_announce() */

void z_clock_set_timeout(int32_t n, bool idle)
void sys_clock_set_timeout(int32_t n, bool idle)
{
	ARG_UNUSED(idle);

@@ -117,7 +117,7 @@ void z_clock_set_timeout(int32_t n, bool idle)
	k_spin_unlock(&lock, key);
}

uint32_t z_clock_elapsed(void)
uint32_t sys_clock_elapsed(void)
{
	uint32_t ccr;
	uint32_t ticks;
@@ -143,7 +143,7 @@ static void isr(const void *arg)

	/*
	 * If we get here and the CCR isn't zero, then this interrupt is
	 * stale: it was queued while z_clock_set_timeout() was setting
	 * stale: it was queued while sys_clock_set_timeout() was setting
	 * a new counter. Just ignore it. See above for more info.
	 */

@@ -161,7 +161,7 @@ static void isr(const void *arg)
	ticks = (total_cycles - last_announcement) / CYCLES_PER_TICK;
	last_announcement = total_cycles;
	k_spin_unlock(&lock, key);
	z_clock_announce(ticks);
	sys_clock_announce(ticks);
}

#else
@@ -175,10 +175,10 @@ static void isr(const void *arg)
	x86_write_loapic(LOAPIC_TIMER_ICR, cached_icr);
	k_spin_unlock(&lock, key);

	z_clock_announce(1);
	sys_clock_announce(1);
}

uint32_t z_clock_elapsed(void)
uint32_t sys_clock_elapsed(void)
{
	return 0U;
}
@@ -213,7 +213,7 @@ uint32_t z_timer_cycle_get_32(void)

#endif

int z_clock_driver_init(const struct device *device)
int sys_clock_driver_init(const struct device *device)
{
	uint32_t val;

Loading