Enabling debug output

Document created by jorge_plascencia Employee on Apr 26, 2016
Version 1Show Document
  • View in full screen mode

LWIP debug output or application messages can be routed out to one of the serial ports by configuring the debug options.

Enabling debug output in LWIP

To enable debug code in LWIP, the "LWIP_DEBUG" flag needs to be defined when compiling the LWIP code. This can usually be done by using the "-D" option to define the flag as part of the argument list for the compiler. For example in the Keil tools, you can add the define C/C++ tab of the target options dialog.

To enable specific debug messages in LWIP, just set the specific define value for the LWIP *_DEBUG value to " LWIP_DBG_ON". A full list of debug defines that can be enabled can be found in the opts.h file. Just copy the defines for the debug messages you want to enable into the lwipopts.h file for your project and enable them there. A few examples are shown below.

#define TCP_DEBUG                       LWIP_DBG_ON
#define ETHARP_DEBUG                    LWIP_DBG_ON
#define PBUF_DEBUG                      LWIP_DBG_ON

Selecting debug output

The UART channel used for debug outputcan be selected by setting the UART_REDIRECT define to the UART number. On the LPC177x_8x devices, setting this to 0, 1, or 2 will enable output for UART ports 0, 1, or 2, respectively. You can completely disable output (while keep the debug code inside LWIP) by setting UART_REDIRECT to -1.
As of release v1.01, simply enabling LWIP_DEBUG as the compilation define will automatically select the right UART for debug output. You can still override the UART for output if needed, but will need to edit the UART in the debug framework file.

Caveats of enabling debug output

Enabling debug output can add significant size to the generated code based on the debug options selected for the build. It will also slow down performance of the LWIP code due to required run-time checks and output. It's is recommended to enable debug support only if needed.

Enabling just the UART for debug output adds about 4KBytes to the code size and about 512 bytes to the data size. The UART driver uses a ring buffer for buffering debug output with the UART IRQ to feed that data to the UART. The ring buffer size can be changed by changing the "UART_RING_BUFSIZE" define value in the serial.c file. Note: The call to initialize the debug framework used for LWIP debug output and printf() is active in the examples by default. Just remove the call to debug_frmwrk_init() in the examples to save some additional code and data memory. You may have also to remove the redirect.c file from the project for this change.

Enabling debug output in the LWIP code uses a varying amount of memory based on which LWIP *_DEBUG defines are enabled. Without LWIP debug output enabled and the options selected below, the code size is increased by an additional 23.5KBytes and the data size increased by 1.6KBytes.

#define LWIP_DEBUG
#define TCP_DEBUG                       LWIP_DBG_ON
#define ETHARP_DEBUG                    LWIP_DBG_ON
#define PBUF_DEBUG                      LWIP_DBG_ON
#define IP_DEBUG                        LWIP_DBG_ON
#define TCPIP_DEBUG                     LWIP_DBG_ON
#define DHCP_DEBUG                      LWIP_DBG_ON
#define UDP_DEBUG                       LWIP_DBG_ON

Note memory usage was checked at the 'default' compiler optimization setting.

Example debug output

Some example debug output use for capturing TCPIP, ethernet ARP, PBUF allocaiton and de-allocation, etc. are shown in the example output below captured from a LWIP run.

