cli: support for new output module API

[sigrok-cli.git] / doc / sigrok-cli.1

diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1
index a8b1f83f96363d74931da025fc8d0e02c02862a5..d86e53b7167c15b9cc6181690f600b0a039165bd 100644 (file)
--- a/doc/sigrok-cli.1
+++ b/doc/sigrok-cli.1
@@ -1,8 +1,8 @@
-.TH SIGROK\-CLI 1 "March 18, 2012"
+.TH SIGROK\-CLI 1 "May 29, 2012"

 .SH "NAME"
 sigrok\-cli \- Command-line client for the sigrok logic analyzer software
 .SH "SYNOPSIS"
 .SH "NAME"
 sigrok\-cli \- Command-line client for the sigrok logic analyzer software
 .SH "SYNOPSIS"

-.B sigrok\-cli \fR[\fB\-hVlDiIoOdptwas\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fB\-l\fR|\fB\-\-loglevel\fR level] [\fB\-D\fR|\fB\-\-list\-devices\fR] [\fB\-i\fR|\fB\-\-input\-file\fR filename] [\fB\-I\fR|\fB\-\-input\-format\fR format] [\fB\-o\fR|\fB\-\-output\-file\fR filename] [\fB\-O\fR|\fB\-\-output-format\fR format] [\fB\-d\fR|\fB\-\-device\fR device] [\fB\-p\fR|\fB\-\-probes\fR probelist] [\fB\-t\fR|\fB\-\-triggers\fR triggerlist] [\fB\-w\fR|\fB\-\-wait\-trigger\fR] [\fB\-a\fR|\fB\-\-protocol\-decoders\fR list] [\fB\-s\fR|\fB\-\-protocol\-decoder\-stack\fR stack] [\fB\-\-time\fR ms] [\fB\-\-samples\fR numsamples] [\fB\-\-continuous\fR]
+.B sigrok\-cli \fR[\fB\-hVlDdiIoOptwasA\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fB\-l\fR|\fB\-\-loglevel\fR level] [\fB\-D\fR|\fB\-\-list\-devices\fR] [\fB\-d\fR|\fB\-\-device\fR device] [\fB\-i\fR|\fB\-\-input\-file\fR filename] [\fB\-I\fR|\fB\-\-input\-format\fR format] [\fB\-o\fR|\fB\-\-output\-file\fR filename] [\fB\-O\fR|\fB\-\-output-format\fR format] [\fB\-p\fR|\fB\-\-probes\fR probelist] [\fB\-t\fR|\fB\-\-triggers\fR triggerlist] [\fB\-w\fR|\fB\-\-wait\-trigger\fR] [\fB\-a\fR|\fB\-\-protocol\-decoders\fR decoderlist] [\fB\-s\fR|\fB\-\-protocol\-decoder\-stack\fR stack] [\fB\-A\fR|\fB\-\-protocol\-decoder\-annotations\fR annlist] [\fB\-\-time\fR ms] [\fB\-\-samples\fR numsamples] [\fB\-\-continuous\fR]

 .SH "DESCRIPTION"
 .B sigrok\-cli
 is a cross-platform command line utility for the
 .SH "DESCRIPTION"
 .B sigrok\-cli
 is a cross-platform command line utility for the


@@ -43,6 +43,29 @@ number, the more debug output will be printed. Valid loglevels are
 List all logic analyzer devices found on the system. This actively scans for
 devices (USB, serial port, and others).
 .TP
 List all logic analyzer devices found on the system. This actively scans for
 devices (USB, serial port, and others).
 .TP

+.BR "\-d, \-\-device " <device>
+The device to use for acquisition. It can be specified by ID as reported by
+.BR "\-\-list\-devices" ,
+or by the name of the driver as reported by
+.BR \-\-version .
+.sp
+A device can optionally be followed by a colon-separated list of device
+options, where each option takes the form
+.BR key=value .
+For example, to set the samplerate on the first device you might specify
+.sp
+.RB "  $ " "sigrok\-cli \-d 0:samplerate=1m"
+.sp
+Samplerate is an option common to most devices. The argument specifies the
+samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz.
+The following are all equivalent:
+.sp
+.RB "  $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1000000"
+.sp
+.RB "  $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1m"
+.sp
+.RB "  $ " "sigrok\-cli \-\-samples 100 \-d ""0:samplerate=1 MHz""
+.TP

 .BR "\-i, \-\-input\-file " <filename>
 Load input from a file instead of a hardware device. If the
 .B \-\-input\-format
 .BR "\-i, \-\-input\-file " <filename>
 Load input from a file instead of a hardware device. If the
 .B \-\-input\-format


