From 49c40ba106e8fbea8e67157591eab7bf0c9e9a01 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 30 Aug 2009 08:49:10 +0000 Subject: [PATCH] git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1136 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 147 ------------------------- os/io/io.dox | 137 +++++++++++++++++++++++ os/io/platforms/AT91SAM7X/platform.dox | 6 +- os/io/platforms/AT91SAM7X/serial_lld.h | 6 +- os/io/platforms/AVR/platform.dox | 2 +- os/io/platforms/AVR/serial_lld.h | 6 +- os/io/platforms/LPC214x/platform.dox | 6 +- os/io/platforms/LPC214x/serial_lld.h | 6 +- os/io/platforms/MSP430/platform.dox | 4 +- os/io/platforms/MSP430/serial_lld.h | 6 +- os/io/platforms/STM32F103/platform.dox | 18 +-- os/io/platforms/STM32F103/serial_lld.c | 6 +- os/io/platforms/STM32F103/serial_lld.h | 8 +- os/io/templates/serial_lld.h | 2 +- os/various/various.dox | 6 +- test/test.dox | 47 ++++++++ 16 files changed, 217 insertions(+), 196 deletions(-) create mode 100644 os/io/io.dox create mode 100644 test/test.dox diff --git a/docs/src/main.dox b/docs/src/main.dox index 59cb75e2c..ee1a2654c 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -64,150 +64,3 @@ * - @subpage testsuite * . */ - -/** - * @page testsuite Test Suite - *

Description

- * Most of the ChibiOS/RT demos link a set of software modules (test suite) in - * order to verify the proper working of the kernel, the port and the demo - * itself.
- * Each Test Module performs a series of tests on a specified subsystem or - * subsystems and can report a failure/success status and/or a performance - * index as the test suite output.
- * The test suite is usually activated in the demo applications by pressing a - * button on the target board, see the readme into the various demos - * directories. The test suite output is usually sent through a serial port and - * can be examined by using a terminal emulator program. - * - *

Test Modules

- * - @subpage test_threads - * - @subpage test_dynamic - * - @subpage test_msg - * - @subpage test_sem - * - @subpage test_mtx - * - @subpage test_events - * - @subpage test_mbox - * - @subpage test_queues - * - @subpage test_heap - * - @subpage test_pools - * - @subpage test_benchmarks - * . - */ - -/** - * @defgroup IO I/O Support - * @brief I/O related services. - * @details This section contains the I/O related services. - * - * The I/O subsystem is a collection of device driver poertable interfaces and - * platform dependent implementations.
- * Under ChibiOS/RT a device driver is split in two layers: - * - High Level Device Driver (HLD). This layer contains the definitions - * of the driver's APIs and the platform independent part of the driver.
- * An HLD is composed by two files: - * - @.c, the high level implementation file. This file must be - * included in the Makefile in order to use the driver. - * - @.h, the high level header file. This file must be included - * by the application code in order to access the driver's APIs. - * . - * - Low Level Device Driver (LLD). This layer contains the platform - * dependent part of the driver.
- * A LLD is composed by two files: - * - @_lld.c, the low level implementation file. This file must be - * included in the Makefile in order to use the driver. - * - @_lld.h, the high level header file. This file is implicitly - * included by the HLD header file. - * . - * . - *

Available Device Drivers

- * The I/O subsystem currently includes support for: - * - @ref PAL. - * - @ref SERIAL. - * . - */ - -/** - * @defgroup PAL I/O Ports Abstraction Layer (PAL) - * @brief I/O Ports Abstraction Layer - * @details This module defines an abstract interface for digital I/O ports. - * Note that most I/O ports functions are just macros. The macros - * have default software implementations that can be redefined in a - * @ref PAL_LLD if the target hardware supports special features like, as - * example, atomic bit set/reset/masking. Please refer to the ports specific - * documentation for details.
- * The @ref PAL has the advantage to make the access to the I/O ports platform - * independent and still be optimized for the specific architectures.
- * Note that the @ref PAL_LLD may also offer non standard macro and functions - * in order to support specific features but, of course, the use of such - * interfaces would not be portable. Such interfaces shall be marked with - * the architecture name inside the function names. - * - *

Implementation Rules

- * In implementing an @ref PAL_LLD there are some rules/behaviors that - * should be respected. - * - *

Writing on input pads

- * The behavior is not specified but there are implementations better than - * others, this is the list of possible implementations, preferred options - * are on top: - * -# The written value is not actually output but latched, should the pads - * be reprogrammed as outputs the value would be in effect. - * -# The write operation is ignored. - * -# The write operation has side effects, as example disabling/enabling - * pull up/down resistors or changing the pad direction. This scenario is - * discouraged, please try to avoid this scenario. - * . - *

Reading from output pads

- * The behavior is not specified but there are implementations better than - * others, this is the list of possible implementations, preferred options - * are on top: - * -# The actual pads states are read (not the output latch). - * -# The output latch value is read (regardless of the actual pads states). - * -# Unspecified, please try to avoid this scenario. - * . - *

Writing unused or unimplemented port bits

- * The behavior is not specified. - * - *

Reading from unused or unimplemented port bits

- * The behavior is not specified. - * - *

Reading or writing on pins associated to other functionalities

- * The behavior is not specified. - * - *

Usage

- * The use of I/O ports requires the inclusion of the header file @p pal.h, - * this file is not automatically included @p ch.h like the other header - * files. - * - * @ingroup IO - */ - -/** - * @defgroup PAL_LLD PAL Low Level Driver - * @brief @ref PAL low level driver template. - * @details This file is a template for an I/O port low level driver. - * - * @ingroup PAL - */ - -/** - * @defgroup SERIAL Serial Driver - * @brief Generic Serial Drivers. - * @details This module implements a generic full duplex serial driver. The - * driver implements a @p SerialDriver interface and uses I/O Queues for - * communication between the upper and the lower driver. Event flags are used - * to notify the application about incoming data, outgoing data and other I/O - * events.
- * The module also contains functions that make the implementation of the - * interrupt service routines much easier.
- * - * @ingroup IO - */ - -/** - * @defgroup SERIAL_LLD Serial Low Level Driver - * @brief @ref SERIAL low level driver template. - * @details This file is a template for a serial low level driver. - * - * @ingroup SERIAL - */ diff --git a/os/io/io.dox b/os/io/io.dox new file mode 100644 index 000000000..aec740168 --- /dev/null +++ b/os/io/io.dox @@ -0,0 +1,137 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + + +/** + * @defgroup IO I/O + * @brief I/O related services. + * @details This section contains the I/O related services. + * + * The I/O subsystem is a collection of device driver poertable interfaces and + * platform dependent implementations.
+ * Under ChibiOS/RT a device driver is split in two layers: + * - High Level Device Driver (HLD). This layer contains the definitions + * of the driver's APIs and the platform independent part of the driver.
+ * An HLD is composed by two files: + * - @.c, the high level implementation file. This file must be + * included in the Makefile in order to use the driver. + * - @.h, the high level header file. This file must be included + * by the application code in order to access the driver's APIs. + * . + * - Low Level Device Driver (LLD). This layer contains the platform + * dependent part of the driver.
+ * A LLD is composed by two files: + * - @_lld.c, the low level implementation file. This file must be + * included in the Makefile in order to use the driver. + * - @_lld.h, the high level header file. This file is implicitly + * included by the HLD header file. + * . + * . + *

Available Device Drivers

+ * The I/O subsystem currently includes support for: + * - @ref PAL. + * - @ref SERIAL. + * . + */ + +/** + * @defgroup PAL Ports Abstraction Layer (PAL) + * @brief I/O Ports Abstraction Layer + * @details This module defines an abstract interface for digital I/O ports. + * Note that most I/O ports functions are just macros. The macros + * have default software implementations that can be redefined in a + * @ref PAL_LLD if the target hardware supports special features like, as + * example, atomic bit set/reset/masking. Please refer to the ports specific + * documentation for details.
+ * The @ref PAL has the advantage to make the access to the I/O ports platform + * independent and still be optimized for the specific architectures.
+ * Note that the @ref PAL_LLD may also offer non standard macro and functions + * in order to support specific features but, of course, the use of such + * interfaces would not be portable. Such interfaces shall be marked with + * the architecture name inside the function names. + * + *

Implementation Rules

+ * In implementing an @ref PAL_LLD there are some rules/behaviors that + * should be respected. + * + *

Writing on input pads

+ * The behavior is not specified but there are implementations better than + * others, this is the list of possible implementations, preferred options + * are on top: + * -# The written value is not actually output but latched, should the pads + * be reprogrammed as outputs the value would be in effect. + * -# The write operation is ignored. + * -# The write operation has side effects, as example disabling/enabling + * pull up/down resistors or changing the pad direction. This scenario is + * discouraged, please try to avoid this scenario. + * . + *

Reading from output pads

+ * The behavior is not specified but there are implementations better than + * others, this is the list of possible implementations, preferred options + * are on top: + * -# The actual pads states are read (not the output latch). + * -# The output latch value is read (regardless of the actual pads states). + * -# Unspecified, please try to avoid this scenario. + * . + *

Writing unused or unimplemented port bits

+ * The behavior is not specified. + * + *

Reading from unused or unimplemented port bits

+ * The behavior is not specified. + * + *

Reading or writing on pins associated to other functionalities

+ * The behavior is not specified. + * + *

Usage

+ * The use of I/O ports requires the inclusion of the header file @p pal.h, + * this file is not automatically included @p ch.h like the other header + * files. + * + * @ingroup IO + */ + +/** + * @defgroup PAL_LLD PAL Low Level Driver template + * @brief @ref PAL low level driver template. + * @details This file is a template for an I/O port low level driver. + * + * @ingroup PAL + */ + +/** + * @defgroup SERIAL Serial Driver + * @brief Generic Serial Drivers. + * @details This module implements a generic full duplex serial driver. The + * driver implements a @p SerialDriver interface and uses I/O Queues for + * communication between the upper and the lower driver. Event flags are used + * to notify the application about incoming data, outgoing data and other I/O + * events.
+ * The module also contains functions that make the implementation of the + * interrupt service routines much easier.
+ * + * @ingroup IO + */ + +/** + * @defgroup SERIAL_LLD Serial Low Level Driver template + * @brief @ref SERIAL low level driver template. + * @details This file is a template for a serial low level driver. + * + * @ingroup SERIAL + */ diff --git a/os/io/platforms/AT91SAM7X/platform.dox b/os/io/platforms/AT91SAM7X/platform.dox index dac6ed181..6176140ad 100644 --- a/os/io/platforms/AT91SAM7X/platform.dox +++ b/os/io/platforms/AT91SAM7X/platform.dox @@ -30,7 +30,7 @@ */ /** - * @defgroup AT91SAM7X_PAL I/O Ports Support + * @defgroup AT91SAM7X_PAL AT91SAM7X I/O Ports Support * @brief I/O Ports peripherals support. * @details This module supports the AT91SAM7X PIO controller. The controller * supports the following features (see @ref PAL): @@ -58,7 +58,7 @@ */ /** - * @defgroup AT91SAM7X_SERIAL USART Support + * @defgroup AT91SAM7X_SERIAL AT91SAM7X USART Support * @brief USART peripherals support. * @details The serial driver supports the AT91SAM7X USART peripherals. * @@ -66,7 +66,7 @@ */ /** - * @defgroup AT91SAM7X_EMAC EMAC Support + * @defgroup AT91SAM7X_EMAC AT91SAM7X EMAC Support * @brief EMAC peripheral support. * * @ingroup AT91SAM7X diff --git a/os/io/platforms/AT91SAM7X/serial_lld.h b/os/io/platforms/AT91SAM7X/serial_lld.h index 639c4055d..41975a524 100644 --- a/os/io/platforms/AT91SAM7X/serial_lld.h +++ b/os/io/platforms/AT91SAM7X/serial_lld.h @@ -120,13 +120,9 @@ struct _serial_driver_data { }; /** - * @brief Generic Serial Driver static initializer. + * @brief AT91SAM7X Serial Driver configuration structure. * @details An instance of this structure must be passed to @p sdStart() * in order to configure and start a serial driver operations. - * - * @note This structure content is architecture dependent, each driver - * implementation defines its own version and the custom static - * initializers. */ typedef struct { uint32_t speed; diff --git a/os/io/platforms/AVR/platform.dox b/os/io/platforms/AVR/platform.dox index d41c0aacf..05eb4d76e 100644 --- a/os/io/platforms/AVR/platform.dox +++ b/os/io/platforms/AVR/platform.dox @@ -25,7 +25,7 @@ */ /** - * @defgroup AVR_SERIAL USART Support + * @defgroup AVR_SERIAL AVR USART Support * @brief USART support. * @details The serial driver supports both the AVR USARTs in asynchronous * mode. diff --git a/os/io/platforms/AVR/serial_lld.h b/os/io/platforms/AVR/serial_lld.h index 98e00a841..c1889f8b5 100644 --- a/os/io/platforms/AVR/serial_lld.h +++ b/os/io/platforms/AVR/serial_lld.h @@ -124,13 +124,9 @@ struct _serial_driver_data { #define UBRR(b) ((F_CPU / (b << 4)) - 1) /** - * @brief Generic Serial Driver static initializer. + * @brief AVR Serial Driver configuration structure. * @details An instance of this structure must be passed to @p sdStart() * in order to configure and start a serial driver operations. - * - * @note This structure content is architecture dependent, each driver - * implementation defines its own version and the custom static - * initializers. */ typedef struct { uint16_t brr; diff --git a/os/io/platforms/LPC214x/platform.dox b/os/io/platforms/LPC214x/platform.dox index e46ac4328..0f6536e0e 100644 --- a/os/io/platforms/LPC214x/platform.dox +++ b/os/io/platforms/LPC214x/platform.dox @@ -42,7 +42,7 @@ */ /** - * @defgroup LPC214x_PAL I/O Ports Support + * @defgroup LPC214x_PAL LPC214x I/O Ports Support * @brief I/O Ports peripherals support. * @details This module supports the LPC214x FIO controller. The controller * supports the following features (see @ref PAL): @@ -67,7 +67,7 @@ */ /** - * @defgroup LPC214x_SERIAL UART Support + * @defgroup LPC214x_SERIAL LPC214x UART Support * @brief UART peripherals support. * @details The serial driver supports the LPC214x UART peripherals. * @@ -75,7 +75,7 @@ */ /** - * @defgroup LPC214x_SSP SSP Support + * @defgroup LPC214x_SSP LPC214x SSP Support * @brief SSP peripheral support. * @details This SPI driver supports the LPC214x SSP peripheral. * diff --git a/os/io/platforms/LPC214x/serial_lld.h b/os/io/platforms/LPC214x/serial_lld.h index d4bc6d01d..b6ac8e379 100644 --- a/os/io/platforms/LPC214x/serial_lld.h +++ b/os/io/platforms/LPC214x/serial_lld.h @@ -136,13 +136,9 @@ struct _serial_driver_data { }; /** - * @brief Generic Serial Driver static initializer. + * @brief LPC214x Serial Driver configuration structure. * @details An instance of this structure must be passed to @p sdStart() * in order to configure and start a serial driver operations. - * - * @note This structure content is architecture dependent, each driver - * implementation defines its own version and the custom static - * initializers. */ typedef struct { uint32_t speed; diff --git a/os/io/platforms/MSP430/platform.dox b/os/io/platforms/MSP430/platform.dox index f840e8b75..22f404ddb 100644 --- a/os/io/platforms/MSP430/platform.dox +++ b/os/io/platforms/MSP430/platform.dox @@ -25,7 +25,7 @@ */ /** - * @defgroup MSP430_PAL I/O Ports Support + * @defgroup MSP430_PAL MSP430 I/O Ports Support * @brief I/O Ports peripherals support. * @details This module supports the MSP430 Digital I/O controller. The * controller supports the following features (see @ref PAL): @@ -51,7 +51,7 @@ */ /** - * @defgroup MSP430_SERIAL USART Support + * @defgroup MSP430_SERIAL MSP430 USART Support * @brief USART support. * @details The serial driver supports both the MSP430 USARTs in asynchronous * mode. diff --git a/os/io/platforms/MSP430/serial_lld.h b/os/io/platforms/MSP430/serial_lld.h index 255376b83..63d94046e 100644 --- a/os/io/platforms/MSP430/serial_lld.h +++ b/os/io/platforms/MSP430/serial_lld.h @@ -121,13 +121,9 @@ struct _serial_driver_data { #define UBR(b) (SMCLK / (b)) /** - * @brief Generic Serial Driver static initializer. + * @brief MSP430 Serial Driver configuration structure. * @details An instance of this structure must be passed to @p sdStart() * in order to configure and start a serial driver operations. - * - * @note This structure content is architecture dependent, each driver - * implementation defines its own version and the custom static - * initializers. */ typedef struct { uint16_t div; diff --git a/os/io/platforms/STM32F103/platform.dox b/os/io/platforms/STM32F103/platform.dox index b1828425c..6ec9fbe20 100644 --- a/os/io/platforms/STM32F103/platform.dox +++ b/os/io/platforms/STM32F103/platform.dox @@ -18,9 +18,9 @@ */ /** - * @defgroup STM32F103 STM32F103 Support - * @brief STM32F103 specific support. - * @details The STM32F103 support includes: + * @defgroup STM32 STM32 Support + * @brief STM32 specific support. + * @details The STM32 support includes: * - I/O ports driver. * - Buffered, interrupt driven, serial driver. * - A demo supporting the kernel test suite. @@ -29,9 +29,9 @@ */ /** - * @defgroup STM32F103_PAL I/O Ports Support + * @defgroup STM32_PAL STM32 I/O Ports Support * @brief I/O Ports peripherals support. - * @details This module supports the STM32F103 GPIO controller. The controller + * @details This module supports the STM3 GPIO controller. The controller * supports the following features (see @ref PAL): * - 16 bits wide ports. * - Atomic set/reset functions. @@ -58,15 +58,15 @@ * resistor can change the resistor setting because the output latch is * used for resistor selection. * . - * @ingroup STM32F103 + * @ingroup STM32 */ /** - * @defgroup STM32F103_SERIAL USART Support + * @defgroup STM32_SERIAL STM32 USART Support * @brief USART peripherals support. - * @details The serial driver supports the STM32F103 USARTs in asynchronous + * @details The serial driver supports the STM32 USARTs in asynchronous * mode. * - * @ingroup STM32F103 + * @ingroup STM32 */ \ No newline at end of file diff --git a/os/io/platforms/STM32F103/serial_lld.c b/os/io/platforms/STM32F103/serial_lld.c index 2a727dc43..29a75ac88 100644 --- a/os/io/platforms/STM32F103/serial_lld.c +++ b/os/io/platforms/STM32F103/serial_lld.c @@ -18,9 +18,9 @@ */ /** - * @file STM32F103/serial_lld.c - * @brief STM32F103 low level serial driver code - * @addtogroup STM32F103_SERIAL + * @file STM32/serial_lld.c + * @brief STM32 low level serial driver code + * @addtogroup STM32_SERIAL * @{ */ diff --git a/os/io/platforms/STM32F103/serial_lld.h b/os/io/platforms/STM32F103/serial_lld.h index a623eb308..ed80f8b5d 100644 --- a/os/io/platforms/STM32F103/serial_lld.h +++ b/os/io/platforms/STM32F103/serial_lld.h @@ -18,9 +18,9 @@ */ /** - * @file STM32F103/serial_lld.h - * @brief STM32F103 low level serial driver header - * @addtogroup STM32F103_SERIAL + * @file STM32/serial_lld.h + * @brief STM32 low level serial driver header + * @addtogroup STM32_SERIAL * @{ */ @@ -159,7 +159,7 @@ struct _serial_driver_data { }; /** - * @brief Generic Serial Driver static initializer. + * @brief STM32 Serial Driver configuration structure. * @details An instance of this structure must be passed to @p sdStart() * in order to configure and start a serial driver operations. * diff --git a/os/io/templates/serial_lld.h b/os/io/templates/serial_lld.h index ab6d8e7a2..5688368e4 100644 --- a/os/io/templates/serial_lld.h +++ b/os/io/templates/serial_lld.h @@ -78,7 +78,7 @@ struct _serial_driver_data { }; /** - * @brief Generic Serial Driver static initializer. + * @brief Generic Serial Driver configuration structure. * @details An instance of this structure must be passed to @p sdStart() * in order to configure and start a serial driver operations. * diff --git a/os/various/various.dox b/os/various/various.dox index 63872e2de..fae5e65e5 100644 --- a/os/various/various.dox +++ b/os/various/various.dox @@ -18,7 +18,7 @@ */ /** - * @defgroup utilities_library Utilities Library + * @defgroup various Various * @brief Utilities Library. * @details This is a collection of useful library code that is not part of * the base kernel services. @@ -35,7 +35,7 @@ * @details This module allows to use the ChibiOS/RT functionalities * from C++ as classes and objects rather the traditional "C" APIs. * - * @ingroup utilities_library + * @ingroup various */ /** @@ -45,5 +45,5 @@ * listening threads can use the event to perform time related activities. * Multiple threads can listen to the same timer. * - * @ingroup utilities_library + * @ingroup various */ diff --git a/test/test.dox b/test/test.dox new file mode 100644 index 000000000..ad3c03927 --- /dev/null +++ b/test/test.dox @@ -0,0 +1,47 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page testsuite Test Suite + *

Description

+ * Most of the ChibiOS/RT demos link a set of software modules (test suite) in + * order to verify the proper working of the kernel, the port and the demo + * itself.
+ * Each Test Module performs a series of tests on a specified subsystem or + * subsystems and can report a failure/success status and/or a performance + * index as the test suite output.
+ * The test suite is usually activated in the demo applications by pressing a + * button on the target board, see the readme into the various demos + * directories. The test suite output is usually sent through a serial port and + * can be examined by using a terminal emulator program. + * + *

Test Modules

+ * - @subpage test_threads + * - @subpage test_dynamic + * - @subpage test_msg + * - @subpage test_sem + * - @subpage test_mtx + * - @subpage test_events + * - @subpage test_mbox + * - @subpage test_queues + * - @subpage test_heap + * - @subpage test_pools + * - @subpage test_benchmarks + * . + */