Configuration Structures and APIs interactions

Once µC/TCP-IP is initialized each type of network interface, wired or wireless, must be added to the stack via NetIF_Add() the same function as shown previously in Adding an Ethernet Interface and Adding a Wireless Interface.

µC/TCP-IP uses API functions to access the interface layer and configuration structures to initialize resources needed by the network interface. When writing a device driver you may have to create a device driver and extension APIs that use configuration structures in your implementation. Thus you must understand what is the interaction between each layer and API.

This is the NetIF_Add() prototype with the arguments you must pass:

NET_IF_NBR  NetIF_Add (void     *if_api,                               (1)
                       void     *dev_api,                              (2)
                       void     *dev_bsp,                              (3)
                       void     *dev_cfg,                              (4)
                       void     *ext_api,                              (5)
                       void     *ext_cfg,                              (6)
                       NET_ERR  *perr)                                 (7)

(1) Pointer to specific network interface API. This API should always be provided with the TCP-IP stack, you must only pass the API of your interface type. You can find the API under the interface folder (/IF).

(2) Pointer to specific network device driver API. If you want to develop your own driver you must implement this API and you should start from the device driver template which can be find under the device folder (/Dev/Template). APIs for Ethernet and wireless have some differences; see Wireless Device Driver Implementation for further information about each type of Interface’s API.

(3) Pointer to unique network device board-specific API. This API is used by the device driver initialization to configure several device aspects which are specific to the board and the application. Thus you must implement the API needed by your network interface. You should start from the BSP template provided with the stack which you can find under the BSP folder (/BSP/Template). For further information about the BSP layer to implement, see Wireless BSP Layer.

(4) Pointer to specific network device hardware configuration. This configuration structure is used by the interface and the device driver to initialize resources needed by the interface. Each interface type has its own configuration structure which always starts with the standard memory configuration. You should start from the interface configuration template which you can find under the configuration template (CFG/Template/net_dev_cfg.*). See Wireless Interface Configuration for further information about configuration structures. The device driver should validate the configuration structure before initializing registers and peripherals.

(5) Pointer to specific network extension layer API. This API is used by the interface to accomplish some operation specific to the physical type. For an Ethernet interface the extension layer is the PHY API. Micrium provides a generic Ethernet PHY which is compatible with the (R)MII standard, if your PHY is not compatible, you may have to implement an API for it. For further information about the Ethernet PHY API, see Ethernet PHY API Implementation.

For a wireless interface, the extension layer is the Wireless Manager API which can be found under (Dev/WiFi/Manager). If you write your own driver you may have to implement the extension API if the provided Wireless Manager doesn’t provide the functionality needed by your device driver.

(6) Pointer to specific network extension layer configuration. This configuration structure is used by the extension layer to initialize by the interface. For an Ethernet interface you should pass the PHY configuration. This configuration structure might be null for a Wireless Manager.

(7) Pointer to variable that will receive the return error code from this function.

For a thorough description of the µC/TCP-IP files and directory structure, see Directories and Files.

Configuration Structures and APIs interactions shows where these API are used by µC/TCP-IP and also the interaction between each interface layer and API passed to NetIF_Add():

(1) NetIF_API_Ether and NetIF_API_WiFi specify the address of the link layer API structure used by the µC/TCPIP module to transmit and receive data from the hardware device. For an Ethernet interface, this value is always defined as NetIF_API_Ether. For a wireless interface, this value is always defined as NetIF_API_WiFi. So, all you need to do is add the files contained in the IF folder to your project.

(2) NetDev_API_<controller> is the address of the API structure used by the IF layer to initialize the controller and control transmissions/reception, multicast, controller speed, and so on.

(3) NetDev_Cfg_<controller> is a configuration structure used by the IF and driver layers to configure memory, reserve buffers, reserve descriptor area, and so on. You have to update this structure following your application requirements. Refer to Wireless Interface Configuration for more information about how to configure an interface.

(4) For an Ethernet interface, a PHY API should be used. NetPhy_API_<phy> is the address of the API structure used by the IF and controller layers to control the PHY speed and to get the link state. If a generic (R)MII PHY provides the features you need, you do not have to implement this layer yourself; you can use the generic PHY. However, if the PHY does not support the MII or RMII standard, or necessary features are not provided by the generic (R)MII PHY, you will have to implement a new PHY.

For a wireless interface a Wireless Manager API should be used. NetWiFiMgr_API_Generic is the address of the API structure used by the IF and controller layers to control the wireless connection state.

(5) NetDev_BSP_<controller> is the address of the API structure used by the device driver to initialize interfaces specific to the board and processor.

(6) For an Ethernet interface, a PHY configuration must be passed. NetPhy_Cfg_<phy> is the address of the API structure where the initial PHY configuration settings (such as link speed and link dupex) are defined. More details are provided on that structure in Ethernet Interface Configuration

For a wireless interface no configuration structure is needed.