Network Core Hardware Porting Guide#

To work properly, Micrium OS Network module requires a hardware driver that is implemented for any specific Ethernet/WiFi controller IP.

Each network controller that your project will use requires a Board Support Package (BSP). The BSP has two purposes:

• It initializes and configures any resources needed by the network controller, but which are provided by external modules. These include the clock, GPIO, interrupts, etc.

• It provides hardware information to the network controller driver.

Micrium provides example BSPs for several 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 create your own BSP and port the network module to your platform.

• Network Driver Selection Guide

• Network BSP Functions Guide

• Network Hardware Information

• Network Controller Registration to the Platform Manager

Network Driver Selection Guide#

Network Interface Types#

The Network module supports two types of network interfaces: Ethernet and Wi-Fi.

Ethernet#

Typically, MCUs with network capabilities will have an internal Ethernet MAC controller, usually with DMA support. Therefore, only an external PHY controller is needed to implement an Ethernet network interface.

An MCU can have multiple Ethernet controllers, and so depending on the MCU's controllers, multiple drivers could be required (one per controller implementation). For example, if multiple, similar Ethernet controllers are present but with different base addresses, the driver will be the same but with individual configurations.

WiFi#

The Micrium OS network module offers drivers for some external Wi-Fi controllers.

The network stack sends/receives commands and IEEE 802.4 type frames via a serial interface (e.g., SPI) between the MCU and the external Wi-Fi controller. Therefore, it is assumed that the external controller implements the IEEE 802.11 standard and takes care of the encryption/decryption of the wireless data.

Network 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 network controller driver and are meant 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.

A network driver knows the detail of a specific controller IP, such as the registers that it contains and how to properly read and write to them. But what a driver doesn't know is the context in which the controller exists in your hardware solution: what are the I/O and interrupt pins, clock source, etc. The purpose of the BSP is to provide a layer of abstraction between the driver and the context of the controller in your hardware. The functions of a BSP are what is subject to customization, based on how the controller is wired to your board. Each network controller you intend to use will need its own BSP. Each BSP defines the same set of functions that the drivers will call.

Each of these functions is described below according to the network controller type.

• Ethernet Controller

  • Clock Configuration

  • Interrupt Control Configuration

  • GPIO Configuration

  • Get Clock Frequency

• Wi-Fi Controller

  • Start

  • Stop

  • GPIO Configuration

  • Interrupt Configuration

  • Interrupt Control

• ISR Handling

Ethernet Controller#

Clock Configuration#

The clock configuration function is called by the driver during network controller initialization. Listing - Clock Configuration Function Signature in the Network BSP Functions Guide page below shows the signature of this required BSP function.

Listing - Clock Configuration Function Signature#

void  BSP_NetEther_ClkCfg (NET_IF    *p_if,
                           RTOS_ERR  *p_err);

Its purpose is to set the clock(s) for a specific network controller.

This function must configure and enable all clocks required by the controller in order for it to work properly. For example, on some controllers it may be necessary to enable clock gating for an Ethernet MAC, as well as various GPIO modules in order to configure Ethernet PHY pins for (R)MII mode and interrupts.

Interrupt Control Configuration#

The interrupt control configuration function is called by the driver during network controller initialization. Listing - Interrupt Configuration Function Signature in the Network BSP Functions Guide page below shows the signature for this required BSP function.

Listing - Interrupt Configuration Function Signature#

void  BSP_NetEther_CfgIntCtrl  (NET_IF    *p_if,
                                RTOS_ERR  *p_err);

Its purpose is to configure and enable all required interrupt sources for the network controller.

In addition, the function should store the network interface number to be assigned to the controller. This information is available inside the p_if argument passed to the function. It will be needed inside the controller's interrupt service routine to indicate to the TCP/IP stack which network interface the interrupt is associated to (see ISR Handling ).

The function should enable only the interrupt sources for each controller, but not the local controller-level interrupts themselves, which are enabled by the driver only after the network controller has been fully configured and started.

GPIO Configuration#

The GPIO configuration function is called by the driver during network controller initialization. Listing - GPIO Configuration Function Signature in the Network BSP Functions Guide page below shows the signature for this required BSP function.

Listing - GPIO Configuration Function Signature#

void  BSP_NetEther_CfgGPIO  (NET_IF    *p_if,
                             RTOS_ERR  *p_err);

