AN00125: USB Mass Storage Device Class£££doc/rst/an00125.html#an00125-usb-mass-storage-device-class
This application note shows how to create a USB device compliant to the standard
USB mass storage device class on an xmos xcore.ai device.
The code associated with this application note provides an example of using the
XMOS Device Library and associated USB class descriptors to provide a framework for the
creation of a USB mass storage device.
The mass storage framework uses XMOS libraries to provide a bidirectional
mass storage device example over high speed USB.
Note: This application note provides a standard USB Mass Storage Device Class which
addresses Bulk-Only Transport (BOT) or Bulk/Bulk/Bulk (BBB) specification and as a
result does not require drivers to run on Windows, Linux or Mac.
The Peripheral Device Type (PDT) supported in this application note is SCSI (Small Computer
System Interface) Block Command (SBC) Direct-access device (e.g., UHD (Ultra High Definition)
Floppy disk). This example application uses the on-board serial flash M25P16 as its memory device.
This application note is designed to run on an XMOS xcore-200 or xcore.ai series device.
The example code provided with the application has been implemented and tested
on the XK-EVK-XU316 board but there is no dependency on this board and it can be modified to
run on any development board which uses an xcore-200 or xcore.ai series device.
This document assumes familiarity with the XMOS xcore architecture, the Universal Serial
Bus 2.0 Specification (and related specifications), the XMOS tool chain and the xC language.
Documentation related to these aspects which are not specific to this application note are linked to in the references appendix.
For the full API listing of the XMOS USB Device (XUD) Library please see thedocument XMOS USB Device (XUD) Library [1].
AN00125: USB Mass Storage Device Class$$$Overview£££doc/rst/an00125.html#overview
The Universal Serial Bus (USB) is a communication architecture that gives a PC the ability to interconnect a variety of devices via a simple four-wire cable. One such device is the mass storage. Traditionally, mass storage device class provides adaptability for devices like
USB flash drive
memory card reader
digital audio player
digital camera
external hard drive
The USB specification provides as standard device class for the implementation of USB mass storage.
Block diagram of USB Mass storage application example
AN00125: USB Mass Storage Device Class$$$Overview$$$Features£££doc/rst/an00125.html#features
This section describes the features that are supported by the demo application. The application uses an on-board flash with a user memory partition of 2 MB. The application does the following
Enumerates as Mass Storage device
On Windows host, the display appears as `` drive labelled as unformatted Removable Disk ``
On Mac, it displays as `` XMOSLTD Flash Disk Media ``
As there is no file system supported by the application, formatting the drive, read and write operations on the drive is not featured.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note£££doc/rst/an00125.html#usb-mass-storage-device-class-application-note
The demo in this note uses the XMOS USB device library and shows a simple program that receives data from and sends data to the host.
For the USB Mass storage device class application example, the system comprises three tasks running in separate logical cores of a xCORE multicore microcontroller.
The tasks perform the following operations.
A task containing the USB library functionality to communicate over USB
A task implementing Endpoint0 responding both standard and mass storage class USB requests
A task implementing the application code for receiving and sending mass storage data into the device
These tasks communicate via the use of xCONNECT channels which allow data to be passed between application code running on separate logical cores.
The following diagram shows the task and communication structure for this USB mass storage device class application example.
Task diagram of USB mass storage application example
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$CMakeLists.tx additions for this application£££doc/rst/an00125.html#cmakelists-tx-additions-for-this-application
To start using the USB library, you need to add lib_xud to your CMakeLists.txt:
set(APP_DEPENDENT_MODULES"lib_xud")
You can then access the USB functions on your source code via the xud_device.h header file:
#include <xud_device.h>
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$Declaring resource and setting up the USB components£££doc/rst/an00125.html#declaring-resource-and-setting-up-the-usb-components
main.xc contains the application implementation for a device based on the USB mass storage device class. There are some defines in it that are used to configure the XMOS USB device library. These are displayed below.
/*USBEndpointDefines*/#define XUD_EP_COUNT_OUT 2 //Includes EP0 (1 out EP0 + Mass Storage data output EP)#define XUD_EP_COUNT_IN 2 //Includes EP0 (1 in EP0 + Mass Storage data input EP)XUD_EpTypeepTypeTableOut[XUD_EP_COUNT_OUT]={XUD_EPTYPE_CTL|XUD_STATUS_ENABLE,XUD_EPTYPE_BUL};XUD_EpTypeepTypeTableIn[XUD_EP_COUNT_IN]={XUD_EPTYPE_CTL|XUD_STATUS_ENABLE,XUD_EPTYPE_BUL};
These describe the endpoint configuration for this device. This example has bi-directional communication with the host machine via the standard endpoint0, an endpoint for receiving the bulk data from the host into our device and an endpoint for sending the bulk data to host from our device.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$The application main() function£££doc/rst/an00125.html#the-application-main-function
Below is the source code for the main function of this application, which is taken from the source file main.xc
Looking at this in a more detail you can see the following:
The par statement starts three separate tasks in parallel
There is a task to configure and execute the USB library: XUD_Main()
There is a task to startup and run the Endpoint0 code: Endpoint0()
There is a task to deal with USB mass storage requests arriving from the host: massStorageClass()
The define USB_TILE describes the tile on which the individual tasks will run
In this example all tasks run on the same tile as the USB PHY although this is only a requirement of XUD_Main()
The xCONNECT communication channels used by the application are set up at the beginning of main()
The USB defines discussed earlier are passed into the function XUD_Main()
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$Configuring the USB Device ID£££doc/rst/an00125.html#configuring-the-usb-device-id
The USB ID values used for vendor id, product id and device version number are defined in the file endpoint0.xc. These are used by the host machine to determine the vendor of the device (in this case XMOS) and the product plus the firmware version.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$USB Mass storage Class specific defines£££doc/rst/an00125.html#usb-mass-storage-class-specific-defines
The USB Mass storage Class is configured in the file endpoint0.xc. Below there are a set of standard defines which are used to configure the USB device descriptors to setup a USB mass storage device running on an xCORE microcontroller.
/*USBMassStorageInterfaceSubclassDefinition*/#define USB_MASS_STORAGE_SUBCLASS 0x06 /* SCSI transparent command set *//*USBMassStorageinterfaceprotocol*/#define USB_MASS_STORAGE_PROTOCOL 0x50 /* USB Mass Storage Class Bulk-Only (BBB) Transport *//*USBMassStorageRequestCode*/#define USB_MASS_STORAGE_RESET 0xFF /* Bulk-Only Mass Storage Reset */#define USB_MASS_STORAGE_GML 0xFE /* Get Max LUN (GML) */
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$USB Device Descriptor£££doc/rst/an00125.html#usb-device-descriptor
endpoint0.xc is where the standard USB device descriptor is declared for the mass storage device. Below is the structure which contains this descriptor. This will be requested by the host when the device is enumerated on the USB bus.
From this descriptor you can see that product, vendor and device firmware revision are all coded into this structure. This will allow the host machine to recognise the mass storage device when it is connected to the USB bus.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$USB Configuration Descriptor£££doc/rst/an00125.html#usb-configuration-descriptor
The USB configuration descriptor is used to configure the device in terms of the device class and the endpoint setup. For the USB mass storage device the configuration descriptor which is read by the host is as follows.
From this you can see that the USB mass storage class defines described earlier are encoded into the configuration descriptor along with the bulk USB endpoint description for receiving storage data into the application code. These endpoint allows us to process the storage data request from the host and to the host inside the main mass storage application task.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$USB string descriptor£££doc/rst/an00125.html#usb-string-descriptor
There is one more descriptor within this file relating to the configuration of the USB Mass storage Class. This section should also be modified to match the capabilities of the mass storage device.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$USB Mass storage Class requests£££doc/rst/an00125.html#usb-mass-storage-class-requests
Inside endpoint0.xc there is some code for handling the USB Mass storage device class specific requests. These are shown in the following code:
These mass storage specific request are implemented by the application as they do not form part of the standard requests which have to be accepted by all device classes via endpoint0.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$USB Mass storage Class Endpoint0£££doc/rst/an00125.html#usb-mass-storage-class-endpoint0
The function Endpoint0() contains the code for dealing with device requests made from the host to the standard endpoint0 which is present in all USB devices. In addition to requests required for all devices, the code handles the requests specific to the mass storage device class.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$Receiving storage data from the host£££doc/rst/an00125.html#receiving-storage-data-from-the-host
The application endpoint for Command Transport, Data-In, Data-Out and Status Transport are implemented in the file mass_storage.xc as per the flow shown in below figure. This is contained within the function massStorageClass() which is shown in next page.
Command/Data/Status Flow
void massStorageClass(chanend chan_ep1_out,chanend chan_ep1_in, int writeProtect)
{
unsigned char commandBlock[CBW_SHORT_PACKET_SIZE];
unsigned char commandStatus[CSW_SHORT_PACKET_SIZE];
unsigned host_transfer_length = 0;
int readCapacity[8];
int readLength, readAddress;
int dCBWSignature = 0, bCBWDataTransferLength = 0;
int bmCBWFlags = 0, bCBWLUN = 0, bCBWCBLength = 0;
int Operation_Code = 0;
XUD_Result_t result;
int ready = 1;
debug_printf("USB Mass Storage class demo started\n");
/* Load some default CSW to reduce response time delay */
memset(commandStatus,0,CSW_SHORT_PACKET_SIZE);
/* Signature helps identify this data packet as a CSW */
(commandStatus, int[])[0] = byterev(CSW_SIGNATURE);
/* Initialise the XUD endpoints */
XUD_ep ep1_out = XUD_InitEp(chan_ep1_out);
XUD_ep ep1_in = XUD_InitEp(chan_ep1_in);
#if !DETECT_AS_FLOPPY
massStorageInit();
#endif
while(1)
{
unsigned char bCSWStatus = CSW_STATUS_CMD_PASSED;
// Get Command Block Wrapper (CBW)
if(XUD_RES_OKAY == (result = XUD_GetBuffer(ep1_out, (commandBlock, char[CBW_SHORT_PACKET_SIZE]), host_transfer_length)) )
{
/* The CBW shall start on a packet boundary and shall end as a short packet
* with exactly 31 (0x1F) bytes transferred
*/
assert(host_transfer_length == CBW_SHORT_PACKET_SIZE);
/* verify Signature - that helps identify this packet as a CBW */
dCBWSignature = commandBlock[0] | commandBlock[1] << 8 |
commandBlock[2] << 16 | commandBlock[3] << 24;
assert(dCBWSignature == CBW_SIGNATURE);
bCBWDataTransferLength = commandBlock[8] | commandBlock[9]<<8 |
commandBlock[10] << 16 | commandBlock[11] << 24;
bmCBWFlags = commandBlock[12]; bCBWLUN = (commandBlock[13] & 0x0F);
assert(bCBWCBLength = (commandBlock[14] & 0x1F) <= 16);
Operation_Code = commandBlock[15];
switch(Operation_Code)
{
case TEST_UNIT_READY_CMD: // Test unit ready:
bCSWStatus = ready ? CSW_STATUS_CMD_PASSED : CSW_STATUS_CMD_FAILED;
break;
case REQUEST_SENSE_CMD: // Request sense
requestSenseAnswer[2] = ready ? STATUS_GOOD : STATUS_CHECK_CONDITION;
result = XUD_SetBuffer(ep1_in, requestSenseAnswer, sizeof(requestSenseAnswer));
break;
case INQUIRY_CMD: // Inquiry
result = XUD_SetBuffer(ep1_in, inquiryAnswer, sizeof(inquiryAnswer));
break;
case START_STOP_CMD: // start/stop
ready = ((commandBlock[19] >> 1) & 1) == 0;
break;
case MODE_SENSE_6_CMD: // Mode sense (6)
case MODE_SENSE_10_CMD: // Mode sense (10) // For Mac OSX
if (writeProtect) modeSenseAnswer[2] |= 0x80;
result = XUD_SetBuffer(ep1_in, modeSenseAnswer, sizeof(modeSenseAnswer));
break;
case MEDIUM_REMOVAL_CMD: // Medium removal
break;
case RECEIVE_DIAGNOSTIC_RESULT_CMD:
memset(readCapacity,0x0000,sizeof(readCapacity));
result = XUD_SetBuffer(ep1_in, (readCapacity, unsigned char[8]), 32);
break;
case READ_FORMAT_CAPACITY_CMD: // Read Format capacity (UFI Command Spec)
readCapacity[0] = byterev(8);
readCapacity[1] = byterev(massStorageSize());
readCapacity[2] = byterev(MASS_STORAGE_BLOCKLENGTH) | (DETECT_AS_FLOPPY ? NO_CARTRIDGE_IN_DRIVE : FORMATTED_MEDIA);
result = XUD_SetBuffer(ep1_in, (readCapacity, unsigned char[8]), 12);
break;
case READ_CAPACITY_CMD: // Read capacity
readCapacity[0] = byterev(massStorageSize()-1);
readCapacity[1] = byterev(MASS_STORAGE_BLOCKLENGTH);
result = XUD_SetBuffer(ep1_in, (readCapacity, unsigned char[8]), 8);
break;
case READ_CAPACITY_16_CMD:
memset(readCapacity,0x0000,sizeof(readCapacity));
readCapacity[1] = byterev(massStorageSize()-1);
readCapacity[2] = byterev(MASS_STORAGE_BLOCKLENGTH);
result = XUD_SetBuffer(ep1_in, (readCapacity, unsigned char[8]), 32);
break;
case READ_10_CMD: // Read (10)
readLength = commandBlock[22] << 8 | commandBlock[23];
readAddress = commandBlock[17] << 24 | commandBlock[18] << 16 |
commandBlock[19] << 8 | commandBlock[20];
for(int i = 0; i < readLength ; i++) {
bCSWStatus |= massStorageRead(readAddress, blockBuffer);
result = XUD_SetBuffer(ep1_in, blockBuffer, MASS_STORAGE_BLOCKLENGTH);
readAddress++; }
break;
case WRITE_10_CMD: // Write
readLength = commandBlock[22] << 8 | commandBlock[23];
readAddress = commandBlock[17] << 24 | commandBlock[18] << 16 |
commandBlock[19] << 8 | commandBlock[20];
for(int i = 0; i < readLength ; i++) {
result = XUD_GetBuffer(ep1_out, (blockBuffer, char[128 * 4]),host_transfer_length);
bCSWStatus |= massStorageWrite(readAddress, blockBuffer);
readAddress++; }
break;
default:
debug_printf("Invalid Operation Code Received : 0x%x\n",Operation_Code);
bCSWStatus = CSW_STATUS_CMD_FAILED;
break;
}
}
/* Check for result, if it is found as XUD_RES_RST, then reset Endpoints */
if(result == XUD_RES_RST) {
XUD_ResetEndpoint(ep1_out,ep1_in);
break;
}
/* Setup Command Status Wrapper (CSW). The CSW shall start on a packet boundry
* and shall end as a short packet with exactly 13 (0x0D) bytes transferred */
/* The device shall echo the contents of dCBWTag back to the host in the dCSWTag */
commandStatus[4] = commandBlock[4];
commandStatus[5] = commandBlock[5];
commandStatus[6] = commandBlock[6];
commandStatus[7] = commandBlock[7];
commandStatus[12] = bCSWStatus;
if(XUD_RES_RST == XUD_SetBuffer(ep1_in, commandStatus, CSW_SHORT_PACKET_SIZE))
XUD_ResetEndpoint(ep1_out,ep1_in);
} //while(1)
} // END of massStorageClass
From this you can see the following.
Two buffers are declared, one to receive the Command transport CBW (Command Block Wrapper) data which is streamed into the application from the host and the other to send Status transport CSW (Command Status Wrapper) to the host.
This task operates inside a while (1) loop which waits for data to arrive and then processes it.
It checks for the CBW Signature and packet size that get received from the host.
Based on the Operation code available on the CBWCB (CBW Command Block) field, SCSI commands corresponding to flash drive are executed.
Operation code received may correspond to SCSI commands like Inquiry, Test Unit Ready, Request Sense, Read Capacity, Mode Sense, Read/Write, etc.
Once the execution (Command transport, Data-In or Data-Out) is completed, the device shall echo the contents of CBWTag field sent by the host back along with the CSWStatus and CSW Signature as Status transport.
This ensures that the Status send to host is associated with the Command received from host.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$SCSI Command Implementation£££doc/rst/an00125.html#scsi-command-implementation
Some of the SCSI command definitions and the reponse from the device are mentioned below.
INQUIRY: command requests that information regarding parameters of the Device be sent to the Host.
The response to this command provides standard INQUIRY data of (36 bytes) PDT, RMB (Removable Medium Bit), Vendor Identification, Product Identification and Product Revison Level, etc.
TEST UNIT READY: command provides a means to check if the Device is ready. This command is useful in that it allows a Host to poll a Device until it is ready without the need to allocate space for returned data.
The response to this command returns GOOD, if the device accepts an appropriate medium access command or CHECK CONDITION status with a sense key of NOT READY.
REQUEST SENSE: command requests the device to transfer sense data to the host whenever an error is reported. The sense data describes what caused the error condition.
The response to this command is a sense key, Additional Sense Code (ASC) or ASC Qualifier (ASCQ) depending on which error occured [2].
READ CAPACITY: command requests the device to transfer 8 bytes of parameter data describing the capacity of the installed medium of the device.
The response to this command returns Logical Block Address (LBA) and block length in bytes of the memory device.
MODE SENSE: command requests the device to transfer parameter data describing the medium type, block descriptor length, read/write error recovery mode.
The response to this command returns PDT type as medium type, error recovery mode, descriptor length.
READ/WRITE: command requests the device to read/write data onto the medium.
The response to READ transfers the most recent data value written in the addressed logical block of the medium to host.
The response to WRITE writes the data transferred by the host to the medium.
AN00125: USB Mass Storage Device Class$$$USB Mass Storage Device Class application note$$$Serial Flash Functions£££doc/rst/an00125.html#serial-flash-functions
For accessing the on-board serial flash, you need to add the flash library lflash in
CMakeLists as one of the APP_COMPILER_FLAGS and use flashlib.h to access the flash library
functions.`Note: No separate core is required to handle the SPI read/write`
The below implementation does write/read operation onto the on-board serial flash M25P16.
AN00125: USB Mass Storage Device Class$$$Demo Hardware Setup£££doc/rst/an00125.html#demo-hardware-setup
To run the demo, connect the XK-EVK-XU316 DEBUG and USB recepticals to separate USB
connectors on your development PC.
Note, the application makes use of xSCOPE (rather than JTAG) such that the print message that are
generated on the device as part of the demo do not interfere with the real-time behavior of the USB
device.
XMOS XK-EVK-XU316 Board
AN00125: USB Mass Storage Device Class$$$Building the application£££doc/rst/an00125.html#building-the-application
The application uses the xcommon-cmake
build system as bundled with the XTC tools.
To configure the build run the following from an XTC command prompt:
cdan00125cmake-G"Unix Makefiles"-Bbuild
If any dependencies are missing it is at this configure step that they will be downloaded by the
build system.
Finally, the application binary can be built using xmake:
xmake-Cbuild
This command will cause a binary (.xe file) to be generated in the bin directory,
Once you have built the application, you need to prepare the flash device
by creating a data partition:
The file image.bin is the initial raw image on the flash device. You
can simply pass it a file with 4 MByte worth of zeroes, or you can supply a
file system image.
AN00125: USB Mass Storage Device Class$$$Launching the demo device£££doc/rst/an00125.html#launching-the-demo-device
Once the demo example has been built the application can be executed on the XK-EVK-XU316 board.
Once built there will be a bin directory within the project which contains the binary for the xcore
device. The xcore binary has a XMOS standard .xe extension.
AN00125: USB Mass Storage Device Class$$$Launching the demo device$$$Launching from the command line£££doc/rst/an00125.html#launching-from-the-command-line
From the command line the xrun tool is used to download code to both the xCORE devices. Changing
into the bin directory of the project we can execute the code on the xCORE microcontroller as
follows:
xrun--xscopeapp_mass_storage.xe
Once this command has executed the mass storage USB device should have enumerated on your machine
AN00125: USB Mass Storage Device Class$$$Detecting the Mass Storage£££doc/rst/an00125.html#detecting-the-mass-storage
AN00125: USB Mass Storage Device Class$$$Detecting the Mass Storage$$$Windows Host£££doc/rst/an00125.html#windows-host
There no specific driver installation is required. Windows will automatically install a driver
for the mass storage class. You should be able to get the below message screen once enumeration
is complete.
Driver Software Installation Screen (On Windows 7)
You can also verify the device using Device Manager Menu
Click on Start Menu goto My Computer - Right click and navigate to Manage option.
On Computer Management screen double click Device Manager on left and navigate to Universal Serial Bus controllers option on right.
Double click on Universal Serial Bus controllers and you should be able to see USB Mass Storage Device
USB Mass Storage Device detection on Device Manager (On Windows 7)
The Mass Storage Device should be seen as a Removable Disk (Drive ID may vary depending upon the number of drives available on your machine).
USB Mass Storage Device detecting as Removable Disk(I:) (On Windows 7)
You could see the successful installation of driver after enumeration is done.
XMOS LTD Flash Disk - Device Driver software installated successfully
AN00125: USB Mass Storage Device Class$$$Detecting the Mass Storage$$$macOS Host£££doc/rst/an00125.html#macos-host
No specific driver installation is required. macOS will automatically detect and you
should be able to get the below message screen once enumeration is complete.
USB Mass Storage Device detection (On Mac)
AN00125: USB Mass Storage Device Class$$$References£££doc/rst/an00125.html#references
AN00125: USB Mass Storage Device Class$$$Full Source Code listing£££doc/rst/an00125.html#full-source-code-listing
AN00125: USB Mass Storage Device Class$$$Full Source Code listing$$$Source Code for main.xc£££doc/rst/an00125.html#source-code-for-main-xc
//Copyright2015-2022XMOSLIMITED.//ThisSoftwareissubjecttothetermsoftheXMOSPublicLicence:Version1.#include <xscope.h>#include "xud_device.h"#include "debug_print.h"#include "mass_storage.h"#include "print.h"/*USBEndpointDefines*/#define XUD_EP_COUNT_OUT 2 //Includes EP0 (1 out EP0 + Mass Storage data output EP)#define XUD_EP_COUNT_IN 2 //Includes EP0 (1 in EP0 + Mass Storage data input EP)XUD_EpTypeepTypeTableOut[XUD_EP_COUNT_OUT]={XUD_EPTYPE_CTL|XUD_STATUS_ENABLE,XUD_EPTYPE_BUL};XUD_EpTypeepTypeTableIn[XUD_EP_COUNT_IN]={XUD_EPTYPE_CTL|XUD_STATUS_ENABLE,XUD_EPTYPE_BUL};/*xSCOPESetupFunction*/#if (USE_XSCOPE == 1)voidxscope_user_init(void){xscope_register(0,0,"",0,"");xscope_config_io(XSCOPE_IO_BASIC);/*Enablefastprintingoverlinks*/}#endif/*PrototypeforEndpoint0functioninendpoint0.xc*/voidEndpoint0(chanendc_ep0_out,chanendc_ep0_in);/*Themainfunctionrunsthreecores:theXUDmanager,Endpoint0,andamassstorageendpoint.AnarrayofchannelsisusedforbothINandOUTendpoints*/intmain(){chanc_ep_out[XUD_EP_COUNT_OUT],c_ep_in[XUD_EP_COUNT_IN];par{onUSB_TILE:XUD_Main(c_ep_out,XUD_EP_COUNT_OUT,c_ep_in,XUD_EP_COUNT_IN,null,epTypeTableOut,epTypeTableIn,XUD_SPEED_HS,XUD_PWR_BUS);onUSB_TILE:Endpoint0(c_ep_out[0],c_ep_in[0]);onUSB_TILE:massStorageClass(c_ep_out[1],c_ep_in[1],0);}return0;}
AN00125: USB Mass Storage Device Class$$$Full Source Code listing$$$Source Code for endpoint0.xc£££doc/rst/an00125.html#source-code-for-endpoint0-xc
//Copyright2015-2021XMOSLIMITED.//ThisSoftwareissubjecttothetermsoftheXMOSPublicLicence:Version1./**@briefImplementsendpointzeroforanexampleMassStorageclassdevice.*/#include <xs1.h>#include <string.h>#include <xscope.h>#include "xud_device.h"#include "debug_print.h"#include "print.h"/*USBDeviceIDDefines*/#define BCD_DEVICE 0x0010#define VENDOR_ID 0x20B1#define PRODUCT_ID 0x10BA/*USBMassStorageInterfaceSubclassDefinition*/#define USB_MASS_STORAGE_SUBCLASS 0x06 /* SCSI transparent command set *//*USBMassStorageinterfaceprotocol*/#define USB_MASS_STORAGE_PROTOCOL 0x50 /* USB Mass Storage Class Bulk-Only (BBB) Transport *//*USBMassStorageRequestCode*/#define USB_MASS_STORAGE_RESET 0xFF /* Bulk-Only Mass Storage Reset */#define USB_MASS_STORAGE_GML 0xFE /* Get Max LUN (GML) *//*USBDeviceDescriptor*/staticunsignedchardevDesc[]={0x12,/*0bLength*/USB_DESCTYPE_DEVICE,/*1bdescriptorType*/0x00,/*2bcdUSBversion*/0x02,/*3bcdUSBversion*/0x00,/*4bDeviceClass-Specifiedbyinterface*/0x00,/*5bDeviceSubClass-Specifiedbyinterface*/0x00,/*6bDeviceProtocol-Specifiedbyinterface*/0x40,/*7bMaxPacketSizeforEP0-max=64*/(VENDOR_ID&0xFF),/*8idVendor*/(VENDOR_ID>>8),/*9idVendor*/(PRODUCT_ID&0xFF),/*10idProduct*/(PRODUCT_ID>>8),/*11idProduct*/(BCD_DEVICE&0xFF),/*12bcdDevice*/(BCD_DEVICE>>8),/*13bcdDevice*/0x01,/*14iManufacturer-indexofstring*/0x02,/*15iProduct-indexofstring*/0x03,/*16iSerialNumber-indexofstring*/0x01/*17bNumConfigurations*/};/*USBConfigurationDescriptor*/staticunsignedcharcfgDesc[]={0x09,/*0bLength*/USB_DESCTYPE_CONFIGURATION,/*1bDescriptortype=configuration*/0x20,0x00,/*2wTotalLengthofalldescriptors*/0x01,/*4bNumInterfaces*/0x01,/*5bConfigurationValue*/0x00,/*6iConfiguration-indexofstring*/0x80,/*7bmAttributes-Selfpowered*/0x50,/*8bMaxPower-160mA*//*USBBulk-OnlyDataInterfaceDescriptor*/0x09,/*0bLength*/USB_DESCTYPE_INTERFACE,/*1bDescriptorType*/0x00,/*2bInterfacecNumber*/0x00,/*3bAlternateSetting*/0x02,/*4:bNumEndpoints*/USB_CLASS_MASS_STORAGE,/*5:bInterfaceClass*/USB_MASS_STORAGE_SUBCLASS,/*6:bInterfaceSubClass*/USB_MASS_STORAGE_PROTOCOL,/*7:bInterfaceProtocol*/0x00,/*8iInterface*//*Bulk-InEndpointDescriptor*/0x07,/*0bLength*/USB_DESCTYPE_ENDPOINT,/*1bDescriptorType*/0x81,/*2bEndpointAddress-EP1,IN*/XUD_EPTYPE_BUL,/*3bmAttributes*/0x00,/*4wMaxPacketSize-Low*/0x02,/*5wMaxPacketSize-High*/0x00,/*6bInterval*//*Bulk-OutEndpointDescriptor*/0x07,/*0bLength*/USB_DESCTYPE_ENDPOINT,/*1bDescriptorType*/0x01,/*2bEndpointAddress-EP1,OUT*/XUD_EPTYPE_BUL,/*3bmAttributes*/0x00,/*4wMaxPacketSize-Low*/0x02,/*5wMaxPacketSize-High*/0x00,/*6bInterval*/};unsafe{/*Stringtable-unsafeasaccessedviasharedmemory*/staticchar*unsafestringDescriptors[]={"\x09\x04",//LanguageIDstring(USEnglish)"XMOS",//iManufacturer"xMASSstorage",//iProduct"XD070101ho4I4KwM",//iSerialNumber};}/*MassStorageClassRequests*/intMassStorageEndpoint0Requests(XUD_epep0_out,XUD_epep0_in,USB_SetupPacket_tsp){unsignedcharbuffer[1]={0};switch(sp.bRequest){caseUSB_MASS_STORAGE_RESET:XUD_ResetEpStateByAddr(1);returnXUD_RES_RST;//Thisrequestisusedtoresetthemassstoragedevicebreak;caseUSB_MASS_STORAGE_GML:returnXUD_DoGetRequest(ep0_out,ep0_in,buffer,1,sp.wLength);break;default:debug_printf("MassStorageEndpoint0Requests @ default : 0x%x\n",sp.bRequest);break;}returnXUD_RES_ERR;}/*Endpoint0Task*/voidEndpoint0(chanendchan_ep0_out,chanendchan_ep0_in){USB_SetupPacket_tsp;unsignedbmRequestType;XUD_BusSpeed_tusbBusSpeed;XUD_epep0_out=XUD_InitEp(chan_ep0_out);XUD_epep0_in=XUD_InitEp(chan_ep0_in);while(1){/*ReturnsXUD_RES_OKAYonsuccess*/XUD_Result_tresult=USB_GetSetupPacket(ep0_out,ep0_in,sp);if(result==XUD_RES_OKAY){/*SetresulttoERR,weexpectittogetsettoOKAYifarequestishandled*/result=XUD_RES_ERR;/*StickbmRequesttypebacktogetherforaneasierparse...*/bmRequestType=(sp.bmRequestType.Direction<<7)|(sp.bmRequestType.Type<<5)|(sp.bmRequestType.Recipient);if((bmRequestType==USB_BMREQ_H2D_STANDARD_DEV)&&(sp.bRequest==USB_CLEAR_FEATURE)){//Hosthassetdeviceaddress,valuecontainedinsp.wValue}/*Handlespecificrequestsfirst*/switch(bmRequestType){/*Direction:Device-to-hostandHost-to-device*Type:Class*Recipient:Interface*/caseUSB_BMREQ_H2D_CLASS_INT:caseUSB_BMREQ_D2H_CLASS_INT:/*Inspectformassstorageinterfacenum*/if(sp.wIndex==0){/*ReturnsXUD_RES_OKAYifhandled,*XUD_RES_ERRifnothandled,*XUD_RES_RSTforbusreset*/result=MassStorageEndpoint0Requests(ep0_out,ep0_in,sp);}break;}}/*Ifwehaven't handled the request above then do standard enumeration requests */if(result==XUD_RES_ERR){/*ReturnsXUD_RES_OKAYifhandledokay,*XUD_RES_ERRifrequestwasnothandled(i.e.STALLed),*XUD_RES_RSTifUSBReset*/result=USB_StandardRequests(ep0_out,ep0_in,devDesc,sizeof(devDesc),cfgDesc,sizeof(cfgDesc),null,0,null,0,stringDescriptors,sizeof(stringDescriptors)/sizeof(stringDescriptors[0]),sp,usbBusSpeed);}/*USBbusresetdetected,resetEPandgetnewbusspeed*/if(result==XUD_RES_RST){usbBusSpeed=XUD_ResetEndpoint(ep0_out,ep0_in);}}}
AN00125: USB Mass Storage Device Class$$$Full Source Code listing$$$Source Code for mass_storage.xc£££doc/rst/an00125.html#source-code-for-mass-storage-xc
// Copyright 2015-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#include <xs1.h>
#include <platform.h>
#include <xclib.h>
#include <string.h>
#include <xassert.h>
#include "xud_device.h"
#include "mass_storage.h"
#include "debug_print.h"
//Flash_Functions_start
#include "quadflash.h"
#include "quadflashlib.h"
on tile[0]: fl_QSPIPorts spiPort = {
PORT_SQI_CS,
PORT_SQI_SCLK,
PORT_SQI_SIO,
XS1_CLKBLK_1
};
int pagesPerBlock_g = 0;
int bytesPerPage_g = 0;
unsigned char pageBuffer_g[MASS_STORAGE_BLOCKLENGTH];
void massStorageInit() {
fl_connect(spiPort);
fl_setBootPartitionSize(FLASH_PARTITION_SIZE);
bytesPerPage_g = fl_getPageSize();
pagesPerBlock_g = (MASS_STORAGE_BLOCKLENGTH / bytesPerPage_g);
}
int massStorageWrite(unsigned int blockNr, unsigned char buffer[]) {
for(int i = 0; i < pagesPerBlock_g; i++) {
for(int j = 0; j < bytesPerPage_g; j++) {
pageBuffer_g[j] = buffer[i * bytesPerPage_g + j];
}
fl_writeDataPage(blockNr * pagesPerBlock_g + i, buffer);
}
return 0;
}
int massStorageRead(unsigned int blockNr, unsigned char buffer[]) {
for(int i = 0; i < pagesPerBlock_g; i++) {
fl_readDataPage(blockNr * pagesPerBlock_g + i, pageBuffer_g);
for(int j = 0; j < bytesPerPage_g; j++) {
buffer[i * bytesPerPage_g + j] = pageBuffer_g[j];
}
}
return 0;
}
int massStorageSize() {
#if DETECT_AS_FLOPPY
return FLOPPY_DISK_SIZE;
#else
int x = fl_getNumDataPages();
return x / pagesPerBlock_g;
#endif
}
//Flash_Functions_end
static unsigned char inquiryAnswer[36] = {
0x00, // Peripheral Device Type (PDT) - SBC Direct-access device
0x80, // Removable Medium Bit is Set
0x02, // Version
0x02, // Obsolete[7:6],NORMACA[5],HISUP[4],Response Data Format[3:0]
0x1f, // Additional Length
0x73, // SCCS[7],ACC[6],TPGS[5:4],3PC[3],Reserved[2:1],PROTECT[0]
0x6d, // BQUE[7],ENCSERV[6],VS[5],MULTIP[4],MCHNGR[3],Obsolete[2:1],ADDR16[0]
0x69, // Obsolete[7:6],WBUS116[5],SYNC[4],LINKED[3],Obsolete[2],CMDQUE[1],VS[0]
'X', 'M', 'O', 'S', 'L', 'T', 'D', 0, // Vendor Identification
'F', 'l', 'a', 's', 'h', ' ', 'D', 'i', 's', 'k', 0, ' ', ' ', ' ', ' ', ' ', // Product Identification
'0', '.', '1', '0' // Product Revision Level
};
static unsigned char modeSenseAnswer[4] = {
0x04, 0x00, 0x10, 0x00
};
//Reference: http://www.usb.org/developers/docs/devclass_docs/usb_msc_boot_1.0.pdf
static unsigned char requestSenseAnswer[18] = {
0x70, // Error Code
0x00, // Segment Number (Reserved)
0x02, // ILI, Sense Key
0x00, 0x00, 0x00, 0x00, // Information
0x0A, // Additional Sense Length (n-7), i.e. 17-7
0x00, 0x00, 0x00, 0x00, // Command Specific Information
0x3A, // Additional Sense Code
0x00, // Additional Sense Qualifier (optional)
0x00, 0x00, 0x00, 0x00 // Reserved
};
static unsigned char blockBuffer[MASS_STORAGE_BLOCKLENGTH];
/* This function receives the mass storage endpoint transfers from the host */
void massStorageClass(chanend chan_ep1_out,chanend chan_ep1_in, int writeProtect)
{
unsigned char commandBlock[CBW_SHORT_PACKET_SIZE];
unsigned char commandStatus[CSW_SHORT_PACKET_SIZE];
unsigned host_transfer_length = 0;
int readCapacity[8];
int readLength, readAddress;
int dCBWSignature = 0, bCBWDataTransferLength = 0;
int bmCBWFlags = 0, bCBWLUN = 0, bCBWCBLength = 0;
int Operation_Code = 0;
XUD_Result_t result;
int ready = 1;
debug_printf("USB Mass Storage class demo started\n");
/* Load some default CSW to reduce response time delay */
memset(commandStatus,0,CSW_SHORT_PACKET_SIZE);
/* Signature helps identify this data packet as a CSW */
(commandStatus, int[])[0] = byterev(CSW_SIGNATURE);
/* Initialise the XUD endpoints */
XUD_ep ep1_out = XUD_InitEp(chan_ep1_out);
XUD_ep ep1_in = XUD_InitEp(chan_ep1_in);
#if !DETECT_AS_FLOPPY
massStorageInit();
#endif
while(1)
{
unsigned char bCSWStatus = CSW_STATUS_CMD_PASSED;
// Get Command Block Wrapper (CBW)
if(XUD_RES_OKAY == (result = XUD_GetBuffer(ep1_out, (commandBlock, char[CBW_SHORT_PACKET_SIZE]), host_transfer_length)) )
{
/* The CBW shall start on a packet boundary and shall end as a short packet
* with exactly 31 (0x1F) bytes transferred
*/
assert(host_transfer_length == CBW_SHORT_PACKET_SIZE);
/* verify Signature - that helps identify this packet as a CBW */
dCBWSignature = commandBlock[0] | commandBlock[1] << 8 |
commandBlock[2] << 16 | commandBlock[3] << 24;
assert(dCBWSignature == CBW_SIGNATURE);
bCBWDataTransferLength = commandBlock[8] | commandBlock[9]<<8 |
commandBlock[10] << 16 | commandBlock[11] << 24;
bmCBWFlags = commandBlock[12]; bCBWLUN = (commandBlock[13] & 0x0F);
assert(bCBWCBLength = (commandBlock[14] & 0x1F) <= 16);
Operation_Code = commandBlock[15];
switch(Operation_Code)
{
case TEST_UNIT_READY_CMD: // Test unit ready:
bCSWStatus = ready ? CSW_STATUS_CMD_PASSED : CSW_STATUS_CMD_FAILED;
break;
case REQUEST_SENSE_CMD: // Request sense
requestSenseAnswer[2] = ready ? STATUS_GOOD : STATUS_CHECK_CONDITION;
result = XUD_SetBuffer(ep1_in, requestSenseAnswer, sizeof(requestSenseAnswer));
break;
case INQUIRY_CMD: // Inquiry
result = XUD_SetBuffer(ep1_in, inquiryAnswer, sizeof(inquiryAnswer));
break;
case START_STOP_CMD: // start/stop
ready = ((commandBlock[19] >> 1) & 1) == 0;
break;
case MODE_SENSE_6_CMD: // Mode sense (6)
case MODE_SENSE_10_CMD: // Mode sense (10) // For Mac OSX
if (writeProtect) modeSenseAnswer[2] |= 0x80;
result = XUD_SetBuffer(ep1_in, modeSenseAnswer, sizeof(modeSenseAnswer));
break;
case MEDIUM_REMOVAL_CMD: // Medium removal
break;
case RECEIVE_DIAGNOSTIC_RESULT_CMD:
memset(readCapacity,0x0000,sizeof(readCapacity));
result = XUD_SetBuffer(ep1_in, (readCapacity, unsigned char[8]), 32);
break;
case READ_FORMAT_CAPACITY_CMD: // Read Format capacity (UFI Command Spec)
readCapacity[0] = byterev(8);
readCapacity[1] = byterev(massStorageSize());
readCapacity[2] = byterev(MASS_STORAGE_BLOCKLENGTH) | (DETECT_AS_FLOPPY ? NO_CARTRIDGE_IN_DRIVE : FORMATTED_MEDIA);
result = XUD_SetBuffer(ep1_in, (readCapacity, unsigned char[8]), 12);
break;
case READ_CAPACITY_CMD: // Read capacity
readCapacity[0] = byterev(massStorageSize()-1);
readCapacity[1] = byterev(MASS_STORAGE_BLOCKLENGTH);
result = XUD_SetBuffer(ep1_in, (readCapacity, unsigned char[8]), 8);
break;
case READ_CAPACITY_16_CMD:
memset(readCapacity,0x0000,sizeof(readCapacity));
readCapacity[1] = byterev(massStorageSize()-1);
readCapacity[2] = byterev(MASS_STORAGE_BLOCKLENGTH);
result = XUD_SetBuffer(ep1_in, (readCapacity, unsigned char[8]), 32);
break;
case READ_10_CMD: // Read (10)
readLength = commandBlock[22] << 8 | commandBlock[23];
readAddress = commandBlock[17] << 24 | commandBlock[18] << 16 |
commandBlock[19] << 8 | commandBlock[20];
for(int i = 0; i < readLength ; i++) {
bCSWStatus |= massStorageRead(readAddress, blockBuffer);
result = XUD_SetBuffer(ep1_in, blockBuffer, MASS_STORAGE_BLOCKLENGTH);
readAddress++; }
break;
case WRITE_10_CMD: // Write
readLength = commandBlock[22] << 8 | commandBlock[23];
readAddress = commandBlock[17] << 24 | commandBlock[18] << 16 |
commandBlock[19] << 8 | commandBlock[20];
for(int i = 0; i < readLength ; i++) {
result = XUD_GetBuffer(ep1_out, (blockBuffer, char[128 * 4]),host_transfer_length);
bCSWStatus |= massStorageWrite(readAddress, blockBuffer);
readAddress++; }
break;
default:
debug_printf("Invalid Operation Code Received : 0x%x\n",Operation_Code);
bCSWStatus = CSW_STATUS_CMD_FAILED;
break;
}
}
/* Check for result, if it is found as XUD_RES_RST, then reset Endpoints */
if(result == XUD_RES_RST) {
XUD_ResetEndpoint(ep1_out,ep1_in);
break;
}
/* Setup Command Status Wrapper (CSW). The CSW shall start on a packet boundry
* and shall end as a short packet with exactly 13 (0x0D) bytes transferred */
/* The device shall echo the contents of dCBWTag back to the host in the dCSWTag */
commandStatus[4] = commandBlock[4];
commandStatus[5] = commandBlock[5];
commandStatus[6] = commandBlock[6];
commandStatus[7] = commandBlock[7];
commandStatus[12] = bCSWStatus;
if(XUD_RES_RST == XUD_SetBuffer(ep1_in, commandStatus, CSW_SHORT_PACKET_SIZE))
XUD_ResetEndpoint(ep1_out,ep1_in);
} //while(1)
} // END of massStorageClass