Network Core Start-Up#

This page provides a summary of the steps necessary to initialize the network core, and to start a network interface. Theses steps are discussed in more detail on pages in this section.

Steps 1 and 3 each provide two different options. One method uses predefined configurations and gets the interface started easily; the other offers more flexibility but requires additional API calls.

Initialize the Network Core Module#

There are two ways you can initialize the network core module :

• Call Net_Init() directly without modifying the default configuration.

• Modify the configuration before calling Net_Init().

Add a Network Interface#

To add a network interface , you must specify a string identifier such as "eth0" or "wifi0" using the appropriate Add Network function. This identifier must be registered with the Platform Manager using BSP_OS_Init().

• For Ethernet devices: The device configuration structure needed for adding the interface is defined in the device's BSP file (e.g., bsp_net_ether_xx.c).

• For Wi-Fi devices: The device configuration structure needed for adding the interface is pre-configured in the device driver. The only configuration you need to pass to the NetIF_WiFi_Add() function is the NET_IF_BUF_CFG buffer configuration structure.

Start the Network Interface#

The network interface can be started in one of two ways:

• Start the network interface with a configuration. To do so, call NetIF_xxx_Start() with a correctly-populated NET_IF_XXX_CFG structure in its second parameter. This starts the interface with a properly-configured local IP address, and/or with a DHCP Client process (the IP address will, therefore, be assigned shortly after interface start), and optionally the Link-local address assignment feature.

• Start the network interface without a configuration. To do so, call NetIF_xxx_Start() with DEF_NULL in its second parameter. Doing so will start the network interface immediately, but you will have to set up the interface manually (the local IP address, DHCP Client, IPv6 Auto Config, and Link-local address enabling) by calling the appropriate API functions.

The following sub-sections cover each of these steps in more detail.

Initializing the Network Core Module#

This section describes the basic steps required to initialize the Network core module.

• Initializing the Network Core Module Using the Default Configuration

• Initializing the Network Core Module Using Optional Configuration

  • Override Using a Specific Function Call

  • Override Using Advanced Configuration

To initialize the Network core module, you call the function Net_Init(). This function initializes and allocates memory for the different layers of the TCP/IP core, as well as for the DHCP client module and the DNS client module, which are also part of the Network Core.

The initialization can be performed in one of two ways:

• Using the default configuration

• Using optional configuration

Initializing the Network Core Module Using the Default Configuration#

This initialization method uses the configuration values from the structure Net_InitCfgDflt. Using this method will be appropriate unless you have a specific need to override any of the default configuration values.

Listing - Example of call to Net_Init()#

RTOS_ERR  err;

Net_Init(&err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}

Initializing the Network Core Module Using Optional Configuration#

This initialization method overrides the default configuration values. There are two options:

Option 1 - Override Using a Specific Function Call#

Suppose you needed the network core task to have a different size than the default value. In this case, you would use the Net_ConfigureCoreTaskStk() function to alter the configuration prior to calling Net_Init().

Here is an example of how this is done.

Listing - Example of call to Net_Init()#

CPU_STK_SIZE   stk_size   = Net_InitCfgDflt.CoreStkSizeElements;
void          *p_stk_base = Net_InitCfgDflt.CoreStkPtr;
RTOS_ERR       err;

stk_size = 1024u;                            /* Modify only what is needed          */
Net_ConfigureCoreTaskStk(stk_size, p_stk_base);  /* Set the new Core Task configuration values */

Net_Init(&err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}

Option 2 - Override Using Advanced Configuration#

To use this approach, the advanced configuration flag must be enabled in the OS.

Listing - rtos_cfg.h#

#define RTOS_CFG_EXTERNALIZE_OPTIONAL_CFG DEF_ENABLED

When this is enabled, the structure Net_InitCfg must be defined somewhere in the application. The example below shows Net_InitCfg defined in full using the default values.

Listing - Example of advanced configuration#

RTOS_ERR  err;

const  NET_INIT_CFG  Net_InitCfg = {
        .DNSc_Cfg = {
                .HostNameLenMax     = 255u,
                .CacheEntriesMaxNbr = 6u,
                .AddrIPv4MaxPerHost = 3u,
                .AddrIPv6MaxPerHost = 3u,
                .TaskDly_ms         = 50u,
                .ReqRetryNbrMax     = 2u,
                .ReqRetryTimeout_ms = 1000u
         },
        .CoreStkSizeElements = 512u,
        .CoreStkPtr          = DEF_NULL,
        .SrvStkSizeElements  = 512u,
        .SrvStkPtr           = DEF_NULL,
        .MemSegPtr           = DEF_NULL
};

Net_Init(&err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}

Adding a Network Interface#

