A BSP contains the following elements:

• Hardware abstraction layer
• Optional custom newlib C standard library¹
• Device drivers
• Optional software packages
• Optional real-time operating system

The Nios^® II EDS includes documented software examples to demonstrate all prominent features of the Nios^® II processor and the development environment. The examples can help you start the development of your custom design. They provide a stable starting point for exploring design options. Also, they demonstrate many commonly used features of the Nios^® II EDS.

The Nios^® II software examples directory contains the following files:

• Source file (.c)
• Header file (.h)
• readme.txt
• template.xml

• The Nios^® II Processor Reference Guide defines the processor hardware architecture and features, including the instruction set architecture.
• The Embedded Peripherals IP User Guide provides a reference for the peripherals distributed with the Nios^® II processor. This handbook describes the hardware structure and Nios^® II software drivers for each peripheral.
• The Embedded Design Handbook describes how to use the software development tools effectively, and recommends design styles and practices for developing, debugging, and optimizing embedded systems.
• The Intel FPGA Knowledge Database is an Internet resource that offers solutions to frequently asked questions with an easy-to-use search engine.
• Application notes and tutorials offer step-by-step instructions on using the Nios^® II processor for a specific application or purpose. These documents are available on the Intel FPGA Nios^® II Processor Documentation web page.
• The Nios^® II EDS documentation launchpad. The launchpad is an HTML page installed with the Nios^® II EDS, which provides links to Nios^® II documentation, examples, and other resources. The way you open the launchpad depends on your software platform.
  • In the Windows operating system, on the Start menu, point to Programs > Intel FPGA > Nios II EDS, and click Nios^® II <version> Documentation.
  • In the Linux operating system, open < Nios^® II EDS install path>/documents/index.html in a web browser.

You specify a BSP in the second page of the wizard.

Select a descriptive name for your project. The SBT creates a folder with this name to contain the application project files.

Letters, numbers, and the underscore (_) symbol are the only valid project name characters. Project names cannot contain spaces or special characters. The first character in the project name must be a letter or underscore. The maximum filename length is 250 characters.

You select the project template from the Templates list.

The hello_world template provides an easy way to create your first Nios II project and verify that it builds and runs correctly.

To place your application project in a different folder, turn off Use default location, and specify the path in the Project location box.

On the second page, you specify the BSP to link with your application. You can create a new BSP for your application, or select an existing BSP. Creating a new BSP is often the simplest way to get a project running the first time.

You optionally specify the name and location of the BSP.

The SBT copies required source files to your project directories, and creates makefiles and other generated files. Finally, the SBT executes a make clean command on your BSP.

This section describes how to run a Nios II program using the Nios II SBT for Eclipse on Nios II hardware, such as an Intel FPGA development board.

To run a software project, right-click the application project name, point to Run As, and click Nios II Hardware. To run a software project as a ModelSim simulation, right-click the application project name, point to Run As, and click Nios II ModelSim.

This command carries out the following actions:

• Creates a Nios II run configuration.
• Builds the project executable. If all target files are up to date, nothing is built.
• Establishes communications with the target, and verifies that the FPGA is configured with the correct hardware design.
• Downloads the Executable and Linking Format File (.elf) to the target memory
• Starts execution at the .elf entry point.

Program output appears in the Nios II Console view. The Nios II Console view maintains a terminal I/O connection with a communication device connected to the Nios II processor in the hardware system, such as a JTAG UART. When the Nios II program writes to stdout or stderr, the Nios II Console view displays the text. The Nios II Console view can also accept character input from the host keyboard, which is sent to the processor and read as stdin.

To disconnect the terminal from the target, click the Terminate icon in the Nios II Console view. Terminating only disconnects the host from the target. The target processor continues executing the program.

This section describes how to debug a Nios II program using the Nios II SBT for Eclipse on Nios II hardware, such as an Intel FPGA development board.

To debug a software project, right-click the application project name, point to Debug As, and click Nios II Hardware. This command carries out the following actions:

• Creates a Nios II run configuration.
• Builds the project executable. If all target files are up to date, nothing is built.
• If debugging on hardware, establishes communications with the target, and verifies that the FPGA is configured with the correct hardware design.
• Downloads the .elf to the target memory.
• Sets a breakpoint at the top of main().
• Starts execution at the .elf entry point.

The Eclipse debugger with the Nios II plugins provides a Nios II perspective, allowing you to perform many common debugging tasks. Debugging a Nios II program with the Nios II plugins is generally the same as debugging any other C/C++ program with Eclipse and the CDT plugins.

For information about debugging with Eclipse and the CDT plugins, refer to the Eclipse help system.

• Controlling program execution with commands such as:
  • Suspend (pause)
  • Resume
  • Terminate
  • Step Into
  • Step Over
  • Step Return
• Setting breakpoints and watchpoints
• Viewing disassembly
• Instruction stepping mode
• Displaying and changing the values of local and global variables in the following formats:
  • Binary
  • Decimal
  • Hexadecimal
• Displaying watch expressions
• Viewing and editing registers in the following formats:
  • Binary
  • Decimal
  • Hexadecimal
• Viewing and editing memory in the following formats:
  • Hexadecimal
  • ASCII
  • Signed integer
  • Unsigned integer
• Viewing stack frames in the Debug view

When an exception is hit, the cause value in the Nios^® II Exception Register can be decoded using the Nios^® II Exceptions (In Decreasing Priority Order) table from the Nios^® II Processor Reference Handbook.

You can select the operating system only at the time you create the BSP. To change operating systems, you must create a new BSP by using the Additional arguments to the nios2-bsp script.

If you intend to run the project in the Nios^® II ModelSim™ simulation environment, use the Additional arguments parameter to specify the location of the test bench simulation package descriptor file (.spd). The .spd file is located in the Intel^® Quartus^® Prime project directory. Specify the path as follows: --set QUARTUS_PROJECT_DIR=<relative path> .

You can examine and modify many makefile properties in the Nios^® II Application Properties or Nios^® II Library Properties dialog box. To open the dialog box, right-click the project, click Properties > Nios^® II Application Properties or Properties > Nios^® II Library Properties.

After the SBT has created a makefile, you can modify the makefile in the following ways:

• With the Nios^® II SBT for Eclipse.
• With Nios^® II SBT commands from the Nios^® II Command Shell.

When modifying a makefile, the SBT preserves any previous nonconflicting modifications, regardless how those modifications were made.

After you modify a makefile with the Nios^® II Command Shell, in Eclipse you must right-click the project and click Update linked resource to keep the Eclipse project view in step with the makefile.

When the Nios^® II SBT for Eclipse modifies a makefile, it locks the makefile to prevent corruption by other processes. You cannot edit the makefile from the command line until the SBT has removed the lock.

If you want to exclude a resource (a file or a folder) from the Nios^® II makefile temporarily, without deleting it from the project, you can use the Remove from Nios^® II Build command. Right-click the resource and click Remove from Nios^® II Build. When a resource is excluded from the build, it does not appear in the makefile, and Eclipse ignores it. However, it is still visible in the Project Explorer, with a modified icon. To add the resource back into the build, right-click the resource and click Add to Nios^® II Build.

