SW500009

SW500009 Datasheet

Part	Datasheet
SW500009	SW500009 (pdf)

PDF Datasheet Preview
HI-TECH PICC STD Compiler HI-TECH Software. Copyright C 2008 HI-TECH Software. All Rights Reserved. Printed in Australia. PICC is licensed exclusively to HI-TECH Software by Microchip Technology Inc. Produced on February 21, 2008 HI-TECH Software Pty. Ltd. ACN 002 724 549 45 Colebard Street West Acacia Ridge QLD 4110 Australia email web: Contents Table of Contents List of Tables xiii 1 Introduction Typographic conventions 1 2 PICC Command-line Driver Long Command Lines 4 Default Libraries 4 Standard Runtime Code 4 PICC Compiler Options 5 -C Compile to Object File 7 -Dmacro Macro 8 -Efile Redirect Compiler Errors to a File 8 -Gfile Generate Source-level Symbol File 9 -Ipath Include Search Path 9 -Llibrary Scan Library 10 -L-option Adjust Linker Options Directly 10 -Mfile Generate Map File 12 -Nsize Length 12 -Ofile Specify Output File 12 -P Preprocess Assembly Files 13 -Q Quiet Mode 13 -S Compile to Assembler Code 13 -Umacro a Macro 13 -V Verbose Compile 14 -X Strip Local Symbols 14 CONTENTS CONTENTS --ASMLIST Generate Assembler .LST Files 14 --CHAR=type Make Char Type Signed or Unsigned 14 Calculate a check- sum 14 --CHIP=processor 15 --CHIPINFO Display List of Supported Processors 15 --CODEOFFSET Offset Program Code to Address 15 --CR=file Generate Cross Reference Listing 15 --DEBUGGER=type Select Debugger Type 16 --DOUBLE=type Select kind of Double Types 16 --ECHO compiler command line 16 --ERRFORMAT=format for Compiler Messages 16 Using the Format Options 17 Modifying the Standard Format 17 --ERRORS=number Maximum Number of Errors 18 --FILL=opcode Fill Unused Program Memory 18 --GETOPTION=app,file Get Command-line Options 19 --HELP<=option> Display Help 19 --IDE=type Specify the IDE being used 19 --LANG=language Specify the Language for Messages 19 --MEMMAP=file Display Memory Map 20 --MSGDISABLE=messagelist Disable Warning Messages 20 --MSGFORMAT=format Set Advisory Message Format 20 --NODEL Do not remove temporary 20 --NOEXEC Don’t Execute Compiler 20 --OPT<=type> Invoke Compiler Optimizations 20 --OUTDIR Specify a directory for output 21 --OUTPUT=type Specify Output File Type 21 --PRE Produce Preprocessed Source Code 21 --PROTO Generate Prototypes 21 --RAM=lo-hi,<lo-hi,...> Specify Additional RAM Ranges 23 --ROM=lo-hi,<lo-hi,...>\|tag Specify Additional ROM Ranges 24 --RUNTIME=type Specify Runtime Environment 24 --SCANDEP Scan for Dependencies 24 Store a Value at this Program Memory Address 26 --SETOPTION=app,file Set The Command-line Options for Application 26 --SETUP=dir Setup the product 26 --STRICT ANSI Conformance 26 CONTENTS 127 -F 127 -Gspec 127 128 -Jerrcount 128 -K 128 -I 129 -L 129 -LM 129 -N, -Ns and-Nc 129 -Pspec 129 -Qprocessor 131 -S 131 -Sclass=limit[, bound] 131 -Usymbol 132 -Vavmap 132 -Wnum 132 -X 132 -Z 132 Invoking the Linker 133 Map Files 133 Call Graph Information 134 Librarian 136 The Library Format 137 Using the Librarian 137 Examples 138 Supplying Arguments 138 Listing Format 139 Ordering of Libraries 139 Error Messages 139 Objtohex 139 Checksum 141 Cref 141 142 -Hheading 142 CONTENTS CONTENTS -Llen 142 -Pwidth 143 -Sstoplist 143 Cromwell 143 -Pname[,architecture] 143 -N 145 -D 145 -C 145 -F 145 -Okey 146 -Ikey 146 -L 146 -E 146 -B 146 -M 146 -V 146 Hexmate 146 Hexmate Command Line Options 147 149 + 149 -ADDRESSING 150 -BREAK 150 -CK 150 -FILL 151 -FIND 152 -FIND...,DELETE 153 -FIND...,REPLACE 153 -FORMAT 153 -HELP 154 -LOGFILE 155 -SERIAL 155 -SIZE 156 -STRING 156 -STRPACK 156 A Library Functions CONTENTS B Error and Warning Messages C Chip Information Index CONTENTS 275 403 409 List of Tables PICC types 3 Default values for unprogrammed code space 15 Supported Double Types 16 Error format 17 Supported IDEs 19 Supported languages 19 Optimization Options 21 Output formats 22 Runtime environment suboptions 25 Memory Summary Suboptions 27 Basic data types 41 Radix formats 42 Floating-point formats 45 Floating-point format example IEEE 754 46 Integral division 59 Preprocessor directives 71 macros 72 Pragma directives 73 Valid Register Names 76 switch types 76 Supported standard I/O functions 79 ASPIC command-line options 82 ASPICstatement formats 85 ASPIC numbers and bases 86 ASPIC operators 90 xiii LIST OF TABLES LIST OF TABLES ASPIC assembler directives 92 PSECT 93 ASPIC assembler controls 104 LIST control options 105 Linker command-line options 125 Librarian command-line options 137 Librarian key letter commands 137 OBJTOHEX command-line options 140 CREF command-line options 142 CROMWELL format types 144 CROMWELL command-line options 144 -P option architecture arguments for COFF output. 145 Hexmate command-line options 148 Hexmate Checksum Algorithm Selection 151 INHX types used in -FORMAT option 154 C.1 Devices supported by HI-TECH PICC STD 403 C.1 Devices supported by HI-TECH PICC STD 404 C.1 Devices supported by HI-TECH PICC STD 405 C.1 Devices supported by HI-TECH PICC STD 406 C.1 Devices supported by HI-TECH PICC STD 407 C.1 Devices supported by HI-TECH PICC STD 408 Introduction Typographic conventions Different fonts and styles are used throughout this manual to indicate special words or text. Computer prompts, responses and will be printed in constant-spaced type. When the is the name of a standard header the name will be enclosed in angle brackets, e.g. <stdio.h>. These header can be found in the INCLUDE directory of your distribution. Samples of code, C keywords or types, assembler instructions and labels will also be printed in a constant-space type. Assembler code is printed in a font similar to that used by C code. Particularly useful points and new terms will be emphasized using italicized type. When part of a term requires substitution, that part should be printed in the appropriate font, but in italics. For example #include <filename.h>. Typographic conventions Introduction PICC Command-line Driver PICC is the driver invoked from the command line to compile and/or link C programs. PICC has the following basic command format: PICC [options] files [libraries] It is conventional to supply the options by a leading dash “-” or double dash before the The options are discussed below. The may be a mixture of source C or assembler and object The order of the is not important, except that it will affect the order in which code or data appears in memory. Libraries are a list of library names, or -L options, see Section Source object and library are distinguished by PICC solely by the type or extension. Recognized types are listed in Table This means, for example, that an assembler must always have a .as extension alphabetic case is not important . PICC will check each argument and perform appropriate actions. C will be compiled assembler will be assembled. At the end, unless suppressed by one of the options discussed later, Table PICC types File Type Meaning C source Assembler source .obj Relocatable object code .lib Effect Use 8086 style segment:offset address form Specify address ranges for a class Call graph options Specify a class name for a global psect Produce binary output based at baseaddr Specify a class delta value Produce old-style symbol Write error messages to errfile Produce .obj with only symbol records Specify calculation for segment selectors Generate symbol Generate enhanced symbol Ignore symbols Set maximum number of errors before aborting Prevent overlaying function parameter and auto areas Preserve relocation items in .obj Preserve segment relocation items in .obj Sort symbol table in map by address order Sort symbol table in map by class address order Sort symbol table in map by space address order Generate a link map in the named Specify name of output Specify psect addresses and ordering Specify the processor type for cosmetic reasons only Inhibit listing of symbols in symbol Specify address limit, and start boundary for a class of psects Pre-enter symbol in table as Use avmap to generate an Avocet format symbol Set warning level -9 to 9 Set map width >=10 Remove any local symbols from the symbol Remove trivial local symbols from the symbol Operation Linker and Utilities Numbers in linker options Several linker options require memory addresses or sizes to be The syntax for all these is similar. By default, the number will be interpreted as a decimal value. To force interpretation as a hex number, a trailing H should be added, e.g. 765FH will be treated as a hex number. -Aclass=low-high,... Normally psects are linked according to the information given to a -P option see below but sometimes it is desired to have a class of psects linked into more than one non-contiguous address range. This option allows a number of address ranges to be for a class. For example: -ACODE=1020h-7FFEh,8000h-BFFEh that the class CODE is to be linked into the given address ranges. Note that a contribution to a psect from one module cannot be split, but the linker will attempt to pack each block from each module into the address ranges, starting with the Where there are a number of identical, contiguous address ranges, they may be with a repeat count, e.g. -ACODE=0-FFFFhx16 that there are 16 contiguous ranges each 64k bytes in size, starting from zero. Even though the ranges are contiguous, no code will straddle a 64k boundary. The repeat count is as the character x or * after a range, followed by a count. These options allow control over the call graph information which may be included in the map produced by the linker. The -CN option removes the call graph information from the map The -CC option only include the critical paths of the call graph. A function call that is marked with a * in a full call graph is on a critical path and only these calls are included when the -CC option is used. A call graph is only produced for processors and memory models that use a compiled stack. -Cpsect=class This option will allow a psect to be associated with a class. Normally this is not required on the command line since classes are in object Linker and Utilities Operation -Dclass=delta This option allows the delta value for psects that are members of the class to be The delta value should be a number and represents the number of bytes per addressable unit of objects within the psects. Most psects do not need this option as they are with a delta value. Use this option to produce an old-style symbol An old-style symbol is an ASCII where each line has the link address of the symbol followed by the symbol name. Error messages from the linker are written to standard error handle Under DOS there is no convenient way to redirect this to a the compiler drivers will redirect standard error if standard output is redirected . This option will make the linker write all error messages to the instead of the screen, which is the default standard error destination. Normally the linker will produce an object that contains both program code and data bytes, and symbol information. Sometimes it is desired to produce a symbol-only object that can be used again in a subsequent linker run to supply symbol values. The -F option will suppress data and code bytes from the output leaving only the symbol records. This option can be used when producing more than one hex for situations where the program is contained in different memory devices located at different addresses. The for one device are compiled using this linker option to produce a symbol-only object this is then linked with the for the other device. The process can then be repeated for the other and device. -Gspec When linking programs using segmented, or bank-switched psects, there are two ways the linker can assign segment addresses, or selectors, to each segment. A segment is as a contiguous group of psects where each psect in sequence has both its link and load address concatenated with the previous psect in the group. The segment address or selector for the segment is the value derived when a segment type relocation is processed by the linker. By default the segment selector will be generated by dividing the base load address of the segment by the relocation quantum of the segment, which is based on the reloc= value given to psects at the assembler level. This is appropriate for 8086 real mode code, but not for protected mode Operation Linker and Utilities or some bank-switched arrangements. In this instance the -G option is used to specify a method for calculating the segment selector. The argument to -G is a string similar to: A/10h-4h where A represents the load address of the segment and / represents division. This means "Take the load address of the psect, divide by 10 hex, then subtract This form can be by substituting N for A, * for / to represent multiplication , and adding rather than subtracting a constant. The token N is replaced by the ordinal number of the segment, which is allocated by the linker. For example: N*8+4 means "take the segment number, multiply by 8 then add The result is the segment selector. This particular example would allocate segment selectors in the sequence 4, 12, 20, for the number of segments This would be appropriate when compiling for 80286 protected mode, where these selectors would represent LDT entries. This option will instruct the linker to generate a symbol The optional argument symfile a to receive the symbol The default name is l.sym. This option will instruct the linker to generate an enhanced symbol which provides, in addition to the standard symbol class names associated with each symbol and a segments section which lists each class name and the range of memory it occupies. This format is recommended if the code is to be run in conjunction with a debugger. The optional argument symfile a to receive the symbol The default name is l.sym. -Jerrcount The linker will stop processing object after a certain number of errors other than warnings . The default number is 10, but the -J option allows this to be altered. For compilers that use a compiled stack, the linker will try and overlay function auto and parameter areas in an attempt to reduce the total amount of RAM required. For debugging purposes, this feature can be disabled with this option. Linker and Utilities Operation Usually failure to resolve a reference to an symbol is a fatal error. Use of this option will cause symbols to be treated as warnings instead. This option will enter the symbol into the linker’s symbol table as an symbol. This is useful for linking entirely from libraries, or for linking a module from a library where the ordering has been arranged so that by default a later module will be linked. -Vavmap To produce an Avocet format symbol the linker needs to be given a map to allow it to map psect names to Avocet memory The avmap will normally be supplied with the compiler, or created automatically by the compiler driver as required. -Wnum The -W option can be used to set the warning level, in the range -9 to 9, or the width of the map for values of num >= -W9 will suppress all warning messages. -W0 is the default. Setting the warning level to -9 -W-9 will give the most comprehensive warning messages. Local symbols can be suppressed from a symbol with this option. Global symbols will always appear in the symbol Some local symbols are compiler generated and not of interest in debugging. This option will suppress from the symbol all local symbols that have the form of a single alphabetic character, followed by a digit string. The set of letters that can start a trivial symbol is currently "klfLSu". The -Z option will strip any local symbols starting with one of these letters, and followed by a digit string. Linker and Utilities Invoking the Linker Invoking the Linker The linker is called HLINK, and normally resides in the BIN subdirectory of the compiler installation directory. It may be invoked with no arguments, in which case it will prompt for input from standard input. If the standard input is a no prompts will be printed. This manner of invocation is generally useful if the number of arguments to HLINK is large. Even if the list of is too long to on one line, continuation lines may be included by leaving a backslash at the end of the preceding line. In this fashion, HLINK commands of almost unlimited length may be issued. For example a link command called x.lnk and containing the following text: -Z -OX.OBJ -MX.MAP -Ptext=0,data=0/,bss,nvram=bss/. X.OBJ Y.OBJ Z.OBJ may be passed to the linker by one of the following: hlink < x.lnk Map Files The map contains information relating to the relocation of psects and the addresses assigned to symbols within those psects. The sections in the map are as follows is a copy of the command line used to invoke the linker. This is followed by the version number of the object code in the linked, and the machine type. This is optionally followed by call graph information, depended on the processor and memory model selected. Then are listed all object that were linked, along with their psect information. Libraries are listed, with each module within the library. The TOTALS section summarises the psects from the object The SEGMENTS section summarises major memory groupings. This will typically show RAM and ROM usage. The segment names are derived from the name of the psect in the segment. Lastly not shown in the example is a symbol table, where each global symbol is listed with its associated psect and link address. Linker command line -z -Mmap -pvectors=00h,text,strings,const,im2vecs -pbaseram=00h -pnvram=bss,heap hello.obj Map Files Linker and Utilities Object code version is Machine type is Z80 Name vectors const text hello.obj text powerup.obj vectors TOTAL Name CLASS CODE vectors const text CLASS DATA SEGMENTS Name vectors Link Load Length Selector Ordering of Libraries The librarian creates libraries with the modules in the order in which they were given on the command line. When updating a library the order of the modules is preserved. Any new modules added to a library after it has been created will be appended to the end. The ordering of the modules in a library is to the linker. If a library contains a module which references a symbol in another module in the same library, the module the symbol should come after the module referencing the symbol. Error Messages LIBR issues various error messages, most of which represent a fatal error, while some represent a harmless occurrence which will nonetheless be reported unless the -W option was used. In this case all warning messages will be suppressed. Objtohex The HI-TECH linker is capable of producing simple binary or object as output. Any other format required must be produced by running the utility program OBJTOHEX. This allows conversion of object as produced by the linker into a variety of different formats, including various hex formats. The program is invoked thus: OBJTOHEX options inputfile outputfile All of the arguments are optional. If outputfile is omitted it defaults to l.hex or l.bin depending on whether the -b option is used. The inputfile defaults to l.obj. The options for OBJTOHEX are listed in Table Where an address is required, the format is the same as for HLINK. Objtohex Linker and Utilities Option -8 -A -Bbase -Cckfile -D -E -Ffill -M -N -Pstk -R -Sfile -T -TE -U -UB -V -n,m Table OBJTOHEX command-line options Meaning Linker and Utilities Cref Checksum If you are generating a HEX output, please refer to the hexmate section for calculating checksums. For OBJTOHEX, the checksum allows automated checksum calculation and takes the form of several lines, each line describing one checksum. The syntax of a checksum line is: addr1-addr2 where1-where2 +offset All of addr1, addr2, where1, where2 and offset are hex numbers, without the usual H Such a says that the bytes at addr1 through to addr2 inclusive should be summed and the sum placed in the locations where1 through where2 inclusive. For an 8 bit checksum these two addresses should be the same. For a checksum stored low byte where1 should be less than where2, and vice versa. The +offset is optional, but if supplied, the value offset will be used to initialise the checksum. Otherwise it is initialised to zero. For example: 0005-1FFF 3-4 +1FFF This will sum the bytes in 5 through 1FFFH inclusive, then add 1FFFH to the sum. The 16 bit checksum will be placed in locations 3 and 4, low byte in The checksum is initialised with 1FFFH to provide protection against an all zero ROM, or a ROM misplaced in memory. A run time check of this checksum would add the last address of the ROM being checksummed into the checksum. For the ROM in question, this should be 1FFFH. The initialization value may, however, be used in any desired fashion. Cref The cross reference list utility CREF is used to format raw cross-reference information produced by the compiler or the assembler into a sorted listing. A raw cross-reference is produced with the --CR option to the compiler. The assembler will generate a raw cross-reference with a -C option most assemblers or by using an OPT CRE directive 6800 series assemblers or a XREF control line PIC assembler . The general form of the CREF command is: cref options files where options is zero or more options as described below and files is one or more raw crossreference CREF takes the options listed in Table Each option is described in more detail in the following paragraphs. Cref Linker and Utilities Table CREF command-line options Option Meaning -Fprefix Exclude symbols from with a pathname or starting with prefix -Hheading Specify a heading for the listing -Llen Specify the page length for the listing -Ooutfile Specify the name of the listing -Pwidth Set the listing width Specify big-endian byte ordering Strip underscore character Verbose mode Linker and Utilities Cromwell Table -P option architecture arguments for COFF output. Architecture Motorola 68000 series chips H8/300 Hitachi 8 bit H8/300 chips H8/300H Hitachi 16 bit H8/300H chips Hitachi 32 bit SuperH RISC chips PIC12 Microchip base-line PIC chips PIC14 Microchip mid-range PIC chips PIC16 Microchip high-end 17Cxxx PIC chips PIC18 Microchip PIC18 chips PIC24 Microchip PIC24F and PIC24H chips PIC30 Microchip dsPIC30 and dsPIC33 chips format the usage of this option must take the form -Pname,architecture. Table enumerates the architectures supported for producing COFF To produce some output formats e.g. COFF , Cromwell requires that the names of the program memory space psect classes be provided. The names of the classes are given as a comma separated list. For example, in the DSPIC C compiler these classes are typically “CODE” and “NEARCODE”, i.e. -NCODE,NEARCODE. The -D option is used to display to the screen details about the named input in a readable format. The input can be one of the types as shown in Table This option will attempt to identify if the input are one of the formats as shown in Table If the is recognised, a of its type will be displayed. When generating a COD this option can be used to force all local symbols to be represented as global symbols. The may be useful where an emulator cannot read local symbol information from the COD Hexmate Linker and Utilities -Okey This option the format of the output The key can be any of the types listed in Table -Ikey This option can be used to specify the default input format. The key can be any of the types listed in Table Use this option to show what format types are supported. A list similar to that given in Table will be shown. Use this option to tell CROMWELL to ignore any extensions that were given. The default extension will be used instead. In formats that support different endian types, use this option to specify big-endian byte ordering. When generating COD this option will remove the preceding underscore character from symbols. Turns on verbose mode which will display information about operations CROMWELL is performing. Hexmate The Hexmate utility is a program designed to manipulate Intel HEX Hexmate is a post-link stage utility that provides the facility to: • Calculate and store variable-length checksum values Linker and Utilities Hexmate • Fill unused memory locations with known data sequences • Merge multiple Intel hex into one output • Convert INHX32 to other INHX formats e.g. INHX8M • Detect or partial opcode sequences within a hex • Find/replace or partial opcode sequences • Provide a map of addresses used in a hex • Change or the length of data records in a hex • Validate checksums within Intel hex Typical applications for hexmate might include • Merging a bootloader or debug module into a main application at build time • Calculating a checksum over a range of program memory and storing its value in program memory or EEPROM • Filling unused memory locations with an instruction to send the PC to a known location if it gets lost. • Storage of a serial number at a address. • Storage of a string e.g. time stamp at a address. • Store initial values at a particular memory address e.g. initialise EEPROM • Detecting usage of a buggy/restricted instruction • Adjusting hex to meet requirements of particular bootloaders Hexmate Command Line Options Some of these hexmate operations may be possible from the compiler’s command line driver. However, if hexmate is to be run directly, its usage is: hexmate <file1.hex fileN.hex> <options> Hexmate Linker and Utilities Table Hexmate command-line options Option Effect -ADDRESSING Set address in all hexmate options to use word addressing or other -BREAK Break continuous data so that a new record begins at a set address Calculate and store a checksum value -FILL Program unused locations with a known value -FIND Search and notify if a particular code sequence is detected -FIND...,DELETE Remove the code sequence if it is detected use with caution -FIND...,REPLACE the code sequence with a new code sequence -FORMAT Specify maximum data record length or select INHX variant -HELP Show all options or display help message for option -LOGFILE Save hexmate analysis of output and various results to a -Ofile Specify the name of the output -SERIAL

