1.. _api_terms: 2 3API Terminology 4############### 5 6The following terms may be used as shorthand API tags to indicate the 7allowed calling context (thread, ISR, pre-kernel), the effect of a call 8on the current thread state, and other behavioral characteristics. 9 10:ref:`api_term_reschedule` 11 if executing the function reaches a reschedule point 12:ref:`api_term_sleep` 13 if executing the function can cause the invoking thread to sleep 14:ref:`api_term_no-wait` 15 if a parameter to the function can prevent the invoking thread from 16 trying to sleep 17:ref:`api_term_isr-ok` 18 if the function can be safely called and will have its specified 19 effect whether invoked from interrupt or thread context 20:ref:`api_term_pre-kernel-ok` 21 if the function can be safely called before the kernel has been fully 22 initialized and will have its specified effect when invoked from that 23 context. 24:ref:`api_term_async` 25 if the function may return before the operation it initializes is 26 complete (i.e. function return and operation completion are 27 asynchronous) 28:ref:`api_term_supervisor` 29 if the calling thread must have supervisor privileges to execute the 30 function 31 32Details on the behavioral impact of each attribute are in the following 33sections. 34 35.. _api_term_reschedule: 36 37reschedule 38========== 39 40The reschedule attribute is used on a function that can reach a 41:ref:`reschedule point <scheduling_v2>` within its execution. 42 43Details 44------- 45 46The significance of this attribute is that when a rescheduling function 47is invoked by a thread it is possible for that thread to be suspended as 48a consequence of a higher-priority thread being made ready. Whether the 49suspension actually occurs depends on the operation associated with the 50reschedule point and the relative priorities of the invoking thread and 51the head of the ready queue. 52 53Note that in the case of timeslicing, or reschedule points executed from 54interrupts, any thread may be suspended in any function. 55 56Functions that are not **reschedule** may be invoked from either thread 57or interrupt context. 58 59Functions that are **reschedule** may be invoked from thread context. 60 61Functions that are **reschedule** but not **sleep** may be invoked from 62interrupt context. 63 64.. _api_term_sleep: 65 66sleep 67===== 68 69The sleep attribute is used on a function that can cause the invoking 70thread to :ref:`sleep <scheduling_v2>`. 71 72Explanation 73----------- 74 75This attribute is of relevance specifically when considering 76applications that use only non-preemptible threads, because the kernel 77will not replace a running cooperative-only thread at a reschedule point 78unless that thread has explicitly invoked an operation that caused it to 79sleep. 80 81This attribute does not imply the function will sleep unconditionally, 82but that the operation may require an invoking thread that would have to 83suspend, wait, or invoke :c:func:`k_yield` before it can complete 84its operation. This behavior may be mediated by **no-wait**. 85 86Functions that are **sleep** are implicitly **reschedule**. 87 88Functions that are **sleep** may be invoked from thread context. 89 90Functions that are **sleep** may be invoked from interrupt and 91pre-kernel contexts if and only if invoked in **no-wait** mode. 92 93.. _api_term_no-wait: 94 95no-wait 96======= 97 98The no-wait attribute is used on a function that is also **sleep** to 99indicate that a parameter to the function can force an execution path 100that will not cause the invoking thread to sleep. 101 102Explanation 103----------- 104 105The paradigmatic case of a no-wait function is a function that takes a 106timeout, to which :c:macro:`K_NO_WAIT` can be passed. The semantics of 107this special timeout value are to execute the function's operation as 108long as it can be completed immediately, and to return an error code 109rather than sleep if it cannot. 110 111It is use of the no-wait feature that allows functions like 112:c:func:`k_sem_take` to be invoked from ISRs, since it is not 113permitted to sleep in interrupt context. 114 115A function with a no-wait path does not imply that taking that path 116guarantees the function is synchronous. 117 118Functions with this attribute may be invoked from interrupt and 119pre-kernel contexts only when the parameter selects the no-wait path. 120 121.. _api_term_isr-ok: 122 123isr-ok 124====== 125 126The isr-ok attribute is used on a function to indicate that it works 127whether it is being invoked from interrupt or thread context. 128 129Explanation 130----------- 131 132Any function that is not **sleep** is inherently **isr-ok**. Functions 133that are **sleep** are **isr-ok** if the implementation ensures that the 134documented behavior is implemented even if called from an interrupt 135context. This may be achieved by having the implementation detect the 136calling context and transfer the operation that would sleep to a thread, 137or by documenting that when invoked from a non-thread context the 138function will return a specific error (generally ``-EWOULDBLOCK``). 139 140Note that a function that is **no-wait** is safe to call from interrupt 141context only when the no-wait path is selected. **isr-ok** functions 142need not provide a no-wait path. 143 144.. _api_term_pre-kernel-ok: 145 146pre-kernel-ok 147============= 148 149The pre-kernel-ok attribute is used on a function to indicate that it 150works as documented even when invoked before the kernel main thread has 151been started. 152 153Explanation 154----------- 155 156This attribute is similar to **isr-ok** in function, but is intended for 157use by any API that is expected to be called in :c:macro:`DEVICE_DEFINE()` 158or :c:macro:`SYS_INIT()` calls that may be invoked with ``PRE_KERNEL_1`` 159or ``PRE_KERNEL_2`` initialization levels. 160 161Generally a function that is **pre-kernel-ok** checks 162:c:func:`k_is_pre_kernel` when determining whether it can fulfill its 163required behavior. In many cases it would also check 164:c:func:`k_is_in_isr` so it can be **isr-ok** as well. 165 166.. _api_term_async: 167 168async 169===== 170 171A function is **async** (i.e. asynchronous) if it may return before the 172operation it initiates has completed. An asynchronous function will 173generally provide a mechanism by which operation completion is reported, 174e.g. a callback or event. 175 176A function that is not asynchronous is synchronous, i.e. the operation 177will always be complete when the function returns. As most functions 178are synchronous this behavior does not have a distinct attribute to 179identify it. 180 181Explanation 182----------- 183 184Be aware that **async** is orthogonal to context-switching. Some APIs 185may provide completion information through a callback, but may suspend 186while waiting for the resource necessary to initiate the operation; an 187example is :c:func:`spi_transceive_async`. 188 189If a function is both **no-wait** and **async** then selecting the 190no-wait path only guarantees that the function will not sleep. It does 191not affect whether the operation will be completed before the function 192returns. 193 194.. _api_term_supervisor: 195 196supervisor 197========== 198 199The supervisor attribute is relevant only in user-mode applications, and 200indicates that the function cannot be invoked from user mode. 201
