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