Purpose of this software

Scope of the document

NxBase2 is a tool developed to interact with devkit boards for NanoXplore's chips. It provides a way to upload bitstreams into the chip and is able to control some of the hardware features of the related devkits.

Installation

The application is delivered as a bundle in order to limit dependencies. It should run out of the box on most GNU/Linux systems without any additional software requirement. It only requires the user to extract the given zip file on its hard drive and add udev rules as described in the Software Installation section below.

Software installation

In order to avoid running NxBase2 as root, the user must setup the Linux udev rules in order to access the board from Linux user space. NanoXplore recommends the following rule file (named 99-nxbase.rules on OpenSuse) for a user in the rd group:

# Raw EzUSB

ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="8613", ATTRS{idProduct}=="584e", MODE="666", GROUP="rd"

ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="58c0", ATTRS{idProduct}=="804e", MODE="666", GROUP="rd"

# ANGIE

ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="584e", ATTRS{idProduct}=="4a55", MODE="666", GROUP="rd"

ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="584e", ATTRS{idProduct}=="424e", MODE="666", GROUP="rd"

The file must be saved in the /etc/udev/rules.d directory and the udev rules must be reloaded with the following command (as root):

udevadm control --reload-rules

Software startup

The executable name is nxbase2_cli and must be run from a terminal. If the program is called without any argument (or using -h or --help options) it returns the nxbase2_cli usage. See sections below for more details about nxbase2_cli arguments.

Usage

Basic usage

nxbase2_cli automatically applies a comprehensive set of default settings for each board detected. Thanks to the automatic default configuration, it is possible to load a bitstream in the target using only one simple call to nxbase2_cli:

nxbase2_cli /path/to/the/bitstream

On an NG-MEDIUM or NG-LARGE DevKit, this will configure the first board found with minimal initialisations and then upload the given bitstream.

Sending commands to the system

nxbase2_cli is a command-based software. Interactions with the board are done by sending commands using one or more of the 3 following ways:

• Using an argument of the nxbase2_cli command line

• Using a command file as an argument of the nxbase2_cli command line

• Using the internal nxbase2_cli interactive shell

nxbase2_cli command argument (-c)

The most basic way to send a command is to use the -c option on the nxbase2_cli command line. The command must directly follow the -c and be quoted in order for the shell to consider it as a single argument.

Example:

nxbase2_cli -i -c "chip bitstream load /path/to/the/bitstream"

It is possible to specify more than one -c argument. In this case, the commands will be executed in the command line order. In the example below, board select 4 will be executed before the chip bitstream load /path/2bitstream command.

nxbase2_cli -i -c "board select 4" -c "chip bitstream load /path/2bitstream"

nxbase2_cli command file argument (-f)

A command file is defined as a text file containing one command per line. The path to the command file is given to nxbase2_cli using its -f option. The command file is executed line by line by nxbase2_cli.

An example of command file is given below:

board select 4
chip bitstream load /path/bitstream1
chip bitstream load /path/bitstream2
board select 3
chip bitstream load /path/bitstream1
chip bitstream load /path/bitstream2
chip bitstream load /path/bitstream3

This command file can be loaded as follow:

nxbase2_cli -f /path/to/command/file

interactive shell

nxbase2_cli also provides an interactive shell in order for the user to interact more dynamically with the devkit. The interactive shell is selected using the -s argument on nxbase2_cli command line.

If the shell is requested on the command line, nxbase2_cli gives the user a prompt (NxBase2>) and then waits for him to enter a command.

nxbase2_cli command line arguments

If no optional argument is given, the given command line:

nxbase2_cli /path/to/bitstream

is equivalent to:

nxbase2_cli -c "chip bitstream load /path/to/bitstream"

It is possible to specify more than one bitstream on the command line:

nxbase2_cli /path.to/bitstream1 /path/to/bitstream2 /path/to/bitstream3

is equivalent to:

