Fixed few newly introduced documentation errors. Improved card detection.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@4364 35acf78f-673a-0410-8e92-d51de3d6d3f4

2 files changed, 59 insertions, 37 deletions

diff --git a/os/hal/include/io_block.h b/os/hal/include/io_block.h
index 90b17be13..b079ac847 100644
--- a/os/hal/include/io_block.h
+++ b/os/hal/include/io_block.h
@@ -113,17 +113,39 @@ typedef struct {
  */

 /**

  * @brief   Returns the driver state.

+ * @note    Can be called in ISR context.

  *

  * @param[in] ip        pointer to a @p BaseBlockDevice or derived class

  *

  * @return              The driver state.

  *

- * @api

+ * @special

  */

 #define blkGetDriverState(ip) ((ip)->state)

 

 /**

+ * @brief   Determines if the device is transferring data.

+ * @note    Can be called in ISR context.

+ *

+ * @param[in] ip        pointer to a @p BaseBlockDevice or derived class

+ *

+ * @return              The driver state.

+ * @retval FALSE        the device is not transferring data.

+ * @retval TRUE         the device not transferring data.

+ *

+ * @special

+ */

+#define blkIsTransferring(ip) ((((ip)->state) == BLK_CONNECTING) ||         \

+                               (((ip)->state) == BLK_DISCONNECTING) ||      \

+                               (((ip)->state) == BLK_READING) ||            \

+                               (((ip)->state) == BLK_WRITING))

+

+/**

  * @brief   Returns the media insertion status.

+ * @note    On some implementations this function can only be called if the

+ *          device is not transferring data.

+ *          The function @p blkIsTransferring() should be used before calling

+ *          this function.

  *

  * @param[in] ip        pointer to a @p BaseBlockDevice or derived class

  *

@@ -157,8 +179,8 @@ typedef struct {
  * @param[in] ip        pointer to a @p BaseBlockDevice or derived class

  *

  * @return              The operation status.

- * @retval FALSE        operation succeeded.

- * @retval TRUE         operation failed.

+ * @retval CH_SUCCESS   operation succeeded.

+ * @retval CH_FAILED    operation failed.

  *

  * @api

  */

@@ -171,8 +193,8 @@ typedef struct {
  * @param[in] ip        pointer to a @p BaseBlockDevice or derived class

  *

  * @return              The operation status.

- * @retval FALSE        operation succeeded.

- * @retval TRUE         operation failed.

+ * @retval CH_SUCCESS   operation succeeded.

+ * @retval CH_FAILED    operation failed.

  *

  * @api

  */

@@ -187,8 +209,8 @@ typedef struct {
  * @param[in] n         number of blocks to read

  *

  * @return              The operation status.

- * @retval FALSE        operation succeeded.

- * @retval TRUE         operation failed.

+ * @retval CH_SUCCESS   operation succeeded.

+ * @retval CH_FAILED    operation failed.

  *

  * @api

  */

@@ -204,8 +226,8 @@ typedef struct {
  * @param[in] n         number of blocks to write

  *

  * @return              The operation status.

- * @retval FALSE        operation succeeded.

- * @retval TRUE         operation failed.

+ * @retval CH_SUCCESS   operation succeeded.

+ * @retval CH_FAILED    operation failed.

  *

  * @api

  */

@@ -218,8 +240,8 @@ typedef struct {
  * @param[in] ip        pointer to a @p BaseBlockDevice or derived class

  *

  * @return              The operation status.

- * @retval FALSE        operation succeeded.

- * @retval TRUE         operation failed.

+ * @retval CH_SUCCESS   operation succeeded.

+ * @retval CH_FAILED    operation failed.

  *

  * @api

  */

@@ -232,8 +254,8 @@ typedef struct {
  * @param[out] bdip     pointer to a @p BlockDeviceInfo structure

  *

  * @return              The operation status.

- * @retval FALSE        operation succeeded.

- * @retval TRUE         operation failed.

+ * @retval CH_SUCCESS   operation succeeded.

+ * @retval CH_FAILED    operation failed.

  *

  * @api

  */

diff --git a/os/hal/src/mmc_spi.c b/os/hal/src/mmc_spi.c
index 96167a950..f8056f392 100644
--- a/os/hal/src/mmc_spi.c
+++ b/os/hal/src/mmc_spi.c
@@ -293,8 +293,8 @@ static uint8_t send_command_R3(MMCDriver *mmcp, uint8_t cmd, uint32_t arg,
  * @param[out] csd       pointer to the CSD buffer

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @notapi

  */

@@ -431,9 +431,9 @@ void mmcStop(MMCDriver *mmcp) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded and the driver is now

+ * @retval CH_SUCCESS   the operation succeeded and the driver is now

  *                      in the @p MMC_READY state.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -538,9 +538,9 @@ failed:
  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @return              The operation status.

  *

- * @retval CH_FAILED    the operation succeeded and the driver is now

+ * @retval CH_SUCCESS   the operation succeeded and the driver is now

  *                      in the @p MMC_INSERTED state.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -573,8 +573,8 @@ bool_t mmcDisconnect(MMCDriver *mmcp) {
  * @param[in] startblk  first block to read

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -611,8 +611,8 @@ bool_t mmcStartSequentialRead(MMCDriver *mmcp, uint32_t startblk) {
  * @param[out] buffer   pointer to the read buffer

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -645,8 +645,8 @@ bool_t mmcSequentialRead(MMCDriver *mmcp, uint8_t *buffer) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -677,8 +677,8 @@ bool_t mmcStopSequentialRead(MMCDriver *mmcp) {
  * @param[in] startblk  first block to write

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -713,8 +713,8 @@ bool_t mmcStartSequentialWrite(MMCDriver *mmcp, uint32_t startblk) {
  * @param[out] buffer   pointer to the write buffer

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -748,8 +748,8 @@ bool_t mmcSequentialWrite(MMCDriver *mmcp, const uint8_t *buffer) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -775,8 +775,8 @@ bool_t mmcStopSequentialWrite(MMCDriver *mmcp) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -798,8 +798,8 @@ bool_t mmcSync(MMCDriver *mmcp) {
  * @param[out] bdip     pointer to a @p BlockDeviceInfo structure

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */

@@ -824,8 +824,8 @@ bool_t mmcGetInfo(MMCDriver *mmcp, BlockDeviceInfo *bdip) {
  * @param[in] endblk    ending block number

  *

  * @return              The operation status.

- * @retval CH_FAILED    the operation succeeded.

- * @retval CH_SUCCESS   the operation failed.

+ * @retval CH_SUCCESS   the operation succeeded.

+ * @retval CH_FAILED    the operation failed.

  *

  * @api

  */