Command-line options

The drasi system consist of a small set of executables, controlled by various command-line options.

It is a general goal to keep the amount of needed options to a minimum, thanks to the system employing sane defaults and heuristics for most configurable parameters.

The relationships between options describing data flow and trigger bus topology are shown in pictures here and here.

Common options

--gdb

Run in GDB (must be the first argument).

(This is actually performed by a wrapper script.)

--help

Show help message.

--xxx=help

Show detailed help message for options that take suboptions.

Options for main data-pump

The readout and merger is to a large extent the same program, and thus share many options.

--port=[+]PORT

Network TCP/IP port to bind to. Default is 56583. With the +N, N is added to the default port number. This is useful for running multiple instances on the same machine.

--server=[drasi|trans[:PORT]][,[no]hold][,forcemap][,clients=N][,bufsize=N][,dest=HOST]

Network data server (output).

Note that a data server can be started at any node, but would usually be at the final event builder or time sorter.

drasi

Native protocol data server [hold].

trans[:PORT]

Transport protocol data server [weakhold].

stream[:PORT]

Stream protocol data server [nohold].

hold|nohold

All data must be sent to one client. (No data is discarded due to slow clients.)

weakhold

All data must be sent when some client connected.

spilldelay|nospilldelay

Force delayed data transmission off/on. (Default is on when only one CPU core available.)

flush=N

Flush data every N seconds.

forcemap

Only allow transport data connections through portmapped port. (Does not work with legacy clients.)

clients=N

Serve data to (at most) N clients (default 1).

bufsize=N

Deliver data in LMD buffers of size N (Mi|raw hex).

dest=HOST

Allowed destinations using the drasi protocol.

readout

Use readout/merge buffer as source. (Matters if a filter stage is in use.)

filter

Use filter buffer as source (only when available).

final

Use filter buffer as source (when available, otherwise readout buffer). (This is the default.)

--log-ack-wait

For each log message, wait for acknowlegde of receipt from the log client before proceeding. This can be used to debug hard lock-ups in readout code, since the readout will not proceed before each message has been successfuly sent over the network.

--log-no-rate-limit

Do not rate-limit log messages.

--file-writer

File writer thread.

Note that a file writer can be started at any node, but would usually be at the final event builder or time sorter.

bufsize=N

Deliver data in LMD buffers of size N (Mi|raw hex).

output=FILENAME

Destination LMD file at start. (Useful for testing.)

max-events=N

Close initial LMD file after N events written.

terminate-on-close

Terminate entire program after closing LMD file. (Useful for testing.)

--buf=[size=N][,direct|physmmap|physpexor@off]

Size of data buffer (Mi|raw hex).

size=N

Size of buffer.

nohint

Do not warn/hint about small buffer size.

valloc

Aligned memory allocation (using valloc(), for systems where this is useful).

direct@OFF

Direct mapping memory offset.

physmmap@OFF

Physical mapping memory offset.

physpexor@OFF

Physical mapping memory offset (via PEXOR driver).

input=N|frac|%

Size or fraction to use for merge input buffers (default 75%).

filter=N|frac|%

Size or fraction to use for (optional) filter output buffer (default 50%). The fraction excludes input buffers.

--max-ev-size=N

Maximum event size (default 0x1000).

--max-ev-interval=Ns

Specify the maximum time between events.

Specifying this options implies a promise to at least deliver some periodic ‘keep-alive’ event (e.g. a synchronisation trigger) every so often.

Warnings will be printed when this promise is not fulfilled.

This is required for any data that eventually goes to a timesorter which uses the ts-disable option, see this.

--[triva|trimi|trixor]=(master|slave),[@0xADDR][,ctime=n][,fctime=n][,spill1213]

Trigger module, being either a triva, trimi or trixor module.

master

Operate as trigger bus / deadtime domain master.

slave

Operate as trigger bus / deadtime domain slave.

@0xADDR

Physical address (bits 31-24 on VME bus) of trigger module.

ctime=N

Conversion time (in 100 ns units).

fctime=N

Fast clear time (in 100 ns units).

spill1213

Spill on/off marked by trigger 12/13 for delayed EB.

sim=MOD[@HOST]

Simulated trigger bus.

multi-word-trig-clear

Do deadtime/trigger clear using multiple word writes.

--inspill-stuck-timeout=Ns

Timeout to regard inspill status as stuck. Delayed event-building will not hold data transport when status is stuck.

--master=HOST[:[+]PORT]

TRIVA/MI master instance. Used when this instance is a slave.

--slave=HOST[:[+]PORT]

TRIVA/MI slave instance. Used (multiple times) when this instance is master.

--eb-master=HOST[:[+]PORT]

Event builder master instance (=TRIVA/MI master). Used when this instance is an event builder.

--eb=host[:[+]PORT]

Event builder (actual) instance. Used when this instance is a master.

--label=STRING

Use the given label for the tree view monitor.

--ntp=HOST

NTP server (use when local clock has sloppy discipline). The received times are only used for monitoring of timestamps.

--no-filter

Disable filter stage (if compiled in).

--[action|info|log|debug|spam]

Minimum severity of messages to print on console (default is info).

--debug=MASK

Enable debug messages.

--insomniac

Disable debugger sleep.

Options for readout

Additional options for (f_user-based) readout:

--max-sticky-size=N

Maximum sticky (after) event size (def 0x1000).

--max-sticky-before-size=N

Maximum sticky (before) event size (def 0x100).

