Table of Contents

Table of Chapters

Chapter 6 - NICHETOOL: DIAGNOSTICS, ETC.

6.0. OVERVIEW

This document describes how to use NicheTool, InterNiche Technologies' customer-extendible diagnostic suite for debugging, monitoring, and runtime configuration of the TCP/IP stack and applications. NicheTool:

The NicheTool is a command line driven interface and requires that the InterNiche TCP/IP stack software be installed and operational in order to function properly.

6.1. COMMAND DESCRIPTIONS

This section describes the various line commands and is organized into two of utility: General commands and Diagnostic commands. Note that there is a third category of menus available, though they are application-specific and are included only if you have licensed and included the additional protocols from InterNiche as a part of your system.

6.1.1 The InterNiche Console

When the stack executable is run, it initializes and presents the INET> prompt on the system console. The line commands can be displayed as Help menu lists or simply entered directly at the prompt. The device on which this prompt is displayed is determined by the porting engineer and will vary depending on the nature of the target system. For purpose of this discussion we will refer to this user interface input/output device as the target system's "console".

6.1.2 Runtime Commands

Commands are available when the option IN_MENUS is defined in the file ipport.h . It is recommended that this define be disabled for shipping product as it presents a possible security hole, increases memory requirements and has not necessarily been subjected to the level reentrancy checking appropriate for a commercial product.

The InterNiche user interface prompts the user with the following prompt:

INET>_

At this point the user can type any of dozens of commands for execution by the agent. Our command interface is a "smart" interface and only requires that you enter enough of the command name to uniquely identify it. Many commands can also take 1 or more parameters typed on the command line.

As an introduction to these commands, an annotated session transcript is reproduced here. Some commonly used commands are host and ping.

INET> host 10.0.0.5

The host command sets a default remote host IP address for those commands that require a remote host to be specified.

INET> ping
ping 0 to 10.0.0.5: ping 1 sent…
got ping reply; len:62 seq 0 from 10.0.0.5

The ping command checks if a host is reachable or not.

INET> ping
INET> quit

Note: In most environments, this will terminate the stack and application execution.

6.2. GENERAL COMMANDS

6.2.1 Help

The Help menu for the InterNiche console displays a list of available commands. The commands can be brought up on the display by entering help or a question mark, ?. The help command by itself displays the general commands. When given diagnostic as an argument, it lists the diagnostic command set.

The "Also try" line at the bottom of the Help menu lists the other InterNiche modules that are installed and for which diagnostic help is available.

Command

help

Syntax

help [submenu]

Parameters

generalDisplays the most commonly used commands
diagnosticDisplays commands that are used for reporting statistics
module_nameThe remaining parameters in the help list will vary according to which options were included in your build.

Description

This command is used to list all the other commands. When typed by itself, the general commands are listed. When followed by diagnostic or a specific configuration name the appropriate command sets are listed. Similarly, help snmp would display the commands for SNMP.

A question mark, '?' is the same as help.

Parameters can be abbreviated to as few as a single letter when the meaning is unambiguous.

6.2.2 General

Command

state - show current setup

Parameters

None

Description

Displays current state information, interfaces, and default settings.

Example

INET> state
iface 0- IP addr:10.0.0.53  subnet:255.0.0.0  gateway:10.0.0.1
current tick count 10372370
Task wakeups:netmain: 51156
nettick: 5185540
keyboard: 5185496

Command

quit - quit station program

Parameters

None

Description

quit will cause the application to do a clean exit of the stack and application to the OS, bootloader, or underlying monitor.

Example

INET> quit
c:\> _

Command

version - display version information

Parameters

None

Description

Displays current version of the InterNiche TCP/IP stack.

Example

INET> version
InterNiche NicheLite TCP/IP for Coldfire, v3.0
INET> _

6.3. DIAGNOSTIC COMMANDS

When IN_MENUS is defined in ipport.h, the Diagnostic Command menu is available and the list will vary according to what other options have been defined in the file ipport.h for inclusion. If NET_STATS is defined, NicheTool will have the ability to display certain statistics.

Command

help diagnostic

Parameters

diagnostic

Description

