From 2b1173e29246cbc82f45490d0b1b1443d7bf897a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 14 Jun 2012 16:45:57 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@4276 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/hal/dox/i2s.dox | 31 +++++++++++++ os/hal/dox/tm.dox | 2 +- os/hal/dox/usb.dox | 79 +++++----------------------------- os/hal/hal.dox | 7 +++ os/hal/include/mmc_spi.h | 30 +++++++------ os/hal/include/mmcsd.h | 8 +++- os/hal/include/usb.h | 2 +- os/hal/platforms/STM32/OTGv1/usb_lld.c | 2 +- os/hal/platforms/STM32/sdc_lld.h | 30 +++++++------ os/hal/src/mmc_spi.c | 9 +--- os/hal/src/sdc.c | 2 +- 11 files changed, 94 insertions(+), 108 deletions(-) create mode 100644 os/hal/dox/i2s.dox (limited to 'os/hal') diff --git a/os/hal/dox/i2s.dox b/os/hal/dox/i2s.dox new file mode 100644 index 000000000..2c6cc4ca2 --- /dev/null +++ b/os/hal/dox/i2s.dox @@ -0,0 +1,31 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, + 2011,2012 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 I2S I2S Driver + * @brief Generic I2S Driver. + * @details This module implements a generic I2S driver. + * @pre In order to use the I2S driver the @p HAL_USE_I2S option + * must be enabled in @p halconf.h. + * + * @section i2s_1 Driver State Machine + * + * @ingroup IO + */ diff --git a/os/hal/dox/tm.dox b/os/hal/dox/tm.dox index d895a6d30..c4c537776 100644 --- a/os/hal/dox/tm.dox +++ b/os/hal/dox/tm.dox @@ -19,7 +19,7 @@ */ /** - * @defgroup TM Time Measurement Driver. + * @defgroup TM Time Measurement Driver * * @brief Time Measurement unit. * @details This module implements a time measurement mechanism able to diff --git a/os/hal/dox/usb.dox b/os/hal/dox/usb.dox index 7298e191d..748e41afe 100644 --- a/os/hal/dox/usb.dox +++ b/os/hal/dox/usb.dox @@ -86,7 +86,7 @@ selected -> selected [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<"]; selected -> configured [label="\nSET_CONF(n)\n>event_cb<"]; configured -> selected [label="\nSET_CONF(0)\n>event_cb<"]; - configured -> configured [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<\n\nEndpoints Activity\n >in_cb< or >out_cb<"]; + configured -> configured [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<\n\nEndpoints Activity\n >in_cb< >out_cb< >setup_cb<"]; configured -> ready [label="\nUSB RESET\n>event_cb<"]; } * @enddot @@ -115,57 +115,9 @@ * - OUT endpoints are used by the application to receive data from * the host. * . - * In ChibiOS/RT the endpoints can be configured in two distinct ways: - * - Packet Mode. In this mode the driver invokes a callback each - * time a packet has been received or transmitted. This mode is especially - * suited for those applications handling continuous streams of data. - *

- * States diagram for OUT endpoints in packet mode: - * @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]; - - disabled [label="EP_DISABLED\nDisabled", style="bold"]; - receiving [label="EP_BUSY\nReceiving Packet"]; - idle [label="EP_IDLE\nPacket in Buffer"]; - - disabled -> receiving [label="\nusbInitEndpointI()"]; - receiving -> idle [label="\npacket received\n>out_cb<"]; - idle -> receiving [label="\nusbReadPacketBuffer()\nusbStartReceiveI()"]; - receiving -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; - idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; - } - * @enddot - *

- * States diagram for IN endpoints in packet mode: - * @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]; - - disabled [label="EP_DISABLED\nDisabled", style="bold"]; - transmitting [label="EP_BUSY\nSending Packet"]; - idle [label="EP_IDLE\nBuffer Empty"]; - - disabled -> idle [label="\nusbInitEndpointI()"]; - idle -> transmitting [label="\nusbWritePacketBuffer()\nusbStartTransmitI()"]; - transmitting -> idle [label="\npacket sent\n>in_cb<"]; - transmitting -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; - idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; - } - * @enddot - *

- * - Transaction Mode. In this mode the driver invokes a callback - * only after a large, potentially multi-packet, transfer has been - * completed, a callback is invoked only at the end of the transfer. - *

- * States diagram for OUT endpoints in transaction mode: - * @dot + * The driver invokes a callback after finishing an IN or OUT transaction. + * States diagram for OUT endpoints in transaction mode: + * @dot digraph example { rankdir="LR"; node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", @@ -183,10 +135,10 @@ receiving -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; } - * @enddot - *

- * States diagram for IN endpoints in transaction mode: - * @dot + * @enddot + *

+ * States diagram for IN endpoints in transaction mode: + * @dot digraph example { rankdir="LR"; node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", @@ -204,19 +156,8 @@ transmitting -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; } - * @enddot - *

- * . - * @subsection usb_2_3 USB Packet Buffers - * An important difference between packet and transaction modes is that there - * is a dedicated endpoint buffer in packet mode while in transaction mode - * the application has to specify its own buffer for duration of the whole - * transfer.
- * Packet buffers cannot be accessed directly by the application because those - * could not be necessarily memory mapped, a buffer could be a FIFO or some - * other kind of memory accessible in a special way depending on the - * underlying hardware architecture, the functions @p usbReadPacketI() and - * @p usbWritePacketI() allow to access packet buffers in an abstract way. + * @enddot + *

* * @subsection usb_2_4 USB Callbacks * The USB driver uses callbacks in order to interact with the application. diff --git a/os/hal/hal.dox b/os/hal/hal.dox index 4e21f3940..1ac733957 100644 --- a/os/hal/hal.dox +++ b/os/hal/hal.dox @@ -91,3 +91,10 @@ * @defgroup IO_BLOCK Abstract I/O Block Device * @ingroup IO */ + +/** + * @defgroup MMCSD MMC/SD Block Devices common ancestor + * @details This module implements a common ancestor for all device drivers + * accessing MMC or SD cards. + * @ingroup IO + */ diff --git a/os/hal/include/mmc_spi.h b/os/hal/include/mmc_spi.h index 307ffd3ca..a008292f5 100644 --- a/os/hal/include/mmc_spi.h +++ b/os/hal/include/mmc_spi.h @@ -119,6 +119,21 @@ typedef struct { const SPIConfig *hscfg; } MMCConfig; +/** + * @brief @p MMCDriver specific methods. + */ +#define _mmc_driver_methods \ + _mmcsd_block_device_methods + +/** + * @extends MMCSDBlockDeviceVMT + * + * @brief @p MMCDriver virtual methods table. + */ +struct MMCDriverVMT { + _mmc_driver_methods +}; + /** * @extends MMCSDBlockDevice * @@ -128,7 +143,8 @@ typedef struct { /** * @brief Virtual Methods Table. */ - const struct MMCSDBlockDeviceVMT *vmt; + const struct MMCDriverVMT *vmt; + _mmcsd_block_device_data /** * @brief Driver state. */ @@ -157,18 +173,6 @@ typedef struct { * @brief Addresses use blocks instead of bytes. */ bool_t block_addresses; - /** - * @brief Card CID. - */ - uint32_t cid[4]; - /** - * @brief Card CSD. - */ - uint32_t csd[4]; - /** - * @brief Total number of blocks in card. - */ - uint32_t capacity; } MMCDriver; /*===========================================================================*/ diff --git a/os/hal/include/mmcsd.h b/os/hal/include/mmcsd.h index 7595e1202..a05c2602f 100644 --- a/os/hal/include/mmcsd.h +++ b/os/hal/include/mmcsd.h @@ -183,7 +183,13 @@ * without implementation. */ #define _mmcsd_block_device_data \ - _base_block_device_data + _base_block_device_data \ + /* Card CID.*/ \ + uint32_t cid[4]; \ + /* Card CSD.*/ \ + uint32_t csd[4]; \ + /* Total number of blocks in card.*/ \ + uint32_t capacity; /** * @extends BaseBlockDeviceVMT diff --git a/os/hal/include/usb.h b/os/hal/include/usb.h index 751128c7c..ddf8cb321 100644 --- a/os/hal/include/usb.h +++ b/os/hal/include/usb.h @@ -423,7 +423,7 @@ typedef const USBDescriptor * (*usbgetdescriptor_t)(USBDriver *usbp, * initialized in transaction mode. * @post The endpoint is ready for @p usbStartReceiveI(). * @note The receive transaction size is equal to the space in the queue - * rounded to the lower multiple of a packet size. So make sure there + * rounded to the lower multiple of a packet size. Make sure there * is room for at least one packet in the queue before starting * the receive operation. * diff --git a/os/hal/platforms/STM32/OTGv1/usb_lld.c b/os/hal/platforms/STM32/OTGv1/usb_lld.c index 1132416ee..2efd4dfea 100644 --- a/os/hal/platforms/STM32/OTGv1/usb_lld.c +++ b/os/hal/platforms/STM32/OTGv1/usb_lld.c @@ -989,7 +989,7 @@ void usb_lld_prepare_transmit(USBDriver *usbp, usbep_t ep, * @brief Prepares for a receive transaction on an OUT endpoint. * @post The endpoint is ready for @p usbStartReceiveI(). * @note The receive transaction size is equal to the space in the queue - * rounded to the lower multiple of a packet size. So make sure there + * rounded to the lower multiple of a packet size. Make sure there * is room for at least one packet in the queue before starting * the receive operation. * diff --git a/os/hal/platforms/STM32/sdc_lld.h b/os/hal/platforms/STM32/sdc_lld.h index a2cb6472d..7511bf581 100644 --- a/os/hal/platforms/STM32/sdc_lld.h +++ b/os/hal/platforms/STM32/sdc_lld.h @@ -197,6 +197,21 @@ typedef struct { uint32_t dummy; } SDCConfig; +/** + * @brief @p SDCDriver specific methods. + */ +#define _sdc_driver_methods \ + _mmcsd_block_device_methods + +/** + * @extends MMCSDBlockDeviceVMT + * + * @brief @p SDCDriver virtual methods table. + */ +struct SDCDriverVMT { + _sdc_driver_methods +}; + /** * @brief Structure representing an SDC driver. */ @@ -204,7 +219,8 @@ struct SDCDriver { /** * @brief Virtual Methods Table. */ - const struct MMCSDBlockDeviceVMT *vmt; + const struct SDCDriverVMT *vmt; + _mmcsd_block_device_data /** * @brief Driver state. */ @@ -221,22 +237,10 @@ struct SDCDriver { * @brief Errors flags. */ sdcflags_t errors; - /** - * @brief Card CID. - */ - uint32_t cid[4]; - /** - * @brief Card CSD. - */ - uint32_t csd[4]; /** * @brief Card RCA. */ uint32_t rca; - /** - * @brief Total number of blocks in card. - */ - uint32_t capacity; /* End of the mandatory fields.*/ /** * @brief Thread waiting for I/O completion IRQ. diff --git a/os/hal/src/mmc_spi.c b/os/hal/src/mmc_spi.c index a6dda0dc1..cb045bcb4 100644 --- a/os/hal/src/mmc_spi.c +++ b/os/hal/src/mmc_spi.c @@ -57,7 +57,7 @@ bool_t mmc_write(void *instance, uint32_t startblk, /** * @brief Virtual methods table. */ -static const struct MMCSDBlockDeviceVMT mmc_vmt = { +static const struct MMCDriverVMT mmc_vmt = { (bool_t (*)(void *))mmc_lld_is_card_inserted, (bool_t (*)(void *))mmc_lld_is_write_protected, (bool_t (*)(void *))mmcConnect, @@ -406,13 +406,6 @@ void mmcInit(void) { * @brief Initializes an instance. * * @param[out] mmcp pointer to the @p MMCDriver object - * @param[in] spip pointer to the SPI driver to be used as interface - * @param[in] lscfg low speed configuration for the SPI driver - * @param[in] hscfg high speed configuration for the SPI driver - * @param[in] is_protected function that returns the card write protection - * setting - * @param[in] is_inserted function that returns the card insertion sensor - * status * * @init */ diff --git a/os/hal/src/sdc.c b/os/hal/src/sdc.c index dd0170b4f..728f05566 100644 --- a/os/hal/src/sdc.c +++ b/os/hal/src/sdc.c @@ -46,7 +46,7 @@ /** * @brief Virtual methods table. */ -static const struct MMCSDBlockDeviceVMT sdc_vmt = { +static const struct SDCDriverVMT sdc_vmt = { (bool_t (*)(void *))sdc_lld_is_card_inserted, (bool_t (*)(void *))sdc_lld_is_write_protected, (bool_t (*)(void *))sdcConnect, -- cgit v1.2.3