USB Host Hardware Porting Guide#

In order to work properly, Micrium OS USB Host requires a hardware driver that is implemented for any specific USB host controller IP. Moreover, each USB host controller must have a Board Support Package (BSP). The BSP has two purposes:

  • initializing and configuring any resources needed by the USB controller, but which are provided by an external module,

  • and providing hardware information to the USB host driver and core.

Micrium provides examples of BSPs for some popular platforms. If one is available for your platform, we recommend that you use it as a starting point. However, if no example BSP is available for your platform, the information in this section will help you understand how to correctly port the USB device module.

Note that each USB host controller (that you are planning to use) will require a BSP, and all the steps described in this section must be performed for each of them.

USB Host Controller Driver Types#

Micrium OS USB Host provides two different types of drivers:

Table - Description of the Different Types of USB Host Controller Drivers#

Type

Description

HCD

The HCD type targets complete controllers that are list-based and handle periodic transfers. Only the OHCI and EHCI drivers are of type HCD.

PBHCD

The PBHCD type is for simple controllers that have a limited set of Pipes (used as endpoints). They are not list-based. These controllers assume that transfer scheduling and other tasks are handled by the software. These drivers require an optional module called PBHCI (Pipe-Based Host Controller Interface).

USB Host BSP Functions Guide#

The Board Support Package contains a set of functions that support your hardware platform on Micrium OS. These functions are called by the USB host driver to perform hardware configuration or initialization of I/O pins, interrupts, etc. It is your responsibility to either create these functions from scratch or to modify example code to fit your needs and the specifics of your hardware.

Each of these functions is described below.

Initialize#

The Initialize function is called by the driver only once at initialization. Depending on whether you have an HCD or a PBHCD, the function will have a slightly different signature. Listing - Init function for a HCD in the USB Host BSP Functions Guide page and Listing - Init function for a PBHCD in the USB Host BSP Functions Guide page show the signatures of the functions.

Listing - Init function for a HCD#
CPU_BOOLEAN  BSP_USBH_EFM32GG_Init (USBH_HCD_ISR_HANDLE_FNCT   isr_fnct,
                                     USBH_HC_DRV               *p_hc_drv);
Listing - Init function for a PBHCD#
CPU_BOOLEAN  BSP_USBH_EFM32GG_Init (USBH_PBHCD_ISR_HANDLE_FNCT   isr_fnct,
                                    USBH_PBHCI_HC_DRV           *p_pbhci_hc_drv);

Its purpose is to initialize and allocate any resource needed by the USB controller BSP.

The initialize function receives two arguments: isr_fnct and p_hc_drv (or p_pbhci_hc_drv, if your driver is a PBHCD), which are used when handling interrupts from the USB host controller. The argument isr_fnct is a pointer to a driver function that is called when a USB interrupt occurs, and this driver function takes p_hc_drv (or p_pbhci_hc_drv, if your driver is a PBHCD) as an argument. So it is important to save these as global variables in your BSP.

You must return DEF_OK from this function if it executed successfully, or DEF_FAIL, otherwise.

Clock Configuration#

The Clock Configuration function is called by the driver when the USB host controller is started. Listing - Clock configure function signature in the USB Host BSP Functions Guide page shows the signature of the function.

Listing - Clock configure function signature#
CPU_BOOLEAN  BSP_USBH_EFM32GG_ClkCfg (void);

Its purpose is to configure the clock of the USB host controller.

You must return DEF_OK from this function if it executed successfully, or DEF_FAIL, otherwise.

I/O Configuration#

The I/O Configuration function is called by the driver when the USB host controller is started. Listing - IO configure function signature in the USB Host BSP Functions Guide page shows the signature of the function.

Listing - IO configure function signature#
CPU_BOOLEAN  BSP_USBH_EFM32GG_IO_Cfg (void);

Its purpose is to configure the I/O pins for the USB host controller.

You must return DEF_OK from this function if it executed successfully, or DEF_FAIL, otherwise.

Interrupt Configuration#

The Interrupt Configuration function is called by the driver when the USB host controller is started. Listing - Interrupt configure function signature in the USB Host BSP Functions Guide page shows the signature of the function.

Listing - Interrupt configure function signature#
CPU_BOOLEAN  BSP_USBH_EFM32GG_IntCfg (void);

Its purpose is to configure the interrupt(s) of the USB host controller.

You must return DEF_OK from this function if it executed successfully, or DEF_FAIL, otherwise.

Power Configuration#

