# 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:

- Instrumentation (or Agents) - built into all InterNiche products
- User Display - the command line interface to the Diagnostic environment
- Menu System - an online list of, and help for, our Diagnostic commands

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

general | Displays the most commonly used commands
diagnostic | Displays commands that are used for reporting statistics
module_name | The 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:

BUGHALT | 0x01 | halt on a gross applications level error that is detected in the network code
DUMP | 0x02 | Works in conjunction with other options: BUGHALT - Dump all arriving packets PROTERR - Dump header for level of error NETTRACE, etc. - Dump headers at trace level
INFOMSG | 0x04 | Print general informational messages
NETERR | 0x08 | Display net interface error messages
PROTERR | 0x10 | Display protocol level error messages
NETRACE | 0x20 | Trace packet in link level net layer
TMO | 0x40 | Print message on timeout
APTRACE | 0x80 | Trace packet through application
TPTRACE | 0x100 | Transport protocol (UDP/TCP/RVD) trace
IPTRACE | 0x200 | Trace packet in internet layer
UPCTRACE | 0x400 | Trace 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.