224 lines
7.2 KiB
ReStructuredText
224 lines
7.2 KiB
ReStructuredText
.. _api_reference:
|
|
|
|
API Reference
|
|
#############
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
bluetooth/index.rst
|
|
kconfig/index.rst
|
|
drivers/index.rst
|
|
display/index.rst
|
|
file_system/index.rst
|
|
kernel/index.rst
|
|
logging/index.rst
|
|
misc/index
|
|
networking/index.rst
|
|
peripherals/index.rst
|
|
power_management/index.rst
|
|
random/index.rst
|
|
shell/index.rst
|
|
storage/index.rst
|
|
usb/index.rst
|
|
usermode/index.rst
|
|
runtime_conf/index.rst
|
|
|
|
Terminology
|
|
***********
|
|
|
|
The following terms may be used as shorthand API tags to indicate the
|
|
allowed calling context (thread, ISR, pre-kernel), the effect of a call
|
|
on the current thread state, and other behavioral characteristics.
|
|
|
|
:ref:`api_term_reschedule`
|
|
if executing the function reaches a reschedule point
|
|
:ref:`api_term_sleep`
|
|
if executing the function can cause the invoking thread to sleep
|
|
:ref:`api_term_no-wait`
|
|
if a parameter to the function can prevent the invoking thread from
|
|
trying to sleep
|
|
:ref:`api_term_isr-ok`
|
|
if the function can always be safely called from interrupt context
|
|
even if it may return an error in that case
|
|
:ref:`api_term_pre-kernel-ok`
|
|
if the function can be safely called before the kernel has been fully
|
|
initialized, even if it may return an error in that case
|
|
:ref:`api_term_async`
|
|
if the function may return before the operation it initializes is
|
|
complete (i.e. function return and operation completion are
|
|
asynchronous)
|
|
:ref:`api_term_supervisor`
|
|
if the calling thread must have supervisor privileges to execute the
|
|
function
|
|
|
|
Details on the behavioral impact of each attribute are in the following
|
|
sections.
|
|
|
|
.. _api_term_reschedule:
|
|
|
|
reschedule
|
|
==========
|
|
|
|
The reschedule attribute is used on a function that can reach a
|
|
:ref:`reschedule point <scheduling_v2>` within its execution.
|
|
|
|
Details
|
|
-------
|
|
|
|
The significance of this attribute is that when a rescheduling function
|
|
is invoked by a thread it is possible for that thread to be suspended as
|
|
a consequence of a higher-priority thread being made ready. Whether the
|
|
suspension actually occurs depends on the operation associated with the
|
|
reschedule point and the relative priorities of the invoking thread and
|
|
the head of the ready queue.
|
|
|
|
Note that in the case of timeslicing, or reschedule points executed from
|
|
interrupts, any thread may be suspended in any function.
|
|
|
|
Functions that are not **reschedule** may be invoked from either thread
|
|
or interrupt context.
|
|
|
|
Functions that are **reschedule** may be invoked from thread context.
|
|
|
|
Functions that are **reschedule** but not **sleep** may be invoked from
|
|
interrupt context.
|
|
|
|
.. _api_term_sleep:
|
|
|
|
sleep
|
|
=====
|
|
|
|
The sleep attribute is used on a function that can cause the invoking
|
|
thread to sleep.
|
|
|
|
Explanation
|
|
-----------
|
|
|
|
This attribute is of relevance specifically when considering
|
|
applications that use only non-preemptible threads, because the kernel
|
|
will not replace a running cooperative-only thread at a reschedule point
|
|
unless that thread has explicitly invoked an operation that caused it to
|
|
sleep.
|
|
|
|
This attribute does not imply the function will sleep unconditionally,
|
|
but that the operation may require an invoking thread that would have to
|
|
suspend, wait, or invoke :cpp:func:`k_yield()` before it can complete
|
|
its operation. This behavior may be mediated by **no-wait**.
|
|
|
|
Functions that are **sleep** are implicitly **reschedule**.
|
|
|
|
Functions that are **sleep** may be invoked from thread context.
|
|
|
|
Functions that are **sleep** may be invoked from interrupt and
|
|
pre-kernel contexts if and only if invoked in **no-wait** mode.
|
|
|
|
.. _api_term_no-wait:
|
|
|
|
no-wait
|
|
=======
|
|
|
|
The no-wait attribute is used on a function that is also **sleep** to
|
|
indicate that a parameter to the function can force an execution path
|
|
that will not cause the invoking thread to sleep.
|
|
|
|
Explanation
|
|
-----------
|
|
|
|
The paradigmatic case of a no-wait function is a function that takes a
|
|
timeout, to which :c:macro:`K_NO_WAIT` can be passed. The semantics of
|
|
this special timeout value are to execute the function's operation as
|
|
long as it can be completed immediately, and to return an error code
|
|
rather than sleep if it cannot.
|
|
|
|
It is use of the no-wait feature that allows functions like
|
|
:cpp:func:`k_sem_take` to be invoked from ISRs, since it is not
|
|
permitted to sleep in interrupt context.
|
|
|
|
A function with a no-wait path does not imply that taking that path
|
|
guarantees the function is synchronous.
|
|
|
|
Functions with this attribute may be invoked from interrupt and
|
|
pre-kernel contexts only when the parameter selects the no-wait path.
|
|
|
|
.. _api_term_isr-ok:
|
|
|
|
isr-ok
|
|
======
|
|
|
|
The isr-ok attribute is used on a function to indicate that it can be
|
|
called from interrupt context. If necessary the function will use
|
|
:cpp:func:`k_is_in_isr` to detect its calling context and force an
|
|
execution path that will not cause the invoking thread to sleep.
|
|
|
|
Explanation
|
|
-----------
|
|
|
|
This attribute is intended for **sleep** functions that may be
|
|
indirectly invoked from interrupt context with arguments that could
|
|
attempt to put the invoking thread to sleep, e.g. because the function
|
|
is not **no-wait** or the parameters do not select the no-wait path.
|
|
|
|
Functions that are **isr-ok** may be always be safely invoked from
|
|
interrupt context, and will return an error if they were unable to
|
|
fulfill their behavior in that context.
|
|
|
|
.. _api_term_pre-kernel-ok:
|
|
|
|
pre-kernel-ok
|
|
=============
|
|
|
|
The pre-kernel-ok attribute is used on a function to indicate that it
|
|
will take reasonable steps to ensure it is safe to invoke before all
|
|
kernel services are started. In some cases the invocation in that
|
|
context may return an error code.
|
|
|
|
Explanation
|
|
-----------
|
|
|
|
This attribute is similar to **isr-ok** in function, but is intended for
|
|
use by any API that is expected to be called in :c:func:`DEVICE_INIT()`
|
|
or :c:func:`SYS_INIT()` calls that may be invoked with ``PRE_KERNEL_1``
|
|
or ``PRE_KERNEL_2`` initialization levels.
|
|
|
|
Generally a function that is **pre-kernel-ok** checks
|
|
:cpp:func:`k_is_pre_kernel` when determining whether it can fulfill its
|
|
required behavior. In many cases it would also check
|
|
:cpp:func:`k_is_in_isr` so it can be **isr-ok** as well.
|
|
|
|
.. _api_term_async:
|
|
|
|
async
|
|
=====
|
|
|
|
A function is **async** (i.e. asynchronous) if it may return before the
|
|
operation it initiates has completed. An asynchronous function will
|
|
generally provide a mechanism by which operation completion is reported,
|
|
e.g. a callback or event.
|
|
|
|
A function that is not asynchronous is synchronous, i.e. the operation
|
|
will always be complete when the function returns. As most functions
|
|
are synchronous this behavior does not have a distinct attribute to
|
|
identify it.
|
|
|
|
Explanation
|
|
-----------
|
|
|
|
Be aware that **async** is orthogonal to context-switching. Some APIs
|
|
may provide completion information through a callback, but may suspend
|
|
while waiting for the resource necessary to initiate the operation; an
|
|
example is :cpp:func:`spi_transceive_async`.
|
|
|
|
If a function is both **no-wait** and **async** then selecting the
|
|
no-wait path only guarantees that the function will not sleep. It does
|
|
not affect whether the operation will be completed before the function
|
|
returns.
|
|
|
|
.. _api_term_supervisor:
|
|
|
|
supervisor
|
|
==========
|
|
|
|
The supervisor attribute is relevant only in user-mode applications, and
|
|
indicates that the function cannot be invoked from user mode.
|