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

• USB Host BSP Functions Guide

• USB Host HCD Hardware Information

• USB Host PBHCD Hardware Information

• USB Host Controller Registration to the Platform Manager

USB Host Controller Driver Types#

Micrium OS USB Host provides two different types of drivers:

• Host Controller Drivers (HCD)

• Pipe-Based Host Controller Drivers (PBHCD)

  Table - Description of the Different Types of USB Host Controller Drivers in the USB Host Controller Driver Types page describes each type of USB host controller driver.

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

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

• Clock Configuration

• I/O Configuration

• Interrupt Configuration

• Power Configuration

• Start

• Stop

• Extended BSP API

• ISR Handling

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

  • Dedicated Memory Information Structure

• BSP API Structure

• Host Controller 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#

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#

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#

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#

USB Host PBHCD Hardware Information#

• Hardware Driver Information

  • Hardware Information Structure

  • Dedicated Memory Information Structure

• Endpoint Information Table

• BSP API Structure

• Host Controller 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#

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#

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#

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#

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#

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#

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.