PDF Datasheet Preview

HI-TECH PICC STD Compiler

HI-TECH Software.

Copyright C 2008 HI-TECH Software. All Rights Reserved. Printed in Australia. PICC is licensed exclusively to HI-TECH Software
by Microchip Technology Inc. Produced on February 21, 2008

HI-TECH Software Pty. Ltd. ACN 002 724 549
45 Colebard Street West Acacia Ridge QLD 4110

Australia
email web:

Contents

Table of Contents

List of Tables
xiii
1 Introduction

Typographic conventions 1
2 PICC Command-line Driver

Long Command Lines 4

Default Libraries 4

Standard Runtime Code 4

PICC Compiler Options 5
-C Compile to Object File 7
-Dmacro Macro 8
-Efile Redirect Compiler Errors to a File 8
-Gfile Generate Source-level Symbol File 9
-Ipath Include Search Path 9
-Llibrary Scan Library 10
-L-option Adjust Linker Options Directly 10
-Mfile Generate Map File 12
-Nsize Length 12
-Ofile Specify Output File 12
-P Preprocess Assembly Files 13
-Q Quiet Mode 13
-S Compile to Assembler Code 13
-Umacro a Macro 13
-V Verbose Compile 14
-X Strip Local Symbols 14

CONTENTS

CONTENTS
--ASMLIST Generate Assembler .LST Files 14 --CHAR=type Make Char Type Signed or Unsigned 14 Calculate a check-
sum 14 --CHIP=processor 15 --CHIPINFO Display List of Supported Processors 15 --CODEOFFSET Offset Program Code to Address 15 --CR=file Generate Cross Reference Listing 15 --DEBUGGER=type Select Debugger Type 16 --DOUBLE=type Select kind of Double Types 16 --ECHO compiler command line 16 --ERRFORMAT=format for Compiler Messages 16

