Nios® V Processor Software Developer Handbook

Download PDF
ID 743810
Date 7/20/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
1. Overview of Nios® V Embedded Processor Development 2. Getting Started from the Command Line 3. Nios® V Processor Software Development and Implementation 4. Nios® V Processor Board Support Package Editor 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. MicroC/OS-II Real-Time Operating System 10. MicroC/TCP-IP Protocol Stack 11. FreeRTOS* Real-Time Operating System 12. Publishing Component Information to Embedded Software 13. Nios® V Processor Appendix A. Nios® V Processor Software Developer Handbook Archives 14. Revision History for Nios® V Processor Software Developer Handbook
1. Overview of Nios® V Embedded Processor Development x
1.1. Nios® V Processor Software Development Environment 1.2. Nios® V Processor Software Project Types 1.3. Nios® V Processor Development Tools 1.4. Nios® V Processor Software Programs
1.1. Nios® V Processor Software Development Environment x
1.1.1. Intel® Quartus® Prime Software Support
1.3. Nios® V Processor Development Tools x
1.3.1. Nios® V Processor Command Line Utilities Tools 1.3.2. Board Support Package Editor 1.3.3. Ashling* RiscFree* IDE for Intel® FPGAs
1.4. Nios® V Processor Software Programs x
1.4.1. CMakeLists.txt and Nios® V Processor Tools
2. Getting Started from the Command Line x
2.1. Advantages of Command Line Software Development 2.2. Outline of the Nios® V Processor Tools Command Line
2.2. Outline of the Nios® V Processor Tools Command Line x
2.2.1. Command Line Utilities
2.2.1. Command Line Utilities x
2.2.1.1. niosv-bsp 2.2.1.2. niosv-app 2.2.1.3. niosv-download
3. Nios® V Processor Software Development and Implementation x
3.1. Nios® V Processor Tools 3.2. Nios® V Processor Software File Tree 3.3. Nios® V Processor Software Development Flow 3.4. Developing with the Hardware Abstraction Layer
3.1. Nios® V Processor Tools x
3.1.1. Nios® V Processor Tools Overview 3.1.2. Nios® V Processor Software Build Tools
3.1.2. Nios® V Processor Software Build Tools x
3.1.2.1. Nios® V Processor Software Build Tools Graphical User Interface 3.1.2.2. Nios® V Processor Software Build Tools Command Line Interface 3.1.2.3. What the Build Tools Create
3.1.2.1. Nios® V Processor Software Build Tools Graphical User Interface x
3.1.2.1.1. BSP Editor 3.1.2.1.2. Ashling* RiscFree* IDE for Intel FPGAs 3.1.2.1.3. Nios V Command Shell
3.1.2.2. Nios® V Processor Software Build Tools Command Line Interface x
3.1.2.2.1. Nios® V Processor Command Line Utilities 3.1.2.2.2. File Format Conversion Tools 3.1.2.2.3. Other Utilities Tools
3.1.2.3. What the Build Tools Create x
3.1.2.3.1. Applications and Libraries 3.1.2.3.2. Board Support Packages 3.1.2.3.3. CMakeLists.txt
3.2. Nios® V Processor Software File Tree x
3.2.1. Building Single Application and Single BSP 3.2.2. Building Single Application, Single Library, and BSP 3.2.3. Building Multiple Applications and Single BSP 3.2.4. Building BSP Library
3.2.1. Building Single Application and Single BSP x
3.2.1.1. Build Commands 3.2.1.2. File Tree Directory
3.2.2. Building Single Application, Single Library, and BSP x
3.2.2.1. Build Commands 3.2.2.2. File Tree Directory
3.2.3. Building Multiple Applications and Single BSP x
3.2.3.1. Build Commands 3.2.3.2. File Tree Directory
3.2.4. Building BSP Library x
3.2.4.1. Build Commands 3.2.4.2. File Tree Directory
3.3. Nios® V Processor Software Development Flow x
3.3.1. Getting Started 3.3.2. Configuring BSP Projects 3.3.3. Configuring the Application Project 3.3.4. Building and Running Nios® V Processor Software
3.3.2. Configuring BSP Projects x
3.3.2.1. Selecting the Operating System 3.3.2.2. Intel HAL Configuration Tips 3.3.2.3. Micrium MicroC/OS-II Configuration tips 3.3.2.4. Configuring FreeRTOS* 3.3.2.5. Adding Software Package 3.3.2.6. Using Tcl Script with BSP Editor 3.3.2.7. Exporting Tcl Scripts with BSP Editor 3.3.2.8. Importing Tcl Script to Create a New BSP
3.3.3. Configuring the Application Project x
3.3.3.1. Application Configuration Tips 3.3.3.2. Linking User Libraries
3.3.4. Building and Running Nios® V Processor Software x
3.3.4.1. Building the Nios® V Processor Software 3.3.4.2. Downloading and Running the Nios® V Processor Software 3.3.4.3. Nios® V Processor Software Debugging 3.3.4.4. Run Time Stack Checking 3.3.4.5. Ensuring Software Project Coherency
3.3.4.2. Downloading and Running the Nios® V Processor Software x
3.3.4.2.1. Communicating with the Target Device
3.3.4.5. Ensuring Software Project Coherency x
3.3.4.5.1. Recommended Development Practice 3.3.4.5.2. Recommended Architecture Practice
3.4. Developing with the Hardware Abstraction Layer x
3.4.1. Hardware Abstraction Layer Services 3.4.2. System Startup in HAL-based Application 3.4.3. HAL Peripheral Services 3.4.4. Handling Exceptions
3.4.1. Hardware Abstraction Layer Services x
3.4.1.1. HAL Configuration Options 3.4.1.2. Configuring the Boot Environment
3.4.2. System Startup in HAL-based Application x
3.4.2.1. System Initialization 3.4.2.2. crt0 Initialization 3.4.2.3. HAL Initialization
3.4.3. HAL Peripheral Services x
3.4.3.1. Timer Devices 3.4.3.2. Character Mode Devices 3.4.3.3. Flash Memory Devices
3.4.3.1. Timer Devices x
3.4.3.1.1. System Clock Timer 3.4.3.1.2. Timestamp Timer
3.4.3.2. Character Mode Devices x
3.4.3.2.1. stdin, stdout and stderr 3.4.3.2.2. Blocking versus Non-Blocking I/O 3.4.3.2.3. Adding Your Own Character Mode Device
3.4.3.3. Flash Memory Devices x
3.4.3.3.1. Memory Initialization, Querying, and Device Support 3.4.3.3.2. Accessing Flash Memory 3.4.3.3.3. Configuration and Use Limitations 3.4.3.3.4. Direct Memory Access Devices 3.4.3.3.5. Unsupported Devices
3.4.4. Handling Exceptions x
3.4.4.1. Modifying the Exception Handler
4. Nios® V Processor Board Support Package Editor x
4.1. Board Support Packages 4.2. Common BSP Tasks 4.3. Details of BSP Creation 4.4. Tcl Scripts for BSP Settings 4.5. Revising Your BSP 4.6. Specifying BSP Defaults 4.7. Device Drivers and Software Packages 4.8. Boot Configurations for Intel FPGA Embedded Software
4.1. Board Support Packages x
4.1.1. Overview of BSP Creation 4.1.2. Nios® V Processor BSP Components
4.1.2. Nios® V Processor BSP Components x
4.1.2.1. Hardware Abstraction Layer 4.1.2.2. newlib C Standard Library 4.1.2.3. Device Drivers 4.1.2.4. Optional Software Packages 4.1.2.5. Optional Real-Time Operating System
4.2. Common BSP Tasks x
4.2.1. Creating a BSP for an Intel® FPGA Development Board 4.2.2. Adding the BSP Editor to Tool Flow 4.2.3. Linking and Locating 4.2.4. Other BSP Tasks
4.2.2. Adding the BSP Editor to Tool Flow x
4.2.2.1. Using Version Control 4.2.2.2. Copying, Moving, or Renaming a BSP 4.2.2.3. Passing the BSP to Another Developer
4.2.2.1. Using Version Control x
4.2.2.1.1. Creating BSP by Running User-defined Script to Call niosv-bsp 4.2.2.1.2. Creating Script that Uses the Command Line Tools
4.2.3. Linking and Locating x
4.2.3.1. Creating Memory Initialization Files 4.2.3.2. Modifying Linker Memory Regions 4.2.3.3. Creating a Custom Linker Section 4.2.3.4. Changing the Linker Section Mapping
4.2.3.3. Creating a Custom Linker Section x
4.2.3.3.1. Creating a Linker Section for an Existing Region 4.2.3.3.2. Dividing a Linker Region to Create a New Region and Section
4.2.4. Other BSP Tasks x
4.2.4.1. Querying Settings 4.2.4.2. Managing Device Drivers 4.2.4.3. Controlling the stdio Device 4.2.4.4. Configuring Optimization and Debugger Options 4.2.4.5. Configuring RISC-V Compiler
4.3. Details of BSP Creation x
4.3.1. BSP Settings File Creation 4.3.2. BSP Files and Folders 4.3.3. Linker Map Validation
4.3.2. BSP Files and Folders x
4.3.2.1. Generated and Copied Files 4.3.2.2. BSP Files
4.4. Tcl Scripts for BSP Settings x
4.4.1. Calling a Custom BSP Tcl Script
4.4.1. Calling a Custom BSP Tcl Script x
4.4.1.1. Tcl Script to Examine Hardware and Choose Settings
4.5. Revising Your BSP x
4.5.1. Regenerating Your BSP 4.5.2. Updating Your BSP 4.5.3. Recreating Your BSP
4.5.1. Regenerating Your BSP x
4.5.1.1. What Happens 4.5.1.2. When to Regenerate Your BSP
4.5.2. Updating Your BSP x
4.5.2.1. What Happens 4.5.2.2. When to Update Your BSP
4.5.3. Recreating Your BSP x
4.5.3.1. What Happens 4.5.3.2. When to Recreate Your BSP
4.6. Specifying BSP Defaults x
4.6.1. Top Level Tcl Script for BSP Defaults
4.6.1. Top Level Tcl Script for BSP Defaults x
4.6.1.1. Specifying the Default stdio Device 4.6.1.2. Specifying the Default System Timer 4.6.1.3. Specifying the Default Memory Map 4.6.1.4. Specifying the Default Bootloader Parameters 4.6.1.5. Specifying the Default Exception Parameter
4.8. Boot Configurations for Intel FPGA Embedded Software x
4.8.1. Memory Types 4.8.2. Boot from Flash Configuration 4.8.3. Run from Initialized Memory Configuration 4.8.4. Run-time Configurable Reset Configuration
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.2. HAL Architecture for Embedded Software Systems x
5.2.1. Services 5.2.2. Applications versus Drivers 5.2.3. Generic Device Models 5.2.4. C Standard Library—Newlib, Picolibc
5.2.3. Generic Device Models x
5.2.3.1. Device Model Classes 5.2.3.2. Benefits to Application Developers 5.2.3.3. Benefits to Device Driver Developers
5.3. Embedded Hardware Supported by the HAL x
5.3.1. Nios® V Processor Core Support 5.3.2. Supported Peripherals
5.3.2. Supported Peripherals x
5.3.2.1. Full HAL Support 5.3.2.2. Partial HAL Support
6. Developing Programs Using the Hardware Abstraction Layer x
6.1. HAL BSP Settings 6.2. The Nios® V Processor 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. Using Character-Mode Devices 6.7. Using Timer Devices 6.8. Using Flash Devices 6.9. Using DMA Devices 6.10. Interrupt Controllers 6.11. Reducing Code Footprint in Embedded Systems 6.12. Boot Sequence and Entry Point 6.13. Memory Usage 6.14. Working with HAL Source Files
6.6. Using Character-Mode Devices x
6.6.1. Standard Input, Standard Output and Standard Error 6.6.2. General Access to Character Mode Devices 6.6.3. C++ Streams 6.6.4. /dev/null 6.6.5. Lightweight Character-Mode I/O 6.6.6. Intel FPGA Logging Functions
6.6.6. Intel FPGA Logging Functions x
6.6.6.1. Enabling Logging 6.6.6.2. Extra Logging Options 6.6.6.3. Logging Levels 6.6.6.4. Example: Creating a BSP with Logging 6.6.6.5. Custom Logging Messages 6.6.6.6. Intel FPGA Logging Files
6.7. Using Timer Devices x
6.7.1. System Clock Driver 6.7.2. Alarms 6.7.3. Timestamp Driver
6.8. Using Flash Devices x
6.8.1. Simple Flash Access 6.8.2. Block Erasure or Corruption 6.8.3. Fine-Grained Flash Access
6.8.3. Fine-Grained Flash Access x
6.8.3.1. alt_get_flash_info() 6.8.3.2. alt_erase_flash() 6.8.3.3. alt_write_flash_block()
6.9. Using DMA Devices x
6.9.1. DMA Transmit Channels 6.9.2. DMA Receive Channels
6.9.2. DMA Receive Channels x
6.9.2.1. Memory-to-Memory DMA Transactions
6.11. Reducing Code Footprint in Embedded Systems x
6.11.1. Apply Compiler Flags 6.11.2. Use Small Variant Device Drivers 6.11.3. Reduce the File Descriptor Pool 6.11.4. Use /dev/null 6.11.5. Use a Smaller File I/O Library 6.11.6. Use the Minimal Character-Mode API 6.11.7. Eliminate Unused Device Drivers 6.11.8. Use the Picolibc Library 6.11.9. Eliminate Unused alt_load() 6.11.10. Eliminate Unneeded Exit Code
6.11.5. Use a Smaller File I/O Library x
6.11.5.1. Definition of 'asnprintf()' 6.11.5.2. Use UNIX-Style File I/O 6.11.5.3. Emulate ANSI C Functions
6.11.10. Eliminate Unneeded Exit Code x
6.11.10.1. Eliminate Clean Exit 6.11.10.2. Eliminate All Exit Code 6.11.10.3. Turn off C++ Support
6.12. Boot Sequence and Entry Point x
6.12.1. Hosted Versus Free-Standing Applications 6.12.2. Boot Sequence for HAL-Based Programs 6.12.3. Customizing the Boot Sequence
6.12.2. Boot Sequence for HAL-Based Programs x
6.12.2.1. System Initialization Code Boot Sequence 6.12.2.2. Default Implementation Steps
6.13. Memory Usage x
6.13.1. Memory Sections 6.13.2. Assigning Code and Data to Memory Partitions 6.13.3. Placement of the Heap and Stack 6.13.4. Global Pointer Register 6.13.5. Boot Modes
6.13.2. Assigning Code and Data to Memory Partitions x
6.13.2.1. Simple Placement Options 6.13.2.2. Advanced Placement Options
6.14. Working with HAL Source Files x
6.14.1. Finding HAL Files 6.14.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® V Processor 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.5. Nios® V Processor Hardware Design Concepts x
7.5.1. The Relationship Between the .qsys 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.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.8. Integrating a Device Driver in the HAL x
7.8.1. Overview 7.8.2. Assumptions and Requirements 7.8.3. Nios® V Processor BSP Generation Flow 7.8.4. File Names and Locations 7.8.5. Driver and Software Package Tcl Script Creation
7.8.3. Nios® V Processor BSP Generation Flow 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 Identifier 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
8. Exception Handling x
8.1. Nios® V Processor Exception Handling Overview 8.2. Nios® V Processor Hardware Interrupt Service Routines 8.3. Nios® V Processor Software Interrupt Service Routines 8.4. Improving Nios® V Processor ISR Performance 8.5. Debugging Nios® V Processor ISRs 8.6. HAL Exception Handling System Implementation 8.7. Nios® V Processor Instruction-Related Exception Handler
8.1. Nios® V Processor Exception Handling Overview x
8.1.1. Exception Handling Terminology 8.1.2. Hardware Interrupt Controllers 8.1.3. How the Hardware works 8.1.4. Latency and Response Time
8.1.2. Hardware Interrupt Controllers x
8.1.2.1. Internal Interrupt Concepts
8.1.3. How the Hardware works x
8.1.3.1. How the Internal Interrupt Controller Works
8.1.4. Latency and Response Time x
8.1.4.1. Internal Interrupt Controller
8.2. Nios® V Processor Hardware Interrupt Service Routines x
8.2.1. HAL APIs for Hardware Interrupts 8.2.2. Writing a Hardware ISR 8.2.3. Registering a Hardware ISR 8.2.4. Enabling and Disabling Interrupts 8.2.5. C Example
8.2.1. HAL APIs for Hardware Interrupts x
8.2.1.1. Enhanced HAL Hardware Interrupt API
8.2.2. Writing a Hardware ISR x
8.2.2.1. Using General Exception Funnels 8.2.2.2. Running in a Restricted Environment
8.2.3. Registering a Hardware ISR x
8.2.3.1. Methods the HAL Uses to Register the ISR
8.2.5. C Example x
8.2.5.1. Writing a Hardware ISR to Service a Button PIO Interrupt 8.2.5.2. Registering the Button PIO ISR with the HAL
8.3. Nios® V Processor Software Interrupt Service Routines x
8.3.1. HAL APIs for Software Interrupt 8.3.2. Writing a Software ISR 8.3.3. Registering a Software ISR 8.3.4. Enabling and Disabling Interrupts 8.3.5. C Example
8.3.5. C Example x
8.3.5.1. Writing a Software ISR 8.3.5.2. Registering the Software ISR with the HAL
8.4. Improving Nios® V Processor ISR Performance x
8.4.1. Software Performance Improvements 8.4.2. Hardware Performance Improvements
8.4.1. Software Performance Improvements x
8.4.1.1. Execute Time-Intensive Algorithms in the Application Context 8.4.1.2. Implement Time-Intensive Algorithms in Hardware 8.4.1.3. Increase Buffer Size 8.4.1.4. Use Double Buffering 8.4.1.5. Keep Interrupts Enabled 8.4.1.6. Use Fast Memory 8.4.1.7. Use a Separate Exception Stack 8.4.1.8. Use Nested Hardware Interrupts 8.4.1.9. Use Compiler Optimization
8.4.1.7. Use a Separate Exception Stack x
8.4.1.7.1. Separate General Exception Stack
8.4.2. Hardware Performance Improvements x
8.4.2.1. Add Fast Memory 8.4.2.2. Add a DMA Controller 8.4.2.3. Place the Handler in Fast Memory 8.4.2.4. Select Hardware Interrupt Priorities
8.4.2.4. Select Hardware Interrupt Priorities x
8.4.2.4.1. Hardware Interrupt Priorities with the Internal Interrupt Controller
8.6. HAL Exception Handling System Implementation x
8.6.1. Exception Handling System Structure 8.6.2. General Exception Funnels 8.6.3. Hardware Interrupt Funnel 8.6.4. Software Exception Funnel 8.6.5. Software Interrupt Handler 8.6.6. Timer Interrupt Handler
8.6.2. General Exception Funnels x
8.6.2.1. Exception Occurs 8.6.2.2. Exception Dispatch with the Internal Interrupt Controller 8.6.2.3. Returning from Exceptions
8.6.3. Hardware Interrupt Funnel x
8.6.3.1. Hardware Interrupt Funnel for the Internal Interrupt Controller
8.6.4. Software Exception Funnel x
8.6.4.1. Instruction-Related Exceptions 8.6.4.2. Miscellaneous Exceptions 8.6.4.3. Invalid Instructions
8.7. Nios® V Processor Instruction-Related Exception Handler x
8.7.1. Writing an Instruction-Related Exception Handler 8.7.2. Registering an Instruction-Related Exception Handler 8.7.3. Removing an Instruction-Related Exception Handler 8.7.4. Debugging for Instruction-Related Exception Handler
8.7.1. Writing an Instruction-Related Exception Handler x
8.7.1.1. Exception Cause Codes
8.7.4. Debugging for Instruction-Related Exception Handler x
8.7.4.1. Enable JTAG UART polling operation 8.7.4.2. Example of Instruction-Related Exception Handler 8.7.4.3. Adding Custom Exception Handler
9. MicroC/OS-II Real-Time Operating System x
9.1. Overview of the MicroC/OS-II RTOS 9.2. Other RTOS Providers 9.3. The Nios® V Processor Implementation of MicroC/OS-II 9.4. Implementing MicroC/OS-II Projects for the Nios® V Processor
9.1. Overview of the MicroC/OS-II RTOS x
9.1.1. Support and Licensing
9.3. The Nios® V Processor Implementation of MicroC/OS-II x
9.3.1. MicroC/OS-II Architecture 9.3.2. MicroC/OS-II Device Drivers 9.3.3. Thread-Safe Drivers 9.3.4. The newlib ANSI C Standard Library 9.3.5. Interrupt Service Routines for MicroC/OS-II
10. MicroC/TCP-IP Protocol Stack x
10.1. Overview of the MicroC/TCP-IP Protocol Stack 10.2. Support and Licensing 10.3. Prerequisites for Understanding the MicroC/TCP-IP Protocol Stack 10.4. Introduction to the MicroC/TCP-IP Protocol Stack - Nios® V Processor Edition 10.5. The MicroC/TCP-IP Protocol Stack Files and Directories 10.6. Enabling MicroC/TCP-IP Protocol Stack 10.7. Using the MicroC/TCP-IP Protocol Stack
10.4. Introduction to the MicroC/TCP-IP Protocol Stack - Nios® V Processor Edition x
10.4.1. Nios® V Processor System Requirements
10.7. Using the MicroC/TCP-IP Protocol Stack x
10.7.1. Initializing the Stack 10.7.2. Network IP configuration 10.7.3. Example applications
10.7.3. Example applications x
10.7.3.1. simple_socket_server.c 10.7.3.2. app_iperf.c
11. FreeRTOS* Real-Time Operating System x
11.1. Overview of the FreeRTOS* 11.2. The Nios® V Processor Implementation of FreeRTOS* 11.3. Implementing FreeRTOS Project for the Nios V Processor
11.1. Overview of the FreeRTOS* x
11.1.1. Support and Licensing
11.2. The Nios® V Processor Implementation of FreeRTOS* x
11.2.1. FreeRTOS* Architecture 11.2.2. FreeRTOS* Device Drivers 11.2.3. Thread-Safe HAL Drivers 11.2.4. The newlib ANSI C Standard Library
12. Publishing Component Information to Embedded Software x
12.1. Embedded Component Information Flow 12.2. Embedded Software Assignments
12.2. Embedded Software Assignments x
12.2.1. C Macro Namespace 12.2.2. Configuration Namespace
12.2.1. C Macro Namespace x
12.2.1.1. Generated Macro in system.h 12.2.1.2. GCC C/C++ 32-bit Processor Constants
12.2.2. Configuration Namespace x
12.2.2.1. Configuration Data Types 12.2.2.2. Component Configuration Information 12.2.2.3. Memory-Mapped Slave Information
13. Nios® V Processor Appendix x
13.1. HAL API 13.2. Nios® V Processor Tools Reference 13.3. GNU RISC-V Embedded GCC Toolchain Reference 13.4. Settings Managed by Nios® V Processor Board Support Package Editor 13.5. Board Support Package Tcl Commands 13.6. Nios® V Processor Design Example
13.1. HAL API x
13.1.1. HAL API Reference 13.1.2. HAL Standard Types
13.1.1. HAL API Reference x
13.1.1.1. _exit() 13.1.1.2. _rename() 13.1.1.3. alt_dcache_flush() 13.1.1.4. alt_dcache_flush_all() 13.1.1.5. alt_icache_flush_all() 13.1.1.6. alt_dcache_flush_no_writeback() 13.1.1.7. alt_uncached_malloc() 13.1.1.8. alt_uncached_free() 13.1.1.9. alt_remap_uncached() 13.1.1.10. alt_remap_cached() 13.1.1.11. alt_icache_flush_all() 13.1.1.12. alt_icache_flush() 13.1.1.13. alt_alarm_start() 13.1.1.14. alt_alarm_stop() 13.1.1.15. alt_dma_rxchan_depth() 13.1.1.16. alt_dma_rxchan_close() 13.1.1.17. alt_dev_reg() 13.1.1.18. alt_dma_rxchan_open() 13.1.1.19. alt_dma_rxchan_prepare() 13.1.1.20. alt_dma_rxchan_reg() 13.1.1.21. alt_dma_txchan_close() 13.1.1.22. alt_dma_txchan_ioctl() 13.1.1.23. alt_dma_txchan_open() 13.1.1.24. alt_dma_txchan_reg() 13.1.1.25. alt_flash_close_dev() 13.1.1.26. alt_exception_cause_generated_bad_addr() 13.1.1.27. alt_erase_flash_block() 13.1.1.28. alt_dma_rxchan_ioctl() 13.1.1.29. alt_dma_txchan_space() 13.1.1.30. alt_dma_txchan_send() 13.1.1.31. alt_flash_open_dev() 13.1.1.32. alt_fs_reg() 13.1.1.33. alt_get_flash_info() 13.1.1.34. alt_ic_irq_disable() 13.1.1.35. alt_ic_irq_enabled() 13.1.1.36. alt_ic_isr_register() 13.1.1.37. alt_ic_irq_enable() 13.1.1.38. alt_instruction_exception_register() 13.1.1.39. alt_irq_cpu_enable_interrupts () 13.1.1.40. alt_irq_disable_all() 13.1.1.41. alt_irq_enable_all() 13.1.1.42. alt_irq_enabled() 13.1.1.43. alt_irq_init() 13.1.1.44. alt_irq_pending () 13.1.1.45. alt_llist_insert() 13.1.1.46. alt_llist_remove() 13.1.1.47. alt_load_section() 13.1.1.48. alt_nticks() 13.1.1.49. alt_read_flash() 13.1.1.50. alt_tick() 13.1.1.51. alt_ticks_per_second() 13.1.1.52. alt_timestamp() 13.1.1.53. alt_timestamp_freq() 13.1.1.54. alt_timestamp_start() 13.1.1.55. alt_write_flash() 13.1.1.56. alt_write_flash_block() 13.1.1.57. close() 13.1.1.58. fstat() 13.1.1.59. fork() 13.1.1.60. fcntl() 13.1.1.61. execve() 13.1.1.62. getpid() 13.1.1.63. kill() 13.1.1.64. stat() 13.1.1.65. settimeofday() 13.1.1.66. wait() 13.1.1.67. unlink() 13.1.1.68. sbrk() 13.1.1.69. link() 13.1.1.70. lseek() 13.1.1.71. open() 13.1.1.72. alt_sysclk_init() 13.1.1.73. times() 13.1.1.74. read() 13.1.1.75. write() 13.1.1.76. usleep() 13.1.1.77. alt_lock_flash() 13.1.1.78. gettimeofday() 13.1.1.79. ioctl() 13.1.1.80. isatty() 13.1.1.81. alt_niosv_enable_msw_interrupt() 13.1.1.82. alt_niosv_disable_msw_interrupt() 13.1.1.83. alt_niosv_is_msw_interrupt_enabled() 13.1.1.84. alt_niosv_trigger_msw_interrupt() 13.1.1.85. alt_niosv_clear_msw_interrupt() 13.1.1.86. alt_niosv_register_msw_interrupt_handler()
13.1.2. HAL Standard Types x
13.1.2.1. alt_getchar() 13.1.2.2. alt_putstr() 13.1.2.3. alt_putchar() 13.1.2.4. alt_printf()
13.2. Nios® V Processor Tools Reference x
13.2.1. Nios® V Processor Command Line Utilities 13.2.2. File Format Conversion Tools Reference 13.2.3. Other Command Line Utilities Tools Reference
13.2.1. Nios® V Processor Command Line Utilities x
13.2.1.1. niosv-shell 13.2.1.2. niosv-bsp 13.2.1.3. niosv-app 13.2.1.4. niosv-download 13.2.1.5. niosv-stack-report
13.2.2. File Format Conversion Tools Reference x
13.2.2.1. elf2hex 13.2.2.2. elf2flash
13.2.3. Other Command Line Utilities Tools Reference x
13.2.3.1. juart-terminal 13.2.3.2. cmake 13.2.3.3. make 13.2.3.4. openocd 13.2.3.5. openocd-cfg-gen
13.4. Settings Managed by Nios® V Processor Board Support Package Editor x
13.4.1. Overview of BSP Settings 13.4.2. Overview of Component and Driver Settings 13.4.3. BSP Settings Reference
13.4.2. Overview of Component and Driver Settings x
13.4.2.1. Intel FPGA Avalon-MM JTAG UART Driver Settings 13.4.2.2. Intel FPGA Avalon-MM UART Driver Settings
13.4.3. BSP Settings Reference x
13.4.3.1. Intel HAL BSP 13.4.3.2. Micrium MicroC/OS-II BSP 13.4.3.3. FreeRTOS BSP 13.4.3.4. Device Drivers BSP
13.5. Board Support Package Tcl Commands x
13.5.1. Tcl Command Environments 13.5.2. Tcl Commands for BSP Settings 13.5.3. Tcl Commands for BSP Generation Callbacks 13.5.4. Tcl Commands for Drivers and Packages
13.5.2. Tcl Commands for BSP Settings x
13.5.2.1. add_memory_device 13.5.2.2. add_memory_region 13.5.2.3. add_section_mapping 13.5.2.4. are_same_resource 13.5.2.5. delete_memory_region 13.5.2.6. delete_section_mapping 13.5.2.7. disable_sw_package 13.5.2.8. enable_sw_package 13.5.2.9. get_addr_span 13.5.2.10. get_assignment 13.5.2.11. get_available_drivers 13.5.2.12. get_available_sw_packages 13.5.2.13. get_base_addr 13.5.2.14. get_break_offset 13.5.2.15. get_break_slave_desc 13.5.2.16. get_cpu_name 13.5.2.17. get_current_memory_regions 13.5.2.18. get_current_section_mappings 13.5.2.19. get_default_memory_regions 13.5.2.20. get_driver 13.5.2.21. get_enabled_sw_packages 13.5.2.22. get_exception_offset 13.5.2.23. get_exception_slave_desc 13.5.2.24. get_fast_tlb_miss_exception_offset 13.5.2.25. get_fast_tlb_miss_exception_slave_desc 13.5.2.26. get_interrupt_controller_id 13.5.2.27. get_irq_interrupt_controller_id 13.5.2.28. get_irq_number 13.5.2.29. get_memory_region 13.5.2.30. get_module_class_name 13.5.2.31. get_module_name 13.5.2.32. get_reset_offset 13.5.2.33. get_reset_slave_desc 13.5.2.34. get_section_mapping 13.5.2.35. get_setting 13.5.2.36. get_setting_desc 13.5.2.37. get_slave_descs 13.5.2.38. is_char_device 13.5.2.39. is_connected_interrupt_controller_device 13.5.2.40. is_connected_to_data_master 13.5.2.41. is_connected_to_instruction_master 13.5.2.42. is_ethernet_mac_device 13.5.2.43. is_flash 13.5.2.44. is_memory_device 13.5.2.45. is_non_volatile_storage 13.5.2.46. is_timer_device 13.5.2.47. log_debug 13.5.2.48. log_default 13.5.2.49. log_error 13.5.2.50. log_verbose 13.5.2.51. set_driver 13.5.2.52. set_ignore_file 13.5.2.53. set_setting 13.5.2.54. update_memory_region 13.5.2.55. update_section_mapping 13.5.2.56. add_default_memory_regions 13.5.2.57. create_bsp 13.5.2.58. generate_bsp 13.5.2.59. get_available_bsp_type_versions 13.5.2.60. get_available_bsp_types 13.5.2.61. get_available_cpu_architectures 13.5.2.62. get_available_cpu_names 13.5.2.63. get_available_software 13.5.2.64. get_available_software_setting_properties 13.5.2.65. get_available_software_settings 13.5.2.66. get_bsp_version 13.5.2.67. get_cpu_architecture 13.5.2.68. get_sopcinfo_file 13.5.2.69. get_supported_bsp_types 13.5.2.70. is_bsp_hal_extension 13.5.2.71. open_bsp 13.5.2.72. save_bsp 13.5.2.73. set_bsp_version 13.5.2.74. set_logging_mode
13.5.3. Tcl Commands for BSP Generation Callbacks x
13.5.3.1. add_class_sw_setting 13.5.3.2. add_class_systemh_line 13.5.3.3. add_module_sw_property 13.5.3.4. add_module_sw_setting 13.5.3.5. add_module_systemh_line 13.5.3.6. add_systemh_line 13.5.3.7. get_class_peripheral 13.5.3.8. get_module_assignment 13.5.3.9. get_module_name 13.5.3.10. get_module_peripheral 13.5.3.11. get_module_sw_setting_value 13.5.3.12. get_peripheral_property 13.5.3.13. remove_class_systemh_line 13.5.3.14. remove_module_systemh_line 13.5.3.15. set_class_sw_setting_property 13.5.3.16. set_module_sw_setting_property
13.5.4. Tcl Commands for Drivers and Packages x
13.5.4.1. add_sw_property 13.5.4.2. add_sw_setting 13.5.4.3. add_sw_setting2 13.5.4.4. create_driver 13.5.4.5. create_os 13.5.4.6. create_sw_package 13.5.4.7. set_sw_property 13.5.4.8. set_sw_setting_property
1. Overview of Nios® V Embedded Processor Development
2. Getting Started from the Command Line
3. Nios® V Processor Software Development and Implementation
4. Nios® V Processor Board Support Package Editor
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. MicroC/OS-II Real-Time Operating System
10. MicroC/TCP-IP Protocol Stack
11. FreeRTOS* Real-Time Operating System
12. Publishing Component Information to Embedded Software
13. Nios® V Processor Appendix
A. Nios® V Processor Software Developer Handbook Archives
14. Revision History for Nios® V Processor Software Developer Handbook

