From 79089d6352e01e1e7c6c3f0a88266abbc9af6abb Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Mon, 19 Jan 2009 15:10:41 +0000
Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@644
 35acf78f-673a-0410-8e92-d51de3d6d3f4

---
 docs/src/atomic.dox     | 12 ++----------
 docs/src/interrupts.dox | 34 ++++++++++++++++++++++++++++++++++
 docs/src/saveram.dox    | 25 +++++++++++--------------
 3 files changed, 47 insertions(+), 24 deletions(-)
 create mode 100644 docs/src/interrupts.dox

(limited to 'docs/src')

diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox
index 0f678448b..22601d8d9 100644
--- a/docs/src/atomic.dox
+++ b/docs/src/atomic.dox
@@ -30,16 +30,8 @@
  
   chSemSignalI(&sem1);
   chSemSignalI(&sem2);
-  /*
-   * The "if" is required because the chSemWaitS() does not always internally
-   * reschedule.
-   */
-  if (chSemGetCounter(&sem3) <= 0)
-    chSemWaitS(&Sem3);
-  else {
-    chSemFastWaitS(&sem3);
-    chSchRescheduleS();
-  }
+  chSemWaitS(&Sem3);
+  chSchRescheduleS(); /* Because chSemWaitS() might not reschedule internally.*/
  
   chSysUnlock();
  * @endcode
diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox
new file mode 100644
index 000000000..8c61eaa6e
--- /dev/null
+++ b/docs/src/interrupts.dox
@@ -0,0 +1,34 @@
+/**
+ * @page article_interrupts Writing interrupt handlers under ChibiOS/RT
+ * @{
+ * Since version 1.1.0 ChbiOS/RT offers a cross-platform system for writing
+ * interrupt handlers. Port-related and compiler-related details are
+ * encapsulated within standard system macros.<br>
+ * An interrupt handler assumes the following general form:
+ * @code
+CH_IRQ_HANDLER(myIRQ) {
+  CH_IRQ_PROLOGUE();
+  
+  // IRQ handling code, preemptable if the architecture supports it.
+  
+  chSysLockI();
+  // Invocation of some I-Class system API, never preemptable.
+  chSysUnlockI().
+  
+  // More IRQ handling code, again preemptable.
+
+  CH_IRQ_EPILOGUE();
+}
+ * @endcode
+ * Note that only interrupt handlers that have to invoke system I-Class APIs
+ * must be written in this form, handlers unrelated to the OS activity can
+ * omit the macros.
+ * Another note about the handler name "myIRQ", in some ports it must be a
+ * vector number rather than a function name, it could also be a name from
+ * within a predefined set, see the notes about the various ports.
+ * <h2>Important Notes</h2>
+ * - There is an important application note about ARM7 interrupt handlers,
+ *   please read about it in the ARM7 port section: @ref ARM7_IH
+ */
+/** @} */
+ 
\ No newline at end of file
diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox
index fec810c81..324bdb9a3 100644
--- a/docs/src/saveram.dox
+++ b/docs/src/saveram.dox
@@ -9,23 +9,21 @@
  * Consider the following code: 
  * @code
 #include <ch.h>
- 
+
 static WORKING_AREA(waMyThread, 64);
- 
+
 static t_msg MyThread(void *arg) {
- 
   while (!chThdShoudTerminate()) {
     /* Do thread inner work */
   }
   return 1;
 }
- 
+
 main() {
   chSysInit();
   ...
-  chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), MyThread, NULL);
+  chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, MyThread, NULL);
   ...
-  chSysPause();
 }
  * @endcode
  * The resulting ASM code for the thread function would be something like this:
@@ -40,23 +38,22 @@ MyThread:
  * saved by modifying the code as follow, using some advanced GCC extensions: 
  * @code
 #include <ch.h>
- 
-static BYTE8 waMyThread[UserStackSize(64)];
- 
-__attribute__((noreturn)) void MyThread(void *arg) {
- 
+
+static WORKING_AREA(waMyThread, 64);
+
+__attribute__((noreturn))
+static void MyThread(void *arg) {
   while (!chThdShoudTerminate()) {
     /* Do thread inner work */
   }
   chThdExit(1);
 }
- 
+
 main() {
   chSysInit();
   ...
-  chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), (t_tfunc)MyThread, NULL);
+  chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, MyThread, NULL);
   ...
-  chSysPause();
 }
  * @endcode
  * This will make GCC believe that the function cannot return and there is no
-- 
cgit v1.2.3