zephyr

History

Andy Ross 7832738ae9 kernel/timeout: Make timeout arguments an opaque type Add a k_timeout_t type, and use it everywhere that kernel API functions were accepting a millisecond timeout argument. Instead of forcing milliseconds everywhere (which are often not integrally representable as system ticks), do the conversion to ticks at the point where the timeout is created. This avoids an extra unit conversion in some application code, and allows us to express the timeout in units other than milliseconds to achieve greater precision. The existing K_MSEC() et. al. macros now return initializers for a k_timeout_t. The K_NO_WAIT and K_FOREVER constants have now become k_timeout_t values, which means they cannot be operated on as integers. Applications which have their own APIs that need to inspect these vs. user-provided timeouts can now use a K_TIMEOUT_EQ() predicate to test for equality. Timer drivers, which receive an integer tick count in ther z_clock_set_timeout() functions, now use the integer-valued K_TICKS_FOREVER constant instead of K_FOREVER. For the initial release, to preserve source compatibility, a CONFIG_LEGACY_TIMEOUT_API kconfig is provided. When true, the k_timeout_t will remain a compatible 32 bit value that will work with any legacy Zephyr application. Some subsystems present timeout (or timeout-like) values to their own users as APIs that would re-use the kernel's own constants and conventions. These will require some minor design work to adapt to the new scheme (in most cases just using k_timeout_t directly in their own API), and they have not been changed in this patch, instead selecting CONFIG_LEGACY_TIMEOUT_API via kconfig. These subsystems include: CAN Bus, the Microbit display driver, I2S, LoRa modem drivers, the UART Async API, Video hardware drivers, the console subsystem, and the network buffer abstraction. k_sleep() now takes a k_timeout_t argument, with a k_msleep() variant provided that works identically to the original API. Most of the changes here are just type/configuration management and documentation, but there are logic changes in mempool, where a loop that used a timeout numerically has been reworked using a new z_timeout_end_calc() predicate. Also in queue.c, a (when POLL was enabled) a similar loop was needlessly used to try to retry the k_poll() call after a spurious failure. But k_poll() does not fail spuriously, so the loop was removed. Signed-off-by: Andy Ross <andrew.j.ross@intel.com>		2020-03-31 19:40:47 -04:00
..
src	kernel/timeout: Make timeout arguments an opaque type	2020-03-31 19:40:47 -04:00
CMakeLists.txt
prj.conf
README.rst
sample.yaml

README.rst

MetaIRQ Thread Priority Demonstration
#####################################

Overview
********

This sample demonstrates the use of a thread running at a MetaIRQ
priority level to implement "bottom half" style processing
synchronously with the end of a hardware ISR.  It implements a
simulated "device" that produces messages that need to be dispatched
to asynchronous queues feeding several worker threads, each running at
a different priority.  The dispatch is handled by a MetaIRQ thread fed
via a queue from the device ISR (really just a timer interrupt).

Each message has a random (and non-trivial) amount of processing that
must happen in the worker thread.  This implements a "bursty load"
environment where occassional spikes in load require preemption of
running threads and delay scheduling of lower priority threads.
Messages are accompanied by a timestamp that allows per-message
latencies to be computed at several points:

* The cycle time between message creation in the ISR and receipt by
  the MetaIRQ thread for dispatch.

* The time between ISR and receipt by the worker thread.

* The real time spent processing the message in the worker thread, for
  comparison with the required processing time.  This provides a way
  to measure preemption overhead where the thread is not scheduled.

Aspects to note in the results:

* On average, higher priority (lower numbered) threads have better
  latencies and lower processing delays, as expected.

* Cooperatively scheduled threads have significantly better processing
  delay behavior than preemtible ones, as they can only be preempted
  by the MetaIRQ thread.

* Because of queueing and the bursty load, all worker threads of any
  priority will experience some load-dependent delays, as the CPU
  occasionally has more work to do than time available.

* But, no matter the system load or thread configuration, the MetaIRQ
  thread always runs immediately after the ISR.  It shows reliable,
  constant latency under all circumstances because it can preempt all
  other threads, including cooperative ones that cannot normally be
  preempted.

Requirements
************

This sample should run well on any Zephyr platform that provides
preemption of running threads by interrupts, a working timer driver,
and working log output.  For precision reasons, it produces better
(and more) data on systems with a high timer tick rate (ideally 10+
kHz).

Note that because the test is fundamentally measuring thread
preemption behavior, it does not run without modification on
native_posix platforms.  In that emulation environment, threads will
not be preempted except at specific instrumentation points (e.g. in
k_busy_wait()) where they will voluntarily release the CPU.