An Eclipse linked resource can be either a file or a folder. With a linked folder, all source files in the folder and its subfolders are included in the build.

When you add a linked resource (file or folder) to your project, the SBT for Eclipse adds the file or folder to your makefile with an absolute path name. You might use a linked resource to refer to common source files in a fixed location. In this situation, you can move the project to a different directory without disturbing the common source file references.

A linked resource appears with a modified icon (green dot) in the Project Explorer, to distinguish it from source files and folders that are part of the project. You can use the Eclipse debugger to step into a linked source file, exactly as if it were part of the project.

You can reconfigure your project to refer to any linked resource either as an individual file, or through its parent folder. Right-click the linked resource and click Update Linked Resource.

You can use the Remove from Nios^® II Build and Add to Nios^® II Build commands with linked resources. When a linked resource is excluded from the build, its icon is modified with a white dot.

You can use Eclipse to create a path variable, defining the location of a linked resource. A path variable makes it easy to modify the location of one or more files in your project.

For information about working with path variables and creating linked resources, refer to the Eclipse help system.

Simply turn off Enable source management to convert the makefile to user source management. When Enable source management is off, you must update your makefile manually to add or remove source files to or from the project. The SBT for Eclipse makes no changes to the list of source files, but continues to manage all other project parameters and settings in the makefile.

In a makefile with user-managed sources, you can refer to source files with an absolute path. You might use an absolute path to refer to common source files in a fixed location. In this situation, you can move the project to a different directory without disturbing the common source file references.

Projects with user-managed sources do not support the following features:

• Linked resources
• The Add to Nios^® II Build command
• The Remove from Nios^® II Build command

BSP makefiles must be managed by the SBT, either through the BSP Editor or through the SBT command-line utilities.

You can also export a Tcl script from the BSP Editor, containing all the settings in an existing BSP. By studying such a script, you can learn about how BSP Tcl scripts are constructed.

• Right-click an existing project, point to Nios^® II , and click BSP Editor. The editor loads the BSP Settings File (.bsp) associated with your project, and is ready to update it.
• On the Nios^® II menu, click Nios^® II BSP Editor. The editor starts without loading a .bsp file.
• Right-click an existing BSP project and click Properties. In the Properties dialog box, select Nios^® II BSP Properties > BSP Editor. The editor loads your .bsp file for update.

Below the console area is the Generate button. This button is enabled when the BSP settings are valid. It generates the BSP target files, as shown in the Target BSP Directory tab.

• The Main tab
• The Software Packages tab
• The Drivers tab
• The Linker Script tab
• The Enable File Generation tab
• The Target BSP Directory tab

Each tab allows you to view and edit a particular aspect of the .bsp, along with relevant command line parameters and Tcl scripts.

The settings that appear on the Main, Software Packages and Drivers tabs are the same as the settings you manipulate on the command line.

• The path to the .sopcinfo file specifying the target hardware
• The processor name
• The operating system and version

• The BSP target directory—the destination for files that the SBT copies and creates for your BSP.
• BSP settings

BSP settings appear in a tree structure. Settings are organized into Common and Advanced categories. Settings are further organized into functional groups. The available settings depend on the operating system.

When you select a group of settings, the controls for those settings appear in the pane to the right of the tree. When you select a single setting, the pane shows the setting control, the full setting name, and the setting description.

At the top of the Software Packages tab is the software package table, listing each available software package. The table allows you to select the software package version, and enable or disable the software package.

The operating system determines which software packages are available.

Many software packages define settings that you can control in your BSP. When you enable a software package, the available settings appear in a tree structure, organized into Common and Advanced settings.

When you select a group of settings, the controls for those settings appear in the pane to the right of the tree. When you select a single setting, the pane shows the setting control, the full setting name, and the setting description.

Enabling and disabling software packages and editing software package settings can have a profound impact on BSP behavior. Refer to the documentation for the specific software package for details.

At the top of the Drivers tab is the driver table, mapping components in the hardware system to drivers. The driver table shows components with driver support. Each component has a module name, module version, module class name, driver name, and driver version, determined by the contents of the hardware system. The table allows you to select the driver by name and version, as well as to enable or disable each driver.

When you select a driver version, all instances of that driver in the BSP are set to the version you select. Only one version of a given driver can be used in an individual BSP.

Many drivers define settings that you can control in your BSP. Available driver settings appear in a tree structure below the driver table, organized into Common and Advanced settings.

When you select a group of settings, the controls for those settings appear in the pane to the right of the tree. When you select a single setting, the pane shows the setting control, the full setting name, and the setting description.

Enabling and disabling device drivers, changing drivers and driver versions, and editing driver settings, can have a profound impact on BSP behavior. Refer to the relevant component documentation and driver information for details.

When you make a change to the memory configuration, the SBT validates your change.

• Add—Adds a linker section mapping to an existing linker region. The Add button opens the Add Section Mapping dialog box, where you specify a new section name and an existing linker region.
• Remove—Removes a mapping from a linker section to a linker region.
• Restore Defaults—Restores the section mappings to the default configuration set up at the time of BSP creation.

You reassign a defined linker region to a different memory device by selecting a different device name in the Memory Device Name column. The Size and Offset columns are editable. You can also edit the list of linker regions using the following buttons located next to the linker region table:

• Add—Adds a linker region in unused space on any existing device. The Add button opens the Add Memory Region dialog box, where you specify the memory device, the new memory region name, the region size, and the region's offset from the device base address.
• Remove—Removes a linker region definition. Removing a region frees the region's memory space to be used for other regions.
• Add Memory Device—Creates a linker region representing a memory device that is outside the hardware system. The button launches the Add Memory Device dialog box, where you can specify the device name, memory size and base address. After you add the device, it appears in the linker region table, the Memory Device Usage Table dialog box, and the Memory Map dialog box. This functionality is equivalent to the add_memory_device Tcl command.

• Restore Defaults—restores the memory regions to the default configuration set up at the time of BSP creation.
• Memory Usage—Opens the Memory Device Usage Table. The Memory Device Usage Table allows you to view memory device usage by defined memory region. As memory regions are added, removed, and adjusted, each device's free memory, used memory, and percentage of available memory are updated. The rightmost column is a graphical representation of the device’s usage, according to the memory regions assigned to it.
• Memory Map—Opens the Memory Map dialog box. The memory map allows you to view a map of system memory in the processor address space. The Device table is a read-only reference showing memories in the hardware system that are mastered by the selected processor. Devices are listed in memory address order.

  To the right of the Device table is a graphical representation of the processor's memory space, showing the locations of devices in the table. Gaps indicate unmapped address space.

It does not depict the actual file system, but rather the files and directories to be created or copied when the BSP is generated. Each software component, including the operating system, drivers, and software packages, specifies source code to be copied into the BSP target directory. The files are generated in the directory specified on the Main tab.

