LPCOpen Platform
LPCOpen Platform for NXP LPC Microcontrollers
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Mass Storage Class Host Mode Driver

Data Structures

struct  USB_ClassInfo_MS_Host_t
 Mass Storage Class Host Mode Configuration and State Structure. More...
 
struct  SCSI_Capacity_t
 SCSI Device LUN Capacity Structure. More...
 

Macros

#define MS_ERROR_LOGICAL_CMD_FAILED   0x80
 

Enumerations

enum  MS_Host_EnumerationFailure_ErrorCodes_t { MS_ENUMERROR_NoError = 0, MS_ENUMERROR_InvalidConfigDescriptor = 1, MS_ENUMERROR_NoCompatibleInterfaceFound = 2, MS_ENUMERROR_PipeConfigurationFailed = 3 }
 

Functions

uint8_t MS_Host_ConfigurePipes (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo, uint16_t ConfigDescriptorSize, void *ConfigDescriptorData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
 Host interface configuration routine, to configure a given Mass Storage host interface instance using the Configuration Descriptor read from an attached USB device. This function automatically updates the given Mass Storage Host instance's state values and configures the pipes required to communicate with the interface if it is found within the device. This should be called once after the stack has enumerated the attached device, while the host state machine is in the Addressed state.
 
uint8_t MS_Host_ResetMSInterface (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
 Sends a MASS STORAGE RESET control request to the attached device, resetting the Mass Storage Interface and readying it for the next Mass Storage command. This should be called after a failed SCSI request to ensure the attached Mass Storage device is ready to receive the next command.
 
uint8_t MS_Host_GetMaxLUN (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo, uint8_t *const MaxLUNIndex) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2)
 Sends a GET MAX LUN control request to the attached device, retrieving the index of the highest LUN (Logical UNit, a logical drive) in the device. This value can then be used in the other functions of the Mass Storage Host mode Class driver to address a specific LUN within the device.
 
uint8_t MS_Host_GetInquiryData (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo, const uint8_t LUNIndex, SCSI_Inquiry_Response_t *const InquiryData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
 Retrieves the Mass Storage device's inquiry data for the specified LUN, indicating the device characteristics and properties.
 
uint8_t MS_Host_TestUnitReady (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo, const uint8_t LUNIndex) ATTR_NON_NULL_PTR_ARG(1)
 Sends a TEST UNIT READY command to the device, to determine if it is ready to accept other SCSI commands.
 
uint8_t MS_Host_ReadDeviceCapacity (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo, const uint8_t LUNIndex, SCSI_Capacity_t *const DeviceCapacity) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
 Retrieves the total capacity of the attached USB Mass Storage device, in blocks, and block size.
 
uint8_t MS_Host_RequestSense (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo, const uint8_t LUNIndex, SCSI_Request_Sense_Response_t *const SenseData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
 Retrieves the device sense data, indicating the current device state and error codes for the previously issued command.
 
uint8_t MS_Host_PreventAllowMediumRemoval (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo, const uint8_t LUNIndex, const bool PreventRemoval) ATTR_NON_NULL_PTR_ARG(1)
 Issues a PREVENT MEDIUM REMOVAL command, to logically (or, depending on the type of device, physically) lock the device from removal so that blocks of data on the medium can be read or altered.
 
uint8_t MS_Host_ReadDeviceBlocks (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo, const uint8_t LUNIndex, const uint32_t BlockAddress, const uint8_t Blocks, const uint16_t BlockSize, void *BlockBuffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(6)
 Reads blocks of data from the attached Mass Storage device's medium.
 
uint8_t MS_Host_WriteDeviceBlocks (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo, const uint8_t LUNIndex, const uint32_t BlockAddress, const uint8_t Blocks, const uint16_t BlockSize, const void *BlockBuffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(6)
 Writes blocks of data to the attached Mass Storage device's medium.
 
static void MS_Host_USBTask (USB_ClassInfo_MS_Host_t *const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE
 General management task for a given Mass Storage host class interface, required for the correct operation of the interface. This should be called frequently in the main program loop, before the master USB management task USB_USBTask().
 

Detailed Description

Module Source Dependencies

The following files must be built with any user project that uses this module:

Module Description

Host Mode USB Class driver framework interface, for the Mass Storage USB Class driver.

Macro Definition Documentation

#define MS_ERROR_LOGICAL_CMD_FAILED   0x80

Error code for some Mass Storage Host functions, indicating a logical (and not hardware) error.

Definition at line 66 of file MassStorageClassHost.h.

Enumeration Type Documentation

Enumerator:
MS_ENUMERROR_NoError 

Configuration Descriptor was processed successfully.

MS_ENUMERROR_InvalidConfigDescriptor 

The device returned an invalid Configuration Descriptor.

MS_ENUMERROR_NoCompatibleInterfaceFound 

A compatible Mass Storage interface was not found in the device's Configuration Descriptor.

MS_ENUMERROR_PipeConfigurationFailed 

One or more pipes for the specified interface could not be configured correctly.

Definition at line 120 of file MassStorageClassHost.h.

Function Documentation

uint8_t MS_Host_ConfigurePipes ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo,
uint16_t  ConfigDescriptorSize,
void *  ConfigDescriptorData 
)

Host interface configuration routine, to configure a given Mass Storage host interface instance using the Configuration Descriptor read from an attached USB device. This function automatically updates the given Mass Storage Host instance's state values and configures the pipes required to communicate with the interface if it is found within the device. This should be called once after the stack has enumerated the attached device, while the host state machine is in the Addressed state.

Parameters
MSInterfaceInfo: Pointer to a structure containing an MS Class host configuration and state.
ConfigDescriptorSize: Length of the attached device's Configuration Descriptor.
ConfigDescriptorData: Pointer to a buffer containing the attached device's Configuration Descriptor.
Returns
A value from the MS_Host_EnumerationFailure_ErrorCodes_t enum.

Definition at line 43 of file MassStorageClassHost.c.

uint8_t MS_Host_GetInquiryData ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo,
const uint8_t  LUNIndex,
SCSI_Inquiry_Response_t *const  InquiryData 
)

Retrieves the Mass Storage device's inquiry data for the specified LUN, indicating the device characteristics and properties.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Parameters
MSInterfaceInfo: Pointer to a structure containing a MS Class host configuration and state.
LUNIndex: LUN index within the device the command is being issued to.
InquiryData: Location where the read inquiry data should be stored.
Returns
A value from the Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED.

Definition at line 400 of file MassStorageClassHost.c.

uint8_t MS_Host_GetMaxLUN ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo,
uint8_t *const  MaxLUNIndex 
)

Sends a GET MAX LUN control request to the attached device, retrieving the index of the highest LUN (Logical UNit, a logical drive) in the device. This value can then be used in the other functions of the Mass Storage Host mode Class driver to address a specific LUN within the device.

Note
Some devices do not support this request, and will STALL it when issued. To get around this, on unsupported devices the max LUN index will be reported as zero and no error will be returned if the device STALLs the request.
Parameters
MSInterfaceInfo: Pointer to a structure containing a MS Class host configuration and state.
MaxLUNIndex: Pointer to a location where the highest LUN index value should be stored.
Returns
A value from the USB_Host_SendControlErrorCodes_t enum.

Definition at line 375 of file MassStorageClassHost.c.

uint8_t MS_Host_PreventAllowMediumRemoval ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo,
const uint8_t  LUNIndex,
const bool  PreventRemoval 
)

Issues a PREVENT MEDIUM REMOVAL command, to logically (or, depending on the type of device, physically) lock the device from removal so that blocks of data on the medium can be read or altered.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Parameters
MSInterfaceInfo: Pointer to a structure containing a MS Class host configuration and state.
LUNIndex: LUN index within the device the command is being issued to.
PreventRemoval: Boolean true if the device should be locked from removal, false otherwise.
Returns
A value from the Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready.

Definition at line 534 of file MassStorageClassHost.c.

uint8_t MS_Host_ReadDeviceBlocks ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo,
const uint8_t  LUNIndex,
const uint32_t  BlockAddress,
const uint8_t  Blocks,
const uint16_t  BlockSize,
void *  BlockBuffer 
)

Reads blocks of data from the attached Mass Storage device's medium.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Parameters
MSInterfaceInfo: Pointer to a structure containing a MS Class host configuration and state.
LUNIndex: LUN index within the device the command is being issued to.
BlockAddress: Starting block address within the device to read from.
Blocks: Total number of blocks to read.
BlockSize: Size in bytes of each block within the device.
BlockBuffer: Pointer to where the read data from the device should be stored.
Returns
A value from the Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready.

Definition at line 566 of file MassStorageClassHost.c.

uint8_t MS_Host_ReadDeviceCapacity ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo,
const uint8_t  LUNIndex,
SCSI_Capacity_t *const  DeviceCapacity 
)

