Network Core Configuration#

Micrium OS Network core includes the TCP/IP stack and the service modules DHCP and DNS. Before using these components, you must properly configure the network core. There are two groups of configuration parameters for the network core:

Furthermore, to successfully configure a network interface, there are two additional configuration layers:

Network Core Compile-Time Configurations#

To configure the Micrium OS Network core module, you make use of approximately 50 #defines located in your application’s net_cfg.h file. The core module uses #defines because they allow code and data sizes to be scaled based on the features you choose to enable and the number of network objects you configure. This allows the ROM and RAM footprints of the Network module to be adjusted based on your application's requirements.

Most of the #defines should be configured with the default configuration values. A handful of these values will likely never be changeable because there is currently only one configuration choice available. This leaves approximately a dozen #defines that you might need to configure.

We recommend that you begin the configuration process with the default values, which are shown in bold.

The topics in this section are organized following the order in the template configuration file, net_cfg.h

Mandatory Configurations#

Debug Features Configuration#

Table - Debug Feature Constants#

Constant

Description

Possible Values

NET_DBG_CFG_MEM_CLR_EN

Clears the internal network data structures when allocated or de-allocated. By clearing, all bytes in internal data structures are set to ‘0’ or to their default initialization values. This configuration is typically set to DEF_DISABLED unless you need to examine the contents of the internal network data structures for debugging purposes. Having the internal network data structures cleared generally helps to differentiate between “proper” data and “pollution”. Note that the network performance can be affected when enabled.

DEF_ENABLED or DEF_DISABLED

Counters Configuration#

The Network core module contains code that increments counters to keep track of statistics such as the number of packets received, the number of packets transmitted, etc. It also contains counters that are incremented when error conditions are detected.

Table - Counter Configuration Constants#

Constant

Description

Possible Values

NET_CTR_CFG_STAT_EN

Allocates code and data space used to keep track of statistics.

DEF_ENABLED or DEF_DISABLED

NET_CTR_CFG_ERR_EN

Allocates code and data space used to keep track of errors.

DEF_ENABLED or DEF_DISABLED

Statistic Pool Configuration#

The Network core module uses pools to allocate many of its internal objects. Using the macro configurations below, the statistics can be enabled for each of those pools individually.

Table - Statistic Pool Configuration Constants#

Constant

Description

Possible Values

NET_STAT_POOL_BUF_EN

Allocates code and data space for the Buffers statistic pool.

DEF_ENABLED or DEF_DISABLED

NET_STAT_POOL_ARP_EN

Allocates code and data space for the ARP cache statistic pool.

DEF_ENABLED or DEF_DISABLED

NET_STAT_POOL_NDP_EN

Allocates code and data space for the NDP cache statistic pool.

DEF_ENABLED or DEF_DISABLED

NET_STAT_POOL_IGMP_EN

Allocates code and data space for the IGMP host group statistic pool.

DEF_ENABLED or DEF_DISABLED

NET_STAT_POOL_MLDP_EN

Allocates code and data space for the MLDP host group statistic pool.

DEF_ENABLED or DEF_DISABLED

NET_STAT_POOL_TMR_EN

Allocates code and data space for the Network Timer statistic pool.

DEF_ENABLED or DEF_DISABLED

NET_STAT_POOL_SOCK_EN

Allocates code and data space for the Socket statistic pool.

DEF_ENABLED or DEF_DISABLED

NET_STAT_POOL_CONN_EN

Allocates code and data space for the Connection statistic pool.

DEF_ENABLED or DEF_DISABLED

NET_STAT_POOL_TCP_CONN_EN

Allocates code and data space for the TCP Connection statistic pool.

DEF_ENABLED or DEF_DISABLED

Network Interfaces Configuration#

Table - Interface Configuration Constants#

Constant

Description

Possible Values

NET_IF_CFG_MAX_NBR_IF

Specifies the maximum number of network interfaces that the network module can create.

1 u if a single network interface is present.

NET_IF_CFG_LOOPBACK_EN

Allocates code and data space used to support the loopback interface for internal-only communication.

DEF_ENABLED or DEF_DISABLED

NET_IF_CFG_TX_SUSPEND_TIMEOUT_MS

Specifies the network interface transmit suspend timeout value in milliseconds.

1 u

NET_IF_CFG_WAIT_SETUP_READY_EN

Specifies whether the wait feature for the interface setup is enabled. When enabled, your application can wait for the network interface setup to complete by using the function NetIF_WaitSetupReady() . The network interface setup consists mainly of IP address configurations. The NetIF_WaitSetupReady() function will wait for all configuration processes that were specified in the start function to complete before returning.

DEF_ENABLED or DEF_DISABLED

