Skip to content

Commit a4a99d6

Browse files
juhaylinenjuhaylinen
committed
SDBlockDevice docs update
1 parent 27dd445 commit a4a99d6

File tree

1 file changed

+44
-15
lines changed

1 file changed

+44
-15
lines changed

‎components/storage/blockdevice/COMPONENT_SD/SDBlockDevice.h

Lines changed: 44 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
#ifndef MBED_SD_BLOCK_DEVICE_H
1818
#define MBED_SD_BLOCK_DEVICE_H
1919

20-
/* If the target has no SPI support then SDCard is not supported */
20+
/* If the target has no SPI support then SD Card is not supported */
2121
#if DEVICE_SPI
2222

2323
#include "BlockDevice.h"
@@ -30,24 +30,35 @@
3030

3131
/** SDBlockDevice class
3232
*
33-
* Access an SD Card using SPI
33+
* Access an SD Card using SPI bus
3434
*/
3535
class SDBlockDevice : public mbed::BlockDevice {
3636
public:
37-
/** Lifetime of an SD card
37+
/** Creates an SDBlockDevice on a SPI bus specified by pins
38+
*
39+
* @param mosi SPI master out, slave in pin
40+
* @param miso SPI master in, slave out pin
41+
* @param sclk SPI clock pin
42+
* @param cs SPI chip select pin
43+
* @param hz Clock speed of the SPI bus (defaults to 1MHz)
44+
* @param crc_on Enable cyclic redundancy check (defaults to disabled)
3845
*/
3946
SDBlockDevice(PinName mosi, PinName miso, PinName sclk, PinName cs, uint64_t hz = 1000000, bool crc_on = 0);
4047
virtual ~SDBlockDevice();
4148

4249
/** Initialize a block device
4350
*
44-
* @return 0 on success or a negative error code on failure
51+
* @return BD_ERROR_OK(0) - success
52+
* BD_ERROR_DEVICE_ERROR - device driver transaction failed
53+
* SD_BLOCK_DEVICE_ERROR_NO_DEVICE - device (SD card) is missing or not connected
54+
* SD_BLOCK_DEVICE_ERROR_UNUSABLE - unusable card
55+
* SD_BLOCK_DEVICE_ERROR_CRC - crc error
4556
*/
4657
virtual int init();
4758

4859
/** Deinitialize a block device
4960
*
50-
* @return 0 on success or a negative error code on failure
61+
* @return BD_ERROR_OK(0) - success
5162
*/
5263
virtual int deinit();
5364

@@ -56,18 +67,30 @@ class SDBlockDevice : public mbed::BlockDevice {
5667
* @param buffer Buffer to write blocks to
5768
* @param addr Address of block to begin reading from
5869
* @param size Size to read in bytes, must be a multiple of read block size
59-
* @return 0 on success, negative error code on failure
70+
* @return BD_ERROR_OK(0) - success
71+
* SD_BLOCK_DEVICE_ERROR_NO_DEVICE - device (SD card) is missing or not connected
72+
* SD_BLOCK_DEVICE_ERROR_CRC - crc error
73+
* SD_BLOCK_DEVICE_ERROR_PARAMETER - invalid parameter
74+
* SD_BLOCK_DEVICE_ERROR_NO_RESPONSE - no response from device
75+
* SD_BLOCK_DEVICE_ERROR_UNSUPPORTED - unsupported command
6076
*/
6177
virtual int read(void *buffer, mbed::bd_addr_t addr, mbed::bd_size_t size);
6278

6379
/** Program blocks to a block device
6480
*
65-
* The blocks must have been erased prior to being programmed
81+
* @note The blocks must have been erased prior to being programmed
6682
*
6783
* @param buffer Buffer of data to write to blocks
6884
* @param addr Address of block to begin writing to
6985
* @param size Size to write in bytes, must be a multiple of program block size
70-
* @return 0 on success, negative error code on failure
86+
* @return BD_ERROR_OK(0) - success
87+
* SD_BLOCK_DEVICE_ERROR_NO_DEVICE - device (SD card) is missing or not connected
88+
* SD_BLOCK_DEVICE_ERROR_CRC - crc error
89+
* SD_BLOCK_DEVICE_ERROR_PARAMETER - invalid parameter
90+
* SD_BLOCK_DEVICE_ERROR_UNSUPPORTED - unsupported command
91+
* SD_BLOCK_DEVICE_ERROR_NO_INIT - device is not initialized
92+
* SD_BLOCK_DEVICE_ERROR_WRITE - SPI write error
93+
* SD_BLOCK_DEVICE_ERROR_ERASE - erase error
7194
*/
7295
virtual int program(const void *buffer, mbed::bd_addr_t addr, mbed::bd_size_t size);
7396

@@ -80,7 +103,13 @@ class SDBlockDevice : public mbed::BlockDevice {
80103
*
81104
* @param addr Address of block to mark as unused
82105
* @param size Size to mark as unused in bytes, must be a multiple of erase block size
83-
* @return 0 on success, negative error code on failure
106+
* @return BD_ERROR_OK(0) - success
107+
* SD_BLOCK_DEVICE_ERROR_NO_DEVICE - device (SD card) is missing or not connected
108+
* SD_BLOCK_DEVICE_ERROR_CRC - crc error
109+
* SD_BLOCK_DEVICE_ERROR_PARAMETER - invalid parameter
110+
* SD_BLOCK_DEVICE_ERROR_UNSUPPORTED - unsupported command
111+
* SD_BLOCK_DEVICE_ERROR_NO_INIT - device is not initialized
112+
* SD_BLOCK_DEVICE_ERROR_ERASE - erase error
84113
*/
85114
virtual int trim(mbed::bd_addr_t addr, mbed::bd_size_t size);
86115

@@ -90,9 +119,9 @@ class SDBlockDevice : public mbed::BlockDevice {
90119
*/
91120
virtual mbed::bd_size_t get_read_size() const;
92121

93-
/** Get the size of a programable block
122+
/** Get the size of a programmable block
94123
*
95-
* @return Size of a programable block in bytes
124+
* @return Size of a programmable block in bytes
96125
* @note Must be a multiple of the read size
97126
*/
98127
virtual mbed::bd_size_t get_program_size() const;
@@ -118,7 +147,7 @@ class SDBlockDevice : public mbed::BlockDevice {
118147

119148
/** Get the BlockDevice class type.
120149
*
121-
* @return A string represent the BlockDevice class type.
150+
* @return A string representation of the BlockDevice class type.
122151
*/
123152
virtual const char *get_type() const;
124153

@@ -167,9 +196,9 @@ class SDBlockDevice : public mbed::BlockDevice {
167196
int _cmd(SDBlockDevice::cmdSupported cmd, uint32_t arg, bool isAcmd = 0, uint32_t *resp = NULL);
168197
int _cmd8();
169198

170-
/* Move the SDCard into the SPI Mode idle state
199+
/* Move the SD Card into the SPI Mode idle state
171200
*
172-
* The card is transitioned from SDCard mode to SPI mode by sending the
201+
* The card is transitioned from SD Card mode to SPI mode by sending the
173202
* CMD0 (GO_IDLE_STATE) command with CS asserted. See the notes in the
174203
* "SPI Startup" section of the comments at the head of the
175204
* implementation file for further details and specification references.
@@ -187,7 +216,7 @@ class SDBlockDevice : public mbed::BlockDevice {
187216

188217
/* SPI functions */
189218
mbed::Timer _spi_timer; /**< Timer Class object used for busy wait */
190-
uint32_t _init_sck; /**< Intial SPI frequency */
219+
uint32_t _init_sck; /**< Initial SPI frequency */
191220
uint32_t _transfer_sck; /**< SPI frequency during data transfer/after initialization */
192221
mbed::SPI _spi; /**< SPI Class object */
193222

0 commit comments

Comments
 (0)