The Power Configuration function is called by the driver when the USB host controller is started. Listing - Power configure function signature in the USB Host BSP Functions Guide page shows the signature of the function.

Listing - Power configure function signature#
CPU_BOOLEAN  BSP_USBH_EFM32GG_PwrCfg (void);

Its purpose is to configure the power of the USB host controller.

You must return DEF_OK from this function if it executed successfully, or DEF_FAIL, otherwise.

Start#

The Start function is called by the driver each time the USB host controller is started. It is always called after all the "configure" functions. Listing - Start function signature in the USB Host BSP Functions Guide page shows the signature of the function.

Listing - Start function signature#
CPU_BOOLEAN  BSP_USBH_EFM32GG_Start (void);

Its main purpose is to perform any operation required when the USB controller is started.

You must return DEF_OK from this function if it executed successfully, or DEF_FAIL, otherwise.

Stop#

The Stop function is called by the driver when the USB host controller is stopped. Listing - Stop function signature in the USB Host BSP Functions Guide page shows the signature of the function.

Listing - Stop function signature#
CPU_BOOLEAN  BSP_USBH_EFM32GG_Stop (void);

Its purpose is to perform any operation required when the USB controller is stopped.

You must return DEF_OK from this function if it executed successfully, or DEF_FAIL, otherwise.

Extended BSP API#

The BSP for the PBHCD may require extended features from the BSP. These features, if required, are specific to each driver.

ISR Handling#

Each USB host driver implements an ISR handler function, which is called each time a USB host interrupt is triggered. For most platforms, it will be necessary to implement an intermediate ISR handler in the BSP, which in turn will call the driver's ISR handler. This is necessary because some interrupt controllers may require the interrupt status to be cleared each time it is triggered.

An intermediate ISR handler is also necessary if your interrupt controller does not pass an argument to the interrupt vector, as the driver's ISR handler takes p_hc_drv (or p_pbhci_hc_drv), which was received in the Init() function of the BSP, as an argument.

Listing - Example of BSP ISR implementation in the USB Host BSP Functions Guide page shows an example of an ISR handler implemented in the BSP (that follows the CMSIS naming convention).

Listing - Example of BSP ISR implementation#
void USB_IRQHandler (void)
{
    /* TODO: Clear interrupt status, if needed. */

    OSIntEnter();
    BSP_USBH_EFM32GG_ISR_Fnct(BSP_USBH_EFM32GG_DrvPtr);                 (1)
    OSIntExit();
}

(1) Here, the driver's ISR is called. Note that the global variable BSP_USBH_EFM32GG_ISR_Fnct is a copy of the isr_fnct argument and the global variable BSP_USBH_EFM32GG_DrvPtr is a copy of the p_hc_drv (or p_pbhci_hc_drv, if your driver is a PBHCD) argument received from the BSP's Init() function.

USB Host HCD Hardware Information#

Hardware Driver Information#

Hardware Information Structure#

The USB host driver requires specific information about the USB controller on your MCU. You provide this information using a structure of type USBH_HC_HW_INFO.

The information describing the USB host controller can be found in the manual of your MCU.

Table - USBH_HC_HW_INFO structure in the USB Host HCD Hardware Information page describes each configuration field available in this structure.

Table - USBH_HC_HW_INFO structure#

Field

Description

.BaseAddr

Base address of the USB host controller registers set. This corresponds to the address of the first register.

.RH_Spd

Maximum speed of operation your USB host controller can support. This depends on your host controller capabilities and on how the controller is set up in your BSP. For example, a High-Speed capable USB host controller can be set to operate at Full-Speed in order to supply a slower clock. Possible values are: - USBH_DEV_SPD_FULL - USBH_DEV_SPD_HIGH

.HC_Type

Type of host controller. Possible values are:

Value

Description

USBH_HC_TYPE_LIST

List-based controller. The controller uses a driver of type HCD. Only OHCI- and EHCI-based controllers fall into this category.

USBH_HC_TYPE_PIPE

Pipe-based controller. The controller uses a driver of type PBHCD.

.HW_DescDedicatedMemInfoPtr

Pointer to a structure of type USBH_HC_DEDICATED_MEM_INFO. Describes the dedicated memory to use for the hardware descriptor. Most of the time, this configuration is optional. Set this to DEF_NULL if not used.

.DataBufDedicatedMemInfoPtr

Pointer to a structure of type USBH_HC_DEDICATED_MEM_INFO. Describes the dedicated memory to use for the data buffers. Most of the time, this configuration is optional. Set this to DEF_NULL if not used.