--subev=[opts]

LMD subevent/crate readout specs.

subcrate=N

Subevent subcrate number [0-15] (or crate).

type=N

Subevent type [0-65535] (or t).

subtype=N

Subevent subtype [0-65535] (or st).

procid=N

Subevent procid [0-65535] (or proc).

control=N

Subevent control [0-255] (or ctrl).

Options for merger / time-sorter

Input and control options for merger:

--drasi=[bufsize=N,]HOST[:[+]PORT]

Network data source (native protocol).

inbufsize=N

Size of buffer to use for incoming data (Mi|raw hex|frac|%%). The buffer allowance is taken from the main data buffer, and can also be specified as a fraction of that.

max-ev-size=N

Give maximum event length smaller than automatically determined. Will be checked for each event.

ts-disable=N

Time to wait (seconds) until this time sorter source is disabled due to no data. Default is 0, no automatic disable.

Caution

This option can cause data to be sorted out-of-order if sources are misbehaving.

Do not use this option unless the implications are clear.

keepalive=Ns

Time to wait (seconds) until this time sorter source is reconnected due to no data.

HOST[:PORT]

The actual data source.

--trans=[bufsize=N,]HOST[:PORT]

Network data source (MBS transport protocol).

The same options as for --drasi are available. In addition:

label=STRING

Use the given label for the tree view monitor.

--file=

Read data from file (useful for filter testing).

--merge-mode=(wr|titris|event)

Merge mode:

event

Do event-building. Events from multiple sources are merged. Events must have matching event and trigger numbers.

wr

Time sort using white rabbit-formatted timestamps.

titris

Time sort using titris-formatted timestamps.

--merge-no-validate

Do not validate sources. (Disables reconnects.) (Use only for testing!)

--merge-ts-disable=N

Time to wait (seconds) until time sorter complains about sources with no data.

Caution

This option can cause data to be sorted out-of-order if sources are misbehaving.

Do not use this option unless the implications are clear.

--merge-ts-wr-check

Check that White Rabbit (WR) timestamps are reasonable compared to the local PC time. Timestamps more than 5 s into the future and timestamps older than 10 times the missing timestamp disable timeout are considered as faulty and sorted as if they were 0. (The values in the data are not modified.)

Caution

This option can cause data to be sorted out-of-order if sources are misbehaving.

Do not use this option unless the implications are clear.

--merge-keepalive=N

Time to wait (seconds) until time sorter sources are reconnected due to no data. (Default is 30 s.)

--merge-ts-analyse-ref=N

Use time-stamp ID N a reference for online time-stamp alignment analysis.

--merge-ts-analyse-sync-trig=N

Trigger number for sync triggers used for online time-stamp alignment analysis.

--merge-ts-analyse-sync-trig-id=ID:N

Trigger number for sync triggers used for online time-stamp alignment analysis for data from timestamp white rabbit ID.

Options for monitor: lwrocmon

HOST[:PORT]

Drasi instance(s) to monitor.

--rate[=N]

Show rate for given systems (every N s).

--tree

Show ncurses tree view of systems.

--no-down-up

Do not search up in tree after destinations.

--no-ts-analysis

Do not show timestamp analysis in tree view.

--no-lookup

Do not do hostname lookup.

--raw-ts

Show raw timestamp values.

--buf-size

Show buffer sizes instead of fill ratios.

--detail

Show ncurses detailed system status.

--monbuf

Dump raw monitor buffer data.

--count=N

Quit after showing N reports (only –rate).

--influxdb

Produce entries for InfluxDB line protocol (requires –rate).

--expire-time=N

Expire stale data (lost connection) after N s.

--nz-rate-success

Exit status 0 if event increase seen (only –rate).

--dt-trace

Store deadtime trace files (requires –tree).

--log[=FILENAME]

Record log messages from systems. Default filename lwlog.l.

--raw

Show raw values.

Options for log pretty-printer: lwroclog

--info|--log|--debug|--spam

Minimum severity of messages to show.

--us

Show fractional time (us) of log messages.

--file

Show source location of log message.

--full

Show all log fields.

--colour=yes|no

Force use of coloured output.

Options for control: lwrocctrl

Control commands beginning with --file- are issued to a file writer node, usually an event builder or time sorter. Control commands beginning with --acq- are issued to the master node of a dead-time domain.

HOSTNAME[:PORT]

Drasi instance to control.

--file-open [=[auto=SIZE,]NAME]

Open a new file.

auto=SIZE

Open a new file after SIZE bytes written. Automatic file names will increment the last number in the filename. If none exist, a number will be added.

time=Ns

Open a new file after a given time. Automatic file names as above.

events=N

Open a new file after a given number of events have been written. Atomatic file names as above.

NAME

Name of file.

--file-new[=[auto=SIZE,]NAME]

Continue recording of data to a new file, with no events lost in-between. Opens file is closed.

The same options as for --file-open are available.

--file-close

Close current file.

--file-hold

Hold data for file collection.

--file-unjam

Close file with write failure (sets hold).

--file-status

Report file writing status.

--acq-start

Start acq (trigger 14).

--acq-stop

Stop acq (trigger 15), and/or hold.

--acq-status

Report acq status.

--acq-meas-dt

Do live dead-time accounting for systems within a dead-time domain.

Results (in microseconds) are shown in the tree view monitor.

--merge-try-reconnect

Request merger to reconnect disabled sources.

--debug[=NUM|0xMASK]

Enable / disable (0) debug messages.