OrgZephyr/zephyr
OrgZephyr
/
zephyr
mirror of https://github.com/zephyrproject-rtos/zephyr.git
1
0
Fork 0
Code Issues Releases Wiki Activity
zephyr/doc/services/notify.rst

38 lines
1.5 KiB
ReStructuredText
Raw Normal View History

sys: add generic asynchronous notification infrastructure k_poll() for a signal is often desired for notification of completion of asynchronous operations, but there are APIs where it may be necessary to invoke "asynchronous" operations from contexts where sleep is disallowed, or before the kernel has been initialized. Extract the general notification solution from the on-off service into a utility that can be used for other APIs. Also move documentation out to a resource management section. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
2020-02-19 20:01:07 +08:00
.. _async_notification:
doc: reference: reword a few titles Reword a few of the reference documentation titles to better fit in with the rest. Do not use all-caps MODBUS for title. Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
2021-12-14 06:21:01 +08:00
Asynchronous Notifications
##########################
sys: add generic asynchronous notification infrastructure k_poll() for a signal is often desired for notification of completion of asynchronous operations, but there are APIs where it may be necessary to invoke "asynchronous" operations from contexts where sleep is disallowed, or before the kernel has been initialized. Extract the general notification solution from the on-off service into a utility that can be used for other APIs. Also move documentation out to a resource management section. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
2020-02-19 20:01:07 +08:00
Zephyr APIs often include :ref:`api_term_async` functions where an
operation is initiated and the application needs to be informed when it
doc: update function references to use :c:func: Following the change to use the C domain for parsing, update all existing :cpp:func: references to :c:func:. Remove the parentheses as well, if used, because they are not needed, this is already known to be a function, and how it is displayed in the documentation later is a semantic decision done by the output builder. Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
2020-08-24 22:35:45 +08:00
completes, and whether it succeeded. Using :c:func:`k_poll` is
sys: add generic asynchronous notification infrastructure k_poll() for a signal is often desired for notification of completion of asynchronous operations, but there are APIs where it may be necessary to invoke "asynchronous" operations from contexts where sleep is disallowed, or before the kernel has been initialized. Extract the general notification solution from the on-off service into a utility that can be used for other APIs. Also move documentation out to a resource management section. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
2020-02-19 20:01:07 +08:00
often a good method, but some application architectures may be more
suited to a callback notification, and operations like enabling clocks
and power rails may need to be invoked before kernel functions are
available so a busy-wait for completion may be needed.
This API is intended to be embedded within specific subsystems such as
:ref:`resource_mgmt_onoff` and other APIs that support async
transactions. The subsystem wrappers are responsible for extracting
operation-specific data from requests that include a notification
element, and for invoking callbacks with the parameters required by the
API.
doc: reference: misc: highlight userspace restriction on sys_notify The underlying structure is not suitable for use in API invoked from user threads for the reasons explained in the edit. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
2020-04-28 01:48:55 +08:00
A limitation is that this API is not suitable for :ref:`syscalls`
because:
doc: update struct references to use :c:struct: Sphinx>=3.0 includes the `struct` role in the C domain, which provides a specific way to link to structs, while the old :c:type: role should be primary used to typedefs. Update existing references, using :c:type:, :cpp:type: or emphasized symbols that point to structs to use the new role. Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
2020-08-21 01:29:47 +08:00
* :c:struct:`sys_notify` is not a kernel object;
doc: reference: misc: highlight userspace restriction on sys_notify The underlying structure is not suitable for use in API invoked from user threads for the reasons explained in the edit. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
2020-04-28 01:48:55 +08:00
* copying the notification content from userspace will break use of
:c:macro:`CONTAINER_OF` in the implementing function;
* neither the spin-wait nor callback notification methods can be
accepted from userspace callers.
Where a notification is required for an asynchronous operation invoked
from a user mode thread the subsystem or driver should provide a syscall
doc: update struct references to use :c:struct: Sphinx>=3.0 includes the `struct` role in the C domain, which provides a specific way to link to structs, while the old :c:type: role should be primary used to typedefs. Update existing references, using :c:type:, :cpp:type: or emphasized symbols that point to structs to use the new role. Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
2020-08-21 01:29:47 +08:00
API that uses :c:struct:`k_poll_signal` for notification.
doc: reference: misc: highlight userspace restriction on sys_notify The underlying structure is not suitable for use in API invoked from user threads for the reasons explained in the edit. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
2020-04-28 01:48:55 +08:00
sys: add generic asynchronous notification infrastructure k_poll() for a signal is often desired for notification of completion of asynchronous operations, but there are APIs where it may be necessary to invoke "asynchronous" operations from contexts where sleep is disallowed, or before the kernel has been initialized. Extract the general notification solution from the on-off service into a utility that can be used for other APIs. Also move documentation out to a resource management section. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
2020-02-19 20:01:07 +08:00
API Reference
*************
.. doxygengroup:: sys_notify_apis