From e3c7dc319ff582f9eb4a593950ac7bedb1d38b77 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 6 Feb 2010 16:17:30 +0000 Subject: [PATCH] git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1571 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/hal/include/adc.h | 7 +- os/hal/include/can.h | 21 +- os/hal/include/hal.h | 5 +- os/hal/include/mac.h | 39 ++-- os/hal/include/mii.h | 5 +- os/hal/include/mmc_spi.h | 29 +-- os/hal/include/pal.h | 337 +++++++++++++++-------------- os/hal/include/pwm.h | 23 +- os/hal/include/serial.h | 100 +++++---- os/hal/include/spi.h | 17 +- os/hal/src/adc.c | 38 ++-- os/hal/src/can.c | 53 ++--- os/hal/src/hal.c | 7 +- os/hal/src/mac.c | 89 ++++---- os/hal/src/mmc_spi.c | 81 ++++--- os/hal/src/pal.c | 68 +++--- os/hal/src/pwm.c | 14 +- os/hal/src/serial.c | 83 +++---- os/hal/src/spi.c | 51 ++--- os/hal/templates/meta/driver.c | 13 +- os/hal/templates/meta/driver.h | 13 +- os/hal/templates/meta/driver_lld.c | 15 +- os/hal/templates/meta/driver_lld.h | 11 +- 23 files changed, 575 insertions(+), 544 deletions(-) diff --git a/os/hal/include/adc.h b/os/hal/include/adc.h index 2aa0c41c5..76e83a51a 100644 --- a/os/hal/include/adc.h +++ b/os/hal/include/adc.h @@ -18,8 +18,9 @@ */ /** - * @file adc.h - * @brief ADC Driver macros and structures. + * @file adc.h + * @brief ADC Driver macros and structures. + * * @addtogroup ADC * @{ */ @@ -50,7 +51,7 @@ /*===========================================================================*/ /** - * @brief Driver state machine possible states. + * @brief Driver state machine possible states. */ typedef enum { ADC_UNINIT = 0, /**< @brief Not initialized. */ diff --git a/os/hal/include/can.h b/os/hal/include/can.h index 72f089379..0e171fee4 100644 --- a/os/hal/include/can.h +++ b/os/hal/include/can.h @@ -18,8 +18,9 @@ */ /** - * @file can.h - * @brief CAN Driver macros and structures. + * @file can.h + * @brief CAN Driver macros and structures. + * * @addtogroup CAN * @{ */ @@ -34,23 +35,23 @@ /*===========================================================================*/ /** - * @brief Errors rate warning. + * @brief Errors rate warning. */ #define CAN_LIMIT_WARNING 1 /** - * @brief Errors rate error. + * @brief Errors rate error. */ #define CAN_LIMIT_ERROR 2 /** - * @brief Bus off condition reached. + * @brief Bus off condition reached. */ #define CAN_BUS_OFF_ERROR 4 /** - * @brief Framing error of some kind on the CAN bus. + * @brief Framing error of some kind on the CAN bus. */ #define CAN_FRAMING_ERROR 8 /** - * @brief Overflow in receive queue. + * @brief Overflow in receive queue. */ #define CAN_OVERFLOW_ERROR 16 @@ -59,7 +60,7 @@ /*===========================================================================*/ /** - * @brief Sleep mode related APIs inclusion switch. + * @brief Sleep mode related APIs inclusion switch. */ #define CAN_USE_SLEEP_MODE TRUE @@ -76,7 +77,7 @@ /*===========================================================================*/ /** - * @brief Driver state machine possible states. + * @brief Driver state machine possible states. */ typedef enum { CAN_UNINIT = 0, /**< @brief Not initialized. */ @@ -93,7 +94,7 @@ typedef enum { /*===========================================================================*/ /** - * @brief Adds some flags to the CAN status mask. + * @brief Adds some flags to the CAN status mask. * * @param[in] canp pointer to the @p CANDriver object * @param[in] mask flags to be added to the status mask diff --git a/os/hal/include/hal.h b/os/hal/include/hal.h index cf4def764..1bdeafe8c 100644 --- a/os/hal/include/hal.h +++ b/os/hal/include/hal.h @@ -18,8 +18,9 @@ */ /** - * @file hal.h - * @brief HAL subsystem header. + * @file hal.h + * @brief HAL subsystem header. + * * @addtogroup HAL * @{ */ diff --git a/os/hal/include/mac.h b/os/hal/include/mac.h index 85da4fc57..29381bab3 100644 --- a/os/hal/include/mac.h +++ b/os/hal/include/mac.h @@ -18,8 +18,8 @@ */ /** - * @file mac.h - * @brief MAC Driver macros and structures. + * @file mac.h + * @brief MAC Driver macros and structures. * @addtogroup MAC * @{ */ @@ -56,37 +56,38 @@ /*===========================================================================*/ /** - * @brief Returns the received frames event source. + * @brief Returns the received frames event source. * - * @param[in] macp pointer to the @p MACDriver object - * @return The pointer to the @p EventSource structure. + * @param[in] macp pointer to the @p MACDriver object + * @return The pointer to the @p EventSource structure. */ #if CH_USE_EVENTS || defined(__DOXYGEN__) #define macGetReceiveEventSource(macp) (&(macp)->md_rdevent) #endif /** - * @brief Writes to a transmit descriptor's stream. + * @brief Writes to a transmit descriptor's stream. * - * @param[in] tdp pointer to a @p MACTransmitDescriptor structure - * @param[in] buf pointer to the buffer containing the data to be written - * @param[in] size number of bytes to be written - * @return The number of bytes written into the descriptor's stream, this - * value can be less than the amount specified in the parameter - * @p size if the maximum frame size is reached. + * @param[in] tdp pointer to a @p MACTransmitDescriptor structure + * @param[in] buf pointer to the buffer containing the data to be written + * @param[in] size number of bytes to be written + * @return The number of bytes written into the descriptor's + * stream, this value can be less than the amount + * specified in the parameter @p size if the maximum frame + * size is reached. */ #define macWriteTransmitDescriptor(tdp, buf, size) \ mac_lld_write_transmit_descriptor(tdp, buf, size) /** - * @brief Reads from a receive descriptor's stream. + * @brief Reads from a receive descriptor's stream. * - * @param[in] rdp pointer to a @p MACReceiveDescriptor structure - * @param[in] buf pointer to the buffer that will receive the read data - * @param[in] size number of bytes to be read - * @return The number of bytes read from the descriptor's stream, this - * value can be less than the amount specified in the parameter - * @p size if there are no more bytes to read. + * @param[in] rdp pointer to a @p MACReceiveDescriptor structure + * @param[in] buf pointer to the buffer that will receive the read data + * @param[in] size number of bytes to be read + * @return The number of bytes read from the descriptor's stream, this + * value can be less than the amount specified in the + * parameter @p size if there are no more bytes to read. */ #define macReadReceiveDescriptor(rdp, buf, size) \ mac_lld_read_receive_descriptor(rdp, buf, size) diff --git a/os/hal/include/mii.h b/os/hal/include/mii.h index 91f31e185..937b805ab 100644 --- a/os/hal/include/mii.h +++ b/os/hal/include/mii.h @@ -23,8 +23,9 @@ */ /*-* - * @file mii.h - * @brief MII Driver macros and structures. + * @file mii.h + * @brief MII Driver macros and structures. + * * @addtogroup MII * @{ */ diff --git a/os/hal/include/mmc_spi.h b/os/hal/include/mmc_spi.h index 2be2673fb..e4c3ee157 100644 --- a/os/hal/include/mmc_spi.h +++ b/os/hal/include/mmc_spi.h @@ -18,8 +18,9 @@ */ /** - * @file mmc_spi.h - * @brief MMC over SPI driver header. + * @file mmc_spi.h + * @brief MMC over SPI driver header. + * * @addtogroup MMC_SPI * @{ */ @@ -52,14 +53,14 @@ /*===========================================================================*/ /** - * @brief Block size for MMC transfers. + * @brief Block size for MMC transfers. */ #if !defined(MMC_SECTOR_SIZE) || defined(__DOXYGEN__) #define MMC_SECTOR_SIZE 512 #endif /** - * @brief Delays insertions. + * @brief Delays insertions. * @details If enabled this options inserts delays into the MMC waiting * routines releasing some extra CPU time for the threads with * lower priority, this may slow down the driver a bit however. @@ -71,15 +72,15 @@ #endif /** - * @brief Number of positive insertion queries before generating the - * insertion event. + * @brief Number of positive insertion queries before generating the + * insertion event. */ #if !defined(MMC_POLLING_INTERVAL) || defined(__DOXYGEN__) #define MMC_POLLING_INTERVAL 10 #endif /** - * @brief Interval, in milliseconds, between insertion queries. + * @brief Interval, in milliseconds, between insertion queries. */ #if !defined(MMC_POLLING_DELAY) || defined(__DOXYGEN__) #define MMC_POLLING_DELAY 10 @@ -98,7 +99,7 @@ /*===========================================================================*/ /** - * @brief Driver state machine possible states. + * @brief Driver state machine possible states. */ typedef enum { MMC_UNINIT = 0, /**< @brief Not initialized. */ @@ -111,21 +112,21 @@ typedef enum { } mmcstate_t; /** - * @brief Function used to query some hardware status bits. + * @brief Function used to query some hardware status bits. * - * @return The status. + * @return The status. */ typedef bool_t (*mmcquery_t)(void); /** - * @brief Driver configuration structure. + * @brief Driver configuration structure. */ typedef struct { } MMCConfig; /** - * @brief Structure representing a MMC driver. + * @brief Structure representing a MMC driver. */ typedef struct { /** @@ -179,12 +180,12 @@ typedef struct { /*===========================================================================*/ /** - * @brief Returns the driver state. + * @brief Returns the driver state. */ #define mmcGetDriverState(mmcp) ((mmcp)->mmc_state) /** - * @brief Returns the write protect status. + * @brief Returns the write protect status. */ #define mmcIsWriteProtected(mmcp) ((mmcp)->mmc_is_protected()) diff --git a/os/hal/include/pal.h b/os/hal/include/pal.h index ead0a4c33..e92a1e1f0 100644 --- a/os/hal/include/pal.h +++ b/os/hal/include/pal.h @@ -18,8 +18,9 @@ */ /** - * @file pal.h - * @brief I/O Ports Abstraction Layer macros, types and structures. + * @file pal.h + * @brief I/O Ports Abstraction Layer macros, types and structures. + * * @addtogroup PAL * @{ */ @@ -34,14 +35,14 @@ /*===========================================================================*/ /** - * @brief Bits in a mode word dedicated as mode selector. + * @brief Bits in a mode word dedicated as mode selector. * @details The other bits are not defined and may be used as device-specific * option bits. */ #define PAL_MODE_MASK 0xF /** - * @brief After reset state. + * @brief After reset state. * @details The state itself is not specified and is architecture dependent, * it is guaranteed to be equal to the after-reset state. It is * usually an input state. @@ -49,7 +50,7 @@ #define PAL_MODE_RESET 0 /** - * @brief Safe state for unconnected pads. + * @brief Safe state for unconnected pads. * @details The state itself is not specified and is architecture dependent, * it may be mapped on @p PAL_MODE_INPUT_PULLUP, * @p PAL_MODE_INPUT_PULLDOWN or @p PAL_MODE_OUTPUT_PUSHPULL as @@ -58,42 +59,42 @@ #define PAL_MODE_UNCONNECTED 1 /** - * @brief Regular input high-Z pad. + * @brief Regular input high-Z pad. */ #define PAL_MODE_INPUT 2 /** - * @brief Input pad with weak pull up resistor. + * @brief Input pad with weak pull up resistor. */ #define PAL_MODE_INPUT_PULLUP 3 /** - * @brief Input pad with weak pull down resistor. + * @brief Input pad with weak pull down resistor. */ #define PAL_MODE_INPUT_PULLDOWN 4 /** - * @brief Analog input mode. + * @brief Analog input mode. */ #define PAL_MODE_INPUT_ANALOG 5 /** - * @brief Push-pull output pad. + * @brief Push-pull output pad. */ #define PAL_MODE_OUTPUT_PUSHPULL 6 /** - * @brief Open-drain output pad. + * @brief Open-drain output pad. */ #define PAL_MODE_OUTPUT_OPENDRAIN 7 /** - * @brief Logical low state. + * @brief Logical low state. */ #define PAL_LOW 0 /** - * @brief Logical high state. + * @brief Logical high state. */ #define PAL_HIGH 1 @@ -112,19 +113,26 @@ #include "pal_lld.h" /** - * @brief I/O bus descriptor. + * @brief I/O bus descriptor. * @details This structure describes a group of contiguous digital I/O lines * that have to be handled as bus. - * @note I/O operations on a bus do not affect I/O lines on the same port but - * not belonging to the bus. + * @note I/O operations on a bus do not affect I/O lines on the same port but + * not belonging to the bus. */ typedef struct { - /** Port identifier.*/ + /** + * @brief Port identifier. + */ ioportid_t bus_portid; - /** Bus mask aligned to port bit 0. The bus mask implicitly define the bus - width. A logical AND is performed on the bus data.*/ + /** + * @brief Bus mask aligned to port bit 0. + * @note The bus mask implicitly define the bus width. A logical AND is + * performed on the bus data. + */ ioportmask_t bus_mask; - /** Offset, within the port, of the least significant bit of the bus.*/ + /** + * @brief Offset, within the port, of the least significant bit of the bus. + */ uint_fast8_t bus_offset; } IOBus; @@ -133,50 +141,50 @@ typedef struct { /*===========================================================================*/ /** - * @brief Port bit helper macro. + * @brief Port bit helper macro. * @details This macro calculates the mask of a bit within a port. * - * @param[in] n the bit position within the port - * @return The bit mask. + * @param[in] n the bit position within the port + * @return The bit mask. */ #define PAL_PORT_BIT(n) ((ioportmask_t)(1 << (n))) /** - * @brief Bits group mask helper. + * @brief Bits group mask helper. * @details This macro calculates the mask of a bits group. * - * @param[in] width the group width - * @return The group mask. + * @param[in] width the group width + * @return The group mask. */ #define PAL_GROUP_MASK(width) ((ioportmask_t)(1 << (width)) - 1) /** - * @brief Data part of a static I/O bus initializer. + * @brief Data part of a static I/O bus initializer. * @details This macro should be used when statically initializing an I/O bus * that is part of a bigger structure. * - * @param name the name of the IOBus variable - * @param port the I/O port descriptor - * @param width the bus width in bits - * @param offset the bus bit offset within the port + * @param[in] name the name of the IOBus variable + * @param[in] port the I/O port descriptor + * @param[in] width the bus width in bits + * @param[in] offset the bus bit offset within the port */ #define _IOBUS_DATA(name, port, width, offset) \ {port, PAL_GROUP_MASK(width), offset} /** - * @brief Static I/O bus initializer. + * @brief Static I/O bus initializer. * - * @param name the name of the IOBus variable - * @param port the I/O port descriptor - * @param width the bus width in bits - * @param offset the bus bit offset within the port + * @param[in] name the name of the IOBus variable + * @param[in] port the I/O port descriptor + * @param[in] width the bus width in bits + * @param[in] offset the bus bit offset within the port */ #define IOBUS_DECL(name, port, width, offset) \ IOBus name = _IOBUS_DATA(name, port, width, offset) /** - * @brief PAL subsystem initialization. + * @brief PAL subsystem initialization. * * @param[in] config pointer to an architecture specific configuration * structure. This structure is defined in the low level driver @@ -185,13 +193,12 @@ typedef struct { #define palInit(config) pal_lld_init(config) /** - * @brief Reads the physical I/O port states. + * @brief Reads the physical I/O port states. + * @note The default implementation always return zero and computes the + * parameter eventual side effects. * - * @param[in] port the port identifier - * @return The port logical states. - * - * @note The default implementation always return zero and computes the - * parameter eventual side effects. + * @param[in] port the port identifier + * @return The port logical states. */ #if !defined(pal_lld_readport) || defined(__DOXYGEN__) #define palReadPort(port) ((void)(port), 0) @@ -200,15 +207,14 @@ typedef struct { #endif /** - * @brief Reads the output latch. + * @brief Reads the output latch. * @details The purpose of this function is to read back the latched output * value. + * @note The default implementation always return zero and computes the + * parameter eventual side effects. * - * @param[in] port the port identifier - * @return The latched logical states. - * - * @note The default implementation always return zero and computes the - * parameter eventual side effects. + * @param[in] port the port identifier + * @return The latched logical states. */ #if !defined(pal_lld_readlatch) || defined(__DOXYGEN__) #define palReadLatch(port) ((void)(port), 0) @@ -217,13 +223,12 @@ typedef struct { #endif /** - * @brief Writes a bits mask on a I/O port. + * @brief Writes a bits mask on a I/O port. + * @note The default implementation does nothing except computing the + * parameters eventual side effects. * - * @param[in] port the port identifier - * @param[in] bits the bits to be written on the specified port - * - * @note The default implementation does nothing except computing the - * parameters eventual side effects. + * @param[in] port the port identifier + * @param[in] bits the bits to be written on the specified port */ #if !defined(pal_lld_writeport) || defined(__DOXYGEN__) #define palWritePort(port, bits) ((void)(port), (void)(bits)) @@ -232,17 +237,17 @@ typedef struct { #endif /** - * @brief Sets a bits mask on a I/O port. + * @brief Sets a bits mask on a I/O port. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The default implementation is non atomic and not necessarily + * optimal. Low level drivers may optimize the function by using + * specific hardware or coding. * - * @param[in] port the port identifier - * @param[in] bits the bits to be ORed on the specified port - * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The default implementation is non atomic and not necessarily - * optimal. Low level drivers may optimize the function by using - * specific hardware or coding. + * @param[in] port the port identifier + * @param[in] bits the bits to be ORed on the specified port */ #if !defined(pal_lld_setport) || defined(__DOXYGEN__) #define palSetPort(port, bits) { \ @@ -253,17 +258,18 @@ typedef struct { #endif /** - * @brief Clears a bits mask on a I/O port. + * @brief Clears a bits mask on a I/O port. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The default implementation is non atomic and not necessarily + * optimal. Low level drivers may optimize the function by using + * specific hardware or coding. * - * @param[in] port the port identifier - * @param[in] bits the bits to be cleared on the specified port + * @param[in] port the port identifier + * @param[in] bits the bits to be cleared on the specified port * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The default implementation is non atomic and not necessarily - * optimal. Low level drivers may optimize the function by using - * specific hardware or coding. */ #if !defined(pal_lld_clearport) || defined(__DOXYGEN__) #define palClearPort(port, bits) { \ @@ -274,17 +280,17 @@ typedef struct { #endif /** - * @brief Toggles a bits mask on a I/O port. + * @brief Toggles a bits mask on a I/O port. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The default implementation is non atomic and not necessarily + * optimal. Low level drivers may optimize the function by using + * specific hardware or coding. * - * @param[in] port the port identifier - * @param[in] bits the bits to be XORed on the specified port - * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The default implementation is non atomic and not necessarily - * optimal. Low level drivers may optimize the function by using - * specific hardware or coding. + * @param[in] port the port identifier + * @param[in] bits the bits to be XORed on the specified port */ #if !defined(pal_lld_toggleport) || defined(__DOXYGEN__) #define palTogglePort(port, bits) { \ @@ -295,13 +301,13 @@ typedef struct { #endif /** - * @brief Reads a group of bits. + * @brief Reads a group of bits. * - * @param[in] port the port identifier - * @param[in] mask the group mask, a logical AND is performed on the input - * data - * @param[in] offset the group bit offset within the port - * @return The group logical states. + * @param[in] port the port identifier + * @param[in] mask the group mask, a logical AND is performed on the input + * data + * @param[in] offset the group bit offset within the port + * @return The group logical states. */ #if !defined(pal_lld_readgroup) || defined(__DOXYGEN__) #define palReadGroup(port, mask, offset) \ @@ -311,14 +317,14 @@ typedef struct { #endif /** - * @brief Writes a group of bits. + * @brief Writes a group of bits. * - * @param[in] port the port identifier - * @param[in] mask the group mask, a logical AND is performed on the output - * data - * @param[in] offset the group bit offset within the port - * @param[in] bits the bits to be written. Values exceeding the group width - * are masked. + * @param[in] port the port identifier + * @param[in] mask the group mask, a logical AND is performed on the + * output data + * @param[in] offset the group bit offset within the port + * @param[in] bits the bits to be written. Values exceeding the group + * width are masked. */ #if !defined(pal_lld_writegroup) || defined(__DOXYGEN__) #define palWriteGroup(port, mask, offset, bits) { \ @@ -332,15 +338,15 @@ typedef struct { /** - * @brief Pads group mode setup. + * @brief Pads group mode setup. * @details This function programs a pads group belonging to the same port * with the specified mode. + * @note Programming an unknown or unsupported mode is silently ignored. * - * @param[in] port the port identifier - * @param[in] mask the group mask - * @param[in] mode the setup mode + * @param[in] port the port identifier + * @param[in] mask the group mask + * @param[in] mode the setup mode * - * @note Programming an unknown or unsupported mode is silently ignored. */ #if !defined(pal_lld_setgroupmode) || defined(__DOXYGEN__) #define palSetGroupMode(port, mask, mode) @@ -349,17 +355,18 @@ typedef struct { #endif /** - * @brief Reads an input pad logical state. + * @brief Reads an input pad logical state. + * @note The default implementation not necessarily optimal. Low level + * drivers may optimize the function by using specific hardware + * or coding. + * @note The default implementation internally uses the @p palReadPort(). * - * @param[in] port the port identifier - * @param[in] pad the pad number within the port - * @return The logical state. - * @retval 0 low logical state. - * @retval 1 high logical state. + * @param[in] port the port identifier + * @param[in] pad the pad number within the port + * @return The logical state. + * @retval PAL_LOW low logical state. + * @retval PAL_HIGH high logical state. * - * @note The default implementation not necessarily optimal. Low level drivers - * may optimize the function by using specific hardware or coding. - * @note The default implementation internally uses the @p palReadPort(). */ #if !defined(pal_lld_readpad) || defined(__DOXYGEN__) #define palReadPad(port, pad) ((palReadPort(port) >> (pad)) & 1) @@ -368,20 +375,20 @@ typedef struct { #endif /** - * @brief Writes a logical state on an output pad. + * @brief Writes a logical state on an output pad. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The default implementation is non atomic and not necessarily + * optimal. Low level drivers may optimize the function by using + * specific hardware or coding. + * @note The default implementation internally uses the @p palReadLatch() + * and @p palWritePort(). * - * @param[in] port the port identifier - * @param[in] pad the pad number within the port - * @param[out] bit the logical value, the value must be @p 0 or @p 1 - * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The default implementation is non atomic and not necessarily - * optimal. Low level drivers may optimize the function by using - * specific hardware or coding. - * @note The default implementation internally uses the @p palReadLatch() and - * @p palWritePort(). + * @param[in] port the port identifier + * @param[in] pad the pad number within the port + * @param[out] bit the logical value, the value must be @p 0 or @p 1 */ #if !defined(pal_lld_writepad) || defined(__DOXYGEN__) #define palWritePad(port, pad, bit) { \ @@ -393,18 +400,18 @@ typedef struct { #endif /** - * @brief Sets a pad logical state to @p 1. + * @brief Sets a pad logical state to @p PAL_HIGH. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The default implementation is non atomic and not necessarily + * optimal. Low level drivers may optimize the function by using + * specific hardware or coding. + * @note The default implementation internally uses the @p palSetPort(). * - * @param[in] port the port identifier - * @param[in] pad the pad number within the port - * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The default implementation is non atomic and not necessarily - * optimal. Low level drivers may optimize the function by using - * specific hardware or coding. - * @note The default implementation internally uses the @p palSetPort(). + * @param[in] port the port identifier + * @param[in] pad the pad number within the port */ #if !defined(pal_lld_setpad) || defined(__DOXYGEN__) #define palSetPad(port, pad) palSetPort(port, PAL_PORT_BIT(pad)) @@ -413,18 +420,18 @@ typedef struct { #endif /** - * @brief Clears a pad logical state to @p 0. + * @brief Clears a pad logical state to @p PAL_LOW. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The default implementation is non atomic and not necessarily + * optimal. Low level drivers may optimize the function by using + * specific hardware or coding. + * @note The default implementation internally uses the @p palClearPort(). * - * @param[in] port the port identifier - * @param[in] pad the pad number within the port - * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The default implementation is non atomic and not necessarily - * optimal. Low level drivers may optimize the function by using - * specific hardware or coding. - * @note The default implementation internally uses the @p palClearPort(). + * @param[in] port the port identifier + * @param[in] pad the pad number within the port */ #if !defined(pal_lld_clearpad) || defined(__DOXYGEN__) #define palClearPad(port, pad) palClearPort(port, PAL_PORT_BIT(pad)) @@ -433,18 +440,18 @@ typedef struct { #endif /** - * @brief Toggles a pad logical state. + * @brief Toggles a pad logical state. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The default implementation is non atomic and not necessarily + * optimal. Low level drivers may optimize the function by using + * specific hardware or coding. + * @note The default implementation internally uses the @p palTogglePort(). * - * @param[in] port the port identifier - * @param[in] pad the pad number within the port - * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The default implementation is non atomic and not necessarily - * optimal. Low level drivers may optimize the function by using - * specific hardware or coding. - * @note The default implementation internally uses the @p palTogglePort(). + * @param[in] port the port identifier + * @param[in] pad the pad number within the port */ #if !defined(pal_lld_togglepad) || defined(__DOXYGEN__) #define palTogglePad(port, pad) palTogglePort(port, PAL_PORT_BIT(pad)) @@ -454,16 +461,16 @@ typedef struct { /** - * @brief Pad mode setup. + * @brief Pad mode setup. * @details This function programs a pad with the specified mode. + * @note The default implementation not necessarily optimal. Low level + * drivers may optimize the function by using specific hardware + * or coding. + * @note Programming an unknown or unsupported mode is silently ignored. * - * @param[in] port the port identifier - * @param[in] pad the pad number within the port - * @param[in] mode the setup mode - * - * @note The default implementation not necessarily optimal. Low level drivers - * may optimize the function by using specific hardware or coding. - * @note Programming an unknown or unsupported mode is silently ignored. + * @param[in] port the port identifier + * @param[in] pad the pad number within the port + * @param[in] mode the setup mode */ #if !defined(pal_lld_setpadmode) || defined(__DOXYGEN__) #define palSetPadMode(port, pad, mode) \ diff --git a/os/hal/include/pwm.h b/os/hal/include/pwm.h index 64b563164..f736c2e98 100644 --- a/os/hal/include/pwm.h +++ b/os/hal/include/pwm.h @@ -18,8 +18,9 @@ */ /** - * @file pwm.h - * @brief PWM Driver macros and structures. + * @file pwm.h + * @brief PWM Driver macros and structures. + * * @addtogroup PWM * @{ */ @@ -46,26 +47,26 @@ /*===========================================================================*/ /** - * @brief Driver state machine possible states. + * @brief Driver state machine possible states. */ typedef enum { - PWM_UNINIT = 0, /**< @brief Not initialized. */ - PWM_STOP = 1, /**< @brief Stopped. */ - PWM_READY = 2, /**< @brief Ready. */ + PWM_UNINIT = 0, /**< @brief Not initialized. */ + PWM_STOP = 1, /**< @brief Stopped. */ + PWM_READY = 2, /**< @brief Ready. */ } pwmstate_t; /** * @brief PWM logic mode. */ typedef enum { - PWM_OUTPUT_DISABLED = 0, /**< @brief Output not driven, callback - only. */ - PWM_OUTPUT_ACTIVE_HIGH = 1, /**< @brief Idle is logic level 0. */ - PWM_OUTPUT_ACTIVE_LOW = 2 /**< @brief Idle is logic level 1. */ + PWM_OUTPUT_DISABLED = 0, /**< @brief Output not driven, callback + only. */ + PWM_OUTPUT_ACTIVE_HIGH = 1, /**< @brief Idle is logic level 0. */ + PWM_OUTPUT_ACTIVE_LOW = 2 /**< @brief Idle is logic level 1. */ } pwmmode_t; /** - * @brief PWM notification callback type. + * @brief PWM notification callback type. * * @param[in] active current channel output state */ diff --git a/os/hal/include/serial.h b/os/hal/include/serial.h index 932f81030..1d45a1601 100644 --- a/os/hal/include/serial.h +++ b/os/hal/include/serial.h @@ -18,8 +18,9 @@ */ /** - * @file serial.h - * @brief Serial Driver macros and structures. + * @file serial.h + * @brief Serial Driver macros and structures. + * * @addtogroup SERIAL * @{ */ @@ -55,7 +56,7 @@ /*===========================================================================*/ /** - * @brief Default bit rate. + * @brief Default bit rate. * @details Configuration parameter, this is the baud rate selected for the * default configuration. */ @@ -64,10 +65,11 @@ #endif /** - * @brief Serial buffers size. + * @brief Serial buffers size. * @details Configuration parameter, you can change the depth of the queue * buffers depending on the requirements of your application. - * @note The default is 64 bytes for both the transmission and receive buffers. + * @note The default is 64 bytes for both the transmission and receive + * buffers. */ #if !defined(SERIAL_BUFFERS_SIZE) || defined(__DOXYGEN__) #define SERIAL_BUFFERS_SIZE 64 @@ -89,26 +91,26 @@ * @brief Driver state machine possible states. */ typedef enum { - SD_UNINIT = 0, /**< @brief Not initialized. */ - SD_STOP = 1, /**< @brief Stopped. */ - SD_READY = 2 /**< @brief Ready. */ + SD_UNINIT = 0, /**< @brief Not initialized. */ + SD_STOP = 1, /**< @brief Stopped. */ + SD_READY = 2 /**< @brief Ready. */ } sdstate_t; /** - * @brief Structure representing a serial driver. + * @brief Structure representing a serial driver. */ typedef struct _SerialDriver SerialDriver; #include "serial_lld.h" /** - * @brief @p SerialDriver specific methods. + * @brief @p SerialDriver specific methods. */ #define _serial_driver_methods \ _base_asynchronous_channel_methods /** - * @brief @p SerialDriver virtual methods table. + * @brief @p SerialDriver virtual methods table. */ struct SerialDriverVMT { _serial_driver_methods; @@ -117,14 +119,12 @@ struct SerialDriverVMT { /** * @extends BaseAsynchronousChannel * - * @brief Full duplex serial driver class. + * @brief Full duplex serial driver class. * @details This class extends @p BaseAsynchronousChannel by adding physical * I/O queues. */ struct _SerialDriver { - /** - * Virtual Methods Table. - */ + /** @brief Virtual Methods Table.*/ const struct SerialDriverVMT *vmt; _serial_driver_data }; @@ -134,129 +134,141 @@ struct _SerialDriver { /*===========================================================================*/ /** - * @brief Direct output check on a @p SerialDriver. + * @brief Direct output check on a @p SerialDriver. * @details This function bypasses the indirect access to the channel and * checks directly the output queue. This is faster but cannot * be used to check different channels implementations. - * @see chIOPutWouldBlock() + * + * @see chIOPutWouldBlock() */ #define sdPutWouldBlock(sdp) chOQIsFull(&(sdp)->oqueue) /** - * @brief Direct input check on a @p SerialDriver. + * @brief Direct input check on a @p SerialDriver. * @details This function bypasses the indirect access to the channel and * checks directly the input queue. This is faster but cannot * be used to check different channels implementations. - * @see chIOGetWouldBlock() + * + * @see chIOGetWouldBlock() */ #define sdGetWouldBlock(sdp) chIQIsEmpty(&(sdp)->iqueue) /** - * @brief Direct write to a @p SerialDriver. + * @brief Direct write to a @p SerialDriver. * @details This function bypasses the indirect access to the channel and * writes directly on the output queue. This is faster but cannot * be used to write to different channels implementations. - * @see chIOPut() + * + * @see chIOPut() */ #define sdPut(sdp, b) chOQPut(&(sdp)->oqueue, b) /** - * @brief Direct write to a @p SerialDriver with timeout specification. + * @brief Direct write to a @p SerialDriver with timeout specification. * @details This function bypasses the indirect access to the channel and * writes directly on the output queue. This is faster but cannot * be used to write to different channels implementations. - * @see chIOPutTimeout() + * + * @see chIOPutTimeout() */ #define sdPutTimeout(sdp, b, t) chOQPutTimeout(&(sdp)->iqueue, b, t) /** - * @brief Direct read from a @p SerialDriver. + * @brief Direct read from a @p SerialDriver. * @details This function bypasses the indirect access to the channel and * reads directly from the input queue. This is faster but cannot * be used to read from different channels implementations. - * @see chIOGet() + * + * @see chIOGet() */ #define sdGet(sdp) chIQGet(&(sdp)->iqueue) /** - * @brief Direct read from a @p SerialDriver with timeout specification. + * @brief Direct read from a @p SerialDriver with timeout specification. * @details This function bypasses the indirect access to the channel and * reads directly from the input queue. This is faster but cannot * be used to read from different channels implementations. - * @see chIOGetTimeout() + * + * @see chIOGetTimeout() */ #define sdGetTimeout(sdp, t) chIQGetTimeout(&(sdp)->iqueue, t) /** - * @brief Direct blocking write to a @p SerialDriver. + * @brief Direct blocking write to a @p SerialDriver. * @details This function bypasses the indirect access to the channel and * writes directly to the output queue. This is faster but cannot * be used to write from different channels implementations. - * @see chIOWriteTimeout() + * + * @see chIOWriteTimeout() */ #define sdWrite(sdp, b, n) \ chOQWriteTimeout(&(sdp)->oqueue, b, n, TIME_INFINITE) /** - * @brief Direct blocking write to a @p SerialDriver with timeout - * specification. + * @brief Direct blocking write to a @p SerialDriver with timeout + * specification. * @details This function bypasses the indirect access to the channel and * writes directly to the output queue. This is faster but cannot * be used to write from different channels implementations. - * @see chIOWriteTimeout() + * + * @see chIOWriteTimeout() */ #define sdWriteTimeout(sdp, b, n, t) \ chOQWriteTimeout(&(sdp)->oqueue, b, n, t) /** - * @brief Direct non-blocking write to a @p SerialDriver. + * @brief Direct non-blocking write to a @p SerialDriver. * @details This function bypasses the indirect access to the channel and * writes directly to the output queue. This is faster but cannot * be used to write from different channels implementations. - * @see chIOWriteTimeout() + * + * @see chIOWriteTimeout() */ #define sdAsynchronousWrite(sdp, b, n) \ chOQWriteTimeout(&(sdp)->oqueue, b, n, TIME_IMMEDIATE) /** - * @brief Direct blocking read from a @p SerialDriver. + * @brief Direct blocking read from a @p SerialDriver. * @details This function bypasses the indirect access to the channel and * reads directly from the input queue. This is faster but cannot * be used to read from different channels implementations. - * @see chIOReadTimeout() + * + * @see chIOReadTimeout() */ #define sdRead(sdp, b, n) \ chIQReadTimeout(&(sdp)->iqueue, b, n, TIME_INFINITE) /** - * @brief Direct blocking read from a @p SerialDriver with timeout - * specification. + * @brief Direct blocking read from a @p SerialDriver with timeout + * specification. * @details This function bypasses the indirect access to the channel and * reads directly from the input queue. This is faster but cannot * be used to read from different channels implementations. - * @see chIOReadTimeout() + * + * @see chIOReadTimeout() */ #define sdReadTimeout(sdp, b, n, t) \ chIQReadTimeout(&(sdp)->iqueue, b, n, t) /** - * @brief Direct non-blocking read from a @p SerialDriver. + * @brief Direct non-blocking read from a @p SerialDriver. * @details This function bypasses the indirect access to the channel and * reads directly from the input queue. This is faster but cannot * be used to read from different channels implementations. - * @see chIOReadTimeout() + * + * @see chIOReadTimeout() */ #define sdAsynchronousRead(sdp, b, n) \ chIQReadTimeout(&(sdp)->iqueue, b, n, TIME_IMMEDIATE) /** - * @brief Returns the status change event source. + * @brief Returns the status change event source. * @details The status change event source is broadcasted when the channel * status is updated, the status flags can then be fetched and * cheared by using @p sdGetAndClearFlags(). * - * @param[in] ip pointer to a @p SerialDriver object - * @return A pointer to an @p EventSource object. + * @param[in] ip pointer to a @p SerialDriver object + * @return A pointer to an @p EventSource object. */ #define sdGetStatusChangeEventSource(ip) (&((ip)->vmt->sevent)) diff --git a/os/hal/include/spi.h b/os/hal/include/spi.h index 6e1df95bd..5729aa042 100644 --- a/os/hal/include/spi.h +++ b/os/hal/include/spi.h @@ -18,8 +18,9 @@ */ /** - * @file spi.h - * @brief SPI Driver macros and structures. + * @file spi.h + * @brief SPI Driver macros and structures. + * * @addtogroup SPI * @{ */ @@ -38,7 +39,7 @@ /*===========================================================================*/ /** - * @brief Enables the mutual exclusion APIs on the SPI bus. + * @brief Enables the mutual exclusion APIs on the SPI bus. */ #if !defined(SPI_USE_MUTUAL_EXCLUSION) || defined(__DOXYGEN__) #define SPI_USE_MUTUAL_EXCLUSION TRUE @@ -57,13 +58,13 @@ /*===========================================================================*/ /** - * @brief Driver state machine possible states. + * @brief Driver state machine possible states. */ typedef enum { - SPI_UNINIT = 0, /**< @brief Not initialized. */ - SPI_STOP = 1, /**< @brief Stopped. */ - SPI_READY = 2, /**< @brief Ready. */ - SPI_ACTIVE = 3 /**< @brief Slave selected. */ + SPI_UNINIT = 0, /**< @brief Not initialized. */ + SPI_STOP = 1, /**< @brief Stopped. */ + SPI_READY = 2, /**< @brief Ready. */ + SPI_ACTIVE = 3 /**< @brief Slave selected. */ } spistate_t; #include "spi_lld.h" diff --git a/os/hal/src/adc.c b/os/hal/src/adc.c index 16bdeac43..dff7d828b 100644 --- a/os/hal/src/adc.c +++ b/os/hal/src/adc.c @@ -18,8 +18,9 @@ */ /** - * @file adc.c - * @brief ADC Driver code. + * @file adc.c + * @brief ADC Driver code. + * * @addtogroup ADC * @{ */ @@ -46,7 +47,7 @@ /*===========================================================================*/ /** - * @brief ADC Driver initialization. + * @brief ADC Driver initialization. */ void adcInit(void) { @@ -54,7 +55,7 @@ void adcInit(void) { } /** - * @brief Initializes the standard part of a @p ADCDriver structure. + * @brief Initializes the standard part of a @p ADCDriver structure. * * @param[in] adcp pointer to the @p ADCDriver object */ @@ -70,7 +71,7 @@ void adcObjectInit(ADCDriver *adcp) { } /** - * @brief Configures and activates the ADC peripheral. + * @brief Configures and activates the ADC peripheral. * * @param[in] adcp pointer to the @p ADCDriver object * @param[in] config pointer to the @p ADCConfig object @@ -90,7 +91,7 @@ void adcStart(ADCDriver *adcp, const ADCConfig *config) { } /** - * @brief Deactivates the ADC peripheral. + * @brief Deactivates the ADC peripheral. * * @param[in] adcp pointer to the @p ADCDriver object */ @@ -108,7 +109,7 @@ void adcStop(ADCDriver *adcp) { } /** - * @brief Starts an ADC conversion. + * @brief Starts an ADC conversion. * @details Starts a conversion operation, there are two kind of conversion * modes: * - LINEAR, this mode is activated when the @p callback @@ -122,6 +123,10 @@ void adcStop(ADCDriver *adcp) { * time. This kind of conversion can only be stopped by explicitly * invoking @p adcStopConversion(). * . + * @note The buffer is organized as a matrix of M*N elements where M is the + * channels number configured into the conversion group and N is the + * buffer depth. The samples are sequentially written into the buffer + * with no gaps. * * @param[in] adcp pointer to the @p ADCDriver object * @param[in] grpp pointer to a @p ADCConversionGroup object @@ -129,14 +134,9 @@ void adcStop(ADCDriver *adcp) { * @param[in] depth buffer depth (matrix rows number). The buffer depth * must be one or an even number. * @param[in] callback pointer to the conversion callback function - * @return The operation status. + * @return The operation status. * @retval FALSE the conversion has been started. * @retval TRUE the driver is busy, conversion not started. - * - * @note The buffer is organized as a matrix of M*N elements where M is the - * channels number configured into the conversion group and N is the - * buffer depth. The samples are sequentially written into the buffer - * with no gaps. */ bool_t adcStartConversion(ADCDriver *adcp, const ADCConversionGroup *grpp, @@ -169,9 +169,9 @@ bool_t adcStartConversion(ADCDriver *adcp, } /** - * @brief Stops an ongoing conversion. + * @brief Stops an ongoing conversion. * - * @param[in] adcp pointer to the @p ADCDriver object + * @param[in] adcp pointer to the @p ADCDriver object */ void adcStopConversion(ADCDriver *adcp) { @@ -196,7 +196,7 @@ void adcStopConversion(ADCDriver *adcp) { } /** - * @brief Waits for completion. + * @brief Waits for completion. * @details If the conversion is not completed or not yet started then the * invoking thread waits for a conversion completion event. * @@ -206,9 +206,9 @@ void adcStopConversion(ADCDriver *adcp) { * - @a TIME_IMMEDIATE immediate timeout. * - @a TIME_INFINITE no timeout. * . - * @return The operation result. - * @retval RDY_OK conversion finished. - * @retval RDY_TIMEOUT conversion not finished within the specified time. + * @return The operation result. + * @retval RDY_OK conversion finished. + * @retval RDY_TIMEOUT conversion not finished within the specified time. */ msg_t adcWaitConversion(ADCDriver *adcp, systime_t timeout) { diff --git a/os/hal/src/can.c b/os/hal/src/can.c index e70c25617..a4da35b8e 100644 --- a/os/hal/src/can.c +++ b/os/hal/src/can.c @@ -18,8 +18,9 @@ */ /** - * @file CAN.c - * @brief CAN Driver code. + * @file can.c + * @brief CAN Driver code. + * * @addtogroup CAN * @{ */ @@ -46,7 +47,7 @@ /*===========================================================================*/ /** - * @brief CAN Driver initialization. + * @brief CAN Driver initialization. */ void canInit(void) { @@ -54,7 +55,7 @@ void canInit(void) { } /** - * @brief Initializes the standard part of a @p CANDriver structure. + * @brief Initializes the standard part of a @p CANDriver structure. * * @param[in] canp pointer to the @p CANDriver object */ @@ -75,7 +76,7 @@ void canObjectInit(CANDriver *canp) { } /** - * @brief Configures and activates the CAN peripheral. + * @brief Configures and activates the CAN peripheral. * * @param[in] canp pointer to the @p CANDriver object * @param[in] config pointer to the @p CANConfig object @@ -101,7 +102,7 @@ void canStart(CANDriver *canp, const CANConfig *config) { } /** - * @brief Deactivates the CAN peripheral. + * @brief Deactivates the CAN peripheral. * * @param[in] canp pointer to the @p CANDriver object */ @@ -123,10 +124,10 @@ void canStop(CANDriver *canp) { } /** - * @brief Can frame transmission. + * @brief Can frame transmission. * @details The specified frame is queued for transmission, if the hardware * queue is full then the invoking thread is queued. - * @note Trying to transmit while in sleep mode simply enqueues the thread. + * @note Trying to transmit while in sleep mode simply enqueues the thread. * * @param[in] canp pointer to the @p CANDriver object * @param[in] ctfp pointer to the CAN frame to be transmitted @@ -135,10 +136,10 @@ void canStop(CANDriver *canp) { * - @a TIME_IMMEDIATE immediate timeout. * - @a TIME_INFINITE no timeout. * . - * @return The operation result. - * @retval RDY_OK the frame has been queued for transmission. - * @retval RDY_TIMEOUT operation not finished within the specified time. - * @retval RDY_RESET driver stopped while waiting. + * @return The operation result. + * @retval RDY_OK the frame has been queued for transmission. + * @retval RDY_TIMEOUT operation not finished within the specified time. + * @retval RDY_RESET driver stopped while waiting. */ msg_t canTransmit(CANDriver *canp, const CANTxFrame *ctfp, systime_t timeout) { @@ -161,9 +162,9 @@ msg_t canTransmit(CANDriver *canp, const CANTxFrame *ctfp, systime_t timeout) { } /** - * @brief Can frame receive. + * @brief Can frame receive. * @details The function waits until a frame is received. - * @note Trying to receive while in sleep mode simply enqueues the thread. + * @note Trying to receive while in sleep mode simply enqueues the thread. * * @param[in] canp pointer to the @p CANDriver object * @param[out] crfp pointer to the buffer where the CAN frame is copied @@ -174,11 +175,12 @@ msg_t canTransmit(CANDriver *canp, const CANTxFrame *ctfp, systime_t timeout) { * for I/O). * - @a TIME_INFINITE no timeout. * . - * @return The operation result. - * @retval RDY_OK a frame has been received and placed in the buffer. - * @retval RDY_TIMEOUT operation not finished within the specified time or - * frame not immediately available if invoked using @p TIME_IMMEDIATE. - * @retval RDY_RESET driver stopped while waiting. + * @return The operation result. + * @retval RDY_OK a frame has been received and placed in the buffer. + * @retval RDY_TIMEOUT operation not finished within the specified time or + * frame not immediately available if invoked using + * @p TIME_IMMEDIATE. + * @retval RDY_RESET driver stopped while waiting. */ msg_t canReceive(CANDriver *canp, CANRxFrame *crfp, systime_t timeout) { @@ -201,11 +203,10 @@ msg_t canReceive(CANDriver *canp, CANRxFrame *crfp, systime_t timeout) { } /** - * @brief Returns the current status mask and clears it. + * @brief Returns the current status mask and clears it. * * @param[in] canp pointer to the @p CANDriver object - * - * @return The status flags mask. + * @return The status flags mask. */ canstatus_t canGetAndClearFlags(CANDriver *canp) { canstatus_t status; @@ -219,7 +220,7 @@ canstatus_t canGetAndClearFlags(CANDriver *canp) { #if CAN_USE_SLEEP_MODE || defined(__DOXYGEN__) /** - * @brief Enters the sleep mode. + * @brief Enters the sleep mode. * * @param[in] canp pointer to the @p CANDriver object */ @@ -241,9 +242,9 @@ void canSleep(CANDriver *canp) { } /** - * @brief Enforces leaving the sleep mode. - * @note The sleep mode is supposed to be usually exited automatically by an - * hardware event. + * @brief Enforces leaving the sleep mode. + * @note The sleep mode is supposed to be usually exited automatically by + * an hardware event. * * @param[in] canp pointer to the @p CANDriver object */ diff --git a/os/hal/src/hal.c b/os/hal/src/hal.c index 3631028e5..f93f036c6 100644 --- a/os/hal/src/hal.c +++ b/os/hal/src/hal.c @@ -18,8 +18,9 @@ */ /** - * @file hal.c - * @brief HAL subsystem code. + * @file hal.c + * @brief HAL subsystem code. + * * @addtogroup HAL * @{ */ @@ -44,7 +45,7 @@ /*===========================================================================*/ /** - * @brief HAL initialization. + * @brief HAL initialization. */ void halInit(void) { diff --git a/os/hal/src/mac.c b/os/hal/src/mac.c index 6d31c7b9e..74e08bdf4 100644 --- a/os/hal/src/mac.c +++ b/os/hal/src/mac.c @@ -18,8 +18,9 @@ */ /** - * @file mac.c - * @brief MAC Driver code. + * @file mac.c + * @brief MAC Driver code. + * * @addtogroup MAC * @{ */ @@ -50,7 +51,7 @@ /*===========================================================================*/ /** - * @brief MAC Driver initialization. + * @brief MAC Driver initialization. */ void macInit(void) { @@ -58,9 +59,9 @@ void macInit(void) { } /** - * @brief Initialize the standard part of a @p MACDriver structure. + * @brief Initialize the standard part of a @p MACDriver structure. * - * @param[in] macp pointer to the @p MACDriver object + * @param[in] macp pointer to the @p MACDriver object */ void macObjectInit(MACDriver *macp) { @@ -72,15 +73,15 @@ void macObjectInit(MACDriver *macp) { } /** - * @brief MAC address setup. + * @brief MAC address setup. + * @note This function must be invoked only with the driver in the stopped + * state. If invoked on an active interface then it is ignored. * - * @param[in] macp pointer to the @p MACDriver object - * @param[in] p pointer to a six bytes buffer containing the MAC address. If - * this parameter is set to @p NULL then a system default MAC is - * used. + * @param[in] macp pointer to the @p MACDriver object + * @param[in] p pointer to a six bytes buffer containing the MAC + * address. If this parameter is set to @p NULL then MAC + * a system default is used. * - * @note This function must be invoked only with the driver in the stopped - * state. If invoked on an active interface then it is ignored. */ void macSetAddress(MACDriver *macp, const uint8_t *p) { @@ -88,21 +89,21 @@ void macSetAddress(MACDriver *macp, const uint8_t *p) { } /** - * @brief Allocates a transmission descriptor. + * @brief Allocates a transmission descriptor. * @details One of the available transmission descriptors is locked and * returned. If a descriptor is not currently available then the * invoking thread is queued until one is freed. * - * @param[in] macp pointer to the @p MACDriver object - * @param[out] tdp pointer to a @p MACTransmitDescriptor structure - * @param[in] time the number of ticks before the operation timeouts, - * the following special values are allowed: - * - @a TIME_IMMEDIATE immediate timeout. - * - @a TIME_INFINITE no timeout. - * . - * @return The operation status. - * @retval RDY_OK the descriptor was obtained. - * @retval RDY_TIMEOUT the operation timed out, descriptor not initialized. + * @param[in] macp pointer to the @p MACDriver object + * @param[out] tdp pointer to a @p MACTransmitDescriptor structure + * @param[in] time the number of ticks before the operation timeouts, + * the following special values are allowed: + * - @a TIME_IMMEDIATE immediate timeout. + * - @a TIME_INFINITE no timeout. + * . + * @return The operation status. + * @retval RDY_OK the descriptor was obtained. + * @retval RDY_TIMEOUT the operation timed out, descriptor not initialized. */ msg_t macWaitTransmitDescriptor(MACDriver *macp, MACTransmitDescriptor *tdp, @@ -123,10 +124,10 @@ msg_t macWaitTransmitDescriptor(MACDriver *macp, } /** - * @brief Releases a transmit descriptor and starts the transmission of the - * enqueued data as a single frame. + * @brief Releases a transmit descriptor and starts the transmission of the + * enqueued data as a single frame. * - * @param[in] tdp the pointer to the @p MACTransmitDescriptor structure + * @param[in] tdp the pointer to the @p MACTransmitDescriptor structure */ void macReleaseTransmitDescriptor(MACTransmitDescriptor *tdp) { @@ -134,21 +135,21 @@ void macReleaseTransmitDescriptor(MACTransmitDescriptor *tdp) { } /** - * @brief Waits for a received frame. + * @brief Waits for a received frame. * @details Stops until a frame is received and buffered. If a frame is * not immediately available then the invoking thread is queued * until one is received. * - * @param[in] macp pointer to the @p MACDriver object - * @param[out] rdp pointer to a @p MACReceiveDescriptor structure - * @param[in] time the number of ticks before the operation timeouts, - * the following special values are allowed: - * - @a TIME_IMMEDIATE immediate timeout. - * - @a TIME_INFINITE no timeout. - * . - * @return The operation status. - * @retval RDY_OK the descriptor was obtained. - * @retval RDY_TIMEOUT the operation timed out, descriptor not initialized. + * @param[in] macp pointer to the @p MACDriver object + * @param[out] rdp pointer to a @p MACReceiveDescriptor structure + * @param[in] time the number of ticks before the operation timeouts, + * the following special values are allowed: + * - @a TIME_IMMEDIATE immediate timeout. + * - @a TIME_INFINITE no timeout. + * . + * @return The operation status. + * @retval RDY_OK the descriptor was obtained. + * @retval RDY_TIMEOUT the operation timed out, descriptor not initialized. */ msg_t macWaitReceiveDescriptor(MACDriver *macp, MACReceiveDescriptor *rdp, @@ -169,11 +170,11 @@ msg_t macWaitReceiveDescriptor(MACDriver *macp, } /** - * @brief Releases a receive descriptor. + * @brief Releases a receive descriptor. * @details The descriptor and its buffer are made available for more incoming * frames. * - * @param[in] rdp the pointer to the @p MACReceiveDescriptor structure + * @param[in] rdp the pointer to the @p MACReceiveDescriptor structure */ void macReleaseReceiveDescriptor(MACReceiveDescriptor *rdp) { @@ -181,12 +182,12 @@ void macReleaseReceiveDescriptor(MACReceiveDescriptor *rdp) { } /** - * @brief Updates and returns the link status. + * @brief Updates and returns the link status. * - * @param[in] macp pointer to the @p MACDriver object - * @return The link status. - * @retval TRUE if the link is active. - * @retval FALSE if the link is down. + * @param[in] macp pointer to the @p MACDriver object + * @return The link status. + * @retval TRUE if the link is active. + * @retval FALSE if the link is down. */ bool_t macPollLinkStatus(MACDriver *macp) { diff --git a/os/hal/src/mmc_spi.c b/os/hal/src/mmc_spi.c index f9f8eef5a..c1cb313ec 100644 --- a/os/hal/src/mmc_spi.c +++ b/os/hal/src/mmc_spi.c @@ -18,8 +18,9 @@ */ /** - * @file mmc_spi.c - * @brief MMC over SPI driver code. + * @file mmc_spi.c + * @brief MMC over SPI driver code. + * * @addtogroup MMC_SPI * @{ */ @@ -41,6 +42,11 @@ /* Driver local functions. */ /*===========================================================================*/ +/** + * @brief Inserion monitor timer callback function. + * + * @param[in] p pointer to the @p MMCDriver object + */ void tmrfunc(void *p) { MMCDriver *mmcp = p; @@ -65,7 +71,7 @@ void tmrfunc(void *p) { } /** - * @brief Waits an idle condition. + * @brief Waits an idle condition. * * @param[in] mmcp pointer to the @p MMCDriver object */ @@ -91,7 +97,7 @@ static void wait(MMCDriver *mmcp) { } /** - * @brief Sends a command header. + * @brief Sends a command header. * * @param[in] mmcp pointer to the @p MMCDriver object * @param cmd[in] the command id @@ -113,11 +119,10 @@ static void send_hdr(MMCDriver *mmcp, uint8_t cmd, uint32_t arg) { } /** - * @brief Receives a single byte response. + * @brief Receives a single byte response. * * @param[in] mmcp pointer to the @p MMCDriver object - * - * @return The response as an @p uint8_t value. + * @return The response as an @p uint8_t value. * @retval 0xFF timed out. */ static uint8_t recvr1(MMCDriver *mmcp) { @@ -133,13 +138,12 @@ static uint8_t recvr1(MMCDriver *mmcp) { } /** - * @brief Sends a command an returns a single byte response. + * @brief Sends a command an returns a single byte response. * * @param[in] mmcp pointer to the @p MMCDriver object * @param cmd[in] the command id * @param arg[in] the command argument - * - * @return The response as an @p uint8_t value. + * @return The response as an @p uint8_t value. * @retval 0xFF timed out. */ static uint8_t send_command(MMCDriver *mmcp, uint8_t cmd, uint32_t arg) { @@ -153,7 +157,7 @@ static uint8_t send_command(MMCDriver *mmcp, uint8_t cmd, uint32_t arg) { } /** - * @brief Waits that the card reaches an idle state. + * @brief Waits that the card reaches an idle state. * * @param[in] mmcp pointer to the @p MMCDriver object */ @@ -177,14 +181,14 @@ static void sync(MMCDriver *mmcp) { /*===========================================================================*/ /** - * @brief MMC over SPI driver initialization. + * @brief MMC over SPI driver initialization. */ void mmcInit(void) { } /** - * @brief Initializes an instance. + * @brief Initializes an instance. * * @param[in] mmcp pointer to the @p MMCDriver object * @param[in] spip pointer to the SPI driver to be used as interface @@ -211,7 +215,7 @@ void mmcObjectInit(MMCDriver *mmcp, SPIDriver *spip, } /** - * @brief Configures and activates the MMC peripheral. + * @brief Configures and activates the MMC peripheral. * * @param[in] mmcp pointer to the @p MMCDriver object * @param[in] config pointer to the @p MMCConfig object @@ -230,7 +234,7 @@ void mmcStart(MMCDriver *mmcp, const MMCConfig *config) { } /** - * @brief Disables the MMC peripheral. + * @brief Disables the MMC peripheral. * * @param[in] mmcp pointer to the @p MMCDriver object */ @@ -253,16 +257,15 @@ void mmcStop(MMCDriver *mmcp) { } /** - * @brief Performs the initialization procedure on the inserted card. + * @brief Performs the initialization procedure on the inserted card. * @details This function should be invoked when a card is inserted and * brings the driver in the @p MMC_READY state where it is possible * to perform read and write operations. - * @note It is possible to invoke this function from the insertion event - * handler. + * @note It is possible to invoke this function from the insertion event + * handler. * * @param[in] mmcp pointer to the @p MMCDriver object - * - * @return The operation status. + * @return The operation status. * @retval FALSE the operation was successful and the driver is now * in the @p MMC_READY state. * @retval TRUE the operation failed. @@ -331,10 +334,10 @@ bool_t mmcConnect(MMCDriver *mmcp) { } /** - * @brief Brings the driver in a state safe for card removal. + * @brief Brings the driver in a state safe for card removal. * * @param[in] mmcp pointer to the @p MMCDriver object - * @return The operation status. + * @return The operation status. * @retval FALSE the operation was successful and the driver is now * in the @p MMC_INSERTED state. * @retval TRUE the operation failed. @@ -363,12 +366,11 @@ bool_t mmcDisconnect(MMCDriver *mmcp) { } /** - * @brief Starts a sequential read. + * @brief Starts a sequential read. * * @param[in] mmcp pointer to the @p MMCDriver object - * @param[in] startblk first block to read - * - * @return The operation status. + * @param[in] startblk first block to read + * @return The operation status. * @retval FALSE the operation was successful. * @retval TRUE the operation failed. */ @@ -398,12 +400,11 @@ bool_t mmcStartSequentialRead(MMCDriver *mmcp, uint32_t startblk) { } /** - * @brief Reads a block within a sequential read operation. + * @brief Reads a block within a sequential read operation. * * @param[in] mmcp pointer to the @p MMCDriver object - * @param[out] buffer pointer to the read buffer - * - * @return The operation status. + * @param[out] buffer pointer to the read buffer + * @return The operation status. * @retval FALSE the operation was successful. * @retval TRUE the operation failed. */ @@ -438,11 +439,10 @@ bool_t mmcSequentialRead(MMCDriver *mmcp, uint8_t *buffer) { } /** - * @brief Stops a sequential read gracefully. + * @brief Stops a sequential read gracefully. * * @param[in] mmcp pointer to the @p MMCDriver object - * - * @return The operation status. + * @return The operation status. * @retval FALSE the operation was successful. * @retval TRUE the operation failed. */ @@ -471,12 +471,11 @@ bool_t mmcStopSequentialRead(MMCDriver *mmcp) { } /** - * @brief Starts a sequential write. + * @brief Starts a sequential write. * * @param[in] mmcp pointer to the @p MMCDriver object * @param[in] startblk first block to write - * - * @return The operation status. + * @return The operation status. * @retval FALSE the operation was successful. * @retval TRUE the operation failed. */ @@ -506,12 +505,11 @@ bool_t mmcStartSequentialWrite(MMCDriver *mmcp, uint32_t startblk) { } /** - * @brief Writes a block within a sequential write operation. + * @brief Writes a block within a sequential write operation. * * @param[in] mmcp pointer to the @p MMCDriver object * @param[out] buffer pointer to the write buffer - * - * @return The operation status. + * @return The operation status. * @retval FALSE the operation was successful. * @retval TRUE the operation failed. */ @@ -545,11 +543,10 @@ bool_t mmcSequentialWrite(MMCDriver *mmcp, const uint8_t *buffer) { } /** - * @brief Stops a sequential write gracefully. + * @brief Stops a sequential write gracefully. * * @param[in] mmcp pointer to the @p MMCDriver object - * - * @return The operation status. + * @return The operation status. * @retval FALSE the operation was successful. * @retval TRUE the operation failed. */ diff --git a/os/hal/src/pal.c b/os/hal/src/pal.c index a04f4ed96..cc898d2fd 100644 --- a/os/hal/src/pal.c +++ b/os/hal/src/pal.c @@ -18,8 +18,9 @@ */ /** - * @file pal.c - * @brief I/O Ports Abstraction Layer code. + * @file pal.c + * @brief I/O Ports Abstraction Layer code. + * * @addtogroup PAL * @{ */ @@ -46,17 +47,17 @@ /*===========================================================================*/ /** - * @brief Read from an I/O bus. + * @brief Read from an I/O bus. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The function internally uses the @p palReadGroup() macro. The use + * of this function is preferred when you value code size, readability + * and error checking over speed. * - * @param[in] bus the I/O bus, pointer to a @p IOBus structure - * @return The bus logical states. - * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The function internally uses the @p palReadGroup() macro. The use of - * this function is preferred when you value code size, readability and - * error checking over speed. + * @param[in] bus the I/O bus, pointer to a @p IOBus structure + * @return The bus logical states. */ ioportmask_t palReadBus(IOBus *bus) { @@ -67,18 +68,19 @@ ioportmask_t palReadBus(IOBus *bus) { } /** - * @brief Write to an I/O bus. + * @brief Write to an I/O bus. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The default implementation is non atomic and not necessarily + * optimal. Low level drivers may optimize the function by using + * specific hardware or coding. * - * @param[in] bus the I/O bus, pointer to a @p IOBus structure - * @param[in] bits the bits to be written on the I/O bus. Values exceeding - * the bus width are masked so most significant bits are lost. - * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The default implementation is non atomic and not necessarily - * optimal. Low level drivers may optimize the function by using - * specific hardware or coding. + * @param[in] bus the I/O bus, pointer to a @p IOBus structure + * @param[in] bits the bits to be written on the I/O bus. Values exceeding + * the bus width are masked so most significant bits are + * lost. */ void palWriteBus(IOBus *bus, ioportmask_t bits) { @@ -89,17 +91,17 @@ void palWriteBus(IOBus *bus, ioportmask_t bits) { } /** - * @brief Programs a bus with the specified mode. + * @brief Programs a bus with the specified mode. + * @note The operation is not guaranteed to be atomic on all the + * architectures, for atomicity and/or portability reasons you may + * need to enclose port I/O operations between @p chSysLock() and + * @p chSysUnlock(). + * @note The default implementation is non atomic and not necessarily + * optimal. Low level drivers may optimize the function by using + * specific hardware or coding. * - * @param[in] bus the I/O bus, pointer to a @p IOBus structure - * @param[in] mode the mode - * - * @note The operation is not guaranteed to be atomic on all the architectures, - * for atomicity and/or portability reasons you may need to enclose port - * I/O operations between @p chSysLock() and @p chSysUnlock(). - * @note The default implementation is non atomic and not necessarily - * optimal. Low level drivers may optimize the function by using - * specific hardware or coding. + * @param[in] bus the I/O bus, pointer to a @p IOBus structure + * @param[in] mode the mode */ void palSetBusMode(IOBus *bus, uint_fast8_t mode) { diff --git a/os/hal/src/pwm.c b/os/hal/src/pwm.c index 404f3d8a7..ddfb6dd83 100644 --- a/os/hal/src/pwm.c +++ b/os/hal/src/pwm.c @@ -18,8 +18,8 @@ */ /** - * @file PWM.c - * @brief PWM Driver code. + * @file pwm.c + * @brief PWM Driver code. * @addtogroup PWM * @{ */ @@ -46,7 +46,7 @@ /*===========================================================================*/ /** - * @brief PWM Driver initialization. + * @brief PWM Driver initialization. */ void pwmInit(void) { @@ -54,7 +54,7 @@ void pwmInit(void) { } /** - * @brief Initializes the standard part of a @p PWMDriver structure. + * @brief Initializes the standard part of a @p PWMDriver structure. * * @param[in] pwmp pointer to a @p PWMDriver object */ @@ -65,7 +65,7 @@ void pwmObjectInit(PWMDriver *pwmp) { } /** - * @brief Configures and activates the PWM peripheral. + * @brief Configures and activates the PWM peripheral. * * @param[in] pwmp pointer to a @p PWMDriver object * @param[in] config pointer to a @p PWMConfig object @@ -85,7 +85,7 @@ void pwmStart(PWMDriver *pwmp, const PWMConfig *config) { } /** - * @brief Deactivates the PWM peripheral. + * @brief Deactivates the PWM peripheral. * * @param[in] pwmp pointer to a @p PWMDriver object */ @@ -103,7 +103,7 @@ void pwmStop(PWMDriver *pwmp) { } /** - * @brief Enables a PWM channel. + * @brief Enables a PWM channel. * * @param[in] pwmp pointer to a @p PWMDriver object * @param[in] channel PWM channel identifier diff --git a/os/hal/src/serial.c b/os/hal/src/serial.c index 9b5219fca..851f16ffb 100644 --- a/os/hal/src/serial.c +++ b/os/hal/src/serial.c @@ -18,8 +18,9 @@ */ /** - * @file serial.c - * @brief Serial Driver code. + * @file serial.c + * @brief Serial Driver code. + * * @addtogroup SERIAL * @{ */ @@ -97,7 +98,7 @@ static const struct SerialDriverVMT vmt = { /*===========================================================================*/ /** - * @brief Serial Driver initialization. + * @brief Serial Driver initialization. */ void sdInit(void) { @@ -105,17 +106,17 @@ void sdInit(void) { } /** - * @brief Initializes a generic full duplex driver object. + * @brief Initializes a generic full duplex driver object. * @details The HW dependent part of the initialization has to be performed * outside, usually in the hardware initialization code. * - * @param[out] sdp pointer to a @p SerialDriver 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. + * @param[out] sdp pointer to a @p SerialDriver 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. */ void sdObjectInit(SerialDriver *sdp, qnotify_t inotify, qnotify_t onotify) { @@ -130,12 +131,12 @@ void sdObjectInit(SerialDriver *sdp, qnotify_t inotify, qnotify_t onotify) { } /** - * @brief Configures and starts the driver. + * @brief Configures and starts the driver. * - * @param[in] sdp pointer to a @p SerialDriver object - * @param[in] config the architecture-dependent serial driver configuration. - * If this parameter is set to @p NULL then a default - * configuration is used. + * @param[in] sdp pointer to a @p SerialDriver object + * @param[in] config the architecture-dependent serial driver configuration. + * If this parameter is set to @p NULL then a default + * configuration is used. */ void sdStart(SerialDriver *sdp, const SerialConfig *config) { @@ -152,11 +153,11 @@ void sdStart(SerialDriver *sdp, const SerialConfig *config) { } /** - * @brief Stops the driver. + * @brief Stops the driver. * @details Any thread waiting on the driver's queues will be awakened with * the message @p Q_RESET. * - * @param[in] sdp pointer to a @p SerialDrive object + * @param[in] sdp pointer to a @p SerialDrive object */ void sdStop(SerialDriver *sdp) { @@ -175,18 +176,18 @@ void sdStop(SerialDriver *sdp) { } /** - * @brief Handles incoming data. + * @brief Handles incoming data. * @details This function must be called from the input interrupt service * routine in order to enqueue incoming data and generate the * related events. - * @note The incoming data event is only generated when the input queue - * becomes non-empty. - * @note In order to gain some performance it is suggested to not use - * this function directly but copy this code directly into the - * interrupt service routine. + * @note The incoming data event is only generated when the input queue + * becomes non-empty. + * @note In order to gain some performance it is suggested to not use + * this function directly but copy this code directly into the + * interrupt service routine. * - * @param[in] sdp pointer to a @p SerialDriver structure - * @param[in] b the byte to be written in the driver's Input Queue + * @param[in] sdp pointer to a @p SerialDriver structure + * @param[in] b the byte to be written in the driver's Input Queue */ void sdIncomingDataI(SerialDriver *sdp, uint8_t b) { @@ -199,17 +200,17 @@ void sdIncomingDataI(SerialDriver *sdp, uint8_t b) { } /** - * @brief Handles outgoing data. + * @brief Handles outgoing data. * @details Must be called from the output interrupt service routine in order * to get the next byte to be transmitted. - * @note In order to gain some performance it is suggested to not use - * this function directly but copy this code directly into the - * interrupt service routine. + * @note In order to gain some performance it is suggested to not use + * this function directly but copy this code directly into the + * interrupt service routine. * - * @param[in] sdp pointer to a @p SerialDriver structure - * @return The byte value read from the driver's output queue. - * @retval Q_EMPTY if the queue is empty (the lower driver usually disables - * the interrupt source when this happens). + * @param[in] sdp pointer to a @p SerialDriver structure + * @return The byte value read from the driver's output queue. + * @retval Q_EMPTY if the queue is empty (the lower driver usually + * disables the interrupt source when this happens). */ msg_t sdRequestDataI(SerialDriver *sdp) { msg_t b; @@ -223,12 +224,12 @@ msg_t sdRequestDataI(SerialDriver *sdp) { } /** - * @brief Handles communication events/errors. + * @brief Handles communication events/errors. * @details Must be called from the I/O interrupt service routine in order to * notify I/O conditions as errors, signals change etc. * - * @param[in] sdp pointer to a @p SerialDriver structure - * @param[in] mask condition flags to be added to the mask + * @param[in] sdp pointer to a @p SerialDriver structure + * @param[in] mask condition flags to be added to the mask */ void sdAddFlagsI(SerialDriver *sdp, sdflags_t mask) { @@ -239,11 +240,11 @@ void sdAddFlagsI(SerialDriver *sdp, sdflags_t mask) { } /** - * @brief Returns and clears the errors mask associated to the driver. + * @brief Returns and clears the errors mask associated to the driver. * - * @param[in] sdp pointer to a @p SerialDriver structure - * @return The condition flags modified since last time this function was - * invoked. + * @param[in] sdp pointer to a @p SerialDriver structure + * @return The condition flags modified since last time this + * function was invoked. */ sdflags_t sdGetAndClearFlags(SerialDriver *sdp) { sdflags_t mask; diff --git a/os/hal/src/spi.c b/os/hal/src/spi.c index 36bde9a3a..611a454a7 100644 --- a/os/hal/src/spi.c +++ b/os/hal/src/spi.c @@ -18,8 +18,9 @@ */ /** - * @file spi.c - * @brief SPI Driver code. + * @file spi.c + * @brief SPI Driver code. + * * @addtogroup SPI * @{ */ @@ -46,7 +47,7 @@ /*===========================================================================*/ /** - * @brief SPI Driver initialization. + * @brief SPI Driver initialization. */ void spiInit(void) { @@ -54,7 +55,7 @@ void spiInit(void) { } /** - * @brief Initializes the standard part of a @p SPIDriver structure. + * @brief Initializes the standard part of a @p SPIDriver structure. * * @param[in] spip pointer to the @p SPIDriver object */ @@ -70,7 +71,7 @@ void spiObjectInit(SPIDriver *spip) { } /** - * @brief Configures and activates the SPI peripheral. + * @brief Configures and activates the SPI peripheral. * * @param[in] spip pointer to the @p SPIDriver object * @param[in] config pointer to the @p SPIConfig object @@ -108,7 +109,7 @@ void spiStop(SPIDriver *spip) { } /** - * @brief Asserts the slave select signal and prepares for transfers. + * @brief Asserts the slave select signal and prepares for transfers. * * @param[in] spip pointer to the @p SPIDriver object */ @@ -127,7 +128,7 @@ void spiSelect(SPIDriver *spip) { } /** - * @brief Deasserts the slave select signal. + * @brief Deasserts the slave select signal. * @details The previously selected peripheral is unselected. * * @param[in] spip pointer to the @p SPIDriver object @@ -147,7 +148,7 @@ void spiUnselect(SPIDriver *spip) { } /** - * @brief Ignores data on the SPI bus. + * @brief Ignores data on the SPI bus. * @details This function transmits a series of idle words on the SPI bus and * ignores the received data. This function can be invoked even * when a slave select signal has not been yet asserted. @@ -166,16 +167,15 @@ void spiIgnore(SPIDriver *spip, size_t n) { } /** - * @brief Exchanges data on the SPI bus. + * @brief Exchanges data on the SPI bus. * @details This function performs a simultaneous transmit/receive operation. + * @note The buffers are organized as uint8_t arrays for data sizes below + * or equal to 8 bits else it is organized as uint16_t arrays. * * @param[in] spip pointer to the @p SPIDriver object * @param[in] n number of words to be exchanged * @param[in] txbuf the pointer to the transmit buffer * @param[out] rxbuf the pointer to the receive buffer - * - * @note The buffers are organized as uint8_t arrays for data sizes below or - * equal to 8 bits else it is organized as uint16_t arrays. */ void spiExchange(SPIDriver *spip, size_t n, const void *txbuf, void *rxbuf) { @@ -189,14 +189,13 @@ void spiExchange(SPIDriver *spip, size_t n, const void *txbuf, void *rxbuf) { } /** - * @brief Sends data ever the SPI bus. + * @brief Sends data ever the SPI bus. + * @note The buffers are organized as uint8_t arrays for data sizes below + * or equal to 8 bits else it is organized as uint16_t arrays. * * @param[in] spip pointer to the @p SPIDriver object * @param[in] n number of words to send * @param[in] txbuf the pointer to the transmit buffer - * - * @note The buffers are organized as uint8_t arrays for data sizes below or - * equal to 8 bits else it is organized as uint16_t arrays. */ void spiSend(SPIDriver *spip, size_t n, const void *txbuf) { @@ -210,14 +209,13 @@ void spiSend(SPIDriver *spip, size_t n, const void *txbuf) { } /** - * @brief Receives data from the SPI bus. + * @brief Receives data from the SPI bus. + * @note The buffers are organized as uint8_t arrays for data sizes below + * or equal to 8 bits else it is organized as uint16_t arrays. * * @param[in] spip pointer to the @p SPIDriver object * @param[in] n number of words to receive * @param[out] rxbuf the pointer to the receive buffer - * - * @note The buffers are organized as uint8_t arrays for data sizes below or - * equal to 8 bits else it is organized as uint16_t arrays. */ void spiReceive(SPIDriver *spip, size_t n, void *rxbuf) { @@ -232,14 +230,14 @@ void spiReceive(SPIDriver *spip, size_t n, void *rxbuf) { #if SPI_USE_MUTUAL_EXCLUSION || defined(__DOXYGEN__) /** - * @brief Gains exclusive access to the SPI bus. + * @brief Gains exclusive access to the SPI bus. * @details This function tries to gain ownership to the SPI bus, if the bus * is already being used then the invoking thread is queued. + * @note This function is only available when the @p SPI_USE_MUTUAL_EXCLUSION + * option is set to @p TRUE. * * @param[in] spip pointer to the @p SPIDriver object * - * @note This function is only available when the @p SPI_USE_MUTUAL_EXCLUSION - * option is set to @p TRUE. */ void spiAcquireBus(SPIDriver *spip) { @@ -253,12 +251,11 @@ void spiAcquireBus(SPIDriver *spip) { } /** - * @brief Releases exclusive access to the SPI bus. + * @brief Releases exclusive access to the SPI bus. + * @note This function is only available when the @p SPI_USE_MUTUAL_EXCLUSION + * option is set to @p TRUE. * * @param[in] spip pointer to the @p SPIDriver object - * - * @note This function is only available when the @p SPI_USE_MUTUAL_EXCLUSION - * option is set to @p TRUE. */ void spiReleaseBus(SPIDriver *spip) { diff --git a/os/hal/templates/meta/driver.c b/os/hal/templates/meta/driver.c index 77b854bd8..e4d6e5748 100644 --- a/os/hal/templates/meta/driver.c +++ b/os/hal/templates/meta/driver.c @@ -18,8 +18,9 @@ */ /** - * @file XXX.c - * @brief XXX Driver code. + * @file xxx.c + * @brief XXX Driver code. + * * @addtogroup XXX * @{ */ @@ -46,7 +47,7 @@ /*===========================================================================*/ /** - * @brief XXX Driver initialization. + * @brief XXX Driver initialization. */ void xxxInit(void) { @@ -54,7 +55,7 @@ void xxxInit(void) { } /** - * @brief Initializes the standard part of a @p XXXDriver structure. + * @brief Initializes the standard part of a @p XXXDriver structure. * * @param[in] xxxp pointer to the @p XXXDriver object */ @@ -65,7 +66,7 @@ void xxxObjectInit(XXXDriver *xxxp) { } /** - * @brief Configures and activates the XXX peripheral. + * @brief Configures and activates the XXX peripheral. * * @param[in] xxxp pointer to the @p XXXDriver object * @param[in] config pointer to the @p XXXConfig object @@ -85,7 +86,7 @@ void xxxStart(XXXDriver *xxxp, const XXXConfig *config) { } /** - * @brief Deactivates the XXX peripheral. + * @brief Deactivates the XXX peripheral. * * @param[in] xxxp pointer to the @p XXXDriver object */ diff --git a/os/hal/templates/meta/driver.h b/os/hal/templates/meta/driver.h index 7a54cfcb4..762e54c7c 100644 --- a/os/hal/templates/meta/driver.h +++ b/os/hal/templates/meta/driver.h @@ -18,8 +18,9 @@ */ /** - * @file xxx.h - * @brief XXX Driver macros and structures. + * @file xxx.h + * @brief XXX Driver macros and structures. + * * @addtogroup XXX * @{ */ @@ -46,12 +47,12 @@ /*===========================================================================*/ /** - * @brief Driver state machine possible states. + * @brief Driver state machine possible states. */ typedef enum { - XXX_UNINIT = 0, /**< @brief Not initialized. */ - XXX_STOP = 1, /**< @brief Stopped. */ - XXX_READY = 2, /**< @brief Ready. */ + XXX_UNINIT = 0, /**< @brief Not initialized. */ + XXX_STOP = 1, /**< @brief Stopped. */ + XXX_READY = 2, /**< @brief Ready. */ } xxxstate_t; #include "xxx_lld.h" diff --git a/os/hal/templates/meta/driver_lld.c b/os/hal/templates/meta/driver_lld.c index 71f8911d0..787ac388d 100644 --- a/os/hal/templates/meta/driver_lld.c +++ b/os/hal/templates/meta/driver_lld.c @@ -18,8 +18,9 @@ */ /** - * @file templates/xxx_lld.c - * @brief XXX Driver subsystem low level driver source template. + * @file templates/xxx_lld.c + * @brief XXX Driver subsystem low level driver source template. + * * @addtogroup XXX_LLD * @{ */ @@ -50,16 +51,16 @@ /*===========================================================================*/ /** - * @brief Low level XXX driver initialization. + * @brief Low level XXX driver initialization. */ void xxx_lld_init(void) { } /** - * @brief Configures and activates the XXX peripheral. + * @brief Configures and activates the XXX peripheral. * - * @param[in] xxxp pointer to the @p XXXDriver object + * @param[in] xxxp pointer to the @p XXXDriver object */ void xxx_lld_start(XXXDriver *xxxp) { @@ -70,9 +71,9 @@ void xxx_lld_start(XXXDriver *xxxp) { } /** - * @brief Deactivates the XXX peripheral. + * @brief Deactivates the XXX peripheral. * - * @param[in] xxxp pointer to the @p XXXDriver object + * @param[in] xxxp pointer to the @p XXXDriver object */ void xxx_lld_stop(XXXDriver *xxxp) { diff --git a/os/hal/templates/meta/driver_lld.h b/os/hal/templates/meta/driver_lld.h index 43824aa94..409523cfb 100644 --- a/os/hal/templates/meta/driver_lld.h +++ b/os/hal/templates/meta/driver_lld.h @@ -18,8 +18,9 @@ */ /** - * @file templates/xxx_lld.h - * @brief XXX Driver subsystem low level driver header template. + * @file templates/xxx_lld.h + * @brief XXX Driver subsystem low level driver header template. + * * @addtogroup XXX_LLD * @{ */ @@ -46,15 +47,15 @@ /*===========================================================================*/ /** - * @brief Driver configuration structure. - * @note It could be empty on some architectures. + * @brief Driver configuration structure. + * @note It could be empty on some architectures. */ typedef struct { } XXXConfig; /** - * @brief Structure representing an XXX driver. + * @brief Structure representing an XXX driver. */ typedef struct { /**