Unit Storage

Return to Unit Reference

Description

---

Ultibo Storage interface unit

This unit provides both the Storage device interface and the generic USB mass storage driver.

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]

Storage specific constants STORAGE_*

STORAGE_NAME_PREFIX = 'Storage';	Name prefix for Storage Devices
STORAGE_STATUS_TIMER_INTERVAL = 1000;

[Expand]

Storage device type constants STORAGE_TYPE_*

STORAGE_TYPE_NONE = 0;
STORAGE_TYPE_HDD = 1;
STORAGE_TYPE_FDD = 2;
STORAGE_TYPE_CDROM = 3;
STORAGE_TYPE_OPTICAL = 4;
STORAGE_TYPE_TAPE = 5;
STORAGE_TYPE_REMOVABLE = 6;
STORAGE_TYPE_MAX = 6;

[Expand]

Storage device state constants STORAGE_STATE_*

STORAGE_STATE_EJECTED = 0;
STORAGE_STATE_EJECTING = 1;
STORAGE_STATE_INSERTING = 2;
STORAGE_STATE_INSERTED = 3;
STORAGE_STATE_MAX = 3;

[Expand]

Storage device flag constants STORAGE_FLAG_*

STORAGE_FLAG_NONE = $00000000;
STORAGE_FLAG_REMOVABLE = $00000001;
STORAGE_FLAG_LBA48 = $00000002;
STORAGE_FLAG_NOT_READY = $00000004;
STORAGE_FLAG_NO_MEDIA = $00000008;
STORAGE_FLAG_READ_ONLY = $00000010;
STORAGE_FLAG_WRITE_ONLY = $00000020;
STORAGE_FLAG_ERASEABLE = $00000040;
STORAGE_FLAG_LOCKABLE = $00000080;
STORAGE_FLAG_LOCKED = $00000100;
STORAGE_FLAG_EJECTABLE = $00000200;
STORAGE_FLAG_CHANGABLE = $00000400;

[Expand]

Storage device control code constants STORAGE_CONTROL_*

STORAGE_CONTROL_TEST_READY = 1;	Test Unit Ready
STORAGE_CONTROL_RESET = 2;	Reset Device
STORAGE_CONTROL_TEST_MEDIA = 3;	Test No Media
STORAGE_CONTROL_LOCK = 4;	Lock Media
STORAGE_CONTROL_UNLOCK = 5;	Unlock Media
STORAGE_CONTROL_EJECT = 6;	Eject Media
STORAGE_CONTROL_TEST_LOCKED = 7;	Test Media Locked
STORAGE_CONTROL_TEST_CHANGED = 8;	Test Media Changed
STORAGE_CONTROL_GET_VENDORID = 9;	Get Vendor ID
STORAGE_CONTROL_GET_PRODUCTID = 10;	Get Product ID
STORAGE_CONTROL_GET_SERIAL = 11;	Get Serial No
STORAGE_CONTROL_GET_REVISION = 12;	Get Revision No
STORAGE_CONTROL_GET_PRODUCT = 13;	Get Product Name
STORAGE_CONTROL_GET_MANUFACTURER = 14;	Get Manufacturer Name

[Expand]

Storage logging constants STORAGE_LOG_*

STORAGE_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;	Storage debugging messages
STORAGE_LOG_LEVEL_INFO = LOG_LEVEL_INFO;	Storage informational messages, such as a device being attached or detached
STORAGE_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;	Storage error messages
STORAGE_LOG_LEVEL_NONE = LOG_LEVEL_NONE;	No Storage messages

[Expand]

USB storage specific constants USB_STORAGE_*

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

---

To be documented

Public variables

---

To be documented

Function declarations

---

Initialization functions

[Expand]

procedure StorageInit;

Description: To be documented

Note	None documented

Storage functions

[Expand]

function StorageDeviceRead(Storage:PStorageDevice; const Start,Count:Int64; Buffer:Pointer):LongWord;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceWrite(Storage:PStorageDevice; const Start,Count:Int64; Buffer:Pointer):LongWord;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceErase(Storage:PStorageDevice; const Start,Count:Int64):LongWord;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceControl(Storage:PStorageDevice; Request:Integer; Argument1:LongWord; var Argument2:LongWord):LongWord;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceSetState(Storage:PStorageDevice; State:LongWord):LongWord;

Description: Set the state of the specified storage and send a notification

Storage	The storage to set the state for
State	The new state to set and notify
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function StorageDeviceStartStatus(Storage:PStorageDevice; Interval:LongWord):LongWord;

