2. Developing Nios II Software

Transcription

1 2. Developing Nios II Sotware July 2011 ED ED Introduction This chapter provides in-depth inormation about sotware development or the Altera Nios II processor. It complements the Nios II Sotware Developer s Handbook by providing the ollowing additional inormation: Recommended design practices Best practice inormation or Nios II sotware design, development, and deployment. Implementation inormation Additional in-depth inormation about the implementation o application programming interaces (APIs) and source code or each topic, i available. Pointers to topics Inormative background and resource inormation or each topic, i available. Beore reading this document, you should be amiliar with the process o creating a simple board support package (BSP) and an application project using the Nios II Sotware Build Tools development low. The Sotware Build Tools low is supported by Nios II Sotware Build Tools or Eclipse as well as the Nios II Command Shell. This document ocuses on the Nios II Sotware Build Tools or Eclipse, but most inormation is also applicable to project development in the Command Shell. The ollowing resources provide training on the Nios II Sotware Build Tools development low: Online training demonstrations located on the Embedded SW Designer Curriculum page o the Altera website: Developing Sotware or the Nios II Processor: Tools Overview Developing Sotware or the Nios II Processor: Design Flow Developing Sotware or the Nios II Processor: Sotware Build Flow (Part 1) Developing Sotware or the Nios II Processor: Sotware Build Flow (Part 2) Documentation located on the Literature: Nios II Processor page o the Altera website, especially the Getting Started rom the Command Line and Getting Started with the Graphical User Interace chapters o the Nios II Sotware Developer's Handbook. Example designs provided with the Nios II Embedded Design Suite (EDS). The online training demonstrations describe these sotware design examples, which you can use as-is or as the basis or your own more complex designs. This chapter is structured according to the Nios II sotware development process. Each section describes Altera s recommended design practices to accomplish a speciic task Altera Corporation. All rights reserved. ALTERA, ARRIA, CYCLONE, HARDCOPY, MAX, MEGACORE, NIOS, QUARTUS and STRATIX are Reg. U.S. Pat. & Tm. O. and/or trademarks o Altera Corporation in the U.S. and other countries. All other trademarks and service marks are the property o their respective holders as described at Altera warrants perormance o its semiconductor products to current speciications 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 o the application or use o any inormation, product, or service described herein except as expressly agreed to in writing by Altera. Altera customers are advised to obtain the latest version o device speciications beore relying on any published inormation and beore placing orders or products or services. Embedded Design Handbook July 2011 Subscribe

2 2 2 Chapter 2: Developing Nios II Sotware Sotware Development Cycle This chapter contains the ollowing sections: Sotware Development Cycle Sotware Project Mechanics on page 2 5 Developing With the Hardware Abstraction Layer on page 2 24 Optimizing the Application on page 2 43 Linking Applications on page 2 49 Application Boot Loading and Programming System Memory on page When you install the Nios II EDS, it is installed in the same directory with the Quartus II sotware. For example, i the Quartus II sotware is installed on the Windows operating system, and the root directory o the Quartus II sotware is c:\altera\<version>\quartus, then the root directory o the Nios II EDS is c:\altera\<version>\nios2eds. For simplicity, this handbook reers to the nios2eds directory as <Nios II EDS install dir>. Sotware Development Cycle The Nios II EDS includes a complete set o C/C++ sotware development tools or the Nios II processor. In addition, a set o third-party embedded sotware tools is provided with the Nios II EDS. This set includes the MicroC/OS-II real-time operating system and the NicheStack TCP/IP networking stack. This chapter ocuses on the use o the Altera-created tools or Nios II sotware generation. It also includes some discussion o third-party tools. The Nios II EDS is a collection o sotware generation, management, and deployment tools or the Nios II processor. The toolchain includes tools that perorm low-level tasks and tools that perorm higher-level tasks using the lower-level tools. This section contains the ollowing subsections: Altera System on a Programmable Chip (SOPC) Solutions Nios II Sotware Development Process on page 2 3 Altera System on a Programmable Chip (SOPC) Solutions To understand the Nios II sotware development process, you must understand the deinition o an SOPC Builder system. SOPC Builder is a system development tool or creating systems including processors, peripherals, and memories. The tool enables you to deine and generate a complete SOPC very eiciently. SOPC Builder does not require that your system contain a Nios II processor, although it provides complete support or integrating Nios II processors with your system. An SOPC Builder system is similar in many ways to a conventional embedded system; however, the two kinds o system are not identical. An in-depth understanding o the dierences increases your eiciency when designing your SOPC Builder system. Embedded Design Handbook July 2011 Altera Corporation

