LatticeMico32 Software Developer User Guide Lattice Semiconductor Corporation 5555 NE Moore Court Hillsboro, OR 97124 (503) 268-8000 May 2007 Copyright Copyright © 2007 Lattice Semiconductor Corporation. This document may not, in whole or part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine- readable form without prior written consent from Lattice Semiconductor Corporation. Trademarks Lattice Semiconductor Corporation, L Lattice Semiconductor Corporation (logo), L (stylized), L (design), Lattice (design), LSC, E2CMOS, Extreme Performance, FlashBAK, flexiFlash, flexiMAC, flexiPCS, FreedomChip, GAL, GDX, Generic Array Logic, HDL Explorer, IPexpress, ISP, ispATE, ispClock, ispDOWNLOAD, ispGAL, ispGDS, ispGDX, ispGDXV, ispGDX2, ispGENERATOR, ispJTAG, ispLEVER, ispLeverCORE, ispLSI, ispMACH, ispPAC, ispTRACY, ispTURBO, ispVIRTUAL MACHINE, ispVM, ispXP, ispXPGA, ispXPLD, LatticeEC, LatticeECP, LatticeECP-DSP, LatticeECP2, LatticeECP2M, LatticeMico8, LatticeMico32, LatticeSC, LatticeSCM, LatticeXP, LatticeXP2, MACH, MachXO, MACO, ORCA, PAC, PAC-Designer, PAL, Performance Analyst, PURESPEED, Reveal, Silicon Forest, Speedlocked, Speed Locking, SuperBIG, SuperCOOL, SuperFAST, SuperWIDE, sysCLOCK, sysCONFIG, sysDSP, sysHSI, sysI/O, sysMEM, The Simple Machine for Complex Design, TransFR, UltraMOS, and specific product designations are either registered trademarks or trademarks of Lattice Semiconductor Corporation or its subsidiaries in the United States and/or other countries. ISP, Bringing the Best Together, and More of the Best are service marks of Lattice Semiconductor Corporation. HyperTransport is a licensed trademark of the HyperTransport Technology Consortium in the U.S. and other jurisdictions. Other product names used in this publication are for identification purposes only and may be trademarks of their respective companies. Disclaimers NO WARRANTIES: THE INFORMATION PROVIDED IN THIS DOCUMENT IS “AS IS” WITHOUT ANY EXPRESS OR IMPLIED WARRANTY OF ANY KIND INCLUDING WARRANTIES OF ACCURACY, COMPLETENESS, MERCHANTABILITY, NONINFRINGEMENT OF INTELLECTUAL PROPERTY, OR FITNESS FOR ANY PARTICULAR PURPOSE. IN NO EVENT WILL LATTICE SEMICONDUCTOR CORPORATION (LSC) OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER (WHETHER DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OF OR INABILITY TO USE THE INFORMATION PROVIDED IN THIS DOCUMENT, EVEN IF LSC HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME JURISDICTIONS PROHIBIT THE EXCLUSION OR LIMITATION OF CERTAIN LIABILITY, SOME OF THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU. LSC may make changes to these materials, specifications, or information, or to the products described herein, at any time without notice. LSC makes no commitment to update this documentation. LSC reserves the right to discontinue any product or service without notice and assumes no obligation LatticeMico32 Software Developer User Guide ii to correct any errors contained herein or to advise any user of this document of any correction if such be made. LSC recommends its customers obtain the latest version of the relevant information to establish, before ordering, that the information being relied upon is current. Type Conventions Used in This Document Convention Meaning or Use Bold Items in the user interface that you select or click. Text that you type into the user interface. <Italic> Variables in commands, code syntax, and path names. Ctrl+L Press the two keys at the same time. Courier Code examples. Messages, reports, and prompts from the software. ... Omitted material in a line of code. Omitted lines in code and report examples. [ ] Optional items in syntax descriptions. In bus specifications, the brackets are required. ( ) Grouped items in syntax descriptions. { } Repeatable items in syntax descriptions. | A choice between items in syntax descriptions. LatticeMico32 Software Developer User Guide iii LatticeMico32 Software Developer User Guide iv Contents Chapter 1 LatticeMico32 System Overview 1 LatticeMico32 System Design Flow 1 Device Support 3 Design Flow Steps 4 About LatticeMico32 System Software Projects 6 Project/Build Management 6 Application Debugging 6 Software Deployment 7 Related Documentation 7 Chapter 2 Using the LatticeMico32 System Software 9 LatticeMico32 System Software Overview 9 About the LatticeMico32 System Tools 9 Running the LatticeMico32 System 10 LatticeMico32 System Perspectives 10 Creating an ispLEVER Project 14 Defining a Hardware Platform in MSB 15 Starting MSB 15 Creating a Platform Description in MSB 17 Connecting Master and Slave Ports 20 Changing Master Port Arbitration Priorities 21 Assigning Component Addresses 22 Assigning Component Interrupt Priorities 23 Performing Design Rule Checks 24 Saving Your Platform 24 Generating Your Platform 24 Generating the Microprocessor Bitstream 25 Downloading Hardware Bitstream to the FPGA 26 Using C/C++ SPE to Develop Your Software 27 Starting C/C++ SPE 27 Creating Software Projects 29 LatticeMico32 Software Developer User Guide v Contents Basic Project Operations 32 Understanding the Build Process 37 Building Your Software Project 39 Setting Project Properties 40 Rebuilding Your Software Project 44 Performing Builds Automatically 44 Running the Debugger on Your Code 45 Debugging and Executing Your Code 47 Common Debugging Tasks 53 Instruction Set Simulator (ISS) 53 Running the Software from the Command Line 54 Opening the SDK Shell 54 Command-Line Managed Project Builds 55 Command-Line Unmanaged Project Builds 57 Chapter 3 LatticeMico32 Run-Time Environment 59 Build/Compilation Utilities 59 Run-Time Libraries 60 Newlib C and Math Libraries 60 Device Drivers and Services 67 Services Available at Run Time 67 Device Driver APIs 71 Basic Program Structure 72 Creating a Blank Project 73 Adding a Source File to the Project 75 Adding Source to the Source file 77 Building the Application 78 Boot Sequence and crt0ram.S 80 The int main(void) Function 89 Context Save/Restore in Interrupt Exception 89 Boot Sequence 92 EBA and DEBA 92 Boot Code Sequence Flow 94 LatticeMico32 Microprocessor Usage 95 Data Types 95 Byte Order 96 Interrupt Management 96 Cache Management 102 Sleep (Busy) Functions 103 Microprocessor Control Register Access 105 Macros 105 Run-Time Services 106 Device Lookup Service 106 LatticeMico32 System Timer Services 110 LatticeMico32 File Service 113 CFI Flash Device Service 121 Chapter 4 Device Driver Framework 137 Overview 137 Supported Components 138 Modifying Existing Device Drivers 139 LatticeMico32 Software Developer User Guide vi Contents Overriding Default Driver Initialization Sequence 139 Overriding Default Driver Implementation 140 Enhancing CFI Flash Service 141 Making Devices Available to Lookup Service 146 File Operations 148 File Operations Functions 148 File Device and LatticeMico32 File Service 150 Maximum File Descriptors 153 Developing File Device Drivers 154 Implementing the Operation Functions 155 Registering the Driver as a File Device 157 File Device Function Handlers 159 Chapter 5 Managed Build Process and Directory Structure 163 Creating Managed Build Applications 163 LatticeMico32 C/C++ Project Build Flow 164 The Build Process 165 Build Directory Structure 166 Platform Library-Generated Source Files 173 DDStructs.h File 175 DDStructs.c File 177 DDInit.c File 178 System_Conf.h File 179 Component Software Elements 186 Chapter 6 Advanced Programming Topics 193 Software Deployment 193 Deployment and Application Sections 194 Deploying to On-Chip Memory 195 Deploying to a Parallel Flash Device 205 Deploying to SPI Flash 212 Linker Script and Memory Sections 236 RTOS Support 238 MicroC/OS-II Real-Time Kernel 238 MicroC/OS-II Port 239 OS Run-Time Initialization Sequence 240 Device Drivers and Multitasking 241 Newlib C Library and Multitasking 241 OS-Aware Debugging 242 Standard-Make Projects 242 Creating a LatticeMico32 Library Project 243 Creating a LatticeMico32 Standard-Make Project 249 Software Development Utilities 279 Build Tools 279 lm32-elf-ar 279 lm32-elf-as 281 lm32-elf-gcc 283 lm32-elf-ld 285 lm32-elf-nm 290 lm32-elf-objcopy 291 LatticeMico32 Software Developer User Guide vii Contents lm32-elf-objdump 294 lm32-elf-size 296 Debug Tools 297 lm32-elf-gdb 297 Glossary 299 Index 305 LatticeMico32 Software Developer User Guide viii 1 LatticeMico32 System Overview This software developer’s guide describes the flow of tools involved in creating, debugging, and deploying the software application code for the LatticeMico32 embedded microprocessor. In addition, it familiarizes you with the LatticeMico32 run-time environment, the managed build environment, and its associated directory structure. “Device Driver Framework” on page 137 describes the device driver framework and the advanced issues related to developing custom device drivers. Some treatment is also given to a command-line approach in “Using the LatticeMico32 System Software” on page 9, with “Software Development Utilities” on page 279 containing tool syntax and options for usage. This guide is targeted to software programmers who are interested in learning the fundamentals of programming the embedded soft-core microprocessor. For a list of related documents on the LatticeMico32 microprocessor, refer to “Related Documentation” on page 7. LatticeMico32 System Design Flow This section lists the major steps involved in designing a LatticeMico32 embedded microprocessor.