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:

• API Overview
• Quick Start Guide for USB Host Mass-Storage Module (UHI MSC)
• Configuration File Examples

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

• AVR4950: ASF - USB Host Stack

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 }
	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_t *	uhi_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, \
}

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.

enum lun_status_t

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.

void uhi_msc_enable

(

uhc_device_t *

dev

)

Enable the interface.

Enable a USB interface corresponding to UHI.

Parameters

[in]

uhc_device_t

Device 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.

uhi_msc_lun_t* uhi_msc_get_lun_desc

(

uint8_t

lun

)

Gives information about a LUN.

Parameters

[in]

lun

LUN number

Returns

Pointer on the LUN information structure.

uhc_enum_status_t uhi_msc_install

(

uhc_device_t *

dev

)

Install interface.

Allocate interface endpoints if supported.

Parameters

[in]

uhc_device_t

Device 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.

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.

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]	addr	Disk address (unit 512B)
[out]	ram	Pointer 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]	lun	LUN number
[in]	u32_nb_sector	Pointer 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]

lun

LUN 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]

lun

LUN number

Returns

Status of the LUN.

bool uhi_msc_mem_wr_protect

(

uint8_t

lun

)

Checks if the LUN is write protected.

Parameters

[in]

lun

LUN 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]	addr	Disk address (unit 512B)
[in]	ram	Pointer 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]	lun	LUN number
[in]	addr	Sector address to read
[out]	ram	RAM address used to store the data
[in]	nb_sector	Number of sector to read
[in]	callback	Callback to call at the end of SCSI command

Returns

True, if the SCSI command has been accepted.

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]	lun	LUN number
[in]	callback	Callback to call at the end of SCSI command

Returns

True, if the Small Computer System Interface (SCSI) command has been accepted.

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]	lun	LUN number
[in]	addr	Sector address to write
[in]	ram	RAM address of data to write
[in]	nb_sector	Number of sector to write
[in]	callback	Callback to call at the end of SCSI command

Returns

True, if the SCSI command has been accepted.

void uhi_msc_uninstall

(

uhc_device_t *

dev

)

Uninstall the interface (if installed).

Parameters

[in]

uhc_device_t

Device to request