HI-TECH C Compiler for PIC18 MCUs Microchip Technology Inc. Copyright (C) 2011 Microchip Technology Inc. All Rights Reserved. Printed in Australia. Produced on: September 27, 2011 Australian Design Centre 45 Colebard Street West Acacia Ridge QLD 4110 Australia web: http://www.microchip.com Contents Table of Contents 3 List of Tables 17 1 Introduction 19 1.1 Typographic conventions ................................ 19 2 PICC18 Command-line Driver 21 2.1 Invoking the Compiler ................................. 22 2.1.1 Long Command Lines ............................. 23 2.2 The Compilation Sequence ............................... 24 2.2.1 Single-step Compilation ............................ 25 2.2.2 Generating Intermediate Files ......................... 26 2.2.3 Special Processing ............................... 27 2.2.3.1 Printf check ............................. 28 2.2.3.2 Assembly Code Requirements ................... 28 2.3 Runtime Files ...................................... 28 2.3.1 Library Files .................................. 29 2.3.1.1 Standard Libraries .......................... 30 2.3.1.2 Utility Libraries ........................... 30 2.3.1.3 Peripheral Libraries ......................... 30 2.3.2 Runtime Startup Code ............................. 31 2.3.2.1 Initialization of Data psects ..................... 32 2.3.2.2 Clearing the Bss Psects ....................... 32 2.3.3 The Powerup Routine ............................. 33 2.3.4 The printf Routine .............................. 34 2.4 Debugging Information ................................. 35 2.5 Compiler Messages ................................... 36 3 CONTENTS CONTENTS 2.5.1 Messaging Overview .............................. 36 2.5.2 Message Language ............................... 37 2.5.3 Message Type .................................. 37 2.5.4 Message Format ................................ 38 2.5.5 Changing Message Behaviour ......................... 40 2.5.5.1 Disabling Messages ......................... 40 2.5.5.2 Changing Message Types ...................... 41 2.6 PICC18 Driver Option Descriptions .......................... 41 2.6.1 Option Formats ................................. 41 2.6.2 -C: Compile to Object File ........................... 42 2.6.3 -Dmacro: Define Macro ............................ 42 2.6.4 -Efile: Redirect Compiler Errors to a File .................. 43 2.6.5 -Gfile: Generate Source-level Symbol File ................. 43 2.6.6 -Ipath: Include Search Path ......................... 44 2.6.7 -Llibrary: Scan Library .......................... 44 2.6.8 -L-option: Adjust Linker Options Directly ................. 45 2.6.9 -Mfile: Generate Map File .......................... 47 2.6.10 -Nsize: Identifier Length ........................... 47 2.6.11 -Ofile: Specify Output File ......................... 47 2.6.12 -P: Preprocess Assembly Files ......................... 48 2.6.13 -Q: Quiet Mode ................................. 48 2.6.14 -S: Compile to Assembler Code ........................ 48 2.6.15 -Umacro: Undefine a Macro ......................... 48 2.6.16 -V: Verbose Compile .............................. 49 2.6.17 -X: Strip Local Symbols ............................ 49 2.6.18 --ADDRQUAL: Set Compiler Response to Memory Qualifier .......... 49 2.6.19 --ASMLIST: Generate Assembler .LST Files .................. 49 2.6.20 --CHECKSUM=start-end@destination<,specs>: Calculate a check- sum ....................................... 50 2.6.21 --CHIP=processor: Define Processor ................... 50 2.6.22 --CHIPINFO: Display List of Supported Processors .............. 50 2.6.23 --CMODE: Specify compatibility mode ..................... 51 2.6.24 --CODEOFFSET: Offset Program Code to Address ............... 51 2.6.25 --CR=file: Generate Cross Reference Listing ................ 51 2.6.26 --DEBUGGER=type: Select Debugger Type .................. 52 2.6.27 --DOUBLE=type: Select kind of Double Types ................ 52 2.6.28 --ECHO: Echo command line before processing ................ 52 2.6.29 --EMI=type: Select operating mode of the external memory interface (EMI) 52 2.6.30 --ERRATA=type: Specify to add or remove specific errata workarounds ... 53 4 CONTENTS CONTENTS 2.6.31 --ERRFORMAT=format: Define Format for Compiler Messages ....... 53 2.6.32 --ERRORS=number: Maximum Number of Errors .............. 53 2.6.33 --FILL=opcode: Fill Unused Program Memory ............... 53 2.6.34 --FLOAT=type: Select kind of Float Types .................. 54 2.6.35 --GETOPTION=app,file: Get Command-line Options ........... 54 2.6.36 --HELP<=option>: Display Help ...................... 54 2.6.37 --HTML: Generate HTML Debug Files ..................... 54 2.6.38 --IDE=type: Specify the IDE being used .................. 55 2.6.39 --LANG=language: Specify the Language for Messages .......... 55 2.6.40 --MEMMAP=file: Display Memory Map ................... 55 2.6.41 --MODE=mode: Choose Compiler Operating Mode .............. 56 2.6.42 --MSGDISABLE=messagelist: Disable Warning Messages ........ 56 2.6.43 --MSGFORMAT=format: Set Advisory Message Format ........... 56 2.6.44 --NODEL: Do not Remove Temporary Files .................. 56 2.6.45 --NOEXEC: Don’t Execute Compiler ...................... 56 2.6.46 --OBJDIR=dir: Specify a Directory for Intermediate Files ......... 57 2.6.47 --OPT<=type>: Invoke Compiler Optimizations ............... 57 2.6.48 --OUTDIR=path: Specify a Directory for Output Files ............ 57 2.6.49 --OUTPUT=type: Specify Output File Type .................. 58 2.6.50 --PASS1: Compile to P-code .......................... 58 2.6.51 --PRE: Produce Preprocessed Source Code .................. 58 2.6.52 --PROTO: Generate Prototypes ......................... 59 2.6.53 --RAM=lo-hi,<lo-hi,...>: Specify Additional RAM Ranges ...... 60 2.6.54 --ROM=lo-hi,<lo-hi,...>|tag: Specify Additional ROM Ranges ... 61 2.6.55 --RUNTIME=type: Specify Runtime Environment .............. 63 2.6.56 --SCANDEP: Scan for Dependencies ...................... 63 2.6.57 --SERIAL=hexcode@address: Store a Value at this Program Memory Address ..................................... 63 2.6.58 --SETOPTION=app,file: Set The Command-line Options for Application 63 2.6.59 --SHROUD: Obfuscate p-code Files ....................... 64 2.6.60 --STRICT: Strict ANSI Conformance ..................... 64 2.6.61 --SUMMARY=type: Select Memory Summary Output Type .......... 64 2.6.62 --TIME: Report time taken for each phase of build process .......... 64 2.6.63 --VER: Display The Compiler’s Version Information ............. 65 2.6.64 --WARN=level: Set Warning Level ...................... 65 2.6.65 --WARNFORMAT=format: Set Warning Message Format ........... 65 2.7 MPLAB IDE v8 Universal Toolsuite Equivalents ................... 66 2.7.1 Directories Tab ................................. 66 2.7.2 Compiler Tab .................................. 66 5 CONTENTS CONTENTS 2.7.3 Linker Tab ................................... 69 2.7.4 Global Tab ................................... 72 2.8 MPLAB X Universal Toolsuite Equivalents ...................... 73 2.8.1 Compiler Category ............................... 74 2.8.1.1 Messages ............................... 74 2.8.1.2 Address Qualifiers .......................... 74 2.8.1.3 Operation .............................. 75 2.8.1.4 Preprocessor ............................. 75 2.8.1.5 Optimization ............................. 76 2.8.2 Linker Category ................................ 77 2.8.2.1 Data ................................. 77 2.8.2.2 Report ................................ 78 2.8.2.3 Runtime ............................... 79 2.8.2.4 Code ................................. 79 2.8.2.5 Additional .............................. 79 3 C Language Features 83 3.1 ANSI Standard Issues .................................. 83 3.1.1 Divergence from the ANSI C Standard .................... 83 3.1.2 Implementation-defined behaviour ....................... 83 3.1.3 Non-ANSI Operations ............................. 84 3.1.4 C18 Compatibility ............................... 84 3.2 Processor-related Features ............................... 85 3.2.1 Processor Support ............................... 85 3.2.2 Device Header Files .............................. 86 3.2.3 Stack ...................................... 86 3.2.4 Configuration Fuses .............................. 86 3.2.5 ID Locations .................................. 88 3.2.6 Bit Instructions ................................. 88 3.2.7 EEPROM and Flash Runtime Access ..................... 89 3.2.7.1 EEPROM Access .......................... 89 3.2.7.2 Flash Access ............................. 90 3.2.8 Using SFRs From C Code ........................... 91 3.2.8.1 Multi-byte SFRs ........................... 92 3.3 Supported Data Types and Variables .......................... 93 3.3.1 Radix Specifiers and Constants ......................... 93 3.3.2 Bit Data Types and Variables .......................... 95 3.3.3 Using Bit-Addressable Registers ........................ 96 3.3.4 8-Bit Integer Data Types and Variables .................... 96 6 CONTENTS CONTENTS 3.3.5 16-Bit Integer Data Types ........................... 96 3.3.6 24-Bit Integer Data Types ........................... 97 3.3.7 32-Bit Integer Data Types and Variables .................... 97 3.3.8 Floating Point Types and Variables ....................... 98 3.3.9 Structures and Unions ............................. 99 3.3.9.1 Bit-fields in Structures ........................ 99 3.3.9.2 Structure and Union Qualifiers ................... 100 3.3.10 Standard Type Qualifiers ...........................