Using the Format Options 17 Modifying the Standard Format 17 --ERRORS=number Maximum Number of Errors 18 --FILL=opcode Fill Unused Program Memory 18 --GETOPTION=app,file Get Command-line Options 19 --HELP<=option> Display Help 19 --IDE=type Specify the IDE being used 19 --LANG=language Specify the Language for Messages 19 --MEMMAP=file Display Memory Map 20 --MSGDISABLE=messagelist Disable Warning Messages 20 --MSGFORMAT=format Set Advisory Message Format 20 --NODEL Do not remove temporary 20 --NOEXEC Don’t Execute Compiler 20 --OPT<=type> Invoke Compiler Optimizations 20 --OUTDIR Specify a directory for output 21 --OUTPUT=type Specify Output File Type 21 --PRE Produce Preprocessed Source Code 21 --PROTO Generate Prototypes 21 --RAM=lo-hi,<lo-hi,...> Specify Additional RAM Ranges 23 --ROM=lo-hi,<lo-hi,...>|tag Specify Additional ROM Ranges 24 --RUNTIME=type Specify Runtime Environment 24 --SCANDEP Scan for Dependencies 24 Store a Value at this Program Memory Address 26 --SETOPTION=app,file Set The Command-line Options for Application 26 --SETUP=dir Setup the product 26 --STRICT ANSI Conformance 26

