Mihail Stoyanov / USBDevice

Fork of the official USBDevice library

Fork of USBDevice by mbed official

USBMSD/USBMSD.h@73:8d28a0cb7b43, 2017-04-28 (annotated)

Committer:
screamer
Date:
Fri Apr 28 11:26:51 2017 +0100
Branch:
github-merge
Revision:
73:8d28a0cb7b43
Parent:
47:a0cd9646ecd1 
Merge from mbed-os @ github

Who changed what in which revision?

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