When you generate the BSP, existing BSP files are overwritten, unless you disable generation of the file in the Enable File Generation tab.

• The Information tab
• The Problems tab
• The Processing tab

• Regenerate the BSP from the command line
• Recreate the BSP as a starting point for a new BSP
• Recreate the BSP on a different hardware platform
• Examine the Tcl script to improve your understanding of Tcl command usage

The exported Tcl script captures all BSP settings that you have changed since the previous time the BSP settings file was saved. If you export a Tcl script after creating a new BSP, the script captures all nondefault settings in the BSP. If you export a Tcl script after editing a pre-existing BSP, the script captures your changes from the current editing session.

To export a Tcl script, in the Tools menu, click Export Tcl Script, and specify a filename and destination path. The file extension is .tcl.

You can later run your exported script as a part of creating a new BSP.

In this dialog box, you specify the following parameters:

• The .sopcinfo file defining the hardware platform.
• The CPU name of the targeted processor.
• The BSP type and version.

Normally, you specify the path to your .sopcinfo file relative to the BSP directory. This enables you to move, copy and archive the hardware and software files together. If you browse to the .sopcinfo file, or specify an absolute path, the Nios II BSP Editor offers to convert your path to the relative form.

This feature allows you to perform the following tasks:

• Recreate an existing BSP as a starting point for a new BSP
• Recreate a BSP on a different hardware platform
• Include custom settings common to a group of BSPs

The Tcl script can be created by hand or exported from another BSP.

If your modifications to the underlying hardware design result in BSP validation errors, the best practice is to update or recreate the BSP. Updating and recreating BSPs is very easy with the BSP Editor.

If you recreate your BSP, you might find it helpful to capture your old BSP settings by exporting them to a Tcl script. You can edit the Tcl script to remove any settings that are incompatible with the new hardware design.

• You can right-click an application, point to Run As, and click Run Configurations.
• You can right-click an application, point to Debug As, and click Debug Configurations.

Depending on which way you opened the run configuration dialog box, the title is either Run Configuration or Debug Configuration. However, both views show the same run configurations.

Each run configuration is presented on several tabs. This section describes each tab.

• Specify the processor on which to execute the program (if the hardware design provides multiple processors)
• Specify the device to use for standard I/O
• Specify the expected location, timestamp and value of the system ID
• Specify the path to the Intel^® Quartus^® Prime JTAG Debugging Information File (.jdi)
• Enable or disable profiling

The Nios II SBT for Eclipse sets these parameters to reasonable defaults. Do not modify them unless you have a clear understanding of their effects.

• Select the cable, if more than one cable is available
• Allow software to run despite a system ID value or timestamp that differs from the hardware
• Reset the processor when the software is downloaded

The System ID Properties button allows you to examine the system ID and timestamp in both the .elf file and the hardware. This can be helpful when you need to analyze the cause of a system ID or timestamp mismatch.

• Command-line C/C++ application project
• Command-line BSP project
• Command-line user library project

You can edit, build, debug, and manage the settings of an imported project exactly the same way you edit, build, debug, and manage the settings of a project created in Nios II SBT for Eclipse.

You can continue to develop project code in your SBT project after importing the project into Eclipse. You can edit source files and rebuild the project, using the SBT either in Eclipse or on the command line.

• Import a command-line C/C++ application
• Import a supporting project
• Debug a command-line C/C++ application
• Edit command-line C/C++ application code

When importing a project, the SBT for Eclipse might make some minor changes to your makefile. If the makefile refers to a source file located outside the project directory tree, the SBT for Eclipse treats that file as a linked resource. However, it does not add or remove any source files to or from your makefile.

When you import an application or user library project, the Nios^® II SBT for Eclipse allows you to choose Eclipse source management or user source management. Unless your project has an unusual directory structure, choose Eclipse source management, to allow the SBT for Eclipse to automatically maintain your list of source files.

You debug and edit an imported project exactly the same way you debug and edit a project created in Eclipse.

If you do not need BSP or user library source code visible in the debugger, you can skip this task, and proceed to debug your project exactly as if you had created it in Eclipse.

If you have several C/C++ applications based on one BSP or user library, import the BSP or user library once, and then import each application that is based on the BSP or user library. Each application's makefile contains the information needed to find and build any associated BSP or libraries.

With user source management, Eclipse never makes any changes to the list of source files in your makefile. However, the SBT for Eclipse manages all other project parameters and settings, just as with any other Nios^® II software project.

If your makefile refers to a source file with an absolute path, when you import with user source management, the absolute path is untouched, like any other source path. You might use an absolute path to refer to common source files in a fixed location. In this situation, you can move the project to a different directory without disturbing the common source file references.

User source management is not available with BSP projects. BSP makefiles are based on the operating system, BSP settings, selected software packages, and selected drivers. You do not specify BSP source files directly.

• Program code
• Program data
• FPGA configuration data
• File systems

Flash programmer tools allow you to program software, FPGA configuration, and application-specific binary data into flash memory devices. The tools support combining these different types of data so that they can be stored in a single flash device.

In Intel^® Quartus^® Prime Standard Edition, the Nios II SBT for Eclipse provides the Nios II flash programmer GUI-based tool and associated utilities, to help you manage and program the contents of flash memory. The sections below describe how to use these tools.

When you first open the flash programmer, no controls are available until you open or create a Flash Programmer Settings File (.flash-settings).

You specify the hardware configuration by opening a .sopcinfo file. You can locate the .sopcinfo file in either of two ways:

• Browse to a BSP settings file. The flash programmer finds the .sopcinfo file associated with the BSP.
• Browse directly to a .sopcinfo file.

Once you have identified a hardware configuration, details about the target hardware appear at the top of the Nios II flash programmer screen.

Also at the top of the Nios II flash programmer screen is the Hardware Connections button, which opens the Hardware Connections dialog box. This dialog box allows you to select a download cable, and control system ID behavior.

• The Information tab
• The Problems tab
• The Processing tab

You specify memory device information when you add the user-defined memory device to your BSP. The device information persists in the BSP settings file, allowing you to regenerate memory initialization files at any time, exactly as if the memory device were part of the hardware system.

• The physical memory width. The device’s name in the hardware system.
• The memory initialization file parameter name. Every memory device can have an HDL parameter specifying the name of the initialization file. The Nios^® II ModelSim launch configuration overrides the HDL parameter to specify the memory initialization filename. When available, this method is preferred for setting the memory initialization filename.
• The Mem init filename parameter can be used in Nios^® II systems as an alternative method of specifying the memory initialization filename. The Mem init filename parameter directly overrides any filename specified in the HDL.
• Connectivity to processor master ports. These parameters are used when creating the linker script.
• The memory type: volatile, CFI flash or EPCS flash.
• Byte lanes.
• You can also enable and disable generation of the following memory initialization file types:
  • .hex file
  • .dat and .sym files
  • .flash file

On the Advanced tab, you can control the following memory characteristics:

• The physical memory width.
• The device's name in the hardware system.
• The memory initialization file parameter name. Every memory device can have an HDL parameter specifying the name of the initialization file. The Nios^® II ModelSim launch configuration overrides the HDL parameter to specify the memory initialization filename. When available, this method is preferred for setting the memory initialization filename.
• The Mem init filename parameter can be used in Nios^® II systems as an alternative method of specifying the memory initialization filename. The Mem init filename parameter directly overrides any filename specified in the HDL.
• Connectivity to processor master ports. These parameters are used when creating the linker script.
• The memory type: volatile, CFI flash or EPCS flash.
• Byte lanes.
• You can also enable and disable generation of the following memory initialization file types:
  • .hex file
  • .dat and .sym files
  • .flash file

When you create the launch configuration, you might see the following error message:

SEVERE: The Intel^® Quartus^® Prime project location has not been set in the ELF section. You can manually override this setting in the launch configuration's ELF file 'Advanced' properties page.

• Use __buildin_custom_* instead of -mcustom-* or #pragma to reliably generate Nios^® II Floating Point Custom Instructions (FPCI), independent of compiler optimization level and command line flags.
• To use -mcustom-* or #pragma for Nios^® II Floating Point Custom Instructions (FPCI):
  • The -ffinite-math-only flag must be used to generate fmins and fmax FPCI
  • The optimization (non -O0 flag) must be used to generate fsqrts FPCI
• Users implementing transcendental functions in hardware must use the -funsafe-math-optimizations flag to generate the FPCI for the transcendental functions fsins(), fcoss(), ftans(), fatans(), fexps(), flogs() and corresponding double-precision functions.
• The Pragma format has changed from eg. #pragma custom_fadds 253 to #pragma GCC target("custom-fadds=253") and function attributes provide an alternative format __attribute__((target("custom-fadds=253"))).
• Use the -mel/-meb flags instead of -EL/-EB for endian settings. Software Build Tool for Eclipse (SBTE) users must regenerate the BSP for this setting to take effect.
• The -mreverse-bitfields flag and reverse_bitfields pragma are no longer supported.
• The -fstack-check flag must be used instead of -mstack-check to enable stack checking.

• The -Wa,-relax-all flag in nios2-elf-gcc GCC 4.7.3 supports function calls and programs exceeding the 256 MB limit.
• When used with optimization, inline assembly code with the asm operator needs to declare values imported from C and exported back to C, using the mechanisms described on the "Exteded Asm - Assembler Instructions with C Expression Operands" page.
• Pre-standard C++ headers are not supported in GCC 4.7.3. Replace pre-standard C++ with standard C++ eg. #include <iostream.h>, cout, endl with #include <iostream>, std::cout and std::endl, respectively.
• The compile flag -Wl,--defsym foo=bar where bar is an undefined symbol, generates error at the linker level in GCC 4.7.3. GCC 4.1.2 does not include this check.

• The name of the target .elf file (application project only)
• The library name (library project only)
• A list of symbols to be defined in the makefile
• A list of symbols to be undefined in the makefile
• A list of assembler flags
• Warning level flags
• A list of user flags
• Generation of debug symbols
• Compiler optimization level
• Generation of object dump file (application project only)
• Source file management
• Path to associated BSP (required for application, optional for library)

This behavior differs from the behavior of the Nios II SBT for Eclipse in version 9.1.

• Disable 'Nios II Console' view
• Ignore mismatched system ID
• Ignore mismatched system timestamp
• Download ELF to selected target system
• Start processor
• Reset the selected target system

The following tables describe the Eclipse CDT features not supported by the Nios^® II plugins. The features listed in the left column are supported by the Eclipse CDT plugins, but are not supported by Nios^® II plugins; and the right column lists alternative features supported by the Nios^® II plugins.

These command line options are:

The following shows how the application properties page looks with the new build configuration options highlighted in red:

Figure 3.  Nios^® II Application Properties

Clicking on the Managed Configurations button shows the following dialog for adding, removing, and activating build configurations:

Figure 4. Managed Configurations

• You can invoke the command line tools from custom scripts or other tools that you might already use in your development flow.
• On a command line, you can run several Tcl scripts to control the creation of a board support package (BSP).
• You can use command line tools in a bash script to build several projects at once.

The Nios^® II SBT command-line interface is designed to work in the Nios^® II Command Shell.

• Command-line utilities
• Command-line scripts
• Tcl commands
• Tcl scripts

These elements work together in the Nios^® II Command Shell to create software projects.

Usage

nios2-bsp <bsp-type> <bsp-dir> [<sopc>] [<override>]...

Options

• <bsp-type>: hal or ucosii .
• <bsp-dir>: Path to the BSP directory.
• <sopc>: The path to the .sopcinfo file or its directory.
• <override>: Options to override defaults.

Description

The nios2-bsp script calls nios2-bsp-create-settings or nios2-bsp-update-settings to create or update a BSP settings file, and the nios2-bsp-generate-files command to create the BSP files. The Nios II Embedded Design Suite (EDS) supports the following BSP types:

• hal
• ucosii

BSP type names are case-insensitive.

This utility produces a BSP of <bsp-type> in <bsp-dir>. If the BSP does not exist, it is created. If the BSP already exists, it is updated to be consistent with the associated hardware system.

The default Tcl script is used to set the following system-dependent settings:

• stdio character device
• System timer device
• Default linker memory
• Boot loader status (enabled or disabled)

If the BSP already exists, nios2-bsp overwrites these system-dependent settings.

The default Tcl script is installed at <Nios II EDS install path>/sdk2/bin/bsp-set-defaults.tcl

When creating a new BSP, this utility runs nios2-bsp-create-settings, which creates settings.bsp in <bsp-dir>.

When updating an existing BSP, this utility runs nios2-bsp-update-settings, which updates settings.bsp in <bsp-dir>.

After creating or updating the settings.bsp file, this utility runs nios2-bsp-generate-files, which generates files in <bsp-dir>

Required arguments:

• <bsp-type>: Specifies the type of BSP. This argument is ignored when updating a BSP. This argument is case-insensitive. The nios2-bsp script supports the following values of <bsp-type>:
  • hal
  • ucosii
• <bsp-dir>: Path to the BSP directory. Use "." to specify the current directory.

Optional arguments:

• <sopc>: The path name of the .sopcinfo file. Alternatively, specify a directory containing a .sopcinfo file. In the latter case, the tool finds a file with the extension .sopcinfo. This argument is ignored when updating a BSP. If you omit this argument, it defaults to the current directory.
• <override>: Options to override defaults. The nios2-bsp script passes most overrides to nios2-bsp-create-settings or nios2-bsp-update-settings. It also passes the --silent, --verbose, --debug, and --log options to nios2-bsp-generate-files.

  nios2-bsp passes the following overrides to the default Tcl script:

  • --default_stdio <device>|none|DONT_CHANGE

    Specifies stdio device.

  • --default_sys_timer <device>|none|DONT_CHANGE

    Specifies system timer device.

  • --default_memory_regions DONT_CHANGE

    Suppresses creation of new default memory regions when updating a BSP. Do not use this option when creating a new BSP.

  • --default_sections_mapping <region>|DONT_CHANGE

    Specifies the memory region for the default sections.

  • --use_bootloader 0|1|DONT_CHANGE

    Specifies whether a boot loader is required.

    On a preexisting BSP, the value DONT_CHANGE prevents associated settings from changing their current value.