Address Resolution Protocol (ARP) Configuration#

Table - ARP Configuration Constants#

Constant

Description

Possible Values

NET_ARP_CFG_CACHE_NBR

Specifies the number of ARP cache entries.

3 u

ARP caches the mapping of IPv4 addresses to physical (i.e., MAC) addresses. NET_ARP_CFG_NBR_CACHE specifies the number of ARP cache entries. Each cache entry requires approximately 18 bytes of RAM, plus seven pointers, plus a hardware address and protocol address (10 bytes assuming Ethernet interfaces and IPv4 addresses).

The number of ARP caches required by your application depends on how many different hosts your application is expected to communicate with. If your application communicates only with hosts on remote networks via the local network’s default gateway (i.e., router), then you need to configure only a single ARP cache.

To test the network module with a small network, the default number of three ARP caches should be sufficient.

Neighbor Discovery Protocol (NDP) Configuration#

Table - NDP Configuration Constants#

Constant

Description

Possible Values

NET_NDP_CFG_CACHE_NBR

Configures the number of NDP Neighbor cache entries.

6 u

NET_NDP_CFG_DEST_NBR

Configures the number of NDP Destination cache entries.

5 u

NET_NDP_CFG_PREFIX_NBR

Configures the number of NDP Prefix entries.

5 u

NET_NDP_CFG_ROUTER_NBR

Configures the number of NDP Router entries.

1 u

NDP caches the mapping of IPv6 addresses to physical (i.e., MAC) addresses. NET_NDP_CFG_NBR_CACHE specifies the number of NDP Neighbor cache entries. Each cache entry requires approximately 18 bytes of RAM, plus seven pointers, plus a hardware address and protocol address (22 bytes assuming Ethernet interfaces and IPv6 addresses).

NDP also caches recent IPv6 destination addresses by mapping next-hop address to the final destination address, thereby relieving the network stack from having to re-calculate the next-hop for each packet to send. NET_NDP_CFG_DEST_NBR specifies the number of NDP destination caches available for the TCP/IP stack.

In IPv6, routers send router advertisement messages to inform hosts about different values such as the on-link IPv6 prefix. Those on-link prefixes are stored in an NDP prefix list. NET_NDP_CFG_PREFIX_NBR specifies the number of prefix entries available in the list.

IPv6 defines an algorithm to chose the optimal router on the network to use to transmit packets in case more than one IPv6 router is available. NET_NDP_CFG_ROUTER_NBR specifies the number of router entries that can be stored by the TCP/IP stack.

IPv4 Layer Configuration#

Table - IPv4 Configuration Constants#

Constant

Description

Possible Values

NET_IPv4_CFG_EN

Enables the IPv4 module.

DEF_ENABLED or DEF_DISABLED

NET_IPv4_CFG_LINK_LOCAL_EN

Enables the IPv4 Link-Local address module.

DEF_ENABLED or DEF_DISABLED

NET_IPv4_CFG_IF_MAX_NBR_ADDR

Specifies the maximum number of IPv4 addresses that may be configured for all network interfaces at run-time.

At least 1

IPv6 Layer Configuration#

Constant

Description

Possible Values

NET_IPv6_CFG_EN

Enables the IPv6 module.

DEF_ENABLED or DEF_DISABLED

NET_IPv6_CFG_ADDR_AUTO_CFG_EN

Enables the IPv6 Stateless Address Auto-Configuration module.

DEF_ENABLED or DEF_DISABLED

NET_IPv6_CFG_DAD_EN

Enables the Duplication Address Detection (DAD) module.

DEF_ENABLED or DEF_DISABLED

NET_IPv6_CFG_IF_MAX_NBR_ADDR

Specifies the maximum number of IPv6 addresses that may be configured for all network interfaces at run-time.

At least 2

Table - IPv6 Configuration Constants#

Multicast Configuration (IGMP and MLDP)#

Table - Multicast Configuration Constants#

Constant

Description

Possible Values

NET_MCAST_CFG_IPv4_RX_EN

Enables multicast support in reception for IPv4.

DEF_ENABLED or DEF_DISABLED

NET_MCAST_CFG_IPv4_TX_EN

Enables multicast support in transmission for IPv4.

DEF_ENABLED or DEF_DISABLED

NET_MCAST_CFG_HOST_GRP_NBR_MAX

Specifies the maximum number of IGMP and MLDP host groups that may be joined at any time.

4 u

NET_MCAST_CFG_MAX_NBR_HOST_GRP configures the maximum number of IGMP and MLDP host groups that may be joined at any time. Each group entry requires approximately 12 bytes of RAM, plus three pointers, plus a protocol address (4 bytes assuming IPv4 address).

