Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
USB Host Interface (UHI) for Mass Storage Class (MSC)

USB Host Interface (UHI) for Mass Storage Class (MSC) provides an interface for the configuration and management of USB MSC host.

The outline of this documentation is as follows:

For more details for Atmel® Software Framework (ASF) USB Host Stack, refer to following application note:

API Overview

Data Structures

struct  uhi_msc_lun_t
 Logical Unit Number (LUN) structure information. More...
 

Typedefs

typedef void(* uhi_msc_scsi_callback_t )(bool)
 Callback type used by uhi_msc_scsi() functions. More...
 

Enumerations

enum  lun_status_t {
  LUN_GOOD = 0,
  LUN_FAIL = 1,
  LUN_NOT_PRESENT = 2,
  LUN_BUSY = 3,
  LUN_GOOD = 0,
  LUN_FAIL = 1,
  LUN_NOT_PRESENT = 2,
  LUN_BUSY = 3
}
 Status of LUN. More...
 

Interface with USB Host Core (UHC)

Definition and functions required by UHC.

#define UHI_MSC
 Global definition which contains standard UHI API for UHC. More...
 

Functions Required by UHC

uhc_enum_status_t uhi_msc_install (uhc_device_t *dev)
 Install interface. More...
 
void uhi_msc_enable (uhc_device_t *dev)
 Enable the interface. More...
 
void uhi_msc_uninstall (uhc_device_t *dev)
 Uninstall the interface (if installed). More...
 

UHI for Mass Storage Class

Common APIs used by high level application to use this USB host class.

bool uhi_msc_is_available (void)
 Tests if the interface UHI Mass Storage is available. More...
 
uint8_t uhi_msc_get_lun (void)
 Gives the number of LUN available. More...
 
uhi_msc_lun_tuhi_msc_get_lun_desc (uint8_t lun)
 Gives information about a LUN. More...
 
bool uhi_msc_scsi_test_unit_ready (uint8_t lun, uhi_msc_scsi_callback_t callback)
 Checks and update the status of the LUN. More...
 
bool uhi_msc_scsi_read_10 (uint8_t lun, uint32_t addr, uint8_t *ram, uint8_t nb_sector, uhi_msc_scsi_callback_t callback)
 Reads a LUN data section to RAM buffer. More...
 
bool uhi_msc_scsi_write_10 (uint8_t lun, uint32_t addr, const uint8_t *ram, uint8_t nb_sector, uhi_msc_scsi_callback_t callback)
 Writes a RAM buffer in a LUN data section. More...
 

USB Host Mass Storage Interface for Control Access Module

Layer added on UHI MSC interface to allow the usage of control access module.

The control access module provides a common access at all memories and it is used by the File Systems available in ASF.

uint8_t uhi_msc_mem_get_lun (void)
 Gives the number of available LUN. More...
 
Ctrl_status uhi_msc_mem_test_unit_ready (uint8_t lun)
 Checks and update the status of the LUN. More...
 
Ctrl_status uhi_msc_mem_read_capacity (uint8_t lun, uint32_t *u32_nb_sector)
 Returns the capacity of the LUN. More...
 
uint8_t uhi_msc_mem_read_sector_size (uint8_t lun)
 Returns the sector size of the LUN. More...
 
bool uhi_msc_mem_wr_protect (uint8_t lun)
 Checks if the LUN is write protected. More...
 
bool uhi_msc_mem_removal (void)
 Checks if the device is removed. More...
 
Ctrl_status uhi_msc_mem_read_10_ram (uint32_t addr, void *ram)
 Reads 512 bytes from the current LUN. More...
 
Ctrl_status uhi_msc_mem_write_10_ram (uint32_t addr, const void *ram)
 Writes 512 bytes to the current LUN. More...
 

#define UHI_MSC
Value:
{ \
.install = uhi_msc_install, \
.enable = uhi_msc_enable, \
.uninstall = uhi_msc_uninstall, \
.sof_notify = NULL, \
}
#define NULL
Definition: def.h:47
void uhi_msc_uninstall(uhc_device_t *dev)
Uninstall the interface (if installed).
Definition: uhi_msc.c:316
uhc_enum_status_t uhi_msc_install(uhc_device_t *dev)
Install interface.
void uhi_msc_enable(uhc_device_t *dev)
Enable the interface.
Definition: uhi_msc.c:291

Global definition which contains standard UHI API for UHC.

It must be added in USB_HOST_UHI definition from conf_usb_host.h file.

typedef void(* uhi_msc_scsi_callback_t)(bool)

Callback type used by uhi_msc_scsi() functions.

Status of LUN.

Enumerator
LUN_GOOD 

Success, memory ready.

LUN_FAIL 

An error occurred.

LUN_NOT_PRESENT 

Memory unplugged.

LUN_BUSY 

Memory not initialized or changed.

LUN_GOOD 

Success, memory ready.

LUN_FAIL 

An error occurred.

LUN_NOT_PRESENT 

Memory unplugged.

LUN_BUSY 

Memory not initialized or changed.

void uhi_msc_enable ( uhc_device_t dev)

Enable the interface.

Enable a USB interface corresponding to UHI.

Parameters
[in]uhc_device_tDevice to request
uint8_t uhi_msc_get_lun ( void  )

Gives the number of LUN available.

