Return to Unit Reference
Description
Ultibo USB Mass Storage Driver unit
USB Mass Storage Devices
The USB Mass Storage Class Control/Bulk/Interrupt (CBI) Transport specification is approved for use only with full-speed floppy disk drives. CBI shall not be used in high-speed capable devices, or in devices other than floppy disk drives. CBI shall not be used in devices that implement LSDFS. Usage of CBI for any new design is discouraged.
Therefore the majority of USB Mass Storage devices use the Bulk only interface.
USB mass storage class devices normally use the SCSI command set and therefore the USB storage driver consumes the SCSI unit for the protocol and command definitions. USB mass storage devices are registered directly as Storage devices not as SCSI devices.
Constants
[Expand]
USB storage USB_STORAGE_*
USBSTORAGE_STORAGE_DESCRIPTION = 'USB Storage Device';
|
|
|
USBSTORAGE_DRIVER_NAME = 'USB Mass Storage Driver';
|
Name of USB storage driver
|
|
CB/CBI (Control/Bulk/Interrupt) Requests
|
USB_STORAGE_REQUEST_CBI_ADSC = 0;
|
|
|
BBB (Bulk Only) Requests
|
USB_STORAGE_REQUEST_BBB_RESET = $FF;
|
|
USB_STORAGE_REQUEST_BBB_GET_MAX_LUN = $FE;
|
|
|
Command Block Wrapper
|
USB_STORAGE_CBW_SIGNATUR = $43425355;
|
|
|
USB_STORAGE_CBW_FLAGS_OUT = $00;
|
|
USB_STORAGE_CBW_FLAGS_IN = $80;
|
|
|
USB_STORAGE_CBW_CB_LENGTH = 16;
|
|
|
USB_STORAGE_CBW_SIZE = 31;
|
|
|
Command Status Wrapper
|
USB_STORAGE_CSW_SIGNATURE = $53425355;
|
|
|
USB_STORAGE_CSW_STATUS_GOOD = $00;
|
|
USB_STORAGE_CSW_STATUS_FAILED = $01;
|
|
USB_STORAGE_CSW_STATUS_PHASE = $02;
|
|
|
USB_STORAGE_CSW_SIZE = 13;
|
|
|
Command Data
|
USB_STORAGE_COMMAND_MAX_SIZE = 16;
|
|
|
Command Retry Counts
|
USB_STORAGE_READ_RETRIES = 2;
|
|
USB_STORAGE_WRITE_RETRIES = 2;
|
|
USB_STORAGE_STATUS_RETRIES = 2;
|
|
USB_STORAGE_INQUIRY_RETRIES = 5;
|
|
USB_STORAGE_READ_CAPACITY_RETRIES = 3;
|
|
USB_STORAGE_TEST_UNIT_READY_RETRIES = 5;
|
10; TestingRPi
|
|
Peripheral Device Types
|
These are a subset of the SCSI Peripheral Device Types
|
USB_STORAGE_DEVICE_TYPE_DISK = $00;
|
SBC Direct-access device (e.g., UHD Floppy disk)
|
USB_STORAGE_DEVICE_TYPE_CDROM = $05;
|
MMC-5 CD-ROM device
|
USB_STORAGE_DEVICE_TYPE_OPTICAL = $07;
|
Optical memory device (e.g., Non-CD optical disks)
|
USB_STORAGE_DEVICE_TYPE_RBC = $0E;
|
RBC Direct-access device (e.g., UHD Floppy disk)
|
USB_STORAGE_DEVICE_TYPE_UNKNOWN = $1F;
|
Unknown or no device type
|
Type definitions
USB command block
[Expand]
PUSBCommandBlock = ^TUSBCommandBlock;
TUSBCommandBlock = record
Note: SBC Command Block (Derived from TSCSICommandBlock)
|
SCSI Properties
|
Command:array[0..USB_STORAGE_COMMAND_MAX_SIZE - 1] of Byte;
|
Command
|
SenseData:array[0..63] of Byte;
|
Request Sense
|
Status:Byte;
|
SCSI Status
|
TargetID:Byte;
|
Target Id
|
TargetLUN:Byte;
|
Target LUN
|
CommandLength:Byte;
|
Command Length
|
DataLength:LongWord;
|
Data Length
|
Data:Pointer;
|
Pointer to Data
|
MessageOut:array[0..11] of Byte;
|
Message out buffer
|
MessageIn:array[0..11] of Byte;
|
Message in buffer
|
SenseCommandLength:Byte;
|
Sense Command Length
|
SenseDataLength:LongWord;
|
Sense Data Length
|
SenseCommand:array[0..5] of Byte;
|
Sense Command
|
ControllerStatus:LongWord;
|
Controller Status
|
TransferredBytes:LongWord;
|
Transferred Bytes
|
USB Properties
|
Direction:Byte;
|
USB Direction (eg USB_DIRECTION_OUT or USB_DIRECTION_IN)
|
USB storage device
[Expand]
PUSBStorageDevice = ^TUSBStorageDevice;
TUSBStorageDevice = record
Storage Properties
|
Storage:TStorageDevice;
|
|
USB Properties
|
Subclass:Byte;
|
|
Protocol:Byte;
|
|
MaxLUN:Byte;
|
|
Sequence:LongWord;
|
For dCBWTag property
|
Primary:PUSBStorageDevice;
|
Primary storage device (for multi LUN devices)
|
StorageInterface:PUSBInterface;
|
USB Mass Storage device Interface
|
ReadWait:TSemaphoreHandle;
|
Read completed semaphore
|
WriteWait:TSemaphoreHandle;
|
Write completed semaphore
|
InterruptWait:TSemaphoreHandle;
|
Interrupt completed semaphore
|
ReadRequest:PUSBRequest;
|
Bulk IN Request
|
WriteRequest:PUSBRequest;
|
Bulk OUT Request
|
InterruptRequest:PUSBRequest;
|
Interrupt IN Request
|
ReadEndpoint:PUSBEndpointDescriptor;
|
Bulk IN Endpoint
|
WriteEndpoint:PUSBEndpointDescriptor;
|
Bulk OUT Endpoint
|
InterruptEndpoint:PUSBEndpointDescriptor;
|
Interrupt IN Endpoint
|
PendingCount:LongWord;
|
Number of USB requests pending for this storage
|
WaiterThread:TThreadId;
|
Thread waiting for pending requests to complete (for storage eject)
|
SCSI Properties
|
CommandBlock:TUSBCommandBlock;
|
|
ATAPI Properties
|
|
|
RBC Properties
|
|
|
USB command block wrapper
[Expand]
PUSBCommandBlockWrapper = ^TUSBCommandBlockWrapper;
TUSBCommandBlockWrapper = record
dCBWSignature:LongWord;
|
|
dCBWTag:LongWord;
|
|
dCBWDataTransferLength:LongWord;
|
|
bCBWFlags:Byte;
|
|
bCBWLUN:Byte;
|
|
bCBWCBLength:Byte;
|
|
CBWCB:array[0..USB_STORAGE_CBW_CB_LENGTH - 1] of Byte;
|
|
USB command status wrapper
[Expand]
PUSBCommandStatusWrapper = ^TUSBCommandStatusWrapper;
TUSBCommandStatusWrapper = record
dCSWSignature:LongWord;
|
|
dCSWTag:LongWord;
|
|
dCSWDataResidue:LongWord;
|
|
bCSWStatus:Byte;
|
|
Function declarations
Initialization functions
[Expand]
procedure USBStorageInit;
Description: To be documented
USB storage functions
[Expand]
function USBStorageDeviceRead(Storage:PStorageDevice; const Start,Count:Int64; Buffer:Pointer):LongWord;
Description: To be documented
Note
|
According to 3.4 of USB Mass Storage Bulk Only 1.0, requests must be queued one at a time to a device.
|
[Expand]
function USBStorageDeviceWrite(Storage:PStorageDevice; const Start,Count:Int64; Buffer:Pointer):LongWord;
Description: To be documented
Note
|
According to 3.4 of USB Mass Storage Bulk Only 1.0, requests must be queued one at a time to a device.
|
[Expand]
function USBStorageDeviceControl(Storage:PStorageDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;
Description: To be documented
Note
|
According to 3.4 of USB Mass Storage Bulk Only 1.0, requests must be queued one at a time to a device.
|
[Expand]
function USBStorageDriverBind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Bind the Storage driver to a USB device if it is suitable
Device
|
The USB device to attempt to bind to
|
Interrface
|
The USB interface to attempt to bind to (or nil for whole device)
|
Return
|
USB_STATUS_SUCCESS if completed, USB_STATUS_DEVICE_UNSUPPORTED if unsupported or another error code on failure.
|
[Expand]
function USBStorageDriverUnbind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Unbind the Storage driver from a USB device
Device
|
The USB device to unbind from
|
Interrface
|
The USB interface to unbind from (or nil for whole device)
|
Return
|
USB_STATUS_SUCCESS if completed or another error code on failure
|
[Expand]
procedure USBStorageReadComplete(Request:PUSBRequest);
Description: Called when a USB request from a USB storage bulk IN endpoint completes
Request
|
The USB request which has completed
|
Note
|
The thread that submitted the read request will hold the storage lock
|
[Expand]
procedure USBStorageWriteComplete(Request:PUSBRequest);
Description: Called when a USB request from a USB storage bulk OUT endpoint completes
Request
|
The USB request which has completed
|
Note
|
The thread that submitted the write request will hold the storage lock
|
[Expand]
procedure USBStorageInterruptComplete(Request:PUSBRequest);
Description: Called when a USB request from a USB storage IN interrupt endpoint completes
Request
|
The USB request which has completed
|
Note
|
The thread that submitted the interrupt request will hold the storage lock
|
USB storage helper functions
[Expand]
function USBStorageCheckDevice(Device:PUSBDevice):Boolean;
Description: Check if the supplied USB device is suitable for detection as a Mass Storage Device
Device
|
The USB device to check
|
Return
|
True if the device is suitable or False if it is not
|
[Expand]
function USBStorageCheckSubclass(Subclass:Byte):Boolean;
Description: To be documented
[Expand]
function USBStorageCheckProtocol(Protocol:Byte):Boolean;
Description: To be documented
[Expand]
function USBStorageBlockSizeToBlockShift(BlockSize:LongWord):LongWord;
Description: To be documented
[Expand]
function USBStoragePatchDevice(Device:PUSBDevice; var Subclass,Protocol:Byte):LongWord;
Description: A function to adjust the subclass and protocol parameters of known defective devices
[Expand]
function USBStorageFixupDevice(Device:PUSBDevice; var Vendor,Product:String):LongWord;
Description: A function to adjust the vendor and product parameters of known defective devices
[Expand]
function USBStorageDeviceLock(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Issue a Prevent Media Removal request to a storage device
[Expand]
function USBStorageDeviceUnlock(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Issue a Allow Media Removal request to a storage device
[Expand]
function USBStorageDeviceLoad(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Issue a Start Stop request to a storage device
[Expand]
function USBStorageDeviceEject(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Issue a Start Stop request to a storage device
USB storage helper functions
[Expand]
function USBStorageDeviceReset(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Issue a Storage Reset request to a storage device
Note
|
Reset recovery (5.3.4 in USB Mass Storage Bulk Only 1.0)
For Reset Recovery the host shall issue in the following order: a) a Bulk-Only Mass Storage Reset, b) a Clear Feature HALT to the Bulk-In endpoint, c) a Clear Feature HALT to the Bulk-Out endpoint. This is done in 3 steps. If the reset doesn't succeed, the device should be port reset.
|
[Expand]
function USBStorageDeviceGetInfo(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Obtain basic information about a storage device (Type, Size, State, Product etc)
[Expand]
function USBStorageDeviceGetStatus(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Supported by Subclass SCSI/UFI/SFF8070
[Expand]
function USBStorageDeviceGetMaxLUN(Device:PUSBDevice; Storage:PUSBStorageDevice; var MaxLUN:Byte):LongWord;
Description: Issue a Get Max LUN request to a storage device
[Expand]
function USBStorageDeviceClearStall(Device:PUSBDevice; Storage:PUSBStorageDevice; Endpoint:PUSBEndpointDescriptor):LongWord;
Description: Issue a USB Clear Feature (HALT) to the supplied endpoint on a storage device
[Expand]
function USBStorageDeviceInquiry(Device:PUSBDevice; Storage:PUSBStorageDevice; var DeviceType,DeviceFlags:LongWord; var Vendor,Product,Revision:PChar):LongWord;
Description: Issue a SCSI Inquiry command to a LUN on a storage device
Note
|
Supported by Subclass SCSI/UFI/SFF8070
|
[Expand]
function USBStorageDeviceRequestSense(Device:PUSBDevice; Storage:PUSBStorageDevice; var SenseKey,ASC,ASCQ:Byte):LongWord;
Description: Issue a SCSI Request Sense command to a LUN on a storage device
Note
|
Supported by Subclass SCSI/UFI/SFF8070
|
[Expand]
function USBStorageDeviceReadCapacity(Device:PUSBDevice; Storage:PUSBStorageDevice; var BlockSize,BlockShift:LongWord; var BlockCount:Int64):LongWord;
Description: Issue a SCSI Read Capacity command to a LUN on a storage device
Note
|
Supported by Subclass SCSI/UFI/SFF8070
|
[Expand]
function USBStorageDeviceTestUnitReady(Device:PUSBDevice; Storage:PUSBStorageDevice; var DeviceFlags:LongWord):LongWord;
Description: Issue a SCSI Test Unit Ready command to a LUN on a storage device
Note
|
Supported by Subclass SCSI/UFI/SFF8070
|
[Expand]
function USBStorageDeviceRead10(Device:PUSBDevice; Storage:PUSBStorageDevice; Start:LongWord; Count:Word;Buffer:Pointer):LongWord;
Description: Issue a SCSI Read10 command to a LUN on a storage device
Note
|
Supported by Subclass SCSI/UFI/SFF8070
Caller must hold the storage lock
|
[Expand]
function USBStorageDeviceWrite10(Device:PUSBDevice; Storage:PUSBStorageDevice; Start:LongWord;Count:Word; Buffer:Pointer):LongWord;
Description: Issue a SCSI Write10 command to a LUN on a storage device
Note
|
Supported by Subclass SCSI/UFI/SFF8070
Caller must hold the storage lock
|
[Expand]
function USBStorageDeviceRead16(Device:PUSBDevice; Storage:PUSBStorageDevice; const Start,Count:Int64; Buffer:Pointer):LongWord;
Description: Issue a SCSI Read16 command to a LUN on a storage device
Note
|
Supported by Subclass SCSI only (Only on devices > 2TB)
Caller must hold the storage lock
|
[Expand]
function USBStorageDeviceWrite16(Device:PUSBDevice; Storage:PUSBStorageDevice; const Start,Count:Int64; Buffer:Pointer):LongWord;
Description: Issue a SCSI Write16 command to a LUN on a storage device
Note
|
Supported by Subclass SCSI only (Only on devices > 2TB)
Caller must hold the storage lock
|
[Expand]
function USBStorageDeviceTransport(Device:PUSBDevice; Storage:PUSBStorageDevice; Command:PUSBCommandBlock):LongWord;
Description: Perform the appropriate transport sequence for the device based on subclass and protocol
Note
|
Handles Command / Data / Status phases plus endpoint stall, reset and retry as per the specification. Supported by Subclass SCSI/UFI/SFF8070
Caller must hold the storage lock
|
Return to Unit Reference