If no command-line arguments are specified, this command returns an exit value of 1 and sends a help message to stderr.

The create-this-app script takes no command-line arguments. Your current directory must be the same directory as the create-this-app script. The exit value is zero on success and one on error.

The create-this-bsp script takes no command-line arguments. Your current directory must be the same directory as the create-this-bsp script. The exit value is zero on success and one on error.

• In the Windows operating system, on the Start menu, point to Programs > Intel FPGA > Nios II EDS <version>,and click Nios II <version> Command Shell :.
• In the Linux operating system, in a command shell, change directories to <Nios II EDS install path>, and type the command nios2_command_shell.sh.

• In the Windows operating system, execute the following command:

  “<Nios II EDS install path>/Nios II Command Shell.bat“ <command>

• In the Linux operating system, execute the following command:

  <Nios II EDS install path>/nios2_command_shell.sh <command>

For example, in Windows, to run an automated build, you might execute the following command:

“<Nios II EDS install path>/Nios II Command Shell.bat“ custom_build.sh

The Nios II Command Shell startup script (Nios II Command Shell.bat or nios2_command_shell.sh) makes no special assumptions about its initial environment. You can use the Nios II Command Shell with auto-execution from any environment that accepts commands native to your host operating system. For example, in Linux you can use crontab to schedule a job to run in the Nios II Command Shell at a later time.

To complete this tutorial, you must have the following:

• Intel FPGA Quartus Prime development software, version 8.0 or later. The software must be installed on a Windows or Linux computer that meets the Quartus Prime minimum requirements.
• The Intel FPGA Nios II Embedded Design Suite (EDS), version 8.0 or later.
• An Intel FPGA development board.
• A download cable such as the Intel FPGA USB-Blaster™ cable.

You run the Nios II SBT commands from the Nios II Command Shell.

In this section, assume that you want to build a software application for a Nios II system that features the LAN91C111 10/100 Non-PCI Ethernet Single Chip MAC + PHY component and supports the NicheStack^® TCP/IP stack. Furthermore, assume that you have organized the hardware design files and the software source files.

A simple method for creating a BSP is to use the nios2-bsp script as in the following example:

nios2-bsp ucosii . ../SOPC/ --cmd enable_sw_package altera_iniche \ 
 --set altera_iniche.iniche_default_if lan91c111 
nios2-bsp lwhal . ../user/data/FastNetProject/FastNetHW/ 
make 

The nios2-bsp script uses the .sopcinfo file to create the BSP files. You can override default settings chosen by nios2-bsp by supplying command-line arguments, Tcl scripts, or both.

You can specify multiple targets on a make command line. For example, the following command removes existing object files in the current project directory, builds the project, downloads the project to a board, and runs it:

make clean download-elf

You can modify an application or user library makefile with the nios2-lib-update-makefile and nios2-app-update-makefile utilities. With these utilities, you can execute the following tasks:

• Add source files to a project
• Remove source files from a project
• Add compiler options to a project’s make rules
• Modify or remove compiler options in a project’s make rules

The SBT creates the following types of projects:

• Nios^® II application—A program implementing some desired functionality, such as control or signal processing.
• Nios^® II BSP—A library providing access to hardware in the Nios^® II system, such as UARTs and other I/O devices. A BSP provides a software runtime environment customized for one processor in a hardware system. A BSP optionally also includes the operating system, and other basic system software packages such as communications protocol stacks.
• User library—A library implementing a collection of reusable functions, such as graphics algorithms.

The Nios^® II SBT for Eclipse provides access to a large, useful subset of SBT functionality. Any project you create in Eclipse can also be created using the SBT from the command line or in a script. Create your software project using the interface that is most convenient for you. Later, it is easy to perform additional project tasks in the other interface if you find it advantageous to do so.

The Nios^® II SBT creates two kinds of makefiles:

• Application or user library makefile—A simple makefile that builds the application or user library with user-provided source files
• BSP makefile—A more complex makefile, generated to conform to user-specified settings and the requirements of the target hardware system

It is not necessary to use to the generated application and user library makefiles if you prefer to write your own. However, Intel FPGA recommends that you use the SBT to manage and modify BSP makefiles.

Generated makefiles are platform-independent, calling only utilities provided with the Nios^® II EDS (such as nios2-elf-gcc).

The generated makefiles have a straightforward structure, and each makefile has in-depth comments explaining how it works. Intel FPGA recommends that you study these makefiles for further information about how they work. Generated BSP makefiles consist of a single main file and a small number of makefile fragments, all of which reside in the BSP directory. Each application and user library has one makefile, located in the application or user library directory.

For more information, refer to the Getting Started with the Graphical User Interface section.

• C/C++ application projects
• C/C++ user library projects
• BSP projects

This section discusses each type of project in detail.

• A device driver is associated with a specific hardware component.
• A device driver might have settings that impact its compilation. These settings become part of the BSP settings.

In the Nios^® II software development environment, a software package typically has the following properties:

• A software package is not associated with specific hardware.
• A software package might have settings that impact its compilation. These settings become part of the BSP settings.

Although this section describes tasks in terms of the SBT command line flow, you can also carry out most of these tasks with the Nios^® II SBT for Eclipse.

The mem_init.mk file includes targets designed to help you create memory initialization files (.dat, .hex, .sym, and .flash). The mem_init.mk file is designed to be included in your application makefile. Memory initialization files are used for HDL simulation, for Quartus Prime compilation of initializable FPGA on-chip memories, and for flash programming. Memories that can be initialized include M512 and M4K, but not MRAM.

Although the application makefile provides the mem_init.mk targets, it does not build any of them by default. The SBT creates the memory initialization files in the application directory (under a directory named mem_init). The SBT optionally copies them to your Quartus Prime project directory and HDL simulation directory.

QUARTUS_PROJECT_DIR = ../my_hw_design
MEM_INIT_FILE := $(BSP_ROOT_DIR)/mem_init.mk
include $(MEM_INIT_FILE)

Suppose you have a memory region named onchip_ram. The Tcl script named reserve_1024_onchip_ram.tcl separates the top 1024 bytes of onchip_ram to create a new region named onchip_special.

For more information about an explanation of each Tcl command used in this example, refer to the " Nios^® II Software Build Tools Reference" chapter.