CONTENTS
127 -F 127 -Gspec 127 128 -Jerrcount 128 -K 128 -I 129 -L 129 -LM 129 -N, -Ns and-Nc 129 -Pspec 129 -Qprocessor 131 -S 131 -Sclass=limit[, bound] 131 -Usymbol 132 -Vavmap 132 -Wnum 132 -X 132 -Z 132 Invoking the Linker 133 Map Files 133 Call Graph Information 134 Librarian 136 The Library Format 137 Using the Librarian 137 Examples 138 Supplying Arguments 138 Listing Format 139 Ordering of Libraries 139 Error Messages 139 Objtohex 139 Checksum 141 Cref 141 142 -Hheading 142

CONTENTS

CONTENTS
-Llen 142 -Pwidth 143 -Sstoplist 143 Cromwell 143 -Pname[,architecture] 143 -N 145 -D 145 -C 145 -F 145 -Okey 146 -Ikey 146 -L 146 -E 146 -B 146 -M 146 -V 146 Hexmate 146 Hexmate Command Line Options 147
149 + 149 -ADDRESSING 150 -BREAK 150 -CK 150 -FILL 151 -FIND 152 -FIND...,DELETE 153 -FIND...,REPLACE 153 -FORMAT 153 -HELP 154 -LOGFILE 155 -SERIAL 155 -SIZE 156 -STRING 156 -STRPACK 156

