How-To: eb-mon

Introduction

The original intention about this tool has been to get (simpler) access to data of the White Rabbit PTP core. But as the name suggests, this tool allows monitoring of all kind of diagnostic data.

• WRC PTP
• 1-wire temperature sensors and IDs
• statistics
  • WR time continuity (by comparing the advance of a eCPU clock with the WR clock)
  • eCPU (data bus) stalls
  • ECA input statistics

This is a read-only tool, no values are modified. Only exception: It is possible to (re)set statistics properties.

Usage

Usage: eb-mon [OPTION] <etherbone-device>

  -a               display gateware 'build type'
  -b<busIndex>     display ID (ID of slave on the specified 1-wire bus)
  -c<eb-device>    compare timestamp with the one of <eb-device> and display the result
  -d               display WR time
  -e               display etherbone version
  -f<familyCode>   specify family code of 1-wire slave (0x43: EEPROM; 0x28,0x42: temperature)
  -g               display WR statistics (lock, time continuity)
  -h               display this help and exit
  -i               display WR IP
  -j<cpu>          display lm32 stall info (default: j0) 
  -k               display 'ECA-Tap' statistics
  -l               display WR link status
  -m               display WR MAC
  -o               display offset between WR time and system time [ms]
  -s <secs> <cpu>  snoop for information continuously (and print warnings. THIS OPTION RESETS ALL STATS!)
  -t<busIndex>     display temperature of sensor on the specified 1-wire bus
  -u<index>        user 1-wire: specify WB device in case multiple WB devices of the same type exist (default: u0)
  -v               display verbose information
  -w<index>        WR 1-wire: specify WB device in case multiple WB devices of the same type exist (default: u0)
  -y               display WR sync status
  -z               display FPGA uptime [h]

  wrstatreset  <tWrObs> <tStallObs>  command clears WR statistics and sets observation times (default: 8 50000)
  ecatapreset  <lateOffset>          command resets ECA-Tap and sets offset for detection of late events (default: 0)
  ecatapclear  <clearFlag>           command clears ECA-Tap counters (b3: late count, b2: count/accu, b1: max, b0: min)
  ecatapenable                       command enables capture on ECA-Tap
  ecatapdisable                      command disables capture on ECA-Tap

Use this tool to get some info about WR enabled hardware.
Example1: 'eb-mon -v dev/wbm0' display typical information.
Example2: 'eb-mon -b0 -f0x43 dev/wbm0' read ID of EEPROM connected to 1st (user) 1-wire bus

When using option '-s<n>', the following information is displayed
eb-mon:    WR [ns]   | CPU stall[%]|                      [n(Hz)]   ECA                 [us(us)]
eb-mon:  lock +dt -dt|   max(  act)| nMessages( rate ) early late  min max avrge(act) ltncy(act)
eb-mon:     1  16   0| 32.71(17.87)|      2501(  69.0)     0    0  879 986   935(935)    65( 65)
            '   '   '      '     '           '      '      '    '    '   '     '   '      '   ' 
            '   '   '      '     '           '      '      '    '    '   '     '   '      '   '- actual latency
            '   '   '      '     '           '      '      '    '    '   '     '   '      '- latency
            '   '   '      '     '           '      '      '    '    '   '     '   '- actual average (dl - ts)
            '   '   '      '     '           '      '      '    '    '   '     '- average (dl - ts)
            '   '   '      '     '           '      '      '    '    '   '- max (dl - ts) since last 'early event'
            '   '   '      '     '           '      '      '    '    '- min (deadline - timestamp) since last 'late event'
            '   '   '      '     '           '      '      '    '- # of late messages
            '   '   '      '     '           '      '       - # of early messages
            '   '   '      '     '           '      ' - actual message rate [Hz]
            '   '   '      '     '           '- total # of messages
            '   '   '      '     ' - actual rate of eCPU stalls (should be below '50.0')
            '   '   '      '- max continous eCPU stall (should be below '50.0')
            '   '   '- WR time continuity: maximum negative difference (should be '0')
            '   '- WR time continuity: maximum positive difference (should be '8' for a 125 MHz CPU clock)
            '- WR lock: '1' signals 'TRACK_PHASE'