Its purpose is to configure the general-purpose input/output (GPIO) pins for the network controller.

This function should configure all GPIO pins required for the network controller in order for it to work properly. For Ethernet controllers, this function is necessary to configure the (R)MII bus pins, depending on whether the user has configured an Ethernet interface to operate in the RMII or MII mode, and optionally the Ethernet PHY interrupt pin.

Get Clock Frequency#

The Get Clock Frequency function is called by the driver during network controller initialization. Listing - Get Clock Frequency Function Signature in the Network BSP Functions Guide page below shows the signature for this required BSP function.

Listing - Get Clock Frequency Function Signature#

CPU_INT32U  BSP_NetEther_ClkFreqGet  (NET_IF    *p_if,
                                      RTOS_ERR  *p_err);

Its purpose is to return the network controller clock frequency (in Hz).

For Ethernet controllers, this is the clock frequency of the controller’s (R)MII bus. The controller driver initialization process uses the returned clock frequency to configure an appropriate bus divider to ensure that the (R)MII bus logic operates within an allowable range. In general, the controller driver should not configure the divider such that the (R)MII bus operates faster than 2.5MHz.

Wi-Fi Controller#

Start#

The BSP start function is called by the Wi-Fi controller driver each time the Wi-Fi network interface is started. Listing - WiFi Start Function Signature in the Network BSP Functions Guide page below shows the signature for this required BSP function.

Listing - WiFi Start Function Signature#

void BSP_NetWiFi_Start (NET_IF    *p_if,
                        RTOS_ERR  *p_err);

Its purpose is to power up the wireless chip. Therefore, the function must set the required GPIO pins to signal chip power up and reset.

Note that some wireless devices could require toggling the reset pin twice to be started or restarted correctly.

Stop#

The BSP stop function is called by the Wi-Fi controller driver each time the Wi-Fi network interface is stopped. Listing - WiFi Stop Function Signature in the Network BSP Functions Guide page below shows the signature for this required BSP function.

Listing - WiFi Stop Function Signature#

void BSP_NetWiFi_Stop (NET_IF    *p_if,
                       RTOS_ERR  *p_err);

Its purpose is to power down the wireless chip. Therefore, the function must set the required GPIO pins for the chip power down to reduce the power consumption.

GPIO Configuration#

The GPIO configuration function is called by the driver during wireless network controller initialization. Listing - WiFi GPIO Configuration Function Signature in the Network BSP Functions Guide page below shows the signature for this required BSP function.

Listing - WiFi GPIO Configuration Function Signature#

void BSP_NetWiFi_CfgGPIO (NET_IF    *p_if,
                          RTOS_ERR  *p_err);

Its purpose is to configure the general-purpose input/output (GPIO) pins for the network controller. For wireless devices, this function is necessary to configure the power, reset and interrupt pins.

Interrupt Configuration#

The interrupt configuration function is called by the driver during wireless network controller initialization. Listing - WiFi Interrupt Configuration Function Signature in the Network BSP Functions Guide page below shows the signature for this required BSP function.

Listing - WiFi Interrupt Configuration Function Signature#

void BSP_NetWiFi_CfgIntCtrl (NET_IF    *p_if,
                             RTOS_ERR  *p_err);

Its main purpose is to configure and enable all required interrupt sources for the wireless network controller.

In addition, the function should store the network interface number to be assigned to the wireless controller. This information is available inside the p_if argument passed to the function. It will be needed inside the controller's interrupt service routine to indicate to the TCP/IP stack which network interface the interrupt is associated to (see ISR Handling ).

The function should enable only each controller’s interrupt sources, but not the local controller-level interrupts themselves, which are enabled by the driver only after the network controller has been fully configured and started.

Interrupt Control#

The interrupt control function is called by the wireless controller driver while the controller is running. Listing - WiFi Interrupt Controller Function Signature in the Network BSP Functions Guide page below shows the signature for this required BSP function.

Listing - WiFi Interrupt Controller Function Signature#

void BSP_NetWiFi_IntCtrl (NET_IF       *p_if,
                          CPU_BOOLEAN   en,
                          RTOS_ERR     *p_err);

Its purpose is to enable or disable all external interrupt sources for the wireless chip. This means the function will enable or disable its corresponding interrupt source based on the enable argument received.

ISR Handling#

Each network controller driver has an ISR handler function that must be called each time a network controller interrupt is triggered. However, for most platforms, it will be necessary to implement an intermediate ISR handler in the BSP. This is necessary, as some interrupt controllers may require the interrupt status to be cleared each time it is triggered. It is also necessary if your interrupt controller does not support passing an argument to the interrupt vector, as the driver's ISR handler needs to know the network controller/network interface associated with the interrupt.

This BSP ISR will call the function NetIF_ISR_Handler() and pass to it, among others, the network interface number that was previously saved during the BSP Interrupt configuration. It's the NetIF_ISR_Handler() function that will take care of calling the controller driver's ISR handler.

In most cases, each controller requires only a single BSP ISR function. This is possible when the controller’s driver is able to determine the interrupt type via internal controller registers or the interrupt controller. In this case, NetIF_ISR_Handler() must be called with interrupt type code NET_DEV_ISR_TYPE_UNKNOWN. However, some controllers cannot determine the interrupt type when an interrupt occurs and may therefore require multiple, unique BSP ISR function’s, each of which calls NetIF_ISR_Handler() with the appropriate interrupt type code.

Ethernet physical layer (PHY) interrupts should call NetIF_ISR_Handler() with interrupt type code NET_DEV_ISR_TYPE_PHY.

If using a Silicon Labs chip (that follows the CMSIS naming standard), the ISR Handler should be named ETH_IRQHandler().

Listing - ISR Handling Function Signature#

void ETH_IRQHandler (void)
{
    RTOS_ERR err;

    /* TODO: Clear interrupt status, if needed. */

    NetIF_ISR_Handler(BSP_Net_<ctrlr>_IF_Nbr, NET_DEV_ISR_TYPE_UNKNOWN, &err);
}

Network Hardware Information#

• Ethernet Interface

  • BSP API Structure

  • MAC Controller Configuration and Information

  • PHY Controller Configuration and Information

  • Hardware Information

• Wireless Interface

  • WiFi Part Information

  • BSP API Structure

Ethernet Interface#

BSP API Structure#

In order to provide a pointer to the BSP functions for the Ethernet controller driver, you must create a structure of type NETDEV_BSP_ETHER. Each network controller you intend to use will need is own BSP API structure. You must define this in the network controller's BSP file (bsp_net_ether&&&.c).

Table - NET_DEV_BSP_ETHER Structure in the Network Hardware Information page describes each field available in this structure.

Table - NET_DEV_BSP_ETHER Structure#

Listing - Example of BSP API Structure in the Network Hardware Information page shows an example of a BSP API structure.

Listing - Example of BSP API Structure#

static  NET_DEV_BSP_ETHER  BSP_NetEther_<ctrlr>_API_Ptr = {
    .CfgClk     = BSP_NetEther_ClkCfg,
    .CfgIntCtrl = BSP_NetEther_CfgIntCtrl,
    .CfgGPIO    = BSP_NetEther_CfgGPIO,
    .ClkFreqGet = BSP_NetEther_ClkFreqGet
};

MAC Controller Configuration and Information#

The network controller driver requires information about the Ethernet MAC controller(s) (typically on your MCU). You provide this information using a structure of type NET_DEV_CFG_ETHER, and each controller you intend to use will require its own configuration structure.

This structure will hold hardware information as well as more application-specific parameters, all of which are related to the specific Ethernet controller you want to use. This configuration structure is located in the BSP file of the Ethernet Controller (bspnet_ether&&&.c).

Table - NET_DEV_CFG_ETHER Configuration Structure in the Network Hardware Information page describes each configuration field available in this structure.

Table - NET_DEV_CFG_ETHER Configuration Structure#

PHY Controller Configuration and Information#

Information about the PHY controller (typically outside the MCU) is also required by the network controller driver, which you provide using a structure of type NETPHY_CFG_ETHER. This configuration structure is located in the BSP file of the Ethernet Controller (bsp_net_ether&&&.c).

Table - NET_PHY_CFG_ETHER Configuration Structure in the Network Hardware Information page describes each configuration field available in this structure.

Table - NET_PHY_CFG_ETHER Configuration Structure#

Hardware Information#

The last step is to create the main controller hardware information structure. This structure contains only pointers to other structures.

Table - Controller Hardware Information Structure in the Network Hardware Information page describes each configuration field available in this structure.

Table - Controller Hardware Information Structure#

Wireless Interface#

WiFi Part Information#

