michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Clarify k_poll() behavior with respect to signal synchronization

Browse source 
Bug #40189 tripped over an interesting synchronization scenario that
wasn't called out in the docs.  Poll signals are level triggered, and
if you're adjusting the level from a racing context (e.g. resetting it
before the next "event" from an ISR or another thread) the polling
thread might wake up but then miss the event.  Mention this case
explicitly in documentation.

Fixes #40189

Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
This commit is contained in:
Andy Ross 2022-01-19 16:43:44 -08:00 • committed by Anas Nashif
commit aa825d77b0
1 changed files with 12 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

12
doc/reference/kernel/other/polling.rst
View file

@ -255,6 +255,18 @@ If the signal is to be polled in a loop, *both* its event state and its
}
}
Note that poll signals are not internally synchronized. A k_poll call
that is passed a signal will return after any code in the system calls
:c:func:`k_poll_signal_raise()`. But if the signal is being
externally managed and reset via :c:func:`k_poll_signal_init()`, it is
possible that by the time the application checks, the event state may
no longer be equal to :c:macro:`K_POLL_STATE_SIGNALED`, and a (naive)
application will miss events. Best practice is always to reset the
signal only from within the thread invoking the k_poll() loop, or else
to use some other event type which tracks event counts: semaphores and
FIFOs more more error-proof in thise sense because they can't "miss"
events, architecturally.
Suggested Uses
**************