A Library Functions

CONTENTS

B Error and Warning Messages C Chip Information Index

CONTENTS
275 403 409

List of Tables

PICC types 3 Default values for unprogrammed code space 15 Supported Double Types 16 Error format 17 Supported IDEs 19 Supported languages 19 Optimization Options 21 Output formats 22 Runtime environment suboptions 25 Memory Summary Suboptions 27

Basic data types 41 Radix formats 42 Floating-point formats 45 Floating-point format example IEEE 754 46 Integral division 59 Preprocessor directives 71 macros 72 Pragma directives 73 Valid Register Names 76 switch types 76 Supported standard I/O functions 79

ASPIC command-line options 82 ASPICstatement formats 85 ASPIC numbers and bases 86 ASPIC operators 90
xiii

LIST OF TABLES

LIST OF TABLES

ASPIC assembler directives 92 PSECT 93 ASPIC assembler controls 104 LIST control options 105

Linker command-line options 125 Librarian command-line options 137 Librarian key letter commands 137 OBJTOHEX command-line options 140 CREF command-line options 142 CROMWELL format types 144 CROMWELL command-line options 144 -P option architecture arguments for COFF output. 145 Hexmate command-line options 148 Hexmate Checksum Algorithm Selection 151 INHX types used in -FORMAT option 154

C.1 Devices supported by HI-TECH PICC STD 403 C.1 Devices supported by HI-TECH PICC STD 404 C.1 Devices supported by HI-TECH PICC STD 405 C.1 Devices supported by HI-TECH PICC STD 406 C.1 Devices supported by HI-TECH PICC STD 407 C.1 Devices supported by HI-TECH PICC STD 408

