This section gives more details on how to configure a network interface for µCμC/TCP-IP.
...
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μ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
.
...
The listing below shows a sample memory configuration structure.
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
The listing below shows a sample wireless configuration structure for wireless devices.
Loopback Configuration
Configuring the loopback interface requires only a memory configuration, as described in µC/TCP-IP Network Interface Configuration.
...
language | cpp |
---|
theme | Confluence |
---|
firstline | 1 |
---|
title | Sample memory configuration |
---|
linenumbers | true |
---|
|
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)
}; |
Panel |
---|
|
.RxBufPoolType specifies 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_MAIN or NET_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.
.RxBufLargeSize specifies 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.
.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. Also, the receive buffer size must also be adjusted by 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 IF 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 into the 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 µ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.
.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 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.
.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. The transmit buffer size must also be adjusted to include 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.
|
Ethernet Device Configuration
152010771 shows a sample Ethernet configuration structure for Ethernet devices.
Code Block |
---|
language | cpp |
---|
theme | Confluence |
---|
firstline | 1 |
---|
title | Listing - Ethernet Device Configuration |
---|
linenumbers | true |
---|
|
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)
}; |
Panel |
---|
|
- Memory configuration of the Ethernet Device. See “Memory Configuration” for further information about how to configure the memory of your Ethernet interface.
.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.
|
Ethernet PHY Configuration
152010771 shows a typical Ethernet PHY configuration structure.
Panel |
---|
bgColor | #f0f0f0 |
---|
title | Listing - Ethernet PHY Configuration |
---|
|
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) };
|
Panel |
---|
|
- 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 specifying NET_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 to NetIF_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_INT
NET_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_AUTO
NET_PHY_SPD_10
NET_PHY_SPD_100
NET_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_AUTO
NET_PHY_DUPLEX_HALF
NET_PHY_DUPLEX_FULL
|
Wireless Device Configuration
The listing below shows a sample wireless configuration structure for wireless devices.
Code Block |
---|
language | cpp |
---|
theme | Confluence |
---|
firstline | 1 |
---|
title | Listing - Wireless device memory configuration |
---|
linenumbers | true |
---|
|
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)
}; |
Panel |
---|
|
- 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.
.Band specifies the desired wireless band enabled and used by the wireless device. This value should be set to one of the following values depending on the
hardware capabilities and the application requirements.
NET_DEV_BAND_2_4_GHZ NET_DEV_BAND_5_0_GHZ NET_DEV_BAND_DUAL .SPI_ClkFreq specifies the SPI controller’s clock frequency (in Hertz) configuration for writing and reading on the wireless device.
.SPI_ClkPol specifies the SPI controller’s clock polarity configuration for writing and reading on the wireless device. The network device BSP should configure the SPI
controller’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_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 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.
Code Block |
---|
language | cpp |
---|
theme | Confluence |
---|
firstline | 1 |
---|
title | Listing - Sample loopback interface configuration |
---|
linenumbers | true |
---|
|
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)
}; |
Panel |
---|
|
- 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_MAIN
NET_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_MAIN
NET_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_NONE No 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.