Download FreeRTOS
 

Quality RTOS & Embedded Software

LIBRARIES
WHAT'S NEW
Simplifying Authenticated Cloud Connectivity for Any Device.
Designing an energy efficient and cloud-connected IoT solution with CoAP.
Introducing FreeRTOS Kernel version 11.0.0:
FreeRTOS Roadmap and Code Contribution process.
OPC-UA over TSN with FreeRTOS.

TCP/IP Specific Trace Hook Macros
For Debugging and Optimising FreeRTOS-Plus-TCP Behaviour

Also see the Debug, Trace and Logging settings in FreeRTOSIOConfig.h.

Description

Trace hook macros allow you to collect data while your FreeRTOS-Plus-TCP application is running. The data can be used for both debugging and optimisation purposes.

Key points of interest within the RTOS's TCP source code contain macros that an application can define for the purpose of providing application specific trace functionality. The application need only implement the macros of interest - unimplemented macros will remain empty (not generate any code) by default.

It is recommended to implement trace macros in a header file, then #include the header file at the bottom of FreeRTOSIPConfig.h.

The FreeRTOS-Plus-TCP example that runs in the Windows simulator (available for download from this website) uses the trace macros to collect TCP/IP stack run time information that can then be viewed using the TCP/IP CLI interface.

The table below details the macros that can be defined.

Macro definition Description
iptraceNETWORK_DOWN() Called when the network driver indicates that the network connection has been lost (not implemented by all network drivers).
iptraceNETWORK_BUFFER_RELEASED( pxBufferAddress ) Called when the network buffer at address pxBufferAddress is released back to the TCP/IP stack.
iptraceNETWORK_BUFFER_OBTAINED( pxBufferAddress ) Called when the network buffer at address pxBufferAddress is obtained from the TCP/IP stack by an RTOS task.
iptraceNETWORK_BUFFER_OBTAINED_FROM_ISR( pxBufferAddress ) Called when the network buffer at address pxBufferAddress is obtained from the TCP/IP stack by an interrupt service routine.
iptraceFAILED_TO_OBTAIN_NETWORK_BUFFER() Called when a task attempts to obtain a network buffer, but a buffer was not available even after any defined block period.
iptraceFAILED_TO_OBTAIN_NETWORK_BUFFER_FROM_ISR() Called when an interrupt service routine attempts to obtain a network buffer, but a buffer was not available.
iptraceCREATING_ARP_REQUEST( ulIPAddress ) Called when the IP generates an ARP request packet.
iptraceARP_TABLE_ENTRY_WILL_EXPIRE( ulIPAddress ) Called when an ARP request is about to be sent because the entry for the IP address ulIPAddress in the ARP cache has become stale. ulIPAddress is expressed as a 32-bit number in network byte order.
iptraceARP_TABLE_ENTRY_EXPIRED( ulIPAddress ) Called when the entry for the IP address ulIPAddress in the ARP cache is removed. ulIPAddress is expressed as a 32-bit number in network byte order.
iptraceARP_TABLE_ENTRY_CREATED( ulIPAddress, ucMACAddress ) Called when a new entry in the ARP table is created to map the IP address ulIPAddress to the MAC address ucMACAddress. ulIPAddress is expressed as a 32-bit number in network byte order. ucMACAddress is a pointer to an MACAddress_t structure.
iptraceSENDING_UDP_PACKET( ulIPAddress ) Called when a UDP packet is sent to the IP address ulIPAddress. ulIPAddress is expressed as a 32-bit number in network byte order.
iptracePACKET_DROPPED_TO_GENERATE_ARP( ulIPAddress ) Called when a packet destined for the IP address ulIPAddress is dropped because the ARP cache does not contain an entry for the IP address. The packet is automatically replaced by an ARP packet. ulIPAddress is expressed as a 32-bit number in network byte order.
iptraceICMP_PACKET_RECEIVED() Called when an ICMP packet is received.
iptraceSENDING_PING_REPLY( ulIPAddress ) Called when an ICMP echo reply (ping reply) is sent to the IP address ulIPAddress in response to an ICMP echo request (ping request) originating from the same address. ulIPAddress is expressed as a 32-bit number in network byte order.
traceARP_PACKET_RECEIVED() Called when an ARP packet is received, even if the local network node is not involved in the ARP transaction.
iptracePROCESSING_RECEIVED_ARP_REPLY( ulIPAddress ) Called when the ARP cache is about to be updated in response to the reception of an ARP reply. ulIPAddress holds the ARP message's target IP address (as a 32-bit number in network byte order), which may not be the local network node (depending on the FreeRTOSIPConfig.h settings).
iptraceSENDING_ARP_REPLY( ulIPAddress ) An ARP reply is being sent in response to an ARP request from the IP address ulIPAddress. ulIPAddress is expressed as a 32-bit number in network byte order.
iptraceFAILED_TO_CREATE_SOCKET() A call to FreeRTOS_socket() failed because there was insufficient FreeRTOS heap memory available for the socket structure to be created.
iptraceRECVFROM_DISCARDING_BYTES( xNumberOfBytesDiscarded ) FreeRTOS_recvfrom() is discarding xNumberOfBytesDiscarded bytes because the number of bytes received is greater than the number of bytes that will fit in the user supplied buffer (the buffer passed in as a FreeRTOS_recvfrom() function parameter).
iptraceETHERNET_RX_EVENT_LOST() Called when a packet received by the network driver is dropped for one of the following reasons: There is insufficient space in the network event queue (see the ipconfigEVENT_QUEUE_LENGTH setting in FreeRTOSIPConfig.h), the received packet has an invalid data length, or there are no network buffers available (see the ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS setting in FreeRTOSIPConfig.h). Note this macro is called by the network driver rather than the TCP/IP stack and may not be called at all by drivers provided by third parties.
iptraceSTACK_TX_EVENT_LOST( xEvent ) Called when a packet generated by the TCP/IP stack is dropped because there is insufficient space in the network event queue (see the ipconfigEVENT_QUEUE_LENGTH setting in FreeRTOSIPConfig.h).
iptraceNETWORK_EVENT_RECEIVED( eEvent ) Called when the TCP/IP stack processes an event previously posted to the network event queue. eEvent will be one of the following values:
  • eNetworkDownEvent - The network interface has been lost and/or needs [re]connecting.
  • eNetworkRxEvent - The network interface has queued a received Ethernet frame.
  • eARPTimerEvent - The ARP timer expired.
  • eStackTxEvent - The software stack has queued a packet to transmit.
  • eDHCPEvent - Process the DHCP state machine.
