LatticeMico32 Software Developer User Guide May 2014 Copyright Copyright © 2014 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, CleanClock, Custom Mobile Device, DiePlus, E2CMOS, ECP5, Extreme Performance, FlashBAK, FlexiClock, flexiFLASH, flexiMAC, flexiPCS, FreedomChip, GAL, GDX, Generic Array Logic, HDL Explorer, iCE Dice, iCE40, iCE65, iCEblink, iCEcable, iCEchip, iCEcube, iCEcube2, iCEman, iCEprog, iCEsab, iCEsocket, IPexpress, ISP, ispATE, ispClock, ispDOWNLOAD, ispGAL, ispGDS, ispGDX, ispGDX2, ispGDXV, ispGENERATOR, ispJTAG, ispLEVER, ispLeverCORE, ispLSI, ispMACH, ispPAC, ispTRACY, ispTURBO, ispVIRTUAL MACHINE, ispVM, ispXP, ispXPGA, ispXPLD, Lattice Diamond, LatticeCORE, LatticeEC, LatticeECP, LatticeECP-DSP, LatticeECP2, LatticeECP2M, LatticeECP3, LatticeECP4, LatticeMico, LatticeMico8, LatticeMico32, LatticeSC, LatticeSCM, LatticeXP, LatticeXP2, MACH, MachXO, MachXO2, MachXO3, MACO, mobileFPGA, ORCA, PAC, PAC-Designer, PAL, Performance Analyst, Platform Manager, ProcessorPM, PURESPEED, Reveal, SensorExtender, SiliconBlue, Silicon Forest, Speedlocked, Speed Locking, SuperBIG, SuperCOOL, SuperFAST, SuperWIDE, sysCLOCK, sysCONFIG, sysDSP, sysHSI, sysI/O, sysMEM, The Simple Machine for Complex Design, TraceID, 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. 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 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. ii LatticeMico32 Software Developer User Guide 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 iv LatticeMico32 Software Developer User Guide Contents Chapter 1 LatticeMico System Overview 1 LatticeMico System Design Flow 1 Device Support 3 Design Flow Steps 4 About LatticeMico System Software Projects 6 Project/Build Management 6 Application Debugging 6 Software Deployment 7 Related Documentation 7 Chapter 2 Using the LatticeMico System Software 9 LatticeMico System Software Overview 9 About the LatticeMico System Tools 9 LatticeMico System Requirements 10 Running LatticeMico System 10 LatticeMico System Perspectives 10 Using C/C++ SPE to Develop Your Software 15 Starting C/C++ SPE 15 Creating Software Projects 17 Basic Project Operations 20 Understanding the Build Process 24 Building Your Software Project 25 Setting Project Properties 26 Rebuilding Your Software Project 30 Performing Builds Automatically 30 Using LatticeMico System as a Stand-Alone Tool 31 Running the Debugger on Your Code 32 Debugging and Executing Your Code 34 Common Debugging Tasks 41 Running the Software from the Command Line 42 Opening the SDK Shell 42 LatticeMico32 Software Developer User Guide v CONTENTS Command-Line Managed Project Builds 43 Command-Line Unmanaged Project Builds 44 Chapter 3 LatticeMico Run-Time Environment 45 Build/Compilation Utilities 45 Run-Time Libraries 45 Newlib C and Math Libraries 46 Device Drivers and Services 52 Services Available at Run Time 53 Device Driver APIs 56 Basic Program Structure 57 Creating a Blank Project 58 Adding a Source File to the Project 59 Adding Source to the Source file 61 Building the Application 62 Boot Sequence and crt0ram.S 64 The int main(void) Function 73 Context Save/Restore in Interrupt Exception 73 Boot Sequence 76 EBA and DEBA 77 Boot Code Sequence Flow 79 LatticeMico32 Microprocessor Usage 80 Data Types 80 Byte Order 80 Interrupt Management 81 Cache Management 88 Sleep (Busy) Functions 89 Microprocessor Control Register Access 90 Macros 90 Run-Time Services 91 Device Lookup Service 91 LatticeMico System Timer Services 95 LatticeMico File Service 98 CFI Flash Device Service 105 Chapter 4 Device Driver Framework 121 Overview 121 Supported Components 122 Modifying Existing Device Drivers 123 Overriding Default Driver Initialization Sequence 123 Overriding Default Driver Implementation 124 Enhancing CFI Flash Service 125 Making Devices Available to Lookup Service 130 File Operations 131 File Operations Functions 131 File Device and LatticeMico File Service 132 Maximum File Descriptors 136 Developing File Device Drivers 137 Implementing the Operation Functions 138 Registering the Driver as a File Device 139 File Device Function Handlers 142 vi LatticeMico32 Software Developer User Guide CONTENTS Chapter 5 Managed Build Process and Directory Structure 145 Creating Managed Build Applications 145 LatticeMico C/C++ Project Build Flow 146 The Build Process 147 Build Directory Structure 148 Platform Library-Generated Source Files 155 DDStructs.h File 157 DDStructs.c File 159 DDInit.c File 160 System_Conf.h File 161 Component Software Elements 168 Chapter 6 Advanced Programming Topics 175 Linker Script and Memory Sections 175 Software Deployment 178 Deployment Strategies 178 Deploying to On-Chip Memory 179 Deploying to Multiple On-Chip Memory 190 Deploying to a Flash Device 193 Deploying to SPI Flash Using Deployment Tool 199 Deploying Applications Across Different Memory Components 211 Device Drivers and Multitasking 244 Standard-Make Projects 244 Creating a LatticeMico Library Project 245 Creating a LatticeMico Standard-Make Project 250 Chapter 7 Software Development Utilities 281 Build Tools 281 lm32-elf-ar 281 lm32-elf-as 283 lm32-elf-gcc 285 lm32-elf-ld 287 lm32-elf-nm 292 lm32-elf-objcopy 293 lm32-elf-objdump 296 lm32-elf-size 298 Debug Tools 299 lm32-elf-gdb 299 Glossary 301 Index 307 LatticeMico32 Software Developer User Guide vii CONTENTS viii LatticeMico32 Software Developer User Guide Chapter 1 LatticeMico 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 LatticeMico run-time environment, the managed build environment, and its associated directory structure. “Device Driver Framework” on page 121 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 LatticeMico System Software” on page 9, with “Software Development Utilities” on page 281 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. LatticeMico System Design Flow This section lists the major steps involved in designing a LatticeMico32 embedded microprocessor. In addition to running the FPGA flow in Lattice Diamond, you will use the LatticeMico System software to build both hardware and software features of your embedded soft-core microprocessor. The LatticeMico System software is composed of three bundled applications: Mico System Builder (MSB) C/C++ Software Project Environment (C/C++ SPE) Debugger These applications work in the background