Dedicated Memory Information Structure#

When using a dedicated memory region for either the hardware descriptors or the data buffers, or both, a structure of type USBH_HC_DEDICATED_MEM_INFO must be used.

Table - USBH_HC_DEDICATED_MEM_INFO structure in the USB Host HCD Hardware Information page describes each configuration field available in this structure.

Table - USBH_HC_DEDICATED_MEM_INFO structure#

Field

Description

.MemSegPtr

Pointer to the memory segment in dedicated memory. See Memory Segments and LIB Heap for more information on the memory segments.

.BufAlignOctets

Minimum alignment, in octets.

BSP API Structure#

In order to provide a pointer to the BSP functions that you created (that are described here: USB Host BSP Functions Guide ) for the USB host controller driver, you have to create a structure of type USBH_HC_BSP_API.

Table - USBH_HC_BSP_API structure in the USB Host HCD Hardware Information page describes each field available in this structure.

Table - USBH_HC_BSP_API structure#

Field

Description

.Init

Pointer to the BSP initialization function.

.ClkCfg

Pointer to the BSP clock configure function.

.IO_Cfg

Pointer to the BSP IO configure function.

.IntCfg

Pointer to the BSP interrupt configure function.

.PwrCfg

Pointer to the BSP power configure function.

.Start

Pointer to the BSP start function.

.Stop

Pointer to the BSP stop function.

Listing - Example of BSP API structure in the USB Host HCD Hardware Information page gives an example of a BSP API structure.

Listing - Example of BSP API structure#
static USBH_PBHCI_BSP_API BSP_USBH_EFM32GG_BSP_API_Ptr = {
  BSP_USBH_EFM32GG_Init,
  BSP_USBH_EFM32GG_ClkCfg,
  BSP_USBH_EFM32GG_IO_Cfg,
  BSP_USBH_EFM32GG_IntCfg,
  BSP_USBH_EFM32GG_PwrCfg,
  BSP_USBH_EFM32GG_Start,
  BSP_USBH_EFM32GG_Stop,
  DEF_NULL
};

Host Controller Hardware Information#

The last step is to create the main host hardware information structure.

Table - USBH_HC_HCD_HW_INFO structure in the USB Host HCD Hardware Information page describes each configuration field available in this structure.

Table - USBH_HC_HCD_HW_INFO structure#

Field

Description

.HW_Info

Hardware information structure described at step Hardware Driver Information above.

.DrvAPI_Ptr

Pointer to the driver API structure that you are using with your driver. Some drivers may provide more than one API structure.

.RH_API_Ptr

Pointer to the driver root hub API structure that you are using with your driver. Some drivers may provide more than one root hub API structure.

.BSP_API_Ptr

Pointer to the BSP API structure you created at step BSP API Structure .

USB Host PBHCD Hardware Information#

Hardware Driver Information#

Hardware Information Structure#

The USB host driver requires specific information about the USB controller on your MCU. You provide this information using a structure of type USBH_HC_HW_INFO.

The information describing the USB host controller can be found in the manual of your MCU.

Table - USBH_HC_HW_INFO structure in the USB Host PBHCD Hardware Information page describes each configuration field available in this structure.

Table - USBH_HC_HW_INFO structure#

Field

Description

.BaseAddr

Base address of the USB host controller registers set. This corresponds to the address of the first register.

.RH_Spd

Maximum speed of operation your USB host controller can support. This depends on your host controller capabilities and on how the controller is set up in your BSP. For example, a High-Speed capable USB host controller can be set to operate at Full-Speed in order to supply a slower clock. Possible values are: - USBH_DEV_SPD_FULL - USBH_DEV_SPD_HIGH

.HC_Type

Type of host controller. Possible values are:

Value

Description

USBH_HC_TYPE_LIST

List-based controller. The controller uses a driver of type HCD. Only OHCI- and EHCI-based controllers fall into this category.

USBH_HC_TYPE_PIPE

Pipe-based controller. The controller uses a driver of type PBHCD.

.HW_DescDedicatedMemInfoPtr

Pointer to a structure of type USBH_HC_DEDICATED_MEM_INFO. Describes the dedicated memory to use for the hardware descriptor. Most of the time, this configuration is optional. Set this to DEF_NULL if not used.

.DataBufDedicatedMemInfoPtr

Pointer to a structure of type USBH_HC_DEDICATED_MEM_INFO. Describes the dedicated memory to use for the data buffers. Most of the time, this configuration is optional. Set this to DEF_NULL if not used.

