Mihail Stoyanov / USBDevice

Fork of the official USBDevice library

Fork of USBDevice by mbed official

USBMSD/USBMSD.h@76:f0fd8d911b24, 2017-04-28 (annotated)

Committer:
screamer
Date:
Fri Apr 28 17:01:10 2017 +0000
Branch:
device-files
Revision:
76:f0fd8d911b24
Parent:
73:8d28a0cb7b43 
Changed the layout of USBDevice implementation for various targets to match mbed-os/targets. This also reduces the amount of files being compiled as USBDevice code for other targets is not compiled.

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