Introduction

Typographic conventions

Different fonts and styles are used throughout this manual to indicate special words or text. Computer prompts, responses and will be printed in constant-spaced type. When the is the name of a standard header the name will be enclosed in angle brackets, e.g. <stdio.h>. These header can be found in the INCLUDE directory of your distribution.

Samples of code, C keywords or types, assembler instructions and labels will also be printed in a constant-space type. Assembler code is printed in a font similar to that used by C code.

Particularly useful points and new terms will be emphasized using italicized type. When part of a term requires substitution, that part should be printed in the appropriate font, but in italics. For example #include <filename.h>.

Typographic conventions

Introduction

PICC Command-line Driver

PICC is the driver invoked from the command line to compile and/or link C programs. PICC has the following basic command format:

PICC [options] files [libraries]

It is conventional to supply the options by a leading dash “-” or double dash before the

The options are discussed below. The may be a mixture of source C or assembler and object The order of the is not important, except that it will affect the order in which code or data appears in memory. Libraries are a list of library names, or -L options, see Section Source object and library are distinguished by PICC solely by the type or extension. Recognized types are listed in Table This means, for example, that an assembler must always have a .as extension alphabetic case is not important .

PICC will check each argument and perform appropriate actions. C will be compiled assembler will be assembled. At the end, unless suppressed by one of the options discussed later,

Table PICC types

File Type

Meaning

C source

Assembler source
.obj

Relocatable object code
.lib
Effect Use 8086 style segment:offset address form Specify address ranges for a class Call graph options Specify a class name for a global psect Produce binary output based at baseaddr Specify a class delta value Produce old-style symbol Write error messages to errfile Produce .obj with only symbol records Specify calculation for segment selectors Generate symbol Generate enhanced symbol Ignore symbols Set maximum number of errors before aborting Prevent overlaying function parameter and auto areas Preserve relocation items in .obj Preserve segment relocation items in .obj Sort symbol table in map by address order Sort symbol table in map by class address order Sort symbol table in map by space address order Generate a link map in the named Specify name of output Specify psect addresses and ordering Specify the processor type for cosmetic reasons only Inhibit listing of symbols in symbol Specify address limit, and start boundary for a class of psects Pre-enter symbol in table as Use avmap to generate an Avocet format symbol Set warning level -9 to 9 Set map width >=10 Remove any local symbols from the symbol Remove trivial local symbols from the symbol

Operation

Linker and Utilities

Numbers in linker options

Several linker options require memory addresses or sizes to be The syntax for all these is similar. By default, the number will be interpreted as a decimal value. To force interpretation as a hex number, a trailing H should be added, e.g. 765FH will be treated as a hex number.
-Aclass=low-high,...

Normally psects are linked according to the information given to a -P option see below but sometimes it is desired to have a class of psects linked into more than one non-contiguous address range. This option allows a number of address ranges to be for a class. For example:
-ACODE=1020h-7FFEh,8000h-BFFEh
that the class CODE is to be linked into the given address ranges. Note that a contribution to a psect from one module cannot be split, but the linker will attempt to pack each block from each module into the address ranges, starting with the

Where there are a number of identical, contiguous address ranges, they may be with a repeat count, e.g.
-ACODE=0-FFFFhx16
that there are 16 contiguous ranges each 64k bytes in size, starting from zero. Even though the ranges are contiguous, no code will straddle a 64k boundary. The repeat count is as the character x or * after a range, followed by a count.

These options allow control over the call graph information which may be included in the map produced by the linker. The -CN option removes the call graph information from the map The -CC option only include the critical paths of the call graph. A function call that is marked with a * in a full call graph is on a critical path and only these calls are included when the -CC option is used. A call graph is only produced for processors and memory models that use a compiled stack.
-Cpsect=class

This option will allow a psect to be associated with a class. Normally this is not required on the command line since classes are in object

Linker and Utilities

Operation
-Dclass=delta

This option allows the delta value for psects that are members of the class to be The delta value should be a number and represents the number of bytes per addressable unit of objects within the psects. Most psects do not need this option as they are with a delta value.

Use this option to produce an old-style symbol An old-style symbol is an ASCII where each line has the link address of the symbol followed by the symbol name.

Error messages from the linker are written to standard error handle Under DOS there is no convenient way to redirect this to a the compiler drivers will redirect standard error if standard output is redirected . This option will make the linker write all error messages to the instead of the screen, which is the default standard error destination.

Normally the linker will produce an object that contains both program code and data bytes, and symbol information. Sometimes it is desired to produce a symbol-only object that can be used again in a subsequent linker run to supply symbol values. The -F option will suppress data and code bytes from the output leaving only the symbol records.

This option can be used when producing more than one hex for situations where the program is contained in different memory devices located at different addresses. The for one device are compiled using this linker option to produce a symbol-only object this is then linked with the for the other device. The process can then be repeated for the other and device.
-Gspec

When linking programs using segmented, or bank-switched psects, there are two ways the linker can assign segment addresses, or selectors, to each segment. A segment is as a contiguous group of psects where each psect in sequence has both its link and load address concatenated with the previous psect in the group. The segment address or selector for the segment is the value derived when a segment type relocation is processed by the linker.

By default the segment selector will be generated by dividing the base load address of the segment by the relocation quantum of the segment, which is based on the reloc= value given to psects at the assembler level. This is appropriate for 8086 real mode code, but not for protected mode

Operation

Linker and Utilities
or some bank-switched arrangements. In this instance the -G option is used to specify a method for calculating the segment selector. The argument to -G is a string similar to:

A/10h-4h
where A represents the load address of the segment and / represents division. This means "Take the load address of the psect, divide by 10 hex, then subtract This form can be by substituting N for A, * for / to represent multiplication , and adding rather than subtracting a constant. The token N is replaced by the ordinal number of the segment, which is allocated by the linker. For example:

N*8+4
means "take the segment number, multiply by 8 then add The result is the segment selector. This particular example would allocate segment selectors in the sequence 4, 12, 20, for the number of segments This would be appropriate when compiling for 80286 protected mode, where these selectors would represent LDT entries.

This option will instruct the linker to generate a symbol The optional argument symfile a to receive the symbol The default name is l.sym.

This option will instruct the linker to generate an enhanced symbol which provides, in addition to the standard symbol class names associated with each symbol and a segments section which lists each class name and the range of memory it occupies. This format is recommended if the code is to be run in conjunction with a debugger. The optional argument symfile a to receive the symbol The default name is l.sym.
-Jerrcount

The linker will stop processing object after a certain number of errors other than warnings . The default number is 10, but the -J option allows this to be altered.

For compilers that use a compiled stack, the linker will try and overlay function auto and parameter areas in an attempt to reduce the total amount of RAM required. For debugging purposes, this feature can be disabled with this option.

Linker and Utilities

Operation

Usually failure to resolve a reference to an symbol is a fatal error. Use of this option will cause symbols to be treated as warnings instead.
This option will enter the symbol into the linker’s symbol table as an symbol. This is useful for linking entirely from libraries, or for linking a module from a library where the ordering has been arranged so that by default a later module will be linked.
-Vavmap

To produce an Avocet format symbol the linker needs to be given a map to allow it to map psect names to Avocet memory The avmap will normally be supplied with the compiler, or created automatically by the compiler driver as required.
-Wnum

The -W option can be used to set the warning level, in the range -9 to 9, or the width of the map for values of num >=
-W9 will suppress all warning messages. -W0 is the default. Setting the warning level to -9 -W-9 will give the most comprehensive warning messages.

Local symbols can be suppressed from a symbol with this option. Global symbols will always appear in the symbol

Some local symbols are compiler generated and not of interest in debugging. This option will suppress from the symbol all local symbols that have the form of a single alphabetic character, followed by a digit string. The set of letters that can start a trivial symbol is currently "klfLSu". The -Z option will strip any local symbols starting with one of these letters, and followed by a digit string.

Linker and Utilities

Invoking the Linker

Invoking the Linker

The linker is called HLINK, and normally resides in the BIN subdirectory of the compiler installation directory. It may be invoked with no arguments, in which case it will prompt for input from standard input. If the standard input is a no prompts will be printed. This manner of invocation is generally useful if the number of arguments to HLINK is large. Even if the list of is too long to on one line, continuation lines may be included by leaving a backslash at the end of the preceding line. In this fashion, HLINK commands of almost unlimited length may be issued. For example a link command called x.lnk and containing the following text:
-Z -OX.OBJ -MX.MAP -Ptext=0,data=0/,bss,nvram=bss/. X.OBJ Y.OBJ Z.OBJ
may be passed to the linker by one of the following:
hlink < x.lnk

Map Files

The map contains information relating to the relocation of psects and the addresses assigned to symbols within those psects. The sections in the map are as follows is a copy of the command line used to invoke the linker. This is followed by the version number of the object code in the linked, and the machine type. This is optionally followed by call graph information, depended on the processor and memory model selected. Then are listed all object that were linked, along with their psect information. Libraries are listed, with each module within the library. The TOTALS section summarises the psects from the object The SEGMENTS section summarises major memory groupings. This will typically show RAM and ROM usage. The segment names are derived from the name of the psect in the segment.

Lastly not shown in the example is a symbol table, where each global symbol is listed with its associated psect and link address.

Linker command line -z -Mmap -pvectors=00h,text,strings,const,im2vecs -pbaseram=00h -pnvram=bss,heap hello.obj

Map Files

Linker and Utilities

Object code version is

Machine type is Z80

Name
vectors
const
text
hello.obj
text
powerup.obj vectors

TOTAL

Name

CLASS CODE
vectors
const
text

CLASS DATA

SEGMENTS

Name
vectors

Link Load Length Selector
Ordering of Libraries

The librarian creates libraries with the modules in the order in which they were given on the command line. When updating a library the order of the modules is preserved. Any new modules added to a library after it has been created will be appended to the end.
The ordering of the modules in a library is to the linker. If a library contains a module which references a symbol in another module in the same library, the module the symbol should come after the module referencing the symbol.

Error Messages

LIBR issues various error messages, most of which represent a fatal error, while some represent a harmless occurrence which will nonetheless be reported unless the -W option was used. In this case all warning messages will be suppressed.

Objtohex

The HI-TECH linker is capable of producing simple binary or object as output. Any other format required must be produced by running the utility program OBJTOHEX. This allows conversion of object as produced by the linker into a variety of different formats, including various hex formats. The program is invoked thus:

OBJTOHEX options inputfile outputfile

All of the arguments are optional. If outputfile is omitted it defaults to l.hex or l.bin depending on whether the -b option is used. The inputfile defaults to l.obj.

The options for OBJTOHEX are listed in Table Where an address is required, the format is the same as for HLINK.

Objtohex

Linker and Utilities

Option -8 -A -Bbase
-Cckfile
-D -E -Ffill
-M -N -Pstk -R -Sfile -T -TE -U -UB -V -n,m

Table OBJTOHEX command-line options Meaning

Linker and Utilities

Cref

Checksum

If you are generating a HEX output, please refer to the hexmate section for calculating checksums. For OBJTOHEX, the checksum allows automated checksum calculation and takes the form of several lines, each line describing one checksum. The syntax of a checksum line is:
addr1-addr2 where1-where2 +offset

