RA Flexible Software Package Documentation  Release v5.2.0

 
FreeRTOS+TCP Wrapper to r_ether (rm_freertos_plus_tcp)

Middleware for using TCP on RA MCUs.

Overview

FreeRTOS Plus TCP is a TCP stack created for use with FreeRTOS.

This module provides the NetworkInterface required to use FreeRTOS Plus TCP with the Ethernet (r_ether) driver.

Please refer to the FreeRTOS Plus TCP documentation for further details.

Configuration

Build Time Configurations for FreeRTOS_Plus_TCP

The following build time configurations are defined in aws/FreeRTOSIPConfig.h:

ConfigurationOptionsDefaultDescription
Print debug messages
  • Disable
  • Enable
Disable If ipconfigHAS_DEBUG_PRINTF is set to 1 then FreeRTOS_debug_printf should be defined to the function used to print out the debugging messages.
Backward Compatible Mode
  • No
  • Yes
Yes Run the code in backward compatible mode
Enable IPV6
  • Disable
  • Enable
Disable Stack supports handling IPv6 packets (including handling IPv6 header, ND, RA, and so on) when enabled
Print info messages
  • Disable
  • Enable
Disable Set to 1 to print out non debugging messages, for example the output of the FreeRTOS_netstat() command, and ping replies. If ipconfigHAS_PRINTF is set to 1 then FreeRTOS_printf should be set to the function used to print out the messages.
Byte order of the target MCUpdFREERTOS_LITTLE_ENDIAN pdFREERTOS_LITTLE_ENDIAN Define the byte order of the target MCU
IP/TCP/UDP checksums
  • Disable
  • Enable
Enable If the network card/driver includes checksum offloading (IP/TCP/UDP checksums) then set ipconfigDRIVER_INCLUDED_RX_IP_CHECKSUM to 1 to prevent the software stack repeating the checksum calculations.
Receive Block TimeValue must be a non-negative integer10000 Amount of time FreeRTOS_recv() will block for. The timeouts can be set per socket, using setsockopt().
Send Block TimeValue must be a non-negative integer10000 Amount of time FreeRTOS_send() will block for. The timeouts can be set per socket, using setsockopt().
DNS caching
  • Disable
  • Enable
Enable DNS caching
DNS Request AttemptsValue must be an integer2 When a cache is present, ipconfigDNS_REQUEST_ATTEMPTS can be kept low and also DNS may use small timeouts.
IP stack task priorityOnly symbols, numbers and arithmetic operators are valid.configMAX_PRIORITIES - 2 Set the priority of the task that executes the IP stack.
Stack size in words (not bytes)Only symbols, numbers and arithmetic operators are valid.configMINIMAL_STACK_SIZE * 5 The size, in words (not bytes), of the stack allocated to the FreeRTOS+TCP stack.
Network Events call vApplicationIPNetworkEventHook
  • Disable
  • Enable
Enable vApplicationIPNetworkEventHook is called when the network connects or disconnects.
Max UDP send block timeOnly symbols, numbers and arithmetic operators are valid.15000 / portTICK_PERIOD_MS Max UDP send block time
Use DHCP
  • Disable
  • Enable
Enable If ipconfigUSE_DHCP is 1 then FreeRTOS+TCP will attempt to retrieve an IP address, netmask, DNS server address and gateway address from a DHCP server.
DHCP Register Hostname
  • Disable
  • Enable
Enable Register hostname when using DHCP
DHCP Uses Unicast
  • Disable
  • Enable
Enable DHCP uses unicast.
DHCP callback function
  • Disable
  • Enable
Disable Provide an implementation of the DHCP callback function(xApplicationDHCPHook)
Interval between transmissionsOnly symbols, numbers and arithmetic operators are valid.120000 / portTICK_PERIOD_MS When ipconfigUSE_DHCP is set to 1, DHCP requests will be sent out at increasing time intervals until either a reply is received from a DHCP server and accepted, or the interval between transmissions reaches ipconfigMAXIMUM_DISCOVER_TX_PERIOD.
ARP Cache EntriesValue must be an integer6 The maximum number of entries that can exist in the ARP table at any one time
ARP Request RetransmissionsValue must be an integer5 ARP requests that do not result in an ARP response will be re-transmitted a maximum of ipconfigMAX_ARP_RETRANSMISSIONS times before the ARP request is aborted.
Maximum time before ARP table entry becomes staleValue must be an integer150 The maximum time between an entry in the ARP table being created or refreshed and the entry being removed because it is stale
Use string for IP Address
  • Disable
  • Enable
Enable Take an IP in decimal dot format (for example, "192.168.0.1") as its parameter FreeRTOS_inet_addr_quick() takes an IP address as four separate numerical octets (for example, 192, 168, 0, 1) as its parameters
Total number of available network buffersValue must be an integer10 Define the total number of network buffer that are available to the IP stack
Set the maximum number of eventsOnly symbols, numbers and arithmetic operators are valid.ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS + 5 Set the maximum number of events that can be queued for processing at any one time. The event queue must be a minimum of 5 greater than the total number of network buffers
Enable FreeRTOS_sendto() without calling Bind
  • Enable
  • Disable
