diff options
author | Allan Stephens <allan.stephens@windriver.com> | 2016-11-11 15:45:03 -0500 |
---|---|---|
committer | Anas Nashif <nashif@linux.intel.com> | 2016-11-16 21:43:16 +0000 |
commit | c98da84e69d8ab25b7661d989b48a81c4e2c31ed (patch) | |
tree | 608d432a939dcb5aa965090499e98b1695102823 /include/irq.h | |
parent | f880c250dda3e4e8d54c5538ff56b143483fa2c6 (diff) |
doc: Various corrections to doxygen info for Kernel APIs
Most kernel APIs are now ready for inclusion in the API guide.
The APIs largely follow a standard template to provide users
of the API guide with a consistent look-and-feel.
Change-Id: Ib682c31f912e19f5f6d8545d74c5f675b1741058
Signed-off-by: Allan Stephens <allan.stephens@windriver.com>
Diffstat (limited to 'include/irq.h')
-rw-r--r-- | include/irq.h | 104 |
1 files changed, 62 insertions, 42 deletions
diff --git a/include/irq.h b/include/irq.h index 88442fcf4..e83e1945c 100644 --- a/include/irq.h +++ b/include/irq.h @@ -30,6 +30,13 @@ #ifdef __cplusplus extern "C" { #endif + +/** + * @defgroup isr_apis Interrupt Service Routine APIs + * @ingroup kernel_apis + * @{ + */ + /** * Configure a static interrupt. * @@ -47,78 +54,91 @@ extern "C" { _ARCH_IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p) /** - * @brief Disable all interrupts on the CPU (inline) - * - * This routine disables interrupts. It can be called from either interrupt, - * task or fiber level. This routine returns an architecture-dependent - * lock-out key representing the "interrupt disable state" prior to the call; - * this key can be passed to irq_unlock() to re-enable interrupts. - * - * The lock-out key should only be used as the argument to the irq_unlock() - * API. It should never be used to manually re-enable interrupts or to inspect - * or manipulate the contents of the source register. - * - * This function can be called recursively: it will return a key to return the - * state of interrupt locking to the previous level. - * - * WARNINGS - * Invoking a kernel routine with interrupts locked may result in - * interrupts being re-enabled for an unspecified period of time. If the - * called routine blocks, interrupts will be re-enabled while another - * thread executes, or while the system is idle. - * - * The "interrupt disable state" is an attribute of a thread. Thus, if a - * fiber or task disables interrupts and subsequently invokes a kernel - * routine that causes the calling thread to block, the interrupt - * disable state will be restored when the thread is later rescheduled - * for execution. - * - * @return An architecture-dependent unsigned int lock-out key representing the - * "interrupt disable state" prior to the call. - * + * @brief Lock interrupts. + * + * This routine disables all interrupts on the CPU. It returns an unsigned + * integer "lock-out key", which is an architecture-dependent indicator of + * whether interrupts were locked prior to the call. The lock-out key must be + * passed to irq_unlock() to re-enable interrupts. + * + * This routine can be called recursively, as long as the caller keeps track + * of each lock-out key that is generated. Interrupts are re-enabled by + * passing each of the keys to irq_unlock() in the reverse order they were + * acquired. (That is, each call to irq_lock() must be balanced by + * a corresponding call to irq_unlock().) + * + * @note + * This routine can be called by ISRs or by threads. If it is called by a + * thread, the interrupt lock is thread-specific; this means that interrupts + * remain disabled only while the thread is running. If the thread performs an + * operation that allows another thread to run (for example, giving a semaphore + * or sleeping for N milliseconds), the interrupt lock no longer applies and + * interrupts may be re-enabled while other processing occurs. When the thread + * once again becomes the current thread, the kernel re-establishes its + * interrupt lock; this ensures the thread won't be interrupted until it has + * explicitly released the interrupt lock it established. + * + * @warning + * The lock-out key should never be used to manually re-enable interrupts + * or to inspect or manipulate the contents of the CPU's interrupt bits. + * + * @return Lock-out key. */ #define irq_lock() _arch_irq_lock() /** + * @brief Unlock interrupts. * - * @brief Enable all interrupts on the CPU (inline) + * This routine reverses the effect of a previous call to irq_lock() using + * the associated lock-out key. The caller must call the routine once for + * each time it called irq_lock(), supplying the keys in the reverse order + * they were acquired, before interrupts are enabled. * - * This routine re-enables interrupts on the CPU. The @a key parameter - * is an architecture-dependent lock-out key that is returned by a previous - * invocation of irq_lock(). + * @note Can be called by ISRs. * - * This routine can be called from either interrupt, task or fiber level - * - * @param key architecture-dependent lock-out key + * @param key Lock-out key generated by irq_lock(). * * @return N/A */ #define irq_unlock(key) _arch_irq_unlock(key) /** - * @brief Enable a specific IRQ + * @brief Enable an IRQ. + * + * This routine enables interrupts from source @a irq. + * + * @param irq IRQ line. * - * @param irq IRQ line * @return N/A */ #define irq_enable(irq) _arch_irq_enable(irq) /** - * @brief Disable a specific IRQ + * @brief Disable an IRQ. + * + * This routine disables interrupts from source @a irq. + * + * @param irq IRQ line. * - * @param irq IRQ line * @return N/A */ #define irq_disable(irq) _arch_irq_disable(irq) /** - * @brief Return IRQ enable state + * @brief Get IRQ enable state. + * + * This routine indicates if interrupts from source @a irq are enabled. + * + * @param irq IRQ line. * - * @param irq IRQ line * @return interrupt enable state, true or false */ #define irq_is_enabled(irq) _arch_irq_is_enabled(irq) +/** + * @} + */ + #ifdef __cplusplus } #endif |