Dedicated Memory Information Structure#

When using a dedicated memory region for either the hardware descriptors or the data buffers, or both, a structure of type USBH_HC_DEDICATED_MEM_INFO must be used.

Table - USBH_HC_DEDICATED_MEM_INFO structure in the USB Host PBHCD Hardware Information page describes each configuration field available in this structure.

Table - USBH_HC_DEDICATED_MEM_INFO structure#

Field

Description

.MemSegPtr

Pointer to the memory segment in dedicated memory. See Memory Segments and LIB Heap for more information on the memory segments.

.BufAlignOctets

Minimum alignment, in octets.

Endpoint Information Table#

Your USB host controller offers a set of pipes (used as endpoints) that are available to the USB host software. The Micrium OS USB Host module requires you to have information about these available pipes. The way to provide this information is by using a table of elements of types USBH_PBHCI_PIPE_INFO. The first element of the table must always be the default control pipe.

Note that the last element of the table must be a null entry.

The information regarding the pipes of your USB host controller can be found in the manual of your MCU.

Table - USBH_PBHCI_PIPE_INFO structure in the USB Host PBHCD Hardware Information page describes each configuration field available in this structure.

Table - USBH_PBHCI_PIPE_INFO structure#

Field

Description

.Attrib

This is a bitmap that represents the different endpoint types and directions that this pipe can support. Possible values of the bitmap are:

Value

Description

USBH_PIPE_INFO_TYPE_CTRL

Pipe supports transfers of type Control.

USBH_PIPE_INFO_TYPE_BULK

Pipe supports transfers of type Bulk.

USBH_PIPE_INFO_TYPE_INTR

Pipe supports transfers of type Interrupt.

USBH_PIPE_INFO_TYPE_ISOC

Pipe supports transfers of type Isochronous.

USBH_PIPE_INFO_DIR_OUT

Pipe supports OUT (host-to-device) transfers.

Special values:

Value

Description

USBH_PIPE_INFO_TYPE_ALL

Pipe supports all transfer types.

USBH_PIPE_INFO_DIR_BOTH

Pipe supports both IN and OUT transfers.

.Nbr

Pipe number.

.MaxPktSize

Maximum packet size (in octets) this pipe supports.

.MaxBuFlen

Maximum transfer buffer length (in octets) this pipe supports.

Listing - Example of pipe description table in the USB Host PBHCD Hardware Information page gives an example of a pipe information table. In this case, the controller has 12 bi-directional pipes. All but one are capable of all transfer types, the other one is the default control pipe. Also, note the null entry at the end of the table.

Listing - Example of pipe description table#
USBH_PBHCI_PIPE_INFO BSP_USBH_EFM32GG_PipeInfoTbl[] =
{
  { USBH_PIPE_INFO_TYPE_CTRL                                                       | USBH_PIPE_INFO_DIR_BOTH, 0u, 64u, 0u },
  { USBH_PIPE_INFO_TYPE_CTRL | USBH_PIPE_INFO_TYPE_BULK | USBH_PIPE_INFO_TYPE_INTR | USBH_PIPE_INFO_DIR_BOTH, 1u, 512u, 0u },
  { USBH_PIPE_INFO_TYPE_CTRL | USBH_PIPE_INFO_TYPE_BULK | USBH_PIPE_INFO_TYPE_INTR | USBH_PIPE_INFO_DIR_BOTH, 2u, 512u, 0u },
  { USBH_PIPE_INFO_TYPE_CTRL | USBH_PIPE_INFO_TYPE_BULK | USBH_PIPE_INFO_TYPE_INTR | USBH_PIPE_INFO_DIR_BOTH, 3u, 512u, 0u },
  { USBH_PIPE_INFO_TYPE_CTRL | USBH_PIPE_INFO_TYPE_BULK | USBH_PIPE_INFO_TYPE_INTR | USBH_PIPE_INFO_DIR_BOTH, 4u, 512u, 0u },
  { USBH_PIPE_INFO_TYPE_CTRL | USBH_PIPE_INFO_TYPE_BULK | USBH_PIPE_INFO_TYPE_INTR | USBH_PIPE_INFO_DIR_BOTH, 5u, 512u, 0u },
  { DEF_BIT_NONE, 0u, 0u, 0u }
};

BSP API Structure#

In order to provide a pointer to the BSP functions you created (that are described here: USB Host BSP Functions Guide ) to the USB host controller driver, you have to create a structure of type USBH_PBHCI_BSP_API.