The number of host groups required by your application depends on how many host groups you expect your application to join at a given time. Since each configured multicast address requires its own host group, we recommend that you configure at least one host group per multicast address used by the application, plus one additional host group. Thus for a single multicast address, we recommend that you set NET_MCAST_CFG_MAX_NBR_HOST_GRP to an initial value of 2.

If IPv6 is enabled, MLDP multicast is enabled automatically and NET_MCAST_CFG_MAX_NBR_HOST_GRP must be adjusted because an interface with IPv6 support will need at least two multicast address.

Socket Layer Configuration#

The Network module supports BSD 4.x sockets and basic socket API for the TCP/UDP/IP protocols.

Table - Socket Configuration Constants#

Constant

Description

Possible Values

NET_SOCK_CFG_SOCK_NBR_TCP

Specifies the total number of TCP connections.

5

NET_SOCK_CFG_SOCK_NBR_UDP

Specifies the total number of UDP connections.

2

NET_SOCK_CFG_SEL_EN

Enables socket select functionality.

DEF_ENABLED or DEF_DISABLED

NET_SOCK_CFG_CONN_ACCEPT_Q_SIZE_MAX

Specifies the maximum size of the stream-type sockets' accept queue.

2

NET_SOCK_CFG_RX_Q_SIZE_OCTET

Specifies the buffer size of the socket receive queue.

4096

NET_SOCK_CFG_TX_Q_SIZE_OCTET

Specifies the buffer size of the socket transmit queue.

4096

TCP Layer Configuration#

Table - TCP Configuration Constants#

Constant

Description

Possible Values

NET_TCP_CFG_EN

Enables the TCP module.

DEF_ENABLED or DEF_DISABLED

UDP Layer Configuration#

Table - UDP Configuration Constants#

Constant

Description

Possible Values

NET_UDP_CFG_RX_CHK_SUM_DISCARD_EN

Used to determine whether received UDP packets without a valid checksum are discarded or are handled and processed. Before a UDP datagram checksum is validated, it is necessary to check whether the UDP datagram was transmitted with or without a computed checksum.

DEF_ENABLED or DEF_DISABLED

NET_UDP_CFG_TX_CHK_SUM_EN

Used to determine whether UDP checksums are computed for transmission to other hosts.

DEF_ENABLED or DEF_DISABLED

Transport Layer Security Configuration#

Table - Security Management Constants#

Constant

Description

Possible Values

NET_SECURE_CFG_MAX_NBR_SOCK_SERVER

Specifies the total number of server secure sockets.

5

NET_SECURE_CFG_MAX_NBR_SOCK_CLIENT

Specifies the total number of client secure sockets.

5

NET_SECURE_CFG_MAX_CERT_LEN

Specifies the maximum length (in octets) of server certificates.

2048

NET_SECURE_CFG_MAX_KEY_LEN

Specifies the maximum length (in octets) of server keys.

2048

NET_SECURE_CFG_MAX_NBR_CA

Specifies the maximum number of certificate authorities that can be installed.

1

NET_SECURE_CFG_MAX_CA_CERT_LEN

Specifies the maximum length (in octets) of certificate authority certificates.

2048

Core Modules Configuration#

The network core module includes basic network services such as DHCP and DNS client, which can be disabled if not required.

Table - Core Modules Configuration#

Constant

Description

Possible Values

NET_DHCP_CLIENT_CFG_MODULE_EN

Enables the DHCP client module.

DEF_ENABLED or DEF_DISABLED

NET_DNS_CLIENT_CFG_MODULE_EN

Enables the DNS client module.

DEF_ENABLED or DEF_DISABLED

Advanced Configurations#

The Network module has many compile-time configurations that are already defined by the module with default values. Those values should work for most cases, but your application can still override them if necessary.

Table - Network Core Default Configuration#

{@Manual intervention complex table}

Name

Description

Default Value

NET_TMR_CFG_NBR_TMR

By default, the network timer pool size has no limits.To limit the maximum number of network timers, you can adjust this configuration.

LIB_MEM_BLK_QTY_UNLIMITED

Socket

NET_SOCK_DFLT_BSD_EN

Enable or Disable BSD API and data type declaration. By default, the API and declaration are included.Note that your application doesn't require BSD API and you experimenting issue with duplication declaration with your compiler you can disable the BSD compatibility. If you BSD compatibility is required and you experimenting duplication declaration you have to change your toolchain setting to remove the BSD and POSIX declaration.

DEF_ENABLED

NET_SOCK_DFLT_NO_BLOCK_EN

Sets all sockets as non-blocking. By default, sockets are set to block.Note that it's possible to change the socket's blocking mode at run-time using the Socket Option API.

DEF_DISABLED

