From 79089d6352e01e1e7c6c3f0a88266abbc9af6abb Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 19 Jan 2009 15:10:41 +0000 Subject: [PATCH] git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@644 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/ch.txt | 15 +++++++----- docs/src/atomic.dox | 12 ++-------- docs/src/interrupts.dox | 34 +++++++++++++++++++++++++++ docs/src/saveram.dox | 25 +++++++++----------- ports/ARM7-AT91SAM7X/sam7x_emac.c | 2 +- ports/ARM7-AT91SAM7X/sam7x_serial.c | 4 ++-- ports/ARM7-AT91SAM7X/sam7x_serial.h | 4 ++-- ports/ARM7-LPC214x/lpc214x_serial.c | 4 ++-- ports/ARM7-LPC214x/lpc214x_serial.h | 4 ++-- ports/ARM7/chcore.h | 4 ++-- ports/ARM7/port.dox | 2 +- ports/ARMCM3-STM32F103/stm32_serial.c | 6 ++--- ports/ARMCM3/chcore.c | 2 +- ports/ARMCM3/chcore.h | 4 ++-- ports/AVR/chcore.h | 4 ++-- ports/MSP430/chcore.h | 5 ++-- readme.txt | 1 + src/include/sys.h | 6 +++-- src/templates/chcore.h | 6 +++-- 19 files changed, 87 insertions(+), 57 deletions(-) create mode 100644 docs/src/interrupts.dox diff --git a/docs/ch.txt b/docs/ch.txt index 5048cf5f6..70aeda6a4 100644 --- a/docs/ch.txt +++ b/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 (ちびOS/RT) \endhtmlonly + * + *

Chibi ?

+ * 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 (ちびOS/RT) @endhtmlonly * means small Real Time Operating System. * Source Wikipedia. - * @section ch_features Features + *

Features

* - 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: + *

Related pages

* - @subpage Concepts * - @subpage Articles */ @@ -241,6 +243,7 @@ * * - @subpage article_atomic * - @subpage article_saveram + * - @subpage article_interrupts */ /** @} */ @@ -491,7 +494,7 @@ *

Operation Mode

* 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.
* Messages are usually processed in FIFO order but it is possible to process 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.
+ * 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. + *

Important Notes

+ * - 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 - + 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 - -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 diff --git a/ports/ARM7-AT91SAM7X/sam7x_emac.c b/ports/ARM7-AT91SAM7X/sam7x_emac.c index 05701b369..21c7808b0 100644 --- a/ports/ARM7-AT91SAM7X/sam7x_emac.c +++ b/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(); diff --git a/ports/ARM7-AT91SAM7X/sam7x_serial.c b/ports/ARM7-AT91SAM7X/sam7x_serial.c index 023b98527..c13701847 100644 --- a/ports/ARM7-AT91SAM7X/sam7x_serial.c +++ b/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(); diff --git a/ports/ARM7-AT91SAM7X/sam7x_serial.h b/ports/ARM7-AT91SAM7X/sam7x_serial.h index 4eac6e22f..f526f7840 100644 --- a/ports/ARM7-AT91SAM7X/sam7x_serial.h +++ b/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 diff --git a/ports/ARM7-LPC214x/lpc214x_serial.c b/ports/ARM7-LPC214x/lpc214x_serial.c index ececd30c4..527f99f59 100644 --- a/ports/ARM7-LPC214x/lpc214x_serial.c +++ b/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(); diff --git a/ports/ARM7-LPC214x/lpc214x_serial.h b/ports/ARM7-LPC214x/lpc214x_serial.h index e3afda35f..d7844a49d 100644 --- a/ports/ARM7-LPC214x/lpc214x_serial.h +++ b/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 diff --git a/ports/ARM7/chcore.h b/ports/ARM7/chcore.h index 20255d652..1e99f7e16 100644 --- a/ports/ARM7/chcore.h +++ b/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. diff --git a/ports/ARM7/port.dox b/ports/ARM7/port.dox index 9a9f319a6..fce2f9cd7 100644 --- a/ports/ARM7/port.dox +++ b/ports/ARM7/port.dox @@ -85,7 +85,7 @@ * registers.
* Example: * @code - * CH_IRQ_HANDLER void irq_handler(void) { + * CH_IRQ_HANDLER(irq_handler) { * CH_IRQ_PROLOGUE(); * * serve_interrupt(); diff --git a/ports/ARMCM3-STM32F103/stm32_serial.c b/ports/ARMCM3-STM32F103/stm32_serial.c index c17d7a56c..d54291b75 100644 --- a/ports/ARMCM3-STM32F103/stm32_serial.c +++ b/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(); diff --git a/ports/ARMCM3/chcore.c b/ports/ARMCM3/chcore.c index 61741c216..91971b866 100644 --- a/ports/ARMCM3/chcore.c +++ b/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(); diff --git a/ports/ARMCM3/chcore.h b/ports/ARMCM3/chcore.h index 505668698..638995f1c 100644 --- a/ports/ARMCM3/chcore.h +++ b/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. diff --git a/ports/AVR/chcore.h b/ports/AVR/chcore.h index 141255d8b..ab2d2f6d5 100644 --- a/ports/AVR/chcore.h +++ b/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. diff --git a/ports/MSP430/chcore.h b/ports/MSP430/chcore.h index 08240835a..ee184be53 100644 --- a/ports/MSP430/chcore.h +++ b/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. diff --git a/readme.txt b/readme.txt index 422dd426f..4e95317ea 100644 --- a/readme.txt +++ b/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. diff --git a/src/include/sys.h b/src/include/sys.h index 29f049f47..0e08452d9 100644 --- a/src/include/sys.h +++ b/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" { diff --git a/src/templates/chcore.h b/src/templates/chcore.h index 7c3fe4f0d..97f3f05e7 100644 --- a/src/templates/chcore.h +++ b/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" {