MULTI: Building Applications for Embedded ARM Green Hills Software, Inc. 30 West Sola Street Santa Barbara, California 93101 USA Tel: 805-965-6044 Fax: 805-965-6343 www.ghs.com DISCLAIMER GREENHILLSSOFTWARE,INC.,MAKESNOREPRESENTATIONSORWARRANTIESWITHRESPECT TO THE CONTENTSHEREOFAND SPECIFICALLY DISCLAIMSANY IMPLIED WARRANTIES OF MERCHANTABILITYORFITNESSFORANYPARTICULARPURPOSE.Further,GreenHillsSoftware,Inc., reservestherighttorevisethispublicationandtomakechangesfromtimetotimeinthecontenthereofwithoutobligation ofGreenHillsSoftware,Inc.,tonotifyanypersonofsuchrevisionorchanges. Copyright©1983-2005byGreenHillsSoftware,Inc. Allrightsreserved. Nopartofthispublicationmaybereproduced, storedinaretrievalsystem,ortransmitted,inanyformorbyanymeans,electronic,mechanical,photocopying,recording, orotherwise,withoutpriorwrittenpermissionfromGreenHillsSoftware,Inc. GreenHills, the GreenHillslogo, CodeBalance, GMART, GSTART,INTEGRITY,andMULTIareregistered trademarksofGreenHillsSoftware,Inc. AdaMULTI,EventAnalyzer,G-Cover,GHnet,GHnetLite,GreenHillsProbe, Integrate,ISIM,PathAnalyzer,QuickStart,ResourceAnalyzer,SafetyCriticalProducts,Slingshot,SuperTraceProbe, TimeMachine,andTotalDeveloperaretrademarksofGreenHillsSoftware,Inc. Allothercompany,product,orservicenamesmentionedinthisbookmaybetrademarksorservicemarksoftheir respective owners. PubID:10379 October24, 2005 Contents 1 Introduction 1 The MULTI Integrated Development Environment 2 The MULTI Launcher 4 MULTI Workspaces 5 The MULTI 4.0 Document Set 6 About This Book 7 The MULTI Builder 8 The C and C++ Compiler Driver 9 The Optimizing Compilers 9 The asarm Assembler 10 The ax Librarian 10 The elxr Linker 11 Optimized Libraries and Header Files 11 Utility Programs 11 The CodeBalance Optimization Wizard 11 ARM Recommended Reading 12 Online Help 13 Viewing Help on Windows Systems 13 Viewing Help on UNIX Systems 14 Conventions Used in This Book 15 Part I Using the MULTI Builder and Compiler Drivers 2 The MULTI Builder 19 Starting the Builder 22 The Build Cycle 23 Creating a New Project: The New Project Wizard 24 Selecting a Target 24 Selecting a Project 25 Setting Link Options 26 Setting C Language Options 27 Setting C++ Language Options 28 Setting Optimizations and Run-Time Checks 29 Green Hills Software, Inc. i Contents Opening the New Project in the MULTI Debugger 30 Working with Project Files 31 Green Hills Project Files 31 Builder File Types 32 Creating New Project Files 34 Adding Existing Source Files To Your Project 35 Creating New Source Files For Your Project 35 Linking with a Library that is Built with Your Project 36 Linking with a Pre-Built Library 37 Adding Header Files 37 Changing File Types 38 Editing the Project Hierarchy 38 Editing Project Files 39 Searching for Project Files 40 Searching in Files 40 Working with Linker Directives Files 43 Setting Builder Options 50 The Options Window 50 Setting Build Option Macros 58 Importing Environment Variables 60 Inheriting Options from Parent Build Files 61 Setting Options for Projects and Subprojects 61 Setting Options for Source Files 61 Building Your Project 62 Using the File Shortcut Bar 63 Building Platform-Specific Programs from the Same Source Files 64 3 The Compiler Driver 65 The Compiler Driver Syntax 67 Building an Executable from C or C++ Source Files 68 Working with Input Files 69 Recognized Input File Types 69 Passing Multiple Input File Types to the Driver 70 Passing Linker Directives Files to the Driver 70 Generating Other Output File Types 71 Creating Libraries 72 Adding and Updating Files in Libraries 72 Driver Options for Intermediate Forms of Output 73 ii MULTI: Building Applications for Embedded ARM Contents Recognized Output File Types 74 Controlling Driver Information 75 Using a Driver Options File 76 Using makefiles 78 Generating Dependency and Header File Information 81 4 Developing for ARM 83 ARM Characteristics 84 Register Usage 85 Structure Packing 86 Specifying an ARM Target 89 ARM Processor Variants 90 Generating Debugging Information 91 Obtaining Profiling Information 93 Optimizing Your Executable 95 Reducing Program Size 95 Increasing Program Speed 95 Using Your Own Header Files and Libraries 96 Instructing the Compiler to Search for Your Headers 96 Instructing the Compiler to Link Against Your Libraries 99 Controlling the Assembler 99 Controlling the Linker 100 Thumb Mode 101 Mixed ARM/Thumb 102 Working with Memory Models 106 Program Sections 106 Position Independent Code (PIC) 112 Position Independent Data (PID) 114 Near and Far Function Calls 115 Storing Global Variables in Registers 118 Customizing the Green Hills Run-Time Environment 119 Other Topics 120 Renaming the Output Executable 120 Specifying an Alternate Program Start Address 120 Writing Interrupt Routines 120 Symbolic Memory-Mapped I/O 122 Green Hills Software, Inc. iii Contents Viewpathing: Setting Relative Workspace Paths 123 Advanced Optimization Strategies 127 5 Builder and Driver Options 129 Target Options 131 Floating-Point 132 Memory Models 133 Instruction Set 135 Operating System 135 Project Options 140 Optimization Options 143 Optimization Scope 144 Individual Functions 146 Debugging Options 147 Preprocessor Options 150 C/C++ Compiler Options 151 MISRA C 154 Data Types 163 Alignment & Packing 165 C/C++ Data Allocation 166 Special Tokens 167 C++ 169 Assembler Options 180 Linker Options 183 Linker Optimizations 186 Start and End Files 187 Symbols 188 Linker Output Analysis 189 Link-Time Checking 190 Compiler Diagnostics Options 191 Varying Message Format 192 C/C++ Messages 192 Advanced Options 197 Advanced Target Options 197 Advanced Project Options 198 Advanced Optimization Options 203 Advanced Debugging Options 206 Advanced Preprocessor Options 210 iv MULTI: Building Applications for Embedded ARM Contents Advanced C/C++ Compiler Options 212 Advanced Assembler Options 216 Advanced Linker Options 216 Advanced Support Diagnostics Options 219 Driver Option Synonyms 220 6 The Builder GUI Reference 223 The File Menu 224 The Edit Menu 225 The Target Selector Dialog Box 228 The Build Menu 229 The Advanced Build Dialog Box 230 The Build Settings Dialog Box 231 The Connect Menu 232 The Debug Menu 233 The Tools Menu 234 The Utility Program Launcher Dialog Box 236 The Windows Menu 236 The Help Menu 237 Part II Using Advanced Tools 7 The asarm Assembler 241 Running the Assembler from the Builder or Driver 242 Generating Assembly Language Files 243 Running the Assembler Directly 243 Assembler Options 244 General Assembler Options 244 Assembler Syntax 245 Character Set 245 Identifiers 245 Reserved Symbols 246 Source Statements 249 Expressions 250 Assignment Statements 250 Scalar Expression Operators 251 Expression Types 252 Green Hills Software, Inc. v Contents Type Combinations 252 Labels 253 Current Location 253 Reading the Compiler’s Assembly Output 254 Header Comment File 254 Function Comment Section 255 File Comment Section 255 Source Line Comments 255 Porting Guide for ARM Limited Assembly 256 Driver and Builder Options 256 Assembler Options 256 Support for ARM Ltd. Syntax 257 Support for ARM Ltd. Variables 258 Support for ARM Ltd. Expressions 258 Support for ARM Ltd. Directives 259 ARM Address Operators 263 8 Assembler Directives 265 Alignment Directives 266 Conditional Assembly Directives 267 Data Initialization Directives 268 File Inclusion Directives 269 Macro Definition Directives 269 Repeat Block Directives 271 Section Control Directives 272 Symbol Definition Directives 273 Symbolic Debugging Directives 275 Miscellaneous Directives 276 9 The elxr Linker 277 Running the Linker from the Builder or Driver 278 Running the Linker Directly 279 Linker Options 280 Specifying the Program Entry Point 284 Linker Directives Files 285 The OPTION Directive 287 The CONSTANTS Directive 287 vi MULTI: Building Applications for Embedded ARM Contents Memory Maps (the MEMORY Directive) 288 Section Maps (the SECTIONS Directive) 289 Expressions 295 Modifying your Section Map for Speed or Size 297 Customizing the Run-Time Environment Program Sections 299 Symbol Definitions 302 Beginning, End, and Size of Section Symbols 302 End of Function Symbols 303 Linker Generated Tables 304 Deleting Unused Functions 305 Advanced Linker Features 307 Code Factoring 307 Compressed ROM 309 Section-information Section (.secinfo) 310 Obtaining Run-Time Section Information 310 Run-Time Clear and Copy Tables 310 Porting to the elxr Linker from the old lx Linker 311 Working with ARM ADS Object Files 312 10 The ax Librarian 313 Creating a Library from the Builder 314 Creating a Library from the Compiler Driver 314 Modifying Libraries 315 Librarian Commands 315 Creating and Updating Tables of Contents 317 11 Utility Programs 319 The gasmlist Utility Program 321 The gbin2c Utility Program 325 Global Options 325 Module Inclusion Options 327 Local Options 327 The gbincmp Utility Program 333 The gbldconvert Utility Program 335 The gbuild Utility Program 336 Using gbuild 339 The gcolor Utility Program 342 Green Hills Software, Inc. vii Contents Color Configuration Files 343 Rules Files 344 The gcompare Utility Program 346 The gdump Utility Program 349 Debugging File Options 349 ELF File Options 350 COFF File Options 353 BSD File Options 355 The gfile Utility Program 356 The gfunsize Utility Program 357 The ghexfile Utility Program 358 Address Space 359 Data Splitting 360 The ghide Utility Program 362 The gmemfile Utility Program 363 Data Splitting 365 The gnm Utility Program 370 General Options 370 ELF File Options 370 BSD File Options 371 Output Formats 372 The gpjmodify Utility Program 375 Editing Existing .gpj Files 375 Creating a New .gpj File 376 Generating a makefile 377 The grun Utility Program 378 The gsize Utility Program 380 The gsrec Utility Program 382 S-Record Output Format 384 Data and Termination Records 384 Data Splitting 385 The gstack Utility Program 387 Caveats 388 The gstrip Utility Program 389 The gversion Utility Program 390 The gwhat Utility Program 392 Version Extract Mode 392 viii MULTI: Building Applications for Embedded ARM