git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@644 35acf78f-673a-0410-8e92-d51de3d6d3f4

docs/ch.txt

@@ -1,12 +1,14 @@
 /**
  * @mainpage ChibiOS/RT
  * @author Giovanni Di Sirio (gdisirio@users.sourceforge.net).
- * @section Chibi Chibi ?
- * It is the Japanese word for small as in small child. So ChibiOS/RT
- * @htmlonly (<span class="t_nihongo_kanji" xml:lang="ja" lang="ja">&#12385;&#12403;</span>OS/RT) \endhtmlonly
+ *
+ * <h2>Chibi ?</h2>
+ * I didn't want a serious name for this project. It is the Japanese word for
+ * small as in small child. So ChibiOS/RT
+ * @htmlonly (<span class="t_nihongo_kanji" xml:lang="ja" lang="ja">&#12385;&#12403;</span>OS/RT) @endhtmlonly
  * means small Real Time Operating System.
  * Source <a href="http://en.wikipedia.org/wiki/Chibi" target="_blank">Wikipedia</a>.
- * @section ch_features Features
+ * <h2>Features</h2>
  * - Free software, GPL3 licensed.
  * - Designed for realtime applications.
  * - Easily portable.
@@ -49,7 +51,7 @@
  *   memory image.
  * - Almost totally written in C with little ASM code required for ports.
  *
- * Related pages:
+ * <h2>Related pages</h2>
  * - @subpage Concepts
  * - @subpage Articles
  */
@@ -241,6 +243,7 @@
  *
  * - @subpage article_atomic
  * - @subpage article_saveram
+ * - @subpage article_interrupts
  */
 /** @} */
 
@@ -491,7 +494,7 @@
  * <h2>Operation Mode</h2>
  * Messages are an easy to use and fast IPC mechanism, threads can both serve
  * messages and send messages to other threads, the mechanism allows data to
- * be carryed in both directions. Data is not copyed between the client and
+ * be carried in both directions. Data is not copied between the client and
  * server threads but just a pointer passed so the exchange is very time
  * efficient.<br>
  * Messages are usually processed in FIFO order but it is possible to process

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

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
+ */
+/** @} */
+ 

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

ports/ARM7-AT91SAM7X/sam7x_emac.c

@@ -124,7 +124,7 @@ static void ServeInterrupt(void) {
   AT91C_BASE_AIC->AIC_EOICR = 0;
 }
 