Note the events are defined by the private eIPEvent_t type which is not generally accessible.
iptraceBIND_FAILED( xSocket, usPort ) A call to FreeRTOS_bind() failed. usPort is the port number the socket xSocket was to be bound to.
iptraceDHCP_REQUESTS_FAILED_USING_DEFAULT_IP_ADDRESS( ulIPAddress ) Called when the default IP address is used becuase an IP address could not be obtained from a DHCP. ulIPAddress is expressed as a 32-bit number in network byte order.
iptraceSENDING_DHCP_DISCOVER() Called when a DHCP discover packet is sent.
iptraceSENDING_DHCP_REQUEST() Called when a DHCP request packet is sent.
iptraceNETWORK_INTERFACE_TRANSMIT() Called when a packet is sent to the network by the network driver. Note this macro is called by the network driver rather than the TCP/IP stack and may not be called at all by drivers provided by third parties.
iptraceNETWORK_INTERFACE_RECEIVE() Called when a packet is received from the network by the network driver. Note this macro is called by the network driver rather than the TCP/IP stack and may not be called at all by drivers provided by third parties.
iptraceSENDING_DNS_REQUEST() Called when a DNS request is sent.
iptraceWAITING_FOR_TX_DMA_DESCRIPTOR() Called when a transmission at the network driver level cannot complete immediately because the driver is having to wait for a DMA descriptor to become free. Try increasing the configNUM_TX_ETHERNET_DMA_DESCRIPTORS setting in FreeRTOSConfig.h (if it exists for the network driver being used).
iptraceDHCP_SUCCEDEED( ulOfferedIPAddress ) Called when DHCP negotiation is complete and the IP address in ulOfferedIPAddress is offered to the device.
iptraceDROPPED_INVALID_ARP_PACKET( pxARPHeader ) Called when an ARP packet is dropped due to invalid protocol and hardware fields in the header at address pxARPHeader.
iptraceFAILED_TO_CREATE_EVENT_GROUP() Called when an event group could not be created, possibly due to insufficient heap space, during new socket creation.
iptraceMEM_STATS_CLOSE() Should be called by the application when the collection of memory statistics should be stopped.
iptraceMEM_STATS_CREATE( xMemType, pxObject, uxSize ) Called when an object at address pxObject of type xMemType and size uxSize has been allocated from the heap.
iptraceMEM_STATS_DELETE( pxObject ) Called when an object at address pxObject has been deallocated and the memory has been returned to the heap.
iptraceNETWORK_INTERFACE_INPUT( uxDataLength, pucEthernetBuffer ) Called when a packet of length uxDataLength and with the contents at address pucEthernetBuffer has been received.
iptraceNETWORK_INTERFACE_OUTPUT( uxDataLength, pucEthernetBuffer ) Called when a packet of length uxDataLength and with the contents at address pucEthernetBuffer has been sent.
iptraceNO_BUFFER_FOR_SENDTO() Called when a call to FreeRTOS_sendto() tries to allocate a buffer, but a buffer was not available even after any defined block period.
iptraceRECVFROM_INTERRUPTED() Called when a blocking call to FreeRTOS_recvfrom() is interrupted through a call to FreeRTOS_SignalSocket().
iptraceRECVFROM_TIMEOUT() Called when FreeRTOS_recvfrom() gets no data on the given socket even after any defined block period.
iptraceSENDTO_DATA_TOO_LONG() Called when the data requested to be sent using a call to FreeRTOS_sendto() is too long and could not be sent.
iptraceSENDTO_SOCKET_NOT_BOUND() Called when the socket used in the call to FreeRTOS_sendto() is not already bound to a port.







Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.