Unit Storage

From Ultibo.org
Revision as of 03:24, 29 March 2024 by Ultibo (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Return to Unit Reference


Description


Ultibo Storage Interface unit

This unit provides the generic Storage device interface used by all storage drivers.

Constants



Storage specific constants STORAGE_*
STORAGE_NAME_PREFIX = 'Storage'; Name prefix for Storage Devices
 
STORAGE_STATUS_TIMER_INTERVAL = 1000;  


Storage device type 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 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 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 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 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_WARN = LOG_LEVEL_WARN; Storage warning messages
STORAGE_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR; Storage error messages
STORAGE_LOG_LEVEL_NONE = LOG_LEVEL_NONE; No Storage messages


Type definitions



Storage enumeration callback

TStorageEnumerate = function(Storage:PStorageDevice; Data:Pointer):LongWord;

Storage notification callback

TStorageNotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;

Storage device read

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

Storage device write

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

Storage device erase

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

Storage device control

TStorageDeviceControl = function(Storage:PStorageDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;

Storage device

PStorageDevice = ^TStorageDevice;

TStorageDevice = record

Device Properties
Device:TDevice; The Device entry for this Storage
Storage Properties
StorageId:LongWord; Unique Id of this Storage in the Storage table
StorageState:LongWord; Storage state (eg STORAGE_STATE_INSERTED)
DeviceRead:TStorageDeviceRead; A Device specific DeviceRead method implementing a standard Storage device interface
DeviceWrite:TStorageDeviceWrite; A Device specific DeviceWrite method implementing a standard Storage device interface
DeviceErase:TStorageDeviceErase; A Device specific DeviceErase method implementing a standard Storage device interface
DeviceControl:TStorageDeviceControl; A Device specific DeviceControl method implementing a standard Storage device interface
Driver Properties
Lock:TMutexHandle; Storage lock
TargetID:LongWord; SCSI Id
TargetLUN:LongWord; LUN
BlockSize:LongWord; Block Size
BlockCount:Int64; Number of Blocks
BlockShift:LongWord; Shift Count for Blocks to Bytes conversion (eg 9 for 512 byte blocks)
Vendor:PChar; ATA Model, SCSI Vendor
Product:PChar; ATA Serial No, SCSI Product
Revision:PChar; Firmware Revision
StatusTimer:TTimerHandle; Timer for status change detection
Statistics Properties
ReadCount:LongWord;  
ReadErrors:LongWord;  
WriteCount:LongWord;  
WriteErrors:LongWord;  
EraseCount:LongWord;  
EraseErrors:LongWord;  
Internal Properties
Prev:PStorageDevice; Previous entry in Storage table
Next:PStorageDevice; Next entry in Storage table


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:PtrUInt; var Argument2:PtrUInt):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 StorageDeviceFindByDevice(Device:PDevice):PStorageDevice;
Description: Find a Storage device by the matching DeviceData property
Device The device entry to match with the DeviceData value
Return The Storage device matched or nil if none found


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


Storage helper functions

function StorageGetCount:LongWord;
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); inline;
Description: To be documented
Note None documented


procedure StorageLogWarn(Storage:PStorageDevice; const AText:String); inline;
Description: To be documented
Note None documented


procedure StorageLogError(Storage:PStorageDevice; const AText:String); inline;
Description: To be documented
Note None documented


procedure StorageLogDebug(Storage:PStorageDevice; const AText:String); inline;
Description: To be documented
Note None documented


procedure StorageStatusTimer(Storage:PStorageDevice);
Description: To be documented
Note None documented


Return to Unit Reference