# Get region information for onchip_ram memory region. 
# Returned as a list. 
set region_info [get_memory_region onchip_ram] 
# Extract fields from region information list. 
set region_name [lindex $region_info 0] 
set slave_desc [lindex $region_info 1] 
set offset [lindex $region_info 2] 
set span [lindex $region_info 3] 
# Remove the existing memory region. 
delete_memory_region $region_name 
# Compute memory ranges for replacement regions. 
set split_span 1024 
set new_span [expr $span-$split_span] 
set split_offset [expr $offset+$new_span] 
# Create two memory regions out of the original region. 
add_memory_region onchip_ram $slave_desc $offset $new_span 
add_memory_region onchip_special $slave_desc $split_offset $split_span 

If you pass this Tcl script to nios2-bsp, it runs after the default Tcl script runs and sets up a linker region named onchip_ram0. You pass the Tcl script to nios2-bsp as follows:

nios2-bsp hal my_bsp --script reserve_1024_onchip_ram.tcl

If you run nios2-bsp again to update your BSP without providing the --script option, your BSP reverts to the default linker memory regions and your onchip_special memory region disappears. To preserve it, you can either provide the --script option to your Tcl script or pass the DONT_CHANGE keyword to the default Tcl script as follows:

nios2-bsp hal my_bsp --default_memory_regions DONT_CHANGE

Intel FPGA recommends that you use the --script approach when updating your BSP. This approach allows the default Tcl script to update memory regions if memories are added, removed, renamed, or resized. Using the DONT_CHANGE keyword approach does not handle any of these cases because the default Tcl script does not update the memory regions at all.

For more information about using the --script argument, refer to the “Calling a Custom BSP Tcl Script” section.

Example 4–2. To Create a Section named .isrs in the tightly_coupled_instruction_memory on-chip memory

# Get region information for tightly_coupled_instruction_memory memory region. 
# Returned as a list. 
set region_info [get_memory_region tightly_coupled_instruction_memory] 
# Extract fields from region information list. 
set region_name [lindex $region_info 0] 
set slave [lindex $region_info 1] 
set offset [lindex $region_info 2] 
set span [lindex $region_info 3] 
# Remove the existing memory region. 
delete_memory_region $region_name 
# Compute memory ranges for replacement regions. 
set split_span 1024 
set new_span [expr $span-$split_span] 
set split_offset [expr $offset+$new_span] 
# Create two memory regions out of the original region. 
add_memory_region tightly_coupled_instruction_memory $slave $offset $new_span 
add_memory_region isrs_region $slave $split_offset $split_span 
add_section_mapping .isrs isrs_region 

The above Tcl script splits off 1 KB of RAM from the region named tightly_coupled_instruction_memory, gives it the name isrs_region, and then calls add_section_mapping to add the .isrs section to isrs_region.

Sections:
Idx Name Size VMA LMA File off Algn
.
.
.

6 .isrs 000000c0 04000c00 04000c00 000000b4 2**2
CONTENTS, ALLOC, LOAD, READONLY, CODE
.
.
.

9 .tightly_coupled_instruction_memory 00000000 04000000 04000000 00013778 2**0
CONTENTS
.
.
.
SYMBOL TABLE:
00000000 l d .entry 00000000
30000020 l d .exceptions 00000000
30000150 l d .text 00000000
30010e14 l d .rodata 00000000
30011788 l d .rwdata 00000000
30013624 l d .bss 00000000
04000c00 l d .isrs 00000000
00000020 l d .ext_flash 00000000
03200000 l d .epcs_controller 00000000
04000000 l d .tightly_coupled_instruction_memory 00000000
04004000 l d .tightly_coupled_data_memory 00000000
.
.
.

MEMORY
{
reset : ORIGIN = 0x0, LENGTH = 32
tightly_coupled_instruction_memory : ORIGIN = 0x4000000, LENGTH = 3072
isrs_region : ORIGIN = 0x4000c00, LENGTH = 1024
.
.
.
}

If you want to know the value of one or more settings, run nios2-bsp-query-settings with the appropriate command-line options. This command sends the values of the settings you requested to stdout. Just capture the output of stdout in some variable in your script when you call nios2-bsp-query-settings. By default, the output of nios2-bsp-query-settings is an ordered list of all option values. Use the -show-names option to display the name of the setting with its value.

For more information about the nios2-bsp-query-settings command-line options, refer to the Nios^® II Software Build Tools Reference section.

• To prevent a default stdio device from being chosen, use the following command:

  nios2-bsp hal my_bsp --default_stdio none

• To override the default stdio device and replace it with uart1, use the following command:

  nios2-bsp hal my_bsp --default_stdio uart1

• To override the stderr device and replace it with uart2, while allowing the default Tcl script to choose the default stdout and stdin devices, use the following command:

  nios2-bsp hal my_bsp --set hal.stderr uart2

In all these cases, if you run nios2-bsp again to update your BSP, you must provide the original command-line options again to prevent the default Tcl script from choosing its own default stdio devices. Alternatively, you can call --default_stdio with the DONT_CHANGE keyword to prevent the default Tcl script from changing the stdio device settings.

You can control the optimization and debug level through the project makefile, which determines the compiler options.

Example 4–5. Default Application Makefile Settings

APP_CFLAGS_OPTIMIZATION := -O0
APP_CFLAGS_DEBUG_LEVEL := -g 

When your project is fully debugged and ready for release, you might want to enable optimization and omit the symbol table, to achieve faster, smaller executable code. To enable optimization and turn off the symbol table, edit the application makefile to contain the symbol definitions shown in the following example. The absence of a value on the right hand side of the APP_CFLAGS_DEBUG_LEVEL definition causes the compiler to omit generating a symbol table.

Example 4–6. Application Makefile Settings with Optimization

APP_CFLAGS_OPTIMIZATION := -O3 
APP_CFLAGS_DEBUG_LEVEL := 

For more information about makefile editing and make clean, refer to the “Applications and Libraries” chapter.

nios2-bsp hal my_bsp --set hal.make.bsp_cflags_debug -g \
 --set hal.make.bsp_cflags_optimization -O0r

Alternatively, you can manipulate the BSP settings with a Tcl script.

You can easily copy an existing BSP and modify it to create a different build configuration.

For more information, refer to the “Copying, Moving, or Renaming a BSP” chapter.

To change the optimization and debug level for a user library, use the same procedure as for an application.

The BSP settings file does not need to duplicate system information (such as base addresses of devices), because the nios2-bsp-generate-files utility has access to the .sopcinfo file.

The nios2-bsp-create-settings utility creates a new BSP settings file. The nios2-bsp-update-settings utility updates an existing BSP settings file. The nios2-bsp-query-settings utility reports the setting values in an existing BSP settings file. The nios2-bsp-generate-files utility generates a BSP from the BSP settings file.

HAL BSP After Build

• The .entry section maps to a nonexistent region.
• The .entry section maps to a memory region that is less than 32 bytes in length.
• The .entry section maps to a memory region that does not start on the reset vector base address.
• The .exceptions section maps to a nonexistent region.
• The .exceptions section maps to a memory region that does not start on the exception vector base address.
• The .entry section and .exceptions section map to the same device, and the memory region associated with the .exceptions section precedes the memory region associated with the .entry section.
• The .entry section and .exceptions section map to the same device, and the base address of the memory region associated with the .exceptions section is less than 32 bytes above the base address of the memory region associated with the .entry section.