Description: Start status monitoring on the specified storage for insert/eject notifications

Storage	The storage to start status monitoring for
Interval	The status monitoring interval in milliseconds
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function StorageDeviceStopStatus(Storage:PStorageDevice):LongWord;

Description: Stop status monitoring on the specified storage for insert/eject notifications

Storage	The storage to stop status monitoring for
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function StorageDeviceCreate:PStorageDevice;

Description: Create a new Storage entry

Return	Pointer to new Storage entry or nil if storage could not be created

[Expand]

function StorageDeviceCreateEx(Size:LongWord):PStorageDevice;

Description: Create a new Storage entry

Size	Size in bytes to allocate for new storage (Including the storage entry)
Return	Pointer to new Storage entry or nil if storage could not be created

[Expand]

function StorageDeviceDestroy(Storage:PStorageDevice):LongWord;

Description: Destroy an existing Storage entry

Note	None documented

[Expand]

function StorageDeviceRegister(Storage:PStorageDevice):LongWord;

Description: Register a new Storage in the Storage table

Note	None documented

[Expand]

function StorageDeviceDeregister(Storage:PStorageDevice):LongWord;

Description: Deregister a Storage from the Storage table

Note	None documented

[Expand]

function StorageDeviceFind(StorageId:LongWord):PStorageDevice;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceFindByName(const Name:String):PStorageDevice; inline;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceFindByDescription(const Description:String):PStorageDevice; inline;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceEnumerate(Callback:TStorageEnumerate; Data:Pointer):LongWord;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceNotification(Storage:PStorageDevice; Callback:TStorageNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;

Description: To be documented

Note	None 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:LongWord; var Argument2:LongWord):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

Storage helper functions

[Expand]

function StorageGetCount:LongWord; inline;

Description: Get the current storage count

Note	None documented

[Expand]

function StorageDeviceCheck(Storage:PStorageDevice):PStorageDevice;

Description: Check if the supplied Storage is in the storage table

Note	None documented

[Expand]

function StorageDeviceTypeToString(StorageType:LongWord):String;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceStateToString(StorageState:LongWord):String;

Description: To be documented

Note	None documented

[Expand]

function StorageDeviceStateToNotification(State:LongWord):LongWord;

Description: Convert a Storage state value into the notification code for device notifications

Note	None documented

[Expand]

procedure StorageLog(Level:LongWord; Storage:PStorageDevice; const AText:String);

Description: To be documented

Note	None documented

[Expand]

procedure StorageLogInfo(Storage:PStorageDevice; const AText:String);

Description: To be documented

Note	None documented

[Expand]

procedure StorageLogError(Storage:PStorageDevice; const AText:String);

Description: To be documented

Note	None documented

[Expand]

procedure StorageLogDebug(Storage:PStorageDevice; const AText:String);

Description: To be documented

Note	None documented

[Expand]

procedure StorageStatusTimer(Storage:PStorageDevice);

Description: To be documented

Note	None documented

USB storage helper functions

[Expand]

function USBStorageCheckSubclass(Subclass:Byte):Boolean;

Description: To be documented

Note	None documented

[Expand]

function USBStorageCheckProtocol(Protocol:Byte):Boolean;

Description: To be documented

Note	None documented

[Expand]

function USBStorageBlockSizeToBlockShift(BlockSize:LongWord):LongWord;

Description: To be documented

Note	None 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

Note	None documented

[Expand]

function USBStorageFixupDevice(Device:PUSBDevice; var Vendor,Product:String):LongWord;

Description: A function to adjust the vendor and product parameters of known defective devices

Note	None documented

[Expand]

function USBStorageDeviceLock(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;

Description: Issue a Prevent Media Removal request to a storage device

Note	None documented

[Expand]

function USBStorageDeviceUnlock(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;

Description: Issue a Allow Media Removal request to a storage device

Note	None documented

[Expand]

function USBStorageDeviceLoad(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;

Description: Issue a Start Stop request to a storage device

Note	None documented

[Expand]

function USBStorageDeviceEject(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;

Description: Issue a Start Stop request to a storage device

Note	None documented

[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)

Note	None documented

[Expand]

function USBStorageDeviceGetStatus(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;

Description: To be documented

Note	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

Note	None documented

[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

Note	None documented

[Expand]

function USBStorageDeviceInquiry(Device:PUSBDevice; Storage:PUSBStorageDevice; var DeviceType,DeviceFlags:LongWord;v ar 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