From d4c246e1bf9af0096b69ded8ae65bbf754267754 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 22 Feb 2013 11:34:04 +0000 Subject: Documentation related fixes. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@5298 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/hal/dox/io_block.dox | 101 ++++++++++++++++++++++++++++++++++++++++++++++ os/hal/dox/io_channel.dox | 24 +++++++++++ os/hal/dox/mmc_spi.dox | 92 +++-------------------------------------- os/hal/dox/mmcsd.dox | 28 +++++++++++++ os/hal/dox/sdc.dox | 78 ++--------------------------------- 5 files changed, 162 insertions(+), 161 deletions(-) create mode 100644 os/hal/dox/io_block.dox create mode 100644 os/hal/dox/io_channel.dox create mode 100644 os/hal/dox/mmcsd.dox (limited to 'os/hal/dox') diff --git a/os/hal/dox/io_block.dox b/os/hal/dox/io_block.dox new file mode 100644 index 000000000..9324b50cb --- /dev/null +++ b/os/hal/dox/io_block.dox @@ -0,0 +1,101 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, + 2011,2012,2013 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @defgroup IO_BLOCK Abstract I/O Block Device + * @ingroup IO + * + * @section io_block_1 Driver State Machine + * The drivers implementing this interface shall implement the following + * state machine internally. Not all the driver functionalities can be used + * in any moment, any transition not explicitly shown in the following + * diagram has to be considered an error and shall be captured by an + * assertion (if enabled). + * @if LATEX_PDF + * @dot + digraph example { + size="5, 7"; + rankdir="LR"; + + node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Sans, fontsize=8]; + + stop [label="BLK_STOP\nLow Power"]; + uninit [label="BLK_UNINIT", style="bold"]; + ready [label="BLK_READY\nClock Enabled"]; + connecting [label="BLK_CONN.ING\nConnecting"]; + disconnecting [label="BLK_DISC.ING\nDisconnecting"]; + active [label="BLK_ACTIVE\nCard Ready"]; + reading [label="BLK_READING\nReading"]; + writing [label="BLK_WRITING\nWriting"]; + + uninit -> stop [label=" blkInit()", constraint=false]; + stop -> stop [label="\nblkStop()"]; + stop -> ready [label="\nblkStart()"]; + ready -> stop [label="\nblkStop()"]; + ready -> ready [label="\nblkStart()\nblkDisconnect()"]; + ready -> connecting [label="\nblkConnect()"]; + connecting -> active [label="\nconnection\nsuccessful"]; + connecting -> active [label="\nblkConnect()", dir="back"]; + connecting -> ready [label="\nconnection\nfailed"]; + disconnecting -> active [label="\nblkDisconnect()", dir="back"]; + ready -> disconnecting [label="\ndisconnection\nfinished", dir="back"]; + active -> reading [label="\nblkRead()"]; + reading -> active [label="\nread finished\nread error"]; + active -> writing [label="\nblkWrite()"]; + writing -> active [label="\nwrite finished\nwrite error"]; + } + * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + + node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Sans, fontsize=8]; + + stop [label="BLK_STOP\nLow Power"]; + uninit [label="BLK_UNINIT", style="bold"]; + ready [label="BLK_READY\nClock Enabled"]; + connecting [label="BLK_CONN.ING\nConnecting"]; + disconnecting [label="BLK_DISC.ING\nDisconnecting"]; + active [label="BLK_ACTIVE\nCard Ready"]; + reading [label="BLK_READING\nReading"]; + writing [label="BLK_WRITING\nWriting"]; + + uninit -> stop [label=" blkInit()", constraint=false]; + stop -> stop [label="\nblkStop()"]; + stop -> ready [label="\nblkStart()"]; + ready -> stop [label="\nblkStop()"]; + ready -> ready [label="\nblkStart()\nblkDisconnect()"]; + ready -> connecting [label="\nblkConnect()"]; + connecting -> active [label="\nconnection\nsuccessful"]; + connecting -> active [label="\nblkConnect()", dir="back"]; + connecting -> ready [label="\nconnection\nfailed"]; + disconnecting -> active [label="\nblkDisconnect()", dir="back"]; + ready -> disconnecting [label="\ndisconnection\nfinished", dir="back"]; + active -> reading [label="\nblkRead()"]; + reading -> active [label="\nread finished\nread error"]; + active -> writing [label="\nblkWrite()"]; + writing -> active [label="\nwrite finished\nwrite error"]; + } + * @enddot + * @endif + */ diff --git a/os/hal/dox/io_channel.dox b/os/hal/dox/io_channel.dox new file mode 100644 index 000000000..66c6bae2c --- /dev/null +++ b/os/hal/dox/io_channel.dox @@ -0,0 +1,24 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, + 2011,2012,2013 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @defgroup IO_CHANNEL Abstract I/O Channel + * @ingroup IO + */ diff --git a/os/hal/dox/mmc_spi.dox b/os/hal/dox/mmc_spi.dox index 4ff4fbff7..55dcaafd8 100644 --- a/os/hal/dox/mmc_spi.dox +++ b/os/hal/dox/mmc_spi.dox @@ -28,92 +28,12 @@ * @p HAL_USE_SPI options must be enabled in @p halconf.h. * * @section mmc_spi_1 Driver State Machine - * The driver implements a state machine internally, not all the driver - * functionalities can be used in any moment, any transition not explicitly - * shown in the following diagram has to be considered an error and shall - * be captured by an assertion (if enabled). - * @if LATEX_PDF - * @dot - digraph example { - size="5, 7"; - rankdir="LR"; - node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; - edge [fontname=Helvetica, fontsize=8]; - - any [label="Any State"]; - stop2 [label="MMC_STOP\nLow Power"]; - uninit [label="MMC_UNINIT", style="bold"]; - stop [label="MMC_STOP\nLow Power"]; - wait [label="MMC_WAIT\nWaiting Card"]; - inserted [label="MMC_INSERTED\nCard Inserted"]; - ready [label="MMC_READY\nCard Ready"]; - reading [label="MMC_READING\nReading"]; - writing [label="MMC_WRITING\nWriting"]; - - uninit -> stop [label="mmcInit()"]; - stop -> wait [label="mmcStart()", constraint=false]; - wait -> inserted [label="insertion (inserted event)"]; - inserted -> inserted [label="mmcDisconnect()"]; - inserted -> ready [label="mmcConnect()"]; - ready -> ready [label="mmcConnect()"]; - ready -> inserted [label="mmcDisconnect()"]; - ready -> reading [label="mmcStartSequentialRead()"]; - reading -> reading [label="mmcSequentialRead()"]; - reading -> ready [label="mmcStopSequentialRead()"]; - reading -> ready [label="read error"]; - ready -> writing [label="mmcStartSequentialWrite()"]; - writing -> writing [label="mmcSequentialWrite()"]; - writing -> ready [label="mmcStopSequentialWrite()"]; - writing -> ready [label="write error"]; - inserted -> wait [label="removal (removed event)"]; - ready -> wait [label="removal (removed event)"]; - reading -> wait [label="removal (removed event)"]; - writing -> wait [label="removal (removed event)"]; - - any -> stop2 [label="mmcStop()"]; - } - * @enddot - * @else - * @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]; - - any [label="Any State"]; - stop2 [label="MMC_STOP\nLow Power"]; - uninit [label="MMC_UNINIT", style="bold"]; - stop [label="MMC_STOP\nLow Power"]; - wait [label="MMC_WAIT\nWaiting Card"]; - inserted [label="MMC_INSERTED\nCard Inserted"]; - ready [label="MMC_READY\nCard Ready"]; - reading [label="MMC_READING\nReading"]; - writing [label="MMC_WRITING\nWriting"]; - - uninit -> stop [label="mmcInit()"]; - stop -> wait [label="mmcStart()", constraint=false]; - wait -> inserted [label="insertion (inserted event)"]; - inserted -> inserted [label="mmcDisconnect()"]; - inserted -> ready [label="mmcConnect()"]; - ready -> ready [label="mmcConnect()"]; - ready -> inserted [label="mmcDisconnect()"]; - ready -> reading [label="mmcStartSequentialRead()"]; - reading -> reading [label="mmcSequentialRead()"]; - reading -> ready [label="mmcStopSequentialRead()"]; - reading -> ready [label="read error"]; - ready -> writing [label="mmcStartSequentialWrite()"]; - writing -> writing [label="mmcSequentialWrite()"]; - writing -> ready [label="mmcStopSequentialWrite()"]; - writing -> ready [label="write error"]; - inserted -> wait [label="removal (removed event)"]; - ready -> wait [label="removal (removed event)"]; - reading -> wait [label="removal (removed event)"]; - writing -> wait [label="removal (removed event)"]; - - any -> stop2 [label="mmcStop()"]; - } - * @enddot - * @endif + * This driver implements a state machine internally, see the @ref IO_BLOCK + * module documentation for details. + * + * @section mmc_spi_2 Driver Operations + * This driver allows to read or write single or multiple 512 bytes blocks + * on a SD Card. * * @ingroup IO */ diff --git a/os/hal/dox/mmcsd.dox b/os/hal/dox/mmcsd.dox new file mode 100644 index 000000000..c7551b975 --- /dev/null +++ b/os/hal/dox/mmcsd.dox @@ -0,0 +1,28 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, + 2011,2012,2013 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 MMCSD MMC/SD Block Device + * @details This module implements a common ancestor for all device drivers + * accessing MMC or SD cards. This interface inherits the state + * machine and the interface from the @ref IO_BLOCK module. + * + * @ingroup IO + */ diff --git a/os/hal/dox/sdc.dox b/os/hal/dox/sdc.dox index 58dc22310..073629457 100644 --- a/os/hal/dox/sdc.dox +++ b/os/hal/dox/sdc.dox @@ -26,82 +26,10 @@ * must be enabled in @p halconf.h. * * @section sdc_1 Driver State Machine - * The driver implements a state machine internally, not all the driver - * functionalities can be used in any moment, any transition not explicitly - * shown in the following diagram has to be considered an error and shall - * be captured by an assertion (if enabled). - * @if LATEX_PDF - * @dot - digraph example { - size="5, 7"; - rankdir="LR"; - - node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; - edge [fontname=Sans, fontsize=8]; - - stop [label="SDC_STOP\nLow Power"]; - uninit [label="SDC_UNINIT", style="bold"]; - ready [label="SDC_READY\nClock Enabled"]; - connecting [label="SDC_CONN.ING\nConnecting"]; - disconnecting [label="SDC_DISC.ING\nDisconnecting"]; - active [label="SDC_ACTIVE\nCard Ready"]; - reading [label="SDC_READING\nReading"]; - writing [label="SDC_WRITING\nWriting"]; - - uninit -> stop [label=" sdcInit()", constraint=false]; - stop -> stop [label="\nsdcStop()"]; - stop -> ready [label="\nsdcStart()"]; - ready -> stop [label="\nsdcStop()"]; - ready -> ready [label="\nsdcStart()\nsdcDisconnect()"]; - ready -> connecting [label="\nsdcConnect()"]; - connecting -> active [label="\nconnection\nsuccessful"]; - connecting -> active [label="\nsdcConnect()", dir="back"]; - connecting -> ready [label="\nconnection\nfailed"]; - disconnecting -> active [label="\nsdcDisconnect()", dir="back"]; - ready -> disconnecting [label="\ndisconnection\nfinished", dir="back"]; - active -> reading [label="\nsdcRead()"]; - reading -> active [label="\nread finished\nread error"]; - active -> writing [label="\nsdcWrite()"]; - writing -> active [label="\nwrite finished\nwrite error"]; - } - * @enddot - * @else - * @dot - digraph example { - rankdir="LR"; - - node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; - edge [fontname=Sans, fontsize=8]; - - stop [label="SDC_STOP\nLow Power"]; - uninit [label="SDC_UNINIT", style="bold"]; - ready [label="SDC_READY\nClock Enabled"]; - connecting [label="SDC_CONN.ING\nConnecting"]; - disconnecting [label="SDC_DISC.ING\nDisconnecting"]; - active [label="SDC_ACTIVE\nCard Ready"]; - reading [label="SDC_READING\nReading"]; - writing [label="SDC_WRITING\nWriting"]; - - uninit -> stop [label=" sdcInit()", constraint=false]; - stop -> stop [label="\nsdcStop()"]; - stop -> ready [label="\nsdcStart()"]; - ready -> stop [label="\nsdcStop()"]; - ready -> ready [label="\nsdcStart()\nsdcDisconnect()"]; - ready -> connecting [label="\nsdcConnect()"]; - connecting -> active [label="\nconnection\nsuccessful"]; - connecting -> active [label="\nsdcConnect()", dir="back"]; - connecting -> ready [label="\nconnection\nfailed"]; - disconnecting -> active [label="\nsdcDisconnect()", dir="back"]; - ready -> disconnecting [label="\ndisconnection\nfinished", dir="back"]; - active -> reading [label="\nsdcRead()"]; - reading -> active [label="\nread finished\nread error"]; - active -> writing [label="\nsdcWrite()"]; - writing -> active [label="\nwrite finished\nwrite error"]; - } - * @enddot - * @endif + * This driver implements a state machine internally, see the @ref IO_BLOCK + * module documentation for details. * - * @section sdc_2 SDC Operations. + * @section sdc_2 Driver Operations * This driver allows to read or write single or multiple 512 bytes blocks * on a SD Card. * -- cgit v1.2.3