nios2-bsp --script custom_bsp.tcl

nios2-bsp-create-settings --script custom_bsp.tcl

nios2-bsp-query-settings --script custom_bsp.tcl

nios2-bsp-update-settings --script custom_bsp.tcl

In the Nios^® II BSP editor, you can execute a Tcl script when generating a BSP, through the New BSP Settings File dialog box.

For more information about using Tcl scripts in the SBT for Eclipse, refer to Using the BSP Editor in the "Getting Started with the Graphical User Interface" chapter.

For more information, refer to an example of custom Tcl script usage in the “Creating Memory Initialization Files” chapter.

For more information about BSP defaults, refer to the “Specifying BSP Defaults” chapter.

For more information, refer to the “Using Version Control” chapter.

If a component has only one slave port connected to the Nios^® II processor, the slave descriptor is the same as the name of the component (for example, onchip_mem_0). If a component has multiple slave ports connecting the Nios^® II to multiple resources in the component, the slave descriptor is the name of the component followed by an underscore and the slave port name (for example, onchip_mem_0_s1).

# Select a device connected to the processor as the default STDIO device.
# It returns the slave descriptor of the selected device.
# It gives first preference to devices with stdio in the name.
# It gives second preference to JTAG UARTs.
# If no JTAG UARTs are found, it uses the last character device.
# If no character devices are found, it returns "none".
# Procedure that does all the work of determining the stdio device
proc choose_default_stdio {} {
   set last_stdio "none"
   set first_jtag_uart "none"
# Get all slaves attached to the processor.
   set slave_descs [get_slave_descs]
   foreach slave_desc $slave_descs {
# Lookup module class name for slave descriptor.
      set module_name [get_module_name $slave_desc]
      set module_class_name [get_module_class_name $module_name]
# If the module_name contains "stdio", we choose it
# and return immediately.
      if { [regexp .*stdio.* $module_name] } {
         return $slave_desc
}
# Assume it is a JTAG UART if the module class name contains
# the string "jtag_uart". In that case, return the first one
# found.
   if { [regexp .*jtag_uart.* $module_class_name] } {
   if {$first_jtag_uart == "none"} {
      set first_jtag_uart $slave_desc
}
}
# Track last character device in case no JTAG UARTs found.
   if { [is_char_device $slave_desc] } {
      set last_stdio $slave_desc
}
}
   if {$first_jtag_uart != "none"} {
      return $first_jtag_uart
}
   return $last_stdio
}
# Call routine to determine stdio
   set default_stdio [choose_default_stdio]
# Set stdio settings to use results of above call.
   set_setting hal.stdin $default_stdio
   set_setting hal.stdout $default_stdio
   set_setting hal.stderr $default_stdio
# Select a device connected to the processor as the default STDIO device. 
# It returns the slave descriptor of the selected device. 
# It gives first preference to devices with stdio in the name. 
# It gives second preference to JTAG UARTs. 
# If no JTAG UARTs are found, it uses the last character device. 
# If no character devices are found, it returns "none". 
# Procedure that does all the work of determining the stdio device proc choose_default_stdio {} 
{  
   set last_stdio "none"  set first_jtag_uart "none"  
# Get all slaves attached to the processor.  
   set slave_descs [get_slave_descs]  foreach slave_desc $slave_descs 
{  
# Lookup module class name for slave descriptor.  
   set module_name [get_module_name $slave_desc]  
   set module_class_name [get_module_class_name $module_name]  
# If the module_name contains "stdio", we choose it  
# and return immediately.  
   if { [regexp .*stdio.* $module_name] } 
{  
      return $slave_desc  
}  
# Assume it is a JTAG UART if the module class name contains  
# the string "jtag_uart". In that case, return the first one  
# found.  
   if { [regexp .*jtag_uart.* $module_class_name] } 
{  
      if {$first_jtag_uart == "none"
} 
{  
         set first_jtag_uart $slave_desc  
}  
}  
# Track last character device in case no JTAG UARTs found.  
   if { [is_char_device $slave_desc] } 
{  
      set last_stdio $slave_desc  
}  
}  
   if {$first_jtag_uart != "none"} 
{  
      return $first_jtag_uart  
}  
   return $last_stdio 
} 
# Call routine to determine stdio set default_stdio [choose_default_stdio] 
# Set stdio settings to use results of above call. 
   set_setting hal.stdin $default_stdio set_setting hal.stdout 
   $default_stdio set_setting hal.stderr $default_stdio 

On the command line, change to the BSP directory and type make.

• Reads the .sopcinfo file for basic system parameters such as module base addresses and clock frequencies.
• Retrieves the current system identification (ID) from the .sopcinfo file. Ensures that the correct system ID is inserted in the .elf file the next time the BSP is built.
• Adjusts the default memory map to correspond to changes in memory sizes. If you are using a custom memory map, it is untouched.
• Retains all other existing settings in the BSP settings file.

• You change your hardware design, but all BSP system-dependent settings remain consistent with the new .sopcinfo file. The following are examples of system changes that do not affect BSP system-dependent settings:
  • Changing a component’s base address
  • With the internal interrupt controller (IIC), adding or removing hardware interrupts
  • With the IIC, changing a hardware interrupt number
  • Changing a clock frequency
  • Changing a simple processor option, such as cache size or core type
  • Changing a simple component option, other than memory size.
  • Adding a bridge
  • Adding a new component
  • Removing or renaming a component, other than a memory component, the stdio device, or the system timer device
  • Changing the size of a memory component when you are using the default memory map
  Note: Unless you are sure that your modified hardware design remains consistent with your BSP settings, update your BSP. For more information, refer to the “Updating Your BSP” chapter.
• You want to eliminate any customized source files and revert to the distributed BSP code.
  Note: To revert to the distributed BSP code, you must ensure that you have not disabled generation on any BSP files.
• You have installed a new version of the Nios^® II EDS, and you want the updated BSP software implementations.
• When you attempt to rebuild your project, an error message indicates that the BSP must be updated.
• You have updated or recreated the BSP settings file.

For more information about generating a BSP with the SBT for Eclipse, refer to the Getting Started with the Graphical User Interface section.

For more information about the nios2-bsp-generate-files command, refer to the Nios^® II Software Build Tools Reference section.

• System-dependent settings are derived from the original BSP settings file, but adjusted to correspond with any changes in the hardware system.
• Non-system-dependent BSP settings persist from the original BSP settings file.

For more information about actions taken when you regenerate the BSP after updating it, refer to the “Regenerating Your BSP” chapter.

• A change to your BSP settings is required.
• Changes to your .sopcinfo file make it inconsistent with your BSP. The following are examples of system changes that affect BSP system-dependent settings:
  • Renaming the processor
  • Renaming or removing a memory, the stdio device, or the system timer device
  • Changing the size of a memory component when using a custom memory map
  • Changing the processor reset or exception slave port or offset
  • Adding or removing an external interrupt controller (EIC)
  • Changing the parameters of an EIC