Used as a parameter for Help, this command displays a list of the diagnostic commands that return current statistical data concerning the features included in your build.

Example

INET> ? diag
SNMP Station: diagnostic commands:
   arps     - display ARP stats and table
   buffers  - display free q buffer stats
   queues   - dump packet buffer queues
   dbytes   - dump block of memory
   debug    - set IP stack debug tracing
   dtrap    - try to hook debugger
   dir      - directory of VFS files
   iface    - display net interface stats
   linkstats - display link layer specific stats
   memory   - list currently alloced memory
   tcp      - display TCP stats
   sockets  - display socket list
   tbconn   - tcp BSD connection stats
   tbsend   - tcp BSD send stats
   tbrcv    - tcp BSD receive stats
   allocsize - set size for alloc() breakpoint
   ipstat   - display IP layer stats
   icmpstat - display ICMP layer stats
   udp      - display UDP layer stats
   upcall   - trace received packets
   tkstats  - tasking system status
   dcstats  - DHCP Client statistics
   users    - list all users
   adduser  - add a new user

Command

buffers - display allocated packet buffer statistics

Parameters

None

Description

Shows statistics for the allocated buffers.

Example

INET> buffers
PACKET    len  buffer    que data offset 0
8100112c,1536,81001188,big:00 00 ff ff ff ff ff ff 00 48 54 8e .........HT.
810017a8,1536,81001804,big:00 00 ff ff ff ff ff ff 00 0d 60 78 ..........`x
81001e24,1536,81001e80,big:00 00 ff ff ff ff ff ff 00 a0 cc e0 ............
810024a0,1536,810024fc,big:00 00 ff ff ff ff ff ff 00 a0 cc e0 ............
81002b1c,1536,81002b78,big:00 00 ff ff ff ff ff ff 00 0c 6e 6c ..........nl
81003198,1536,810031f4,big:00 00 ff ff ff ff ff ff 00 10 75 00 ..........u.
81003814,1536,81003870,big:00 00 ff ff ff ff ff ff 00 a0 cc e0 ............
81003e90,1536,81003eec,big:00 00 ff ff ff ff ff ff 00 a0 cc e0 ............
8100450c, 128,81004568,lil:00 00 ff ff ff ff ff ff 00 14 2a 05 ..........*.
81004608, 128,81004664,lil:00 00 ff ff ff ff ff ff 00 11 5b 4b ..........[K
81004704, 128,81004760,lil:00 00 ff ff ff ff ff ff 00 11 11 be ............
81004800, 128,8100485c,lil:00 00 00 0f 66 92 2c ff 00 50 c2 48 ....f.,..P.H
810048fc, 128,81004958,lil:00 00 ff ff ff ff ff ff 00 50 c2 48 .........P.H
810049f8, 128,81004a54,lil:00 00 00 50 c2 48 5a 86 00 0f 66 92 ...P.HZ...f.
81004af4, 128,81004b50,lil:00 00 00 50 c2 48 5a 86 00 0f 66 92 ...P.HZ...f.
81004bf0, 128,81004c4c,lil:00 00 ff ff ff ff ff ff 00 0e 35 1f ..........5.
81004cec, 128,81004d48,lil:00 00 00 50 c2 48 5a 86 00 0f 66 92 ...P.HZ...f.
81004de8, 128,81004e44,lil:00 00 00 0f 66 92 2c ff 00 50 c2 48 ....f.,..P.H
81004ee4, 128,81004f40,lil:00 00 ff ff ff ff ff ff 00 11 5b 4b ..........[K
....press any key for more (ESC to break)....
INET> _

Command

queues - dump packet buffer queues

Parameters

None

Description

The first two lines provide tally information about the big and little packet buffer free queues. The len field gives an instantaneous snapshot of how many packet buffers of each type are in the queues. The min field shows how low len has gotten, indicating whether or not the application is running out of packet buffers. When min is 0 it means that the stack has run out of packet buffers in the listed queue type at least once since the stack was initialized.

The line about rcvdq is telling you how big the packet receive queue has gotten. rcvdq len tells you that you have packets in the receive queue that have not yet been processed by the IP layer. rcvdq max lets you know how high len has gotten to be since boot time. A high value in rcvdq max would be an indication that the stack isn't getting around to processing the receive queue in a timely manner.

Example

INET> queue
bigfreeq: head:8100112c, tail:81003e90, len:8, min:3, max:8
lilfreeq: head:81004704, tail:81004608, len:12, min:4, max:12
rcvdq: head:0, tail:0, len:0, min:0, max:8
INET> _

Command

dbytes - dump block of memory

Parameters

location [length]

Description

This command helps in debugging.

The location parameter us a single 32 bit number that indicates the address.

Example

INET> dbytes
enter memory location in hex, followed by optional length.
INET> dbytes 0x0 100
18 f0 9f e5 18 f0 9f e5 18 f0 9f e5 18 f0 9f e5 ................
18 f0 9f e5 00 00 a0 e1 f0 ff 1f e5 18 f0 9f e5 ................
40 00 00 80 10 6a 01 80 0c 6a 01 80 08 6a 01 80 @....j...j...j..
04 6a 01 80 00 00 00 00 00 6a 01 80 20 ca 00 80 .j.......j.. ...
b0 00 9f e5 aa 10 a0 e3 55 20 a0 e3 24 30 a0 e3 ........U ..$0..
04 30 80 e5 01 30 a0 e3 00 30 80 e5 0c 10 80 e5 .0...0...0......
0c 20 80 e5 08 30 90 e5 01 3b 13 e2 fc ff ff 0a . ...0...;......
03 30 a0 e3 00 30 80 e5 0c 10 80 e5 0c 20 80 e5 .0...0....... ..
74 00 9f e5 04 10 a0 e3 04 10 80 e5 02 10 a0 e3 t...............
00 10 80 e5 64 00 9f e5 db f0 21 e3 00 d0 a0 e1 ....d.....!.....
04 00 40 e2 d7 f0 21 e3 00 d0 a0 e1 04 00 40 e2 ..@...!.......@.
d1 f0 21 e3 00 d0 a0 e1 04 00 40 e2 d2 f0 21 e3 ..!.......@...!.
00 d0 a0 e1 80 00 40 e2 d3 f0 21 e3 00 d0 a0 e1 ......@...!.....
04 00 40 e2 10 f0 21 e3 00 d0 a0 e1 20 00 9f e5 ..@...!..... ...
01 00 10 e3 1c e0 9f 05 1c e0 9f 15 10 ff 2f e1 ............../.
fe ff ff ea fe e7 c0 46 80 c0 1f e0 00 c0 1f e0 .......F........
INET> _

Command

debug - set IP stack debug tracing

Parameters

[bitmask]

Description

This diagnostic command sets an internal flag which results in the application printing out scores of status messages as packets are received or sent up and down the protocol stack. This can be helpful for detecting at exactly what protocol stack layer a bad packet's error occurs. Often the nature of the error will be reported, i.e. "bad cksum".

The debug command accepts an optional parameter, which is a hex number that represents a bit mask in which each bit specifies whether a particular type of IP stack tracing will occur. Below are the definitions of the various bits:

BUGHALT0x01halt on a gross applications level error that is detected in the network code
DUMP0x02Works in conjunction with other options:
BUGHALT - Dump all arriving packets
PROTERR - Dump header for level of error
NETTRACE, etc. - Dump headers at trace level
INFOMSG0x04Print general informational messages
NETERR0x08Display net interface error messages
PROTERR0x10Display protocol level error messages
NETRACE0x20Trace packet in link level net layer
TMO0x40Print message on timeout
APTRACE0x80Trace packet through application
TPTRACE0x100Transport protocol (UDP/TCP/RVD) trace
IPTRACE0x200Trace packet in internet layer
UPCTRACE0x400Trace upcall progress - DANGEROUS!

Example

INET> debug
IP stack debug tracing on
INET> debug
IP stack debug tracing off
INET> _

See Also

upcall - Debug tracing will not occur on packets being processed in ISR context unless both these options are enabled.

Command

dtrap - try to hook debugger

Parameters

None

Description

dtrap causes a call to the porting engineer provided dtrap() function to occur.

Example

INET> dtrap
???
INET> _

Command

dump - hexdump incoming packets

Parameters

None

Description

This dumps the SNMP protocol portion of all packets received and sent. It ignores other protocols such as ARP and PING.

Example

INET> dump
Packet hex dumping enabled
INET>
INET> host 10.0.0.1
active host number set to 10.0.0.1
INET> dump
Packet hex dumping enabled
INET> dump
Packet hex dumping disabled
INET> _

Known Issues

With some Ethernet drivers this can hang the system after a received packet is dumped. It is reliable when used on the loopback driver.

Command

linkstats - display link layer specific statistics

Parameters

An optional interface number

Description

This command displays statistics for the hardware associated with the given interface. The format, content, and accuracy of these statistics will vary from link driver to link driver. This command differs from the iface command in that these counters are generally read from the hardware driver, and are maintained since the driver was installed, not since the station started as is the case with the iface counters. Exceptions to this principle are the upcalls, pkts dropped, and pktdrvq.

In general, packet counts should be obtained from the iface command, since those counters are well defined (by MIB-2) and are uniform across all devices.

Example

INET> linkstats
Interrups: rx:51245, tx:552 alloc:551, total:10377516
coll1:0 collx:0 overrun:526
Sendq max:2, current 0. IObase: 0x82000300 ISR 0
Tx Status: 0x0081 TxENA: On Pad:On
Rx Status: 0x0300 RxENA: On 
CTR: 0x1af0
Int MSK: 0xf3 Status:0x0c Tx Alloc, Tx FIFO empty, 
INET> _

See Also

iface

Command

allocsize - set size for alloc() breakpoint

Parameters

Number of bytes to be allocated

Description

The stack code expects the porting engineer to provide an implementation of a function called npalloc() that the stack uses for memory allocation. npalloc() take a single parameter which specifies the number of bytes to be allocated by the call.

Notes

This capability may not be implemented in all ports.

Example

INET> allocsize 128
malloc trap size set to 128
INET> _

Command

upcall - trace received packets

Parameters

None

Description

Enables protocol stack trace reporting on incoming packets. upcall toggles the UPCTRACE bit in the tracing bit mask that is affected by the debug command. Its just a shorthand way of setting this one particular bit.

Example

INET> upcall
Upcall debugging enabled
INET> _

See Also

debug

6.3.1 Statistics

NET_STATS must be defined in ipport.h for the features in this section to be available.

Command

arps - display ARP statistics and table

Parameters

None

Description

The ARP command displays some arp statistics and dumps data from the entries in the current ARP table. The most interesting fields are the MAC address and the associated IP address. The entry "X)" field is the position in the ARP table of this entry. Entries are allocated last first, so this compile has 8 ARP entries (0-7). iface is the logical interface the arp was resolved on. pend indicates whether the stack is holding an outgoing packet awaiting the results of an arp reply. It will almost always be N for "no". The time is the internal timestamp when the ARP reply was last referenced. This is kept so that if we run out of room in the ARP table, we can delete the entry that has not been used for the longest time.

This command is included in the menu list if NET_STATS was defined in ipport.h.

Example

INET> host 10.0.0.80
active host number set to 192.9.200.3
INET> p
ping 0 to 10.0.0.80: Arping for host...
got ping reply; len :62 seq 0 from 192.9.200.3
ping complete; send 1, received 1
INET> arp
arp Requests In: 75,   out: 28
arp Replys   In: 8,   out: 75
X)  MAC Address   iface pend    IP      ctime    ltime
7)  0080C8-E2AF2A   1   N   10.0.0.80   4669168  4670448
INET> _

Command

ipstat - display IP layer statistics

Parameters

None

Description

ipstat displays the standard IP SNMP MIB statistics.

This command is included in the menu list if NET_STATS was defined in ipport.h.

Example

INET> ipstat
IP MIB statistics:
Gateway: NO     default TTL: 30
rcv:  total: 39002    header err: 0    address err: 0
rcv:  unknown Protocols: 0    delivered: 39002
send: total: 2360    discarded: 0     No routes: 0
Routing; forwarded: 0    discarded: 0
Recvd fragments: 0, Frames reassembled: 0
Pkts fragmented: 0, Fragments sent: 0, dropped: 0
Reasm.Timeouts: 0,  Reasm.Errors: 0
INET> _

Command

icmpstat

- display ICMP layer statistics

Parameters

None

Description

icmpstat displays the standard ICMP SNMP MIB statistics

This command is included in the menu list if NET_STATS was defined in ipport.h.

Example

INET> icmpstat
ICMP layer stats:
icmpInMsgs 1    icmpInErrors 0
In counters: DestUnreach 0   TimeExceed 0   ParmProb 0
SrcQuench 0   Redirect 0   Echo(ping) 0   EchoReps 1
Timestmp  0   TStmpRep 0    AddrMasks 0   AddrMaskRep 0
icmpOutMsgs 2    icmpOutErrors 0
Out counts:  DestUnreach 2   TimeExceed 0   ParmProb 0
SrcQuench 0   Redirect 0   Echo(ping) 0   EchoReps 0
Timestmp  0   TStmpRep 0    AddrMasks 0   AddrMaskRep 0
INET> _

Command

udp - display UDP layer statistics

Parameters

None

Description

The udp command displays the standard UDP SNMP MIB statistics.

This command is included in the menu list if NET_STATS was defined in ipport.h.

Example

INET> udp
UDP MIB dump:
In: Good: 26    No Port: 2     Bad: 0
Out: 26
INET> _

6.3.2 DNS

DNS_CLIENT and NET_STATS must be defined in ipport.h for the features in this section to be available.

Command

dnsstats - display DNS setup and statistics

Parameters

None

Description

This command shows statistics about the DNS Client. It shows a list of DNS servers that the client is configured to know about, a listing of the client side DNS cache which is a kind of a history of DNS resolutions that the client has performed, and some general DNS statistics.

This command is included in the menu list if DNS_CLIENT and NET_STATS was defined in ipport.h.

Example

INET> dnsstats
DNS servers:0.0.0.0 0.0.0.0 0.0.0.0 DNS cache:
name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0
name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0
name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0
name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0
name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0
name: , IP: 0.0.0.0, retry:0, ID:0, rcode:0, err:0
protocol/implementation runtime errors:0
requests sent:0
replys received:0
usable replys:0
total reties:0
timeouts:0
INET> _

6.3.3 TCP

Both INCLUDE_TCP and NET_STATS must be defined in ipport.h for the commands in this section to be available.

Command

tcp

- display TCP statistics

Parameters

None

Description

Displays the standard TCP SNMP MIB statistics.

This command is included in the menu list if INCLUDE_TCP and NET_STATS was defined in ipport.h.

Example

INET> tcp
tcpRtoAlgorithm 0,  tcpRtoMin 0
tcpRtoMax 0,    tcpMaxConn 0
tcpActiveOpens 11,  tcpPassiveOpens 6
tcpAttemptFails 0,  tcpEstabResets 3
tcpCurrEstab 0,  tcpInSegs 2344
tcpOutSegs 2567,  tcpRetransSegs 16
tcpInErrs 0,    tcpOutRsts 0
INET> _

6.3.4 Memory - define MEM_BLOCKS in ipport.h

Command

memory - list currently allocated memory

Parameters

None

Example

INET> memory
free list:
0: at 8100513c, 0x3aec8 bytes
heap; start: 262132,  min: 241168,  current: 241352;  actual: 241352 alloc faile
d: 0
wrappers: allocs: 1437,  frees: 1390,  allocbytes: 236244   freebytes: 216840
alloced: current bytes: 19404  max bytes: 19560
biggest block: 2048,  allocs failed: 0
Block sizes, in size[alloc - free = cur] format:
   40[3-0=3]               2048[2-0=2]                 60[20-0=20]            
 1541[8-0=8]                133[12-0=12]               32[2-0=2]              
  156[1403-1403=0]    
INET> _

Description

Dumps address and size of all allocated but un-freed memory since the application started. This is useful in detecting memory leaks during ports on the InterNiche SNMP API when no other such tools are available.

This command is included in the menu list if MEM_BLOCKS was defined in ipport.h.