Disable Set to 1 then calling FreeRTOS_sendto() on a socket that has not yet been bound will result in the IP stack automatically binding the socket to a port number from the range socketAUTO_PORT_ALLOCATION_START_NUMBER to 0xffff. If ipconfigALLOW_SOCKET_SEND_WITHOUT_BIND is set to 0 then calling FreeRTOS_sendto() on a socket that has not yet been bound will result in the send operation being aborted.
TTL values for UDP packetsValue must be an integer128 Define the Time To Live (TTL) values used in outgoing UDP packets
TTL values for TCP packetsValue must be an integer128 Defines the Time To Live (TTL) values used in outgoing TCP packets
Use TCP and all its features
  • Disable
  • Enable
Enable Use TCP and all its features
Let TCP use windowing mechanism
  • Disable
  • Enable
Disable Let TCP use windowing mechanism
Maximum number of bytes the payload of a network frame can containValue must be an integer1500 Maximum number of bytes the payload of a network frame can contain
Basic DNS client or resolver
  • Disable
  • Enable
Enable Set ipconfigUSE_DNS to 1 to include a basic DNS client/resolver. DNS is used through the FreeRTOS_gethostbyname() API function.
Reply to incoming ICMP echo (ping) requests
  • Disable
  • Enable
Enable If ipconfigREPLY_TO_INCOMING_PINGS is set to 1 then the IP stack will generate replies to incoming ICMP echo (ping) requests.
FreeRTOS_SendPingRequest() is available
  • Disable
  • Enable
Disable If ipconfigSUPPORT_OUTGOING_PINGS is set to 1 then the FreeRTOS_SendPingRequest() API function is available.
FreeRTOS_select() (and associated) API function is available
  • Disable
  • Enable
Disable If ipconfigSUPPORT_SELECT_FUNCTION is set to 1 then the FreeRTOS_select() (and associated) API function is available
Filter out non Ethernet II frames.
  • Disable
  • Enable
Enable If ipconfigFILTER_OUT_NON_ETHERNET_II_FRAMES is set to 1 then Ethernet frames that are not in Ethernet II format will be dropped. This option is included for potential future IP stack developments
Responsibility of the Ethernet interface to filter out packets
  • Disable
  • Enable
Disable If ipconfigETHERNET_DRIVER_FILTERS_FRAME_TYPES is set to 1 then it is the responsibility of the Ethernet interface to filter out packets that are of no interest.
Access 32-bit fields in the IP packetsValue must be an integer2 To access 32-bit fields in the IP packets with 32-bit memory instructions, all packets will be stored 32-bit-aligned, plus 16-bits. This has to do with the contents of the IP-packets: all 32-bit fields are 32-bit-aligned, plus 16-bit
Size of the pool of TCP window descriptorsValue must be an integer240 Define the size of the pool of TCP window descriptors
Size of Rx buffer for TCP socketsValue must be an integer3000 Define the size of Rx buffer for TCP sockets
Size of Tx buffer for TCP socketsValue must be an integer3000 Define the size of Tx buffer for TCP sockets
TCP keep-alive
  • Disable
  • Enable
Enable TCP keep-alive is avaiable or not
TCP keep-alive intervalValue must be an integer120 TCP keep-alive interval in second
The socket semaphore to unblock the MQTT task (USER_SEMAPHORE)
  • Disable
  • Enable
Disable The socket semaphore is used to unblock the MQTT task
The socket semaphore to unblock the MQTT task (WAKE_CALLBACK)
  • Disable
  • Enable
Enable The socket semaphore is used to unblock the MQTT task
The socket semaphore to unblock the MQTT task (USE_CALLBACKS)
  • Disable
  • Enable
Disable The socket semaphore is used to unblock the MQTT task
The socket semaphore to unblock the MQTT task (TX_DRIVER)
  • Disable
  • Enable
Disable The socket semaphore is used to unblock the MQTT task
The socket semaphore to unblock the MQTT task (RX_DRIVER)
  • Disable
  • Enable
Disable The socket semaphore is used to unblock the MQTT task
Possible optimisation for expert users
  • Disable
  • Enable
Disable Possible optimisation for expert users - requires network driver support. It is is useful when there is high network traffic. If non-zero value then instead of passing received packets into the IP task one at a time the network interface can chain received packets together and pass them into the IP task in one go. If set to 0 then only one buffer will be sent at a time.

Usage Notes

In order to use the NetworkInterface implementation provided by Renesas for RA devices:

/* Reference used by the NetworkInterface to access the ethernet instance. */
extern ether_instance_t const * gp_freertos_ether;
...
/* Make it reference the configured ether instance. */
ether_instance_t const * gp_freertos_ether = &g_ether_instance;
Note
The MAC address passed to FreeRTOS_FillEndPoint must match the MAC address configured in the r_ether instance.
g_ether_instance must have vEtherISRCallback configured as the callback.
The xApplicationGetRandomNumber and ulApplicationGetNextSequenceNumber functions should be implemented in systems using FreeRTOS Plus TCP without Secure Sockets.
To connect to a server using an IP address the macro ipconfigINCLUDE_FULL_INET_ADDR must be set to 1.

Limitations