nxbase2_cli -c “chip bitstream load /path/to/bitstream1” -c “chip bitstream load /path/to/bitstream2” -c “chip bitstream load /path/to/bitstream3” 

Here follows the description for each nxbase2_cli command line argument.

nxbase2_cli usage is given below:

usage: nxbase2_cli [-h] [-s] [-i] [-x] [-q] [-d]

                   [--logbuffer_timeout LOGBUFFER_TIMEOUT]

                   [--forced_board_ids FORCED_BOARD_IDS] [--logfile LOGFILE]

                   [--logfile_level {0,1,2,3}] [-f F] [-c C] [-o]

                   [--force_factory_mode] [--factory_mode_usb_ids] [--version]

                   [bitstream [bitstream ...]]
positional arguments:
  bitstream             One or more bitstream to load

optional arguments:
  -h, --help            show this help message and exit
  -s                    Switch to NxBase2 command line interpreter mode
  -i                    Not used anymore (here for compatibility)
  -x                    Explicitly display command result
  -q, --quit_on_error   quit on first error encountered
  -d                    increase logging level
  --logbuffer_timeout LOGBUFFER_TIMEOUT
                        Delayed buffer timeout. 0->no delayed buffer
  --forced_board_ids FORCED_BOARD_IDS
                        force board mezzanine ids to compatible id
  --logfile LOGFILE     logfile path
  --logfile_level {0,1,2,3}
                        logfile level
  -f F                  command file
  -c C                  command
  -o, --oem             Set OEM mode at startup
  --version             show program's version number and exit

Command reference

Commands are divided in 3 categories:

• General commands

• Board related commands

• Chip related commands

Command syntax

A command is described by its syntax (Usage field in this command reference). The notation used is described in the following table:

Example:

For the given command syntax:

board set clock <channel> <on/off> [burst_len] [polarization]

The following command inputs are valid:

• board set clock 0 off

• board set clock 1 on polarization=on

• board set clock clkd_id on burst_len=15

• board set clock another_string off burst_len=15 polarization=off

• board set clock 8 on polarization=none burst_len=4
  

General commands

help

Usage:

Help

Description:

Displays all available commands. All commands might not be applicable for the current board. Refer to the "applies on" field to determine which board is applicable:

• BrDk stands for NG-MEDIUM (Brave) Devkit

• NglDk stands for NG-LARGE Devkit

Example:

NxBase2>help

Board related commands

board help

Usage:

board help

Description:

Displays all available board related commands for the currently selected board.

Example:

NxBase2>board help

board list

Usage:

board list

Description:

Displays all detected boards. The currently selected board is marked with a star. The index returned by this command is used by the board select command to identify the requested board.

Example:

NxBase2>board list

board select

Usage:

board select <index>

Description:

Selects the board at the given index according to the board list command result. If the -i argument was given to the nxbase2_cli command line, and if the requested board wasn't initialized before, the init process is applied.

Example:

NxBase2>board select 8

board set reset

Usage:

board set reset <on/off>

Description:

Asserts or deasserts the chip reset pin.

Example:

NxBase2>board set reset on

NxBase2>board set reset off

board get mode list

Usage:

board get mode list

Description:

Displays all compatible modes for the chip on the current board.

Example:

NxBase2>board get mode list

board set mode

Usage:

board set mode <mode> [force]

Description:

Applies the given mode to the chip on the current board. If force is On or True, the force bit is set after setting the mode bits. The force parameter is set to True if not given. The valid modes values are given by the board get mode list command.

Example:

NxBase2>board set mode 'Jtag only'

NxBase2>board set mode 'Slave Spacewire' force=on

NxBase2>board set mode 'Slave Spacewire' force=off

board get mode

Usage:

board get mode

Description:

Retrieves the currently applied mode.

Example:

NxBase2>board get mode

board get force_bit

Usage:

board get force_bit

Description:

