diff --git a/docs/rsc/layout.xml b/docs/rsc/layout.xml index eba6d68b3..4dc8961aa 100644 --- a/docs/rsc/layout.xml +++ b/docs/rsc/layout.xml @@ -137,12 +137,12 @@ + + - - @@ -154,12 +154,12 @@ + + - - diff --git a/os/hal/dox/adc.dox b/os/hal/dox/adc.dox index 9ebfca99c..4f1cf963d 100644 --- a/os/hal/dox/adc.dox +++ b/os/hal/dox/adc.dox @@ -20,7 +20,8 @@ /** * @defgroup ADC ADC Driver * @brief Generic ADC Driver. - * @details This module implements a generic ADC driver. + * @details This module implements a generic ADC driver supporting a + * variety of buffer and conversion modes. * @pre In order to use the ADC driver the @p HAL_USE_ADC option * must be enabled in @p halconf.h. * diff --git a/os/hal/dox/can.dox b/os/hal/dox/can.dox index 81ee24e8b..550cbc79c 100644 --- a/os/hal/dox/can.dox +++ b/os/hal/dox/can.dox @@ -20,7 +20,8 @@ /** * @defgroup CAN CAN Driver * @brief Generic CAN Driver. - * @details This module implements a generic CAN driver. + * @details This module implements a generic CAN driver allowing the exchange + * of information at frame level. * @pre In order to use the CAN driver the @p HAL_USE_CAN option * must be enabled in @p halconf.h. * diff --git a/os/hal/dox/gpt.dox b/os/hal/dox/gpt.dox new file mode 100644 index 000000000..1cca2a689 --- /dev/null +++ b/os/hal/dox/gpt.dox @@ -0,0 +1,76 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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 GPT GPT Driver + * @brief Generic GPT Driver. + * @details This module implements a generic timer driver. The timer can be + * programmed in order to trigger callbacks after a specified time + * period or continuously with a specified interval. + * @pre In order to use the GPT driver the @p HAL_USE_GPT option + * must be enabled in @p halconf.h. + * + * @section gpt_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="GPT_STOP\nLow Power"]; + uninit [label="GPT_UNINIT", style="bold"]; + ready [label="GPT_READY\nClock Enabled"]; + continuous [label="GPT_CONT..S\nContinuous\nMode"]; + oneshot [label="GPT_ONESHOT\nOne Shot\nMode"]; + + uninit -> stop [label=" gptInit()", constraint=false]; + stop -> stop [label="\ngptStop()"]; + stop -> ready [label="\ngptStart()"]; + ready -> stop [label="\ngptStop()"]; + ready -> ready [label="\ngptStart()"]; + ready -> continuous [label="\ngptStartContinuous()"]; + continuous -> ready [label="\ngptStopTimer()"]; + continuous -> continuous [label=">callback<"]; + ready -> oneshot [label="\ngptStartOneShot()\ngptPolledDelay()"]; + oneshot -> ready [label="\n>callback<\nor\nDelay Over"]; + } + * @enddot + * + * @section gpt_2 GPT Operations. + * This driver abstracts a generic timer composed of: + * - A clock prescaler. + * - A main up counter. + * - A comparator register that resets the main counter to zero when the limit + * is reached. A callback is invoked when this happens. + * . + * The timer can operate in three different modes: + * - Continuous Mode, a periodic callback is invoked until the driver + * is explicitly stopped. + * - One Shot Mode, a callback is invoked after the programmed period + * and then the timer automatically stops. + * - Delay Mode, the timer is used for inserting a brief delay into + * the execution flow, no callback is invoked in this mode. + * . + * @ingroup IO + */ diff --git a/os/hal/dox/mac.dox b/os/hal/dox/mac.dox index 778795f15..903397749 100644 --- a/os/hal/dox/mac.dox +++ b/os/hal/dox/mac.dox @@ -20,8 +20,8 @@ /** * @defgroup MAC MAC Driver * @brief Generic MAC driver. - * @details This module implements a generic interface for MAC (Media - * Access Control) drivers, as example Ethernet controllers. + * @details This module implements a generic MAC (Media Access Control) + * driver for Ethernet controllers. * @pre In order to use the MAC driver the @p HAL_USE_MAC option * must be enabled in @p halconf.h. * diff --git a/os/hal/dox/mmc_spi.dox b/os/hal/dox/mmc_spi.dox index e18ff1a8a..9ccdeb2bc 100644 --- a/os/hal/dox/mmc_spi.dox +++ b/os/hal/dox/mmc_spi.dox @@ -20,7 +20,7 @@ /** * @defgroup MMC_SPI MMC over SPI Driver * @brief Generic MMC driver. - * @details This module implements a portable MMC driver that uses a SPI + * @details This module implements a portable MMC/SD driver that uses a SPI * driver as physical layer. * @pre In order to use the MMC_SPI driver the @p HAL_USE_MMC_SPI option * must be enabled in @p halconf.h. diff --git a/os/hal/dox/pal.dox b/os/hal/dox/pal.dox index 4c7fe685a..63e428377 100644 --- a/os/hal/dox/pal.dox +++ b/os/hal/dox/pal.dox @@ -19,19 +19,21 @@ /** * @defgroup PAL PAL Driver - * @brief I/O Ports Abstraction Layer + * @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 - * PAL Low Level Driver 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 PAL Low Level Driver 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. + * Note that most I/O ports functions are just macros. The macros + * have default software implementations that can be redefined in a + * PAL Low Level Driver if the target hardware supports special + * features like, for 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 PAL Low Level Driver 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. * @pre In order to use the PAL driver the @p HAL_USE_PAL option * must be enabled in @p halconf.h. * diff --git a/os/hal/dox/pwm.dox b/os/hal/dox/pwm.dox index 6fbe2efa1..1cb13056e 100644 --- a/os/hal/dox/pwm.dox +++ b/os/hal/dox/pwm.dox @@ -19,7 +19,7 @@ /** * @defgroup PWM PWM Driver - * @brief Generic PWM Driver. + * @brief Generic PWM Driver. * @details This module implements a generic PWM driver. * @pre In order to use the PWM driver the @p HAL_USE_PWM option * must be enabled in @p halconf.h. @@ -45,8 +45,9 @@ } * @enddot * - * @section pwm_1 PWM Operations. - * This driver abstracts a generic PWM times composed of: + * @section pwm_2 PWM Operations. + * This driver abstracts a generic PWM timer composed of: + * - A clock prescaler. * - A main up counter. * - A comparator register that resets the main counter to zero when the limit * is reached. An optional callback can be generated when this happens. diff --git a/os/hal/dox/serial.dox b/os/hal/dox/serial.dox index 071b2dac5..d4f2cf634 100644 --- a/os/hal/dox/serial.dox +++ b/os/hal/dox/serial.dox @@ -19,14 +19,14 @@ /** * @defgroup SERIAL Serial Driver - * @brief Generic Serial Driver. + * @brief Generic Serial Driver. * @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. + * 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. * @pre In order to use the SERIAL driver the @p HAL_USE_SERIAL option * must be enabled in @p halconf.h. * diff --git a/os/hal/dox/serial_usb.dox b/os/hal/dox/serial_usb.dox index 599ee3c16..0f857052b 100644 --- a/os/hal/dox/serial_usb.dox +++ b/os/hal/dox/serial_usb.dox @@ -19,7 +19,7 @@ /** * @defgroup SERIAL_USB Serial over USB Driver - * @brief Serial over USB Driver. + * @brief Serial over USB Driver. * @details This module implements an USB Communication Device Class * (CDC) as a normal serial communication port accessible from * the device application. diff --git a/os/hal/dox/spi.dox b/os/hal/dox/spi.dox index 7f68f3c40..7c43fec6e 100644 --- a/os/hal/dox/spi.dox +++ b/os/hal/dox/spi.dox @@ -19,8 +19,10 @@ /** * @defgroup SPI SPI Driver - * @brief Generic SPI Driver. - * @details This module implements a generic SPI driver. + * @brief Generic SPI Driver. + * @details This module implements a generic SPI driver allowing bidirectional + * and monodirectional transfers, complex atomic transactions are + * supported as well. * @pre In order to use the SPI driver the @p HAL_USE_SPI option * must be enabled in @p halconf.h. * diff --git a/os/hal/dox/uart.dox b/os/hal/dox/uart.dox index 192ce4d91..53339046d 100644 --- a/os/hal/dox/uart.dox +++ b/os/hal/dox/uart.dox @@ -19,26 +19,27 @@ /** * @defgroup UART UART Driver - * @brief Generic UART Driver. + * @brief Generic UART Driver. * @details This driver abstracts a generic UART peripheral, the API is - * designed to be: - * - Unbuffered and copy-less, transfers are always directly performed - * from/to the application-level buffers without extra copy operations. - * - Asynchronous, the API is always non blocking. - * - Callbacks capable, operations completion and other events are notified - * via callbacks. - * . - * Special hardware features like deep hardware buffers, DMA transfers - * are hidden to the user but fully supportable by the low level - * implementations.
- * This driver model is best used where communication events are meant to - * drive an higher level state machine, as example: - * - RS485 drivers. - * - Multipoint network drivers. - * - Serial protocol decoders. - * . - * If your application requires a synchronoyus buffered driver then the - * @ref SERIAL should be used instead. + * designed to be: + * - Unbuffered and copy-less, transfers are always directly performed + * from/to the application-level buffers without extra copy + * operations. + * - Asynchronous, the API is always non blocking. + * - Callbacks capable, operations completion and other events are + * notified using callbacks. + * . + * Special hardware features like deep hardware buffers, DMA transfers + * are hidden to the user but fully supportable by the low level + * implementations.
+ * This driver model is best used where communication events are + * meant to drive an higher level state machine, as example: + * - RS485 drivers. + * - Multipoint network drivers. + * - Serial protocol decoders. + * . + * If your application requires a synchronoyus buffered driver then + * the @ref SERIAL should be used instead. * @pre In order to use the UART driver the @p HAL_USE_UART option * must be enabled in @p halconf.h. * diff --git a/os/hal/dox/usb.dox b/os/hal/dox/usb.dox index 1f843efae..e9c6687ce 100644 --- a/os/hal/dox/usb.dox +++ b/os/hal/dox/usb.dox @@ -19,8 +19,9 @@ /** * @defgroup USB USB Driver - * @brief Generic USB Driver. - * @details This module implements a generic USB driver. + * @brief Generic USB Driver. + * @details This module implements a generic USB driver supporting device-mode + * operations. * @pre In order to use the USB driver the @p HAL_USE_USB option * must be enabled in @p halconf.h. * diff --git a/os/hal/include/usb.h b/os/hal/include/usb.h index d569a6031..24b492e2f 100644 --- a/os/hal/include/usb.h +++ b/os/hal/include/usb.h @@ -385,6 +385,7 @@ typedef const USBDescriptor * (*usbgetdescriptor_t)(USBDriver *usbp, * @param[in] usbp pointer to the @p USBDriver object * @param[in] buf pointer to a buffer for the transaction data * @param[in] n number of bytes to be transferred + * @param[in] endcb callback to be invoked after the transfer or @p NULL * * @api */ diff --git a/os/hal/platforms/STM32/platform.dox b/os/hal/platforms/STM32/platform.dox index 91f0addca..8edf27161 100644 --- a/os/hal/platforms/STM32/platform.dox +++ b/os/hal/platforms/STM32/platform.dox @@ -99,6 +99,25 @@ * @ingroup STM32_DRIVERS */ +/** + * @defgroup STM32_GPT STM32 GPT Support + * @details The STM32 GPT driver uses the TIMx peripherals. + * + * @section stm32_gpt_1 Supported HW resources + * - TIM1. + * - TIM2. + * - TIM3. + * - TIM4. + * - TIM5. + * . + * @section stm32_gpt_2 STM32 GPT driver implementation features + * - Each timer can be independently enabled and programmed. Unused + * peripherals are left in low power mode. + * - Programmable TIMx interrupts priority level. + * . + * @ingroup STM32_DRIVERS + */ + /** * @defgroup STM32_PAL STM32 GPIO Support * @details The STM32 PAL driver uses the GPIO peripherals. @@ -158,6 +177,7 @@ * - TIM2. * - TIM3. * - TIM4. + * - TIM5. * . * @section stm32_pwm_2 STM32 PWM driver implementation features * - Each timer can be independently enabled and programmed. Unused diff --git a/os/hal/src/serial_usb.c b/os/hal/src/serial_usb.c index 83f1c93ff..0393ad141 100644 --- a/os/hal/src/serial_usb.c +++ b/os/hal/src/serial_usb.c @@ -167,12 +167,6 @@ void sduInit(void) { * outside, usually in the hardware initialization code. * * @param[out] sdup pointer to a @p SerialUSBDriver structure - * @param[in] inotify pointer to a callback function that is invoked when - * some data is read from the Queue. The value can be - * @p NULL. - * @param[in] onotify pointer to a callback function that is invoked when - * some data is written in the Queue. The value can be - * @p NULL. * * @init */ @@ -244,6 +238,11 @@ void sduStop(SerialUSBDriver *sdup) { * - CDC_SET_LINE_CODING. * - CDC_SET_CONTROL_LINE_STATE. * . + * + * @param[in] usbp pointer to the @p USBDriver object + * @return The hook status. + * @retval TRUE Message handled internally. + * @retval FALSE Message not handled. */ bool_t sduRequestsHook(USBDriver *usbp) { @@ -270,6 +269,9 @@ bool_t sduRequestsHook(USBDriver *usbp) { * @brief Default data transmitted callback. * @details The application must use this function as callback for the IN * data endpoint. + * + * @param[in] usbp pointer to the @p USBDriver object + * @param[in] ep endpoint number */ void sduDataTransmitted(USBDriver *usbp, usbep_t ep) { SerialUSBDriver *sdup = usbp->param; @@ -294,6 +296,9 @@ void sduDataTransmitted(USBDriver *usbp, usbep_t ep) { * @brief Default data received callback. * @details The application must use this function as callback for the OUT * data endpoint. + * + * @param[in] usbp pointer to the @p USBDriver object + * @param[in] ep endpoint number */ void sduDataReceived(USBDriver *usbp, usbep_t ep) { SerialUSBDriver *sdup = usbp->param; @@ -319,6 +324,9 @@ void sduDataReceived(USBDriver *usbp, usbep_t ep) { * @brief Default data received callback. * @details The application must use this function as callback for the IN * interrupt endpoint. + * + * @param[in] usbp pointer to the @p USBDriver object + * @param[in] ep endpoint number */ void sduInterruptTransmitted(USBDriver *usbp, usbep_t ep) {