Difference between revisions of "Unit Storage"
From Ultibo.org
| Line 345: | Line 345: | ||
---- | ---- | ||
| − | '' | + | |
| + | '''Storage logging''' | ||
| + | |||
| + | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
| + | |- | ||
| + | | <code>STORAGE_DEFAULT_LOG_LEVEL:LongWord = STORAGE_LOG_LEVEL_DEBUG;</code> | ||
| + | | style="width: 65%;"|Minimum level for Storage messages. Only messages with level greater than or equal to this will be printed. | ||
| + | |- | ||
| + | |} | ||
| + | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
| + | |- | ||
| + | | <code>STORAGE_LOG_ENABLED:Boolean;</code> | ||
| + | | style="width: 65%;"| | ||
| + | |- | ||
| + | |} | ||
| + | <br /> | ||
=== Function declarations === | === Function declarations === | ||
Revision as of 02:27, 5 January 2017
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
Storage specific constants
STORAGE_* STORAGE_NAME_PREFIX = 'Storage';
|
Name prefix for Storage Devices |
STORAGE_STATUS_TIMER_INTERVAL = 1000;
|
|
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;
|
|
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;
|
|
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;
|
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 |
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 |
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
Storage logging
STORAGE_DEFAULT_LOG_LEVEL:LongWord = STORAGE_LOG_LEVEL_DEBUG;
|
Minimum level for Storage messages. Only messages with level greater than or equal to this will be printed. |
STORAGE_LOG_ENABLED:Boolean;
|
Function declarations
Initialization functions
procedure StorageInit;
Description: To be documented
| Note | None documented |
|---|
Storage functions
function StorageDeviceRead(Storage:PStorageDevice; const Start,Count:Int64; Buffer:Pointer):LongWord;
Description: To be documented
| Note | None documented |
|---|
function StorageDeviceWrite(Storage:PStorageDevice; const Start,Count:Int64; Buffer:Pointer):LongWord;
Description: To be documented
| Note | None documented |
|---|
function StorageDeviceErase(Storage:PStorageDevice; const Start,Count:Int64):LongWord;
Description: To be documented
| Note | None documented |
|---|
function StorageDeviceControl(Storage:PStorageDevice; Request:Integer; Argument1:LongWord; var Argument2:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
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 |
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 |
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 |
function StorageDeviceCreate:PStorageDevice;
Description: Create a new Storage entry
| Return | Pointer to new Storage entry or nil if storage could not be created |
|---|
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 |
function StorageDeviceDestroy(Storage:PStorageDevice):LongWord;
Description: Destroy an existing Storage entry
| Note | None documented |
|---|
function StorageDeviceRegister(Storage:PStorageDevice):LongWord;
Description: Register a new Storage in the Storage table
| Note | None documented |
|---|
function StorageDeviceDeregister(Storage:PStorageDevice):LongWord;
Description: Deregister a Storage from the Storage table
| Note | None documented |
|---|
function StorageDeviceFind(StorageId:LongWord):PStorageDevice;
Description: To be documented
| Note | None documented |
|---|
function StorageDeviceFindByName(const Name:String):PStorageDevice; inline;
Description: To be documented
| Note | None documented |
|---|
function StorageDeviceFindByDescription(const Description:String):PStorageDevice; inline;
Description: To be documented
| Note | None documented |
|---|
function StorageDeviceEnumerate(Callback:TStorageEnumerate; Data:Pointer):LongWord;
Description: To be documented
| Note | None documented |
|---|
function StorageDeviceNotification(Storage:PStorageDevice; Callback:TStorageNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
USB storage functions
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 |
|---|
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 |
|---|
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 |
|---|
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 |
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 |
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 |
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 |
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
function StorageGetCount:LongWord; inline;
Description: Get the current storage count
| Note | None documented |
|---|
function StorageDeviceCheck(Storage:PStorageDevice):PStorageDevice;
Description: Check if the supplied Storage is in the storage table
| Note | None documented |
|---|
function StorageDeviceTypeToString(StorageType:LongWord):String;
Description: To be documented
| Note | None documented |
|---|
function StorageDeviceStateToString(StorageState:LongWord):String;
Description: To be documented
| Note | None documented |
|---|
function StorageDeviceStateToNotification(State:LongWord):LongWord;
Description: Convert a Storage state value into the notification code for device notifications
| Note | None documented |
|---|
procedure StorageLog(Level:LongWord; Storage:PStorageDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure StorageLogInfo(Storage:PStorageDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure StorageLogError(Storage:PStorageDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure StorageLogDebug(Storage:PStorageDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure StorageStatusTimer(Storage:PStorageDevice);
Description: To be documented
| Note | None documented |
|---|
USB storage helper functions
function USBStorageCheckSubclass(Subclass:Byte):Boolean;
Description: To be documented
| Note | None documented |
|---|
function USBStorageCheckProtocol(Protocol:Byte):Boolean;
Description: To be documented
| Note | None documented |
|---|
function USBStorageBlockSizeToBlockShift(BlockSize:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
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 |
|---|
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 |
|---|
function USBStorageDeviceLock(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Issue a Prevent Media Removal request to a storage device
| Note | None documented |
|---|
function USBStorageDeviceUnlock(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Issue a Allow Media Removal request to a storage device
| Note | None documented |
|---|
function USBStorageDeviceLoad(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Issue a Start Stop request to a storage device
| Note | None documented |
|---|
function USBStorageDeviceEject(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Issue a Start Stop request to a storage device
| Note | None documented |
|---|
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. |
|---|
function USBStorageDeviceGetInfo(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: Obtain basic information about a storage device (Type, Size, State, Product etc)
| Note | None documented |
|---|
function USBStorageDeviceGetStatus(Device:PUSBDevice; Storage:PUSBStorageDevice):LongWord;
Description: To be documented
| Note | Supported by Subclass SCSI/UFI/SFF8070 |
|---|
function USBStorageDeviceGetMaxLUN(Device:PUSBDevice; Storage:PUSBStorageDevice; var MaxLUN:Byte):LongWord;
Description: Issue a Get Max LUN request to a storage device
| Note | None documented |
|---|
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 |
|---|
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 |
|---|
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 |
|---|
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 |
|---|
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 |
|---|
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. |
|---|
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. |
|---|
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. |
|---|
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. |
|---|
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
