`PacketWatcher`

Monitor ports for packets

PacketWatcher

Shortest form: pw.

Added to the shell at runtime rather than built in.

Packet watcher (“PW”) runs a background thread that receives packets sent to the CPU, keeps the most recent ones in a log and prints them as they arrive. pw is the short form of the command. With no argument it prints a status report, starting with <name>: Status: Running|Not Running. Mode RX|SOC. Buffering up to <n> packets. and followed by the rate limit, the report and dump options, and the RX channels in use.

Several sub-commands can be given on one line; they are processed left to right, e.g. pw log 5 report +decode start. Sub-command words must be written in full (case does not matter). The report and dump options count, decode, raw, dma and channel can be prefixed with + to set, - to clear, or nothing to toggle.

The status, count, report and dump forms are read-only. start and stop act on the receive layer that SONiC’s syncd uses, so they can break the host packet path. On a SONiC switch PW is not running: it is in rx mode with the default channels and a 1000 packets/s rate limit, and pw count shows no packets, because SONiC’s host traffic goes through KNET, not through PW. To look at packets on a SONiC switch, tcpdump on the EthernetN interface is safer (see KNET and the CPU port).

In PKTIO mode a different PacketWatcher runs. It has no channel, rate, interval, mode, hdr or debugpkt, although its built-in help still shows interval. It adds pmd [nonzero | all] to dump the RX metadata of each packet.

Unvalidated — Keep 5 packets, decode them, start

drivshell> packetwatcher log 5 report +decode start

Usage seen on other chips: packetwatcher log 5 report +dec start and pw report -raw (bcm cmd).

PacketWatcher start

Start the watcher thread. In the default rx mode it starts the receive layer if necessary and registers for all CPU queues. Packets it receives may no longer reach SONiC’s own handler, so host traffic can be disturbed. If PW is already running, it prints WARNING: Already running.

Unvalidated

drivshell> pw start

PacketWatcher stop

Stop the watcher and free its log. If PW is not running, it prints WARNING: Not running and still succeeds, so rc scripts carry on.

Warning

In rx mode, stopping PW also stops packet reception for the whole unit, which breaks SONiC’s host packet path.

Unvalidated

drivshell> pw stop

PacketWatcher count

Print the number of packets received, the count per DMA channel, the rate since the previous count, how many are logged and how many were discarded, e.g. Received <n> packets [(<c0>),<c1>,<c2>,<c3>,<c4>] (<r>/sec), last <m> packet(s) logged, <d> pkts discarded. Read-only.

Hardware-validated

drivshell> pw count
bcmPW.0: Received 0 packets [(0),0,0,0,0] (0/sec), last 0 packet(s) logged, 0 pkts discarded

PacketWatcher report [[+|-]<option> …]

Without options, show which report options are on and which are off. Otherwise set, clear or toggle count, decode, raw, dma and channel, which choose what PW prints for each packet it receives. pw quiet switches all reporting off.

Unvalidated

drivshell> pw report -raw +decode

PacketWatcher log <n | on | off>

Set how many packets are kept: on keeps 64, off keeps 1. This cannot be changed while PW runs. Without a value, the command prints Logging(<n>-packets).

Unvalidated

drivshell> pw log 32

PacketWatcher dump [<n>]

Print logged packets: all of them with no number, the first <n> for a positive number, or the last <n> for a negative one. pw dump options [[+|-]<option> …] shows or sets the options used by dump, which have the same names as for report. Read-only.

Unvalidated

drivshell> pw dump -5

PacketWatcher mode [soc | rx]

Show the mode, or choose between the receive layer (rx, the default) and driving the DMA channels directly (soc). The mode cannot be changed while PW runs. soc mode bypasses the receive layer that SONiC uses, so do not use it on a running switch.

Hardware-validated

drivshell> pw mode
Current mode is RX

PacketWatcher channel [<chan> …]

Show which RX DMA channels PW uses, or select channels. Selecting is refused while PW runs. pw stop goes back to the default channels.

Hardware-validated

drivshell> pw channel
bcmPW.0: RX on for channel(s):  -- using default --

PacketWatcher rate [<pps>]

Show or set the packet rate PW accepts, in packets per second. In rx mode the rate is applied when PW starts the receive layer.

Hardware-validated

drivshell> pw rate
bcmPW.0: Rate limit is currently 1000 pkts/sec.

PacketWatcher interval <us>

Set a wait, in microseconds, after each packet before the next DMA starts. soc mode only.

Unvalidated

drivshell> pw interval 100

PacketWatcher reset

Reset PW’s settings to their defaults. Refused while PW runs.

Unvalidated

drivshell> pw reset

PacketWatcher hdr <on | off>

Switch header dumping on or off. The built-in help does not mention this form.

Unvalidated

drivshell> pw hdr on

PacketWatcher debugpkt <on | off>

on makes the KNET kernel driver send a copy of every packet it handles to the receive layer, and starts PW if it is not running. off stops the copies. While this is on, every host packet is processed twice. See also knetctrl debugpkt.

Unvalidated

drivshell> pw debugpkt on

Built-in help

Parameters: [report +/-<values>] [stop|start] [count]
    log # - specifies # packets to remember
    dump [# | options] - # > 0 dumps # packets from start of log
                         # < 0 dumps last # packets
                         nothing - dumps all logs
                         options - count   - print packet # only
                                   decode  - attempt to decode packet
                                   raw     - dump raw byte stream (host order)
                                   dma     - dump DMA descriptors (SOC mode only)
                                   channel - dump DMA channel
                                   Prepend + to set, - to clear, nothing to toggle
    interval # - # us to wait after a packet arrives before next
            DMA starts (SOC mode only)
    report- count   - print packet # only
            decode  - attempt to decode packet
            raw     - dump raw byte stream (host order)
            dma     - dump DMA descriptors (SOC mode only)
            channel - dump DMA channel
            Prepend + to set, - to clear, nothing to toggle
    quiet - disable all reporting
    channel x [y z] - configure PW to use the specified RX channels
    rate    n       - Set the globally accepted pps rate
    start - start the PW-daemon
    stop  - stop the PW-daemon and deallocate log space
    count - print # packets received.
    reset - reinitialize configuration from bcm_rx_* API state
    mode [soc | rx]  - set packetwatcher mode
            With no parameters, reports current mode
            soc      - Use the soc layer calls directly
            rx       - Use the RX API
    debugpkt [on | off] - set KNET debug pkt mode

Built-in help

Parameters: [report +/-<values>] [stop|start] [count]
    log # - specifies # packets to remember
    dump [# | options] - # > 0 dumps # packets from start of log
                         # < 0 dumps last # packets
                         nothing - dumps all logs
                         options - count   - print packet # only
                                   decode  - attempt to decode packet
                                   raw     - dump raw byte stream (host order)
                                   pmd     - dump rx metadata and reason
                                   Prepend + to set, - to clear, nothing to toggle
    interval # - # us to wait after a packet arrives before next
            DMA starts (SOC mode only)
    report- count   - print packet # only
            decode  - attempt to decode packet
            raw     - dump raw byte stream (host order)
            pmd     - dump rx metadata and reason
            Prepend + to set, - to clear, nothing to toggle
    quiet - disable all reporting
    start - start the PW-daemon
    stop  - stop the PW-daemon and deallocate log space
    count - print # packets received.
    reset - reinitialize configuration