Ethernet link not yet detected, will continue
Starting LWIP ping server...
dhcp_start(netif=1000eddc) en0
dhcp_start(): starting new DHCP client
dhcp_start(): allocated dhcpudp_bind(ipaddr = 0.0.0.0, port = 68)
udp_bind: bound to 0.0.0.0, port 68
udp_connect: connected to 0.0.0.0,port 68
dhcp_start(): starting DHCP configuration
dhcp_discover()
pbuf_alloc(length=308)
pbuf_alloc(length=308) == 200018b4
transaction id xid(abcd0001)
dhcp_discover: making request
dhcp_discover: realloc()ing
dhcp_discover: sendto(DISCOVER, IP_ADDR_BROADCAST, DHCP_SERVER_PORT)
pbuf_header: old 200018fc new 200018f4 (8)
udp_send: added header in given pbuf 200018b4
udp_send: sending datagram of length 316
udp_send: UDP packet length 316
udp_send: UDP checksum 0xdee0
udp_send: ip_output_if (,,,,IP_PROTO_UDP,)
pbuf_header: old 200018f4 new 200018e0 (20)
ip_output_if: en0
IP header:
+-------------------------------+
| 4 | 5 |  0x00 |       336     | (v, hl, tos, len)
+-------------------------------+
|        0      |000|       0   | (id, flags, offset)
+-------------------------------+
|  255  |   17  |    0xba9d     | (ttl, proto, chksum)
+-------------------------------+
|    0  |    0  |    0  |    0  | (src)
+-------------------------------+
|  255  |  255  |  255  |  255  | (dest)
+-------------------------------+
netif->output()pbuf_header: old 200018e0 new 200018d2 (14)
etharp_send_ip: sending packet 200018b4
dhcp_discover: deleting()ing
pbuf_free(200018b4)
pbuf_free: deallocating 200018b4
dhcp_discover: SELECTING
dhcp_discover(): set request timeout 2000 msecs
tcp_bind: bind to port 7
dhcp_discover()
pbuf_alloc(length=308)
pbuf_alloc(length=308) == 200018b4
transaction id xid(abcd0002)
dhcp_discover: making request
dhcp_discover: realloc()ing
dhcp_discover: sendto(DISCOVER, IP_ADDR_BROADCAST, DHCP_SERVER_PORT)
pbuf_header: old 200018fc new 200018f4 (8)
udp_send: added header in given pbuf 200018b4
udp_send: sending datagram of length 316
udp_send: UDP packet length 316
udp_send: UDP checksum 0xdde0
udp_send: ip_output_if (,,,,IP_PROTO_UDP,)
pbuf_header: old 200018f4 new 200018e0 (20)
ip_output_if: en0
IP header:
+-------------------------------+
| 4 | 5 |  0x00 |       336     | (v, hl, tos, len)
+-------------------------------+
|        1      |000|       0   | (id, flags, offset)
+-------------------------------+
|  255  |   17  |    0xba9c     | (ttl, proto, chksum)
+-------------------------------+
|    0  |    0  |    0  |    0  | (src)
+-------------------------------+
|  255  |  255  |  255  |  255  | (dest)
+-------------------------------+
netif->output()pbuf_header: old 200018e0 new 200018d2 (14)
etharp_send_ip: sending packet 200018b4
dhcp_discover: deleting()ing
pbuf_free(200018b4)
pbuf_free: deallocating 200018b4
dhcp_discover: SELECTING
dhcp_discover(): set request timeout 2000 msecs
etharp_request: sending ARP request.
pbuf_alloc(length=42)
pbuf_alloc(length=42) == 200018b4
etharp_raw: sending raw ARP packet.
pbuf_free(200018b4)
pbuf_free: deallocating 200018b4
pbuf_alloc(length=594)
pbuf_alloc(length=594) == 20004cc0
ethernet_input: dest:00:60:37:12:34:56, src:00:26:f3:a2:6b:b2, type:800
pbuf_header: old 20000050 new 2000005e (-14)
ip_input: iphdr->dest 0x1d0a010a netif->ip_addr 0x0 (0x0, 0x0, 0x1d0a010a)
ip_input: UDP packet to DHCP client port 68
ip_input: DHCP packet accepted.
ip_input:
IP header:
+-------------------------------+
| 4 | 5 |  0x00 |       576     | (v, hl, tos, len)
+-------------------------------+
|        0      |000|       0   | (id, flags, offset)
+-------------------------------+
|   64  |   17  |    0x508e     | (ttl, proto, chksum)
+-------------------------------+
|   10  |    1  |   10  |    1  | (src)
+-------------------------------+
|   10  |    1  |   10  |   29  | (dest)
+-------------------------------+
ip_input: p->len 576 p->tot_len 576
pbuf_header: old 2000005e new 20000072 (-20)
udp_input: received datagram of length 556
UDP header:
+-------------------------------+
|        67     |        68     | (src port, dest port)
+-------------------------------+
|       556     |     0x8880    | (len, chksum)
+-------------------------------+
udp (10.1.10.29, 68) <-- (10.1.10.1, 67)
udp_input: calculating checksum
pbuf_header: old 20000072 new 2000007a (-8)
dhcp_recv(pbuf = 20004cc0) from DHCP server 10.1.10.1 port 67
pbuf->len = 548
pbuf->tot_len = 548
searching DHCP_OPTION_MESSAGE_TYPE
DHCP_OFFER received in DHCP_SELECTING state
dhcp_handle_offer(netif=1000eddc) en0
dhcp_handle_offer(): server 0x010a010a
dhcp_handle_offer(): offer for 0x1d0a010a
dhcp_select(netif=1000eddc) en0
pbuf_alloc(length=308)
pbuf_alloc(length=308) == 200018b4
transaction id xid(abcd0003)
pbuf_header: old 200018fc new 200018f4 (8)
udp_send: added header in given pbuf 200018b4
udp_send: sending datagram of length 316
udp_send: UDP packet length 316
udp_send: UDP checksum 0x9958
udp_send: ip_output_if (,,,,IP_PROTO_UDP,)
pbuf_header: old 200018f4 new 200018e0 (20)
ip_output_if: en0
IP header:
+-------------------------------+
| 4 | 5 |  0x00 |       336     | (v, hl, tos, len)
+-------------------------------+
|        2      |000|       0   | (id, flags, offset)
+-------------------------------+
|  255  |   17  |    0xba9b     | (ttl, proto, chksum)
+-------------------------------+
|    0  |    0  |    0  |    0  | (src)
+-------------------------------+
|  255  |  255  |  255  |  255  | (dest)
+-------------------------------+
netif->output()pbuf_header: old 200018e0 new 200018d2 (14)
etharp_send_ip: sending packet 200018b4
pbuf_free(200018b4)
pbuf_free: deallocating 200018b4
dhcp_select: REQUESTING
dhcp_select(): set request timeout 2000 msecs
pbuf_free(20004cc0)
pbuf_free: 20004cc0 has ref 1, ending here.
pbuf_free(20004cc0)
pbuf_free: deallocating 20004cc0

Attachments

    Outcomes