Nios II Classic Software Developer’s Handbook

Download PDF
ID 683282
Date 5/14/2015
Public
Document Table of Contents
Document Table of Contents x
1. Overview of Nios II Embedded Development 2. Getting Started with the Graphical User Interface 3. Getting Started from the Command Line 4. Nios II Software Build Tools 5. Overview of the Hardware Abstraction Layer 6. Developing Programs Using the Hardware Abstraction Layer 7. Developing Device Drivers for the Hardware Abstraction Layer 8. Exception Handling 9. Cache and Tightly-Coupled Memory 10. MicroC/OS-II Real-Time Operating System 11. Ethernet and the NicheStack TCP/IP Stack 12. Read-Only Zip File System 13. Publishing Component Information to Embedded Software 14. HAL API Reference 15. Nios II Software Build Tools Reference
1. Overview of Nios II Embedded Development x
1.1. Prerequisites for Understanding the Nios II Embedded Design Suite 1.2. Finding Nios II EDS Files 1.3. Nios II Software Development Environment 1.4. Nios II EDS Development Flows 1.5. Nios II Programs 1.6. Intel FPGA Software Packages for Embedded Systems 1.7. Nios II Embedded Design Examples 1.8. Third-Party Embedded Tools Support 1.9. Additional Nios II Information 1.10. Overview of Nios II Embedded Development Revision History
1.4. Nios II EDS Development Flows x
1.4.1. Nios II SBT Development Flow
1.4.1. Nios II SBT Development Flow x
1.4.1.1. Nios II SBT for Eclipse 1.4.1.2. Nios II SBT Command Line
1.5. Nios II Programs x
1.5.1. Makefiles and the SBT 1.5.2. Nios II Software Project Types
1.5.2. Nios II Software Project Types x
1.5.2.1. Application Project 1.5.2.2. User Library Project 1.5.2.3. BSP Project
1.7. Nios II Embedded Design Examples x
1.7.1. Hardware Examples 1.7.2. Software Examples
2. Getting Started with the Graphical User Interface x
2.1. Getting Started with Nios II Software in Eclipse 2.2. Makefiles and the Nios II SBT for Eclipse 2.3. Using the BSP Editor 2.4. Run Configurations in the SBT for Eclipse 2.5. Nios II Hardware v2 (beta) 2.6. Optimizing Project Build Time 2.7. Importing a Command-Line Project 2.8. Packaging a Library for Reuse 2.9. Creating a Software Package 2.10. Programming Flash in Intel FPGA Embedded Systems 2.11. Creating Memory Initialization Files 2.12. Running a Nios II System with ModelSim 2.13. Eclipse Usage Notes 2.14. Getting Started with the Graphical User Interface Revision History
2.1. Getting Started with Nios II Software in Eclipse x
2.1.1. The Nios II SBT for Eclipse Workbench 2.1.2. Creating a Project 2.1.3. Navigating the Project 2.1.4. Building the Project 2.1.5. Configuring the FPGA 2.1.6. Running the Project on Nios II Hardware 2.1.7. Debugging the Project on Nios II Hardware 2.1.8. Creating a Simple BSP
2.1.1. The Nios II SBT for Eclipse Workbench x
2.1.1.1. Perspectives, Editors, and Views 2.1.1.2. The Intel FPGA Bytestream Console
2.1.2. Creating a Project x
2.1.2.1. Specifying the Application 2.1.2.2. Specifying the BSP 2.1.2.3. Creating the Projects
2.1.2.1. Specifying the Application x
2.1.2.1.1. Specifying the Hardware Platform 2.1.2.1.2. Specifying the Project Name 2.1.2.1.3. Specifying the Project Template 2.1.2.1.4. Specifying the Project Location 2.1.2.1.5. Specifying the Processor
2.1.2.2. Specifying the BSP x
2.1.2.2.1. Specifying the BSP Project Name 2.1.2.2.2. Specifying the BSP Project Location 2.1.2.2.3. Selecting an Existing BSP
2.1.7. Debugging the Project on Nios II Hardware x
2.1.7.1. List of Debugging Tasks with the Nios II SBT for Eclipse 2.1.7.2. Using the Intel FPGA Bytestream Console 2.1.7.3. Run Time Stack Checking And Exception Debugging
2.1.7.1. List of Debugging Tasks with the Nios II SBT for Eclipse x
2.1.7.1.1. Console View 2.1.7.1.2. Disconnecting the Terminal from the Target
2.1.7.3. Run Time Stack Checking And Exception Debugging x
2.1.7.3.1. Nios II Exception Debugging 2.1.7.3.2. Stack Overflow
2.2. Makefiles and the Nios II SBT for Eclipse x
2.2.1. Eclipse Source Management 2.2.2. User Source Management 2.2.3. BSP Source Management
2.2.1. Eclipse Source Management x
2.2.1.1. Modifying a Makefile with Eclipse Source Management 2.2.1.2. Absolute Source Paths and Linked Resources
2.2.2. User Source Management x
2.2.2.1. Modifying a Makefile with User Source Management
2.3. Using the BSP Editor x
2.3.1. Tcl Scripting and the Nios II BSP Editor 2.3.2. Starting the Nios II BSP Editor 2.3.3. The Nios II BSP Editor Screen Layout 2.3.4. The Command Area 2.3.5. The Console Area 2.3.6. Exporting a Tcl Script 2.3.7. Creating a New BSP 2.3.8. BSP Validation Errors
2.3.4. The Command Area x
2.3.4.1. The Main Tab 2.3.4.2. The Software Packages Tab 2.3.4.3. The Drivers Tab 2.3.4.4. The Linker Script Tab 2.3.4.5. Enable File Generation Tab 2.3.4.6. Target BSP Directory Tab
2.3.4.4. The Linker Script Tab x
2.3.4.4.1. Linker Section Mappings 2.3.4.4.2. Linker Regions
2.3.5. The Console Area x
2.3.5.1. The Information Tab 2.3.5.2. The Problems Tab 2.3.5.3. The Processing Tab
2.3.7. Creating a New BSP x
2.3.7.1. Using a Tcl Script in BSP Creation
2.4. Run Configurations in the SBT for Eclipse x
2.4.1. Opening the Run Configuration Dialog Box 2.4.2. The Project Tab 2.4.3. The Target Connection Tab 2.4.4. The Debugger Tab
2.5. Nios II Hardware v2 (beta) x
2.5.1. Main Tab 2.5.2. Debugger Tab 2.5.3. Multi-Core Launches
2.7. Importing a Command-Line Project x
2.7.1. Nios II Command-Line Projects 2.7.2. Importing through the Import Wizard 2.7.3. Road Map 2.7.4. Import a Command-Line C/C++ Application 2.7.5. Import a Supporting Project 2.7.6. User-Managed Source Files
2.7.4. Import a Command-Line C/C++ Application x
2.7.4.1. Importing a Project with Absolute Source Paths
2.8. Packaging a Library for Reuse x
2.8.1. Creating the User Library 2.8.2. Using the Library
2.10. Programming Flash in Intel FPGA Embedded Systems x
2.10.1. Starting the Flash Programmer 2.10.2. Creating a Flash Programmer Settings File 2.10.3. The Flash Programmer Screen Layout 2.10.4. The Command Area 2.10.5. The Console Area 2.10.6. Saving a Flash Programmer Settings File 2.10.7. Flash Programmer Options
2.10.2. Creating a Flash Programmer Settings File x
2.10.2.1. Specifying the Hardware Configuration
2.10.5. The Console Area x
2.10.5.1. The Information Tab 2.10.5.2. The Problems Tab 2.10.5.3. The Processing Tab
2.10.7. Flash Programmer Options x
2.10.7.1. Staging Directories 2.10.7.2. Generate Files 2.10.7.3. Program Files 2.10.7.4. Erase Flash Before Programming 2.10.7.5. Run From Reset After Programming
2.11. Creating Memory Initialization Files x
2.11.1. Generate Memory Initialization Files 2.11.2. Generate Memory Initialization Files by the Legacy Method 2.11.3. Memory Initialization Files for User-Defined Memories
2.11.3. Memory Initialization Files for User-Defined Memories x
2.11.3.1. Specifying the Memory Device Information in the Advanced Tab
2.12. Running a Nios II System with ModelSim x
2.12.1. Using ModelSim with an SOPC Builder-Generated System 2.12.2. Using ModelSim with a Qsys-Generated System
2.12.2. Using ModelSim with a Qsys-Generated System x
2.12.2.1. Preparing your Software for ModelSim 2.12.2.2. Potential Error Message 2.12.2.3. Nios II GCC Tool Chain
2.12.2.3. Nios II GCC Tool Chain x
2.12.2.3.1. Nios II Specific Changes 2.12.2.3.2. GCC Changes and Enhancements
2.13. Eclipse Usage Notes x
2.13.1. Configuring Application and Library Properties 2.13.2. Configuring BSP Properties 2.13.3. Exclude from Build Not Supported 2.13.4. Selecting the Correct Launch Configuration Type 2.13.5. Target Connection Options 2.13.6. Renaming Nios II Projects 2.13.7. Running Shell Scripts from the SBT for Eclipse 2.13.8. Must Use Nios II Build Configuration 2.13.9. CDT Limitations 2.13.10. Enhancements for Build Configurations in SBT and SBT for Eclipse
2.13.1. Configuring Application and Library Properties x
2.13.1.1. Comparing the Nios II Application Properties and Nios II Library Properties tabs
2.13.10. Enhancements for Build Configurations in SBT and SBT for Eclipse x
2.13.10.1. Build Configurations in SBT 2.13.10.2. Build Configurations in SBT for Eclipse
3. Getting Started from the Command Line x
3.1. Advantages of Command-Line Software Development 3.2. Outline of the Nios II SBT Command-Line Interface 3.3. Getting Started in the SBT Command Line 3.4. Software Build Tools Scripting Basics 3.5. Running make 3.6. Getting Started from the Command Line Revision History
3.2. Outline of the Nios II SBT Command-Line Interface x
3.2.1. Utilities 3.2.2. Scripts 3.2.3. Tcl Commands 3.2.4. Tcl Scripts 3.2.5. The Nios II Command Shell
3.2.2. Scripts x
3.2.2.1. nios2-bsp 3.2.2.2. create-this-app 3.2.2.3. create-this-bsp
3.2.5. The Nios II Command Shell x
3.2.5.1. Starting the Nios II Command Shell 3.2.5.2. Auto-Executing a Command in the Nios II Command Shell
3.3. Getting Started in the SBT Command Line x
3.3.1. Prerequisites 3.3.2. Creating Hello_World for an Intel FPGA Development Board 3.3.3. Running Hello_World on an Intel FPGA Development Board 3.3.4. Debugging hello_world
3.3.4. Debugging hello_world x
3.3.4.1. Import the hello_world Application 3.3.4.2. Download Executable Code and Start the Debugger
3.4. Software Build Tools Scripting Basics x
3.4.1. Creating a BSP with a Script 3.4.2. Creating an Application Project with a Script
3.5. Running make x
3.5.1. Creating Memory Initialization Files
4. Nios II Software Build Tools x
4.1. Road Map for the SBT 4.2. Makefiles 4.3. Nios II Embedded Software Projects 4.4. Common BSP Tasks 4.5. Details of BSP Creation 4.6. Tcl Scripts for BSP Settings 4.7. Revising Your BSP 4.8. Specifying BSP Defaults 4.9. Device Drivers and Software Packages 4.10. Boot Configurations for Altera Embedded Software 4.11. Intel FPGA-Provided Embedded Development Tools 4.12. Restrictions 4.13. Nios II Software Build Tools Revision History
4.1. Road Map for the SBT x
4.1.1. What the Build Tools Create 4.1.2. Comparing the Command Line with Eclipse
4.2. Makefiles x
4.2.1. Modifying Makefiles 4.2.2. Makefile Targets
4.3. Nios II Embedded Software Projects x
4.3.1. Applications and Libraries 4.3.2. Board Support Packages 4.3.3. Software Build Process
4.3.1. Applications and Libraries x
4.3.1.1. Supported Source File Types
4.3.2. Board Support Packages x
4.3.2.1. Overview of BSP Creation 4.3.2.2. Parts of a Nios II BSP
4.3.2.2. Parts of a Nios II BSP x
4.3.2.2.1. Hardware Abstraction Layer 4.3.2.2.2. newlib C Standard Library 4.3.2.2.3. Device Drivers 4.3.2.2.4. Optional Software Packages 4.3.2.2.5. Optional Real-Time Operating System
4.4. Common BSP Tasks x
4.4.1. Adding the Nios II SBT to Your Tool Flow 4.4.2. Linking and Locating 4.4.3. Other BSP Tasks
4.4.1. Adding the Nios II SBT to Your Tool Flow x
4.4.1.1. Using Version Control 4.4.1.2. Copying, Moving, or Renaming a BSP 4.4.1.3. Handing Off a BSP
4.4.1.1. Using Version Control x
4.4.1.1.1. Creating BSP by Running a User Defined Script to Call nios2-bsp 4.4.1.1.2. Creating BSP by Manually Running nios2-bsp 4.4.1.1.3. Creating BSP before Running Make 4.4.1.1.4. Creating a Script that Uses the Command-Line Tools
4.4.2. Linking and Locating x
4.4.2.1. Creating Memory Initialization Files 4.4.2.2. Modifying Linker Memory Regions 4.4.2.3. Creating a Custom Linker Section 4.4.2.4. Changing the Default Linker Memory Region 4.4.2.5. Changing a Linker Section Mapping
4.4.2.3. Creating a Custom Linker Section x
4.4.2.3.1. Creating a Linker Section for an Existing Region 4.4.2.3.2. Dividing a Linker Region to Create a New Region and Section 4.4.2.3.3. Excerpts from Object Dump Files 4.4.2.3.4. Excerpt from Linker.x
4.4.3. Other BSP Tasks x
4.4.3.1. Creating a BSP for an Intel FPGA Development Board 4.4.3.2. Querying Settings 4.4.3.3. Managing Device Drivers 4.4.3.4. Creating a Custom Version of newlib 4.4.3.5. Controlling the stdio Device 4.4.3.6. Configuring Optimization and Debugger Options
4.4.3.6. Configuring Optimization and Debugger Options x
4.4.3.6.1. Configuring a BSP for Debugging
4.5. Details of BSP Creation x
4.5.1. BSP Settings File Creation 4.5.2. Generated and Copied Files 4.5.3. HAL BSP Files and Folders 4.5.4. Linker Map Validation
4.5.3. HAL BSP Files and Folders x
4.5.3.1. HAL BSP After Generating Files 4.5.3.2. Copied BSP Files 4.5.3.3. HAL BSP After Build
4.6. Tcl Scripts for BSP Settings x
4.6.1. Calling a Custom BSP Tcl Script
4.6.1. Calling a Custom BSP Tcl Script x
4.6.1.1. Simple Tcl Script 4.6.1.2. Tcl Script to Examine Hardware and Choose Settings
4.7. Revising Your BSP x
4.7.1. Rebuilding Your BSP 4.7.2. Regenerating Your BSP 4.7.3. Updating Your BSP 4.7.4. Recreating Your BSP
4.7.1. Rebuilding Your BSP x
4.7.1.1. What Happens 4.7.1.2. How to Rebuild Your BSP
4.7.2. Regenerating Your BSP x
4.7.2.1. What Happens 4.7.2.2. When to Regenerate Your BSP 4.7.2.3. How to Regenerate Your BSP
4.7.2.3. How to Regenerate Your BSP x
4.7.2.3.1. Regenerating Your BSP in Eclipse 4.7.2.3.2. Regenerating Your BSP from the Command Line
4.7.3. Updating Your BSP x
4.7.3.1. What Happens 4.7.3.2. When to Update Your BSP 4.7.3.3. How to Update Your BSP
4.7.4. Recreating Your BSP x
4.7.4.1. What Happens 4.7.4.2. When to Recreate Your BSP 4.7.4.3. How to Recreate Your BSP
4.7.4.3. How to Recreate Your BSP x
4.7.4.3.1. Using Tcl Scripts When Recreating Your BSP 4.7.4.3.2. Recreating Your BSP in Eclipse 4.7.4.3.3. Recreating Your BSP at the Command Line
4.8. Specifying BSP Defaults x
4.8.1. Top Level Tcl Script for BSP Defaults 4.8.2. Specifying the Default stdio Device 4.8.3. Specifying the Default System Timer 4.8.4. Specifying the Default Memory Map 4.8.5. Specifying Default Bootloader Parameters 4.8.6. Using Individual Default Tcl Procedures
4.8.5. Specifying Default Bootloader Parameters x
4.8.5.1. Boot Loader Dependent Settings
4.10. Boot Configurations for Altera Embedded Software x
4.10.1. Memory Types 4.10.2. Boot from Flash Configuration 4.10.3. Boot from Monitor Configuration 4.10.4. Run from Initialized Memory Configuration 4.10.5. Run-time Configurable Reset Configuration
4.11. Intel FPGA-Provided Embedded Development Tools x
4.11.1. Nios II Software Build Tool GUIs 4.11.2. The Nios II Command Shell 4.11.3. The Nios II Command-Line Commands
4.11.1. Nios II Software Build Tool GUIs x
4.11.1.1. The Nios II SBT for Eclipse 4.11.1.2. The Nios II BSP Editor 4.11.1.3. The Nios II Flash Programmer
4.11.3. The Nios II Command-Line Commands x
4.11.3.1. GNU Compiler Tool Chain 4.11.3.2. Nios II Software Build Tools 4.11.3.3. File Format Conversion Tools 4.11.3.4. Other Command-Line Tools
4.11.3.3. File Format Conversion Tools x
4.11.3.3.1. alt-file-convert (BETA) 4.11.3.3.2. bin2flash 4.11.3.3.3. elf2dat 4.11.3.3.4. elf2flash 4.11.3.3.5. elf2hex 4.11.3.3.6. elf2mif 4.11.3.3.7. flash2dat 4.11.3.3.8. sof2flash
4.11.3.4. Other Command-Line Tools x
4.11.3.4.1. nios2-download 4.11.3.4.2. nios2-flash-programmer-generate 4.11.3.4.3. nios2-flash-programmer 4.11.3.4.4. nios2-gdb-server 4.11.3.4.5. nios2-terminal 4.11.3.4.6. validate_zip 4.11.3.4.7. nios2-configure-sof 4.11.3.4.8. jtagconfig
5. Overview of the Hardware Abstraction Layer x
5.1. Getting Started with the Hardware Abstraction Layer 5.2. HAL Architecture for Embedded Software Systems 5.3. Embedded Hardware Supported by the HAL 5.4. Overview of the Hardware Abstraction Layer Revision History
5.2. HAL Architecture for Embedded Software Systems x
5.2.1. Services 5.2.2. Layers of a HAL-Based System 5.2.3. Applications versus Drivers 5.2.4. Generic Device Models 5.2.5. C Standard Library—newlib
5.2.4. Generic Device Models x
5.2.4.1. Device Model Classes 5.2.4.2. Benefits to Application Developers 5.2.4.3. Benefits to Device Driver Developers
5.3. Embedded Hardware Supported by the HAL x
5.3.1. Nios II Processor Core Support 5.3.2. Supported Peripherals 5.3.3. MPU Support 5.3.4. MMU Support
5.3.2. Supported Peripherals x
5.3.2.1. Provide Full HAL Support 5.3.2.2. Provide Partial HAL Support
6. Developing Programs Using the Hardware Abstraction Layer x
6.1. HAL BSP Settings 6.2. The Nios II Embedded Project Structure 6.3. The system.h System Description File 6.4. Data Widths and the HAL Type Definitions 6.5. UNIX-Style Interface 6.6. File System 6.7. Using Character-Mode Devices 6.8. Using File Subsystems 6.9. Using Timer Devices 6.10. Using Flash Devices 6.11. Using DMA Devices 6.12. Using Interrupt Controllers 6.13. Reducing Code Footprint in Embedded Systems 6.14. Boot Sequence and Entry Point 6.15. Memory Usage 6.16. Working with HAL Source Files 6.17. Developing Programs Using the Hardware Abstraction Layer Revision History
6.7. Using Character-Mode Devices x
6.7.1. Standard Input, Standard Output and Standard Error 6.7.2. General Access to Character Mode Devices 6.7.3. C++ Streams 6.7.4. /dev/null 6.7.5. Lightweight Character-Mode I/O 6.7.6. Intel FPGA Logging Functions
6.7.6. Intel FPGA Logging Functions x
6.7.6.1. Enabling Logging 6.7.6.2. Extra Logging Options 6.7.6.3. Logging Levels 6.7.6.4. Example: Creating a BSP with Logging 6.7.6.5. Custom Logging Messages 6.7.6.6. Altera Logging Files
6.8. Using File Subsystems x
6.8.1. Host-Based File System
6.9. Using Timer Devices x
6.9.1. System Clock Driver 6.9.2. Alarms 6.9.3. Timestamp Driver
6.10. Using Flash Devices x
6.10.1. Simple Flash Access 6.10.2. Block Erasure or Corruption 6.10.3. Fine-Grained Flash Access
6.10.3. Fine-Grained Flash Access x
6.10.3.1. alt_get_flash_info() 6.10.3.2. alt_erase_flash() 6.10.3.3. alt_write_flash_block() 6.10.3.4. alt_lock_flash()
6.11. Using DMA Devices x
6.11.1. DMA Transmit Channels 6.11.2. DMA Receive Channels
6.11.2. DMA Receive Channels x
6.11.2.1. Memory-to-Memory DMA Transactions
6.13. Reducing Code Footprint in Embedded Systems x
6.13.1. Enable Compiler Optimizations 6.13.2. Use Reduced Device Drivers 6.13.3. Reduce the File Descriptor Pool 6.13.4. Use /dev/null 6.13.5. Use a Smaller File I/O Library 6.13.6. Use the Lightweight Device Driver API 6.13.7. Use the Minimal Character-Mode API 6.13.8. Eliminate Unused Device Drivers 6.13.9. Eliminate Unneeded Exit Code 6.13.10. Turn off C++ Support
6.13.5. Use a Smaller File I/O Library x
6.13.5.1. Definition of 'asnprintf()' 6.13.5.2. Use the Small newlib C Library 6.13.5.3. Use UNIX-Style File I/O 6.13.5.4. Emulate ANSI C Functions
6.13.7. Use the Minimal Character-Mode API x
6.13.7.1. alt_printf() 6.13.7.2. alt_putchar() 6.13.7.3. alt_putstr() 6.13.7.4. alt_getchar()
6.13.9. Eliminate Unneeded Exit Code x
6.13.9.1. Eliminate Clean Exit 6.13.9.2. Eliminate All Exit Code
6.14. Boot Sequence and Entry Point x
6.14.1. Hosted Versus Free-Standing Applications 6.14.2. Boot Sequence for HAL-Based Programs 6.14.3. Customizing the Boot Sequence
6.14.2. Boot Sequence for HAL-Based Programs x
6.14.2.1. System Initialization Code Boot Sequence 6.14.2.2. Default Implementation Steps
6.15. Memory Usage x
6.15.1. Memory Sections 6.15.2. Assigning Code and Data to Memory Partitions 6.15.3. Placement of the Heap and Stack 6.15.4. Global Pointer Register 6.15.5. Boot Modes
6.15.2. Assigning Code and Data to Memory Partitions x
6.15.2.1. Simple Placement Options 6.15.2.2. Advanced Placement Options
6.16. Working with HAL Source Files x
6.16.1. Finding HAL Files 6.16.2. Overriding HAL Functions
7. Developing Device Drivers for the Hardware Abstraction Layer x
7.1. Driver Integration in the HAL API 7.2. The HAL Peripheral-Specific API 7.3. Preparing for HAL Driver Development 7.4. Development Flow for Creating Device Drivers 7.5. Nios II Hardware Design Concepts 7.6. Accessing Hardware 7.7. Creating Embedded Drivers for HAL Device Classes 7.8. Integrating a Device Driver in the HAL 7.9. Creating a Custom Device Driver for the HAL 7.10. Reducing Code Footprint in HAL Embedded Drivers 7.11. HAL Namespace Allocation 7.12. Overriding the HAL Default Device Drivers 7.13. Developing Device Drivers for the Hardware Abstraction Layer Revision History
7.5. Nios II Hardware Design Concepts x
7.5.1. The Relationship Between the .sopcinfo File and system.h 7.5.2. Using the System Generation Tool to Optimize Hardware 7.5.3. Components, Devices, and Peripherals
7.7. Creating Embedded Drivers for HAL Device Classes x
7.7.1. Character-Mode Device Drivers 7.7.2. File Subsystem Drivers 7.7.3. Timer Device Drivers 7.7.4. Flash Device Drivers 7.7.5. DMA Device Drivers 7.7.6. Ethernet Device Drivers
7.7.1. Character-Mode Device Drivers x
7.7.1.1. Create a Device Instance 7.7.1.2. Register a Character Device
7.7.1.1. Create a Device Instance x
7.7.1.1.1. Modifying the Global Error Status, errno 7.7.1.1.2. Default Behavior for Functions Defined in alt_dev
7.7.2. File Subsystem Drivers x
7.7.2.1. Create a Device Instance 7.7.2.2. Register a File Subsystem Device
7.7.3. Timer Device Drivers x
7.7.3.1. System Clock Driver 7.7.3.2. Timestamp Driver
7.7.4. Flash Device Drivers x
7.7.4.1. Create a Flash Driver 7.7.4.2. Register a Flash Device
7.7.5. DMA Device Drivers x
7.7.5.1. DMA Transmit Channel 7.7.5.2. DMA Receive Channel
7.7.6. Ethernet Device Drivers x
7.7.6.1. Layered Software Model 7.7.6.2. Writing a New Ethernet Device Driver 7.7.6.3. Provide the NicheStack Hardware Interface Routines 7.7.6.4. Provide *INSTANCE and *INIT Macros 7.7.6.5. Provide a Software Initialization Function
7.8. Integrating a Device Driver in the HAL x
7.8.1. Overview 7.8.2. Assumptions and Requirements 7.8.3. The Nios II BSP Generator 7.8.4. File Names and Locations 7.8.5. Driver and Software Package Tcl Script Creation
7.8.3. The Nios II BSP Generator x
7.8.3.1. Component Discovery 7.8.3.2. Device Driver Versions 7.8.3.3. Device Driver and Software Package Inclusion
7.8.3.3. Device Driver and Software Package Inclusion x
7.8.3.3.1. Specific Requests 7.8.3.3.2. No Specific Requests
7.8.4. File Names and Locations x
7.8.4.1. Source Code Discovery
7.8.5. Driver and Software Package Tcl Script Creation x
7.8.5.1. Example Device Driver File Hierarchy and Naming 7.8.5.2. Tcl Command Walkthrough for a Typical Driver or Software Package 7.8.5.3. Creating Settings for Device Drivers and Software Packages
7.8.5.2. Tcl Command Walkthrough for a Typical Driver or Software Package x
7.8.5.2.1. Creating and Naming the Driver or Package 7.8.5.2.2. Identifying the Hardware Component Class 7.8.5.2.3. Setting the BSP Type 7.8.5.2.4. Specifying an Operating System 7.8.5.2.5. Specifying Source Files 7.8.5.2.6. Specifying a Subdirectory 7.8.5.2.7. Enabling Software Initialization 7.8.5.2.8. Adding Include Paths 7.8.5.2.9. Version Compatibility
7.8.5.3. Creating Settings for Device Drivers and Software Packages x
7.8.5.3.1. How Settings Affect the Generated BSP 7.8.5.3.2. Data Types 7.8.5.3.3. Setting Destination Files 7.8.5.3.4. Setting Display Name 7.8.5.3.5. Setting Generation Name 7.8.5.3.6. Setting Default Value 7.8.5.3.7. Setting Description 7.8.5.3.8. Setting Creation Example
7.9. Creating a Custom Device Driver for the HAL x
7.9.1. Header Files and alt_sys_init.c 7.9.2. Device Driver Source Code
7.9.1. Header Files and alt_sys_init.c x
7.9.1.1. Creating alt_sys_init.c Based on Associated Header Files 7.9.1.2. altera_avalon_jtag_uart.h Defining Macros
7.10. Reducing Code Footprint in HAL Embedded Drivers x
7.10.1. Provide Reduced Footprint Drivers 7.10.2. Support the Lightweight Device Driver API
7.10.2. Support the Lightweight Device Driver API x
7.10.2.1. Using Character-Mode Functions 7.10.2.2. Using Macros 7.10.2.3. Invoking Macros in Your Application Software 7.10.2.4. Calling Direct Without Macros
8. Exception Handling x
8.1. Nios II Exception Handling Overview 8.2. Nios II Interrupt Service Routines 8.3. Improving Nios II ISR Performance 8.4. Debugging Nios II ISRs 8.5. HAL Exception Handling System Implementation 8.6. The Nios II Instruction-Related Exception Handler 8.7. Exception Handling Revision History
8.1. Nios II Exception Handling Overview x
8.1.1. Exception Handling Terminology 8.1.2. Interrupt Controllers 8.1.3. Latency and Response Time
8.1.2. Interrupt Controllers x
8.1.2.1. Internal Interrupt Concepts 8.1.2.2. External Interrupt Concepts
8.1.2.2. External Interrupt Concepts x
8.1.2.2.1. Requested Handler Address 8.1.2.2.2. Requested Interrupt Level 8.1.2.2.3. Requested Register Set 8.1.2.2.4. Requested NMI Mode 8.1.2.2.5. Shadow Register Sets
8.1.3. Latency and Response Time x
8.1.3.1. Internal or External Interrupt Controller 8.1.3.2. Shadow Register Sets 8.1.3.3. How the Internal Interrupt Controller Works 8.1.3.4. How an External Interrupt Controller Works
8.1.3.2. Shadow Register Sets x
8.1.3.2.1. How the Hardware Works
8.2. Nios II Interrupt Service Routines x
8.2.1. HAL APIs for Hardware Interrupts 8.2.2. HAL ISR Restrictions 8.2.3. Writing an ISR 8.2.4. Registering an ISR with the Enhanced Interrupt API 8.2.5. Enabling and Disabling Interrupts 8.2.6. Configuring an External Interrupt Controller 8.2.7. C Example 8.2.8. Upgrading to the Enhanced HAL Interrupt API
8.2.1. HAL APIs for Hardware Interrupts x
8.2.1.1. Selecting an Interrupt API 8.2.1.2. The Enhanced HAL Interrupt API 8.2.1.3. Using the Enhanced HAL Interrupt API to Implement ISRs 8.2.1.4. The Legacy HAL Interrupt API 8.2.1.5. Supporting Multiple Interrupt APIs
8.2.1.3. Using the Enhanced HAL Interrupt API to Implement ISRs x
8.2.1.3.1. The External Interrupt Controller Driver 8.2.1.3.2. Using the HAL Interrupt API with the VIC
8.2.1.4. The Legacy HAL Interrupt API x
8.2.1.4.1. Using the Legacy HAL API to Implement ISRs
8.2.3. Writing an ISR x
8.2.3.1. Using Interrupt Funnels 8.2.3.2. Running in a Restricted Environment 8.2.3.3. Managing Pre-Emption
8.2.4. Registering an ISR with the Enhanced Interrupt API x
8.2.4.1. Methods the HAL Uses to Register the ISR
8.2.7. C Example x
8.2.7.1. An ISR to Service a Button PIO Interrupt 8.2.7.2. Registering the Button PIO ISR with the HAL
8.3. Improving Nios II ISR Performance x
8.3.1. Software Performance Improvements 8.3.2. Hardware Performance Improvements
8.3.1. Software Performance Improvements x
8.3.1.1. Execute Time-Intensive Algorithms in the Application Context 8.3.1.2. Implement Time-Intensive Algorithms in Hardware 8.3.1.3. Increase Buffer Size 8.3.1.4. Use Double Buffering 8.3.1.5. Keep Interrupts Enabled 8.3.1.6. Use Fast Memory 8.3.1.7. Use a Separate Exception Stack 8.3.1.8. Use Nested Hardware Interrupts 8.3.1.9. Locate ISR Body in Vector Table 8.3.1.10. Use Compiler Optimization
8.3.1.7. Use a Separate Exception Stack x
8.3.1.7.1. Separate General Exception Stack 8.3.1.7.2. Separate Hardware Interrupt Stack
8.3.1.8. Use Nested Hardware Interrupts x
8.3.1.8.1. Nested Hardware Interrupts with the Internal Interrupt Controller 8.3.1.8.2. Nested Hardware Interrupts with an External Interrupt Controller
8.3.2. Hardware Performance Improvements x
8.3.2.1. Use Vectored Hardware Interrupts 8.3.2.2. Add Fast Memory 8.3.2.3. Add a DMA Controller 8.3.2.4. Place the Handler in Fast Memory 8.3.2.5. Use a Fast Nios II Core 8.3.2.6. Select Hardware Interrupt Priorities
8.3.2.1. Use Vectored Hardware Interrupts x
8.3.2.1.1. Using the Interrupt Vector Custom Instruction 8.3.2.1.2. Using an External Interrupt Controller
8.3.2.6. Select Hardware Interrupt Priorities x
8.3.2.6.1. Hardware Interrupt Priorities with the Internal Interrupt Controller 8.3.2.6.2. Hardware Interrupt Priorities with an External Interrupt Controller
8.5. HAL Exception Handling System Implementation x
8.5.1. Exception Handling System Structure 8.5.2. General Exception Funnel 8.5.3. Hardware Interrupt Funnel 8.5.4. Software Exception Funnel 8.5.5. Invalid Instructions
8.5.2. General Exception Funnel x
8.5.2.1. Hardware Interrupt Dispatch with the Internal Interrupt Controller 8.5.2.2. Returning from Exceptions
8.5.3. Hardware Interrupt Funnel x
8.5.3.1. Interrupt Funnel for the Internal Interrupt Controller 8.5.3.2. Interrupt Funnels for External Interrupt Controllers 8.5.3.3. Interrupt Funnels for Internal Interrupt Controllers
8.5.4. Software Exception Funnel x
8.5.4.1. Unimplemented Instructions 8.5.4.2. Instruction-Related Exceptions 8.5.4.3. Software Trap Handling 8.5.4.4. Miscellaneous Exceptions
8.5.4.1. Unimplemented Instructions x
8.5.4.1.1. When to Use the Unimplemented Instruction Handler 8.5.4.1.2. Using the Unimplemented Instruction Handler
8.6. The Nios II Instruction-Related Exception Handler x
8.6.1. Writing an Instruction-Related Exception Handler 8.6.2. Registering an Instruction-Related Exception Handler 8.6.3. Removing an Instruction-Related Exception Handler
8.6.1. Writing an Instruction-Related Exception Handler x
8.6.1.1. Exception Cause Codes
9. Cache and Tightly-Coupled Memory x
9.1. Nios II Cache Implementation 9.2. HAL API Functions for Managing Cache 9.3. Initializing the Nios II Cache after Reset 9.4. Nios II Device Driver Cache Considerations 9.5. Cache Considerations for Writing Program Loaders 9.6. Managing Cache in Multi-Master and Multi-Processor Systems 9.7. Nios II Tightly-Coupled Memory 9.8. Cache and Tightly-Coupled Memory Revision History
9.1. Nios II Cache Implementation x
9.1.1. Defining Cache Properties
9.3. Initializing the Nios II Cache after Reset x
9.3.1. Assembly Code to Initialize the Instruction Cache 9.3.2. Assembly Code to Initialize the Data Cache 9.3.3. HAL Behavior for Initializing the Nios II Cache after Reset
9.4. Nios II Device Driver Cache Considerations x
9.4.1. HAL Behavior for Nios II Device Driver Cache Considerations
9.5. Cache Considerations for Writing Program Loaders x
9.5.1. HAL Behavior for Cache Considerations for Writing Program Loaders
9.6. Managing Cache in Multi-Master and Multi-Processor Systems x
9.6.1. Bit-31 Cache Bypass 9.6.2. HAL Behavior for Managing Cache in Multi-Master and Multi-Processor Systems
10. MicroC/OS-II Real-Time Operating System x
10.1. Overview of the MicroC/OS-II RTOS 10.2. Other RTOS Providers 10.3. The Nios II Implementation of MicroC/OS-II 10.4. Implementing MicroC/OS-II Projects for the Nios II Processor 10.5. MicroC/OS-II Real-Time Operating System Revision History
10.1. Overview of the MicroC/OS-II RTOS x
10.1.1. Licensing
10.3. The Nios II Implementation of MicroC/OS-II x
10.3.1. MicroC/OS-II Architecture 10.3.2. MicroC/OS-II Device Drivers 10.3.3. Thread-Safe HAL Drivers 10.3.4. The newlib ANSI C Standard Library 10.3.5. Interrupt Service Routines for MicroC/OS-II
11. Ethernet and the NicheStack TCP/IP Stack x
11.1. Prerequisites for Understanding the NicheStack TCP/IP Stack 11.2. Introduction to the NicheStack TCP/IP Stack - Nios II Edition 11.3. Other TCP/IP Stack Providers for the Nios II Processor 11.4. Using the NicheStack TCP/IP Stack - Nios II Edition 11.5. Configuring the NicheStack TCP/IP Stack in a Nios II Program 11.6. Further Information 11.7. Known Limitations 11.8. Ethernet and the NicheStack TCP/IP Stack - Nios II Edition Revision History
11.2. Introduction to the NicheStack TCP/IP Stack - Nios II Edition x
11.2.1. The NicheStack TCP/IP Stack Files and Directories 11.2.2. Support and Licensing
11.4. Using the NicheStack TCP/IP Stack - Nios II Edition x
11.4.1. Nios II System Requirements 11.4.2. The NicheStack TCP/IP Stack Tasks 11.4.3. Initializing the Stack 11.4.4. Calling the Sockets Interface
11.4.3. Initializing the Stack x
11.4.3.1. alt_iniche_init() 11.4.3.2. netmain() 11.4.3.3. iniche_net_ready 11.4.3.4. get_mac_addr() and get_ip_addr()
11.4.3.4. get_mac_addr() and get_ip_addr() x
11.4.3.4.1. Prototype for get_mac_addr() 11.4.3.4.2. Prototype for get_ip_addr()
11.5. Configuring the NicheStack TCP/IP Stack in a Nios II Program x
11.5.1. NicheStack TCP/IP Stack General Settings 11.5.2. IP Options 11.5.3. TCP Options
12. Read-Only Zip File System x
12.1. Using the Read-Only Zip File System in a Project 12.2. Read-Only Zip File System Revision History
12.1. Using the Read-Only Zip File System in a Project x
12.1.1. Preparing the Zip File 12.1.2. Programming the Zip File to Flash
13. Publishing Component Information to Embedded Software x
13.1. Embedded Component Information Flow 13.2. Embedded Software Assignments 13.3. Publishing Component Information to Embedded Software Revision History
13.1. Embedded Component Information Flow x
13.1.1. Embedded Component Information Flow Diagram 13.1.2. Tcl Assignment Statements
13.2. Embedded Software Assignments x
13.2.1. C Macro Namespace 13.2.2. Configuration Namespace 13.2.3. Memory Initialization Namespace
13.2.1. C Macro Namespace x
13.2.1.1. Generated Macro in system.h 13.2.1.2. GCC C/C++ 32-bit Processor Constants
13.2.2. Configuration Namespace x
13.2.2.1. Configuration Data Types 13.2.2.2. Component Configuration Information 13.2.2.3. Memory-Mapped Slave Information 13.2.2.4. Streaming Source Information 13.2.2.5. Streaming Sink Information
14. HAL API Reference x
14.1. HAL API Functions 14.2. HAL Standard Types 14.3. ADC HAL Device Driver 14.4. HAL API Reference Revision History
14.1. HAL API Functions x
14.1.1. _exit() 14.1.2. _rename() 14.1.3. alt_dcache_flush() 14.1.4. alt_dcache_flush_all() 14.1.5. alt_dcache_flush_no_writeback() 14.1.6. alt_uncached_malloc() 14.1.7. alt_uncached_free() 14.1.8. alt_remap_uncached() 14.1.9. alt_remap_cached() 14.1.10. alt_icache_flush_all() 14.1.11. alt_icache_flush() 14.1.12. alt_alarm_start() 14.1.13. alt_alarm_stop() 14.1.14. alt_dma_rxchan_depth() 14.1.15. alt_dma_rxchan_close() 14.1.16. alt_dev_reg() 14.1.17. alt_dma_rxchan_open() 14.1.18. alt_dma_rxchan_prepare() 14.1.19. alt_dma_rxchan_reg() 14.1.20. alt_dma_txchan_close() 14.1.21. alt_dma_txchan_ioctl() 14.1.22. alt_dma_txchan_open() 14.1.23. alt_dma_txchan_reg() 14.1.24. alt_flash_close_dev() 14.1.25. alt_exception_cause_generated_bad_addr() 14.1.26. alt_erase_flash_block() 14.1.27. alt_dma_rxchan_ioctl() 14.1.28. alt_dma_txchan_space() 14.1.29. alt_dma_txchan_send() 14.1.30. alt_flash_open_dev() 14.1.31. alt_fs_reg() 14.1.32. alt_get_flash_info() 14.1.33. alt_ic_irq_disable() 14.1.34. alt_ic_irq_enabled() 14.1.35. alt_ic_isr_register() 14.1.36. alt_ic_irq_enable() 14.1.37. alt_instruction_exception_register() 14.1.38. alt_irq_disable() 14.1.39. alt_irq_cpu_enable_interrupts () 14.1.40. alt_irq_disable_all() 14.1.41. alt_irq_enable() 14.1.42. alt_irq_enable_all() 14.1.43. alt_irq_enabled() 14.1.44. alt_irq_init() 14.1.45. alt_irq_pending () 14.1.46. alt_irq_register() 14.1.47. alt_llist_insert() 14.1.48. alt_llist_remove() 14.1.49. alt_load_section() 14.1.50. alt_nticks() 14.1.51. alt_read_flash() 14.1.52. alt_tick() 14.1.53. alt_ticks_per_second() 14.1.54. alt_timestamp() 14.1.55. alt_timestamp_freq() 14.1.56. alt_timestamp_start() 14.1.57. alt_write_flash() 14.1.58. alt_write_flash_block() 14.1.59. close() 14.1.60. fstat() 14.1.61. fork() 14.1.62. fcntl() 14.1.63. execve() 14.1.64. getpid() 14.1.65. kill() 14.1.66. stat() 14.1.67. settimeofday() 14.1.68. wait() 14.1.69. unlink() 14.1.70. sbrk() 14.1.71. link() 14.1.72. lseek() 14.1.73. alt_sysclk_init() 14.1.74. open() 14.1.75. times() 14.1.76. read() 14.1.77. write() 14.1.78. usleep() 14.1.79. alt_lock_flash() 14.1.80. gettimeofday() 14.1.81. ioctl() 14.1.82. isatty()
14.2. HAL Standard Types x
14.2.1. alt_getchar() 14.2.2. alt_putstr() 14.2.3. alt_putchar() 14.2.4. alt_printf()
14.3. ADC HAL Device Driver x
14.3.1. adc_stop 14.3.2. adc_start 14.3.3. adc_set_mode_run_once 14.3.4. adc_set_mode_run_continuously 14.3.5. adc_recalibrate 14.3.6. adc_interrupt_enable 14.3.7. adc_interrupt_disable 14.3.8. adc_clear_interrupt_status 14.3.9. adc_wait_for_interrupt - ADC Sample Storage Status Register 14.3.10. adc_interrupt_asserted 14.3.11. adc_wait_for interrupt - IRQ Status Register 14.3.12. alt_adc_word_read
15. Nios II Software Build Tools Reference x
15.1. Nios II Software Build Tools Utilities 15.2. Nios II Design Example Scripts 15.3. Settings Managed by the Software Build Tools 15.4. Application and User Library Makefile Variables 15.5. Software Build Tools Tcl Commands 15.6. Software Build Tools Path Names 15.7. Nios II Software Build Tools Reference Revision History
15.1. Nios II Software Build Tools Utilities x
15.1.1. Logging Levels 15.1.2. Setting Values 15.1.3. Utility and Script Summary 15.1.4. nios2-app-generate-makefile 15.1.5. nios2-bsp-create-settings 15.1.6. nios2-bsp-generate-files 15.1.7. nios2-bsp-query-settings 15.1.8. nios2-bsp-update-settings 15.1.9. nios2-lib-generate-makefile 15.1.10. nios2-bsp-editor 15.1.11. nios2-app-update-makefile 15.1.12. nios2-lib-update-makefile 15.1.13. nios2-swexample-create 15.1.14. nios2-elf-insert 15.1.15. nios2-elf-query 15.1.16. nios2-flash-programmer-generate 15.1.17. nios2-bsp 15.1.18. nios2-bsp-console 15.1.19. alt-file-convert (BETA)
15.2. Nios II Design Example Scripts x
15.2.1. create-this-bsp 15.2.2. create-this-app 15.2.3. Finding create-this-app and create-this-bsp
15.3. Settings Managed by the Software Build Tools x
15.3.1. Overview of BSP Settings 15.3.2. Overview of Component and Driver Settings 15.3.3. Settings Reference
15.3.2. Overview of Component and Driver Settings x
15.3.2.1. Altera Host-Based File System Settings 15.3.2.2. Altera Read-Only Zip File System Settings 15.3.2.3. Altera NicheStack TCP/IP - Nios II Edition Stack Settings 15.3.2.4. Altera Avalon-MM JTAG UART Driver Settings 15.3.2.5. Intel FPGA Avalon-MM UART Driver Settings
15.4. Application and User Library Makefile Variables x
15.4.1. Application Makefile Variables 15.4.2. User Library Makefile Variables 15.4.3. Standard Build Flag Variables
15.5. Software Build Tools Tcl Commands x
15.5.1. Tcl Command Environments 15.5.2. Tcl Commands for BSP Settings 15.5.3. Tcl Commands for BSP Generation Callbacks 15.5.4. Tcl Commands for Drivers and Packages
15.5.2. Tcl Commands for BSP Settings x
15.5.2.1. add_memory_device 15.5.2.2. add_memory_region 15.5.2.3. add_section_mapping 15.5.2.4. are_same_resource 15.5.2.5. delete_memory_region 15.5.2.6. delete_section_mapping 15.5.2.7. disable_sw_package 15.5.2.8. enable_sw_package 15.5.2.9. get_addr_span 15.5.2.10. get_assignment 15.5.2.11. get_available_drivers 15.5.2.12. get_available_sw_packages 15.5.2.13. get_base_addr 15.5.2.14. get_break_offset 15.5.2.15. get_break_slave_desc 15.5.2.16. get_cpu_name 15.5.2.17. get_current_memory_regions 15.5.2.18. get_current_section_mappings 15.5.2.19. get_default_memory_regions 15.5.2.20. get_driver 15.5.2.21. get_enabled_sw_packages 15.5.2.22. get_exception_offset 15.5.2.23. get_exception_slave_desc 15.5.2.24. get_fast_tlb_miss_exception_offset 15.5.2.25. get_fast_tlb_miss_exception_slave_desc 15.5.2.26. get_interrupt_controller_id 15.5.2.27. get_irq_interrupt_controller_id 15.5.2.28. get_irq_number 15.5.2.29. get_memory_region 15.5.2.30. get_module_class_name 15.5.2.31. get_module_name 15.5.2.32. get_reset_offset 15.5.2.33. get_reset_slave_desc 15.5.2.34. get_section_mapping 15.5.2.35. get_setting 15.5.2.36. get_setting_desc 15.5.2.37. get_slave_descs 15.5.2.38. is_char_device 15.5.2.39. is_connected_interrupt_controller_device 15.5.2.40. is_connected_to_data_master 15.5.2.41. is_connected_to_instruction_master 15.5.2.42. is_ethernet_mac_device 15.5.2.43. is_flash 15.5.2.44. is_memory_device 15.5.2.45. is_non_volatile_storage 15.5.2.46. is_timer_device 15.5.2.47. log_debug 15.5.2.48. log_default 15.5.2.49. log_error 15.5.2.50. log_verbose 15.5.2.51. set_driver 15.5.2.52. set_ignore_file 15.5.2.53. set_setting 15.5.2.54. update_memory_region 15.5.2.55. update_section_mapping 15.5.2.56. add_default_memory_regions 15.5.2.57. create_bsp 15.5.2.58. generate_bsp 15.5.2.59. get_available_bsp_type_versions 15.5.2.60. get_available_bsp_types 15.5.2.61. get_available_cpu_architectures 15.5.2.62. get_available_cpu_names 15.5.2.63. get_available_software 15.5.2.64. get_available_software_setting_properties 15.5.2.65. get_available_software_settings 15.5.2.66. get_bsp_version 15.5.2.67. get_cpu_architecture 15.5.2.68. get_nios2_dpx_thread_num 15.5.2.69. get_sopcinfo_file 15.5.2.70. get_supported_bsp_types 15.5.2.71. is_bsp_hal_extension 15.5.2.72. is_bsp_lwhal_extension 15.5.2.73. open_bsp 15.5.2.74. save_bsp 15.5.2.75. set_bsp_version 15.5.2.76. set_logging_mode
15.5.3. Tcl Commands for BSP Generation Callbacks x
15.5.3.1. add_class_sw_setting 15.5.3.2. add_class_systemh_line 15.5.3.3. add_module_sw_property 15.5.3.4. add_module_sw_setting 15.5.3.5. add_module_systemh_line 15.5.3.6. add_systemh_line 15.5.3.7. get_class_peripheral 15.5.3.8. get_module_assignment 15.5.3.9. get_module_name 15.5.3.10. get_module_peripheral 15.5.3.11. get_module_sw_setting_value 15.5.3.12. get_peripheral_property 15.5.3.13. remove_class_systemh_line 15.5.3.14. remove_module_systemh_line 15.5.3.15. set_class_sw_setting_property 15.5.3.16. set_module_sw_setting_property
15.5.4. Tcl Commands for Drivers and Packages x
15.5.4.1. add_sw_property 15.5.4.2. add_sw_setting Usage Options Description 15.5.4.3. add_sw_setting2 15.5.4.4. create_driver 15.5.4.5. create_os 15.5.4.6. create_sw_package 15.5.4.7. set_sw_property 15.5.4.8. set_sw_setting_property
15.6. Software Build Tools Path Names x
15.6.1. Command Arguments 15.6.2. Object File Directory Tree
1. Overview of Nios II Embedded Development
2. Getting Started with the Graphical User Interface
3. Getting Started from the Command Line
4. Nios II Software Build Tools
5. Overview of the Hardware Abstraction Layer
6. Developing Programs Using the Hardware Abstraction Layer
7. Developing Device Drivers for the Hardware Abstraction Layer
8. Exception Handling
9. Cache and Tightly-Coupled Memory
10. MicroC/OS-II Real-Time Operating System
11. Ethernet and the NicheStack TCP/IP Stack
12. Read-Only Zip File System
13. Publishing Component Information to Embedded Software
14. HAL API Reference
15. Nios II Software Build Tools Reference