Report software bugs to <d.beck@gsi.de>
Version 2.0.3. Licensed under the LGPL v3.

Selection of Wishbone Device
The values are read from Wishbone devices via Etherbone. If this tool queries data from a Wishbone device, it first connects to the first device of that relevant type on the Wishbone bus. In case multiple devices of the same type exist, a specific device can be selected using the option -w (default: -w0).

1-Wire IDs and Temperatue Sensors
Some form factors such as the SCU have more than one controller for 1-wire devices connected to the Wishbone bus. As a controller for 1-wire devices may support multiple physical 1-wire buses, the bus number must be specified too. Use option -t (or: -b) to read the temperature in degree Celsius (or: 1-wire ID).

• use option -w or -u to select the 1-wire controller (w: WB slave 'WR 1-Wire', u: 'User 1-Wire')
• use option -t or -b to selected the 1-wire bus connected to the 1-wire controller
• use option -f to specify the 1-wire family code
• this tool will automatically select the first matching device on the selected 1-wire bus (= multiple devices of the same family code on the same bus are not supported).

form factor	Wishbone device	1-wire bus	type	family code	location
SCU 2/3	-u0	-t0 (-b0)	temp	-f0x42	extension board (if mounted)
SCU 2/3	-u0	-t1 (-b1)	temp	-f0x42	backplane
SCU 2/3	-w0	-t0 (-b0)	temp	-f0x42	carrier (White Rabbit)
SCU 2/3	-w0	-b0	EEPROM	-f0x43	carrier (White Rabbit)
PEXARIA5B	-u0	-t0 (-b0)	temp	-f0x28	daughter board (I/O...)
PEXARIA5B	-u0	-b0	EEPROM	-f0x43	daughter board (I/O...)
PEXARIA5B	-w0	-t0 (-b0)	temp	-f0x28	carrier (White Rabbit)
PEXARIA5B	-w0	-b0	EEPROM	-f0x43	carrier (White Rabbit)
VETAR2A	-w0	-t0 (-b0)	temp	-f0x28	carrier (White Rabbit)
VETAR2A	-w0	-b0	EEPROM	-f0x43	carrier (White Rabbit)
EXPLODER5A	-u0	-t0 (-b0)	temp	-f0x28	daughter board (I/O...)
EXPLODER5A	-u0	-b0	EEPROM	-f0x43	daughter board (I/O...)
EXPLODER5A	-w0	-t0 (-b0)	temp	-f0x28	carrier (White Rabbit)
EXPLODER5A	-w0	-b0	EEPROM	-f0x43	carrier (White Rabbit)

Table: 1-wire devices on various form factors (release > "cherry"). This list might be incomplete.

form factor	Wishbone device	1-wire bus	type	family code	location
SCU 2/3	-w0	-t0 (-b0)	temp	-f0x42	extension board (if mounted)
SCU 2/3	-w0	-t1 (-b1)	temp	-f0x42	backplane
SCU 2/3	-w1	-t0 (-b0)	temp	-f0x42	carrier (White Rabbit)
SCU 2/3	-w1	-b0	EEPROM	-f0x43	carrier (White Rabbit)
PEXARIA5B	-w0	-t0 (-b0)	temp	-f0x28	carrier (White Rabbit)
PEXARIA5B	-w0	-b0	EEPROM	-f0x43	carrier (White Rabbit)
VETAR2A	-w0	-t0 (-b0)	temp	-f0x28	carrier (White Rabbit)
VETAR2A	-w0	-b0	EEPROM	-f0x43	carrier (White Rabbit)
EXPLODER5A	-w0	-t0 (-b0)	temp	-f0x28	daughter board (I/O...)
EXPLODER5A	-w0	-b0	EEPROM	-f0x43	daughter board (I/O...)
EXPLODER5A	-w1	-t0 (-b0)	temp	-f0x28	carrier (White Rabbit)
EXPLODER5A	-w1	-b0	EEPROM	-f0x43	carrier (White Rabbit)

Table (deprecated): 1-wire devices on various form factors ("balloon" <= release <= "cherry"). This list might be incomplete.

-- DietrichBeck - 22 October 2019