3 Chapter 2: Developing Nios II Sotware 2 3 Sotware Development Cycle In Altera SOPC Builder solutions, the hardware design is implemented in an FPGA device. An FPGA device is volatile contents are lost when the power is turned o and reprogrammable. When an FPGA is programmed, the logic cells inside it are conigured and connected to create an SOPC system, which can contain Nios II processors, memories, peripherals, and other structures. The system components are connected with Avalon interaces. Ater the FPGA is programmed to implement a Nios II processor, you can download, run, and debug your system sotware on the system. Understanding the ollowing basic characteristics o FPGAs and Nios II processors is critical or developing your Nios II sotware application eiciently: FPGA devices and SOPC Builder basic properties: Volatility The FPGA is unctional only ater it is conigured, and it can be reconigured at any time. Design Many Altera SOPC systems are designed using SOPC Builder and the Quartus II sotware, and may include multiple peripherals and processors. Coniguration FPGA coniguration can be perormed through a programming cable, such as the USB-Blaster cable, which is also used or Nios II sotware debugging operations. Peripherals Peripherals are created rom FPGA resources and can appear anywhere in the Avalon memory space. Most o these peripherals are internally parameterizable. Nios II processor basic properties: Volatility The Nios II processor is volatile and is only present ater the FPGA is conigured. It must be implemented in the FPGA as a system component, and, like the other system components, it does not exist in the FPGA unless it is implemented explicitly. Parameterization Many properties o the Nios II processor are parameterizable in SOPC Builder, including core type, cache memory support, and custom instructions, among others. Processor Memory The Nios II processor must boot rom and run code loaded in an internal or external memory device. Debug support To enable sotware debug support, you must conigure the Nios II processor with a debug core. Debug communication is perormed through a programming cable, such as the USB-Blaster cable. Reset vector The reset vector address can be conigured to any memory location. Exception vector The exception vector address can be conigured to any memory location. Nios II Sotware Development Process This section provides an overview o the Nios II sotware development process and introduces terminology. The rest o the chapter elaborates the description in this section. July 2011 Altera Corporation Embedded Design Handbook

4 2 4 Chapter 2: Developing Nios II Sotware Sotware Development Cycle The Nios II sotware generation process includes the ollowing stages and main hardware coniguration tools: 1. Hardware coniguration SOPC Builder Quartus II sotware 2. Sotware project management BSP coniguration Application project coniguration Editing and building the sotware project Running, debugging, and communicating with the target Ensuring hardware and sotware coherency Project management 3. Sotware project development Developing with the Hardware Abstraction Layer (HAL) Programming the Nios II processor to access memory Writing exception handlers Optimizing the application or perormance and size 4. Application deployment Linking (run-time memory) Boot loading the system application Programming lash memory In this list o stages and tools, the subtopics under the topics Sotware project management, Sotware project development, and Application deployment correspond closely to sections in the chapter. You create the hardware or the system using the Quartus II and SOPC Builder sotware. The main output produced by generating the hardware or the system is the SRAM Object File (.so), which is the hardware image o the system, and the SOPC Inormation File (.sopcino), which describes the hardware components and connections. 1 The key ile required to generate the application sotware is the.sopcino ile. The sotware generation tools use the.sopcino ile to create a BSP project. The BSP project is a collection o C source, header and initialization iles, and a makeile or building a custom library or the hardware in the system. This custom library is the BSP library ile (.a). The BSP library ile is linked with your application project to create an executable binary ile or your system, called an application image. The combination o the BSP project and your application project is called the sotware project. Embedded Design Handbook July 2011 Altera Corporation

5 Chapter 2: Developing Nios II Sotware 2 5 Sotware Project Mechanics The application project is your application C source and header iles and a makeile that you can generate by running Altera-provided tools. You can edit these iles and compile and link them with the BSP library ile using the makeile. Your application sources can reerence all resources provided by the BSP library ile. The BSP library ile contains services provided by the HAL, which your application sources can reerence. Ater you build your application image, you can download it to the target system, and communicate with it through a terminal application. 1 You can access the makeile in the Eclipse Project Explorer view ater you have created your project in the Nios II Sotware Build Tools or Eclipse ramework. The sotware project is lexible: you can regenerate it i the system hardware changes, or modiy it to add or remove unctionality, or tune it or your particular system. You can also modiy the BSP library ile to include additional Altera-supplied sotware packages, such as the read-only zip ile system or TCP/IP networking stack (the NicheStack TCP/IP Stack). Both the BSP library ile and the application project can be conigured to build with dierent parameters, such as compiler optimizations and linker settings. 1 I you change the hardware system, you must recreate, update or regenerate the BSP project to keep the library header iles up-to-date. For inormation about how to keep your BSP up-to-date with your hardware, reer to Revising Your BSP in the Nios II Sotware Build Tools chapter o the Nios II Sotware Developer's Handbook. Sotware Project Mechanics This section describes the recommended ways to edit, build, download, run, and debug your sotware application, primarily using the Nios II Sotware Build Tools or Eclipse. The Nios II Sotware Build Tools low is the recommended design low or hardware designs that contain a Nios II processor. This section describes how to conigure BSP and application projects, and the process o developing a sotware project or a system that contains a Nios II processor, including ensuring coherency between the sotware and hardware designs. This section contains the ollowing subsections: Sotware Tools Background Development Flow Guidelines on page 2 6 Nios II Sotware Build Tools Flow on page 2 7 Coniguring BSP and Application Projects on page 2 8 Ensuring Sotware Project Coherency on page 2 20 July 2011 Altera Corporation Embedded Design Handbook