15.5.4.2. add_sw_setting

Usage

add_sw_setting <type> <destination> <displayName> <identifier> <value> <description>

Options

  • <type>: Setting type - Boolean, QuotedString, UnquotedString.
  • <destination>: The destination BSP file associated with the setting, or the module generator that processes this setting.
  • <displayName>: Setting name.
  • <identifier>: Name of the macro created for a generated destination file.
  • <value>: Default value of the setting.
  • <description>: Setting description.

Description

This command creates a BSP setting associated with a software package or device driver. The setting is available whenever the software package or device driver is present in the BSP. nios2-bsp-generate-files converts the setting and its value into either a C preprocessor macro or BSP makefile variable. add_sw_setting passes macro definitions to the compiler using the -D command-line option, or adds them to the system.h file as #define statements.

The setting only exists once even if there are multiple instances of a software package. Set or get the setting with the --set and --get command-line options of the nios2-bsp, nios2-bsp-create-settings, nios2-bsp-query-settings, and nios2-bsp-update-settings commands. You can also use the BSP Tcl commands set_setting and get_setting to set or get the setting. The value of the setting persists in the BSP settings file.

To create a setting, you must define each of the following parameters.

type—This parameter formats the setting value during BSP generation. The following supported types and usage restrictions apply:

  • boolean_define_only—Defines a macro if the setting’s value is 1 or true. Example: #define LCD_PRESENT. No macro is defined if the setting’s value is 0 or false. This setting type supports the system_h_define and public_mk_define destinations, defined below.
  • boolean—Defines a macro or makefile variable and sets it to 1 (if the value is 1 or true) or 0 (if the value is 0 or false). Example: #define LCD_PRESENT 1. This type supports all destinations.
  • character—Defines a macro as a single character with single quotes around the character. Example: #define DELIMITER ':'. This type supports the system_h_define destination, defined below.
  • decimal_number—Defines a macro or makefile variable and sets it with an unquoted decimal (integer) number. Example: #define NUM_COPROCESSORS 3. This type supports all destinations.
  • double—Defines a macro name and sets it to a value with a decimal point. Example: #define PI 3.1416. This type supports the system_h_define destination, defined below.
  • float—Defines a macro name and sets it to a value with a decimal point and f character. Example: #define PI 3.1416f. This type supports the system_h_define destination, defined below.
  • hex_number—Defines a macro name and sets it to a value with a 0x prepended to the value. Example: #define LCD_SIZE 0x1000. This type supports the system_h_define destination, defined below.
  • quoted_string—Quoted strings always have the macro name and setting value added to the destination files. In the destination, the setting value is enclosed in quotation marks. Example: #define DFLT_ERR "General error"
