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>

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)
+ * @brief Lock interrupts.
  *
- * 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.
+ * 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.
  *
- * 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 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().)
  *
- * This function can be called recursively: it will return a key to return the
- * state of interrupt locking to the previous level.
+ * @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.
  *
- * 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.
+ * @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