Checks if the mode is forced by the nxbase2_cli application. This is the case when the mode is applied using the board set mode command.

Example:

NxBase2>board get force_bit

board set force_bit

Usage:

board set force_bit <on_off>

Description:

Sets the board force bit.

Example:

NxBase2>board set force_bit on

NxBase2>board set force_bit off

board release force_bit

Usage:

board release force_bit

Description:

Stops the mode forcing. The chip mode will be restored with the mode configured on the board jumpers.

Example:

NxBase2>board release force_bit

board set jtag_clock

Usage:

board set jtag_clock <on/off>

Description:

Activates or deactivates the JTAG clock on the currently selected board.

Example:

NxBase2>board set jtag_clock on

NxBase2>board set jtag_clock off

board spi flash program

Usage:

board spi flash program <bitstream_path>

Description:

Writes the given bitstream to the SPI flash daughter board.

Example:

NxBase2>board spi flash program /path/to/nxb/file.nxb

board spi flash validate

Usage:

board spi flash validate <bitstream_path>

Description:

Compares the SPI flash daughter board content against the given bitstream.

Example:

NxBase2>board spi flash validate /path/to/nxb/file.nxb

board monitor list

Usage:

board monitor list

Description:

Get the list of available monitor channels installed on this board.

Example:

NxBase2>board monitor list

board monitor get

Usage:

board monitor get <channel_index>

Description:

Gathers the output values for the given monitoring channel index. If -1 is given, all the channels are retrieved. channel_index is given by the result of the board monitor list command.

Example:

NxBase2>board monitor get 0

NxBase2>board monitor get -1

board set oem mode

Usage:

board monitor set oem mode <on_off>

Description:

Activates or deactivates the OEM mode.

Example:

NxBase2>board set oem mode on

NxBase2>board set oem mode off

board get oem mode

Usage:

board get oem mode

Description:

Retrieves the current OEM mode.

Example:

NxBase2>board get oem mode

board get ids

Usage:

board get ids

Description:

Retrieves the board identifiers (ANGIE and Devkit itself).

Example:

NxBase2>board get ids

board set fabric_clock freq

Usage:

board set fabric_clock freq <freq>

Description:

Sets the internal fabric clock frequency

Example:

NxBase2> board set fabric_clock freq 48

board set fabric_clock ref ratio

Usage:

board set fabric_clock ref ratio <mul> <div>

Description:

Sets the internal fabric clock gen ratio. Default is mul=48, div=48 resulting in 48MHz output frequency.

Example:

NxBase2>board set fabric_clock ref ratio 24 48

board set fabric_clock continuous

Usage:

board set fabric_clock continuous <channel> <on/off> [divider] [polarization]

Description:

Enable or disable the continuous fabric clock on a given channel. Only available on NG-LARGE devkit on channel 0. In this case, the output fabric clock is sent on the MODE[3] ANGIE signal.

The divider parameter is an integer. It allows the user to easily divide the output fabric clock frequency.

The polarity parameter must be 0 or 1. It allows the user to invert the output fabric clock polarity. 0 means no inversion. 1 means inverted signal.

Examples:

NxBase2>board set fabric_clock continuous 0 on

NxBase2>board set fabric_clock continuous 0 off

NxBase2>board set fabric_clock continuous 0 on divider=2 polarization=1

board set fabric_clock burst

Usage:

board set fabric_clock burst <channel> <count> [divider] [polarization]

Description:

Enable or disable the burst on fabric clock on a given channel.

The burst parameter is an integer that represents the amount of clock pulses to send. divider and polarization parameters work like in the board set fabric_clock continuous command.

Example:

NxBase2>board set fabric_clock burst 0 22

NxBase2>board set fabric_clock burst 0 47823

NxBase2>board set fabric_clock burst 0 55 divider=4 polarization=1

board set jtag_head_tail

Usage:

board set jtag_head_tail <d_tail> <d_head> <i_tail> <i_head>

Description:

Sets the JTAG head and tail for data and instruction. This command is useless on NanoXplore board but can be useful on custom board with multiple JTAG devices on the JTAG bus.

Example:

NxBase2>board set jtag_head_tail 16 0 3 0

board probe

Usage:

board probe

Description:

This command checks if a board is connected to ANGIE. This command always returns True since V2.3.0 (since the -i option is always implied).

Example:

NxBase2>board probe

board set jtag_clock_divider

Usage:

board set jtag_clock_divider <div>

Description:

Sets the given JTAG clock divider. Base clock is 24MHz. Resulting clock is: base_clock /(2*(div+1)).

Example:

NxBase2>board set jtag_clock_divider 4

Chip related commands

chip help

Usage:

chip help

Description:

Displays all available chip related commands for the installed chip.

Example:

NxBase2>chip help

chip get id_code

Usage:

chip get id_code

Description:

Retrieves the chip id code.

Example:

NxBase2>chip get id_code

chip get user_code

Usage:

chip get user_code

Description:

Retrieves the chip user code.

Example:

NxBase2>chip get user_code

chip get status

Usage:

chip get status

Description:

Retrieves the chip errors.

Example:

NxBase2>chip get status

chip get thermal sensors

Usage:

chip get thermal sensors

Description:

Retrieves the temperature for each internal thermal sensor.

Example:

NxBase2>chip get thermal sensors

chip bitstream channel list

Usage:

chip bitstream channel list

Description:

Displays all the communication channels compatible with the chip. The currently selected channel is marked with a star.

Example:

NxBase2>chip bitstream channel list

chip bitstream channel select

Usage:

chip bitstream channel select <channel>

Description:

Selects the given channel. The channel must be chosen in the channel list returned by the chip bitstream channel list command. The selected channel will remain active until another one is selected or the current board changed via the board select command.

Example:

NxBase2>chip bitstream channel select 'Jtag'

chip bitstream get channel

Usage:

chip bitstream get channel

Description:

Returns the currently selected channel.

Example:

NxBase2>chip bitstream get channel

chip bitstream err_handler list

Usage:

chip bitstream err_handler list

Description:

Returns the list of available error handlers.

Example:

NxBase2>chip bitstream err_handler list

chip bitstream err_handler help

Usage:

chip bitstream err_handler <handler> help

Description:

Displays all the available options for the given handler. These options must be given to the chip bitstream select command.

Example:

NxBase2>chip bitstream err_handler 'Jtag' help

chip bitstream err_handler select

Usage:

chip bitstream err_handler select <handler> [handler_options]*

Description:

Selects the given handler with the given options.

Please refer to the result of chip bitstream err_handler help command for the list of available options. Previous options are discarded at each call to chip bitstream err_handler select or when current board is changed using the board select command.

Example:

NxBase2>chip bitstream err_handler select 'Text'

NxBase2>chip bitstream err_handler select 'Text' outfilepath=/path/to/logfile

NxBase2>chip bitstream err_handler select 'Text' show_cnts=True

NxBase2>chip bitstream err_handler select 'Text' show_headers=False

NxBase2>chip bitstream err_handler select 'Text' outfilepath=/path/to/logfile show_cnts=True

chip bitstream load

Usage:

chip bitstream load <path>

Description:

Loads the bitstream at the given path into the chip of the current board. The bitstream is uploaded trough the current channel and encountered errors are handled by the currently selected error handler.

If the given path is a directory, all the bitstreams contained in the directory will be uploaded in the order of their filename (using python sort algorithm).

Example:

NxBase2>chip bitstream load /path/to/a/nxb/file.nxb

NxBase2>chip bitstream load /path/to/a/directory

chip raw register access read

Usage:

chip raw register access read <address>

Description:

Returns the content of the register at the given address.

Example:

NxBase2>chip raw register access read 0x15

chip raw register access write

Usage:

chip raw register access write <address> <value>