-CH_IRQ_HANDLER void EMACIrqHandler(void) {
+CH_IRQ_HANDLER(EMACIrqHandler) {
 
   CH_IRQ_PROLOGUE();
 

ports/ARM7-AT91SAM7X/sam7x_serial.c

@@ -74,7 +74,7 @@ static void ServeInterrupt(AT91PS_USART u, FullDuplexDriver *com) {
   AT91C_BASE_AIC->AIC_EOICR = 0;
 }
 
-CH_IRQ_HANDLER void USART0IrqHandler(void) {
+CH_IRQ_HANDLER(USART0IrqHandler) {
 
   CH_IRQ_PROLOGUE();
 
@@ -83,7 +83,7 @@ CH_IRQ_HANDLER void USART0IrqHandler(void) {
   CH_IRQ_EPILOGUE();
 }
 
-CH_IRQ_HANDLER void USART1IrqHandler(void) {
+CH_IRQ_HANDLER(USART1IrqHandler) {
 
   CH_IRQ_PROLOGUE();
 

ports/ARM7-AT91SAM7X/sam7x_serial.h

@@ -30,9 +30,9 @@
 extern "C" {
 #endif
   void InitSerial(int prio0, int prio1);
-  void UART0IrqHandler(void);
-  void UART1IrqHandler(void);
   void SetUSARTI(AT91PS_USART u, int speed, int mode);
+  CH_IRQ_HANDLER(UART0IrqHandler);
+  CH_IRQ_HANDLER(UART1IrqHandler);
 #ifdef __cplusplus
 }
 #endif

ports/ARM7-LPC214x/lpc214x_serial.c

@@ -109,7 +109,7 @@ static void ServeInterrupt(UART *u, FullDuplexDriver *com) {
   }
 }
 
-CH_IRQ_HANDLER void UART0IrqHandler(void) {
+CH_IRQ_HANDLER(UART0IrqHandler) {
 
   CH_IRQ_PROLOGUE();
 
@@ -119,7 +119,7 @@ CH_IRQ_HANDLER void UART0IrqHandler(void) {
   CH_IRQ_EPILOGUE();
 }
 
-CH_IRQ_HANDLER void UART1IrqHandler(void) {
+CH_IRQ_HANDLER(UART1IrqHandler) {
 
   CH_IRQ_PROLOGUE();
 

ports/ARM7-LPC214x/lpc214x_serial.h

@@ -41,9 +41,9 @@
 extern "C" {
 #endif
   void InitSerial(int vector1, int vector2);
-  void UART0IrqHandler(void);
-  void UART1IrqHandler(void);
   void SetUARTI(UART *u, int speed, int lcr, int fcr);
+  CH_IRQ_HANDLER(UART0IrqHandler);
+  CH_IRQ_HANDLER(UART1IrqHandler);
 #ifdef __cplusplus
 }
 #endif

ports/ARM7/chcore.h

@@ -184,9 +184,9 @@ struct context {
 #endif /* !THUMB */
 
 /**
- * IRQ handler function modifier.
+ * IRQ handler function declaration.
  */
-#define PORT_IRQ_HANDLER __attribute__((naked))
+#define PORT_IRQ_HANDLER(id) __attribute__((naked)) void id(void)
 
 /**
  * This function is empty in this port.

ports/ARM7/port.dox

@@ -85,7 +85,7 @@
  * registers.<br>
  * Example:
  * @code
- * CH_IRQ_HANDLER void irq_handler(void) {
+ * CH_IRQ_HANDLER(irq_handler) {
  *   CH_IRQ_PROLOGUE();
  *
  *   serve_interrupt();

ports/ARMCM3-STM32F103/stm32_serial.c

@@ -85,7 +85,7 @@ static void ServeInterrupt(USART_TypeDef *u, FullDuplexDriver *com) {
 /*
  * USART1 IRQ service routine.
  */
-CH_IRQ_HANDLER void VectorD4(void) {
+CH_IRQ_HANDLER(VectorD4) {
 
   CH_IRQ_PROLOGUE();
 
@@ -108,7 +108,7 @@ static void OutNotify1(void) {
 /*
  * USART2 IRQ service routine.
  */
-CH_IRQ_HANDLER void VectorD8(void) {
+CH_IRQ_HANDLER(VectorD8) {
 
   CH_IRQ_PROLOGUE();
 
@@ -131,7 +131,7 @@ static void OutNotify2(void) {
 /*
  * USART3 IRQ service routine.
  */
-CH_IRQ_HANDLER void VectorDC(void) {
+CH_IRQ_HANDLER(VectorDC) {
 
   CH_IRQ_PROLOGUE();
 

ports/ARMCM3/chcore.c

@@ -71,7 +71,7 @@ void threadstart(void) {
  * This interrupt is used as system tick.
  * @note The timer is initialized in the board setup code.
  */
-CH_IRQ_HANDLER void SysTickVector(void) {
+CH_IRQ_HANDLER(SysTickVector) {
 
   CH_IRQ_PROLOGUE();
 

ports/ARMCM3/chcore.h

@@ -207,9 +207,9 @@ struct context {
 }
 
 /**
- * IRQ handler function modifier.
+ * IRQ handler function declaration.
  */
-#define PORT_IRQ_HANDLER
+#define PORT_IRQ_HANDLER(id) void id(void)
 
 /**
  * This function is empty in this port.

ports/AVR/chcore.h

@@ -188,10 +188,10 @@ asm ("" : : : "r18", "r19", "r20", "r21", "r22", "r23", "r24",          \
 }
 
 /**
- * IRQ handler function modifier. Note, it just aliases the WinAVR "ISR"
+ * IRQ handler function declaration. Note, it just aliases the WinAVR "ISR"
  * macro.
  */
-#define PORT_IRQ_HANDLER ISR
+#define PORT_IRQ_HANDLER(id) ISR(id)
 
 /**
  * This function is empty in this port.

ports/MSP430/chcore.h

@@ -155,10 +155,9 @@ struct context {
 }
 
 /**
- * IRQ handler function modifier. Note, it just aliases the WinMSP "interrupt"
- * macro.
+ * IRQ handler function modifier.
  */
-#define PORT_IRQ_HANDLER interrupt
+#define PORT_IRQ_HANDLER(id) interrupt void id(void)
 
 /**
  * This function is empty in this port.

readme.txt

@@ -87,6 +87,7 @@ Win32-MinGW            - ChibiOS/RT simulator and demo into a WIN32 process,
 - Huge improvements to the ports documentation.
 - Articles and notes previously in the wiki now merged in the general
   documentation, the wiki entries are obsolete and will be removed.
+- New application notes and articles added.
 
 *** 1.0.0rc2 ***
 - FIX: Removed unused variable "retaddr" from the Cortex-M3 port.

src/include/sys.h

@@ -156,9 +156,11 @@
 #define CH_IRQ_EPILOGUE() PORT_IRQ_EPILOGUE()
 
 /**
- * Standard modifier for IRQ handler functions.
+ * Standard IRQ handler declaration.
+ * @note @p id can be a function name or a vector number depending on the
+ *       port implementation.
  */
-#define CH_IRQ_HANDLER PORT_IRQ_HANDLER
+#define CH_IRQ_HANDLER(id) PORT_IRQ_HANDLER(id)
 
 #ifdef __cplusplus
 extern "C" {

src/templates/chcore.h

@@ -122,9 +122,11 @@ struct context {
 #define PORT_IRQ_EPILOGUE()
 
 /**
- * IRQ handler function modifier.
+ * IRQ handler function declaration.
+ * @note @p id can be a function name or a vector number depending on the
+ *       port implementation.
  */
-#define PORT_IRQ_HANDLER
+#define PORT_IRQ_HANDLER(id) void id(void)
 
 #ifdef __cplusplus
 extern "C" {