6 2 6 Chapter 2: Developing Nios II Sotware Sotware Project Mechanics Sotware Tools Background The Nios II EDS provides a sophisticated set o sotware project generation tools to build your application image. Two separate sotware-development methodologies are available or project creation: the Nios II Sotware Build Tools low and the Nios II Integrated Development Environment (IDE) low. The Nios II Sotware Build Tools low includes the Sotware Build Tools command-line interace and the Nios II Sotware Build Tools or Eclipse. The Nios II Sotware Build Tools or Eclipse is the recommended low. However, the Nios II Sotware Build Tools or Eclipse does not support the ollowing Nios II IDE eatures: Trace eatures available in the FS2 console do not work correctly with the System Console debugger. stdio output to an RS-232 UART cannot display on the System Console. To display stdio output on the System Console, conigure your BSP to use a JTAG UART peripheral or stdout, using the hal.stdout BSP setting. I no JTAG UART is available in your hardware system, you can run nios2-terminal in a separate Nios II Command Sheell to capture stdio output. The Nios II Sotware Build Tools development low provides an easily controllable development environment or creating, managing, and coniguring sotware applications. The Nios II Sotware Build Tools include command-line utilities, scripts, and tools or Tcl scripting. Starting in version 9.1 o the Nios II EDS, Altera provides Nios II Sotware Build Tools or Eclipse, which is a user-riendly, graphical user interace (GUI)-based version o the Sotware Build Tools low. 1 Altera recommends that you use the Nios II Sotware Build Tools or Eclipse to create new sotware projects. The Nios II Sotware Build Tools are the basis or Altera s uture development. For inormation about migrating existing Nios II IDE projects to the Nios II Sotware Build Tools low, reer to Porting Nios II IDE Projects to the Sotware Build Tools in the Using the Nios II Integrated Development Environment appendix to the Nios II Sotware Developer's Handbook. 1 In the Nios II IDE design low, the BSP project is called a system library. A graphical user interace or coniguring BSP libraries, called the Nios II BSP Editor, is also available. The BSP Editor is integrated with the Nios II Sotware Build Tools or Eclipse, and can also be used independently. Development Flow Guidelines The Nios II Sotware Build Tools low provides many services and unctions or your use. Until you become amiliar with these services and unctions, Altera recommends that you adhere to the ollowing guidelines to simpliy your development eort: Embedded Design Handbook July 2011 Altera Corporation