Description:

Writes the given value in the register at the given address.

Example:

NxBase2>chip raw register access write 0x0F 0x55

chip cfgcheck init

Usage:

chip cfgcheck init <filename> [rows]

Description:

Creates a reference (golden) for the configuration memory. The result dump is saved in the given filename. The row parameter selects the rows to be dumped. Row numbers are expressed as a comma separated list. If no row is specified, all rows are selected. See SEE tests chapter for more details.

Examples:

NxBase2>chip cfgcheck init mydump

NxBase2>chip cfgcheck init mydump rows=0,1,4

chip cfgcheck compare

Usage:

chip cfgcheck compare <golden> [rows]

Description:

Reads back the configuration memory then compares it to a previously saved golden (dumped using the chip cfgcheck init command. The golden parameter represents the path to the golden. The row parameter selects the rows to be compared. Row numbers are expressed as a comma separated list. If no row is specified, all rows are selected. The number of rows must be identical between chip cfgcheck init and chip cfgcheck compare. See SEE tests chapter for more details.

Examples:

NxBase2>chip cfgcheck compare mydump

NxBase2>chip cfgcheck compare mydump rows=0,1,4

chip cmic set state

Usage:

chip cmic set state <on/off>

Description:

Sets the CMIC state.

Example:

NxBase2>chip cmic set state on

NxBase2>chip cmic set state off

chip get global channel list

Usage:

chip get global channel list 

Description:

Returns the list of all available channel for the current board/chip couple.

Example:

NxBase2>chip get global channel list

chip global channel select

Usage:

chip global channel select <channel>

Description:

Selects the given channel as base channel for every chip related command (except bitstream loading). See the chip get global channel list command for a list of applicable channels.

Example:

NxBase2>chip get global channel list

NXscope related commands

nxscope info

Usage:

nxscope info

Description:

Retrieves NXscope IP core parameters (version, number of input lines, capture depth).

Example:

NxBase2>nxscope info

nxscope capture

Usage:

nxscope capture <output_file> <freq> [immediate] [timeout]

Description:

Starts and retrieves data from the running NXscope IP core. The output_file parameter contains the path of the file which will contain data. If output_file ends with .vcd, a VCD file is generated. For any other file extension, data format is:

• text file

• 1 line per sample

• one digit (0 or 1) per sample bit, MSB first

The freq parameter specifies the frequency of the user design running in the FPGA expressed in Hz with scientific notation (ie: 25E6 for 25MHz). This parameter is essential for vcd file generation.

The immediate, if set to 1, will immediately trigger a capture (and will not wait for the trigger condition).

The timeout parameter, if given, sets the trigger wait timeout (expressed in seconds).

For more details, please refer to the NXscope user manual.

Example:

NxBase2>nxscope capture outfile.txt 25E6

NxBase2>nxscope capture outfile.txt 50E6 immediate=1

NxBase2>nxscope capture outfile.vcd 50E6 immediate=1 timeout=10

NxBase2>nxscope capture outfile.vcd 50E6 timeout=10

Command and bitstream processing

Board initialization

In order to be able to execute a command or upload a bitstream in the chip of an uninitialized board, the user needs to perform some actions.

If nxbase2_cli is started without the -i option, the software will only perform the following initialisations:

• Asserts the Reset signal.

• Disables the JTAG clock.

• Unforces the mode and use the one selected by the board jumpers.

The -i option performs the following actions (in that order):

• Sets the current mode to JTAG.

• Forces the mode using the force bit.

• Activates the JTAG clock.

• Deasserts the Reset signal.

It is perfectly possible to perform these actions using the corresponding commands for each newly selected board. The -i option just performs this automatically.

Chip channels

A NanoXplore chip usually embeds more than one way (channel) to configure it using nxbase2_cli. According to the type of DevKit used, some of the channels might not be available.

On the NG-MEDIUM/NG-LARGE DevKit, the interface role is played by the Angie board that only handles the JTAG channel. So nxbase2_cli will only show the JTAG channel in both the chip bitstream channel list chip get global channel list commands result.

Nxbase2_cli allows two independent channel configurations:

• Channel for the bitstream loading

• Channel for any other commands

Channel for bitstream loading is selected by

Bitstream Error handling

When a bitstream is uploaded, errors might occur. In this case, all errors are collected by the currently selected error handler and processed according to its predefined behaviour. Each error handler has its own way of processing error.

nxbase2_cli is shipped with 2 default error handlers:

• Dummy: Does nothing and discard all messages

• Text: Displays the error on the screen and/or a text file

Text is the error handler selected by default.

Dummy

This error handler is simple. It take no argument and does nothing but dropping the messages when they arrive.

Text

This is the default error handler. It displays errors in a readable form on the screen.

It has 3 options:

SPI flash programming

It is possible to program a bitstream into a compatible SPI flash memory plugged in the dedicated connector using the board spi flash program command. It is also possible to compare any flash content to a given bitstream using the board spi flash validate command. See the board related commands reference for more details.

The supported flash memory part numbers are given by the following table:

NG-MEDIUM and NG-LARGE configuration interface are only compatible with uniform 256KB sector size.

Using the ANGIE JTAG adaptor with non-NanoXplore boards

Introduction

While prototyping boards, it might be useful to upload bitstreams inside the NanoXplore chip using the given ANGIE JTAG adapter and NxBase2_cli.

Nevertheless, the ANGIE/nxbase2_cli duo requires some specific hardware accommodations in order to work correctly.

In case the required hardware cannot be populated, nxbase2_cli provides a specific mode called OEM mode. This mode indicates to nxbase2_cli to ignore errors due to the lake of hardware.

Non-OEM mode

This is the recommended mode. It will let you access to all ANGIE and nxbase2_cli features. The board must satisfy the following requirements:

• A 24LC128 serial EEPROM connected to the ANGIE I2C bus

• A JTAG connection between the ANGIE and the chip

• A way to override the chip mode using the ANGIE mode pins

• A voltage supervisor

• A circuitry to properly reset the chip JTAG interface

• Connect the /RST signal from ANGIE interface to the chip service reset pin

The serial EEPROM memory might be used to store any kind of data but the six first bytes must contain the following magic code (in ASCII): "NGMDK" for NG-MEDIUM devkit, “NGL_DK” for NG-MARGE devkit. The EEPROM I2C address must be 0x51.

A design reference is provided on the following page.

OEM mode

In this mode, the board designer might discard the serial EEPROM and the mode override circuitry. However, the chip mode must be fixed to JTAG mode if no override mechanism is provided.

The procedure to upload bitstreams using nxbase2_cli is now the following:

• Start nxbase2_cli with -i and -s options.

• Select the desired board if more than one board is connected

• Activate the OEM mode: board set oem mode on

• Upload bitstreams as usual using chip bitstream load path

It is possible to load a bitstream directly from a terminal by using a chain of command:

nxbase2_cli -i -C"board select X" -C"board set oem mode on" -C"chip bitstream load path"

SEE tests utilities

NxBase2 can be used to perform basic configuration memory SEE tests using the 2 following commands:

• chip cfgcheck init

• chip cfgcheck compare

Both commands use the default channel to communicate with the chip.

Test procedure

Use of these commands is very simple and can be summarized in the following steps:

1. Configure the tested chip

2. Use chip cfgcheck init to create an image of the current configuration memory (aka golden).

3. Run tests.

4. Run chip cfgcheck compare to get the number of differences between the golden and the current configuration.

5. If you need more results, perform a power cycle, reload the configuration then jump back to step 3.

Cross section computation

Cross section computation can be done using the number of errors given by chip cfgcheck compare and the number of configuration memory elements in the chip. The table below gives these details for the NG-MEDIUM chip.