All of addr1, addr2, where1, where2 and offset are hex numbers, without the usual H Such a says that the bytes at addr1 through to addr2 inclusive should be summed and the sum placed in the locations where1 through where2 inclusive. For an 8 bit checksum these two addresses should be the same. For a checksum stored low byte where1 should be less than where2, and vice versa. The +offset is optional, but if supplied, the value offset will be used to initialise the checksum. Otherwise it is initialised to zero. For example:
0005-1FFF 3-4 +1FFF

This will sum the bytes in 5 through 1FFFH inclusive, then add 1FFFH to the sum. The 16 bit checksum will be placed in locations 3 and 4, low byte in The checksum is initialised with 1FFFH to provide protection against an all zero ROM, or a ROM misplaced in memory. A run time check of this checksum would add the last address of the ROM being checksummed into the checksum. For the ROM in question, this should be 1FFFH. The initialization value may, however, be used in any desired fashion.

Cref

The cross reference list utility CREF is used to format raw cross-reference information produced by the compiler or the assembler into a sorted listing. A raw cross-reference is produced with the --CR option to the compiler. The assembler will generate a raw cross-reference with a -C option most assemblers or by using an OPT CRE directive 6800 series assemblers or a XREF control line PIC assembler . The general form of the CREF command is:
cref options files
where options is zero or more options as described below and files is one or more raw crossreference CREF takes the options listed in Table

Each option is described in more detail in the following paragraphs.

Cref

Linker and Utilities

Table CREF command-line options

Option

Meaning
-Fprefix Exclude symbols from with a pathname or
starting with prefix
-Hheading Specify a heading for the listing
-Llen

Specify the page length for the listing
-Ooutfile Specify the name of the listing
-Pwidth

Set the listing width
Specify big-endian byte ordering

Strip underscore character

Verbose mode

Linker and Utilities

Cromwell

Table -P option architecture arguments for COFF output.

Architecture

Motorola 68000 series chips

H8/300

Hitachi 8 bit H8/300 chips

H8/300H

Hitachi 16 bit H8/300H chips

Hitachi 32 bit SuperH RISC chips

PIC12

Microchip base-line PIC chips

PIC14

Microchip mid-range PIC chips

PIC16

Microchip high-end 17Cxxx PIC chips

PIC18

Microchip PIC18 chips

PIC24

Microchip PIC24F and PIC24H chips

PIC30

Microchip dsPIC30 and dsPIC33 chips
format the usage of this option must take the form -Pname,architecture. Table enumerates the architectures supported for producing COFF

To produce some output formats e.g. COFF , Cromwell requires that the names of the program memory space psect classes be provided. The names of the classes are given as a comma separated list. For example, in the DSPIC C compiler these classes are typically “CODE” and “NEARCODE”, i.e. -NCODE,NEARCODE.

The -D option is used to display to the screen details about the named input in a readable format. The input can be one of the types as shown in Table

This option will attempt to identify if the input are one of the formats as shown in Table If the is recognised, a of its type will be displayed.

When generating a COD this option can be used to force all local symbols to be represented as global symbols. The may be useful where an emulator cannot read local symbol information from the COD

Hexmate

Linker and Utilities
-Okey

This option the format of the output The key can be any of the types listed in Table
-Ikey

This option can be used to specify the default input format. The key can be any of the types listed in Table

Use this option to show what format types are supported. A list similar to that given in Table will be shown.

Use this option to tell CROMWELL to ignore any extensions that were given. The default extension will be used instead.
In formats that support different endian types, use this option to specify big-endian byte ordering.

When generating COD this option will remove the preceding underscore character from symbols.

Turns on verbose mode which will display information about operations CROMWELL is performing.

Hexmate

The Hexmate utility is a program designed to manipulate Intel HEX Hexmate is a post-link stage utility that provides the facility to:
• Calculate and store variable-length checksum values

Linker and Utilities

Hexmate
• Fill unused memory locations with known data sequences
• Merge multiple Intel hex into one output
• Convert INHX32 to other INHX formats e.g. INHX8M
• Detect or partial opcode sequences within a hex
• Find/replace or partial opcode sequences
• Provide a map of addresses used in a hex
• Change or the length of data records in a hex
• Validate checksums within Intel hex Typical applications for hexmate might include
• Merging a bootloader or debug module into a main application at build time
• Calculating a checksum over a range of program memory and storing its value in program
memory or EEPROM
• Filling unused memory locations with an instruction to send the PC to a known location if it
gets lost.
• Storage of a serial number at a address.
• Storage of a string e.g. time stamp at a address.
• Store initial values at a particular memory address e.g. initialise EEPROM
• Detecting usage of a buggy/restricted instruction
• Adjusting hex to meet requirements of particular bootloaders

Hexmate Command Line Options

Some of these hexmate operations may be possible from the compiler’s command line driver. However, if hexmate is to be run directly, its usage is:
hexmate <file1.hex fileN.hex> <options>

Hexmate

Linker and Utilities

Table Hexmate command-line options

Option

Effect
-ADDRESSING

Set address in all hexmate options to use word addressing
or other
-BREAK

Break continuous data so that a new record begins at a set
address

Calculate and store a checksum value
-FILL

Program unused locations with a known value
-FIND

Search and notify if a particular code sequence is detected
-FIND...,DELETE Remove the code sequence if it is detected use with caution
-FIND...,REPLACE the code sequence with a new code sequence
-FORMAT

Specify maximum data record length or select INHX variant
-HELP

Show all options or display help message for option
-LOGFILE

Save hexmate analysis of output and various results to a
-Ofile

Specify the name of the output
-SERIAL

Notice: we do not provide any warranties that information, datasheets, application notes, circuit diagrams, or software stored on this website are up-to-date or error free. The archived SW500009 Datasheet file may be downloaded here without warranties.

Datasheet ID: SW500009 636070