git.piffa.net Git - arduino/blob - books/pdummies/Libraries/SD/utility/Sd2Card.h

   1 /* Arduino Sd2Card Library
   2  * Copyright (C) 2009 by William Greiman
   3  *
   4  * This file is part of the Arduino Sd2Card Library
   5  *
   6  * This Library is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This Library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with the Arduino Sd2Card Library.  If not, see
  18  * <http://www.gnu.org/licenses/>.
  19  */
  20 #ifndef Sd2Card_h
  21 #define Sd2Card_h
  22 /**
  23  * \file
  24  * Sd2Card class
  25  */
  26 #include "Sd2PinMap.h"
  27 #include "SdInfo.h"
  28 /** Set SCK to max rate of F_CPU/2. See Sd2Card::setSckRate(). */
  29 uint8_t const SPI_FULL_SPEED = 0;
  30 /** Set SCK rate to F_CPU/4. See Sd2Card::setSckRate(). */
  31 uint8_t const SPI_HALF_SPEED = 1;
  32 /** Set SCK rate to F_CPU/8. Sd2Card::setSckRate(). */
  33 uint8_t const SPI_QUARTER_SPEED = 2;
  34
  35 /**
  36  * Define MEGA_SOFT_SPI non-zero to use software SPI on Mega Arduinos.
  37  * Pins used are SS 10, MOSI 11, MISO 12, and SCK 13.
  38  *
  39  * MEGA_SOFT_SPI allows an unmodified Adafruit GPS Shield to be used
  40  * on Mega Arduinos.  Software SPI works well with GPS Shield V1.1
  41  * but many SD cards will fail with GPS Shield V1.0.
  42  */
  43 #define MEGA_SOFT_SPI 0
  44
  45 /**
  46  * Define LEO_SOFT_SPI non-zero to use software SPI on Leonardo Arduinos.
  47  * Pins used are SS 10, MOSI 11, MISO 12, and SCK 13.
  48  *
  49  * LEO_SOFT_SPI allows an unmodified Adafruit GPS Shield to be used
  50  * on Leonardo Arduinos.  Software SPI works well with GPS Shield V1.1
  51  * but many SD cards will fail with GPS Shield V1.0.
  52  */
  53 #define LEO_SOFT_SPI 0
  54
  55 //------------------------------------------------------------------------------
  56 #if MEGA_SOFT_SPI && (defined(__AVR_ATmega1280__)||defined(__AVR_ATmega2560__))
  57 #define SOFTWARE_SPI
  58 #endif  // MEGA_SOFT_SPI
  59 //------------------------------------------------------------------------------
  60 #if LEO_SOFT_SPI && (defined(__AVR_ATmega32U4__))
  61 #define SOFTWARE_SPI
  62 #endif  // LEO_SOFT_SPI
  63 //------------------------------------------------------------------------------
  64 // SPI pin definitions
  65 //
  66 #ifndef SOFTWARE_SPI
  67 // hardware pin defs
  68 /**
  69  * SD Chip Select pin
  70  *
  71  * Warning if this pin is redefined the hardware SS will pin will be enabled
  72  * as an output by init().  An avr processor will not function as an SPI
  73  * master unless SS is set to output mode.
  74  */
  75 /** The default chip select pin for the SD card is SS. */
  76 uint8_t const  SD_CHIP_SELECT_PIN = SS_PIN;
  77 // The following three pins must not be redefined for hardware SPI.
  78 /** SPI Master Out Slave In pin */
  79 uint8_t const  SPI_MOSI_PIN = MOSI_PIN;
  80 /** SPI Master In Slave Out pin */
  81 uint8_t const  SPI_MISO_PIN = MISO_PIN;
  82 /** SPI Clock pin */
  83 uint8_t const  SPI_SCK_PIN = SCK_PIN;
  84 /** optimize loops for hardware SPI */
  85 //#define OPTIMIZE_HARDWARE_SPI  // MEME FIX ME LATER
  86
  87 #else  // SOFTWARE_SPI
  88 // define software SPI pins so Mega/Leonardo can use unmodified GPS Shield
  89 /** SPI chip select pin */
  90 uint8_t const SD_CHIP_SELECT_PIN = 10;
  91 /** SPI Master Out Slave In pin */
  92 uint8_t const SPI_MOSI_PIN = 11;
  93 /** SPI Master In Slave Out pin */
  94 uint8_t const SPI_MISO_PIN = 12;
  95 /** SPI Clock pin */
  96 uint8_t const SPI_SCK_PIN = 13;
  97 #endif  // SOFTWARE_SPI
  98 //------------------------------------------------------------------------------
  99 /** Protect block zero from write if nonzero */
 100 #define SD_PROTECT_BLOCK_ZERO 1
 101 /** init timeout ms */
 102 uint16_t const SD_INIT_TIMEOUT = 2000;
 103 /** erase timeout ms */
 104 uint16_t const SD_ERASE_TIMEOUT = 10000;
 105 /** read timeout ms */
 106 uint16_t const SD_READ_TIMEOUT = 300;
 107 /** write time out ms */
 108 uint16_t const SD_WRITE_TIMEOUT = 600;
 109 //------------------------------------------------------------------------------
 110 // SD card errors
 111 /** timeout error for command CMD0 */
 112 uint8_t const SD_CARD_ERROR_CMD0 = 0X1;
 113 /** CMD8 was not accepted - not a valid SD card*/
 114 uint8_t const SD_CARD_ERROR_CMD8 = 0X2;
 115 /** card returned an error response for CMD17 (read block) */
 116 uint8_t const SD_CARD_ERROR_CMD17 = 0X3;
 117 /** card returned an error response for CMD24 (write block) */
 118 uint8_t const SD_CARD_ERROR_CMD24 = 0X4;
 119 /**  WRITE_MULTIPLE_BLOCKS command failed */
 120 uint8_t const SD_CARD_ERROR_CMD25 = 0X05;
 121 /** card returned an error response for CMD58 (read OCR) */
 122 uint8_t const SD_CARD_ERROR_CMD58 = 0X06;
 123 /** SET_WR_BLK_ERASE_COUNT failed */
 124 uint8_t const SD_CARD_ERROR_ACMD23 = 0X07;
 125 /** card's ACMD41 initialization process timeout */
 126 uint8_t const SD_CARD_ERROR_ACMD41 = 0X08;
 127 /** card returned a bad CSR version field */
 128 uint8_t const SD_CARD_ERROR_BAD_CSD = 0X09;
 129 /** erase block group command failed */
 130 uint8_t const SD_CARD_ERROR_ERASE = 0X0A;
 131 /** card not capable of single block erase */
 132 uint8_t const SD_CARD_ERROR_ERASE_SINGLE_BLOCK = 0X0B;
 133 /** Erase sequence timed out */
 134 uint8_t const SD_CARD_ERROR_ERASE_TIMEOUT = 0X0C;
 135 /** card returned an error token instead of read data */
 136 uint8_t const SD_CARD_ERROR_READ = 0X0D;
 137 /** read CID or CSD failed */
 138 uint8_t const SD_CARD_ERROR_READ_REG = 0X0E;
 139 /** timeout while waiting for start of read data */
 140 uint8_t const SD_CARD_ERROR_READ_TIMEOUT = 0X0F;
 141 /** card did not accept STOP_TRAN_TOKEN */
 142 uint8_t const SD_CARD_ERROR_STOP_TRAN = 0X10;
 143 /** card returned an error token as a response to a write operation */
 144 uint8_t const SD_CARD_ERROR_WRITE = 0X11;
 145 /** attempt to write protected block zero */
 146 uint8_t const SD_CARD_ERROR_WRITE_BLOCK_ZERO = 0X12;
 147 /** card did not go ready for a multiple block write */
 148 uint8_t const SD_CARD_ERROR_WRITE_MULTIPLE = 0X13;
 149 /** card returned an error to a CMD13 status check after a write */
 150 uint8_t const SD_CARD_ERROR_WRITE_PROGRAMMING = 0X14;
 151 /** timeout occurred during write programming */
 152 uint8_t const SD_CARD_ERROR_WRITE_TIMEOUT = 0X15;
 153 /** incorrect rate selected */
 154 uint8_t const SD_CARD_ERROR_SCK_RATE = 0X16;
 155 //------------------------------------------------------------------------------
 156 // card types
 157 /** Standard capacity V1 SD card */
 158 uint8_t const SD_CARD_TYPE_SD1 = 1;
 159 /** Standard capacity V2 SD card */
 160 uint8_t const SD_CARD_TYPE_SD2 = 2;
 161 /** High Capacity SD card */
 162 uint8_t const SD_CARD_TYPE_SDHC = 3;
 163 //------------------------------------------------------------------------------
 164 /**
 165  * \class Sd2Card
 166  * \brief Raw access to SD and SDHC flash memory cards.
 167  */
 168 class Sd2Card {
 169  public:
 170   /** Construct an instance of Sd2Card. */
 171   Sd2Card(void) : errorCode_(0), inBlock_(0), partialBlockRead_(0), type_(0) {}
 172   uint32_t cardSize(void);
 173   uint8_t erase(uint32_t firstBlock, uint32_t lastBlock);
 174   uint8_t eraseSingleBlockEnable(void);
 175   /**
 176    * \return error code for last error. See Sd2Card.h for a list of error codes.
 177    */
 178   uint8_t errorCode(void) const {return errorCode_;}
 179   /** \return error data for last error. */
 180   uint8_t errorData(void) const {return status_;}
 181   /**
 182    * Initialize an SD flash memory card with default clock rate and chip
 183    * select pin.  See sd2Card::init(uint8_t sckRateID, uint8_t chipSelectPin).
 184    */
 185   uint8_t init(void) {
 186     return init(SPI_FULL_SPEED, SD_CHIP_SELECT_PIN);
 187   }
 188   /**
 189    * Initialize an SD flash memory card with the selected SPI clock rate
 190    * and the default SD chip select pin.
 191    * See sd2Card::init(uint8_t sckRateID, uint8_t chipSelectPin).
 192    */
 193   uint8_t init(uint8_t sckRateID) {
 194     return init(sckRateID, SD_CHIP_SELECT_PIN);
 195   }
 196   uint8_t init(uint8_t sckRateID, uint8_t chipSelectPin, int8_t mosiPin = -1, int8_t misoPin = -1, int8_t clockPin = -1);
 197   void partialBlockRead(uint8_t value);
 198   /** Returns the current value, true or false, for partial block read. */
 199   uint8_t partialBlockRead(void) const {return partialBlockRead_;}
 200   uint8_t readBlock(uint32_t block, uint8_t* dst);
 201   uint8_t readData(uint32_t block,
 202           uint16_t offset, uint16_t count, uint8_t* dst);
 203   /**
 204    * Read a cards CID register. The CID contains card identification
 205    * information such as Manufacturer ID, Product name, Product serial
 206    * number and Manufacturing date. */
 207   uint8_t readCID(cid_t* cid) {
 208     return readRegister(CMD10, cid);
 209   }
 210   /**
 211    * Read a cards CSD register. The CSD contains Card-Specific Data that
 212    * provides information regarding access to the card's contents. */
 213   uint8_t readCSD(csd_t* csd) {
 214     return readRegister(CMD9, csd);
 215   }
 216   void readEnd(void);
 217   uint8_t setSckRate(uint8_t sckRateID);
 218   /** Return the card type: SD V1, SD V2 or SDHC */
 219   uint8_t type(void) const {return type_;}
 220   uint8_t writeBlock(uint32_t blockNumber, const uint8_t* src);
 221   uint8_t writeData(const uint8_t* src);
 222   uint8_t writeStart(uint32_t blockNumber, uint32_t eraseCount);
 223   uint8_t writeStop(void);
 224   void    enableCRC(uint8_t mode);
 225
 226  private:
 227   uint32_t block_;
 228   uint8_t chipSelectPin_;
 229   uint8_t errorCode_;
 230   uint8_t inBlock_;
 231   uint16_t offset_;
 232   uint8_t partialBlockRead_;
 233   uint8_t status_;
 234   uint8_t type_;
 235   uint8_t writeCRC_;
 236
 237   // private functions
 238   uint8_t cardAcmd(uint8_t cmd, uint32_t arg) {
 239     cardCommand(CMD55, 0);
 240     return cardCommand(cmd, arg);
 241   }
 242   uint8_t cardCommand(uint8_t cmd, uint32_t arg);
 243   void error(uint8_t code) {errorCode_ = code;}
 244   uint8_t readRegister(uint8_t cmd, void* buf);
 245   uint8_t sendWriteCommand(uint32_t blockNumber, uint32_t eraseCount);
 246   void chipSelectHigh(void);
 247   void chipSelectLow(void);
 248   void type(uint8_t value) {type_ = value;}
 249   uint8_t waitNotBusy(uint16_t timeoutMillis);
 250   uint8_t writeData(uint8_t token, const uint8_t* src);
 251   uint8_t waitStartBlock(void);
 252 };
 253 #endif  // Sd2Card_h