Nios® II Software Developer Handbook

ID 683525
Date 8/28/2023
Public
Document Table of Contents

5.11.3.4.1. nios2-download

Description

This tool prepares a target system for debugging, it checks that the hardware and software are compatible, downloads the software and optionally makes the target processor run the downloaded code.

Usage

nios2-download [-h/--help] [-C/--directory <dir name>]
       [-c/--cable <cable name>] [-d/--device <device index>]
       [-i/--instance <instance>] [-r/--reset-target]        
       [-s/--sidp <address> -I/--id <id> -t/--timestamp <timestamp>]
       [--accept-bad-sysid] [-w/--wait <seconds>] [-g/--go] [--stop]
           [--tcpport <port> | auto] [--write-gmon <file>]          
           [--jdi <file>] [--cpu_name <name>]                       
           [<filename>]      

Options

 -h/--help                   Prints this message.

 -C/--directory <dir name>   Change to this directory before running

 -c/--cable <cable name>     Specifies which JTAG cable to use (not needed if
                             you only have one cable).                       
 -d/--device <device index>  Specifies in which device you want to look for the
                             
               Nios® II CPU (1 = device nearest TDI etc.)         
 -i/--instance <instance>    Specifies the INSTANCE value of the 
               Nios® II CPU   
                             JTAG debug module (auto-detected if you specify   
                             an ELF file or use --directory to point to one)   

 -r/--reset-target           Reset the target SOPC system before use.

 -s/--sidp <address>         Base-address of System ID peripheral on target
                             This base-address must be specified in hex (0x...)
 -I/--id <system-id-value>   Unique ID code for target system
 -t/--timestamp <time-stamp> Timestamp for target-system (when last generated)
    --accept-bad-sysid       Continue even if the system ID comparison fails

 <filename.elf>              An ELF file to download to the target

 -w/--wait <seconds>         Wait for time specified before starting processor
 -g/--go                     Run processor from entry point after downloading.
    --stop                   Stop processor (leave it in a paused state).
    --tcpport <port> | auto  Listen on specified TCP port for a connection from
                             GDB (with "auto" a free port is used).
    --write-gmon <file>      Write profiling data to the file specified when the
                             target exits.
    --jdi <file>            Specify which .jdi file to read the INSTANCE
                             value of the 
               Nios® II CPU JTAG debug module from.
                             (if not specified, looks in the same folder
                             as the .ptf file, as specified in generated.sh)
    --cpu_name <name>        CPU module name to use when trying to scan for
                             INSTANCE value from the .jdi file.  Uses the
                             name specified in generated.sh if it is not passed
                             in.
                    NOTE:    nios2-download needs a .jdi file and a cpu_name
                             to search for the INSTANCE value.  This can be
                             supplied through the command line, or searched
                             for with information from generated.sh

If you specify the --go option then the target processor starts before this tool exits. If --go is not specified but a file is downloaded or the target processor needs to be reset then it is left in the paused state. Otherwise the target processor state is left unchanged unless --stop is specified (in which case it is paused). Return codes are: 0 for success; 1 if the system ID did not match; 2 if no Nios® II CPUs are found; a return code of 4 or more indicates an error which needs manual intervention to solve.