Nios II Classic Software Developer’s Handbook Subscribe Send Feedback NII5V2 2015.05.14 101 Innovation Drive San Jose, CA 95134 www.altera.
TOC-2 Contents Overview of Nios II Embedded Development.................................................... 1-1 Prerequisites for Understanding the Nios II Embedded Design Suite.................................................1-1 Finding Nios II EDS Files........................................................................................................................... 1-1 Nios II Software Development Environment........................................................................................
TOC-3 The Project Tab.............................................................................................................................. 2-21 The Target Connection Tab......................................................................................................... 2-21 The Debugger Tab......................................................................................................................... 2-21 Nios II Hardware v2 (beta).....................................................
TOC-4 Advantages of Command-Line Software Development.........................................................................3-1 Outline of the Nios II SBT Command-Line Interface............................................................................ 3-1 Utilities.............................................................................................................................................. 3-1 Scripts........................................................................................
TOC-5 Specifying the Default stdio Device.............................................................................................4-36 Specifying the Default System Timer.......................................................................................... 4-37 Specifying the Default Memory Map.......................................................................................... 4-37 Specifying Default Bootloader Parameters........................................................................
TOC-6 Altera Logging Functions................................................................................................................6-7 Using File Subsystems............................................................................................................................... 6-13 Host-Based File System................................................................................................................. 6-13 Using Timer Devices...................................................
TOC-7 The Relationship Between the .sopcinfo File and system.h....................................................... 7-3 Using the System Generation Tool to Optimize Hardware.......................................................7-3 Components, Devices, and Peripherals........................................................................................ 7-3 Accessing Hardware..................................................................................................................................
TOC-8 General Exception Funnel............................................................................................................ 8-26 Hardware Interrupt Funnel..........................................................................................................8-26 Software Exception Funnel...........................................................................................................8-28 Invalid Instructions..........................................................................
TOC-9 The NicheStack TCP/IP Stack Files and Directories................................................................ 11-2 Licensing......................................................................................................................................... 11-3 Other TCP/IP Stack Providers for the Nios II Processor.....................................................................11-3 Using the NicheStack TCP/IP Stack - Nios II Edition.......................................................
TOC-10 alt_alarm_start().......................................................................................................................... 14-10 alt_alarm_stop()...........................................................................................................................14-11 alt_dma_rxchan_depth()............................................................................................................ 14-12 alt_dma_rxchan_close()......................................................
TOC-11 fork()..............................................................................................................................................14-56 fcntl()............................................................................................................................................. 14-57 execve()..........................................................................................................................................14-58 getpid()...................................
TOC-12 nios2-bsp-console........................................................................................................................ 15-21 alt-file-convert..............................................................................................................................15-22 Nios II Design Example Scripts............................................................................................................. 15-23 create-this-bsp...................................................
1 Overview of Nios II Embedded Development 2015.05.14 NII5V2 Subscribe Send Feedback The Nios II Software Developer's Handbook has been divided into two documents - Nios II Classic Software Developer's Handbook and Nios II Gen2 Software Developer's Handbook. • The Nios II Classic Software Developer's Handbook is familiar to past users. There are no future updates planned for this version.
1-2 NII5V2 2015.05.14 Nios II Software Development Environment Nios II Software Development Environment The Nios II EDS provides a consistent software development environment that works for all Nios II processor systems. With the Nios II EDS running on a host computer, an Altera FPGA, and a JTAG download cable (such as an Altera USB-Blaster™ download cable), you can write programs for and communicate with any Nios II processor system.
NII5V2 2015.05.14 Nios II SBT Command Line 1-3 The Nios II SBT for Eclipse is based on the popular Eclipse framework and the Eclipse C/C++ develop‐ ment toolkit (CDT) plugins. The Nios II SBT creates your project makefiles for you, and Eclipse provides extensive capabilities for interactive debugging and management of source files. The SBT for Eclipse also allows you to import and debug projects you created in the Nios II Command Shell.
1-4 NII5V2 2015.05.14 Nios II Software Project Types Nios II Software Project Types Application Project A Nios II C/C++ application project consists of a collection of source code, plus a makefile. A typical characteristic of an application is that one of the source files contains function main(). An application includes code that calls functions in libraries and BSPs. The makefile compiles the source code and links it with a BSP and one or more optional libraries, to create one .elf file.
NII5V2 2015.05.14 Nios II Embedded Design Examples Name Host file system 1-5 Description Refer to the "Developing Programs Using the Hardware Abstraction Layer" chapter. Related Information Ethernet and the NicheStack TCP/IP Stack - Nios II Edition on page 11-1 Read-Only Zip File System Developing Programs Using the Hardware Abstraction Layer on page 6-1 https://www.altera.com/products/design-software/embedded-software-developers/nios-iieds.
1-6 NII5V2 2015.05.14 Third-Party Embedded Tools Support Each BSP example directory contains a create-this-bsp script. After this script is run, each software example directory contains the following files: • • • • Source file (.c) Header file (.h) readme.txt template.xml Figure 1-1: Software Design Example Directory Structure Related Information Getting Started from the Command Line on page 3-1 For more information about using these scripts to create software projects.
NII5V2 2015.05.14 Document Revision History for Overview of Nios II Embedded Development 1-7 The Nios II Processor Reference Handbook 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.
1-8 NII5V2 2015.05.14 Document Revision History for Overview of Nios II Embedded Development Date Version February 2011 10.1.0 Removed "Referenced Documents" section. July 2010 10.0.0 Installation method changed; Nios II EDS always installed in a directory adjacent to Quartus II tools. November 2009 9.1.0 • Described the Nios II Software Build Tools for Eclipse. • Nios II IDE information moved to Appendix A.
2 Getting Started with the Graphical User Interface 2015.05.14 NII5V2 Subscribe Send Feedback The Nios II Software Build Tools (SBT) for Eclipse is a set of plugins based on the Eclipse framework and the Eclipse C/C++ development toolkit (CDT) plugins. The Nios II SBT for Eclipse provides a consistent development platform that works for all Nios II embedded processor systems.
2-2 NII5V2 2015.05.14 The Altera Bytestream Console Any number of editors can be open at once, but only one can be active at a time. The main menu bar and toolbar for the workbench window contain operations that are applicable to the active editor. Tabs in the editor area indicate the names of resources that are currently open for editing. An asterisk (*) indicates that an editor has unsaved changes.
NII5V2 2015.05.14 Specifying the Project Template 2-3 Related Information Specifying the BSP on page 2-3 For more information about how the SBT also creates a folder to contain BSP project files. Specifying the Project Template Project templates are ready-made, working software projects that serve as examples to show you how to structure your own Nios II projects. It is often easier to start with a working project than to start a blank project from scratch.
2-4 NII5V2 2015.05.14 Creating the Projects BSP in the list. The Create and Import buttons to the right of the existing BSP list provide convenient ways to add BSPs to the list. Creating the Projects When you have specified your BSP, you click Finish to create the projects. 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.
NII5V2 2015.05.14 Running the Project on Nios II Hardware 2-5 The project directory for your hardware design contains an SRAM Object File (.sof) along with the .sopcinfo file. The .sof file contains the hardware design to be programmed in the FPGA. Related Information Quartus II Programmer For more information about programming an FPGA with Quartus II Programmer.
2-6 NII5V2 2015.05.14 List of Debugging Tasks with the Nios II SBT for Eclipse 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.
NII5V2 2015.05.14 Console View 2-7 Console View Just as when running a program, Eclipse displays program output in the Console view of Eclipse. The 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 Console view displays the text.
2-8 NII5V2 2015.05.14 Nios II Exception Debugging 1. Enable the Run Time Stack Checking in the BSP project from NIOS II SBT for Eclipce Nios II BSP Editor. From the BSP project, right-click and navigate to Nios II > BSP editor Settings > Advanced > hal > enable_run_time_stack_checking. 2. Rebuild BSP and software. 3. Ensure that the FPGA is configured. 4. Start the Debug Session by navigating to Debug As > Nios II Hardware. 5. Run the Software.
NII5V2 2015.05.14 Recognizing and Debugging a Stack Overflow 2-9 The bgeu and break 3 lines are what is added for the stack overflow checking. If the stack pointer has grown beyond its limits the break is called. Related Information Embedded Design Handbook For more information, refer to the "Stack Overflow" chapter of the Embedded Design Handbook.
2-10 NII5V2 2015.05.14 Custom Instruction-Related Exception Handler Figure 2-1: Nios II Debug window Custom Instruction-Related Exception Handler For use outside the debugger, you can register your own instruction-related exception handler which is called when the break (or any exception) is seen. On an exception, including overflow, the HAL calls the instruction-related exception handler, passing in the cause field from the exception register, and the address which caused the exception.
NII5V2 2015.05.14 Creating a Simple BSP 2-11 • Determining the Cause of Interrupt and Instruction-Related Exceptions For more information, refer to the "Determining the Cause of Interrupt and Instruction-Related Exceptions" chapter of the Nios II Classic Processor Reference Handbook. • link/iga1409256728501/iga1409336670098 • Programming Model For more information, refer to the "Programming Model" chapter of the Nios II Classic Processor Reference Handbook.
2-12 NII5V2 2015.05.14 Eclipse Source Management Details of how each makefile is created and maintained vary depending on the project type, and on project options that you control. The authoritative specification of project contents is always the makefile, regardless how it is created or updated. By default, the Nios II SBT manages the list of source files in your makefile, based on actions you take in Eclipse.
NII5V2 2015.05.14 Absolute Source Paths and Linked Resources 2-13 modified icon. To add the resource back into the build, right-click the resource and click Add to Nios II Build. Note: Do not use the Eclipse Exclude from build command. With Nios II software projects, you must use the Remove from Nios II Build and Add to Nios II Build commands instead. Absolute Source Paths and Linked Resources By default, the source files for an Eclipse project are stored under the project directory.
2-14 NII5V2 2015.05.
NII5V2 2015.05.14 The Nios II BSP Editor Screen Layout 2-15 The Nios II BSP Editor Screen Layout The Nios II BSP Editor screen is divided into two areas. The top area is the command area, and the bottom is the console area. The details of the Nios II BSP Editor screen areas are described in this section. 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.
2-16 NII5V2 2015.05.14 The Software Packages Tab The Software Packages Tab The Software Packages tab allows you to insert and remove software packages in your BSP, and control software package settings. 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.
NII5V2 2015.05.14 The Linker Script Tab 2-17 • The Main Tab on page 2-15 • Embedded Peripherals IP User Guide For more information about Altera components. The Linker Script Tab The Linker Script tab allows you to view available memory in your hardware system, and examine and modify the arrangement and usage of linker regions in memory. When you make a change to the memory configuration, the SBT validates your change.
2-18 NII5V2 2015.05.14 Enable File Generation Tab • 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.
NII5V2 2015.05.14 The Information Tab 2-19 • The Information tab • The Problems tab • The Processing tab The Information Tab The Information tab shows a running list of high-level changes you make to your BSP, such as adding a software package or changing a setting value. The Problems Tab The Problems tab shows warnings and errors that impact or prohibit BSP creation. For example, if you inadvertently specify an invalid linker section mapping, a message appears in the Problems tab.
2-20 NII5V2 2015.05.14 Using a Tcl Script in BSP Creation Note: You can select the operating system only at the time you create the BSP. To change operating systems, you must create a new BSP. • The operating system version. • The name of the BSP settings file. It is created with file extension .bsp. • Absolute or relative path names in the BSP settings file. By default, relative paths are enabled for filenames in the BSP settings file.
NII5V2 2015.05.14 Run Configurations in the SBT for Eclipse 2-21 Run Configurations in the SBT for Eclipse Eclipse uses run configurations to control how it runs and debugs programs. Run configurations in the Nios II SBT for Eclipse have several features that help you debug Nios II software running on FPGA platforms. Opening the Run Configuration Dialog Box You can open the run configuration dialog box two ways: • You can right-click an application, point to Run As, and click Run Configurations.
2-22 NII5V2 2015.05.14 Nios II Hardware v2 (beta) Nios II Hardware v2 (beta) Run configurations and debug configurations have a launch type called Nios II Hardware v2 (beta). To create this launch type, in the Run menu select either Run Configurations or Debug Configurations. In the Run/Debug Configurations dialog box, select Nios II Hardware v2 (beta) and click the New button to create a new launch configuration.
NII5V2 2015.05.14 Nios II Command-Line Projects 2-23 Your command-line C/C++ application, and its associated BSP, is created on the command line. Any Nios II SBT command-line project is ready to import into the Nios II SBT for Eclipse. No additional preparation is necessary.
2-24 NII5V2 2015.05.14 Importing a Project with Absolute Source Paths 1. Start the Nios II SBT for Eclipse. 2. On the File menu, click Import. The Import dialog box appears. 3. Expand the Nios II Software Build Tools Project folder, and select Import Nios II Software Build Tools Project. 4. Click Next. The File Import wizard appears. 5. Click Browse and locate the directory containing the C/C++ application project to import. 6. Click OK. The wizard fills in the project path. 7.
NII5V2 2015.05.14 User-Managed Source Files 2-25 User-Managed Source Files When you import a Nios II application or user library project, the Nios II SBT for Eclipse offers the option of user source management. User source management is helpful if you prefer to update your makefile manually to reflect source files added to or removed from the project. With user source management, Eclipse never makes any changes to the list of source files in your makefile.
2-26 NII5V2 2015.05.14 Creating a Software Package 5. Next to Library name, click Add and type the library project name you selected when you created your user library. 6. Click OK. 7. Build your application. As this example shows, the .c source files are not required to build the application project. To hand off the library to another engineer or organization for reuse, you provide the following files: • Nios II library archive file (.a) • Software header files (.
NII5V2 2015.05.14 Creating a Software Package 2-27 # # example_sw_package_sw.tcl # # Create a software package known as "example_sw_package" create_sw_package example_sw_package # The version of this software set_sw_property version 14.1 # Location in generated BSP that sources should be copied into set_sw_property bsp_subdirectory Example_SW_Package # # Source file listings... # # C/C++ source files #add_sw_property c_source EXAMPLE_SW_PACKAGE/src/my_source.
2-28 NII5V2 2015.05.14 Programming Flash in Altera Embedded Systems * This example prints 'Hello from Nios II' to the STDOUT stream. It also * tests inclusion of a user software package. */ #include #include "example_sw_package.h" int main() { printf("Hello from Nios II!\n"); example_sw_package(); return 0; } Delete hello_world.c from the hello_example_sw_package application project. 8. 9. In the File menu, point to New and click Nios II Library 10.
NII5V2 2015.05.14 Creating a Flash Programmer Settings File 2-29 When you first open the flash programmer, no controls are available until you open or create a Flash Programmer Settings File (.flash-settings). Creating a Flash Programmer Settings File The .flash-settings file describes how you set up the flash programmer GUI to program flash. This information includes the files to be programmed to flash, a .sopcinfo file describing the hardware configuration, and the file programming locations.
2-30 NII5V2 2015.05.14 The Console Area The Properties button opens the Properties dialog box, which allows you to view and modify informa‐ tion about an individual file. In the case of a .elf, the Properties button provides access to the project reset address, the flash base and end addresses, and the boot loader file (if any). The flash programmer determines whether a boot loader is required based on the load and run locations of the .text section.
NII5V2 2015.05.14 Program Files 2-31 Program Files If you disable this option, the flash programmer generates the programming files and the script, but does not program flash. You can use the files later to program flash by turning off the Generate Files option. Erase Flash Before Programming When enabled, this option erases flash memory before programming. Run From Reset After Programming When enabled, this option resets and starts the Nios II processor after programming flash.
2-32 NII5V2 2015.05.14 Memory Initialization Files for User-Defined Memories 1. 2. 3. 4. Right-click the application project. Point to Make targets and click Build to open the Make Targets dialog box. Select mem_init_install. Click Build. The makefile generates a separate file (or files) for each memory device. The makefile inserts the memory initialization files directly in the Quartus II project directory for you. 5. Recompile your Quartus II project.
NII5V2 2015.05.14 Running a Nios II System with ModelSim 2-33 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.
2-34 NII5V2 2015.05.14 Preparing your Software for ModelSim Related Information Creating a System with Qsys For more information, refer to the "Qsys Design Flow". Preparing your Software for ModelSim Creating the software projects is nearly the same as when you run the project on hardware. To prepare your software for ModelSim simulation, perform the following steps: 1. Create your software project.
NII5V2 2015.05.14 Nios II Specific Changes 2-35 Related Information • Porting to GCC 4.7 For more information about how GNU also provides a porting guide to GCC4.7 to document common issues. • GCC Releases For more information about full GCC release notes. Nios II Specific Changes • 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.
2-36 NII5V2 2015.05.14 Eclipse Usage Notes Eclipse Usage Notes The behavior of certain Eclipse and CDT features is modified by the Nios II SBT for Eclipse. If you attempt to use these features the same way you would with a non-Nios II project, you might have problems configuring or building your project. This section discusses such features.
NII5V2 2015.05.14 Selecting the Correct Launch Configuration Type 2-37 Selecting the Correct Launch Configuration Type If you try to debug a Nios II software project as a CDT Local C/C++ Application launch configuration type, you see an error message, and the Nios II Debug perspective fails to open. This is expected CDT behavior in the Eclipse platform. Local C/C++ Application is the launch configuration type for a standard CDT project.
2-38 NII5V2 2015.05.14 Must Use Nios II Build Configuration Table 2-3: Location and Argument to Run Shell Script from Eclipse Platform Windows Linux Location Argument ${env_var:QUARTUS_ROOTDIR}\bin\cygwin\ bin\sh.exe ${env_var:SOPC_KIT_NIOS2}/bin/