6.9.2. DMA Receive Channels

DMA receive channels operate similarly to DMA transmit channels. Software can obtain a handle for a DMA receive channel using the alt_dma_rxchan_open() function. You can then use the alt_dma_rxchan_prepare() function to post receive requests. The prototype for alt_dma_rxchan_prepare() is: 
typedef void (alt_rxchan_done)(void* handle, void* data);
int alt_dma_rxchan_prepare (alt_dma_rxchan dma, 
void* data,
alt_u32 length,
alt_rxchan_done* done, 
void* handle);

A call to this function posts a receive request to channel dma, for up to length bytes of data to be placed at address data. This function returns before the DMA transaction completes. The return value indicates whether the request is successfully queued. A negative return value indicates that the request failed. When the transaction completes, the user-supplied function done() is called with argument handle to provide notification and a pointer to the receive data.

Certain errors can prevent the DMA transfer from completing. Typically this is caused by a catastrophic hardware failure; for example, if a component involved in the transfer fails to respond to a read or write request. If the DMA transfer does not complete (that is, less than length bytes are transferred), function done() is never called.

Two additional functions are provided for manipulating DMA receive channels: alt_dma_rxchan_depth() and alt_dma_rxchan_ioctl().

Note: If you are using the Avalon-MM DMA device to receive from hardware (not memory-to-memory transfer), call the alt_dma_rxchan_ioctl() function with the request argument set to ALT_DMA_RX_ONLY_ON.

alt_dma_rxchan_depth() returns the maximum number of receive requests that can be queued to the device. alt_dma_rxchan_ioctl() performs device-specific manipulation of the receive device. 

#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>
#include "sys/alt_dma.h"
#include "alt_types.h"
/* flag used to indicate the transaction is complete */
volatile int dma_complete = 0;
/* function that is called when the transaction completes */
void dma_done (void* handle, void* data)
   {
   dma_complete = 1;
   }
   int main (void)
      {
      alt_u8 buffer[1024];
      alt_dma_rxchan rx;
      /* Obtain a handle for the device */
      if ((rx = alt_dma_rxchan_open ("/dev/dma_0")) == NULL)
         {
            printf ("Error: failed to open device\n");
            exit (1);
         }
      else
         {
         /* Post the receive request */
         if (alt_dma_rxchan_prepare (rx, buffer, 1024, dma_done, NULL) < 0)
            {
               printf ("Error: failed to post receive request\n");
               exit (1);
            }
         /* Wait for the transaction to complete */
         while (!dma_complete);
            printf ("Transaction complete\n");
            alt_dma_rxchan_close (rx);
      }
      return 0;
}

Section Content
Memory-to-Memory DMA Transactions

Level Two Title