Commands

The following section documents the user interface provided by NLTrace.

Command reference

Detailed installation instructions can be found here, along with a step-by-step tutorial which can be found here, or in the man pages:

    man nltrace
    man nltrace-tutorial

USAGE:

    nltrace [OPTIONS] [vcd-file [vcd-file ...]]

OPTIONS:

    -s <FILE>, --script <FILE>

            Execute the commands given in <FILE>. Can be issued multiple times.

    -p <COMMAND>, --pass <COMMAND>

            Execute COMMAND. Multiple COMMANDs can be separated by ';', and should be
            enclosed within double quotes ("). Can be issued multiple times.

    -d <FILE>, --doc <FILE>

            Create command reference in Markdown. If FILE is '-', print to stdout

NLTrace provides a rich command shell, inspired by the Yosys shell. If you are familiar with the Yosys shell, you will quickly understand how NLTrace works. NLTrace makes use of tab completion wherever possible. The completers are designed with context sensitivity in mind to provide a smooth user experience. For example, if a command accepts long options, the completer will suggest all implemented long options when the command is followed by -- and the TAB key is pressed. Likewise, the completer suggests file names where reasonable, or selected objects when inside a selection.

This section fully documents all built-in NLTrace commands.

Command Description
add Add a diagram representing a (subset of a) VCD file
cd Select VCD files and diagrams
dump Dump selected VCD data in JSON format
exit Exit nltrace
help Show documentation
history Show command history
list Prints a list of VCD files and diagrams
ls List selected objects
opt Optimize VCD trace
plugin Manage plugins
read_vcd Read VCD files
script Execute commands in a file
select Select signals
set Set diagram parameters
show Open the selected diagram in the selected viewer
write_json Generate JSON representation of a VCD diagram
write_pdf Generate a PDF file showing the selected waveforms
write_png Generate a PNG file showing the selected waveforms
write_svg Generate an SVG file showing the selected waveforms
write_tex Generate 'TikZ Timing' representation selected waveforms
write_vcd Generate a VCD file from the selected VCD subset of a diagram

add

Add a diagram representing a (subset of a) VCD file

add <NAME>

This command adds a diagram to the currently selected VCD file, with a mandatory NAME, with the parameters of the currently selected diagram. If no diagram is selected, the diagram is created with default parameters.

cd

Select VCD files and diagrams

cd ..

cd [VCDFILE] [DIAGRAM]

Navigate through VCD files and diagrams. If called with .., go one level up. If called without argument, deselect any VCD file and diagram. If called with one argument and nothing is selected, change into VCDFILE. If a VCD file is selected when calling cd with one argument, change into DIAGRAM. When called with two arguments, change into DIAGRAM of VCDFILE.

dump

Dump selected VCD data in JSON format

dump

Dump the selected VCD trace in JSON format.

exit

Exit nltrace

help

Show documentation

help [OPTIONS] [COMMAND ...]

Print the documentation for COMMAND(s). If COMMAND is empty, print a list of available commands, along with a short description.

Options:

-a, --all

  Print the documentation for all available commands.

history

Show command history

history [OPTIONS] [FILE]

Show the last 1000 commands.

If FILE is given, save the history in a script file. This file can then be executed with the shell command.

Options:

-n INTEGER, --limit=INTEGER

  Only print most recent lines up to the specified limit. If '0', all history
  is shown. (Works like `tail -n INTEGER`)

-c, --current-length

  Print the current history length

-i, --line-numbers

  Print the history along with line numbers in reversed order to appropriately
  choose a value for `-n`/`--limit`.

list

Prints a list of VCD files and diagrams

list

List all VCD files, and all diagrams per VCD file. The currently active VCD file, and the currently active diagram are marked by an asterisk (*)

The list of diagrams is printed in the following form:

[id]: scale:begin:end:step+offset

  | Parameter | Description                                                 |
  |-----------|-------------------------------------------------------------|
  | id        | The identifier of a diagram                                 |
  | scale     | A scaling factor to resize the diagram along the time scale |
  | begin     | Start time of the selected trace                            |
  | end       | End time of the selected trace                              |
  | step      | Defines the time step for the diagram's tick marks          |
  | offset    | Offset added to the time scale                              |

ls

List selected objects

ls

List the selected signals of the currently selected diagram. The signals are listed in a tree, reflecting the design's hierarchy. If no diagram is selected, show a list of all available diagrams of a VCD file. If no VCD file is selected, the output is the same as for the 'list' command.

opt

Optimize VCD trace

opt

Optimze the currently active VCD file. Currently, unnecessary entries are removed. Unnecessary entries are timestamp/value pairs with unchanging values.

plugin

Manage plugins

plugin [OPTIONS]

Options:

-i name, --insert=name

  Insert the plugin of the given name. At the moment, the plugin must be
  placed inside a directory 'plugins' to make it recognized by nltrace.

read_vcd

Read VCD files

read_vcd FILE [FILE ...]

Load the given VCD file(s) into memory.

script

Execute commands in a file

script FILE

Execute the commands in FILE. Comments are introduced by '#', and last until the end of a line. Multiple commands per line can be separated by ';'

select

Select signals

select [OPTIONS] [REGEX ...]

Select all signals matching the regular expression (REGEX). Multiple regular expressions can be given. If -a or -d is given, the current selection is modified (extended or reduced). Otherwise, a new selection is created. -a and -d can be combined with -c, -l, -e, and -x. It is not allowed to specify -a and -d at the same time. If -c is given, the current selection is cleared before matching any regular expression.

By default, a regular expression is interpreted as Python regular expression, and matches any signal containing the pattern specified by the regular expression.

Options:

-a, --add

  Add all signals matching the regular expression(s) to the current selection.

-d, --del

  Remove all signals matching the regular expression(s) from the current selection.

-c, --clear

  Clear the current selection.

-l LEVEL, --level=INTEGER

  Select all signals in the hierarchy tree up to the specified level

-e REGEX, --exact=REGEX

  A signal must exactly match the REGEX. Can be given multiple times.

-x REGEX, --exclude=REGEX

  Any signal is selected that does not match the REGEX. Can be given multiple times.

set

Set diagram parameters

set PARAMETER [VALUE]

Set a parameter of the currently active diagram with the given VALUE. If no value is given, the parameter's current value is printed.

Currently, the following parameters are supported:

  | Parameter  | Description                                                              |
  |------------|--------------------------------------------------------------------------|
  | begin      | Integer specifying the start time of the diagram                         | 
  | end        | Integer specifying the end time of the diagram                           | 
  | offset     | Specify this integer to add offset to the time scale                     | 
  | scale      | Float; Scaling factor to resize the diagram's time scale                 | 
  | step       | Integer; Time step for the time scale's tick marks                       | 
  | plain      | Boolean; If `True`, the diagram does not contain a time scale nor a grid |

show

Open the selected diagram in the selected viewer

show

Create a temporary PDF, and show it in the configured viewer. The current viewer is evince.

write_json

Generate JSON representation of a VCD diagram

write_json [FILE]

Write selected VCD trace to a JSON file. If no FILE is given, write to stdout.

This command is not yet implemented!

write_pdf

Generate a PDF file showing the selected waveforms

write_pdf FILE

Writes the selected VCD trace to a PDF file.

write_png

Generate a PNG file showing the selected waveforms

write_png [OPTIONS] FILE

Writes the selected VCD trace to a PNG file.

Options:

-r INTEGER, --resolution=INTEGER

  The resolution of the PNG image in dots per inch (dpi). Default value
  is 300 dpi.

-q INTEGER, --quality=INTEGER

  The quality of the resulting PNG image in percent (from 0 to 100%).
  Defualt value is 90%.

write_svg

Generate an SVG file showing the selected waveforms

write_svg FILE

Writes the selected VCD trace to a SVG file.

write_tex

Generate 'TikZ Timing' representation selected waveforms

write_tex [OPTIONS] [FILE]

Create a LaTeX representation of the selected VCD trace using the TikZ timing package. If no FILE is given, print to stdout. This command supports to generate a standalone LaTex document that can be directly translated into other formats, such as PDF or DVI. If not standalaone, the selected VCD trace is translated into a sequence of TikZ timing waveforms, which can be included into your LaTeX document.

Options:

-s, --standalone

  Generate a standalone LaTeX document including a preamble, with the diagram
  as the document body.

write_vcd

Generate a VCD file from the selected VCD subset of a diagram

write_vcd [FILE]

Generate a VCD representation of the selected trace, and write it to FILE. If no FILE is given, write to stdout. The VCD trace is written using the shell's timescale attribute. The current timescale is 1s

Next Post