ICCV8 for Cortex – C Compiler for ARM Cortex-M INTRODUCTION.............................................................................................5 Version, Trademarks, and Copyrights.................................................. 5 Software License Agreement................................................................ 6 IMPORTANT: Licensing the Software................................................ 8 Transferring a License to Another Computer....................................... 9 Using the Hardware Dongle ............................................................... 10 Annual Maintenance........................................................................... 11 Support................................................................................................ 12 Product Updates.................................................................................. 14 File Types and File Extensions........................................................... 15 ImageCraft C Compiler Extensions.................................................... 17 Converting from Other ANSI C Compilers........................................ 19 Optimizations...................................................................................... 20 Acknowledgments.............................................................................. 23 GETTING STARTED.....................................................................................25 Quick Start Guide............................................................................... 25 Example Projects................................................................................ 27 EMBEDDED PROGRAMMING....................................................................29 Embedded Programming Basics......................................................... 29 Some Pitfalls....................................................................................... 30 Best Practices...................................................................................... 32 Bit Twiddling...................................................................................... 34 General Debugging Hints................................................................... 36 CODE::BLOCKS IDE.....................................................................................39 Code::Blocks IDE............................................................................... 39 Useful General Settings for CodeBlocks IDE.................................... 41 ImageCraft Enhancements to CodeBlocks......................................... 42 IDE and the Compiler......................................................................... 43 Project Management........................................................................... 44 Editor.................................................................................................. 46 Handy CodeBlocks Editor Features.................................................... 47 Multi-Target Support and Build Properties........................................ 48 C::B Supported Variables................................................................... 55 Menu Reference: Build Options - Project........................................... 59 Build Options - Paths.......................................................................... 60 Build Options - Compiler................................................................... 61 1 ICCV8 for Cortex – C Compiler for ARM Cortex-M Build Options - Target........................................................................ 63 Project - Debug/Download Interface.................................................. 65 JUMPSTART DEBUGGER............................................................................67 JumpStart Debugger JDB................................................................... 67 Installing the USB Drivers.................................................................. 68 Debugger Operations.......................................................................... 69 CodeBlocks Debugger Functions....................................................... 72 Advanced Debug Toolbar (ADT) Functions...................................... 75 C PREPROCESSOR........................................................................................79 C Preprocessor Dialects...................................................................... 79 Predefined Macros.............................................................................. 80 Pragmas............................................................................................... 82 Supported Directives........................................................................... 85 String Literals and Token Pasting....................................................... 87 C IN 16 PAGES...............................................................................................89 Preamble............................................................................................. 89 Declaration.......................................................................................... 92 Expressions and Type Promotions...................................................... 95 Statements......................................................................................... 100 C LIBRARY AND STARTUP FILE............................................................103 C Library General Description......................................................... 103 Overriding a Library Function.......................................................... 104 Startup File........................................................................................ 105 Header Files...................................................................................... 106 Character Type Functions................................................................. 107 Floating-Point Math Functions......................................................... 109 Standard IO Functions...................................................................... 111 Standard Library And Memory Allocation Functions...................... 115 String Functions................................................................................ 118 Variable Argument Functions........................................................... 121 PROGRAMMING THE CORTEX-M..........................................................123 CMSIS (Cortex Microcontroller Software Interface Standard)........ 124 Interrupt and Reset Handling............................................................ 126 Clock Source..................................................................................... 130 Programming the STM32 MCU Peripherals.................................... 131 Cortex-M Compiler-Specific Information........................................ 135 2 ICCV8 for Cortex – C Compiler for ARM Cortex-M C RUNTIME ARCHITECTURE..................................................................137 Data Type Sizes................................................................................ 137 Assembly Interface and Calling Conventions.................................. 139 C Machine Routines.......................................................................... 141 Memory Map.................................................................................... 142 Program Areas.................................................................................. 143 Stack and Heap Functions................................................................. 145 COMMAND-LINE COMPILER OVERVIEW............................................147 Compilation Process......................................................................... 147 Driver................................................................................................ 148 Compiler Arguments......................................................................... 149 Preprocessor Arguments................................................................... 151 Compiler Arguments......................................................................... 152 Assembler Arguments....................................................................... 153 Linker Arguments............................................................................. 154 TOOL REFERENCES...................................................................................157 MISRA / Lint Code Checking.......................................................... 157 Code Compressor (tm)...................................................................... 168 Assembler Syntax............................................................................. 171 Assembler Directives........................................................................ 175 Linker Operations............................................................................. 180 ImageCraft Debug Format................................................................ 181 Librarian............................................................................................ 189 3 ICCV8 for Cortex – C Compiler for ARM Cortex-M 4 INTRODUCTION Version, Trademarks, and Copyrights About this Document This document describes version 8 of the product. The printed document and the online help are generated from a single source. Since we update our products frequently, sometimes the printed document becomes out of phase with the shipping product. When in doubt, please refer to the online document for the most up-to-date information. This document was last updated on September 14, 2016 1:18 am. Trademarks and Copyrights ImageCraft, ICC08, ICC11, ICC12, ICC16, ICCAVR, ICCtiny, ICCM8C, ICC430, ICCV7 for AVR, ICCV7 for ARM, ICCV7 for 430, ICCV7 for CPU12, ICCV7 for Propeller, ICCV8 for AVR, ICCV8 for Cortex, JumpStarter C, JumpStart Debugger, MIO (Machine Independent Optimizer) and Code Compressor™, and this document copyright © 1999-2014 by ImageCraft Creations Inc. All rights reserved. Atmel, AVR, MegaAVR, tinyAVR, XMega, Atmel Studio ® Atmel Corporation. Motorola, HC08, MC68HC11, MC68HC12 and MC68HC16 ® Motorola Inc. and Freescale Semiconductor Inc. ARM, Thumb, Thumb2, Cortex ® ARM Inc. All trademarks belong to their respective owners. ICCV8 for Cortex – C Compiler for ARM Cortex-M Software License Agreement This is a legal agreement between you, the end user, and ImageCraft. If you do not agree to the terms of this Agreement, please promptly return the package for a full refund. GRANT OF LICENSE. This ImageCraft Software License Agreement permits you to use one copy of the ImageCraft software product (“SOFTWARE”) on any computer provided that only one copy is used at a time. COPYRIGHT. The SOFTWARE is owned by ImageCraft and is protected by United States copyright laws and international treaty provisions. You must treat the SOFTWARE like any other copyrighted material (e.g., a book). You may not copy written materials accompanying the SOFTWARE. OTHER RESTRICTIONS. You may not rent or lease the SOFTWARE, but you may transfer your rights under this License on a permanent basis provided that you transfer this License, the SOFTWARE and all accompanying written materials, you retain no copies, and the recipient agrees to the terms of this License. If the SOFTWARE is an update, any transfer must include the update and all prior versions. LIMITED WARRANTY LIMITED WARRANTY. ImageCraft warrants that the SOFTWARE will perform substantially in accordance with the accompanying written materials and will be free from defects in materials and workmanship under normal use and service for a period of thirty (30) days from the date of receipt. Any implied warranties on the SOFTWARE are limited to 30 days. Some states do not allow limitations on the duration of an implied warranty, so the above limitations may not apply to you. This limited warranty gives you specific legal rights. You may have others, which vary from state to state. CUSTOMER REMEDIES. ImageCraft’s entire liability and your exclusive remedy shall be, at ImageCraft’s option, (a) return of the price paid or (b) repair or replacement of the SOFTWARE that does not meet ImageCraft’s Limited Warranty and that is returned to ImageCraft. This Limited Warranty is void if failure of the SOFTWARE has resulted from accident, abuse, or misapplication. Any replacement SOFTWARE will be warranted for the remainder of the original warranty period or 30 days, whichever is longer. NO OTHER WARRANTIES. ImageCraft disclaims all other warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to the SOFTWARE, the accompanying written materials, and any accompanying hardware. 6 ICCV8 for Cortex – C Compiler for ARM Cortex-M NO LIABILITY FOR CONSEQUENTIAL DAMAGES. In no event shall ImageCraft or its supplier be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the SOFTWARE, even if ImageCraft has been advised of the possibility of such damages. The SOFTWARE is not designed, intended, or authorized for use in applications in which the failure of the SOFTWARE could create a situation where personal injury or death may occur. Should you use the SOFTWARE for any such unintended or unauthorized application, you shall indemnify and hold ImageCraft and its suppliers harmless against all claims, even if such claim alleges that ImageCraft was negligent regarding the design or implementation of the SOFTWARE. 7 ICCV8 for Cortex – C Compiler for ARM Cortex-M IMPORTANT: Licensing the Software [A hardware dongle can be used instead of the software licensing scheme described below. See Using the Hardware Dongle] The software uses different licensing keys to enable different features. By default, the software is code size limited. If you install the software for the first time, the software is fully functional (similar to a STD license) for 45 days, after which it will be code limited for an unlimited time. The code limited version is for non-commercial personal use only. The latest version of our software is always available through the demo download link on our website. After downloading and installing demo, you may license the software if you purchase a license. Licensing Your Software To license your software, invoke the ImageCraft License Manager ICCcortex_LicMgr.exe. The License Manager may be found under the Start button ImageCraft Development Tools->ICCV8AVR License Manager or invoked through the C::B IDE under Help->ImageCraft License Manager. You will see a pop-up window containing a Hardware ID number. Fill in the serial number as noted on your invoice, and your name or company name, then click "Copy User Info to the Clipboard" button and then paste the clipboard content to an email message and send the message to [email protected]. The data is formatted for processing and it will expedite our response. If you have a valid license, then you may upgrade to the latest version of the software by simply downloading the latest demo and installing it in the same directory as your current version. We feel that the ability to obtain easy updates from our website outweighs the minor annoyances that the registration process causes. Re-Licensing If some accident occurs or that the OS or your computer changes, you need to reinstall the software and get a replacement license key. Follow the instructions above along with an explanation and we will give you a new license key. Using the Software on Multiple Computers If you need to use the software on multiple computers, such as on an office PC and a laptop, and if you are the only user of the product, you may obtain a separate license from us. Contact us for details. Alternatively, you may purchase the hardware dongle. 8 ICCV8 for Cortex – C Compiler for ARM Cortex-M Transferring a License to Another Computer If you wish to transfer a software license from one computer to another one permanently:  On the old machine, run ICCcortex_LicMgr.exe and click on the Uninstall button on lower left.  On the new machine, run ICCcortex_LicMgr.exe. Email both sets of information you see to [email protected] and we will send you a license key for the new computer. 9 ICCV8 for Cortex – C Compiler for ARM Cortex-M Using the Hardware Dongle ICCV8 for Cortex allows you to optionally use a hardware dongle instead of the default software licensing scheme. With a dongle, you may install the compilers on multiple computers and run it on one machine at any given time. Using the USB Licensing Dongle Plug in the USB dongle. It uses the standard Windows USB driver and no additional driver is needed. Run “ICCV8Cortex License Manager” (Start->ImageCraft Development Tools- >ICCV8Cortex License Manager)  If this is a new purchase, click "Enable Dongle Check."  If you already have a software license, click "Transfer Software License to Dongle." If you are unsure, try “Enable Dongle Check” and if there is no license on the USB dongle, you will receive an error message. When a machine is dongle licensed, and if the dongle is not present while running the compiler, the compiler uses "EXPIRED DEMO" as its license. If you have BOTH a software license and a licensing dongle (RARE), click "Enable Dongle Check" to enable dongle check and "Disable Dongle Check" to disable the check and use the software license. Please restart the IDE after these operations. Upgrading a Dongle License To upgrade the dongle license, on a command prompt, type c:\iccv8cortex\bin\ilinkcortex --DONGLE:0 and email the serial number to [email protected]. After we email you the dongle upgrade code, paste the code into the "Dongle Upgrade Code" edit box in the ICCV8Cortex License Manager and click "Enter Code." 10