7 Chapter 2: Developing Nios II Sotware 2 7 Sotware Project Mechanics Begin with a known hardware design The Nios II Embedded Processor Design Examples web page o the Altera website includes a set o known working designs, called hardware example designs, which are excellent starting points or your own design. In addition, the Nios II Hardware Development Tutorial walks through some example designs. Begin with a known sotware example design The Nios II EDS includes a set o preconigured application projects or you to use as the starting point o your own application. Use one o these designs and parameterize it to suit your application goals. Follow pointers to documentation Many o the application and BSP project source iles include inline comments that provide additional inormation. Make incremental changes Regardless o your end-application goals, develop your sotware application by making incremental, testable changes, to compartmentalize your sotware development process. Altera recommends that you use a version control system to maintain distinct versions o your source iles as you develop your project. The ollowing section describes how to implement these guidelines. Nios II Sotware Build Tools Flow The Nios II Sotware Build Tools are a collection o command-line utilities and scripts. These tools allow you to build a BSP project and an application project to create an application image. The BSP project is a parameterizable library, customized or the hardware capabilities and peripherals in your system. When you create a BSP library ile rom the BSP project, you create it with a speciic set o parameter values. The application project consists o your application source iles and the application makeile. The source iles can reerence services provided by the BSP library ile. For the ull list o utilities and scripts in the Nios II Sotware Build Tools low, reer to Altera-Provided Embedded Development Tools in the Nios II Sotware Build Tools chapter o the Nios II Sotware Developer's Handbook. The Nios II Sotware Build Tools or Eclipse The Nios II Sotware Build Tools or Eclipse provide a consistent development platorm that works or all Nios II processor systems. You can accomplish most sotware development tasks in the Nios II Sotware Build Tools or Eclipse, including creating, editing, building, running, debugging, and proiling programs. The Nios II Sotware Build Tools or Eclipse are based on the popular Eclipse ramework and the Eclipse C/C++ development toolkit (CDT) plug-ins. Simply put, the Nios II Sotware Build Tools or Eclipse provides a GUI that runs the Nios II Sotware Build Tools utilities and scripts behind the scenes. For detailed inormation about the Nios II Sotware Build Tools or Eclipse, reer to the Getting Started with the Graphical User Interace chapter o the Nios II Sotware Developer's Handbook. For details about Eclipse, visit the Eclipse Foundation website ( July 2011 Altera Corporation Embedded Design Handbook

8 2 8 Chapter 2: Developing Nios II Sotware Sotware Project Mechanics The Nios II Sotware Build Tools Command Line In the Nios II Sotware Build Tools command line development low, you create, modiy, build, and run Nios II programs with Nios II Sotware Build Tools commands typed at a command line or embedded in a script. To debug your program, import your Sotware Build Tools projects to Eclipse. You can urther edit, rebuild, run, and debug your imported project in Eclipse. For urther inormation about the Nios II Sotware Build Tools and the Nios II Command Shell, reer to the Getting Started rom the Command Line chapter o the Nios II Sotware Developer's Handbook. Coniguring BSP and Application Projects This section describes some methods or coniguring the BSP and application projects that comprise your sotware application, while encouraging you to begin your sotware development with a sotware example design. For inormation about using version control, copying, moving and renaming a BSP project, and transerring a BSP project to another person, reer to Common BSP Tasks in the Nios II Sotware Build Tools chapter o the Nios II Sotware Developer's Handbook. Sotware Example Designs The best way to become acquainted with the Nios II Sotware Build Tools low and begin developing sotware or the Nios II processor is to use one o the pre-existing sotware example designs that are provided with the Nios II EDS. The sotware example designs are preconigured sotware applications that you can use as the basis or your own sotware development. The sotware examples can be ound in the Nios II installation directory. For more inormation about the sotware example designs provided in the Nios II EDS, reer to Nios II Embedded Design Examples in the Overview o Nios II Embedded Development chapter o the Nios II Sotware Developer s Handbook. To use a sotware example design, ollow these steps: 1. Set up a working directory that contains your system hardware, including the system.sopcino ile. 1 Ensure that you have compiled the system hardware with the Quartus II sotware to create up-to-date.so and.sopcino iles. 2. Start the Nios II Sotware Build Tools or Eclipse as ollows: In the Windows operating system, on the Start menu, point to Programs > Altera > Nios II EDS <version>, and click Nios II <version> Sotware Build Tools or Eclipse. In the Linux operating system, in a command shell, type eclipse-nios2r. 3. Right-click anywhere in the Project Explorer view, point to New and click Nios II Application and BSP rom Template. Embedded Design Handbook July 2011 Altera Corporation

9 Chapter 2: Developing Nios II Sotware 2 9 Sotware Project Mechanics 4. Select an appropriate sotware example rom the Templates list. 1 You must ensure that your system hardware satisies the requirements or the sotware example design listed under Template description. I you use an Altera Nios II development kit, the sotware example designs supplied with the kit are guaranteed to work with the hardware examples included with the kit. 5. Next to SOPC Inormation File Name, browse to your working directory and select the.sopcino ile associated with your system. 6. In a multiprocessor design, you must select the processor on which to run the sotware project. 1 I your design contains a single Nios II processor, the processor name is automatically illed in. 7. Fill in the project name. 8. Click Next. 9. Select Create a new BSP project based on the application project template. 10. Click Finish. The Nios II Sotware Build Tools generate an Altera HAL BSP or you. 1 I you do not want the Sotware Build Tools or Eclipse to automatically create a BSP or you, at Step 9, select Select an existing BSP project rom your workspace. You then have several options: You can import a pre-existing BSP by clicking Import. You can create a HAL or MicroC/OS-II BSP as ollows: a. Click Create. The Nios II Board Support Package dialog box appears. b. Next to Operating System, select either Altera HAL or Micrium MicroC/OS-II. 1 You can select the operating system only at the time you create the BSP. To change operating systems, you must create a new BSP. Selecting the Operating System (HAL versus MicroC/OS-II RTOS) You have a choice o the ollowing run-time environments (operating systems) to incorporate in your BSP library ile: The Nios II HAL A lightweight, POSIX-like, single-threaded library, suicient or many applications. The MicroC/OS-II RTOS A real-time, multi-threaded environment. The Nios II implementation o MicroC/OS-II is based on the HAL, and includes all HAL services. 1 Ater you select HAL or MicroC/OS-II, you cannot change the operating system or this BSP project. July 2011 Altera Corporation Embedded Design Handbook

10 2 10 Chapter 2: Developing Nios II Sotware Sotware Project Mechanics Coniguring the BSP Project The BSP project is a conigurable library. You can conigure your BSP project to incorporate your optimization preerences size, speed, or other eatures in the custom library you create. This custom library is the BSP library ile (.a) that is used by the application project. Creating the BSP project populates the target directory with the BSP library ile source and build ile scripts. Some o these iles are copied rom other directories and are not overwritten when you recreate the BSP project. Others are generated when you create the BSP project. The most basic tool or coniguring BSPs is the BSP setting. Throughout this chapter, many o the project modiications you can make are based on BSP settings. In each case, this chapter presents the names o the relevant settings, and explains how to select the correct setting value. You can control the value o BSP settings several ways: on the command line, with a Tcl script, by directly adjusting the settings with the BSP Editor, or by importing a Tcl script to the BSP Editor. Another powerul tool or coniguring a BSP is the sotware package. Sotware packages add complex capabilities to your BSP. As when you work with BSP settings, you can add and remove sotware packages on the command line, with a Tcl script, directly with the BSP Editor, or by importing a Tcl script to the BSP Editor. Altera recommends that you use the Nios II BSP Editor to conigure your BSP project. To start the Nios II BSP Editor rom the Nios II Sotware Build Tools or Eclipse, right-click an existing BSP, point to Nios II, and click BSP Editor. For detailed inormation about how to manipulate BSP settings and add and remove sotware packages with the BSP Editor, reer to Using the BSP Editor in the Getting Started with the Graphical User Interace chapter o the Nios II Sotware Developer's Handbook. This chapter also discusses how to use Tcl scripts in the BSP Editor. For inormation about manipulating BSP settings and controlling sotware packages at the command line, reer to Nios II Sotware Build Tools Utilities in the Nios II Sotware Build Tools Reerence chapter o the Nios II Sotware Developer's Handbook. For details about available BSP settings, reer to Settings Managed by the Sotware Build Tools in the Nios II Sotware Build Tools Reerence chapter o the Nios II Sotware Developer's Handbook. For a discussion o Tcl scripting, reer to Sotware Build Tools Tcl Commands in the Nios II Sotware Build Tools Reerence chapter o the Nios II Sotware Developer's Handbook. 1 Do not edit BSP iles, because they are overwritten by the Sotware Build Tools the next time the BSP is generated. MicroC/OS-II RTOS Coniguration Tips I you use the MicroC/OS-II RTOS environment, be aware o the ollowing properties o this environment: MicroC/OS-II BSP settings The MicroC/OS-II RTOS supports many coniguration options. All o these options can be enabled and disabled with BSP settings. Some o the options are enabled by deault. A comprehensive list o BSP settings or MicroC/OS-II is shown in the Settings tab o the Nios II BSP Editor. Embedded Design Handbook July 2011 Altera Corporation

11 Chapter 2: Developing Nios II Sotware 2 11 Sotware Project Mechanics The MicroC/OS-II BSP settings are also described in Settings Managed by the Sotware Build Tools in the Nios II Sotware Build Tools Reerence chapter o the Nios II Sotware Developer's Handbook. MicroC/OS-II setting modiication Modiying the MicroC/OS-II options modiies the system.h ile, which is used to compile the BSP library ile. MicroC/OS-II initialization The core MicroC/OS-II RTOS is initialized during the execution o the C run-time initialization (crt0) code block. Ater the crt0 code block runs, the MicroC/OS-II RTOS resources are available or your application to use. For more inormation, reer to crt0 Initialization on page You can conigure MicroC/OS-II with the BSP Editor. Figure 2 1 shows how you enable the MicroC/OS-II timer and queue code. Figure 2 2 on page 2 12 shows how you speciy a maximum o our timers or use with MicroC/OS-II. Figure 2 1. Enabling MicroC/OS-II Timers and Queues in BSP Editor July 2011 Altera Corporation Embedded Design Handbook

12 2 12 Chapter 2: Developing Nios II Sotware Sotware Project Mechanics The MicroC/OS-II coniguration script in Example 2 1 on page 2 12 perorms the same MicroC/OS-II coniguration as Figure 2 1 and Figure 2 2: it enables the timer and queue code, and speciies a maximum o our timers. Figure 2 2. Coniguring MicroC/OS-II or Four Timers in BSP Editor Example 2 1. MicroC/OS-II Tcl Coniguration Script Example (ucosii_con.tcl) #enable code or UCOSII timers set_setting ucosii.os_tmr_en 1 #enable a maximum o 4 UCOSII timers set_setting ucosii.timer.os_tmr_cg_max 4 #enable code or UCOSII queues set_setting ucosii.os_q_en 1 HAL Coniguration Tips I you use the HAL environment, be aware o the ollowing properties o this environment: Embedded Design Handbook July 2011 Altera Corporation

13 Chapter 2: Developing Nios II Sotware 2 13 Sotware Project Mechanics HAL BSP settings A comprehensive list o options is shown in the Settings tab in the Nios II BSP Editor. These options include settings to speciy a pre- and post-process to run or each C or C++ ile compiled, and or each ile assembled or archived. For more inormation about BSP settings, reer to Settings Managed by the Sotware Build Tools in the Nios II Sotware Build Tools Reerence chapter o the Nios II Sotware Developer's Handbook. HAL setting modiication Modiying the HAL options modiies the system.h ile, which is used to compile the BSP library ile. HAL initialization The HAL is initialized during the execution o the C run-time initialization (crt0) code block. Ater the crt0 code block runs, the HAL resources are available or your application to use. For more inormation, reer to crt0 Initialization on page You can conigure the HAL in the BSP Editor. Figure 2 3 on page 2 14 shows how you speciy a UART to be used as the stdio device. July 2011 Altera Corporation Embedded Design Handbook

14 2 14 Chapter 2: Developing Nios II Sotware Sotware Project Mechanics The Tcl script in Example 2 2 on page 2 14 perorms the same coniguration as Figure 2 3: it speciies a UART to be used as the stdio device. Figure 2 3. Coniguring HAL stdio Device in BSP Editor Example 2 2. HAL Tcl Coniguration Script Example (hal_con.tcl) #set up stdio ile handles to point to a UART set deault_stdio uart1 set_setting hal.stdin $deault_stdio set_setting hal.stdout $deault_stdio set_setting hal.stderr $deault_stdio Adding Sotware Packages Altera supplies several add-on sotware packages in the Nios II EDS. These sotware packages are available or your application to use, and can be conigured in the BSP Editor rom the Sotware Packages tab. The Sotware Packages tab allows you to insert and remove sotware packages in your BSP, and control sotware package settings. The sotware package table at the top o this tab lists each available sotware package. The table allows you to select the sotware package version, and enable or disable the sotware package. 1 The operating system determines which sotware packages are available. The ollowing sotware packages are provided with the Nios II EDS: Embedded Design Handbook July 2011 Altera Corporation

15 Chapter 2: Developing Nios II Sotware 2 15 Sotware Project Mechanics Host File System Allows a Nios II system to access a ile system that resides on the workstation. For more inormation, reer to The Host-Based File System on page Read-Only Zip File System Provides access to a simple ile system stored in lash memory. For more inormation, reer to Read-Only Zip File System on page NicheStack TCP/IP Stack Nios II Edition Enables support o the NicheStack TCP/IP networking stack. For more inormation about the NicheStack TCP/IP networking stack, reer to the Ethernet and the TCP/IP Networking Stack - Nios II Edition chapter o the Nios II Sotware Developer's Handbook. Using Tcl Scripts with the Nios II BSP Editor The Nios II BSP Editor supports Tcl scripting. Tcl scripting in the Nios II BSP Editor is a simple but powerul tool that allows you to easily migrate settings rom one BSP to another. This eature is especially useul i you have multiple sotware projects utilizing similar BSP settings. Tcl scripts in the BSP editor allow you to perorm the ollowing tasks: Regenerate the BSP rom the command line Export a TCL script rom an existing BSP as a starting point or a new BSP Recreate the BSP on a dierent hardware platorm Examine the Tcl script to improve your understanding o Tcl command usage and BSP settings You can conigure a BSP either by importing your own manually-created Tcl script, or by using a Tcl script exported rom the Nios II BSP Editor. 1 You can apply a Tcl script only at the time that you create the BSP. Exporting a Tcl Script To export a Tcl script, ollow these steps: 1. Use the Nios II BSP Editor to conigure the BSP settings in an existing BSP project. 2. In the Tools menu, click Export Tcl Script. 3. Navigate to the directory where you wish to store your Tcl script. 4. Select a ile name or the Tcl script. July 2011 Altera Corporation Embedded Design Handbook

16 2 16 Chapter 2: Developing Nios II Sotware Sotware Project Mechanics When creating a Tcl script, the Nios II BSP Editor only exports settings that dier rom the BSP deaults. For example, i the only nondeault settings in the BSP are those shown in Figure 2 3 on page 2 14, the BSP Editor exports the script shown in Example 2 3. Example 2 3. Tcl Script Exported by BSP Editor ###################################################################### # # This is a generated Tcl script exported # by a user o the Altera Nios II BSP Editor. # # It can be used with the Altera 'nios2-bsp' shell script '--script' # option to customize a new or existing BSP. # ###################################################################### ###################################################################### # # Exported Setting Changes # ###################################################################### set_setting hal.stdout uart1 set_setting hal.stderr uart1 set_setting hal.stdin uart1 For details about deault BSP settings, reer to Speciying BSP Deaults in the Nios II Sotware Build Tools chapter o the Nios II Sotware Developer's Handbook. Importing a Tcl Script to Create a New BSP The ollowing example illustrates how to conigure a new BSP with an imported Tcl script. You import the Tcl script with the Nios II BSP Editor, when you create a new BSP settings ile. 1 In this example, you create the Tcl script by hand, with a text editor. You can also use a Tcl script exported rom another BSP, as described in Exporting a Tcl Script. To conigure a new BSP with a Tcl script, ollow these steps: 1. With any text editor, create a new ile called example.tcl. 2. Insert the contents o Example 2 4 in the ile. Example 2 4. BSP Coniguration Tcl Script example.tcl set_setting hal.enable_reduced_device_drivers true set_setting hal.enable_sim_optimize true set_setting hal.enable_small_c_library true set_setting hal.enable_gpro true 3. In the Nios II BSP Editor, in the File menu, click New BSP. 4. In the BSP Settings File Name box, select a older in which to save your new BSP settings ile. Accept the deault settings ile name, settings.bsp. 5. In the Operating System list, select Altera HAL. 6. In the Additional Tcl script box, navigate to example.tcl. Embedded Design Handbook July 2011 Altera Corporation

17 Chapter 2: Developing Nios II Sotware 2 17 Sotware Project Mechanics 7. In the SOPC Inormation File Name box, select the.sopcino ile. 8. Click OK. The BSP Editor creates the new BSP. The settings modiied by example.tcl appear as in Figure 2 4. Figure 2 4. Nios II BSP Settings Conigured with example.tcl 1 Do not attempt to import an Altera HAL Tcl script to a MicroC/OS-II BSP or vice-versa. Doing so could result in unpredictable behavior, such as lost settings. Some BSP settings are OS-speciic, making scripts rom dierent OSes incompatible. For more inormation about commands that can appear in BSP Tcl scripts, reer to Sotware Build Tools Tcl Commands in the Nios II Sotware Build Tools Reerence chapter o the Nios II Sotware Developer's Handbook. Coniguring the Application Project You conigure the application project by speciying source iles and a valid BSP project, along with other command-line options to the nios2-app-generate-makeile or nios2-app-update-makeile commands. Application Coniguration Tips Use the ollowing tips to increase your eiciency in designing your application project: Source ile inclusion To add source iles to your project, drag them rom a ile browser, such as Windows Explorer, and drop them in the Project Explorer view in the Nios II Sotware Build Tools or Eclipse. From the command line, several options are available or speciying the source iles in your application project. I all your source iles are in the same directory, use the --src-dir command-line option. I all your source iles are contained in a single directory and its subdirectories, use the --src-rdir command-line option. July 2011 Altera Corporation Embedded Design Handbook

18 2 18 Chapter 2: Developing Nios II Sotware Sotware Project Mechanics Makeile variables When a new project is created in the Nios II Sotware Build Tools or Eclipse, a makeile is automatically generated in the sotware project directory. You can modiy application makeile variables with the Nios II Application Wizard. From the command line, set makeile variables with the --set <var> <value> command-line option during coniguration o the application project. The variables you can set include the pre- and post-processing settings BUILD_PRE_PROCESS and BUILD_POST_PROCESS to speciy commands to be executed beore and ater building the application. Examine a generated application makeile to ensure you understand the current and deault settings. Creating top level generation script From the command line, simpliy the parameterization o your application project by creating a top level shell script to control the coniguration. The create-this-app scripts in the embedded processor design examples available rom the Nios II Embedded Processor Design Examples web page are good models or your coniguration script. Linking User Libraries You can create and use your own user libraries in the Nios II Sotware Build Tools. The Nios II Sotware Build Tools or Eclipse includes the Nios II Library wizard, which enables you to create a user library in a GUI environment. You can also create user libraries in the Nios II Command Shell, as ollows: 1. Create the library using the nios2-lib-generate-makeile command. This command generates a public.mk ile. 2. Conigure the application project with the new library by running the nios2-app-generate-makeile command with the --use-lib-dir option. The value or the option speciies the path to the library's public.mk ile. Makeiles and the Nios II Sotware Build Tools or Eclipse The Nios II Sotware Build Tools or Eclipse create and manage the makeiles or Nios II sotware projects. When you create a project, the Nios II Sotware Build Tools create a makeile based on parameters and settings you select. When you modiy parameters and settings, the Nios II Sotware Build Tools update the makeile to match. BSP makeiles are based on the operating system, BSP settings, selected sotware packages, and selected drivers. Nios II BSP makeiles are handled dierently rom application and user library makeiles. Nios II application and user library makeiles are based on source iles that you speciy directly. The ollowing changes to an application or user library change the contents o the corresponding makeile: Change the application or user library name Add or remove source iles Speciy a path to an associated BSP Speciy a path to an associated user library Enable, disable or modiy compiler options Embedded Design Handbook July 2011 Altera Corporation

19 Chapter 2: Developing Nios II Sotware 2 19 Sotware Project Mechanics For inormation about BSPs and makeiles, reer to Makeiles and the Nios II Sotware Build Tools or Eclipse in the Getting Started with the Graphical User Interace chapter o the Nios II Sotware Developer's Handbook. Building and Running the Sotware in Nios II Sotware Build Tools or Eclipse Building the Project Ater you edit the BSP settings and properties, and generate the BSP (including the makeile), you can build your project. Right-click your project in the Project Explorer view and click Build Project. Downloading and Running the Sotware To download and run or debug your program, right-click your project in the Project Explorer view. To run the program, point to Run As and click Nios II Hardware. 1 Beore you run your target application, ensure that your FPGA is conigured with the target hardware image in your.so ile. Communicating with the Target The Nios II Sotware Build Tools or Eclipse provide a console window through which you can communicate with your system. When you use the Nios II Sotware Build Tools or Eclipse to communicate with the target, characters you input are transmitted to the target line by line. Characters are visible to the target only ater you press the Enter key on your keyboard. I you conigured your application to use the stdio unctions in a UART or JTAG UART interace, you can use the nios2-terminal application to communicate with your target subsystem. However, the Nios II Sotware Build Tools or Eclipse and the nios2-terminal application handle input characters very dierently. On the command line, you must use the nios2-terminal application to communicate with your target. To start the application, type the ollowing command: nios2-terminal r When you use the nios2-terminal application, characters you type in the shell are transmitted, one by one, to the target. Sotware Debugging in Nios II Sotware Build Tools or Eclipse This section describes how to debug a Nios II program using the Nios II Sotware Build Tools or Eclipse. You can debug a Nios II program on Nios II hardware such as a Nios development board. To debug a sotware project, right-click the application project name, point to Debug As and click Nios II Hardware. 1 Do not select Local C/C++ Application. Nios II projects can only be run and debugged with Nios II run conigurations. For more inormation about using the Nios II Sotware Build Tools or Eclipse to debug your application, reer to the Debugging Nios II Designs chapter o the Embedded Design Handbook. July 2011 Altera Corporation Embedded Design Handbook

20 2 20 Chapter 2: Developing Nios II Sotware Sotware Project Mechanics For debugging purposes, it is useul to enable run-time stack checking, using the hal.enable_runtime_stack_checking BSP setting. When properly used, this setting enables the debugger to take control i the stack collides with the heap or with statically allocated data in memory. For inormation about how to use run-time stack checking, reer to Run-Time Analysis Debug Techniques in the Debugging Nios II Designs chapter o the Embedded Design Handbook. For more inormation about this and other BSP coniguration settings, reer to Settings Managed by the Sotware Build Tools in the Nios II Sotware Build Tools Reerence chapter o the Nios II Sotware Developer's Handbook. Ensuring Sotware Project Coherency In some engineering environments, maintaining coherency between the sotware and system hardware projects is diicult. For example, in a mixed team environment in which a hardware engineering team creates new versions o the hardware, independent o the sotware engineering team, the potential or using the incorrect version o the sotware on a particular version o the system hardware is high. Such an error may cause engineers to spend time debugging phantom issues. This section discusses several design and sotware architecture practices that can help you avoid this problem. Recommended Development Practice The saest sotware development practice or avoiding the sotware coherency problem is to ollow a strict hardware and sotware project hierarchy, and to use scripts to generate your application and BSP projects. One best practice is to structure your application hierarchy with parallel application project and BSP project olders. In Figure 2 5, a top-level hardware project older includes the Quartus II project ile, the SOPC Builder-generated iles, and the sotware project older. The sotware project older contains a subolder or the application project and a subolder or the BSP project. The application project older contains a create-this-app script, and the BSP project older contains a create-this-bsp script. Figure 2 5. Recommended Directory Structure hardware project older <system_name>.sopcino <system_name>.so sotware project older application project older create-this-app clean-this-app application sotware source iles BSP project older create-this-bsp clean-this-bsp bsp_settings.tcl (optional) (1) Note or Figure 2 5: (1) bsp_settings.tcl is a Tcl coniguration ile. For more inormation about the Tcl coniguration ile, reer to Coniguring the BSP Project on page Embedded Design Handbook July 2011 Altera Corporation

21 Chapter 2: Developing Nios II Sotware 2 21 Sotware Project Mechanics To build your own sotware project rom the command line, create your own create-this-app and create-this-bsp scripts. Altera recommends that you also create clean-this-app and clean-this-bsp scripts. These scripts perorm the ollowing tasks: create-this-app This bash script uses the nios2-app-generate-makeile command to create the application project, using the application sotware source iles or your project. The script veriies that the BSP project is properly conigured (a settings.bsp ile is present in the BSP project directory), and runs the create-this-bsp script i necessary. The Altera-supplied create-this-app scripts that are included in the embedded design examples on the Nios II Embedded Processor Design Examples web page o the Altera website provide good models or this script. clean-this-app This bash script perorms all necessary clean-up tasks or the whole project, including the ollowing: Call the application makeile with the clean-all target. Call the clean-this-bsp shell script. create-this-bsp This bash script generates the BSP project. The script uses the nios2-bsp command, which can optionally call the coniguration script bsp_settings.tcl. The nios2-bsp command reerences the <system_name>.sopcino ile located in the hardware project older. Running this script creates the BSP project, and builds the BSP library ile or the system. clean-this-bsp This bash script calls the clean target in the BSP project makeile and deletes the settings.bsp ile. The complete system generation process, rom hardware to BSP and application projects, must be repeated every time a change is made to the system in SOPC Builder. Thereore, deining all your settings in your create-this-bsp script is more eicient than using the Nios II BSP Editor to customize your project. The system generation process ollows: 1. Hardware iles generation Using SOPC Builder, write the updated system description to the <system_name>.sopcino ile. 2. Regenerate BSP project Generate the BSP project with the create-this-bsp script. 3. Regenerate application project Generate the application project with the create-this-app script. This script typically runs the create-this-bsp script, which builds the BSP project by creating and running the makeile to generate the BSP library ile. 4. Build the system Build the system sotware using the application and BSP makeile scripts. The create-this-app script runs make to build both the application project and the BSP library. To implement this system generation process, Altera recommends that you use the ollowing checklists or handing o responsibility between the hardware and sotware groups. 1 This method assumes that the hardware engineering group installs the Nios II EDS. I so, the hardware and sotware engineering groups must use the same version o the Nios II EDS toolchain. July 2011 Altera Corporation Embedded Design Handbook

22 2 22 Chapter 2: Developing Nios II Sotware Sotware Project Mechanics To hand o the project rom the hardware group to the sotware group, perorm the ollowing steps: 1. Hardware project hand-o The hardware group provides copies o the <system_name>.sopcino and <system_name>.so iles. The sotware group copies these iles to the sotware group s hardware project older. 2. Recreate sotware project The sotware team recreates the sotware application or the new hardware by running the create-this-app script. This script runs the create-this-bsp script. 3. Build The sotware team runs make in its application project directory to regenerate the sotware application. To hand o the project rom the sotware group to the hardware group, perorm the ollowing steps: 1. Clean project directories The sotware group runs the clean-this-app script. 2. Sotware project older hand-o The sotware group provides the hardware group with the sotware project older structure it generated or the latest hardware version. Ideally, the sotware project older contains only the application project iles and the application project and BSP generation scripts. 3. Reconigure sotware project The hardware group runs the create-this-app script to reconigure the group s application and BSP projects. 4. Build The hardware group runs make in the application project directory to regenerate the sotware application. Recommended Architecture Practice Many o the hardware and sotware coherency issues that arise during the creation o the application sotware are problems o misplaced peripheral addresses. Because o the lexibility provided by SOPC Builder, almost any peripheral in the system can be assigned an arbitrary address, or have its address modiied during system creation. Implement the ollowing practices to prevent this type o coherency issue during the creation o your sotware application: Peripheral and Memory Addressing The Nios II Sotware Build Tools automatically generate a system header ile, system.h, that deines a set o #deine symbols or every peripheral in the system. These deinitions speciy the peripheral name, base address location, and address span. I the Memory Management Unit (MMU) is enabled in your Nios II system, veriy that the address span or all peripherals is located in direct-mapped memory, outside the memory address range managed by the MMU. To protect against coherency issues, access all system peripherals and memory components with their system.h name and address span symbols. This method guarantees successul peripheral register access even ater a peripheral's addressable location changes. For example, i your system includes a UART peripheral named UART1, located at address 0x1000, access the UART1 registers using the system.h address symbol (iowr_32(uart1_base, 0x0, 0x )) rather than using its address (iowr_32(0x1000, 0x0, 0x )). Embedded Design Handbook July 2011 Altera Corporation