The Network module offers two types of network interfaces: Ethernet and Wi-Fi. Each interface type has its own Add function.

Once the network core module has been initialized successfully, you can start adding your network interface(s) with the NetIF_Ether_Add() function (for Ethernet interfaces) and the NetIF_WiFi_Add() function (for Wi-Fi interfaces). You must add each network interface you want to use in your application using one of those two functions.

The Add functions require an ID string argument: for example, "eth0". This ID string is the same string that was used in the BSP_OS_Init() function earlier when the network interface was registered. See section Network Core Hardware Porting Guide for more details.

Ethernet Interface#

Listing - Example of call to NetIF_Ether_Add() in the Adding a Network Interface page shows an example of call to NetIF_Ether_Add() using the default arguments.

Listing - Example of call to NetIF_Ether_Add()#

NET_IF_NBR      if_nbr;
RTOS_ERR        err;

#ifdef  NET_IF_ETHER_MODULE_EN
                                                      /* -------------- ADD ETHERNET INTERFACE -------------- */
if_nbr = NetIF_Ether_Add("eth0", DEF_NULL, DEF_NULL, &err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occured. Error handling should be added here. */
}
#endif

The structure NET_DEV_CFG_ETHER includes configuration parameters such as the number of network buffers and memory locations. You can modify these parameters as you see fit, according to your application's needs. This structure is defined in the BSP of the network controller and is passed when the network interface is registered via the BSP_OS_Init() function. For more details on the NET_DEV_CFG_ETHER structure, refer to Network Interface Controller Configuration , and for more details on the registration process of the network interface(s), refer to Network Controller Registration to the Platform Manager .

Wi-Fi Interface#

Listing - Example of call to NetIF_WiFi_Add() in the Adding a Network Interface page shows an example of a call to NetIF_WiFi_Add() using the default arguments.

In contrast to the Ethernet interface, the Wi-Fi interface has an additional configuration argument of type NET_IF_BUF_CFG. This configuration structure contains network buffer parameters. For more details on configuring arguments to pass to NetIF_WiFi_Add(), see Network Interface Controller Configuration .

Listing - Example of call to NetIF_WiFi_Add()#

static  const  NET_IF_BUF_CFG Ex_NetWiFi_IF_BufCfg = {
        .RxBufLargeNbr  = 10u,
        .TxBufLargeNbr  = 8u,
        .TxBufSmallNbr  = 4u,
        .BufAlignOctets = LIB_MEM_BUF_ALIGN_AUTO,
        .BufPoolType    = NET_IF_MEM_TYPE_MAIN,
        .MemAddr        = 0x0,
        .MemSize        = 0x0
};

NET_IF_NBR      if_nbr;
RTOS_ERR        err;

#ifdef  NET_IF_WIFI_MODULE_EN
                                                      /* -------------- ADD WIRELESS INTERFACE -------------- */
if_nbr = NetIF_WiFi_Add("wifi0",
                        &Ex_NetWiFi_IF_BufCfg,
                         DEF_NULL,
                         DEF_NULL,
                        &err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}
#endif

Lookback Interface#

Also, a virtual Loopback network interface can be added automatically if the #define configuration NET_IF_CFG_LOOPBACK_EN is enabled (see Network Core Compile-Time Configurations ).

Starting a Network Interface#

• Starting the Network Interface

  • Ethernet Interface

  • Wi-Fi Interface

  • Network Interface Ready

• Starting the Network Interface Without a Configuration

The last step in making your network interface active on the network is to start it. Similar to the Add function, each type of network interface has its own Start function.

Each Start function has an optional argument for a setup structure that includes parameters for IPv4, IPv6, DHCP and other interface-specific parameters. This allows your application to define and populate a setup structure with parameters that match your network's characteristics and your application's needs. Including the argument causes the Network Core Stack to perform the minimal setup required for the interface to be visible on the network. For more details on the network interface setup structure, see Network Interface Start Setup .

The sections below show how to start a network interface according to its type; either Ethernet of Wi-Fi.

Starting the Network Interface#

Ethernet Interface#

Listing - Example of call to NetIF_Ether_Start() in the Starting a Network Interface page shows an example of call to NetIF_Ether_Start().

For more information on configuring arguments to pass to NetIF_Ether_Start(), see Network Interface Start Setup .

For a complete example on how to start an Ethernet interface, see the example files.

Listing - Example of call to NetIF_Ether_Start()#