The Wi-Fi driver requires information about the Wi-Fi controller/part, which you provide using a structure of type NETIF_WIFI_PART_INFO. Each Wi-Fi part has its own information structure. This information can be found in the manual of the Wi-Fi controller. For the Wi-Fi parts that are supported by the Micrium Network module, the information structures are already defined and available in the Wi-Fi driver (net_drv_wifi&&&.c) associated with each WiFi controller.

Table - NET_IF_WIFI_PART_INFO Structure#

BSP API Structure#

In order to provide a pointer to the BSP functions for the Wi-Fi controller driver, you must create a structure of type NETDEV_BSP_WIFI. Each network controller you intend to use will need is own BSP API structure. This is must be defined within the network controller's BSP file (bsp_net_wifi&&&.c).

Table - NET_DEV_BSP_WIFI Structure in the Network Hardware Information page describes each field available in this structure.

Table - NET_DEV_BSP_WIFI Structure#

Network Controller Registration to the Platform Manager#

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

There are two different macros you can call to register a network controller; one for Ethernet controllers and one for Wi-Fi controllers.

Table - Network Controller Register Macros#

Ethernet Controller Registration#

Listing - Example of Ethernet Controller Registration in the Network Controller Registration to the Platform Manager page shows an example of how to register a network Ethernet controller.

Listing - Example of Ethernet Controller Registration#

#include  <rtos_description.h>

#ifdef  RTOS_MODULE_NET_IF_ETHER_AVAIL                             (1)
BSP_HW_INFO_EXT(const  NET_IF_ETHER_CTRLR_INFO, BSP_Ether_<ctrlr0>_Info);
#endif

void  BSP_OS_Init (void)
{

    /* ... */
                                /* --------- REGISTER ETHER CONTROLLER ------- */
#ifdef  RTOS_MODULE_NET_IF_ETHER_AVAIL
    NET_CTRLR_ETHER_REG("eth0", &BSP_Ether_<ctrlr0>_Info);         (2)
#endif
}

(1) Since the global variable for Ethernet controller information is declared in another file, you must declare it as external in your bsp_os.c file. Always use the BSP_HW_INFO_EXT() macro.

(2) Registering an Ethernet controller with the tag "eth0". The tag will be used later on when calling the NetIF_Ether_Add() function.

Wi-Fi Controller Registration#

Listing - Example of WiFi Controller Registration in the Network Controller Registration to the Platform Manager page shows an example of how to register an external network Wi-Fi controller that is connected to the MCU via an SPI bus.

Listing - Example of WiFi Controller Registration#

#include  <rtos_description.h>

#if defined(RTOS_MODULE_IO_SERIAL_AVAIL)                           (1)
BSP_HW_INFO_EXT(const  SERIAL_CTRLR_DRV_INFO,    BSP_Serial_SPI_HwInfo_<bus>__DrvInfo);
#endif
#if defined(RTOS_MODULE_NET_IF_WIFI_AVAIL)
BSP_HW_INFO_EXT(const  NET_IF_WIFI_PART_INFO,    NetWiFi_Info_<ctrlr>);
BSP_HW_INFO_EXT(const  NET_DEV_BSP_WIFI,         BSP_NetWiFi_<ctrlr>_BSP_API);
#endif

void  BSP_OS_Init (void)
{

    /* ... */
                                                                /* ------ REGISTER SPI & WiFi CONTROLLER ----- */
#if defined(RTOS_MODULE_IO_SERIAL_AVAIL)
    IO_SERIAL_CTRLR_REG("spi0",                                    (2)
                        &BSP_Serial_SPI_HwInfo_<bus>__DrvInfo);
#endif

#if defined(RTOS_MODULE_NET_IF_WIFI_AVAIL)
    NET_CTRLR_WIFI_SPI_REG("wifi0",                                (3)
                           "spi0",
                           &NetWiFi_Info_<ctrlr>,
                           &BSP_NetWiFi_<ctrlr>_BSP_API,
                            0u);
#endif
}

(1) Since the global variables for the Wi-Fi controller information are declared in another file, you must declare them as external in your bsp_os.c file. Always use the BSP_HW_INFO_EXT() macro.

(2) Registering the SPI Bus used by the Wi-Fi controller with the appropriate tag. The tag will be used later on when calling the SPI_BusAdd() function.

(3) Registering a Wi-Fi controller with the tag "wifi0". The tag will be used later on when calling the NetIF_WiFi_Add() function.