The FreeRTOS Ecosystem Showcase . . .
A Selection of Add-on and Complementary Products

 Real time embedded FreeRTOS RSS feed 
Homepage FreeRTOS+ Products FreeRTOS Labs Support Forum Contact / Enquiries

 FreeRTOS+POSIX:
 POSIX API for FreeRTOS
 FreeRTOS+FAT:
 Thread aware file system

TCP/IP Specific Trace Hook Macros
For Debugging and Optimising FreeRTOS+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+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+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. (_RB_ Is this a complete list? Are they all still valid?)

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).








[ Back to the top ]    [ About FreeRTOS ]    [ Privacy ]    [ FreeRTOS Labs Sitemap ]    [ Main FreeRTOS Sitemap ]    [ ]




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