cli: Add -A (alias for --protocol-decoder-annotation).

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

diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1
index 2150a8451ddb6ba2b2803e18bdefadd414c12a42..46e149760e06c9657f2e0634389556e67a583e12 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\-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\-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\-annotation\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


@@ -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,10 +27,45 @@ 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).
 .TP
 .B "\-D, \-\-list\-devices"
 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


@@ -64,8 +99,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


@@ -85,29 +122,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


@@ -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,116 @@ 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. 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
+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 "\-A, \-\-protocol\-decoder\-annotation " <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"
+.br
+.B "              \-\-protocol\-decoder\-annotation 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 "              \-\-protocol\-decoder\-annotation 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 "              \-\-protocol\-decoder\-annotation i2c=rawhex,edid"
+.TP

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


@@ -205,7 +329,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