static  const  NET_IF_ETHER_CFG  Ex_NetIF_CfgDflt = {
        .HW_AddrStr                    = "00:17:4A:B0:00:01",
        .IPv4.Static.Addr              = DEF_NULL,
        .IPv4.Static.Mask              = DEF_NULL,
        .IPv4.Static.Gateway           = DEF_NULL,
        .IPv4.DHCPc.En                 = DEF_YES,
        .IPv4.DHCPc.Cfg                = DHCPc_CFG_DFLT,
        .IPv4.DHCPc.OnCompleteHook     = Ex_DHCPc_SetupResult,
        .IPv4.LinkLocal.En             = DEF_NO,
        .IPv4.LinkLocal.OnCompleteHook = DEF_NULL,
        .IPv6.Static.Addr              = DEF_NULL,
        .IPv6.Static.PrefixLen         = 0,
        .IPv6.Static.DAD_En            = DEF_NO,
        .IPv6.AutoCfg.En               = DEF_YES,
        .IPv6.AutoCfg.DAD_En           = DEF_YES,
        .IPv6.Hook                     = Ex_IPv6_AddrCfgResult
};

NET_IF_ETHER_CFG  if_cfg;
NET_IF_NBR        if_nbr;
RTOS_ERR          err;

if_cfg = Ex_NetIF_CfgDflt;

                                                       /* ------------- START ETHERNET INTERFACE ------------- */
NetIF_Ether_Start(if_nbr, &if_cfg, &err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occured. Error handling should be added here. */
}

Wi-Fi Interface#

Listing - Example of call to NetIF_WiFi_Start() in the Starting a Network Interface page shows an example of call to NetIF_WiFi_Start().

For more information on configuring arguments to pass to NetIF_WiFi_Start(), see Network Interface Start Setup .

For a complete example on how to start a Wi-Fi Interface, see the example files.

Listing - Example of call to NetIF_WiFi_Start()#

static  const  NET_IF_WiFi_CFG  Ex_NetIF_CfgDflt = {
        .HW_AddrStr                    = "00:17:4A:B0:00:01",
        .IPv4.Static.Addr              = DEF_NULL,
        .IPv4.Static.Mask              = DEF_NULL,
        .IPv4.Static.Gateway           = DEF_NULL,
        .IPv4.DHCPc.En                 = DEF_YES,
        .IPv4.DHCPc.Cfg                = DHCPc_CFG_DFLT,
        .IPv4.DHCPc.OnCompleteHook     = Ex_DHCPc_SetupResult,
        .IPv4.LinkLocal.En             = DEF_NO,
        .IPv4.LinkLocal.OnCompleteHook = DEF_NULL,
        .IPv6.Static.Addr              = DEF_NULL,
        .IPv6.Static.PrefixLen         = 0,
        .IPv6.Static.DAD_En            = DEF_NO,
        .IPv6.AutoCfg.En               = DEF_YES,
        .IPv6.AutoCfg.DAD_En           = DEF_YES,
        .IPv6.Hook                     = Ex_IPv6_AddrCfgResult,
        .Band                          = NET_DEV_BAND_2_4_GHZ
};

NET_IF_WIFI_CFG  if_cfg;
NET_IF_NBR       if_nbr;
RTOS_ERR         err;

if_cfg = Ex_NetIF_CfgDflt;

                                                      /* ------------- START WIRELESS INTERFACE ------------- */
NetIF_WiFi_Start(if_nbr, &if_cfg, &err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}

Network Interface Ready#

Because the network interface start function doesn't block, other mechanisms exist to let your application know when the setup of the interface is complete. You can use the different callback functions (DHCP, IPv6, IPv4. Link-Local) inside the NET_IF_xxx_CFG structure you are passing to the interface start function. You can use those callbacks to notify your application when a specific setup process has finished. They will also give you information on the process that just completed: for example, the status of the process, the IP address that was just configured, etc.

Micrium OS also includes a module to that allows your application to wait for the network interface setup to be complete. To enable this module, you must enable the NET_IF_CFG_WAIT_SETUP_READY_EN configuration in your net_cfg.h file (see section Network Core Compile-Time Configurations ). So once the network interface is started, your application can begin waiting for the setup to be complete by using the API function NetIF_WaitSetupReady(). This function will wait for the various processes that you enabled in the NET_IF_xxx_CFG argument (DHCP, IPv6, etc.), and it will exit when every process has finished, if no error occurred. You can also pass a reference to a NET_IF_APP_INFO type variable. The function will populate structure with the information collected during the setup.

Starting the Network Interface Without a Configuration#

Alternatively, the network interface can be started immediately without a configuration.

Listing - Starting the interface without a configuration#

NET_IF_NBR       if_nbr;
RTOS_ERR         err;

                                                       /* ------------- START ETHERNET INTERFACE ------------- */
NetIF_Ether_Start(if_nbr, DEF_NULL, &err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occurred. Error handling should be added here. */
}

Note that in this case, the interface setup must be done by calling the appropriate API functions after the interface has been started: