NxBase2 User Manual

Owned by Julia DAUMAL (Unlicensed)
Last updated: 11 Oct, 2022 by Samah
17 min read

Revision

Date

Originator

Comments

1.0

03/03/2017

Cédric DEBARGE

Creation

1.1

09/05/2017

Cédric DEBARGE

Updates to cover Nxbase2 version 2.1.0

1.2

12/06/2017

Cédric DEBARGE

Updates to cover Nxbase2 version 2.1.1

1.3

20/07/2018

Cédric DEBARGE

Updates to cover Nxbase2 version 2.2.0

1.4

14/01/2019

Cédric DEBARGE

Updates to cover Nxbase2 version 2.2.1

1.5

01/04/2019

Cédric DEBARGE

Updates to cover Nxbase2 version 2.2.2

1.6

23/12/2019

Cédric DEBARGE

Updates to cover Nxbase2 version 2.3.0

1.6.1

13/02/2020

Cédric DEBARGE

Fixes some typos

1.7

05/08/2020

Cédric DEBARGE

Updates to cover Nxbase2 version 2.3.1

1.8

31/08/2021

Cédric DEBARGE

Updates to cover Nxbase2 version 2.5.0



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

you MUST replace the “rd” group given in example above by an actual group name for which the Unix user is a member of. On most GNU/Linux distributions, each Unix user also get a Unix group with the same name. Thus, using the Unix user name as Unix group name should work. You can retrieve the current Unix user name by typing the following command:

whoami

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:

 

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:

It is not necessary to quote the command in a command file since a new line is used to delimit the commands.

In case of simultaneous use of both -c and -f options, the command file will be executed before the commands specified by the -c option.

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.

Option

Description

-h, --help

Displays usage, help and quits.

--version

Displays the nxbase2_cli version and then quits.

-s

Starts the interactive shell.

-f commandfile

Executes all commands in the given command file.

-c command

Executes the given command.

-q, --quit_on_error

Quit nxbase2_cli on the first encountered error.

-i

Does nothing. Just here for compatibility. See below for more details.

-d

Increases the debug level.

Can be repeated multiple times or concatenated (-ddd).

-x

Explicitly show command results.

-o, --oem

Set OEM mode at startup

--fored_board_ids ids

Bypass board detection and use given ids.

--logfile logfile

Specifies a path to a text file where all the messages will be redirected. The display of messages on screen is not affected.

--logfile_level level

Specifies the debug level for the logfile as a number. 0 means no debugs, 3 means full debugs.

--logbuffer_timeout timeout

Screen messages are displayed periodically each timeout seconds.

 

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:

Element

Description

element

Mandatory part of the command name. Must be supplied unchanged.

<value>

Mandatory parameter with no constraint on the expected value.

<on/off/none>

Mandatory parameter. A slash separates all valid values.

[opt]

Optional parameter. Must be specified in the following form: opt=value. The order of optional parameters is not relevant as long as all mandatory parameters are placed before the first optional one.

[opt]*

One or many optional parameters. All rules about optional parameters placement and syntax remain valid.

Example:

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

Usage:

 

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:

Board related commands

board help

Usage:

Description:

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

Example:

board list

Usage:

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:

board select

Usage:

 

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:

board set reset

Usage:

 

Description:

Asserts or deasserts the chip reset pin.

 

Example:

 

board get mode list

Usage:

 

Description:

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

 

Example:

 

board set mode

Usage:

 

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:

 

board get mode

Usage:

 

Description:

Retrieves the currently applied mode.

 

Example:

 

board get force_bit

Usage:

 

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:

board set force_bit

Usage:

 

Description:

Sets the board force bit.

 

Example:

board release force_bit

Usage:

 

Description:

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.

 

Example:

board set jtag_clock

Usage:

 

Description:

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

 

Example:

board spi flash program

Usage:

 

Description:

Writes the given bitstream to the SPI flash daughter board.

 

Example:

board spi flash validate

Usage:

 

Description:

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

 

Example:

board monitor list

Usage:

 

Description:

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

 

Example:

board monitor get

Usage:

 

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:

board set oem mode

Usage:

 

Description:

Activates or deactivates the OEM mode.

 

Example:

board get oem mode

Usage:

 

Description:

Retrieves the current OEM mode.

 

Example:

board get ids

Usage:

 

Description:

Retrieves the board identifiers (ANGIE and Devkit itself).

 

Example:

board set fabric_clock freq

Usage:

 

Description:

Sets the internal fabric clock frequency

 

Example:

 

board set fabric_clock ref ratio

Usage:

 

Description:

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

 

Example:

 

board set fabric_clock continuous

Usage:

 

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:

 

board set fabric_clock burst

Usage:

 

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:

 

board set jtag_head_tail

Usage:

 

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:

 

board probe

Usage:

 

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:

 

board set jtag_clock_divider

Usage:

 

Description:

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

 

Example:

 

 

Chip related commands

chip help

Usage:

 

Description:

Displays all available chip related commands for the installed chip.

 

Example:

chip get id_code

Usage:

 

Description:

Retrieves the chip id code.

 

Example:

chip get user_code

Usage:

 

Description:

Retrieves the chip user code.

 

Example:

chip get status

Usage:

 

Description:

Retrieves the chip errors.

 

Example:

chip get thermal sensors

Usage:

 

Description:

Retrieves the temperature for each internal thermal sensor.

 

Example:

chip bitstream channel list

Usage:

 

Description:

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

 

Example:

 

chip bitstream channel select

Usage:

 

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:

chip bitstream get channel

Usage:

 

Description:

Returns the currently selected channel.

 

Example:

chip bitstream err_handler list

Usage:

 

Description:

Returns the list of available error handlers.

 

Example:

chip bitstream err_handler help

Usage:

 

Description:

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

 

Example:

chip bitstream err_handler select

Usage:

 

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:

chip bitstream load

Usage:

 

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:

chip raw register access read

Usage:

 

Description:

Returns the content of the register at the given address.

 

Example:

chip raw register access write

Usage:

 

Description:

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

 

Example:

chip cfgcheck init

Usage:

 

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:

chip cfgcheck compare

Usage:

 

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:

chip cmic set state

Usage:

 

Description:

Sets the CMIC state.

 

Example:

chip get global channel list

Usage:

 

Description:

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

 

Example:

chip global channel select

Usage:

 

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:

 

NXscope related commands

nxscope info

Usage:

 

Description:

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

 

Example:

nxscope capture

Usage:

 

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:



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:

 

Option

Description

outfilepath

Duplicates the messages in the file pointed by this path.

Show_headers

Adds messages before and after bitstream processing to show information (date, bitstream name ...).

Show_counters

Shows the read counters.

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:

 

Flash part number

Support introduced in

S25FL512

version 2.1.0

S25FL256

version 2.1.1

S25FL128

version 2.1.1

IS25LP128

version 2.2.0

CYRS16B256

version 2.3.0

 

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



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.

 

Row

Configuration memory elements

0

1558016

1

941440

2

1138864

3

941760

4

1558016

Total

6138096

 

© NanoXplore 2022