From bb01382c18dc2937d721c1e1fb3152e9de1e8ab5 Mon Sep 17 00:00:00 2001 From: Carles Cufi Date: Wed, 19 Feb 2020 19:04:29 +0100 Subject: [PATCH] doc: reference: Move terminology to its own page Move the terminology section to its own page in preparation for additional sections to be addded later. Signed-off-by: Carles Cufi --- doc/reference/index.rst | 199 +--------------------------------- doc/reference/terminology.rst | 199 ++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+), 198 deletions(-) create mode 100644 doc/reference/terminology.rst diff --git a/doc/reference/index.rst b/doc/reference/index.rst index 455529f424..e970364b2d 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -6,6 +6,7 @@ API Reference .. toctree:: :maxdepth: 1 + terminology.rst bluetooth/index.rst kconfig/index.rst crypto/index.rst @@ -24,201 +25,3 @@ API Reference 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 ` 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. diff --git a/doc/reference/terminology.rst b/doc/reference/terminology.rst new file mode 100644 index 0000000000..367ecb3311 --- /dev/null +++ b/doc/reference/terminology.rst @@ -0,0 +1,199 @@ +.. _api_terms: + +API 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 ` 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.