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:

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):

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:

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.

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 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:

This command file can be loaded as follow:

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:

is equivalent to:

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

is equivalent to:

Here follows the description for each nxbase2_cli command line argument.

nxbase2_cli usage is given below:

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:

For the given command syntax:

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

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

Board related commands

board help

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

board list

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.

board select

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.

board set reset

Asserts or deasserts the chip reset pin.

board get mode list

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

board set mode

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.

board get mode

Retrieves the currently applied mode.

board get force_bit

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.

board set force_bit

Sets the board force bit.

board release force_bit

Stops the mode forcing. The chip mode will be restored with the mode configured on the board jumpers. The selected channel is adapted to the mode configured on the board jumpers.

board set jtag_clock

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

board spi flash program

Writes the given bitstream to the SPI flash daughter board.

board spi flash validate

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

board monitor list

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

board monitor get

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.

board set oem mode

Activates or deactivates the OEM mode.

board get oem mode

Retrieves the current OEM mode.

board get ids

Retrieves the board identifiers (ANGIE and Devkit itself).

board set fabric_clock freq

Sets the internal fabric clock frequency

board set fabric_clock ref ratio

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

board set fabric_clock continuous

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.

board set fabric_clock burst

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.

board set jtag_head_tail

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.

board probe

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).

board set jtag_clock_divider

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

Chip related commands

chip help

Displays all available chip related commands for the installed chip.

chip get id_code

Retrieves the chip id code.

chip get user_code

Retrieves the chip user code.

chip get status

Retrieves the chip errors.

chip get thermal sensors

Retrieves the temperature for each internal thermal sensor.

chip bitstream channel list

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

chip bitstream channel select

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.

chip bitstream get channel

Returns the currently selected channel.

chip bitstream err_handler list

Returns the list of available error handlers.

chip bitstream err_handler help

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

chip bitstream err_handler select

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.

chip bitstream load

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).

chip raw register access read

Returns the content of the register at the given address.

chip raw register access write

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

chip cfgcheck init

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.

chip cfgcheck compare

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.

chip cmic set state

Sets the CMIC state.

chip get global channel list

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

chip global channel select

NXscope related commands

nxscope info

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

nxscope capture

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.

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.

Open

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

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): "BR_DK" 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:

Open

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