Retrieves the total capacity of the attached USB Mass Storage device, in blocks, and block size.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Parameters
MSInterfaceInfo: Pointer to a structure containing a MS Class host configuration and state.
LUNIndex: LUN index within the device the command is being issued to.
DeviceCapacity: Pointer to the location where the capacity information should be stored.
Returns
A value from the Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready.

Definition at line 463 of file MassStorageClassHost.c.

uint8_t MS_Host_RequestSense ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo,
const uint8_t  LUNIndex,
SCSI_Request_Sense_Response_t *const  SenseData 
)

Retrieves the device sense data, indicating the current device state and error codes for the previously issued command.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Parameters
MSInterfaceInfo: Pointer to a structure containing a MS Class host configuration and state.
LUNIndex: LUN index within the device the command is being issued to.
SenseData: Pointer to the location where the sense information should be stored.
Returns
A value from the Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready.

Definition at line 502 of file MassStorageClassHost.c.

uint8_t MS_Host_ResetMSInterface ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo)

Sends a MASS STORAGE RESET control request to the attached device, resetting the Mass Storage Interface and readying it for the next Mass Storage command. This should be called after a failed SCSI request to ensure the attached Mass Storage device is ready to receive the next command.

Parameters
MSInterfaceInfo: Pointer to a structure containing a MS Class host configuration and state.
Returns
A value from the USB_Host_SendControlErrorCodes_t enum.

