Real time embedded FreeRTOS RSS feed 
Homepage FreeRTOS+ Products FreeRTOS Labs Integration Services Contact / Enquiries

Embedded IP Stack Trace Hook Macros
For Debugging and Optimising FreeRTOS+UDP Behaviour

Description

Trace hook macros allow you to collect valuable data on the run-time behaviour of your networked enabled embedded application. The collected data can be used for debugging and optimisation purposes.

Key points of interest within the FreeRTOS+UDP source code contain empty macros that an application can re-define for the purpose of providing application specific trace functionality. The application need only implement the macros of particular interest.

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

The FreeRTOS Win32 simulator example (available on this website) uses the trace macros to collect IP stack run time information that can then be viewed using the UDP 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 IP stack.
iptraceNETWORK_BUFFER_OBTAINED( pxBufferAddress ) Called when the network buffer at address pxBufferAddress is obtained from the IP stack by an RTOS task.
iptraceNETWORK_BUFFER_OBTAINED_FROM_ISR( pxBufferAddress ) Called when the network buffer at address pxBufferAddress is obtained from the 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 xMACAddress_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 UDP packet destined for the IP address ulIPAddress is dropped because the ARP cache does not contain an entry for the IP address. The UDP 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_BUFFERS setting in FreeRTOSIPConfig.h). Note this macro is called by the network driver rather than the 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 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 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.
  • eEthernetRxEvent - 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 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 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 ]    [ FreeRTOS+ Sitemap ]    [ Main FreeRTOS Sitemap ]    [ ]


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