Copyright © 2004 Altera Corporation. All rights reserved. Altera, The Programmable Solutions Company, the stylized Altera logo, specific device des-
ignations, and all other words and logos that are identified as trademarks and/or service marks are, unless noted otherwise, the trademarks and
service marks of Altera Corporation in the U.S. and other countries. All other product or service names are the property of their respective holders. Al-
tera products are protected under numerous U.S. and foreign patents and pending applications, maskwork rights, and copyrights. Altera warrants
performance of its semiconductor products to current specifications in accordance with Altera's standard warranty, but reserves the right to make
changes to any products and services at any time without notice. Altera assumes no responsibility or liability arising out of the ap-
plication or use of any information, product, or service described herein except as expressly agreed to in writing by Altera
Corporation. Altera customers are advised to obtain the latest version of device specifications before relying on any published in-
formation and before placing orders for products or services.
Printed on recycled paper
ii Altera Corporation
Preliminary
Altera Corporation iii
Preliminary
Contents
Chapter Revision Dates ........................................................................... ix
About this Handbook ............................................................................... xi
How to Contact Altera ............................................................................................................................. xi
Typographic Conventions ....................................................................................................................... xi
Section I. Nios II Software Development
Revision History ....................................................................................................................... Section I–1
Chapter 1. Overview
Introduction ............................................................................................................................................ 1–1
Getting Started ...................................................................................................................................... 1–1
Development Environment .................................................................................................................. 1–1
Tools ................................................................................................................................................... 1–1
Consistent Development Environment ......................................................................................... 1–3
Consistent Runtime Environment ................................................................................................. 1–3
Third-Party Support .............................................................................................................................. 1–3
Migrating from the First-Generation Nios Processor ....................................................................... 1–4
Further Nios II Information ................................................................................................................. 1–4
Chapter 2. Tour of the Nios II IDE
Introduction ............................................................................................................................................ 2–1
The Nios II IDE Workbench ................................................................................................................. 2–1
Perspectives, Editors & Views ........................................................................................................ 2–2
Creating a New Project ......................................................................................................................... 2–3
Building & Managing Projects ............................................................................................................. 2–4
Running & Debugging Programs ........................................................................................................ 2–5
Programming Flash ............................................................................................................................... 2–9
Online Help .......................................................................................................................................... 2–10
Section II. The HAL System Library
Revision History ..................................................................................................................... Section II–1
Chapter 3. Overview of the HAL System Library
Introduction ............................................................................................................................................ 3–1
iv Altera Corporation
Preliminary
Contents Nios II Software Developer’s Handbook
Getting Started ....................................................................................................................................... 3–1
HAL Architecture .................................................................................................................................. 3–2
Services .............................................................................................................................................. 3–2
Applications vs. Drivers .................................................................................................................. 3–3
Generic Device Models .................................................................................................................... 3–3
C Standard Library—Newlib ......................................................................................................... 3–4
Supported Peripherals .......................................................................................................................... 3–5
Chapter 4. Developing Programs using the HAL
Introduction ............................................................................................................................................ 4–1
The Nios II IDE Project Structure ........................................................................................................ 4–1
The system.h System Description File ................................................................................................ 4–2
Data Widths & the HAL Type Definitions ......................................................................................... 4–3
UNIX-Style Interface ............................................................................................................................. 4–4
File System .............................................................................................................................................. 4–5
Using Character-Mode Devices ........................................................................................................... 4–6
Standard Input, Standard Output & Standard Error .................................................................. 4–7
General Access to Character Mode Devices ................................................................................. 4–7
C++ Streams ...................................................................................................................................... 4–8
/dev/null .......................................................................................................................................... 4–8
Using File Subsystems .......................................................................................................................... 4–8
Using Timer Devices ............................................................................................................................. 4–8
The HAL System Clock ................................................................................................................... 4–9
Alarms ................................................................................................................................................ 4–9
High Resolution Time Measurement .......................................................................................... 4–11
Using Flash Devices ............................................................................................................................ 4–12
Simple Flash Access ....................................................................................................................... 4–12
Block Erasure or Corruption ......................................................................................................... 4–14
Fine-Grained Flash Access ............................................................................................................ 4–15
Using DMA Devices ............................................................................................................................ 4–18
DMA Transmit Channels .............................................................................................................. 4–19
DMA Receive Channels ................................................................................................................. 4–20
Memory-to-Memory DMA Transactions .................................................................................... 4–21
Reducing Code Footprint ................................................................................................................... 4–23
Enable Compiler Optimizations ...................................................................................................4–23
Use Small Footprint Device Drivers ............................................................................................ 4–23
Reduce the File Descriptor Pool ................................................................................................... 4–24
Use /dev/null ................................................................................................................................. 4–24
Use UNIX not ANSI C File I/O ....................................................................................................4–24
Use the Small Newlib C Library ..................................................................................................4–25
Eliminate Unused Device Drivers ............................................................................................... 4–27
Use _exit() for No Clean Exit ........................................................................................................ 4–27
Disable Instruction Emulation ...................................................................................................... 4–27
Boot Sequence and Entry Point ......................................................................................................... 4–28
Hosted vs. Free-Standing Applications ...................................................................................... 4–28
Boot Sequence for HAL-Based Programs ................................................................................... 4–29
Customizing the Boot Sequence ..................................................................................................
.4–30
Altera Corporation v
Preliminary
Contents Contents
Memory Usage ..................................................................................................................................... 4–30
Memory Sections ............................................................................................................................ 4–30
Assigning Code & Data to Memory Partitions .......................................................................... 4–31
Placement of the Heap & Stack .................................................................................................... 4–32
Boot Modes ...................................................................................................................................... 4–33
Paths to HAL System Library Files ................................................................................................... 4–33
Finding HAL Files .......................................................................................................................... 4–33
Overriding HAL Functions ........................................................................................................... 4–34
Chapter 5. Developing Device Drivers for the HAL
Introduction ............................................................................................................................................ 5–1
Integration into the HAL API ......................................................................................................... 5–1
Peripheral-Specific API ................................................................................................................... 5–1
Before You Begin .............................................................................................................................. 5–2
Development Flow for Creating Device Drivers .............................................................................. 5–2
SOPC Builder Concepts ........................................................................................................................ 5–2
The Relationship between system.h & SOPC Builder ................................................................ 5–2
Using SOPC Builder for Optimal Hardware Configuration ...................................................... 5–3
Components, Devices & Peripherals ............................................................................................. 5–3
Accessing Hardware ............................................................................................................................ 5–3
Creating Drivers for HAL Device Classes ......................................................................................... 5–4
Character-Mode Device Drivers .................................................................................................... 5–5
File Subsystem Drivers .................................................................................................................... 5–7
Timer Device Drivers ....................................................................................................................... 5–8
Flash Device Drivers ........................................................................................................................ 5–9
DMA Device Drivers ..................................................................................................................... 5–10
Ethernet Device Drivers ................................................................................................................ 5–12
Integrating a Device Driver into the HAL ....................................................................................... 5–15
Directory Structure for HAL Devices .......................................................................................... 5–15
Device Driver Files for the HAL .................................................................................................. 5–15
Summary ......................................................................................................................................... 5–19
Providing Reduced Footprint Drivers .............................................................................................. 5–19
Namespace Allocation ........................................................................................................................ 5–19
Overriding the Default Device Drivers ............................................................................................ 5–20
Section III. Advanced Programming Topics
Revision History .................................................................................................................... Section III–1
Chapter 6. Exception Handling
Introduction ............................................................................................................................................ 6–1
Nios II Exceptions Overview ............................................................................................................... 6–1
HAL Implementation ............................................................................................................................ 6–2
_irq_entry .......................................................................................................................................... 6–2
alt_irq_handler() ............................................................................................................................... 6–3
software_exception .......................................................................................................................... 6–4