• When you attempt to rebuild your project, an error message indicates that you must update the BSP.

From the command line, use the nios2-bsp-update-settings command. You can use the --script option to define the BSP with a Tcl script.

For more information about the nios2-bsp-update-settings command, refer to the " Nios^® II Software Build Tools Reference" chapter.

nios2-bsp-update-settings does not reapply default settings unless you explicitly call the top-level default Tcl script with the --script option.

For more information about using the default Tcl script, refer to the “Specifying BSP Defaults” chapter.

Alternatively, you can update your BSP with the nios2-bsp script. nios2-bsp determines that your BSP already exists, and uses the nios2-bsp-update-settings command to update the BSP settings file.

The nios2-bsp script executes the default Tcl script every time it runs, overwriting previous default settings.

For more information about preserving all settings, including the default settings, use the DONT_CHANGE keyword, described in the “Top Level Tcl Script for BSP Defaults” chapter.

Alternatively, you can provide nios2-bsp with command-line options or Tcl scripts to override the default settings.

For more information about using the nios2-bsp script, refer to the " Nios^® II Software Build Tools Reference" chapter.

• System-dependent settings are created based on the current hardware system.
• Non-system-dependent settings can be selected by the default Tcl script, by values you specify, or both.

  For more information about actions taken when you generate the BSP after recreating it, refer to the “Regenerating Your BSP” chapter.

To use Tcl scripts most effectively, it is best to create a Tcl script at the time you initially create the BSP. However, the BSP Editor enables you to export a Tcl script from an existing BSP.

For more information about exporting Tcl scripts, refer to Using the BSP Editor in the "Getting Started with the Graphical User Interface" chapter.

By recreating the BSP settings file with a Tcl script that specifies all BSP settings, you can reproduce the original BSP while ensuring that system-dependent settings are adjusted correctly based on any changes in the hardware system.

For more information about Tcl scripting with the SBT, refer to the “Tcl Scripts for BSP Settings”.

For more information, refer to “Getting Started with Nios^® II Software in Eclipse” and “Using the BSP Editor” in the Getting Started with the Graphical User Interface section.

The nios2-bsp-create-settings command does not apply default settings to your BSP. However, you can use the --script command-line option to run the default Tcl script.

For more information about the default Tcl script, refer to the “Specifying BSP Defaults” chapter.

For more information about using the nios2-bsp-create-settings command, refer to the " Nios^® II Software Build Tools Reference" chapter.

The top level Tcl script for setting BSP defaults is bsp-set-defaults.tcl. This script specifies BSP system-dependent settings, which depend on the hardware system. The nios2-bsp-create-settings and nios2-bsp-update-settings utilities do not call the default Tcl script when creating or updating a BSP settings file. The --script option must be used to specify bsp-set-defaults.tcl explicitly. Both the Nios^® II SBT for Eclipse and the nios2-bsp script call the default Tcl script by invoking either nios2-bsp-create-settings or nios2-bsp-update-settings with the --script bsp-set-defaults.tcl option.

The default Tcl script consists of a top-level Tcl script named bsp-set-defaults.tcl plus the helper Tcl scripts listed in the "Default Tcl Script Components" table (Table 4–9). The helper Tcl scripts do the real work of examining the .sopcinfo file and choosing appropriate defaults.

The bsp-set-defaults.tcl script sets the following defaults:

• stdio character device (bsp-stdio-utils.tcl)
• System timer device (bsp-timer-utils.tcl)
• Default linker memory regions (bsp-linker-utils.tcl)
• Default linker sections mapping (bsp-linker-utils.tcl)
• Default boot loader settings (bsp-bootloader-utils.tcl)

You run the default Tcl script on the nios2-bsp-create-settings, nios2-bsp-query-settings, or nios2-bsp-update-settings command line, by using the --script argument. It has the following usage:

bsp-set-defaults.tcl [<argument name> <argument value>]*

All arguments are optional. If present, each argument must be in the form of a name and argument value, separated by white space. All argument values are strings. For any argument not specified, the corresponding helper script chooses a suitable default value. In every case, if the argument value is DONT_CHANGE, the default Tcl scripts leave the setting unchanged. The DONT_CHANGE value allows fine-grained control of what settings the default Tcl script changes and is useful when updating an existing BSP.

For more information about these settings, refer to the Nios^® II Software Build Tools Reference section.

The script searches the .sopcinfo file for a slave descriptor with the string stdio in its name. If bsp-stdio-utils.tcl finds any such slave descriptors, it chooses the first as the default stdio device. If the script finds no such slave descriptor, it looks for a slave descriptor with the string jtag_uart in its component class name. If it finds any such slave descriptors, it chooses the first as the default stdio device. If the script finds no slave descriptors fitting either description, it chooses the last character device slave descriptor connected to the Nios^® II processor. If bsp-stdio-utils.tcl does not find any character devices, there is no stdio device.

For more information about this setting, refer to the Nios^® II Software Build Tools Reference section.

The script searches the .sopcinfo file for a timer component to use as the default system timer. To be an appropriate system timer, the component must have the following characteristics:

• It must be a timer, that is, is_timer_device must return true.
• It must have a slave port connected to the Nios^® II processor.

When the script finds an appropriate system timer component, it sets hal.sys_clk_timer to the timer slave port descriptor. The script prefers a slave port whose descriptor contains the string sys_clk, if one exists. If no appropriate system timer component is found, the script sets hal.sys_clk_timer to none.

For more information about these commands, refer to the Nios^® II Software Build Tools Reference section.

The script chooses the largest volatile memory region as the default memory region. If there is no volatile memory region, bsp-linker-utils.tcl chooses the largest non-volatile memory region. The script assigns the .text, .rodata, .rwdata, .bss, .heap, and .stack section mappings to this default memory region. The script also sets the hal.linker.exception_stack_memory_region BSP setting to the default memory region. The setting is available in case the separate exception stack option is enabled (this setting is disabled by default).

For more information about this setting, refer to the Nios^® II Software Build Tools Reference section.

• hal.linker.allow_code_at_reset
• hal.linker.enable_alt_load_copy_rodata
• hal.linker.enable_alt_load_copy_rwdata
• hal.linker.enable_alt_load_copy_exceptions

For more information about these settings, refer to the Nios^® II Software Build Tools Reference section.

The script examines the .text section mapping and the Nios^® II reset slave port. If the .text section is mapped to the same memory as the Nios^® II reset slave port and the reset slave port is a flash memory device, the script assumes that a boot loader is being used. You can override this behavior by passing the enable_bootloader option to the default Tcl script.

If a boot loader is enabled, the assumption is that the boot loader is located at the reset address and handles the copying of sections on reset. If there is no boot loader, the BSP might need to provide code to handle these functions. You can use the alt_load() function to implement a boot loader.