@@ -53,7 +76,12 @@ the input file.
 When loading an input file, assume it's in the specified format. If this
 option is not supplied (in addition to
 .BR \-\-input\-file ),
 When loading an input file, assume it's in the specified format. If this
 option is not supplied (in addition to
 .BR \-\-input\-file ),

-sigrok-cli attempts to autodetect the file format of the input file.
+sigrok-cli attempts to autodetect the file format of the input file. Use the
+.B \-V
+option to see a list of available input formats. The format name may
+optionally be followed by a colon-separated list of options, where each
+option takes the form
+.BR "key=value" .

 .TP
 .BR "\-o, \-\-output\-file " <filename>
 Save output to a file instead of writing it to stdout. The default format
 .TP
 .BR "\-o, \-\-output\-file " <filename>
 Save output to a file instead of writing it to stdout. The default format


@@ -99,29 +127,6 @@ like this:
  1:11111111 11111111 11111111 11111111 [...]
  2:11111111 00000000 11111111 00000000 [...]
 .TP
  1:11111111 11111111 11111111 11111111 [...]
  2:11111111 00000000 11111111 00000000 [...]
 .TP

-.BR "\-d, \-\-device " <device>
-The device to use for acquisition. It can be specified by ID as reported by
-.BR "\-\-list\-devices" ,
-or by the name of the driver as reported by
-.BR \-\-version .
-.sp
-A device can optionally be followed by a colon-separated list of device
-options, where each option takes the form
-.BR key=value .
-For example, to set the samplerate on the first device you might specify
-.sp
-.RB "  $ " "sigrok\-cli \-d 0:samplerate=1m"
-.sp
-Samplerate is an option common to most devices. The argument specifies the
-samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz.
-The following are all equivalent:
-.sp
-.RB "  $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1000000"
-.sp
-.RB "  $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1m"
-.sp
-.RB "  $ " "sigrok\-cli \-\-samples 100 \-d ""0:samplerate=1 MHz""
-.TP

 .BR "\-p, \-\-probes " <probelist>
 A comma-separated list of probes to be used in the session.
 .sp
 .BR "\-p, \-\-probes " <probelist>
 A comma-separated list of probes to be used in the session.
 .sp


@@ -232,7 +237,10 @@ as SCK, and probe 0 as CS# signal.
 .BR "\-s, \-\-protocol\-decoder\-stack " <stack>
 This option allows the user to specify a protocol decoder stack, i.e.
 the way in which one protocol decoder's output gets piped into another
 .BR "\-s, \-\-protocol\-decoder\-stack " <stack>
 This option allows the user to specify a protocol decoder stack, i.e.
 the way in which one protocol decoder's output gets piped into another

-protocol decoder.
+protocol decoder. If not specified, the stack will be set up in the same
+order in which the protocol decoders were given with the
+.B \-\-protocol-decoders
+option.

 .sp
 The decoders are specified by their ID, as shown in the
 .B \-\-version
 .sp
 The decoders are specified by their ID, as shown in the
 .B \-\-version


@@ -246,7 +254,7 @@ parameter.
 Example:
 .sp
  $
 Example:
 .sp
  $

-.B "sigrok\-cli \-i <file.sr> \-a i2c:sda=4,scl=7,rtc8564"
+.B "sigrok\-cli \-i <file.sr> \-a i2c:sda=4:scl=7,rtc8564"

 .br
 .B "              \-s i2c,rtc8564"
 .sp
 .br
 .B "              \-s i2c,rtc8564"
 .sp


@@ -268,6 +276,30 @@ option (you cannot specify them in the
 .B \-s
 option).
 .TP
 .B \-s
 option).
 .TP

+.BR "\-A, \-\-protocol\-decoder\-annotations " <annotations>
+By default, only the stack's topmost protocol decoder's annotation output is
+shown. With this option another decoder's annotation can be selected for
+display, by specifying its ID:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-a i2c,i2cfilter,edid -A i2c"
+.sp
+If a protocol decoder has multiple annotation formats, you can also specify
+which of them to show by specifying its short description like this:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-a i2c,i2cfilter,edid"
+.br
+.B "              \-A i2c=rawhex"
+.sp
+You can also select multiple protocol decoders, with an optional selected
+annotation format each, by separating them with commas:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-a i2c,i2cfilter,edid"
+.br
+.B "              \-A i2c=rawhex,edid"
+.TP

 .BR "\-\-time " <ms>
 Sample for
 .B <ms>
 .BR "\-\-time " <ms>
 Sample for
 .B <ms>