tMSCDMedia tUSBDMSCDevice
Defines
COMPOSITE_DMSC_SIZE USBD_MSC_EVENT_IDLE USBD_MSC_EVENT_READING USBD_MSC_EVENT_WRITINGFunctions
void ∗ USBDMSCCompositeInit (uint32_t ui32Index, tUSBDMSCDevice ∗psMSCDevice,
tCompositeEntry∗psCompEntry)
void∗USBDMSCInit(uint32_t ui32Index,tUSBDMSCDevice∗psMSCDevice)
voidUSBDMSCMediaChange(void∗pvMSCDevice, tUSBDMSCMediaStatus iMediaStatus) voidUSBDMSCTerm(void∗pvMSCDevice)
2.22.1
Detailed Description
The macros and functions defined in this section can be found in header filedevice/usbdmsc.h.
2.22.2
Data Structure Documentation
2.22.2.1 tMSCDMedia
Definition:typedef struct {
void * (*pfnOpen)(uint32_t ui32Drive); void (*pfnClose)(void *pvDrive);
uint32_t (*pfnBlockRead)(void *pvDrive, uint8_t *pui8Data, uint32_t ui32Sector, uint32_t ui32NumBlocks); uint32_t (*pfnBlockWrite)(void *pvDrive,
uint8_t *pui8Data, uint32_t ui32Sector, uint32_t ui32NumBlocks); uint32_t (*pfnNumBlocks)(void *pvDrive);
uint32_t (*pfnBlockSize)(void *pvDrive); }
tMSCDMedia Members:
pfnOpen This function is used to initialize and open the physical drive number associated with
the parameterui32Drive. The function returns zero if the drive could not be opened for some reason. In the case of removable device like an SD card this function must return zero if the SD card is not present. The function returns a pointer to data that should be passed to other APIs or returns 0 if no drive was found.
pfnClose This function closes the drive number in use by the mass storage class device. The
pvDrive is the pointer that was returned from a call to pfnOpen . This function is used to close the physical drive number associated with the parameterpvDrive. This function returns 0 if the drive was closed successfully and any other value indicates a failure.
pfnBlockRead This function reads a block of data from a device opened by thepfnOpencall.
ThepvDriveparameter is the pointer that was returned from the original call topfnOpen. Thepui8Dataparameter is the buffer that data will be written into. The data area pointed to bypui8Datamust be at leastui32NumBlocks* Block Size bytes to prevent overwriting data. Theui32Sector is the block address to read andui32NumBlocksis the number of blocks to read. This function returns the number of bytes that were read from the and placed into thepui8Databuffer..
pfnBlockWrite This function is use to write blocks to a physical device from the buffer pointed
to by thepui8Databuffer. ThepvDriveparameter is the pointer that was returned from the original call topfnOpen. Thepui8Datais the pointer to the data to write to the storage device andui32NumBlocksis the number of blocks to write. Theui32Sectorparameter is the sector number used to write the block. If the number of blocks is greater than one then the block address increments and writes to the next block untilui32NumBlocks* Block Size bytes are written. This function returns the number of bytes that were written to the device.
pfnNumBlocks This function returns the total number of blocks on a physical device based
on thepvDriveparameter. The pvDrive parameter is the pointer that was returned from the original call topfnOpen.
pfnBlockSize This function returns the block size for a physical device based on thepvDrive
parameter. ThepvDriveparameter is the pointer that was returned from the original call to
pfnOpen.
Description:
Media Access functions.
2.22.2.2 tUSBDMSCDevice
Definition:typedef struct {
const uint16_t ui16VID; const uint16_t ui16PID; const uint8_t pui8Vendor[8]; const uint8_t pui8Product[16]; const uint8_t pui8Version[4]; const uint16_t ui16MaxPowermA; const uint8_t ui8PwrAttributes;
const uint8_t *const *ppui8StringDescriptors; const uint32_t ui32NumStringDescriptors; const tMSCDMedia sMediaFunctions;
const tUSBCallback pfnEventCallback; tMSCInstance sPrivateData;
}
tUSBDMSCDevice Members:
ui16VID The vendor ID that this device is to present in the device descriptor.
pui8Vendor 8 byte vendor string.
pui8Product 16 byte vendor string.
pui8Version 4 byte vendor string.
ui16MaxPowermA The maximum power consumption of the device, expressed in milliamps.
ui8PwrAttributes Indicates whether the device is self or bus-powered and whether or
not it supports remote wakeup. Valid values are USB_CONF_ATTR_SELF_PWR or
USB_CONF_ATTR_BUS_PWR, optionally ORed withUSB_CONF_ATTR_RWAKE.
ppui8StringDescriptors A pointer to the string descriptor array for this device. This array
must contain the following string descriptor pointers in this order. Language descriptor, Manufacturer name string (language 1), Product name string (language 1), Serial number string (language 1), MSC Interface description string (language 1), Configuration descrip- tion string (language 1).
If supporting more than 1 language, the descriptor block (except for string descriptor 0) must be repeated for each language defined in the language descriptor.
ui32NumStringDescriptors The number of descriptors provided in the ppStringDescriptors
array. This must be 1 + ((5 + (num HID strings)) * (num languages)).
sMediaFunctions This structure holds the access functions for the media used by this in-
stance of the mass storage class device. All of the functions in this structure are required to be filled out with valid functions.
pfnEventCallback This is the callback function for various events that occur during mass stor-
age class operation.
sPrivateData The private instance data for this device. This memory must remain accessible
for as long as the MSC device is in use and must not be modified by any code outside the MSC class driver.
Description:
The structure used by the application to define operating parameters for the mass storage device.
2.22.3
Define Documentation
2.22.3.1 COMPOSITE_DMSC_SIZE
Definition: #define COMPOSITE_DMSC_SIZE Description:The size of the memory that should be allocated to create a configuration descriptor for a single instance of the USB Audio Device. This does not include the configuration descriptor which is automatically ignored by the composite device class.
2.22.3.2 USBD_MSC_EVENT_IDLE
Definition:#define USBD_MSC_EVENT_IDLE Description:
This event indicates that the host has completed other operations and is no longer accessing the device.
2.22.3.3 USBD_MSC_EVENT_READING
Definition:#define USBD_MSC_EVENT_READING Description:
This event indicates that the host is reading the storage media.
2.22.3.4 USBD_MSC_EVENT_WRITING
Definition:#define USBD_MSC_EVENT_WRITING Description:
This event indicates that the host is writing to the storage media.
2.22.4
Function Documentation
2.22.4.1 USBDMSCCompositeInit
This function should be called once for the mass storage class device to initialized basic operation and prepare for enumeration.
Prototype: void * USBDMSCCompositeInit(uint32_t ui32Index, tUSBDMSCDevice *psMSCDevice, tCompositeEntry *psCompEntry) Parameters:
ui32Index is the index of the USB controller to initialize for mass storage class device opera-
tion.
psMSCDevice points to a structure containing parameters customizing the operation of the
mass storage device.
psCompEntry is the composite device entry to initialize when creating a composite device.
Description:
In order for an application to initialize the USB device mass storage class, it must first call this function with the a valid mass storage device class structure in thepsMSCDeviceparameter. This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a USB mass storage device. If this mass storage device is part of a composite device, then thepsCompEntry should point to the composite device entry to initialize. This is part of the array that is passed to theUSBDCompositeInit()function.
This function returns a void pointer that must be passed in to all other APIs used by the mass storage class.
See the documentation on the tUSBDMSCDevice structure for more information on how to properly fill the structure members.
Returns:
Returns zero on failure or a non-zero instance value that should be used with the remaining USB mass storage APIs.
2.22.4.2 USBDMSCInit
This function should be called once for the mass storage class device to initialized basic operation and prepare for enumeration.
Prototype: void *
USBDMSCInit(uint32_t ui32Index,
tUSBDMSCDevice *psMSCDevice) Parameters:
ui32Index is the index of the USB controller to initialize for mass storage class device opera-
tion.
psMSCDevice points to a structure containing parameters customizing the operation of the
mass storage device.
Description:
In order for an application to initialize the USB device mass storage class, it must first call this function with the a valid mass storage device class structure in thepsMSCDeviceparameter. This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a USB mass storage device.
This function returns a void pointer that must be passed in to all other APIs used by the mass storage class.
See the documentation on the tUSBDMSCDevice structure for more information on how to properly fill the structure members.
Returns:
Returns 0 on failure or a non-zero void pointer on success.
2.22.4.3 USBDMSCMediaChange
This function is used by an application if it can detect insertion or removal of the media.
Prototype: void
USBDMSCMediaChange(void *pvMSCDevice,
tUSBDMSCMediaStatus iMediaStatus) Parameters:
pvMSCDevice is the mass storage device instance that had a media change.
iMediaStatus is the updated status for the media.
Description:
This function should be called by an application when it detects a change in the status of the media in use by the USB mass storage class. TheiMediaStatus parameter will indicate the
new status of the media and can also indicate that the application has no knowledge of the media state.
There are currently the three following values for theiMediaStatusparameter:
eUSBDMSCMediaPresentindicates that the media is present or has been added.
eUSBDMSCMediaNotPresentindicates that the media is not present or was removed.
eUSBDMSCMediaUnknownindicates that the application has no knowledge of the media state and the USB mass storage class.
It will be left up to the application to call this function whenever it detects a change or simply call it once witheUSBDMSCMediaUnknown and allow the mass storage class to infer the state from the remaining device APIs.
Note:
It is recommended that the application use this function to inform the mass storage class of media state changes as it will lead to a more responsive system.
Returns:
None.
2.22.4.4 USBDMSCTerm
Shuts down the mass storage device.
Prototype: void
USBDMSCTerm(void *pvMSCDevice) Parameters:
pvMSCDevice is the pointer to the device instance structure as returned byUSBDMSCInit()
orUSBDMSCCompositeInit().
Description:
This function terminates mass storage operation for the instance supplied and removes the de- vice from the USB bus. Following this call, thepvMSCDeviceinstance may not me used in any other call to the mass storage device other thanUSBDMSCInit()orUSBDMSCCompositeInit().
Returns:
None.