NET_SOCK_DFLT_PORT_NBR_RANDOM_BASE

Specifies the initial random port number. By default, the random port number start at 49152.

49152

NET_SOCK_DFLT_TIMEOUT_RX_Q_MS

Specifies the timeout for the socket reception queue in milliseconds.When a socket is set as blocking, the specified timeout value is used.Timeout values may also be configured to never time out with the network time constant NET_TMR_TIME_INFINITE.Note that it's possible to change at run-time any timeout values using the Socket Option API.

10000

NET_SOCK_DFLT_TIMEOUT_CONN_REQ_MS

Specifies the default timeout for the socket connection connect request in milliseconds.When a socket is set as blocking the specified timeout value is used.Timeout values may also be configured to never time out with the network time constant NET_TMR_TIME_INFINITE.Note that it's possible to change at run-time any timeout values using the Socket Option API.

10000

NET_SOCK_DFLT_TIMEOUT_CONN_ACCEPT_MS

Specifies the timeout for the socket connection accept in milliseconds.When a socket is set as blocking the following specified timeout value is used.Timeout values may also be configured to never time out with the network time constant NET_TMR_TIME_INFINITE.Note that it's possible to change at run-time any timeout values using the Socket Option API.

10000

NET_SOCK_DFLT_TIMEOUT_CONN_CLOSE_MS

Specifies the timeout for the socket connection close in milliseconds.When a socket is set as blocking the following specified timeout value is used.Timeout values may also be configured to never time out with the network time constant NET_TMR_TIME_INFINITE.Note that it's possible to change at run-time any timeout values using Socket Option API.

10000

TCP

NET_TCP_DFLT_RX_WIN_SIZE_OCTET

Specifies the TCP RX window size.By default, the TCP RX window is set to equal the socket RX queue size. TCP windows must be properly configured to optimize performance (see section Configuring Window Sizes ).Note that it's possible to decrease window size at run time using Socket Option API.

NET_SOCK_CFG_RX_Q_SIZE_OCTET

NET_TCP_DFLT_TX_WIN_SIZE_OCTET

Specifies the TCP TX window size.By default, the TCP TX window is set to equal the socket TX queue size. TCP windows must be properly configured to optimize performance (see section Configuring Window Sizes ).Note that it's possible to decrease window size at run time using Socket Option API.

NET_SOCK_CFG_TX_Q_SIZE_OCTET

NET_TCP_DFLT_TIMEOUT_CONN_MAX_SEG_SEC

