µC/TCP-IP is configurable at compile time via approximately 50 #defines in the application’s net_cfg.h file. µC/TCP-IP uses #defines because they allow code and data sizes to be scaled at compile time based on enabled features and the configured number of network objects. This allows the ROM and RAM footprints of µC/TCP-IP to be adjusted based on application requirements.
Most of the #defines should be configured with the default configuration values. A handful of values may likely never change because there is currently only one configuration choice available. This leaves approximately a dozen values that should be configured with values that may deviate from the default configuration.
It is recommended that the configuration process begins with the default configuration values which in the next sections will be shown in bold.
The sections in this chapter are organized following the order in µC/TCP-IP's template configuration file, net_cfg.h.
Sub-modules Configuration
µC/TCP-IP contains code that can use sub-modules such as DNS client to perform some specific operation and extend the functionalities of some particular API.
| Constant | Description | Possible Values |
|---|---|---|
| NET_EXT_MODULE_CFG_DNS_EN | Select portions of µC/TCP-IP code may call µC/DNSc API to resolve remote hostname. If µC/DNSc files/functions are included in the µC/TCP-IP build set NET_EXT_MODULE_CFG_DNS_EN to DEF_ENABLED. Set to DEF_DISABLED otherwise. | DEF_ENABLED or DEF_DISABLED |
Task Queue Configuration
The µC/TCP-IP stack has two queues that need to be configured. The first one is the Rx queue and is used to store the Rx buffer that have been filled and are ready to be process. The second queue is the Tx deallocation and is used to store the Tx buffers that are ready to be deallocate.
| Constant | Description | Possible Values |
|---|---|---|
| NET_CFG_IF_RX_Q_SIZE | Should be configured such that it reflects the total number of receive buffer minus the number of receive descriptor on all physical interfaces. If DMA is not available, or a combination of DMA and I/O based interfaces are configured then this number reflects the maximum number of packets that can be acknowledged and signaled during a single receive interrupt event for all interfaces. | Depends on the device configuration (see net_dev_cfg.c) |
| NET_CFG_IF_TX_DEALLOC_Q_SIZE | Should be defined to be the total number of small and large transmit buffers declared for all interfaces. | Depends on the device configuration (see net_dev_cfg.c) |
Compile Features Configuration
| Constant | Description | Possible Values |
|---|---|---|
| NET_CFG_OPTIMIZE_ASM_EN | Select portions of µC/TCP-IP code may call optimized assembly functions by configuring NET_CFG_OPTIMIZE_ASM_EN to DEF_ENABLED. If optimized assembly files/functions are included in the µC/TCP-IP build set NET_CFG_OPTIMIZE_ASM_EN to DEF_NEABLED. Set to DEF_DISABLED otherwise. | DEF_ENABLED or DEF_DISABLED |
Debug Features Configuration
| Constant | Description | Possible Values |
|---|---|---|
| NET_DBG_CFG_MEM_CLR_EN | Is used to clear internal network data structures when allocated or de-allocated. By clearing, all bytes in internal data structures are set to ‘0’ or to default initialization values. This configuration is typically set it to DEF_DISABLED unless the contents of the internal network data structures need to be examined for debugging purposes. Having the internal network data structures cleared generally helps to differentiate between “proper” data and “pollution”. | DEF_ENABLED or DEF_DISABLED |
Argument Check Configuration
Most functions in µC/TCP-IP include code to validate arguments that are passed to it. Specifically, µC/TCP-IP checks to see if passed pointers are NULL, if arguments are within valid ranges, etc. The following constants configure additional argument checking.
Counters Configuration
µC/TCP-IP contains code that increments counters to keep track of statistics such as the number of packets received, the number of packets transmitted, etc. Also, µC/TCP-IP contains counters that are incremented when error conditions are detected.
Timer Configuration
µC/TCP-IP manages software timers used to keep track of timeouts and execute callback functions when needed.
Network Interfaces Configuration
Address Resolution Protocol (ARP) Configuration
ARP is only used when the IPv4 stack is enabled.
ARP caches the mapping of IPv4 addresses to physical (i.e., MAC) addresses. NET_ARP_CFG_NBR_CACHE configures 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 the application depends on how many different hosts are expected to communicate. If the application only communicates with hosts on remote networks via the local network’s default gateway (i.e., router), then only a single ARP cache needs to be configured.
To test µC/TCP-IP with a smaller network, a default number of 3 ARP caches should be sufficient.
Neighbor Discovery Protocol (NDP) Configuration
NDP is only used when the IPv6 stack is enabled.
NDP caches the mapping of IPv6 addresses to physical (i.e., MAC) addresses. NET_NDP_CFG_NBR_CACHE configures 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 final destination address. It allows the µC/TCP-IP stack not having to re-calculating the next-hop for each packet to send. NET_NDP_CFG_DEST_NBR configured the numver of NDP destination caches available for the TCPIP stack.
In IPv6, routers send router advertisement messages to inform hosts on different values like the IPv6 prefix considered on-link. Those on-link prefix are stored in a NDP prefix list. NET_NDP_CFG_PREFIX_NBR configured the the number of prefix entries available in the list.
IPv6 defines an algorithm to chose the adequate router on the network to transmit packet outside in case more than one IPv6 router is present. NET_NDP_CFG_ROUTER_NBR defines the number of router information that can be store by the µC/TCP-IP stack.
IPv4 Layer Configuration
IPv6 Layer Configuration
Multicast Configuration (IGMP and MLDP)
NET_IGMP_CFG_MAX_NBR_HOST_GRP configures the maximum number of IGMP host groups that may be joined at any one 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 IGMP host groups required by the application depends on how many host groups are expected to be joined at a given time. Since each configured multicast address requires its own IGMP host group, it is recommended to configure at least one host group per multicast address used by the application, plus one additional host group. Thus for a single multicast address, it is recommended to set NET_IGMP_CFG_MAX_NBR_HOST_GRP with an initial value of 2.
Socket Layer Configuration
µC/TCP-IP supports BSD 4.x sockets and basic socket API for the TCP/UDP/IP protocols.
See Configuring window sizes for more information about how to configure receive and transmit queues buffer size.
BSD Socket API Configuration
By default, this setting is checked within the stack for having been defined. If it is not defined, by default it is defined as DEF_ENABLED. For developers to utilize this define from their application, this #define should be defined as DEF_DISABLED to remove them. The developer will also need to simply un-comment the line where it is defined.