Network Interface Configuration
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
Network Interface Configuration#Listing - Ethernet Device Configuration shows a sample Ethernet configuration structure for Ethernet devices.
const NET_DEV_CFG_ETHER NetDev_Cfg_Dev1_0 = {
/* Structure member: */
NET_IF_MEM_TYPE_MAIN, /* .RxBufPoolType */ (1)
1518u, /* .RxBufLargeSize */
10u, /* .RxBufLargeNbr */
4u, /* .RxBufAlignOctets */
0u, /* .RxBufIxOffset */
NET_IF_MEM_TYPE_MAIN, /* .TxBufPoolType */
1606u, /* .TxBufLargeSize */
4u, /* .TxBufLargeNbr */
64u, /* .TxBufSmallSize */
4u, /* .TxBufSmallNbr */
4u, /* .TxBufAlignOctets */
0u, /* .TxBufIxOffset */
0x00000000u, /* .MemAddr */
0u, /* .MemSize */
NET_DEV_CFG_FLAG_NONE, /* .Flag */
6u, /* .RxDescNbr */ (2)
6u, /* .TxDescNbr */ (3)
0x40028000u, /* .BaseAddr */ (4)
0u, /* .DataBusSizeNbrBits */ (5)
"00:50:C2:25:61:00", /* .HW_AddrStr */ (6)
};
- Memory configuration of the Ethernet Device. See “Memory Configuration” for further information about how to configure the memory of your Ethernet interface.
.RxDescNbrspecifies 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.
.TxDescNbrspecifies 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.
.BaseAddrspecifies the base address of the device’s hardware/registers.
.DataBusSizeNbrBitsspecifies the size of device's data bus (in bits), if available.
.HW_AddrStrspecifies 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.
Ethernet PHY Configuration
Network Interface Configuration#Listing - Ethernet PHY Configuration shows a typical Ethernet PHY configuration structure.
NET_PHY_CFG_ETHER NetPhy_Cfg_FEC_0= { NET_PHY_ADDR_AUTO, (1)
NET_PHY_BUS_MODE_MII, (2)
NET_PHY_TYPE_EXT (3)
NET_PHY_SPD_AUTO, (4)
NET_PHY_DUPLEX_AUTO, (5)
};
- PHY Address. This field represents the address of the PHY on the (R)MII bus. The value configured depends on the PHY and the state of the PHY pins during power-up. Developers may need to consult the schematics for their board to determine the configured PHY address.
Alternatively, the PHY address may be detected automatically by specifyingNET_PHY_ADDR_AUTO; however, this will increase the initialization latency of µC/TCP-IP and possibly the rest of the application depending on where the application places the call toNetIF_Start().
PHY bus mode. This value should be set to one of the following values depending on the hardware capabilities and schematics of the development board. The network device BSP should configure
the Phy-level hardware based on this configuration value.
NET_PHY_BUS_MODE_MII
NET_PHY_BUS_MODE_RMII
NET_PHY_BUS_MODE_SMII- PHY bus type. This field represents the type of electrical attachment of the PHY to the Ethernet controller. In some cases, the PHY may be internal to the network controller, while in other cases, it may be attached via an external MII or RMII bus. It is desirable to specify which attachment method is in use so that a device driver can initialize additional hardware resources if an external PHY is attached to a device that also has an internal PHY. Available settings for this field are:
NET_PHY_TYPE_INTNET_PHY_TYPE_EXT - Initial PHY link speed. This configuration setting will force the PHY to link to the specified link speed. Optionally, auto-negotiation may be enabled. This field must be set to one of the following values:
NET_PHY_SPD_AUTONET_PHY_SPD_10NET_PHY_SPD_100NET_PHY_SPD_1000 - Initial PHY link duplex. This configuration setting will force the PHY to link using the specified duplex. This setting must be set to one of the following values:
NET_PHY_DUPLEX_AUTONET_PHY_DUPLEX_HALFNET_PHY_DUPLEX_FULL
Wireless Device Configuration
const NET_DEV_CFG_WIFI NetDev_Cfg_WiFi_0 = {
/* Structure member: */
NET_IF_MEM_TYPE_MAIN, /* .RxBufPoolType */ (1)
1518u, /* .RxBufLargeSize */
9u, /* .RxBufLargeNbr */
16u, /* .RxBufAlignOctets */
0u, /* .RxBufIxOffset */
NET_IF_MEM_TYPE_MAIN, /* .TxBufPoolType */
1606u, /* .TxBufLargeSize */
4u, /* .TxBufLargeNbr */
64u, /* .TxBufSmallSize */
2u, /* .TxBufSmallNbr */
16u, /* .TxBufAlignOctets */
0u, /* .TxBufIxOffset */
0x00000000u, /* .MemAddr */
0u, /* .MemSize */
NET_DEV_CFG_FLAG_NONE, /* .Flag */
NET_DEV_BAND_DUAL, /* .Band */ (2)
25000000L, /* .SPI_ClkFreq */ (3)
NET_DEV_SPI_CLK_POL_INACTIVE_HIGH, /* .SPI_ClkPol */ (4)
NET_DEV_SPI_CLK_PHASE_FALLING_EDGE, /* .SPI_ClkPhase */ (5)
NET_DEV_SPI_XFER_UNIT_LEN_8_BITS, /* .SPI_XferUnitLen */ (6)
NET_DEV_SPI_XFER_SHIFT_DIR_FIRST_MSB, /* .SPI_XferShiftDir */ (7)
"00:50:C2:25:60:02", /* .HW_AddrStr */ (8)
};
- Memory configuration of the wireless device. See µC/TCP-IP Network Interface Configuration for further information about how to configure the memory of your wireless interface.
.Bandspecifies the desired wireless band enabled and used by the wireless device. This value should be set to one of the following values depending on thehardware capabilities and the application requirements.
NET_DEV_BAND_2_4_GHZ
NET_DEV_BAND_5_0_GHZ
NET_DEV_BAND_DUAL.SPI_ClkFreqspecifies the SPI controller’s clock frequency (in Hertz) configuration for writing and reading on the wireless device..SPI_ClkPolspecifies the SPI controller’s clock polarity configuration for writing and reading on the wireless device. The network device BSP should configure the SPIcontroller’s clock polarity based on this configuration value.
NET_DEV_SPI_CLK_POL_INACTIVE_LOW
NET_DEV_SPI_CLK_POL_INACTIVE_HIGH.SPI_ClkPhase specifies the SPI controller’s clock phase configuration for writing and reading on the wireless device. The network device BSP should configure the SPI controller’s clock phase based on this configuration value.
NET_DEV_SPI_CLK_PHASE_FALLING_EDGE
NET_DEV_SPI_CLK_PHASE_RAISING_EDGE
.SPI_XferUnitLen specifies the SPI controller’s transfer unit length configuration for writing and reading on the wireless device. The network device BSP should configure the SPI
controller’s transfer unit length based on this configuration value.
NET_DEV_SPI_XFER_UNIT_LEN_8_BITS
NET_DEV_SPI_XFER_UNIT_LEN_16_BITS
NET_DEV_SPI_XFER_UNIT_LEN_32_BITS
NET_DEV_SPI_XFER_UNIT_LEN_64_BITS
- .SPI_XferShiftDir specifies the SPI controller’s shift direction configuration for writing and reading on the wireless device. The network device BSP should configure the SPI controller’s transfer unit length based on this configuration value.
NET_DEV_SPI_XFER_SHIFT_DIR_FIRST_MSB
NET_DEV_SPI_XFER_SHIFT_DIR_FIRST_LSB
.HW_AddrStrspecifies 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 device
drivers will automatically try to load and use the hardware address located in the memory of the device.
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.
const NET_IF_CFG_LOOPBACK NetIF_Cfg_Loopback = {
NET_IF_MEM_TYPE_MAIN, (1)
1518, (2)
10, (3)
4, (4)
0, (5)
NET_IF_MEM_TYPE_MAIN, (6)
1594, (7)
5, (8)
64, (9)
5, (10)
4, (11)
0, (12)
0x00000000, (13)
0, (14)
NET_DEV_CFG_FLAG_NONE (15)
};
- Receive buffer pool type. This configuration setting controls the memory placement of the receive data buffers. Buffers may either be placed in main memory or in a dedicated, possibly higher speed, memory region (see point #13, below). This field should be set to one of the two macros:
NET_IF_MEM_TYPE_MAINNET_IF_MEM_TYPE_DEDICATED - Receive buffer size. This field sets the size of the largest receivable packet, and can be set to match the application’s requirements.
Note: If packets are sent from a socket bound to a non local-host address, to the local host address (127.0.0.1), then the receive buffer size must be configured to match the maximum transmit buffer size, or maximum expected data size, that could be generated from a socket bound to any other interface.
- Number of receive buffers. This setting controls the number of receive buffers that will be allocated to the loopback interface. This value must be set greater than or equal to one buffer if loopback is receiving only UDP. If TCP data is expected to be transferred across the loopback interface, then there must be a minimum of four receive buffers.
- Receive buffer alignment. This setting controls the alignment of the receive buffers in bytes. 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 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 4-byte boundary.
- Receive buffer offset. The loopback interface receives packets starting at base index 0 in the network buffer data areas. This setting configures an offset from the base index of 0 to receive loopback packets. The default offset of 0 should be configured. However, if loopback receive packets are configured with an offset, the receive buffer size must also be adjusted by the additional number of offset bytes.
- Transmit buffer pool type. This configuration setting controls the memory placement of the transmit data buffers for the loopback interface. Buffers may either be placed in main memory or in a dedicated, possibly higher speed, memory region (see point #13, below). This field should be set to one of two macros:
NET_IF_MEM_TYPE_MAINNET_IF_MEM_TYPE_DEDICATED - Large transmit buffer size. At the time of this writing, transmit fragmentation is not supported; therefore this field sets the size of the largest transmittable buffer for the loopback interface when the application sends from a socket that is bound to the local-host address.
- Number of large transmit buffers. This field controls the number of large transmit buffers allocated to the loopback interface. The developer may set this field to zero to make room for additional large transmit buffers, however, the number of large plus the number of small transmit buffers must be greater than or equal to one for UDP traffic and three for TCP traffic.
- 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 64 byte small transmit buffers, however, the developer 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.
- Number of small transmit buffers. This field controls the number of small transmit buffers allocated to the device. The developer may set this field to zero to make room for additional large transmit buffers, however, the number of large plus the number of small transmit buffers must be greater than or equal to one for UDP traffic and three for TCP traffic.
- Transmit buffer alignment. This setting controls the alignment of the receive buffers in bytes. 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 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 4-byte boundary.
- Transmit buffer offset. This setting configures an offset from the base transmit index to prepare loopback packets. The default offset of 0 should be configured. However, if loopback transmit packets are configured with an offset, the transmit buffer size must also be adjusted by the additional number of offset bytes.
- Memory address. By default, this field is configured to 0x00000000. A value of 0 tells µC/TCP-IP to allocate buffers for the loopback interface from the µC/LIB Memory Manager default heap. If a faster, more specialized memory is available, the loopback interface buffers may be allocated into an alternate region if desired.
- Memory size. By default, this field is configured to 0. A value of 0 tells µC/TCP-IP to allocate as much memory as required from the µC/LIB Memory Manager default heap. If an alternate memory region is specified in the ‘Memory Address’ field above, then the maximum size of the specified memory segment must be specified.
- Optional configuration flags. Configure (optional) loopback features by logically OR’ing bit-field flags:
NET_DEV_CFG_FLAG_NONENo loopback configuration flags selected
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.