Nios® II Software Developer Handbook

Download PDF
ID 683525
Date 8/28/2023
Public
Document Table of Contents
Document Table of Contents x
Product Discontinuance Notification 1. Nios® II Software Developer's Handbook Revision History 2. Overview of Nios® II Embedded Development 3. Getting Started with the Graphical User Interface 4. Getting Started from the Command Line 5. Nios® II Software Build Tools 6. Overview of the Hardware Abstraction Layer 7. Developing Programs Using the Hardware Abstraction Layer 8. Developing Device Drivers for the Hardware Abstraction Layer 9. Exception Handling 10. Cache and Tightly-Coupled Memory 11. MicroC/OS-II Real-Time Operating System 12. Ethernet and the NicheStack TCP/IP Stack 13. Read-Only Zip File System 14. Publishing Component Information to Embedded Software 15. HAL API Reference 16. Nios® II Software Build Tools Reference 17. Nios® II Software Developer's Handbook Archives
1. Nios® II Software Developer's Handbook Revision History x
1.1. Overview of Nios® II Embedded Development Revision History 1.2. Getting Started with the Graphical User Interface Revision History 1.3. Getting Started from the Command Line Revision History 1.4. Nios® II Software Build Tools Revision History 1.5. Overview of the Hardware Abstraction Layer Revision History 1.6. Developing Programs Using the Hardware Abstraction Layer Revision History 1.7. Developing Device Drivers for the Hardware Abstraction Layer Revision History 1.8. Exception Handling Revision History 1.9. Cache and Tightly-Coupled Memory Revision History 1.10. MicroC/OS-II Real-Time Operating System Revision History 1.11. Ethernet and the NicheStack TCP/IP Stack - Nios® II Edition Revision History 1.12. Read-Only Zip File System Revision History 1.13. Publishing Component Information to Embedded Software Revision History 1.14. HAL API Reference Revision History 1.15. Nios® II Software Build Tools Reference Revision History
2. Overview of Nios® II Embedded Development x
2.1. Windows* Subsystem for Linux* (WSL 1) on Windows Requirements for Nios® II EDS 2.2. Prerequisites for Understanding the Nios® II Embedded Design Suite 2.3. Finding Nios II EDS Files 2.4. Nios® II Software Development Environment 2.5. Nios® II EDS Development Flows 2.6. Nios® II Programs 2.7. Intel FPGA Software Packages for Embedded Systems 2.8. Nios® II Embedded Design Examples 2.9. Third-Party Embedded Tools Support 2.10. Additional Nios® II Information
2.5. Nios® II EDS Development Flows x
2.5.1. Nios® II SBT Development Flow
2.5.1. Nios® II SBT Development Flow x
2.5.1.1. Nios® II SBT for Eclipse 2.5.1.2. Nios® II SBT Command Line
2.6. Nios® II Programs x
2.6.1. Makefiles and the SBT 2.6.2. Nios® II Software Project Types
2.6.2. Nios® II Software Project Types x
2.6.2.1. Application Project 2.6.2.2. User Library Project 2.6.2.3. BSP Project
2.8. Nios® II Embedded Design Examples x
2.8.1. Hardware Examples 2.8.2. Software Examples
3. Getting Started with the Graphical User Interface x
3.1. Installing Eclipse IDE into Nios® II EDS 3.2. Getting Started with Nios II Software in Eclipse 3.3. Makefiles and the Nios® II SBT for Eclipse 3.4. Using the BSP Editor 3.5. Run Configurations in the SBT for Eclipse 3.6. Optimizing Project Build Time 3.7. Importing a Command-Line Project 3.8. Packaging a Library for Reuse 3.9. Creating a Software Package 3.10. Programming Flash in Intel FPGA Embedded Systems 3.11. Creating Memory Initialization Files 3.12. Running a Nios® II System with ModelSim 3.13. Eclipse Usage Notes
3.1. Installing Eclipse IDE into Nios® II EDS x
3.1.1. Windows Installation 3.1.2. Linux Installation
3.2. Getting Started with Nios II Software in Eclipse x
3.2.1. The Nios II SBT for Eclipse Workbench 3.2.2. Creating a Project 3.2.3. Navigating the Project 3.2.4. Building the Project 3.2.5. Configuring the FPGA 3.2.6. Running the Project on Nios II Hardware 3.2.7. Debugging the Project on Nios II Hardware 3.2.8. Creating a Simple BSP
3.2.1. The Nios II SBT for Eclipse Workbench x
3.2.1.1. Perspectives, Editors, and Views 3.2.1.2. The Intel FPGA Bytestream Console
3.2.2. Creating a Project x
3.2.2.1. Specifying the Application 3.2.2.2. Specifying the BSP 3.2.2.3. Creating the Projects
3.2.2.1. Specifying the Application x
3.2.2.1.1. Specifying the Hardware Platform 3.2.2.1.2. Specifying the Project Name 3.2.2.1.3. Specifying the Project Template 3.2.2.1.4. Specifying the Project Location 3.2.2.1.5. Specifying the Processor
3.2.2.2. Specifying the BSP x
3.2.2.2.1. Specifying the BSP Project Name 3.2.2.2.2. Specifying the BSP Project Location 3.2.2.2.3. Selecting an Existing BSP
3.2.7. Debugging the Project on Nios II Hardware x
3.2.7.1. List of Debugging Tasks with the Nios II SBT for Eclipse 3.2.7.2. Using the Intel FPGA Bytestream Console 3.2.7.3. Run Time Stack Checking And Exception Debugging
3.2.7.1. List of Debugging Tasks with the Nios II SBT for Eclipse x
3.2.7.1.1. Console View 3.2.7.1.2. Disconnecting the Terminal from the Target
3.2.7.3. Run Time Stack Checking And Exception Debugging x
3.2.7.3.1. Nios® II Exception Debugging 3.2.7.3.2. Stack Overflow
3.3. Makefiles and the Nios® II SBT for Eclipse x
3.3.1. Eclipse Source Management 3.3.2. User Source Management 3.3.3. BSP Source Management
3.3.1. Eclipse Source Management x
3.3.1.1. Modifying a Makefile with Eclipse Source Management 3.3.1.2. Absolute Source Paths and Linked Resources
3.3.2. User Source Management x
3.3.2.1. Modifying a Makefile with User Source Management
3.4. Using the BSP Editor x
3.4.1. Tcl Scripting and the Nios® II BSP Editor 3.4.2. Starting the Nios® II BSP Editor 3.4.3. The Nios® II BSP Editor Screen Layout 3.4.4. The Command Area 3.4.5. Messages Tabs 3.4.6. Exporting a Tcl Script 3.4.7. Creating a New BSP 3.4.8. BSP Validation Errors
3.4.4. The Command Area x
3.4.4.1. Main Tab 3.4.4.2. BSP Software Packages Tab 3.4.4.3. BSP Drivers Tab 3.4.4.4. BSP Linker Script Tab 3.4.4.5. BSP Enable File Generation Tab 3.4.4.6. BSP Target Directory Tab
3.4.4.4. BSP Linker Script Tab x
3.4.4.4.1. Linker Section Mappings 3.4.4.4.2. Linker Regions
3.4.5. Messages Tabs x
3.4.5.1. The Information Tab 3.4.5.2. The Problems Tab 3.4.5.3. The Processing Tab
3.4.7. Creating a New BSP x
3.4.7.1. Using a Tcl Script in BSP Creation
3.5. Run Configurations in the SBT for Eclipse x
3.5.1. Opening the Run Configuration Dialog Box 3.5.2. The Project Tab 3.5.3. The Target Connection Tab 3.5.4. The Debugger Tab
3.7. Importing a Command-Line Project x
3.7.1. Nios II Command-Line Projects 3.7.2. Importing through the Import Wizard 3.7.3. Road Map 3.7.4. Import a Command-Line C/C++ Application 3.7.5. Import a Supporting Project 3.7.6. User-Managed Source Files
3.7.4. Import a Command-Line C/C++ Application x
3.7.4.1. Importing a Project with Absolute Source Paths
3.8. Packaging a Library for Reuse x
3.8.1. Creating the User Library 3.8.2. Using the Library
3.10. Programming Flash in Intel FPGA Embedded Systems x
3.10.1. Starting the Flash Programmer 3.10.2. Creating a Flash Programmer Settings File 3.10.3. The Flash Programmer Screen Layout 3.10.4. The Command Area 3.10.5. The Console Area 3.10.6. Saving a Flash Programmer Settings File 3.10.7. Flash Programmer Options
3.10.2. Creating a Flash Programmer Settings File x
3.10.2.1. Specifying the Hardware Configuration
3.10.5. The Console Area x
3.10.5.1. The Information Tab 3.10.5.2. The Problems Tab 3.10.5.3. The Processing Tab
3.10.7. Flash Programmer Options x
3.10.7.1. Staging Directories 3.10.7.2. Generate Files 3.10.7.3. Program Files 3.10.7.4. Erase Flash Before Programming 3.10.7.5. Run From Reset After Programming
3.11. Creating Memory Initialization Files x
3.11.1. Generate Memory Initialization Files 3.11.2. Generate Memory Initialization Files by the Legacy Method 3.11.3. Memory Initialization Files for User-Defined Memories
3.11.3. Memory Initialization Files for User-Defined Memories x
3.11.3.1. Specifying the Memory Device Information in the Advanced Tab
3.12. Running a Nios® II System with ModelSim x
3.12.1. Using ModelSim with a Platform Designer-Generated System
3.12.1. Using ModelSim with a Platform Designer-Generated System x
3.12.1.1. Preparing your Software for ModelSim 3.12.1.2. Potential Error Message 3.12.1.3. Nios® II GCC Tool Chain
3.13. Eclipse Usage Notes x
3.13.1. Configuring Application and Library Properties 3.13.2. Configuring BSP Properties 3.13.3. Exclude from Build Not Supported 3.13.4. Selecting the Correct Launch Configuration Type 3.13.5. Target Connection Options 3.13.6. Renaming Nios® II Projects 3.13.7. Running Shell Scripts from the SBT for Eclipse 3.13.8. Must Use Nios® II Build Configuration 3.13.9. CDT Limitations 3.13.10. Enhancements for Build Configurations in SBT and SBT for Eclipse
3.13.1. Configuring Application and Library Properties x
3.13.1.1. Comparing the Nios® II Application Properties and Nios® II Library Properties tabs
3.13.10. Enhancements for Build Configurations in SBT and SBT for Eclipse x
3.13.10.1. Build Configurations in SBT 3.13.10.2. Build Configurations in SBT for Eclipse
4. Getting Started from the Command Line x
4.1. Advantages of Command-Line Software Development 4.2. Outline of the Nios® II SBT Command-Line Interface 4.3. Getting Started in the SBT Command Line 4.4. Software Build Tools Scripting Basics 4.5. Running make
4.2. Outline of the Nios® II SBT Command-Line Interface x
4.2.1. Utilities 4.2.2. Scripts 4.2.3. Tcl Commands 4.2.4. Tcl Scripts 4.2.5. The Nios® II Command Shell
4.2.2. Scripts x
4.2.2.1. nios2-bsp 4.2.2.2. create-this-app 4.2.2.3. create-this-bsp
4.2.5. The Nios® II Command Shell x
4.2.5.1. Starting the Nios II Command Shell 4.2.5.2. Auto-Executing a Command in the Nios II Command Shell
4.3. Getting Started in the SBT Command Line x
4.3.1. Prerequisites 4.3.2. Creating Hello_World for an Intel FPGA Development Board 4.3.3. Running Hello_World on an Intel FPGA Development Board 4.3.4. Debugging hello_world
4.3.4. Debugging hello_world x
4.3.4.1. Import the hello_world Application 4.3.4.2. Download Executable Code and Start the Debugger
4.4. Software Build Tools Scripting Basics x
4.4.1. Creating a BSP with a Script 4.4.2. Creating an Application Project with a Script
4.5. Running make x
4.5.1. Creating Memory Initialization Files
5. Nios® II Software Build Tools x
5.1. Road Map for the SBT 5.2. Makefiles 5.3. Nios® II Embedded Software Projects 5.4. Common BSP Tasks 5.5. Details of BSP Creation 5.6. Tcl Scripts for BSP Settings 5.7. Revising Your BSP 5.8. Specifying BSP Defaults 5.9. Device Drivers and Software Packages 5.10. Boot Configurations for Intel FPGA Embedded Software 5.11. Intel FPGA-Provided Embedded Development Tools 5.12. Restrictions
5.1. Road Map for the SBT x
5.1.1. What the Build Tools Create 5.1.2. Comparing the Command Line with Eclipse
5.2. Makefiles x
5.2.1. Modifying Makefiles 5.2.2. Makefile Targets
5.3. Nios® II Embedded Software Projects x
5.3.1. Applications and Libraries 5.3.2. Board Support Packages 5.3.3. Software Build Process
5.3.1. Applications and Libraries x
5.3.1.1. Supported Source File Types
5.3.2. Board Support Packages x
5.3.2.1. Overview of BSP Creation 5.3.2.2. Parts of a Nios® II BSP
5.3.2.2. Parts of a Nios® II BSP x
5.3.2.2.1. Hardware Abstraction Layer 5.3.2.2.2. newlib C Standard Library 5.3.2.2.3. Device Drivers 5.3.2.2.4. Optional Software Packages 5.3.2.2.5. Optional Real-Time Operating System
5.4. Common BSP Tasks x
5.4.1. Adding the Nios® II SBT to Your Tool Flow 5.4.2. Linking and Locating 5.4.3. Other BSP Tasks
5.4.1. Adding the Nios® II SBT to Your Tool Flow x
5.4.1.1. Using Version Control 5.4.1.2. Copying, Moving, or Renaming a BSP 5.4.1.3. Handing Off a BSP
5.4.1.1. Using Version Control x
5.4.1.1.1. Creating BSP by Running a User Defined Script to Call nios2-bsp 5.4.1.1.2. Creating BSP by Manually Running nios2-bsp 5.4.1.1.3. Creating BSP before Running Make 5.4.1.1.4. Creating a Script that Uses the Command-Line Tools
5.4.2. Linking and Locating x
5.4.2.1. Creating Memory Initialization Files 5.4.2.2. Modifying Linker Memory Regions 5.4.2.3. Creating a Custom Linker Section 5.4.2.4. Changing the Default Linker Memory Region 5.4.2.5. Changing a Linker Section Mapping
5.4.2.3. Creating a Custom Linker Section x
5.4.2.3.1. Creating a Linker Section for an Existing Region 5.4.2.3.2. Dividing a Linker Region to Create a New Region and Section 5.4.2.3.3. Excerpts from Object Dump Files 5.4.2.3.4. Excerpt from Linker.x
5.4.3. Other BSP Tasks x
5.4.3.1. Creating a BSP for an Intel FPGA Development Board 5.4.3.2. Querying Settings 5.4.3.3. Managing Device Drivers 5.4.3.4. Creating a Custom Version of newlib 5.4.3.5. Controlling the stdio Device 5.4.3.6. Configuring Optimization and Debugger Options
5.4.3.6. Configuring Optimization and Debugger Options x
5.4.3.6.1. Configuring a BSP for Debugging
5.5. Details of BSP Creation x
5.5.1. BSP Settings File Creation 5.5.2. Generated and Copied Files 5.5.3. HAL BSP Files and Folders 5.5.4. Linker Map Validation
5.5.3. HAL BSP Files and Folders x
5.5.3.1. HAL BSP After Generating Files 5.5.3.2. Copied BSP Files 5.5.3.3. HAL BSP After Build
5.6. Tcl Scripts for BSP Settings x
5.6.1. Calling a Custom BSP Tcl Script
5.6.1. Calling a Custom BSP Tcl Script x
5.6.1.1. Simple Tcl Script 5.6.1.2. Tcl Script to Examine Hardware and Choose Settings
5.7. Revising Your BSP x
5.7.1. Rebuilding Your BSP 5.7.2. Regenerating Your BSP 5.7.3. Updating Your BSP 5.7.4. Recreating Your BSP
5.7.1. Rebuilding Your BSP x
5.7.1.1. What Happens 5.7.1.2. How to Rebuild Your BSP
5.7.2. Regenerating Your BSP x
5.7.2.1. What Happens 5.7.2.2. When to Regenerate Your BSP 5.7.2.3. How to Regenerate Your BSP
5.7.2.3. How to Regenerate Your BSP x
5.7.2.3.1. Regenerating Your BSP in Eclipse 5.7.2.3.2. Regenerating Your BSP from the Command Line
5.7.3. Updating Your BSP x
5.7.3.1. What Happens 5.7.3.2. When to Update Your BSP 5.7.3.3. How to Update Your BSP
5.7.4. Recreating Your BSP x
5.7.4.1. What Happens 5.7.4.2. When to Recreate Your BSP 5.7.4.3. How to Recreate Your BSP
5.7.4.3. How to Recreate Your BSP x
5.7.4.3.1. Using Tcl Scripts When Recreating Your BSP 5.7.4.3.2. Recreating Your BSP in Eclipse 5.7.4.3.3. Recreating Your BSP at the Command Line
5.8. Specifying BSP Defaults x
5.8.1. Top Level Tcl Script for BSP Defaults 5.8.2. Specifying the Default stdio Device 5.8.3. Specifying the Default System Timer 5.8.4. Specifying the Default Memory Map 5.8.5. Specifying Default Bootloader Parameters 5.8.6. Using Individual Default Tcl Procedures
5.8.5. Specifying Default Bootloader Parameters x
5.8.5.1. Boot Loader Dependent Settings
5.10. Boot Configurations for Intel FPGA Embedded Software x
5.10.1. Memory Types 5.10.2. Boot from Flash Configuration 5.10.3. Boot from Monitor Configuration 5.10.4. Run from Initialized Memory Configuration 5.10.5. Run-time Configurable Reset Configuration
5.11. Intel FPGA-Provided Embedded Development Tools x
5.11.1. Nios® II Software Build Tool GUIs 5.11.2. The Nios® II Command Shell 5.11.3. The Nios® II Command-Line Commands
5.11.1. Nios® II Software Build Tool GUIs x
5.11.1.1. The Nios® II SBT for Eclipse 5.11.1.2. The Nios® II BSP Editor 5.11.1.3. The Nios® II Flash Programmer
5.11.3. The Nios® II Command-Line Commands x
5.11.3.1. GNU Compiler Tool Chain 5.11.3.2. Nios® II Software Build Tools 5.11.3.3. File Format Conversion Tools 5.11.3.4. Other Command-Line Tools
5.11.3.3. File Format Conversion Tools x
5.11.3.3.1. alt-file-convert (BETA) 5.11.3.3.2. bin2flash 5.11.3.3.3. elf2dat 5.11.3.3.4. elf2flash 5.11.3.3.5. elf2hex 5.11.3.3.6. elf2mif 5.11.3.3.7. flash2dat 5.11.3.3.8. sof2flash
5.11.3.4. Other Command-Line Tools x
5.11.3.4.1. nios2-download 5.11.3.4.2. nios2-flash-programmer-generate 5.11.3.4.3. nios2-flash-programmer (64-bit support) 5.11.3.4.4. nios2-gdb-server (64-bit support) 5.11.3.4.5. nios2-terminal (64-bit support) 5.11.3.4.6. validate_zip 5.11.3.4.7. nios2-configure-sof 5.11.3.4.8. jtagconfig
6. Overview of the Hardware Abstraction Layer x
6.1. Getting Started with the Hardware Abstraction Layer 6.2. HAL Architecture for Embedded Software Systems 6.3. Embedded Hardware Supported by the HAL
6.2. HAL Architecture for Embedded Software Systems x
6.2.1. Services 6.2.2. Layers of a HAL-Based System 6.2.3. Applications versus Drivers 6.2.4. Generic Device Models 6.2.5. C Standard Library—newlib
6.2.4. Generic Device Models x
6.2.4.1. Device Model Classes 6.2.4.2. Benefits to Application Developers 6.2.4.3. Benefits to Device Driver Developers
6.3. Embedded Hardware Supported by the HAL x
6.3.1. Nios® II Processor Core Support 6.3.2. Supported Peripherals 6.3.3. MPU Support 6.3.4. MMU Support
6.3.2. Supported Peripherals x
6.3.2.1. Provide Full HAL Support 6.3.2.2. Provide Partial HAL Support
7. Developing Programs Using the Hardware Abstraction Layer x
7.1. HAL BSP Settings 7.2. The Nios® II Embedded Project Structure 7.3. The system.h System Description File 7.4. Data Widths and the HAL Type Definitions 7.5. UNIX-Style Interface 7.6. File System 7.7. Using Character-Mode Devices 7.8. Using File Subsystems 7.9. Using Timer Devices 7.10. Using Flash Devices 7.11. Using DMA Devices 7.12. Using Interrupt Controllers 7.13. Reducing Code Footprint in Embedded Systems 7.14. Boot Sequence and Entry Point 7.15. Memory Usage 7.16. Working with HAL Source Files
7.7. Using Character-Mode Devices x
7.7.1. Standard Input, Standard Output and Standard Error 7.7.2. General Access to Character Mode Devices 7.7.3. C++ Streams 7.7.4. /dev/null 7.7.5. Lightweight Character-Mode I/O 7.7.6. Intel FPGA Logging Functions
7.7.6. Intel FPGA Logging Functions x
7.7.6.1. Enabling Logging 7.7.6.2. Extra Logging Options 7.7.6.3. Logging Levels 7.7.6.4. Example: Creating a BSP with Logging 7.7.6.5. Custom Logging Messages 7.7.6.6. Intel FPGA Logging Files
7.8. Using File Subsystems x
7.8.1. Host-Based File System
7.9. Using Timer Devices x
7.9.1. System Clock Driver 7.9.2. Alarms 7.9.3. Timestamp Driver
7.10. Using Flash Devices x
7.10.1. Simple Flash Access 7.10.2. Block Erasure or Corruption 7.10.3. Fine-Grained Flash Access
7.10.3. Fine-Grained Flash Access x
7.10.3.1. alt_get_flash_info() 7.10.3.2. alt_erase_flash() 7.10.3.3. alt_write_flash_block() 7.10.3.4. alt_lock_flash()
7.11. Using DMA Devices x
7.11.1. DMA Transmit Channels 7.11.2. DMA Receive Channels
7.11.2. DMA Receive Channels x
7.11.2.1. Memory-to-Memory DMA Transactions
7.13. Reducing Code Footprint in Embedded Systems x
7.13.1. Enable Compiler Optimizations 7.13.2. Use Reduced Device Drivers 7.13.3. Reduce the File Descriptor Pool 7.13.4. Use /dev/null 7.13.5. Use a Smaller File I/O Library 7.13.6. Use the Lightweight Device Driver API 7.13.7. Use the Minimal Character-Mode API 7.13.8. Eliminate Unused Device Drivers 7.13.9. Eliminate Unneeded Exit Code 7.13.10. Turn off C++ Support
7.13.5. Use a Smaller File I/O Library x
7.13.5.1. Definition of 'asnprintf()' v*printf (mnemonic: v-for-varargs) *s*printf (mnemonic: prints to string buffer) *i*printf (mnemonic: 'i' for 'integer-only) 7.13.5.2. Use the Small newlib C Library 7.13.5.3. Use UNIX-Style File I/O 7.13.5.4. Emulate ANSI C Functions
7.13.7. Use the Minimal Character-Mode API x
7.13.7.1. alt_printf() 7.13.7.2. alt_putchar() 7.13.7.3. alt_putstr() 7.13.7.4. alt_getchar()
7.13.9. Eliminate Unneeded Exit Code x
7.13.9.1. Eliminate Clean Exit 7.13.9.2. Eliminate All Exit Code
7.14. Boot Sequence and Entry Point x
7.14.1. Hosted Versus Free-Standing Applications 7.14.2. Boot Sequence for HAL-Based Programs 7.14.3. Customizing the Boot Sequence
7.14.2. Boot Sequence for HAL-Based Programs x
7.14.2.1. System Initialization Code Boot Sequence 7.14.2.2. Default Implementation Steps
7.15. Memory Usage x
7.15.1. Memory Sections 7.15.2. Assigning Code and Data to Memory Partitions 7.15.3. Placement of the Heap and Stack 7.15.4. Global Pointer Register 7.15.5. Boot Modes
7.15.2. Assigning Code and Data to Memory Partitions x
7.15.2.1. Simple Placement Options 7.15.2.2. Advanced Placement Options
7.16. Working with HAL Source Files x
7.16.1. Finding HAL Files 7.16.2. Overriding HAL Functions
8. Developing Device Drivers for the Hardware Abstraction Layer x
8.1. Driver Integration in the HAL API 8.2. The HAL Peripheral-Specific API 8.3. Preparing for HAL Driver Development 8.4. Development Flow for Creating Device Drivers 8.5. Nios® II Hardware Design Concepts 8.6. Accessing Hardware 8.7. Creating Embedded Drivers for HAL Device Classes 8.8. Integrating a Device Driver in the HAL 8.9. Creating a Custom Device Driver for the HAL 8.10. Reducing Code Footprint in HAL Embedded Drivers 8.11. HAL Namespace Allocation 8.12. Overriding the HAL Default Device Drivers
8.5. Nios® II Hardware Design Concepts x
8.5.1. The Relationship Between the .sopcinfo File and system.h 8.5.2. Using the System Generation Tool to Optimize Hardware 8.5.3. Components, Devices, and Peripherals
8.7. Creating Embedded Drivers for HAL Device Classes x
8.7.1. Character-Mode Device Drivers 8.7.2. File Subsystem Drivers 8.7.3. Timer Device Drivers 8.7.4. Flash Device Drivers 8.7.5. DMA Device Drivers
8.7.1. Character-Mode Device Drivers x
8.7.1.1. Create a Device Instance 8.7.1.2. Register a Character Device
8.7.1.1. Create a Device Instance x
8.7.1.1.1. Modifying the Global Error Status, errno 8.7.1.1.2. Default Behavior for Functions Defined in alt_dev
8.7.2. File Subsystem Drivers x
8.7.2.1. Create a Device Instance 8.7.2.2. Register a File Subsystem Device
8.7.3. Timer Device Drivers x
8.7.3.1. System Clock Driver 8.7.3.2. Timestamp Driver
8.7.4. Flash Device Drivers x
8.7.4.1. Create a Flash Driver 8.7.4.2. Register a Flash Device
8.7.5. DMA Device Drivers x
8.7.5.1. DMA Transmit Channel 8.7.5.2. DMA Receive Channel
8.8. Integrating a Device Driver in the HAL x
8.8.1. Overview 8.8.2. Assumptions and Requirements 8.8.3. The Nios® II BSP Generator 8.8.4. File Names and Locations 8.8.5. Driver and Software Package Tcl Script Creation
8.8.3. The Nios® II BSP Generator x
8.8.3.1. Component Discovery 8.8.3.2. Device Driver Versions 8.8.3.3. Device Driver and Software Package Inclusion
8.8.3.3. Device Driver and Software Package Inclusion x
8.8.3.3.1. Specific Requests 8.8.3.3.2. No Specific Requests
8.8.4. File Names and Locations x
8.8.4.1. Source Code Discovery
8.8.5. Driver and Software Package Tcl Script Creation x
8.8.5.1. Example Device Driver File Hierarchy and Naming 8.8.5.2. Tcl Command Walkthrough for a Typical Driver or Software Package 8.8.5.3. Creating Settings for Device Drivers and Software Packages
8.8.5.2. Tcl Command Walkthrough for a Typical Driver or Software Package x
8.8.5.2.1. Creating and Naming the Driver or Package 8.8.5.2.2. Identifying the Hardware Component Class 8.8.5.2.3. Setting the BSP Type 8.8.5.2.4. Specifying an Operating System 8.8.5.2.5. Specifying Source Files 8.8.5.2.6. Specifying a Subdirectory 8.8.5.2.7. Enabling Software Initialization 8.8.5.2.8. Adding Include Paths 8.8.5.2.9. Version Compatibility
8.8.5.3. Creating Settings for Device Drivers and Software Packages x
8.8.5.3.1. How Settings Affect the Generated BSP 8.8.5.3.2. Data Types 8.8.5.3.3. Setting Destination Files 8.8.5.3.4. Setting Display Name 8.8.5.3.5. Setting Generation Name 8.8.5.3.6. Setting Default Value 8.8.5.3.7. Setting Description 8.8.5.3.8. Setting Creation Example
8.9. Creating a Custom Device Driver for the HAL x
8.9.1. Header Files and alt_sys_init.c 8.9.2. Device Driver Source Code
8.9.1. Header Files and alt_sys_init.c x
8.9.1.1. Creating alt_sys_init.c Based on Associated Header Files 8.9.1.2. altera_avalon_jtag_uart.h Defining Macros
8.10. Reducing Code Footprint in HAL Embedded Drivers x
8.10.1. Provide Reduced Footprint Drivers 8.10.2. Support the Lightweight Device Driver API
8.10.2. Support the Lightweight Device Driver API x
8.10.2.1. Using Character-Mode Functions 8.10.2.2. Using Macros 8.10.2.3. Invoking Macros in Your Application Software 8.10.2.4. Calling Direct Without Macros
9. Exception Handling x
9.1. Nios® II Exception Handling Overview 9.2. Nios® II Interrupt Service Routines 9.3. Improving Nios® II ISR Performance 9.4. Debugging Nios® II ISRs 9.5. HAL Exception Handling System Implementation 9.6. The Nios® II Instruction-Related Exception Handler
9.1. Nios® II Exception Handling Overview x
9.1.1. Exception Handling Terminology 9.1.2. Interrupt Controllers 9.1.3. Latency and Response Time
9.1.2. Interrupt Controllers x
9.1.2.1. Internal Interrupt Concepts 9.1.2.2. External Interrupt Concepts
9.1.2.2. External Interrupt Concepts x
9.1.2.2.1. Requested Handler Address 9.1.2.2.2. Requested Interrupt Level 9.1.2.2.3. Requested Register Set 9.1.2.2.4. Requested NMI Mode 9.1.2.2.5. Shadow Register Sets
9.1.3. Latency and Response Time x
9.1.3.1. Internal or External Interrupt Controller 9.1.3.2. Shadow Register Sets 9.1.3.3. How the Internal Interrupt Controller Works 9.1.3.4. How an External Interrupt Controller Works
9.1.3.2. Shadow Register Sets x
9.1.3.2.1. How the Hardware Works
9.2. Nios® II Interrupt Service Routines x
9.2.1. HAL APIs for Hardware Interrupts 9.2.2. HAL ISR Restrictions 9.2.3. Writing an ISR 9.2.4. Registering an ISR with the Enhanced Interrupt API 9.2.5. Enabling and Disabling Interrupts 9.2.6. Configuring an External Interrupt Controller 9.2.7. C Example 9.2.8. Upgrading to the Enhanced HAL Interrupt API
9.2.1. HAL APIs for Hardware Interrupts x
9.2.1.1. Selecting an Interrupt API 9.2.1.2. The Enhanced HAL Interrupt API 9.2.1.3. Using the Enhanced HAL Interrupt API to Implement ISRs 9.2.1.4. The Legacy HAL Interrupt API 9.2.1.5. Supporting Multiple Interrupt APIs
9.2.1.3. Using the Enhanced HAL Interrupt API to Implement ISRs x
9.2.1.3.1. The External Interrupt Controller Driver 9.2.1.3.2. Using the HAL Interrupt API with the VIC
9.2.1.4. The Legacy HAL Interrupt API x
9.2.1.4.1. Using the Legacy HAL API to Implement ISRs
9.2.3. Writing an ISR x
9.2.3.1. Using Interrupt Funnels 9.2.3.2. Running in a Restricted Environment 9.2.3.3. Managing Pre-Emption
9.2.4. Registering an ISR with the Enhanced Interrupt API x
9.2.4.1. Methods the HAL Uses to Register the ISR
9.2.7. C Example x
9.2.7.1. An ISR to Service a Button PIO Interrupt 9.2.7.2. Registering the Button PIO ISR with the HAL
9.3. Improving Nios® II ISR Performance x
9.3.1. Software Performance Improvements 9.3.2. Hardware Performance Improvements
9.3.1. Software Performance Improvements x
9.3.1.1. Execute Time-Intensive Algorithms in the Application Context 9.3.1.2. Implement Time-Intensive Algorithms in Hardware 9.3.1.3. Increase Buffer Size 9.3.1.4. Use Double Buffering 9.3.1.5. Keep Interrupts Enabled 9.3.1.6. Use Fast Memory 9.3.1.7. Use a Separate Exception Stack 9.3.1.8. Use Nested Hardware Interrupts 9.3.1.9. Locate ISR Body in Vector Table 9.3.1.10. Use Compiler Optimization
9.3.1.7. Use a Separate Exception Stack x
9.3.1.7.1. Separate General Exception Stack 9.3.1.7.2. Separate Hardware Interrupt Stack
9.3.1.8. Use Nested Hardware Interrupts x
9.3.1.8.1. Nested Hardware Interrupts with the Internal Interrupt Controller 9.3.1.8.2. Nested Hardware Interrupts with an External Interrupt Controller
9.3.2. Hardware Performance Improvements x
9.3.2.1. Use Vectored Hardware Interrupts 9.3.2.2. Add Fast Memory 9.3.2.3. Add a DMA Controller 9.3.2.4. Place the Handler in Fast Memory 9.3.2.5. Use a Fast Nios® II Core 9.3.2.6. Select Hardware Interrupt Priorities
9.3.2.1. Use Vectored Hardware Interrupts x
9.3.2.1.1. Using the Interrupt Vector Custom Instruction 9.3.2.1.2. Using an External Interrupt Controller
9.3.2.6. Select Hardware Interrupt Priorities x
9.3.2.6.1. Hardware Interrupt Priorities with the Internal Interrupt Controller 9.3.2.6.2. Hardware Interrupt Priorities with an External Interrupt Controller
9.5. HAL Exception Handling System Implementation x
9.5.1. Exception Handling System Structure 9.5.2. General Exception Funnel 9.5.3. Hardware Interrupt Funnel 9.5.4. Software Exception Funnel 9.5.5. Invalid Instructions
9.5.2. General Exception Funnel x
9.5.2.1. Hardware Interrupt Dispatch with the Internal Interrupt Controller 9.5.2.2. Returning from Exceptions
9.5.3. Hardware Interrupt Funnel x
9.5.3.1. Interrupt Funnel for the Internal Interrupt Controller 9.5.3.2. Interrupt Funnels for External Interrupt Controllers 9.5.3.3. Interrupt Funnels for Internal Interrupt Controllers
9.5.4. Software Exception Funnel x
9.5.4.1. Unimplemented Instructions 9.5.4.2. Instruction-Related Exceptions 9.5.4.3. Software Trap Handling 9.5.4.4. Miscellaneous Exceptions
9.5.4.1. Unimplemented Instructions x
9.5.4.1.1. When to Use the Unimplemented Instruction Handler 9.5.4.1.2. Using the Unimplemented Instruction Handler
9.6. The Nios® II Instruction-Related Exception Handler x
9.6.1. Writing an Instruction-Related Exception Handler 9.6.2. Registering an Instruction-Related Exception Handler 9.6.3. Removing an Instruction-Related Exception Handler
9.6.1. Writing an Instruction-Related Exception Handler x
9.6.1.1. Exception Cause Codes
10. Cache and Tightly-Coupled Memory x
10.1. Nios® II Cache Implementation 10.2. HAL API Functions for Managing Cache 10.3. Initializing the Nios® II Cache after Reset 10.4. Nios® II Device Driver Cache Considerations 10.5. Cache Considerations for Writing Program Loaders 10.6. Managing Cache in Multi-Master and Multi-Processor Systems 10.7. Nios® II Tightly-Coupled Memory
10.1. Nios® II Cache Implementation x
10.1.1. Defining Cache Properties
10.3. Initializing the Nios® II Cache after Reset x
10.3.1. Assembly Code to Initialize the Instruction Cache 10.3.2. Assembly Code to Initialize the Data Cache 10.3.3. HAL Behavior for Initializing the Nios® II Cache after Reset
10.4. Nios® II Device Driver Cache Considerations x
10.4.1. HAL Behavior for Nios® II Device Driver Cache Considerations
10.5. Cache Considerations for Writing Program Loaders x
10.5.1. HAL Behavior for Cache Considerations for Writing Program Loaders
10.6. Managing Cache in Multi-Master and Multi-Processor Systems x
10.6.1. Cache Implementation 10.6.2. Bit-31 Cache Bypass 10.6.3. HAL Behavior for Managing Cache in Multi-Master and Multi-Processor Systems
11. MicroC/OS-II Real-Time Operating System x
11.1. Overview of the MicroC/OS-II RTOS 11.2. Other RTOS Providers 11.3. The Nios II Implementation of MicroC/OS-II 11.4. Implementing MicroC/OS-II Projects for the Nios® II Processor
11.1. Overview of the MicroC/OS-II RTOS x
11.1.1. Licensing
11.3. The Nios II Implementation of MicroC/OS-II x
11.3.1. MicroC/OS-II Architecture 11.3.2. MicroC/OS-II Device Drivers 11.3.3. Thread-Safe HAL Drivers 11.3.4. The newlib ANSI C Standard Library 11.3.5. Interrupt Service Routines for MicroC/OS-II
13. Read-Only Zip File System x
13.1. Using the Read-Only Zip File System in a Project
13.1. Using the Read-Only Zip File System in a Project x
13.1.1. Preparing the Zip File 13.1.2. Programming the Zip File to Flash
14. Publishing Component Information to Embedded Software x
14.1. Embedded Component Information Flow 14.2. Embedded Software Assignments
14.1. Embedded Component Information Flow x
14.1.1. Embedded Component Information Flow Diagram 14.1.2. Tcl Assignment Statements
14.2. Embedded Software Assignments x
14.2.1. C Macro Namespace 14.2.2. Configuration Namespace 14.2.3. Memory Initialization Namespace
14.2.1. C Macro Namespace x
14.2.1.1. Generated Macro in system.h 14.2.1.2. GCC C/C++ 32-bit Processor Constants
14.2.2. Configuration Namespace x
14.2.2.1. Configuration Data Types 14.2.2.2. Component Configuration Information 14.2.2.3. Memory-Mapped Slave Information 14.2.2.4. Streaming Source Information 14.2.2.5. Streaming Sink Information
15. HAL API Reference x
15.1. HAL API Functions 15.2. HAL Standard Types 15.3. ADC HAL Device Driver
15.1. HAL API Functions x
15.1.1. _exit() 15.1.2. _rename() 15.1.3. alt_dcache_flush() 15.1.4. alt_dcache_flush_all() 15.1.5. alt_dcache_flush_no_writeback() 15.1.6. alt_uncached_malloc() 15.1.7. alt_uncached_free() 15.1.8. alt_remap_uncached() 15.1.9. alt_remap_cached() 15.1.10. alt_icache_flush_all() 15.1.11. alt_icache_flush() 15.1.12. alt_alarm_start() 15.1.13. alt_alarm_stop() 15.1.14. alt_dma_rxchan_depth() 15.1.15. alt_dma_rxchan_close() 15.1.16. alt_dev_reg() 15.1.17. alt_dma_rxchan_open() 15.1.18. alt_dma_rxchan_prepare() 15.1.19. alt_dma_rxchan_reg() 15.1.20. alt_dma_txchan_close() 15.1.21. alt_dma_txchan_ioctl() 15.1.22. alt_dma_txchan_open() 15.1.23. alt_dma_txchan_reg() 15.1.24. alt_flash_close_dev() 15.1.25. alt_exception_cause_generated_bad_addr() 15.1.26. alt_erase_flash_block() 15.1.27. alt_dma_rxchan_ioctl() 15.1.28. alt_dma_txchan_space() 15.1.29. alt_dma_txchan_send() 15.1.30. alt_flash_open_dev() 15.1.31. alt_fs_reg() 15.1.32. alt_get_flash_info() 15.1.33. alt_ic_irq_disable() 15.1.34. alt_ic_irq_enabled() 15.1.35. alt_ic_isr_register() 15.1.36. alt_ic_irq_enable() 15.1.37. alt_instruction_exception_register() 15.1.38. alt_irq_disable() 15.1.39. alt_irq_cpu_enable_interrupts () 15.1.40. alt_irq_disable_all() 15.1.41. alt_irq_enable() 15.1.42. alt_irq_enable_all() 15.1.43. alt_irq_enabled() 15.1.44. alt_irq_init() 15.1.45. alt_irq_pending () 15.1.46. alt_irq_register() 15.1.47. alt_llist_insert() 15.1.48. alt_llist_remove() 15.1.49. alt_load_section() 15.1.50. alt_nticks() 15.1.51. alt_read_flash() 15.1.52. alt_tick() 15.1.53. alt_ticks_per_second() 15.1.54. alt_timestamp() 15.1.55. alt_timestamp_freq() 15.1.56. alt_timestamp_start() 15.1.57. alt_write_flash() 15.1.58. alt_write_flash_block() 15.1.59. close() 15.1.60. fstat() 15.1.61. fork() 15.1.62. fcntl() 15.1.63. execve() 15.1.64. getpid() 15.1.65. kill() 15.1.66. stat() 15.1.67. settimeofday() 15.1.68. wait() 15.1.69. unlink() 15.1.70. sbrk() 15.1.71. link() 15.1.72. lseek() 15.1.73. alt_sysclk_init() 15.1.74. open() 15.1.75. times() 15.1.76. read() 15.1.77. write() 15.1.78. usleep() 15.1.79. alt_lock_flash() 15.1.80. gettimeofday() 15.1.81. ioctl() 15.1.82. isatty()
15.2. HAL Standard Types x
15.2.1. alt_getchar() 15.2.2. alt_putstr() 15.2.3. alt_putchar() 15.2.4. alt_printf()
15.3. ADC HAL Device Driver x
15.3.1. adc_stop 15.3.2. adc_start 15.3.3. adc_set_mode_run_once 15.3.4. adc_set_mode_run_continuously 15.3.5. adc_recalibrate 15.3.6. adc_interrupt_enable 15.3.7. adc_interrupt_disable 15.3.8. adc_clear_interrupt_status 15.3.9. adc_wait_for_interrupt - ADC Sample Storage Status Register 15.3.10. adc_interrupt_asserted 15.3.11. adc_wait_for interrupt - IRQ Status Register 15.3.12. alt_adc_word_read
16. Nios® II Software Build Tools Reference x
16.1. Nios® II Software Build Tools Utilities 16.2. Nios® II Design Example Scripts 16.3. Settings Managed by the Software Build Tools 16.4. Application and User Library Makefile Variables 16.5. Software Build Tools Tcl Commands 16.6. Software Build Tools Path Names
16.1. Nios® II Software Build Tools Utilities x
16.1.1. Logging Levels 16.1.2. Setting Values 16.1.3. Utility and Script Summary 16.1.4. nios2-app-generate-makefile 16.1.5. nios2-bsp-create-settings 16.1.6. nios2-bsp-generate-files 16.1.7. nios2-bsp-query-settings 16.1.8. nios2-bsp-update-settings 16.1.9. nios2-lib-generate-makefile 16.1.10. nios2-bsp-editor 16.1.11. nios2-app-update-makefile 16.1.12. nios2-lib-update-makefile 16.1.13. nios2-swexample-create 16.1.14. nios2-elf-insert 16.1.15. nios2-elf-query 16.1.16. nios2-flash-programmer-generate 16.1.17. nios2-bsp 16.1.18. nios2-bsp-console 16.1.19. alt-file-convert (BETA)
16.3. Settings Managed by the Software Build Tools x
16.3.1. Overview of BSP Settings 16.3.2. Overview of Component and Driver Settings 16.3.3. Settings Reference
16.3.2. Overview of Component and Driver Settings x
16.3.2.1. Intel FPGA Host-Based File System Settings 16.3.2.2. Intel FPGA Read-Only Zip File System Settings 16.3.2.3. Intel FPGA Avalon-MM JTAG UART Driver Settings 16.3.2.4. Intel FPGA Avalon-MM UART Driver Settings
16.4. Application and User Library Makefile Variables x
16.4.1. Application Makefile Variables 16.4.2. User Library Makefile Variables 16.4.3. Standard Build Flag Variables
16.5. Software Build Tools Tcl Commands x
16.5.1. Tcl Command Environments 16.5.2. Tcl Commands for BSP Settings 16.5.3. Tcl Commands for BSP Generation Callbacks 16.5.4. Tcl Commands for Drivers and Packages
16.5.2. Tcl Commands for BSP Settings x
16.5.2.1. add_memory_device 16.5.2.2. add_memory_region 16.5.2.3. add_section_mapping 16.5.2.4. are_same_resource 16.5.2.5. delete_memory_region 16.5.2.6. delete_section_mapping 16.5.2.7. disable_sw_package 16.5.2.8. enable_sw_package 16.5.2.9. get_addr_span 16.5.2.10. get_assignment 16.5.2.11. get_available_drivers 16.5.2.12. get_available_sw_packages 16.5.2.13. get_base_addr 16.5.2.14. get_break_offset 16.5.2.15. get_break_slave_desc 16.5.2.16. get_cpu_name 16.5.2.17. get_current_memory_regions 16.5.2.18. get_current_section_mappings 16.5.2.19. get_default_memory_regions 16.5.2.20. get_driver 16.5.2.21. get_enabled_sw_packages 16.5.2.22. get_exception_offset 16.5.2.23. get_exception_slave_desc 16.5.2.24. get_fast_tlb_miss_exception_offset 16.5.2.25. get_fast_tlb_miss_exception_slave_desc 16.5.2.26. get_interrupt_controller_id 16.5.2.27. get_irq_interrupt_controller_id 16.5.2.28. get_irq_number 16.5.2.29. get_memory_region 16.5.2.30. get_module_class_name 16.5.2.31. get_module_name 16.5.2.32. get_reset_offset 16.5.2.33. get_reset_slave_desc 16.5.2.34. get_section_mapping 16.5.2.35. get_setting 16.5.2.36. get_setting_desc 16.5.2.37. get_slave_descs 16.5.2.38. is_char_device 16.5.2.39. is_connected_interrupt_controller_device 16.5.2.40. is_connected_to_data_master 16.5.2.41. is_connected_to_instruction_master 16.5.2.42. is_ethernet_mac_device 16.5.2.43. is_flash 16.5.2.44. is_memory_device 16.5.2.45. is_non_volatile_storage 16.5.2.46. is_timer_device 16.5.2.47. log_debug 16.5.2.48. log_default 16.5.2.49. log_error 16.5.2.50. log_verbose 16.5.2.51. set_driver 16.5.2.52. set_ignore_file 16.5.2.53. set_setting 16.5.2.54. update_memory_region 16.5.2.55. update_section_mapping 16.5.2.56. add_default_memory_regions 16.5.2.57. create_bsp 16.5.2.58. generate_bsp 16.5.2.59. get_available_bsp_type_versions 16.5.2.60. get_available_bsp_types 16.5.2.61. get_available_cpu_architectures 16.5.2.62. get_available_cpu_names 16.5.2.63. get_available_software 16.5.2.64. get_available_software_setting_properties 16.5.2.65. get_available_software_settings 16.5.2.66. get_bsp_version 16.5.2.67. get_cpu_architecture 16.5.2.68. get_nios2_dpx_thread_num 16.5.2.69. get_sopcinfo_file 16.5.2.70. get_supported_bsp_types 16.5.2.71. is_bsp_hal_extension 16.5.2.72. is_bsp_lwhal_extension 16.5.2.73. open_bsp 16.5.2.74. save_bsp 16.5.2.75. set_bsp_version 16.5.2.76. set_logging_mode
16.5.3. Tcl Commands for BSP Generation Callbacks x
16.5.3.1. add_class_sw_setting 16.5.3.2. add_class_systemh_line 16.5.3.3. add_module_sw_property 16.5.3.4. add_module_sw_setting 16.5.3.5. add_module_systemh_line 16.5.3.6. add_systemh_line 16.5.3.7. get_class_peripheral 16.5.3.8. get_module_assignment 16.5.3.9. get_module_name 16.5.3.10. get_module_peripheral 16.5.3.11. get_module_sw_setting_value 16.5.3.12. get_peripheral_property 16.5.3.13. remove_class_systemh_line 16.5.3.14. remove_module_systemh_line 16.5.3.15. set_class_sw_setting_property 16.5.3.16. set_module_sw_setting_property
16.5.4. Tcl Commands for Drivers and Packages x
16.5.4.1. add_sw_property 16.5.4.2. add_sw_setting 16.5.4.3. add_sw_setting2 16.5.4.4. create_driver 16.5.4.5. create_os 16.5.4.6. create_sw_package 16.5.4.7. set_sw_property 16.5.4.8. set_sw_setting_property
16.6. Software Build Tools Path Names x
16.6.1. Command Arguments 16.6.2. Object File Directory Tree
Product Discontinuance Notification
1. Nios® II Software Developer's Handbook Revision History
2. Overview of Nios® II Embedded Development
3. Getting Started with the Graphical User Interface
4. Getting Started from the Command Line
5. Nios® II Software Build Tools
6. Overview of the Hardware Abstraction Layer
7. Developing Programs Using the Hardware Abstraction Layer
8. Developing Device Drivers for the Hardware Abstraction Layer
9. Exception Handling
10. Cache and Tightly-Coupled Memory
11. MicroC/OS-II Real-Time Operating System
12. Ethernet and the NicheStack TCP/IP Stack
13. Read-Only Zip File System
14. Publishing Component Information to Embedded Software
15. HAL API Reference
16. Nios® II Software Build Tools Reference
17. Nios® II Software Developer's Handbook Archives

7.13.5.1. Definition of 'asnprintf()'

newlib implements a maze of 22 printf() variants, all based on the same core engine, and all with slightly different interfaces. Some are specified by the C standard, some by Posix, some are GNU extensions, and some are newlib extensions. The newlib libc web page documents the functions that conform to their respective standards.

For more information about libc, refer to the "The Red Hat newlib C Libray" web page.

The 22 variants fill a four-dimensional space of design alternatives:
  • Plain vs varargs
  • File vs buffer output
  • Output buffer management alternatives:
    • Fixed buffer, unknow length
    • Fixed buffer, known length
    • malloc()ed-and-returned buffer
    • realloc()-able buffer
  • Plain vs no-floating-point formatting support

The map to the maze is the set of prefix chars.

v*printf (mnemonic: v-for-varargs)

The canonical printf() functions take a variable number of arguments including one for each percent-specifier in the format string. This is convenient for you, but inconvenient for wrapper functions taking a variable number of arguments and then doing some sort of value-added before invoking the regular printf() library, because C provides no convenient, portable way for a function to read a variable number of arguments and then pass them to another function taking a variable number of arguments. Consequently, for each plain printf() function, the C library provides a v*printf variant which accepts the extra arguments in varargs vector format.

The "plain" (variable number of arguments) printf functions are:
  • fprintf()
  • printf()
  • asprintf()
  • asnprintf()
  • snprintf()
  • sprintf()
  • fiprintf()
  • iprintf()
  • asiprintf()
  • asniprintf()
  • sniprintf()
  • siprintf()
The fixed-number-of-argument (vararg-based) variants are:
  • vprintf()
  • vasprintf()
  • vasnprintf()
  • vsprintf()
  • vsnprintf()
  • viprintf()
  • vasiprintf()
  • vasniprintf()
  • vsiprintf()
  • vsniprintf()

*s*printf (mnemonic: prints to string buffer)

The canonical printf() function prints to an output stream; the *s*printf functions instead print into a RAM buffer, allowing the buffered results to be further processed. The functions in this family are:
  • asprintf()
  • asnprintf()
  • snprintf()
  • sprintf()
  • vasprintf()
  • vasnprintf()
  • vsprintf()
  • vsnprintf()
  • asiprintf()
  • asniprintf()
  • sniprintf()
  • siprintf()
  • vasiprintf()
  • vasniprintf()
  • vsiprintf()
  • vsniprintf()
These functions differ in part in how the destination buffer is managed:
  • The original functions in this family, like sprintf took a buffer pointer as input and wrote into it. Since the length of the buffer was not given, these functions would frequently overrun the given buffer, resulting in reliability and security issues. The functions in this family are:
    • sprintf()
    • vsprintf()
    • siprintf()
    • vsiprintf()
  • *sn*printf (mnemonic: 'n' for number of bytes in buffer): variants attempted to deal with this problem by passing a buffer length as well as a buffer, allowing the function to avoid overrunning the buffer. This mitigates the security issues but results in incorrect output when the buffer is insufficient. The functions in this family are:
    • snprintf()
    • vsnprintf()
    • sniprintf()
    • vsniprintf()
  • *as*printf (mnemonic: 'a' for aallocate): variants deal with this problem by malloc()ing and returning the buffer holding the result string. It The caller must then free() the buffer.This avoids the security and reliability issues at the cost of significant added de/allocation overhead. The functions in this family are:
    • asprintf()
    • vasprintf()
    • asiprintf()
    • vasiprintf()
  • *asn*printf: variants try to reduce this overhead by taking a buffer and a limit and realloc()ing it only if the output won't fit in the provided buffer. The functions in this family are:
    • asnprintf()
    • vasnprintf()
    • asniprintf()
    • vasniprintf()

*i*printf (mnemonic: 'i' for 'integer-only)

The usual printf() functions support formatting of floating point numbers. Consequently they not only contain a fair amount of logic to do the actual formatting of floating point numbers, but can also link into the executable image such things as a floating point emulation library. If the application does not actually use floating point numbers, and if a small RAM footprint is desired, this can be very counterproductive. Consequently, newlib defines a parallel set of printf functions which lack floating-point formatting support.

The usual set of printf() functions is:
  • fprintf()
  • vprintf()
  • printf()
  • asprintf()
  • asnprintf()
  • snprintf()
  • sprintf()
  • vasprintf()
  • vasnprintf()
  • vsprintf()
  • vsnprintf()
The parallel set of no-floating-point formatting support printf functions is:
  • fiprintf()
  • iprintf()
  • viprintf()
  • asiprintf()
  • asniprintf()
  • sniprintf()
  • siprintf()
  • vasiprintf()
  • vasniprintf()
  • vsiprintf()
  • vsniprintf()
Note: Despite the mnemonic, these functions are not really integer-only: They also support (for example) unsigned, char and string values.
Lumping all the above variants together, the full list of printf() functions supported by newlib is:
  • fprintf()
  • vprintf()
  • printf()
  • asprintf()
  • asnprintf()
  • snprintf()
  • sprintf()
  • vasprintf()
  • vasnprintf()
  • vsprintf()
  • vsnprintf()
  • fiprintf()
  • iprintf()
  • viprintf()
  • asiprintf()
  • asniprintf()
  • sniprintf()
  • siprintf()
  • vasiprintf()
  • vasniprintf()
  • vsiprintf()
  • vsniprintf()
Additional printf variants supported by newlib libc (but not libsmallc!) are:
  • dprintf, vdprintf: Print to a file descriptor (vs FILE*).
  • diprintf, vdiprintf: No-floating-point-formatting versions of above.
  • fwprintf, swprintf, vfwprintf, vswprintf, vwprintf, wprintf: Versions with wide-char support.

For more information about these printf() variants, refer to the "The Red Hat newlib C Libray" web page.

Related Information
Level Two Title