USB Device MSC API#

USBD_MSC_ConfigureBufAlignOctets()#

Description#

Configures the alignment of the internal buffers.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

void  USBD_MSC_ConfigureBufAlignOctets (CPU_SIZE_T  buf_align_octets)

Arguments#

buf_align_octets

Buffer alignment, in octets.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the MSC class is initialized via the USBD_MSC_Init() function.

USBD_MSC_ConfigureDataBufLen()#

Description#

Configures the length, in octets, of the buffer used to exchange MSC data with the USB host.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

void  USBD_MSC_ConfigureDataBufLen (CPU_INT32U  data_buf_len)

Arguments#

data_buf_len

Data buffer length, in octets.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the MSC class is initialized via the USBD_MSC_Init() function.

USBD_MSC_ConfigureMemSeg()#

Description#

Configures the memory segment to use when allocating control data and buffers.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

void  USBD_MSC_ConfigureMemSeg (MEM_SEG  *p_mem_seg,
                                MEM_SEG  *p_mem_seg_buf)

Arguments#

p_mem_seg

Pointer to memory segment to use when allocating control data. Can be the same segment used for p_mem_seg_buf. DEF_NULL means general purpose heap segment.

p_mem_seg_buf

Pointer to memory segment to use when allocating data buffers. Can be the same segment used for p_mem_seg. DEF_NULL means general purpose heap segment.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the MSC class is initialized via the USBD_MSC_Init() function.

USBD_MSC_Init()#

Description#

Initializes internal structures and variables used by the Mass Storage Class Bulk Only Transport.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

void USBD_MSC_Init (USBD_MSC_CFG  *p_qty_cfg,
                    RTOS_ERR      *p_err)

Arguments#

p_qty_cfg

Pointer to the MSC configuration structure.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

None.

USBD_MSC_Add()#

Description#

Adds a new instance of the Mass Storage Class.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

CPU_INT08U USBD_MSC_Add (RTOS_TASK_CFG    *p_msc_task_cfg,
                         RTOS_ERR         *p_err)

Arguments#

p_msc_task_cfg

Pointer to the configuration structure of the task to be created for this MSC instance.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_CLASS_INSTANCE_ALLOC

  • RTOS_ERR_SEG_OVF

Returned Value#

  • Class instance number, if no errors are returned.

  • USBD_CLASS_NBR_NONE, if any errors are returned.

Notes / Warnings#

None.

USBD_MSC_TaskPrioSet()#

Description#

Sets priority of the given MSC class instance.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

void  USBD_MSC_TaskPrioSet (CPU_INT08U       class_nbr,
                            RTOS_TASK_PRIO   prio,
                            RTOS_ERR        *p_err)

Arguments#

class_nbr

MSC instance number.

prio

Priority of the MSC instance's task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

None.

USBD_MSC_ConfigAdd()#

Description#

Adds an existing MSC instance to the specified configuration and device.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

CPU_BOOLEAN USBD_MSC_ConfigAdd (CPU_INT08U    class_nbr,
                                CPU_INT08U    dev_nbr,
                                CPU_INT08U    config_nbr,
                                RTOS_ERR     *p_err)

Arguments#

class_nbr

MSC instance number.

dev_nbr

Device number.

config_nbr

Configuration index to which to add the existing MSC interface.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_IF_ALT_ALLOC

  • RTOS_ERR_ALLOC

  • RTOS_ERR_CLASS_INSTANCE_ALLOC

  • RTOS_ERR_IF_ALLOC

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_EP_ALLOC

  • RTOS_ERR_EP_NONE_AVAIL

Returned Value#

  • DEF_YES, if the MSC instance is added to USB device configuration successfully.

  • DEF_NO, if it fails to be added.

Notes / Warnings#

USBD_MSC_ConfigAdd() adds an Interface descriptor and its associated Endpoint descriptor(s) to the Configuration descriptor. One call to USBD_MSC_ConfigAdd() builds the Configuration descriptor corresponding to an MSC device with the following format:

