Update some comments

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3073 42af7a65-404d-4744-a932-0658087f49c3

arch/avr/include/avr32/irq.h

@@ -98,7 +98,6 @@
 #define INTCONTEXT_REGS   8 /* r8-r12, lr, pc, sr */
 #define XCPTCONTEXT_REGS 17 /* Plus r0-r7, sp */
 
-
 /****************************************************************************
  * Public Types
  ****************************************************************************/

arch/avr/src/avr32/up_fullcontextrestore.S

@@ -53,6 +53,28 @@
 /****************************************************************************
  * Name: up_fullcontextrestore
  *
+ * Descripion:
+ *   Restore the full-running contex of a thread.
+ *
+ *   NOTE: Thus function must handle one very strange case.  That is when
+ *   this function is called with up_sigdeliver().  That case is strange in
+ *   two ways:
+ *
+ *   1. It is not a context switch between threads.  Rather, up_fullcontextrestore
+ *      must behave more it more like a longjmp within the same task, using the
+ *      same stack.
+ *   2. In this case, this function is called with r12 pointing to a register
+ *      save area on the stack to be destroyed.  This is dangerous for two
+ *      reasons: (a) there is a period of time where the stack contents still
+ *      contain valid data, but are outside of range protected by the stack
+ *      pointer (hence, interrupts must be disabled), and (b) there is the
+ *      very real possibility that the new stack pointer might overlap with
+ *      the register save area and stack usage in this function might corrupt
+ *      the register save data before the state is restored.
+ *
+ * Input Parameters:
+ *   r12 = A pointer to the register save area of the thread to be restored.
+ *
  * C Prototype:
  *  void up_fullcontextrestore(uint32_t *regs);
  *

arch/avr/src/avr32/up_sigdeliver.c

@@ -82,7 +82,7 @@
 void up_sigdeliver(void)
 {
   _TCB  *rtcb = (_TCB*)g_readytorun.head;
-  uint32_t regs[XCPTCONTEXT_REGS];
+  uint32_t regs[XCPTCONTEXT_REGS+3];  /* Why +3? See below */
   sig_deliver_t sigdeliver;
 
   /* Save the errno.  This must be preserved throughout the signal handling
@@ -128,7 +128,20 @@ void up_sigdeliver(void)
   (void)irqsave();
   rtcb->pterrno = saved_errno;
 
-  /* Then restore the correct state for this thread of execution. */
+  /* Then restore the correct state for this thread of execution. This is an
+   * unusual case that must be handled by up_fullcontextresore. This case is
+   * unusal in two ways:
+   *
+   *   1. It is not a context switch between threads.  Rather, up_fullcontextrestore
+   *      must behave more it more like a longjmp within the same task, using
+   *      he same stack.
+   *   2. In this case, up_fullcontextrestore is called with r12 pointing to
+   *      a register save area on the stack to be destroyed.  This is
+   *      dangerous because there is the very real possibility that the new
+   *      stack pointer might overlap with the register save area and hat stack
+   *      usage in up_fullcontextrestore might corrupt the register save data
+   *      before the state is restored.
+   */
 
   up_ledoff(LED_SIGNAL);
   up_fullcontextrestore(regs);