Specifies the TIME_WAIT connection timeout.As shown in the TCP state diagram (see RFC #793), before moving to the 'CLOSED' state, the connection waits for a short period (typically 2 minutes), which is called the TIME_WAIT state. This timeout prevents the TCP connection from becoming immediately available for subsequent TCP connections. But this delay can be a problem for embedded systems that cannot handle many simultaneous connections, especially when many TCP connections are made in a small period of time. Therefore this timeout is set to 0 by default to avoid this kind of problem, and the connection is made available as soon as the TIME_WAIT state is reached.Note that it is possible to change the MSL timeout for a specific TCP connection using Socket Option API.

0

NET_TCP_DFLT_TIMEOUT_CONN_FIN_WAIT_2_SEC

Specifies the FIN_WAIT_2 connection timeout.In the FIN_WAIT_2 state, the local endpoint is waiting for a connection termination request from the remote endpoint. To prevent a connection from being left open indefinitely if the termination request never arrives, the TCP connection's timer is set to 15 seconds by default, and when it expires the connection is dropped.

15

NET_TCP_CFG_NBR_CONN

Specifies the total number of TCP connections.The number of TCP connections is based on the number of TCP sockets and the accept queue size when TIME_WAIT is set to 0 ms. However, since the default TIME_WAIT value can be modified, you might need to increase the number of TCP connections in order to establish new connections when waiting for the TIME_WAIT expiration.

0

NET_TCP_DFLT_TIMEOUT_CONN_ACK_DLY_MS

Specifies the ACK delay in milliseconds.By default, an ACK is generated within 500 ms of the arrival of the first unacknowledged packet, as specified in RFC #2581, Section 4.2.

500

NET_TCP_DFLT_TIMEOUT_CONN_RX_Q_MS

Specifies the default timeout for the TCP Reception Queue in milliseconds.This value determines how long a socket is allowed to remain blocking when receiving.Timeout values may also be configured to never time out with the network time constant NET_TMR_TIME_INFINITE.Note that it's possible to change at run-time any timeout values using the Socket Option API.

1000

NET_TCP_DFLT_TIMEOUT_CONN_TX_Q_MS

Specifies the default timeout for the TCP Transmission Queue, in milliseconds.This value determines how long a socket is allowed to remain blocking when transmitting.Timeout values may also be configured to never time out with network time constant, NET_TMR_TIME_INFINITE.Note that it's possible to change at run-time any timeout values using the Socket Option API.

1000

Checksum Offload

By default, all checksum are validated by the stack. However, it is possible to enable or disable validation for specific checksums. Enable any of the following defines in your net_cfg.h file to change the default behavior. Turning off checksum validation can also provide a performance boost.

NET_IPV4_CFG_CHK_SUM_OFFLOAD_RX_EN

Turn off validation in reception for IPv4 checksums.

DEF_DISABLED

NET_IPV4_CFG_CHK_SUM_OFFLOAD_TX_EN

Turn off calculation in transmission for IPv4 checksums.

DEF_DISABLED

NET_ICMP_CFG_CHK_SUM_OFFLOAD_RX_EN

Turn off validation in reception for ICMP checksums.

DEF_DISABLED

NET_ICMP_CFG_CHK_SUM_OFFLOAD_TX_EN

Turn off calculation in transmission for ICMP checksums.

DEF_DISABLED

NET_UDP_CFG_CHK_SUM_OFFLOAD_RX_EN

Turn off validation in reception for UDP checksums.

DEF_DISABLED

NET_UDP_CFG_CHK_SUM_OFFLOAD_TX_EN

Turn off calculation in transmission for UDP checksums.

DEF_DISABLED

NET_TCP_CFG_CHK_SUM_OFFLOAD_RX_EN

Turn off validation in reception for TCP checksums.

DEF_DISABLED

NET_TCP_CFG_CHK_SUM_OFFLOAD_TX_EN

Turn off calculation in transmission for TCP checksums.

DEF_DISABLED

Network Core Run-Time Configurations#

This section describes the application-specific configurations of the Micrium OS Network module, that are specified at run-time.

Network Core Configuration#

To initialize the Micrium OS Network Core module, you must call the function Net_Init(). This function does not have any mandatory configuration argument.

Optional Configurations#

The configurations described below are optional; if you do not set them in your application, the default values will apply. The default values can be retrieved via the structure Net_InitCfgDflt.

There are two different ways of overriding the default values:

  • The first method is to via the four functions listed in the table below.

  • The second method is for your application to define the configuration structure over the one declared by Micrium OS (as an extern variable).

Note that in either case, these configurations must be set before calling the Net_Init() function.

Method 1 - Specific Function Calls#

Memory Segments#

Specifies a pointer to a memory segment to use when allocating control data for the network core.

Configuration Type

Function to Call

Default

Field From Default Configuration Structure

MEM_SEG*

Net_ConfigureMemSeg()

General-purpose heap .

.MemSegPtr

Network Core Task's Stack Size#

Specifies the size (in CPU_STK elements) of the stack for the network core task. The core stack is used for the main TCP/IP core operations: receive packets, demux packets up to the socket layer, network timer handling, free network buffers, etc.

Configuration Type

Function to Call

Default

Field From Default Configuration Structure

CPU_STK_SIZECPU_STK*

Net_ConfigureCoreTaskStk()

A stack of 512 elements allocated on network core's memory segment.

.CoreStkSizeElements.CoreStkPtr

Network Core Services Task's Stack Size#

Specifies the size (in CPU_STK elements) of the stack for the network core services task. The core services task is used for the DHCP client and DNS client module.

Configuration Type

Function to Call

Default

Field From Default Configuration Structure

CPU_STK_SIZECPU_STK*

Net_ConfigureCoreSvcTaskStk()

A stack of 512 elements allocated on network core's memory segment.

.CoreSvcStkSizeElements.CoreSvcStkPtr

DNS Configuration#

Specifies the configuration structure for the DNS client core module. The fields in this structure are as follows:

Field

Description

Possible Values

.HostNameLenMax

Maximum host name length that can be requested.

Any 16-bit unsigned integer, 255 u by default.

.CacheEntriesMaxNbr

Number of entries the cache can contain.

Any unsigned integer, LIB_MEM_BLK_QTY_UNLIMITED by default.

.AddrIPv4MaxPerHost

The maximum number of IPv4 addresses that can be stored by a host in the cache.Only valid if IPv4 is enabled.

Any unsigned integer, LIB_MEM_BLK_QTY_UNLIMITED by default.

.AddrIPv6MaxPerHost

The maximum number of IPv6 addresses that can be stored by a host in the cache.Only valid if IPv6 is enabled.

Any unsigned integer, LIB_MEM_BLK_QTY_UNLIMITED by default.

.OpDly_ms

Configures the operations delay in integer milliseconds.

Any 8-bit unsigned integer, 50 u by default.

.ReqRetryNbrMax

Configures maximum of request resolution retry.

Any 8-bit unsigned integer, 3 u by default.

.ReqRetryTimeout_ms

Configures timeout before a request resolution retry.

Any 16-bit unsigned integer, 1000 u by default.

.DfltServerAddrFallbackEn

Enables the DNS process to fallback to the default DNS server address if no address is available. By default, the fallback DNS server address is 8.8.8.8

DEF_ENABLED or DEF_DISABLED

Configuration Type

Function to Call

Default

Field From Default Configuration Structure

DNSc_CFG

Net_ConfigureDNS_Client()

See structure's description.

.DNSc_Cfg

Method 2 - Externalized Structure#

If you prefer to use the advanced configuration method, you must set the flag RTOS_CFG_EXTERNALIZE_OPTIONAL_CFG to DEF_ENABLED. In addition, the Network module will assume that your application will define a NET_INIT_CFG structure named Net_InitCfg. Optionally, you may assign Net_InitCfg the value of NET_INIT_CFG_DFLT to begin, and then modify some fields (see the table from Method 1) to suit your application's needs. See Initializing the Network Core Module for more information.

Post-Init Configurations#

This section describes the configurations that can be set at any time during execution after you call the function Net_Init().

These configurations are optional. If you do not set them in your application, the default configurations will apply.

Configurations

Description

Type

Function to call

Default

Network core task priority

Net_Init() creates a task for handling the TCP/IP core. You can change the priority of this task at any time.

RTOS_TASK_PRIO

Net_CoreTaskPrioSet()

See Appendix A - Internal Tasks .

Network core services task priority

Net_Init() creates a task for handling core services such as the DHCP client and the DNS client. You can change the priority of this task at any time.

RTOS_TASK_PRIO

Net_CoreSvcTaskPrioSet()

See Appendix A - Internal Tasks .

Network Interface Controller Configuration#

The approach to configuring your network interface controller is a bit different depending on the interface type. The sections below discuss the different strategies for the two supported network interfaces: Ethernet and Wi-Fi.

Ethernet Controller#

For an Ethernet interface controller, all the application and hardware parameters are grouped into one global configuration structure named NET_DEV_CFG_ETHER. Each Ethernet interface present on your board must have its own NET_DEV_CFG_ETHER object. This object must also be defined in the BSP files of your project because it will be passed as an argument when registering the network interface with the BSP_OS_Init() function. Refer to the section Network Core Hardware Porting Guide for more details.

The NET_DEV_CFG_ETHER object is passed to the network stack during the registration process inside the BSP. So, when your application adds an Ethernet interface (using the NetIF_Ether_Add() function), there is no need to pass arguments describing the interface configuration.

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

Table - NET_DEV_CFG_ETHER Configuration Structure#

Field

Description

.RxBufPoolType

Specifies the memory location for the receive data buffers. Buffers may be located either in main memory or in a dedicated memory region. This setting is used by the Interface layer to initialize the Rx memory pool. This field must be set to one of two macros: NET_IF_MEM_TYPE_MAIN or NET_IF_MEM_TYPE_DEDICATED. You may want to set this field when using DMA with dedicated memory. It is possible that you might have to store descriptors within the dedicated memory if your device requires it.

.RxBufLargeSize

Specifies the size of all receive buffers. Specifying a value is required. The default buffer length is set to 1518 bytes, which corresponds to the Maximum Transmission Unit (MTU) size for an Ethernet network. For DMA-based Ethernet controllers, you must set the receive data buffer size to be greater or equal to the size of the largest receivable frame. If the size of the total buffer allocation is greater than the amount of available memory in the chosen memory region, a run-time error will be generated when the device is initialized.

.RxBufLargeNbr

Specifies the number of receive buffers that will be allocated to the device. There should be at least one receive buffer allocated, and it is recommended to have at least ten receive buffers. The optimal number of receive buffers depends on your application.

.RxBufAlignOctets

Specifies the required alignment of the receive buffers, in bytes. Some devices require that the receive buffers be aligned to a specific byte boundary. Additionally, some processor architectures do not allow multi-byte reads and writes across word boundaries and therefore may require buffer alignment. In general, it is probably a best practice to align buffers to the data bus width of the processor, which may improve performance. For example, a 32-bit processor may benefit from having buffers aligned on a four-byte boundary.

.RxBufIxOffset

Specifies the receive buffer offset in bytes. Most devices receive packets starting at base index zero in the network buffer data areas. However, some devices may buffer additional bytes prior to the actual received Ethernet packet. This setting configures an offset to ignore these additional bytes. If a device does not buffer any additional bytes ahead of the received Ethernet packet, then an offset of 0 must be specified. However, if a device does buffer additional bytes ahead of the received Ethernet packet, then you should configure this offset with the number of additional bytes.

.TxBufPoolType

Specifies the memory placement of the transmit data buffers. Buffers may be placed either in main memory or in a dedicated memory region. This field is used by the Interface layer, and it should be set to one of two macros: NET_IF_MEM_TYPE_MAIN or NET_IF_MEM_TYPE_DEDICATED. When DMA descriptors are used, they may be stored in dedicated memory.

.TxBufLargeSize

Specifies the size of the large transmit buffers in bytes. This field has no effect if the number of large transmit buffers is configured to zero. Setting the size of the large transmit buffers below 1594 bytes may hinder the TCP/IP module’s ability to transmit full sized IP datagrams since IP transmit fragmentation is not yet supported. We recommend setting this field between 1594 and 1614 bytes in order to accommodate all of the maximum transmit packet sizes for TCP-IP’s protocols.You can also optimize the transmit buffer if you know in advance what the maximum size of the packets the user will want to transmit through the device are.

.TxBufLargeNbr

Specifies the number of large transmit buffers allocated to the device. You may set this field to zero to make room for additional small transmit buffers, however, the size of the maximum transmittable packet will then depend on the size of the small transmit buffers.

.TxBufSmallSize

Specifies the small transmit buffer size. For devices with a minimal amount of RAM, it is possible to allocate small transmit buffers as well as large transmit buffers. In general, we recommend a small transmit buffer size of 64 bytes, however, you may adjust this value according to the application requirements. This field has no effect if the number of small transmit buffers is configured to zero.

.TxBufSmallNbr

Specifies the numbers of small transmit buffers. This field controls the number of small transmit buffers allocated to the device. You may set this field to zero to make room for additional large transmit buffers if required.

.TxBufAlignOctets

Specifies the transmit buffer alignment in bytes. Some devices require that the transmit buffers be aligned to a specific byte boundary. Additionally, some processor architectures do not allow multi-byte reads and writes across word boundaries, and therefore may require buffer alignment. In general, it's probably a best practice to align buffers to the data bus width of the processor which may improve performance. For example, a 32-bit processor may benefit from having buffers aligned on a four-byte boundary.

.TxBufIxOffset

Specifies the transmit buffer offset in bytes. Most devices only need to transmit the actual Ethernet packets as prepared by the higher network layers. However, some devices may need to transmit additional bytes prior to the actual Ethernet packet. This setting configures an offset to prepare space for these additional bytes. If a device does not transmit any additional bytes ahead of the Ethernet packet, the default offset of zero should be configured. However, if a device does transmit additional bytes ahead of the Ethernet packet then configure this offset with the number of additional bytes.

.MemAddr

Specifies the starting address of the dedicated memory region for devices with this memory type. For devices with non-dedicated memory, you can initialize this field to zero. You may use this setting to put DMA descriptors into the dedicated memory.

.MemSize

Specifies the size of the dedicated memory region in bytes for devices with this memory type. For devices with non-dedicated memory, you can initialize this field to zero. You may use this setting to put DMA descriptors into the dedicated memory.

.Flags

Specify the optional configuration flags. Configure (optional) device features by logically OR’ing bit-field flags:NET_DEV_CFG_FLAG_NONE — No device configuration flags selected.NET_DEV_CFG_FLAG_SWAP_OCTETS — Swap data bytes (i.e., swap data words’ high-order bytes with data words’ low-order bytes, and vice-versa) if required by device-to-CPU data bus wiring and/or CPU endian word order.

.RxDescNbr

Specifies the number of receive descriptors. For DMA-based devices, this value is used by the device driver during initialization in order to allocate a fixed-size pool of receive descriptors to be used by the device. The number of descriptors must be less than the number of configured receive buffers. We recommend setting this value to something within 40% and 70% of the number of receive buffers. Non-DMA based devices may configure this value to zero. You must use this setting with DMA based devices and at least two descriptors must be set.

.TxDescNbr

Specifies the number of transmit descriptors. For DMA based devices, this value is used by the device driver during initialization to allocate a fixed size pool of transmit descriptors to be used by the device. For best performance, it’s recommended to set the number of transmit descriptors equal to the number of small, plus the number of large transmit buffers configured for the device. Non-DMA based devices may configure this value to zero. You must use this setting with DMA based devices and set at least two descriptors.

.BaseAddr

Specifies the base address of the device’s hardware/registers.

.DataBusSizeNbrBits

Specifies the size of device's data bus (in bits), if available.

.HW_AddrStr

Specifies the desired device hardware address; may be NULL address or string if the device hardware address is configured or set at run-time.Depending on the driver, if this value is kept NULL or invalid, most of the device driver will automatically try to load and use the hardware address located in the memory of the device.

.CfgExtPtr

Specifies the pointer to an extension configuration structure if needed, else set to DEF_NULL.

There is an additional configuration structure for PHY controllers: NET_PHY_CFG_ETHER. You might need to adjust some of the configuration fields in this structure depending on your specific needs (for example, the link speed). See PHY Configuration and Information for more details.

Wi-Fi Controller#

In contrast to the Ethernet interface, the Wi-Fi interface separates the application-specific configuration parameters from the hardware parameters for the controller. So, when adding a Wi-Fi interface with NetIF_WiFi_Add(), you must pass a NET_IF_BUF_CFG argument. The NET_IF_BUF_CFG structure contains all the fields related to the network buffer configuration of a Wi-Fi interface.

Table - NET_IF_BUF_CFG Configuration Structure#

Filed

Description

.RxBufLargeNbr

Specifies the number of receive buffers that will be allocated to the device. There should be at least one receive buffer allocated, and we recommend at least ten receive buffers. The optimal number of receive buffers depends on your application.

.TxBufLargeNbr

Specifies the number of large transmit buffers allocated to the device. You may set this field to zero to make room for additional small transmit buffers; however, the size of the maximum transmittable packet will then depend on the size of the small transmit buffers.

.TxBufSmallNbr

Specifies the numbers of small transmit buffers. This field controls the number of small transmit buffers allocated to the device. You may set this field to zero to make room for additional large transmit buffers if required.

.BufAlignOctets

Specifies the network buffer alignment in bytes. Some devices require that the buffers be aligned to a specific byte boundary. Additionally, some processor architectures do not allow multi-byte reads and writes across word boundaries and therefore may require buffer alignment. In general, it's probably a best practice to align buffers to the data bus width of the processor, which may improve performance. For example, a 32-bit processor may benefit from having buffers aligned on a four-byte boundary.

.BufPoolType

Specifies the memory location for the network buffers. Buffers may be located either in main memory or in a dedicated memory region. This field must be set to one of two macros: NET_IF_MEM_TYPE_MAIN or NET_IF_MEM_TYPE_DEDICATED.

.MemAddr

Specifies the starting address of the dedicated memory region for devices with this memory type. For devices with non-dedicated memory, you can initialize this field to zero.

.MemSize

Specifies the size of the dedicated memory region in bytes for devices with this memory type. For devices with non-dedicated memory, you can initialize this field to zero.

Network Interface Start Setup#

To start a network interface, you need to make only one API call. This is done by providing a configuration structure as an argument to the NetIF_Ether_Start() or NetIF_WiFi_Start() functions. Each interface type has its own configuration structure since some parameters are unique. These structures include parameters for the local IP address and DHCP setup, among others.

Using this configuration structure is optional; both NetIF_Ether_Start() and NetIF_WiFi_Start() can be called with a null pointer as an argument instead. If you start the network interface without a configuration, the interface will not be active on the network until you provide the necessary configuration information using additional API calls. This would include, for example, setting the local IP address, network mask, and gateway. See the IP Address Programming section of the Network Core Programming Guide for more details.

The following sections describe the parameters for the Network Interface Start configuration structure.

Ethernet Interface#

Table - NET_IF_ETHER_CFG Setup Structure in the Network Interface Start Setup page shows the setup structure for the Ethernet interface. To start and configure the Ethernet interface, call NetIF_Ether_Start() using this structure as the second argument in the function.

Table - NET_IF_ETHER_CFG Setup Structure#

NET_IF_ETHER_CFG Setup StructureNET_IF_ETHER_CFG Setup Structure

Wi-Fi Interface#

Table - NET_IF_WIFI_CFG Setup Structure in the Network Interface Start Setup page shows the setup structure for the Wi-Fi interface. To start and configure the Wi-Fi interface, call NetIF_WiFi_Start() using this structure as the second argument in the function. As you can see, it is almost the same structure as for the Ethernet interface, plus additional Wi-Fi-specific parameters.

Table - NET_IF_WIFI_CFG Setup Structure#

Field

Description

.HW_AddrStr

Same as for the Ethernet interface. See Table - NET_IF_ETHER_CFG Setup Structure in the Network Interface Start Setup page

.IPv4

Same as for the Ethernet interface. See Table - NET_IF_ETHER_CFG Setup Structure in the Network Interface Start Setup page

.IPv6

Same as for the Ethernet interface. See Table - NET_IF_ETHER_CFG Setup Structure in the Network Interface Start Setup page

.Band

Configures the wireless band used by the Wi-Fi device: NET_DEV_2_4_GHZ, NET_DEV_5_0_GHZ, NET_DEV_DUAL