Configuration Descriptor
|-- Interface Descriptor (MSC)
|-- Endpoint Descriptor (Bulk OUT)
|-- Endpoint Descriptor (Bulk IN)

If USBD_MSC_ConfigAdd() is called several times from the application, it creates multiple instances and configurations. For example, the following architecture could be created for a high-speed device:

High-speed
|-- Configuration 0
|-- Interface 0 (MSC 0)
|-- Configuration 1
|-- Interface 0 (MSC 0)
|-- Interface 1 (MSC 1)

In this example, there are two instances of MSC: 'MSC 0' and 'MSC 1', and two possible configurations for the device: 'Configuration 0' and 'Configuration 1'. 'Configuration 1' is composed of two interfaces.

Each class instance has an association with one of the interfaces. If 'Configuration 1' is activated by the host, it allows the host to access two different functionalities offered by the device.

USBD_MSC_SCSI_LunAdd()#

Description#

Adds a SCSI logical unit to the MSC interface.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

CPU_INT08U USBD_MSC_SCSI_LunAdd (CPU_INT08U            class_nbr,
                                 USBD_SCSI_LU_INFO    *p_lu_info,
                                 USBD_SCSI_LU_FNCTS   *p_lu_fncts,
                                 RTOS_ERR             *p_err)

Arguments#

class_nbr

MSC instance number.

p_lu_info

Pointer to the logical unit information structure.

p_lu_fncts

Pointer to the structure of callbacks associated to this logical unit. Can be DEF_NULL.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_ALLOC

Returned Value#

Logical Unit Number.

Notes / Warnings#

None.

USBD_MSC_SCSI_LunAttach()#

Description#

Attach a storage media to the given LUN.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

void USBD_MSC_SCSI_LunAttach (CPU_INT08U    class_nbr,
                              CPU_INT08U    lu_nbr,
                              CPU_CHAR     *media_name,
                              RTOS_ERR     *p_err)

Arguments#

class_nbr

MSC instance number.

lu_nbr

Logical unit number.

media_name

Name of the storage media to use as registered in the platform manager.

p_err

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. As soon as this function is called, the media will be shown as available to the host. In case you are using a removable media (such as an SD card), you MUST call USBD_MSC_SCSI_LunDetach() once the removable media is removed to mark it as unavailable for the host.

  2. If the LUN has been ejected from the host, calling USBD_MSC_SCSI_LunDetach() and USBD_MSC_SCSI_LunAttach() will make it re-appear.

  3. Use this function with care as ejecting a logical unit in the middle of a transfer may corrupt the file system. The only scenarios where the usage of this function is safe are:

    1. Host: Read, Embedded app: Read

    2. Host: Read, Embedded app: Write

    The following scenarios are not considered safe. Use at your own risk.

    1. Host: Write, Embedded app: Read

    2. Host: Write, Embedded app: Write

USBD_MSC_SCSI_LunDetach()#

Description#

Detach a storage media from a LUN.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

void USBD_MSC_SCSI_LunDetach (CPU_INT08U    class_nbr,
                              CPU_INT08U    lu_nbr,
                              RTOS_ERR     *p_err)

Arguments#

class_nbr

MSC instance number.

lu_nbr

Logical unit number.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. After a call to this function, the media will be available to the embedded application. The standard file API can be used.

  2. Use this function with care as ejecting a logical unit in the middle of a transfer may corrupt the file system. The only scenarios where the usage of this function is considered safe are:

    1. Host: Read, Embedded app: Read

    2. Host: Read, Embedded app: Write

    The following scenarios are not considered safe. Use at your own risk.

    1. Host: Write, Embedded app: Read

    2. Host: Write, Embedded app: Write

USBD_MSC_IsConn()#

Description#

Gets the MSC connection state of the device.

Files#

usbd_msc.h/usbd_msc.c

Prototype#

CPU_BOOLEAN USBD_MSC_IsConn (CPU_INT08U   class_nbr)

Arguments#

class_nbr

MSC instance number.

Returned Value#

  • DEF_YES, if MSC class is connected.

  • DEF_NO, if the MSC class fails to connect.

Notes / Warnings#

None.