doc/reference/index.rst

.. _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.