cli: manpage: Document -l, -a, and -s.

Also, update list of supporter input/output formats.

diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1
index 2150a8451ddb6ba2b2803e18bdefadd414c12a42..a8b1f83f96363d74931da025fc8d0e02c02862a5 100644 (file)
--- a/doc/sigrok-cli.1
+++ b/doc/sigrok-cli.1
@@ -2,7 +2,7 @@
 .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\-hVDiIoOdptwa\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\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\-triggers\fR] [\fB\-a\fR|\fB\-\-protocol\-decoders\fR sequence] [\fB\-\-time\fR ms] [\fB\-\-samples\fR numsamples] [\fB\-\-continuous\fR]
+.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]

 .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


@@ -11,7 +11,7 @@ logic analyzer software.
 .PP
 The command-line frontend for sigrok cannot display graphical output, but is
 still sufficient to run through the whole process of hardware initialization,
 .PP
 The command-line frontend for sigrok cannot display graphical output, but is
 still sufficient to run through the whole process of hardware initialization,

-acquisition, protocol analysis and saving the session.
+acquisition, protocol decoding and saving the session.

 .PP
 It is useful for running on remote or embedded systems, netbooks, PDAs,
 and for various other use-cases. It can display samples on standard output or
 .PP
 It is useful for running on remote or embedded systems, netbooks, PDAs,
 and for various other use-cases. It can display samples on standard output or


@@ -27,6 +27,18 @@ Show
 version, and information about supported hardware drivers, input file
 formats, output file formats, and protocol decoders.
 .TP
 version, and information about supported hardware drivers, input file
 formats, output file formats, and protocol decoders.
 .TP

+.BR "\-l, \-\-loglevel " <level>
+Set the libsigrok and libsigrokdecode loglevel. At the moment
+.B sigrok-cli
+doesn't support setting the two loglevels independently. The higher the
+number, the more debug output will be printed. Valid loglevels are
+.BR 0 " (NONE),"
+.BR 1 " (ERR),"
+.BR 2 " (WARN),"
+.BR 3 " (INFO),"
+.BR 4 " (DBG), and"
+.BR 5 " (SPEW)."
+.TP

 .B "\-D, \-\-list\-devices"
 List all logic analyzer devices found on the system. This actively scans for
 devices (USB, serial port, and others).
 .B "\-D, \-\-list\-devices"
 List all logic analyzer devices found on the system. This actively scans for
 devices (USB, serial port, and others).


@@ -64,8 +76,10 @@ Supported formats currently include
 .BR ascii ,
 .BR binary ,
 .BR vcd ,
 .BR ascii ,
 .BR binary ,
 .BR vcd ,

-.BR ols ", and"
-.BR gnuplot .
+.BR ols ,
+.BR gnuplot ,
+.BR chronovu-la8 ", and"
+.BR csv .

 .sp
 The
 .B bits
 .sp
 The
 .B bits


@@ -160,7 +174,7 @@ effectively corresponds to
 .BR 01 .
 .br
 .BR "c" :
 .BR 01 .
 .br
 .BR "c" :

-Any kind of change on a pin.
+Any kind of change on a pin (either a rising or a falling edge).

 .sp
 Not every device supports all of these trigger types. Use the
 .B "\-d <device>"
 .sp
 Not every device supports all of these trigger types. Use the
 .B "\-d <device>"


@@ -173,6 +187,87 @@ any pre-trigger data. This option is useful if you don't care about the data
 that came before the trigger (but the logic analyzer hardware delivers this
 data to sigrok nonetheless).
 .TP
 that came before the trigger (but the logic analyzer hardware delivers this
 data to sigrok nonetheless).
 .TP

+.BR "\-a, \-\-protocol\-decoders " <list>
+This option allows the user to specify a comma-separated list of protocol
+decoders to be used in this session. The decoders are specified by their
+ID, as shown in the
+.B \-\-version
+output.
+.sp
+Example:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-a i2c"
+.sp
+Each protocol decoder can optionally be followed by a colon-separated list
+of options, where each option takes the form
+.BR "key=value" .
+.sp
+Example:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-a uart:baudrate=115200:parity=odd"
+.sp
+The list of supported options depends entirely on the protocol decoder. Every
+protocol decoder has different options it supports.
+.sp
+Any "options" specified for a protocol decoder which are not actually
+supported options, will be interpreted as being probe name/number assignments.
+.sp
+Example:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr>"
+.br
+.B "              \-a spi:wordsize=9:miso=1:mosi=5:sck=3:cs=0"
+.sp
+In this example,
+.B wordsize
+is an option supported by the
+.B spi
+protocol decoder. Additionally, the user tells sigrok to decode the SPI
+protocol using probe 1 as MISO signal for SPI, probe 5 as MOSI, probe 3
+as SCK, and probe 0 as CS# signal.
+.TP
+.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.
+.sp
+The decoders are specified by their ID, as shown in the
+.B \-\-version
+output. In addition to the
+.B \-s
+option, all protocol decoders that are used in a stack, must also be specified
+(together with their options, if any) using the
+.B \-a
+parameter.
+.sp
+Example:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-a i2c:sda=4,scl=7,rtc8564"
+.br
+.B "              \-s i2c,rtc8564"
+.sp
+In this example, the
+.B \-s
+option specifies that the output of the
+.BR i2c " decoder"
+is piped into the
+.BR rtc8564 " decoder,"
+i.e., the
+.BR rtc8564 " decoder"
+is stacked on top of the
+.BR i2c " decoder."
+.sp
+The respective protocol decoder options and probe name/number assignments
+must be given using the
+.B \-a
+option (you cannot specify them in the
+.B \-s
+option).
+.TP

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


@@ -205,7 +300,7 @@ Alternatively, you can also use:
 .TP
 To capture data from 4 probes lasting 100ms at 10 MHz starting at the trigger condition 1:high, 2:rising, 3:low, 4:high, use:
 .TP
 .TP
 To capture data from 4 probes lasting 100ms at 10 MHz starting at the trigger condition 1:high, 2:rising, 3:low, 4:high, use:
 .TP

-.B "  sigrok\-cli \-O bits \-p 1\-4 \-\-time 100 \-o samplerate=10m \\\\"
+.B "  sigrok\-cli -d 0:samplerate=10m \-O bits \-p 1\-4 \-\-time 100 \\\\"

 .B "      \-\-wait\-trigger \-\-triggers 1=1,2=r,3=0,4=1 "
 .SH "EXIT STATUS"
 .B sigrok\-cli
 .B "      \-\-wait\-trigger \-\-triggers 1=1,2=r,3=0,4=1 "
 .SH "EXIT STATUS"
 .B sigrok\-cli