This section gives more details on how to configure a network interface for μC/TCP-IP.
Buffers' Management
This section describe how µC/TCP-IP uses buffers to receive and transmit application data and network protocol control information. You should understand how network buffers are used by µC/TCP-IP to correctly configure your interface(s).
Network Buffers
µC/TCP-IP stores transmitted and received data in data structures known as Network Buffers. Each Network Buffer consists of two parts: the Network Buffer header and the Network Buffer Data Area pointer. Network Buffer headers contain information about the data pointed to via the data area pointer. Data to be received or transmitted is stored in the Network Buffer Data Area.
µC/TCP-IP is designed with the inherent constraints of an embedded system in mind, the most important being the restricted RAM space. µC/TCP-IP defines network buffers for the Maximum Transmission Unit (MTU) of the Data Link technology used, which is most of the time Ethernet. Default Ethernet’s maximum transmit unit (MTU) size is 1500 bytes.
Receive Buffers
Network Buffers used for reception for a Data Link technology are buffers that can hold one maximum frame size. Because it is impossible to predict how much data will be received, only large buffers can be configured. Even if the packet does not contain any payload, a large buffer must be used, as worst case must always be assumed.
Transmit Buffers
On transmission, the number of bytes to transmit is always known, so it is possible to use a Network Buffer size smaller than the maximum frame size. µC/TCP-IP allows you to reduce the RAM usage of the system by defining small buffers. When the application does not require a full size frame to transmit, it is possible to use smaller Network Buffers. Depending on the configuration, up to eight pools of Network Buffer related objects may be created per network interface. Only four pools are shown below and the remaining pools are used for maintaining Network Buffer usage statistics for each of the pools shown.
In transmission, the situation is different. The TCP/IP stack knows how much data is being transmitted. In addition to RAM being limited in embedded systems, another feature is the small amount of data that needs to be transmitted. For example, in the case of sensor data to be transmitted periodically, a few hundred bytes every second can be transferred. In this case, a small buffer can be used and save RAM instead of waste a large transmit buffer. Another example is the transmission of TCP acknowledgment packets, especially when they are not carrying any data back to the transmitter. These packets are also small and do not require a large transmit buffer. RAM is also saved.
µC/TCP-IP requires that network buffer sizes configured in net_dev_cfg.c satisfy the minimum and maximum packet frame sizes of network interfaces/devices.
Assuming an Ethernet interface (with non-jumbo or VLAN-tagged frames), the minimum frame packet size is 64 bytes (including its 4-byte CRC). If an Ethernet frame is created such that the frame length is less than 60 bytes (before its 4-byte CRC is appended), frame padding must be appended by the network driver or the Ethernet network interface layer to the application data area to meet Ethernet’s minimum packet size. For example, the ARP protocol typically creates packets of 42 bytes and therefore 18 bytes of padding must be added. The additional padding must fit within the network buffer’s data area.
Ethernet’s maximum transmit unit (MTU) size is 1500 bytes. When TCP is used as the transport protocol, TCP and IP protocol header sizes are subtracted from Ethernet’s 1500-byte MTU. A maximum of 1460 bytes of TCP application data may be sent in a full-sized Ethernet frame.
In addition, the variable size of network packet protocol headers must also be considered when configuring buffer sizes. The following computations demonstrate how to configure network buffer sizes to transmit and receive maximum sized network packets.
Typical Buffers Size
The following table shows how each network buffer should be configured to handle the majority of worst cases.
Type of network buffer | Size |
Receive Large Buffer | 1518 + Alignment |
Transmit Large Buffer | 1518 + Alignment |
Transmit Small Buffer | 64 + Alignment |
Network Device Configuration
All μC/TCP-IP device drivers require a configuration structure for each device that must be compiled into your driver. You must place all device configuration structures and declarations within a pair of files named net_dev_cfg.c and net_dev_cfg.h.
Micriµm provides sample configuration code free of charge; however, most sample code will likely require modification depending on the combination of compiler, processor, evaluation board, and device hardware used.
Memory Configuration
The first step in creating a device driver configuration for µC/TCP-IP begins with the memory configuration structure. This section describes the memory configuration settings for most device drivers, and should provide you an in-depth understanding of memory configuration. You will also discover which settings to modify in order to enhance the performances of the driver.
The listing below shows a sample memory configuration structure.
const NET_DEV_CFG NetDev_Cfg_Dev1 = {
/* Structure member: */
NET_IF_MEM_TYPE_MAIN, /* .RxBufPoolType */ (1)
1518u, /* .RxBufLargeSize */ (2)
9u, /* .RxBufLargeNbr */ (3)
16u, /* .RxBufAlignOctets */ (4)
0u, /* .RxBufIxOffset */ (5)
NET_IF_MEM_TYPE_MAIN, /* .TxBufPoolType */ (6)
1606u, /* .TxBufLargeSize */ (7)
4u, /* .TxBufLargeNbr */ (8)
64u, /* .TxBufSmallSize */ (9)
2u, /* .TxBufSmallNbr */ (10)
16u, /* .TxBufAlignOctets */ (11)
0u, /* .TxBufIxOffset */ (12)
0x00000000u, /* .MemAddr */ (13)
0u, /* .MemSize */ (14)
NET_DEV_CFG_FLAG_NONE, /* .Flag */ (15)
};
.RxBufPoolTypespecifies the memory location for the receive data buffers. Buffers may located either in main memory or in a dedicated memory region. This setting is used by the IF layer to initialize the Rx memory pool. This field must be set to one of two macros:NET_IF_MEM_TYPE_MAINorNET_IF_MEM_TYPE_DEDICATED. You may want to set this field when DMA with dedicated memory is used. It is possible that you might have to store descriptors within the dedicated memory if your device requires it..RxBufLargeSizespecifies the size of all receive buffers. Specifying a value is required. The buffer length is set to 1518 bytes which corresponds to the Maximum Transmission Unit (MTU) of 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..RxBufLargeNbrspecifies 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..RxBufAlignOctetsspecifies 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..RxBufIxOffsetspecifies 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. Also, the receive buffer size must also be adjusted by the number of additional bytes..TxBufPoolTypespecifies 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 IF layer, and it should be set to one of two macros:NET_IF_MEM_TYPE_MAINorNET_IF_MEM_TYPE_DEDICATED. When DMA descriptors are used, they may be stored into the dedicated memory..TxBufLargeSizespecifies 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 µC/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 μC/TCP-IP’s protocols.
You can 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..TxBufLargeNbrspecifies 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..TxBufSmallSizespecifies 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 64 byte small transmit buffer size, 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..TxBufSmallNbrspecifies 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..TxBufAlignOctetsspecifies 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..TxBufIxOffsetspecifies 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. The transmit buffer size must also be adjusted to include the number of additional bytes..MemAddrspecifies 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..MemSizespecifies 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..Flagsspecify 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.
Ethernet Device Configuration
Listing - Ethernet Device Configuration shows a sample Ethernet configuration structure for Ethernet devices.
Ethernet PHY Configuration
Listing - Ethernet PHY Configuration shows a typical Ethernet PHY configuration structure.
Wireless Device Configuration
Loopback Configuration
Configuring the loopback interface requires only a memory configuration, as described in µC/TCP-IP Network Interface Configuration.
Listing 5-9 shows a sample configuration structure for the loopback interface.
Adding a Loopback Interface
Basically, to enable and add the loopback interface you only have to enable the loopback interface within the network configuration See Network Interfaces Configuration.
Network Queues Configuration
The device configuration will directly impact the Network Task Queues Configuration.
The µC/TCP-IP stack includes two queues. 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.
The size of the Rx queue should reflects the total number of DMA receive descriptors configured for all the interfaces. If the devices are not DMA-based, it should reflects the maximum number of packets that can be acknowledged and signaled during a single receive interrupt even for all interfaces.
The size of the Tx queue should be defined as the total number of small and large transmit buffers declared for all interfaces.
Please refer to section Task Queue Configuration for more details.