Table - USBH_PBHCI_BSP_API structure in the USB Host PBHCD Hardware Information page describes each field available in this structure.

Table - USBH_PBHCI_BSP_API structure#

Field

Description

.Init

Pointer to the BSP initialization function.

.ClkCfg

Pointer to the BSP clock configure function.

.IO_Cfg

Pointer to the BSP IO configure function.

.IntCfg

Pointer to the BSP interrupt configure function.

.PwrCfg

Pointer to the BSP power configure function.

.Start

Pointer to the BSP start function.

.Stop

Pointer to the BSP stop function.

.ExtBSP_API

Pointer to optional driver specific extended BSP API. Can be set to DEF_NULL.

Listing - Example of BSP API structure in the USB Host PBHCD Hardware Information page gives an example of a BSP API structure.

Listing - Example of BSP API structure#
static USBH_PBHCI_BSP_API BSP_USBH_EFM32GG_BSP_API_Ptr = {
  BSP_USBH_EFM32GG_STK3700A_Init,
  BSP_USBH_EFM32GG_STK3700A_ClkCfg,
  BSP_USBH_EFM32GG_STK3700A_IO_Cfg,
  BSP_USBH_EFM32GG_STK3700A_IntCfg,
  BSP_USBH_EFM32GG_STK3700A_PwrCfg,
  BSP_USBH_EFM32GG_STK3700A_Start,
  BSP_USBH_EFM32GG_STK3700A_Stop,
  DEF_NULL
};

Host Controller Hardware Information#

The last step is to create the main host hardware information structure.

Table - USBH_PBHCI_HC_HW_INFO structure in the USB Host PBHCD Hardware Information page describes each configuration field available in this structure.

Table - USBH_PBHCI_HC_HW_INFO structure#

Field

Description

.HW_Info

Hardware information structure described at step Hardware driver information .

.DrvAPI_Ptr

Pointer to the driver API structure you are using with your driver. Some drivers may provide more than one API structure.

.BSP_API_Ptr

Pointer to the BSP API structure you created at step BSP API Structure .

.PipeInfoTblPtr

Pointer to the table you created at step Endpoint information table .

USB Host Controller Registration to the Platform Manager#

Once the hardware information structure for your USB host controller is ready, it must be registered to the Platform Manager. This should normally be done from the BSP_OS_Init() function that is located in the file bsp_os.c.

There exist three different macros located in the file usb_ctrlr.h you can call to register a USB Host controller. Table - USB Host Controller Register Macros in the USB Host Controller Registration to the Platform Manager page describes the different macros.

Table - USB Host Controller Register Macros#

Macro

Description

USB_CTRLR_HW_INFO_REG()

Registers hardware information for a USB controller that has both Device and Host functionalities. Refer to USB Device Hardware Porting Guide for more information on the device side.

USB_CTRLR_HW_INFO_HOST_ONLY_REG()

Registers hardware information for a USB host controller.

USB_CTRLR_HW_INFO_HOST_COMPANION_REG()

Registers hardware information for a USB host companion controller.

Listing - Example of USB Controller Registration in the USB Host Controller Registration to the Platform Manager page gives an example of how to register a USB Host controller.

Listing - Example of USB Controller Registration#
#if defined(RTOS_MODULE_USB_HOST_AVAIL) && defined (RTOS_MODULE_USB_HOST_PBHCI_AVAIL)    (1)
BSP_HW_INFO_EXT(const USBH_PBHCI_HC_HW_INFO, BSP_USBH_EFM32_PBHCI_HW_Info);
#endif

#if defined(RTOS_MODULE_USB_DEV_AVAIL)
BSP_HW_INFO_EXT(const USBD_DEV_CTRLR_HW_INFO, BSP_USBD_EFM32_HwInfo);
#endif

void  BSP_OS_Init (void)
{

    /* ... */
                                                /* ------------- REGISTER USB CONTROLLERS ------------- */
    USB_CTRLR_HW_INFO_REG("usb0",                                  (2)
                          &BSP_USBD_EFM32_HwInfo,
                          &BSP_USBH_EFM32_PBHCI_HW_Info);
}

(1) Since the hardware information global variables are declared in another file, you have to declare them as external in your bsp_os.c file. Always use the BSP_HW_INFO_EXT() macro.

(2) Registering a USB controller that implements both host and device functionalities. The controller name is "usb0". The tag will be used later on when calling the USBD_DevAdd() and/or USBH_HC_Add() function.