From a2aba902523add693595709a5e177d94e6a90f11 Mon Sep 17 00:00:00 2001
From: Gregory Nutt <gnutt@nuttx.org>
Date: Sat, 19 Nov 2016 11:48:08 -0600
Subject: [PATCH] Update some comments

---
 include/nuttx/irq.h | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/include/nuttx/irq.h b/include/nuttx/irq.h
index f7bfd75b3b..d0076d9ca0 100644
--- a/include/nuttx/irq.h
+++ b/include/nuttx/irq.h
@@ -108,9 +108,22 @@ int irq_attach(int irq, xcpt_t isr);
  *     Take the CPU IRQ lock and disable interrupts on all CPUs.  A thread-
  *     specific counter is increment to indicate that the thread has IRQs
  *     disabled and to support nested calls to enter_critical_section().
+ *
+ *     NOTE: Most architectures do not support disabling all CPUs from one
+ *     CPU.  ARM is an example.  In such cases, logic in
+ *     enter_critical_section() will still manage entrance into the
+ *     protected logic using spinlocks.
+ *
  *   If SMP is not enabled:
  *     This function is equivalent to up_irq_save().
  *
+ * Input Parameters:
+ *   None
+ *
+ * Returned Value:
+ *   An opaque, architecture-specific value that represents the state of
+ *   the interrupts prior to the call to enter_critical_section();
+ *
  ****************************************************************************/
 
 #if defined(CONFIG_SMP) || defined(CONFIG_SCHED_INSTRUMENTATION_CSECTION)
@@ -125,10 +138,19 @@ irqstate_t enter_critical_section(void);
  * Description:
  *   If SMP is enabled:
  *     Decrement the IRQ lock count and if it decrements to zero then release
- *     the spinlock.
+ *     the spinlock and restore the interrupt state as it was prior to the
+ *     previous call to enter_critical_section().
+ *
  *   If SMP is not enabled:
  *     This function is equivalent to up_irq_restore().
  *
+ * Input Parameters:
+ *   flags - The architecture-specific value that represents the state of
+ *           the interrupts prior to the call to enter_critical_section();
+ *
+ * Returned Value:
+ *   None
+ *
  ****************************************************************************/
 
 #if defined(CONFIG_SMP) || defined(CONFIG_SCHED_INSTRUMENTATION_CSECTION)