Note
A LUN can be available, but with a status LUN_NOT_PRESENT.

It is the case for a card reader without card.

Returns
Number of LUN available.

Referenced by uhi_msc_mem_get_lun().

uhi_msc_lun_t* uhi_msc_get_lun_desc ( uint8_t  lun)

Gives information about a LUN.

Parameters
[in]lunLUN number
Returns
Pointer on the LUN information structure.

Referenced by uhi_msc_mem_read_10_ram(), uhi_msc_mem_read_capacity(), uhi_msc_mem_read_sector_size(), uhi_msc_mem_test_unit_ready(), uhi_msc_mem_wr_protect(), and uhi_msc_mem_write_10_ram().

uhc_enum_status_t uhi_msc_install ( uhc_device_t dev)

Install interface.

Allocate interface endpoints if supported.

Parameters
[in]uhc_device_tDevice to request
Returns
Status of the install.
bool uhi_msc_is_available ( void  )

Tests if the interface UHI Mass Storage is available.

The UHI Mass Storage can be busy during the enumeration of a USB Device MSC.

Returns
True, if UHI Mass Storage is available.

Referenced by uhi_msc_mem_get_lun(), uhi_msc_mem_read_10_ram(), uhi_msc_mem_read_capacity(), uhi_msc_mem_read_sector_size(), uhi_msc_mem_test_unit_ready(), uhi_msc_mem_wr_protect(), and uhi_msc_mem_write_10_ram().

uint8_t uhi_msc_mem_get_lun ( void  )

Gives the number of available LUN.

Note
A LUN can be available, but with a status not present.

It is the case for a card reader without card.

Returns
Number of available LUN.

Referenced by main().

Ctrl_status uhi_msc_mem_read_10_ram ( uint32_t  addr,
void *  ram 
)

Reads 512 bytes from the current LUN.

The LUN is selected by uhi_msc_mem_test_unit_ready() or uhi_msc_mem_read_capacity() function.

Parameters
[in]addrDisk address (unit 512B)
[out]ramPointer to store the data
Returns
Status of the LUN.
Ctrl_status uhi_msc_mem_read_capacity ( uint8_t  lun,
uint32_t *  u32_nb_sector 
)

Returns the capacity of the LUN.

Parameters
[in]lunLUN number
[in]u32_nb_sectorPointer to store the last sector address possible on this LUN
Returns
Status of the LUN.
uint8_t uhi_msc_mem_read_sector_size ( uint8_t  lun)

Returns the sector size of the LUN.

Parameters
[in]lunLUN number
Returns
Sector size (unit 512B).
bool uhi_msc_mem_removal ( void  )

Checks if the device is removed.

Returns
Always true for USB Device.
Ctrl_status uhi_msc_mem_test_unit_ready ( uint8_t  lun)

Checks and update the status of the LUN.

Parameters
[in]lunLUN number
Returns
Status of the LUN.
bool uhi_msc_mem_wr_protect ( uint8_t  lun)

Checks if the LUN is write protected.

Parameters
[in]lunLUN number
Returns
True, if write protected.
Ctrl_status uhi_msc_mem_write_10_ram ( uint32_t  addr,
const void *  ram 
)

Writes 512 bytes to the current LUN.

The LUN is selected by uhi_msc_mem_test_unit_ready() or uhi_msc_mem_read_capacity() function.

Parameters
[in]addrDisk address (unit 512B)
[in]ramPointer on the data
Returns
Status of the LUN.
bool uhi_msc_scsi_read_10 ( uint8_t  lun,
uint32_t  addr,
uint8_t *  ram,
uint8_t  nb_sector,
uhi_msc_scsi_callback_t  callback 
)

Reads a LUN data section to RAM buffer.

Note
The sector size used to define the data section is the sector size returned by LUN in field.
Parameters
[in]lunLUN number
[in]addrSector address to read
[out]ramRAM address used to store the data
[in]nb_sectorNumber of sector to read
[in]callbackCallback to call at the end of SCSI command
Returns
True, if the SCSI command has been accepted.

Referenced by uhi_msc_mem_read_10_ram().

bool uhi_msc_scsi_test_unit_ready ( uint8_t  lun,
uhi_msc_scsi_callback_t  callback 
)

Checks and update the status of the LUN.

Parameters
[in]lunLUN number
[in]callbackCallback to call at the end of SCSI command
Returns
True, if the Small Computer System Interface (SCSI) command has been accepted.

Referenced by uhi_msc_mem_test_unit_ready().

bool uhi_msc_scsi_write_10 ( uint8_t  lun,
uint32_t  addr,
const uint8_t *  ram,
uint8_t  nb_sector,
uhi_msc_scsi_callback_t  callback 
)

Writes a RAM buffer in a LUN data section.

Note
The sector size used to define the data section is the sector size returned by LUN in field.
Parameters
[in]lunLUN number
[in]addrSector address to write
[in]ramRAM address of data to write
[in]nb_sectorNumber of sector to write
[in]callbackCallback to call at the end of SCSI command
Returns
True, if the SCSI command has been accepted.

Referenced by uhi_msc_mem_write_10_ram().

void uhi_msc_uninstall ( uhc_device_t dev)

Uninstall the interface (if installed).

Parameters
[in]uhc_device_tDevice to request