If the setting value contains white space, you must place quotation marks around the value string in the Tcl script. This type supports the system_h_define destination, defined below.
  • unquoted_string—Unquoted strings define a macro or makefile variable with setting name and value in the destination file. In the destination file, the setting value is not enclosed in quotation marks. Example: #define DFLT_ERROR Error This type supports all destinations.

destination—The destination parameter specifies where add_sw_setting puts the setting in the generated BSP. add_sw_settings supports the following destinations:

  • system_h_define—With this destination, add_sw_settings formats settings as #define <setting name> [<setting value>] macros in the system.h file
  • public_mk_define—With this destination, add_sw_settings formats settings as -D<setting name>[=<setting value>] additions to the ALT_CPPFLAGS variable in the BSP public.mk file. public.mk passes the flag to the C preprocessor for each source file in the BSP, and in applications and libraries using the BSP.
  • makefile_variable—With this destination, add_sw_settings formats settings as makefile variable additions to the BSP makefile. The variable name must be unique in the makefile.

displayName—The name of the setting. Settings exist in a hierarchical namespace. A period separates levels of the hierarchy. Settings created in your Tcl script are located in the hierarchy under the driver or software package name you specified in the create_driver or create_sw_package command. Example: my_driver.my_setting. The Nios II SBT adds the hierarchical prefix to the setting name.

identifier—The name of the macro or makefile variable being defined. In a setting added to the system.h file at generation time, this parameter corresponds to the text immediately following the #define statement.

value—The default value associated with the setting. If you do not assign a value to the option, its value is this default value. Valid initial values are TRUE, 1, FALSE, and 0 for boolean and boolean_define_only setting types, a single character for the character type, integer numbers for the decimal_number setting type, integer numbers with or without a 0x prefix for the hex_number type, numbers with decimals for float_number and double_number types, or an arbitrary string of text for quoted and unquoted string setting types. For string types, if the value contains any white space, you must enclose it in quotation marks.

description—Descriptive text that is inserted along with the setting value and name in the summary.html file. You must enclose the description in quotation marks if it contains any spaces. If the description includes any special characters (such as quotation marks), you must escape them with the backslash (\) character. The description field is mandatory, but can be an empty string ("").

Level Two Title