tmk_core/tool/mbed/mbed-sdk/libraries/USBDevice/USBMSD/USBMSD.h

   1 /* Copyright (c) 2010-2011 mbed.org, MIT License
   2 *
   3 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
   4 * and associated documentation files (the "Software"), to deal in the Software without
   5 * restriction, including without limitation the rights to use, copy, modify, merge, publish,
   6 * distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
   7 * Software is furnished to do so, subject to the following conditions:
   8 *
   9 * The above copyright notice and this permission notice shall be included in all copies or
  10 * substantial portions of the Software.
  11 *
  12 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
  13 * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  14 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
  15 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  16 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  17 */
  18
  19
  20 #ifndef USBMSD_H
  21 #define USBMSD_H
  22
  23 /* These headers are included for child class. */
  24 #include "USBEndpoints.h"
  25 #include "USBDescriptor.h"
  26 #include "USBDevice_Types.h"
  27
  28 #include "USBDevice.h"
  29
  30 /**
  31  * USBMSD class: generic class in order to use all kinds of blocks storage chip
  32  *
  33  * Introduction
  34  *
  35  * The USBMSD implements the MSD protocol. It permits to access a memory chip (flash, sdcard,...)
  36  * from a computer over USB. But this class doesn't work standalone, you need to subclass this class
  37  * and define virtual functions which are called in USBMSD.
  38  *
  39  * How to use this class with your chip ?
  40  *
  41  * You have to inherit and define some pure virtual functions (mandatory step):
  42  *   - virtual int disk_read(char * data, int block): function to read a block
  43  *   - virtual int disk_write(const char * data, int block): function to write a block
  44  *   - virtual int disk_initialize(): function to initialize the memory
  45  *   - virtual int disk_sectors(): return the number of blocks
  46  *   - virtual int disk_size(): return the memory size
  47  *   - virtual int disk_status(): return the status of the storage chip (0: OK, 1: not initialized, 2: no medium in the drive, 4: write protection)
  48  *
  49  * All functions names are compatible with the fat filesystem library. So you can imagine using your own class with
  50  * USBMSD and the fat filesystem library in the same program. Just be careful because there are two different parts which
  51  * will access the sd card. You can do a master/slave system using the disk_status method.
  52  *
  53  * Once these functions defined, you can call connect() (at the end of the constructor of your class for instance)
  54  * of USBMSD to connect your mass storage device. connect() will first call disk_status() to test the status of the disk.
  55  * If disk_status() returns 1 (disk not initialized), then disk_initialize() is called. After this step, connect() will collect information
  56  * such as the number of blocks and the memory size.
  57  */
  58 class USBMSD: public USBDevice {
  59 public:
  60
  61     /**
  62     * Constructor
  63     *
  64     * @param vendor_id Your vendor_id
  65     * @param product_id Your product_id
  66     * @param product_release Your preoduct_release
  67     */
  68     USBMSD(uint16_t vendor_id = 0x0703, uint16_t product_id = 0x0104, uint16_t product_release = 0x0001);
  69
  70     /**
  71     * Connect the USB MSD device. Establish disk initialization before really connect the device.
  72     *
  73     * @param blocking if not configured
  74     * @returns true if successful
  75     */
  76     bool connect(bool blocking = true);
  77
  78     /**
  79     * Disconnect the USB MSD device.
  80     */
  81     void disconnect();
  82
  83     /**
  84     * Destructor
  85     */
  86     ~USBMSD();
  87
  88 protected:
  89
  90     /*
  91     * read one or more blocks on a storage chip
  92     *
  93     * @param data pointer where will be stored read data
  94     * @param block starting block number
  95     * @param count number of blocks to read
  96     * @returns 0 if successful
  97     */
  98     virtual int disk_read(uint8_t* data, uint64_t block, uint8_t count) = 0;
  99
 100     /*
 101     * write one or more blocks on a storage chip
 102     *
 103     * @param data data to write
 104     * @param block starting block number
 105     * @param count number of blocks to write
 106     * @returns 0 if successful
 107     */
 108     virtual int disk_write(const uint8_t* data, uint64_t block, uint8_t count) = 0;
 109
 110     /*
 111     * Disk initilization
 112     */
 113     virtual int disk_initialize() = 0;
 114
 115     /*
 116     * Return the number of blocks
 117     *
 118     * @returns number of blocks
 119     */
 120     virtual uint64_t disk_sectors() = 0;
 121
 122     /*
 123     * Return memory size
 124     *
 125     * @returns memory size
 126     */
 127     virtual uint64_t disk_size() = 0;
 128
 129
 130     /*
 131     * To check the status of the storage chip
 132     *
 133     * @returns status: 0: OK, 1: disk not initialized, 2: no medium in the drive, 4: write protected
 134     */
 135     virtual int disk_status() = 0;
 136
 137     /*
 138     * Get string product descriptor
 139     *
 140     * @returns pointer to the string product descriptor
 141     */
 142     virtual uint8_t * stringIproductDesc();
 143
 144     /*
 145     * Get string interface descriptor
 146     *
 147     * @returns pointer to the string interface descriptor
 148     */
 149     virtual uint8_t * stringIinterfaceDesc();
 150
 151     /*
 152     * Get configuration descriptor
 153     *
 154     * @returns pointer to the configuration descriptor
 155     */
 156     virtual uint8_t * configurationDesc();
 157
 158     /*
 159     * Callback called when a packet is received
 160     */
 161     virtual bool EPBULK_OUT_callback();
 162
 163     /*
 164     * Callback called when a packet has been sent
 165     */
 166     virtual bool EPBULK_IN_callback();
 167
 168     /*
 169     * Set configuration of device. Add endpoints
 170     */
 171     virtual bool USBCallback_setConfiguration(uint8_t configuration);
 172
 173     /*
 174     * Callback called to process class specific requests
 175     */
 176     virtual bool USBCallback_request();
 177
 178
 179 private:
 180
 181     // MSC Bulk-only Stage
 182     enum Stage {
 183         READ_CBW,     // wait a CBW
 184         ERROR,        // error
 185         PROCESS_CBW,  // process a CBW request
 186         SEND_CSW,     // send a CSW
 187         WAIT_CSW,     // wait that a CSW has been effectively sent
 188     };
 189
 190     // Bulk-only CBW
 191     typedef struct {
 192         uint32_t Signature;
 193         uint32_t Tag;
 194         uint32_t DataLength;
 195         uint8_t  Flags;
 196         uint8_t  LUN;
 197         uint8_t  CBLength;
 198         uint8_t  CB[16];
 199     } PACKED CBW;
 200
 201     // Bulk-only CSW
 202     typedef struct {
 203         uint32_t Signature;
 204         uint32_t Tag;
 205         uint32_t DataResidue;
 206         uint8_t  Status;
 207     } PACKED CSW;
 208
 209     //state of the bulk-only state machine
 210     Stage stage;
 211
 212     // current CBW
 213     CBW cbw;
 214
 215     // CSW which will be sent
 216     CSW csw;
 217
 218     // addr where will be read or written data
 219     uint32_t addr;
 220
 221     // length of a reading or writing
 222     uint32_t length;
 223
 224     // memory OK (after a memoryVerify)
 225     bool memOK;
 226
 227     // cache in RAM before writing in memory. Useful also to read a block.
 228     uint8_t * page;
 229
 230     int BlockSize;
 231     uint64_t MemorySize;
 232     uint64_t BlockCount;
 233
 234     void CBWDecode(uint8_t * buf, uint16_t size);
 235     void sendCSW (void);
 236     bool inquiryRequest (void);
 237     bool write (uint8_t * buf, uint16_t size);
 238     bool readFormatCapacity();
 239     bool readCapacity (void);
 240     bool infoTransfer (void);
 241     void memoryRead (void);
 242     bool modeSense6 (void);
 243     void testUnitReady (void);
 244     bool requestSense (void);
 245     void memoryVerify (uint8_t * buf, uint16_t size);
 246     void memoryWrite (uint8_t * buf, uint16_t size);
 247     void reset();
 248     void fail();
 249 };
 250
 251 #endif