Definition at line 344 of file MassStorageClassHost.c.

uint8_t MS_Host_TestUnitReady ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo,
const uint8_t  LUNIndex 
)

Sends a TEST UNIT READY command to the device, to determine if it is ready to accept other SCSI commands.

Parameters
MSInterfaceInfo: Pointer to a structure containing a MS Class host configuration and state.
LUNIndex: LUN index within the device the command is being issued to.
Returns
A value from the Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready.

Definition at line 432 of file MassStorageClassHost.c.

static void MS_Host_USBTask ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo)
inlinestatic

General management task for a given Mass Storage host class interface, required for the correct operation of the interface. This should be called frequently in the main program loop, before the master USB management task USB_USBTask().

Parameters
MSInterfaceInfo: Pointer to a structure containing an Mass Storage Class host configuration and state.
Returns
Nothing

Definition at line 298 of file MassStorageClassHost.h.

uint8_t MS_Host_WriteDeviceBlocks ( USB_ClassInfo_MS_Host_t *const  MSInterfaceInfo,
const uint8_t  LUNIndex,
const uint32_t  BlockAddress,
const uint8_t  Blocks,
const uint16_t  BlockSize,
const void *  BlockBuffer 
)

Writes blocks of data to the attached Mass Storage device's medium.

Precondition
This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.
Parameters
MSInterfaceInfo: Pointer to a structure containing a MS Class host configuration and state.
LUNIndex: LUN index within the device the command is being issued to.
BlockAddress: Starting block address within the device to write to.
Blocks: Total number of blocks to read.
BlockSize: Size in bytes of each block within the device.
BlockBuffer: Pointer to where the data to write should be sourced from.
Returns
A value from the Pipe_Stream_RW_ErrorCodes_t enum or MS_ERROR_LOGICAL_CMD_FAILED if not ready.

Definition at line 605 of file MassStorageClassHost.c.