SDBlockDevice.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2012 ARM Limited
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00020  * SOFTWARE.
00021  */
00022 #ifndef MBED_SD_BLOCK_DEVICE_H
00023 #define MBED_SD_BLOCK_DEVICE_H
00024 
00025 /* If the target has no SPI support then SDCard is not supported */
00026 #ifdef DEVICE_SPI
00027 
00028 #include "BlockDevice.h"
00029 #include "mbed.h"
00030 
00031 
00032 /** Access an SD Card using SPI
00033  *
00034  * @code
00035  * #include "mbed.h"
00036  * #include "SDBlockDevice.h"
00037  *
00038  * SDBlockDevice sd(p5, p6, p7, p12); // mosi, miso, sclk, cs
00039  * uint8_t block[512] = "Hello World!\n";
00040  *
00041  * int main() {
00042  *     sd.init();
00043  *     sd.write(block, 0, 512);
00044  *     sd.read(block, 0, 512);
00045  *     printf("%s", block);
00046  *     sd.deinit();
00047  * }
00048  */
00049 class SDBlockDevice : public BlockDevice {
00050 public:
00051     /** Lifetime of an SD card
00052      */
00053     SDBlockDevice(PinName mosi, PinName miso, PinName sclk, PinName cs, uint64_t hz=1000000);
00054     virtual ~SDBlockDevice();
00055 
00056     /** Initialize a block device
00057      *
00058      *  @return         0 on success or a negative error code on failure
00059      */
00060     virtual int init();
00061 
00062     /** Deinitialize a block device
00063      *
00064      *  @return         0 on success or a negative error code on failure
00065      */
00066     virtual int deinit();
00067 
00068     /** Read blocks from a block device
00069      *
00070      *  @param buffer   Buffer to write blocks to
00071      *  @param addr     Address of block to begin reading from
00072      *  @param size     Size to read in bytes, must be a multiple of read block size
00073      *  @return         0 on success, negative error code on failure
00074      */
00075     virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
00076 
00077     /** Program blocks to a block device
00078      *
00079      *  The blocks must have been erased prior to being programmed
00080      *
00081      *  @param buffer   Buffer of data to write to blocks
00082      *  @param addr     Address of block to begin writing to
00083      *  @param size     Size to write in bytes, must be a multiple of program block size
00084      *  @return         0 on success, negative error code on failure
00085      */
00086     virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
00087 
00088     /** Mark blocks as no longer in use
00089      *
00090      *  This function provides a hint to the underlying block device that a region of blocks
00091      *  is no longer in use and may be erased without side effects. Erase must still be called
00092      *  before programming, but trimming allows flash-translation-layers to schedule erases when
00093      *  the device is not busy.
00094      *
00095      *  @param addr     Address of block to mark as unused
00096      *  @param size     Size to mark as unused in bytes, must be a multiple of erase block size
00097      *  @return         0 on success, negative error code on failure
00098      */
00099     virtual int trim(bd_addr_t addr, bd_size_t size);
00100 
00101     /** Get the size of a readable block
00102      *
00103      *  @return         Size of a readable block in bytes
00104      */
00105     virtual bd_size_t get_read_size() const;
00106 
00107     /** Get the size of a programable block
00108      *
00109      *  @return         Size of a programable block in bytes
00110      *  @note Must be a multiple of the read size
00111      */
00112     virtual bd_size_t get_program_size() const;
00113 
00114     /** Get the total size of the underlying device
00115      *
00116      *  @return         Size of the underlying device in bytes
00117      */
00118     virtual bd_size_t size() const;
00119 
00120     /** Enable or disable debugging
00121      *
00122      *  @param          State of debugging
00123      */
00124     virtual void debug(bool dbg);
00125 
00126     /** Set the transfer frequency
00127      *
00128      *  @param         Transfer frequency
00129      *  @note Max frequency supported is 25MHZ
00130      */
00131     virtual int frequency(uint64_t freq);
00132 
00133 
00134 private:
00135     /* Commands : Listed below are commands supported
00136      * in SPI mode for SD card : Only Mandatory ones
00137      */
00138     enum cmdSupported {
00139         CMD_NOT_SUPPORTED = -1,             /**< Command not supported error */
00140         CMD0_GO_IDLE_STATE = 0,             /**< Resets the SD Memory Card */
00141         CMD1_SEND_OP_COND = 1,              /**< Sends host capacity support */
00142         CMD6_SWITCH_FUNC = 6,               /**< Check and Switches card function */
00143         CMD8_SEND_IF_COND = 8,              /**< Supply voltage info */
00144         CMD9_SEND_CSD = 9,                  /**< Provides Card Specific data */
00145         CMD10_SEND_CID = 10,                /**< Provides Card Identification */
00146         CMD12_STOP_TRANSMISSION = 12,       /**< Forces the card to stop transmission */
00147         CMD13_SEND_STATUS = 13,             /**< Card responds with status */
00148         CMD16_SET_BLOCKLEN = 16,            /**< Length for SC card is set */
00149         CMD17_READ_SINGLE_BLOCK = 17,       /**< Read single block of data */
00150         CMD18_READ_MULTIPLE_BLOCK = 18,     /**< Card transfers data blocks to host until interrupted
00151                                                  by a STOP_TRANSMISSION command */
00152         CMD24_WRITE_BLOCK = 24,             /**< Write single block of data */
00153         CMD25_WRITE_MULTIPLE_BLOCK = 25,    /**< Continuously writes blocks of data until
00154                                                  'Stop Tran' token is sent */
00155         CMD27_PROGRAM_CSD = 27,             /**< Programming bits of CSD */
00156         CMD32_ERASE_WR_BLK_START_ADDR = 32, /**< Sets the address of the first write
00157                                                  block to be erased. */
00158         CMD33_ERASE_WR_BLK_END_ADDR = 33,   /**< Sets the address of the last write
00159                                                  block of the continuous range to be erased.*/
00160         CMD38_ERASE = 38,                   /**< Erases all previously selected write blocks */
00161         CMD55_APP_CMD = 55,                 /**< Extend to Applications specific commands */
00162         CMD56_GEN_CMD = 56,                 /**< General Purpose Command */
00163         CMD58_READ_OCR = 58,                /**< Read OCR register of card */
00164         CMD59_CRC_ON_OFF = 59,              /**< Turns the CRC option on or off*/
00165         // App Commands
00166         ACMD6_SET_BUS_WIDTH = 6,
00167         ACMD13_SD_STATUS = 13,
00168         ACMD22_SEND_NUM_WR_BLOCKS = 22,
00169         ACMD23_SET_WR_BLK_ERASE_COUNT = 23,
00170         ACMD41_SD_SEND_OP_COND = 41,
00171         ACMD42_SET_CLR_CARD_DETECT = 42,
00172         ACMD51_SEND_SCR = 51,
00173     };
00174 
00175     uint8_t _card_type;
00176     int _cmd(SDBlockDevice::cmdSupported cmd, uint32_t arg, bool isAcmd=0, uint32_t *resp=NULL);
00177     int _cmd8();
00178 
00179     /*  Move the SDCard into the SPI Mode idle state
00180      *
00181      *  The card is transitioned from SDCard mode to SPI mode by sending the
00182      *  CMD0 (GO_IDLE_STATE) command with CS asserted. See the notes in the
00183      *  "SPI Startup" section of the comments at the head of the
00184      *  implementation file for further details and specification references.
00185      *
00186      *  @return         Response form the card. R1_IDLE_STATE (0x1), the successful
00187      *                  response from CMD0. R1_XXX_XXX for more response
00188      */
00189     uint32_t _go_idle_state();
00190     int _initialise_card();
00191 
00192     uint32_t _sectors;
00193     uint32_t _sd_sectors();
00194 
00195     bool _is_valid_trim(bd_addr_t addr, bd_size_t size);
00196 
00197     /* SPI functions */
00198     Timer _spi_timer;               /**< Timer Class object used for busy wait */
00199     uint32_t _init_sck;             /**< Intial SPI frequency */
00200     uint32_t _transfer_sck;         /**< SPI frequency during data transfer/after initialization */
00201     SPI _spi;                       /**< SPI Class object */
00202 
00203     /* SPI initialization function */
00204     void _spi_init();
00205     uint8_t _cmd_spi(SDBlockDevice::cmdSupported cmd, uint32_t arg);
00206     void _spi_wait(uint8_t count);
00207 
00208     bool _wait_token(uint8_t token);        /**< Wait for token */
00209     bool _wait_ready(uint16_t ms=300);      /**< 300ms default wait for card to be ready */
00210     int _read(uint8_t * buffer, uint32_t length);
00211     int _read_bytes(uint8_t * buffer, uint32_t length);
00212     uint8_t _write(const uint8_t *buffer,uint8_t token, uint32_t length);
00213     int _freq(void);
00214 
00215     /* Chip Select and SPI mode select */
00216     DigitalOut _cs;
00217     void _select();
00218     void _deselect();
00219 
00220     mutable Mutex _lock;
00221     uint32_t _block_size;
00222     uint32_t _erase_size;
00223     bool _is_initialized;
00224     bool _dbg;
00225 };
00226 
00227 #endif  /* DEVICE_SPI */
00228 
00229 #endif  /* MBED_SD_BLOCK_DEVICE_H */