SW500009 Microchip Technology, SW500009 Datasheet
SW500009
Specifications of SW500009
778-1003
778-1003
Related parts for SW500009
SW500009 Summary of contents
Page 1
...
Page 2
... 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. 45 Colebard Street West Acacia Ridge QLD 4110 email: hitech@htsoft.com web: http://www.htsoft.com ftp: ftp://www ...
Page 3
Contents Table of Contents List of Tables 1 Introduction 1.1 Typographic conventions 2 PICC Command-line Driver 2.1 Long Command Lines 2.2 Default Libraries . . . . . . . . . . . . . . . . . ...
Page 4
CONTENTS 2.4.17 --ASMLIST: Generate Assembler .LST Files 2.4.18 --CHAR=type: Make Char Type Signed or Unsigned 2.4.19 --CHECKSUM=start-end@destination<,specs>: Calculate a check- sum . . . . . . . . . . . . . . . . . . . ...
Page 5
CONTENTS 2.4.52 --SUMMARY=type: Select Memory Summary Output Type 2.4.53 --TIME: Report time taken for each phase of build process 2.4.54 --VER: Display The Compiler’s Version Information 2.4.55 --WARN=level: Set Warning Level 2.4.56 --WARNFORMAT=format: Set Warning Message Format 3 C Language ...
Page 6
CONTENTS 3.4.3 8-Bit Integer Data Types and Variables 3.4.4 16-Bit Integer Data Types 3.4.5 32-Bit Integer Data Types and Variables 3.4.6 Floating Point Types and Variables 3.4.7 Structures and Unions 3.4.7.1 Bit-fields in Structures 3.4.7.2 Structure and Union Qualifiers 3.4.8 ...
Page 7
CONTENTS 3.10.1.4 MidRange Context Saving 3.10.1.5 High-End Context Saving 3.10.1.6 Context Restoration 3.10.1.7 Interrupt Levels 3.10.1.8 Multiple Interrupts on High-End PICs 3.10.1.9 Enabling Interrupts 3.11 Mixing C and Assembler Code 3.11.1 External Assembly Language Functions 3.11.2 #asm, #endasm and asm() ...
Page 8
CONTENTS 4.3.4 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 ...
Page 9
CONTENTS 4.3.9.2 EXPAND 4.3.9.3 INCLUDE 4.3.9.4 LIST 4.3.9.5 NOCOND 4.3.9.6 NOEXPAND 4.3.9.7 NOLIST 4.3.9.8 NOXREF 4.3.9.9 PAGE 4.3.9.10 SPACE 4.3.9.11 SUBTITLE 4.3.9.12 TITLE 4.3.9.13 XREF 5 Linker and Utilities 5.1 Introduction . . . . . . . . . ...
Page 10
CONTENTS 5.9.6 -Dsymfi 127 ...
Page 11
CONTENTS 5.14.3 -Llen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 12
CONTENTS B Error and Warning Messages C Chip Information Index xii CONTENTS 275 403 409 ...
Page 13
List of Tables 2.1 PICC file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 14
LIST OF TABLES 4.5 ASPIC assembler directives 4.6 PSECT flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 15
Chapter 1 Introduction 1.1 Typographic conventions Different fonts and styles are used throughout this manual to indicate special words or text. Com- puter prompts, responses and filenames will be printed in constant-spaced type. When the filename is the name of ...
Page 16
Typographic conventions 2 Introduction ...
Page 17
Chapter 2 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 conventional to supply the options (identified by ...
Page 18
Long Command Lines all object files resulting from compilation or assembly, or those listed explicitly on the command line, will be linked together with the standard runtime code and libraries and any user-specified libraries. Functions in libraries will be linked ...
Page 19
PICC Command-line Driver 2.4 PICC Compiler Options Most aspects of the compilation can be controlled using the command-line driver, PICC. The driver will configure and execute all required applications, such as the code generator, assembler and linker. PICC recognizes the ...
Page 20
PICC Compiler Options Option --ERRORS=number --FILL=opcode --GETOPTION=app,file --HELP<=option> --IDE=ide --LANG=language --MEMMAP=file --MSGFORMAT<=format> --MSGDISABLE<=numbers> --NODEL --NOEXEC --OPT<=type> --OUTDIR --OUTPUT=type --PRE --PROTO --RAM=lo-hi<,lo-hi,...> --ROM=lo-hi<,lo-hi,...> --RUNTIME=type --SCANDEP --SERIAL=code@address --SETOPTION=app,file --SETUP=argument --STRICT --SUMMARY=type --TIME --VER --WARN=level continued PICC Command-line Options Meaning ...
Page 21
PICC Command-line Driver Option --WARNFORMAT=format All single letter options are identifi leading dash character, “-”, e.g. -C. Some single letter options specify an additional data field which follows the option name immediately and without any whitespace, e.g. -Ddebug. ...
Page 22
PICC Compiler Options 2.4.2 -Dmacro: Define Macro The -D option is used to define a preprocessor macro on the command line, exactly had been defined using a #define directive in the source code. This option may take ...
Page 23
PICC Command-line Driver If you wish to compile several files and combine all of the errors generated into a single text file, use the -E option to create the file then use -E+ when compiling all the other source files. ...
Page 24
PICC Compiler Options will search the directories c:\include and d:\myapp\include for any header files included into the source code, then search the default include directory (the include directory where the compiler was installed). This option has no effect for files ...
Page 25
PICC Command-line Driver The -L option is especially useful when linking code which contains non-standard program sections (or psects), as may be the case if the program contains C code which makes use of the #pragma psect directive or assembly ...
Page 26
PICC Compiler Options that the psects should be linked so that one follows two, which follows three, and that the highest address of one should be located at 5FFh. This new arragement can be specified issuing the following driver option: ...
Page 27
... By default, assembler files are not preprocessed. 2.4.12 -Q: Quiet Mode This option places the compiler in a quiet mode which suppresses the HI-TECH Software copyright notice from being displayed. 2.4.13 -S: Compile to Assembler Code The -S option stops compilation after generating an assembler source file. An assembler file will be generated for each C source fi ...
Page 28
PICC Compiler Options 2.4.15 -V: Verbose Compile The -V is the verbose option. The compiler will display the full command lines used to invoke each of the compiler applications or compiler passes. This option may be useful for determining the ...
Page 29
PICC Command-line Driver Table 2.3: Default values for filling unprogrammed code space ,algorithm=n Select one of the checksum algorithms implemented in hexmate. The selectable al- gorithms are described in Table 5.10. The start, end and destination attributes can be entered ...
Page 30
PICC Compiler Options Suboption 24 32 fast32 reference information into the listing file, in this case test.crf. If multiple source files are to be included in the cross reference listing, all must be compiled and linked with the one PICC ...
Page 31
PICC Command-line Driver reading the error output, but is not generally usable with environments which support compiler error handling. The following sections indicate how this option may be used in such situations. This option allows the exact format of printed ...
Page 32
PICC Compiler Options --ERRFORMAT=”file %f; line %l; column %c; %s” The column number is relative to the left-most non-space character on the source line. To instruct the compiler to use an environment variable to determine the message format, use the ...
Page 33
... Table 2.7 shows those langauges currently supported. See Section 2.4.27.1 for full details of the messaging system employed by PICC. Table 2.6: Supported IDEs IDE HI-TECH Software’s HI-TIDE Microchip’s MPLAB Table 2.7: Supported languages Suboption Language English French German PICC Compiler Options ...
Page 34
PICC Compiler Options 2.4.34 --MEMMAP=file: Display Memory Map This option will display a memory map for the specified map file. This option is seldom required, but would be useful if the linker is being driven explicitly, i.e. instead of in ...
Page 35
PICC Command-line Driver Option name 1..9 asm speed space debug none 2.4.40 --OUTDIR: Specify a directory for output files This option allows a directory to be nominated in for PICC to locate its output files. If this option is omitted, ...
Page 36
PICC Compiler Options Option name lib intel tek aahex mot ubrof bin mcof cof cod elf the same base name as the corresponding source file. Prototype files contain both ANSI C-style prototypes and old-style C function declarations within conditional compilation ...
Page 37
PICC Command-line Driver PICC --CHIP=16F877A --PROTO test.c PICC will produce test.pro containing the following declarations which may then be edited as necessary: /* Prototypes from test extern functions - include these in a header file */ #if PROTOTYPES ...
Page 38
PICC Compiler Options 2.4.45 --ROM=lo-hi,<lo-hi,...>|tag: Specify Additional ROM Ran- ges This option is used to specify memory, in addition to any ROM specified in the chip configuration file, which should be treated as available ROM space. Strictly speaking, this option ...
Page 39
PICC Command-line Driver Table 2.10: Runtime environment suboptions Suboption The code present in the startup module that clear clears the rbss psects. The inclusion of library files into the output clib code by the linker. Conditions the application and the ...
Page 40
PICC Compiler Options 2.4.48 --SERIAL=hexcode@address: Store a Value at this Program Mem- ory Address This option allows a hexadecimal code to be stored at a particular address in program memory. A typical application for this option might be to position ...
Page 41
PICC Command-line Driver Table 2.11: Memory Summary Suboptions Suboption Summary of psect usage. psect Summary of class usage. class General summary of memory used. mem Summary of address used within the hex hex file. Whether summary information is shown file ...
Page 42
PICC Compiler Options 2.4.55 --WARN=level: Set Warning Level The --WARN option is used to set the compiler warning level. Allowable warning levels range from - The warning level determines how pedantic the compiler is about dubious type conversions ...
Page 43
Chapter 3 C Language Features HI-TECH PICC STD supports a number of special features and extensions to the C language which are designed to ease the task of producing ROM-based applications. This chapter documents the compiler options and special language ...
Page 44
Processor-related Features 3.2.2 Configuration Fuses The PIC processor’s configuration fuses (or configuration bits) may be set using the __CONFIG macro as follows: __CONFIG(x); Note there are two leading underscore characters and x is the value that ...
Page 45
C Language Features 3.2.4 Bit Instructions Wherever possible, HI-TECH C will attempt to use the PIC bit instructions. For example, when using a bitwise operator and a mask to alter a bit within an integral type, the compiler will check ...
Page 46
Processor-related Features The compiler will produce the appropriate code to access EEPROM and is particularly efficient when accessing multi-byte variables. Unlike conventional RAM variables initialized EEPROM variable is modified during runtime, next time the processor is reset the ...
Page 47
C Language Features 3.2.5.3 EEPROM Access Functions The library functions eeprom_read() and eeprom_write(), can be called to read from, and write to the EEPROM during program execution. For example, to write a byte-size value to an address in EEPROM and ...
Page 48
Processor-related Features Be aware that if a program contains multiple instances of either macro, any code space saving will be negated as the full content of the macro is now duplicated in code space. In the case of EEPROM_READ(), there ...
Page 49
C Language Features 3.2.6.2 Flash Access Functions The flash_read() function provides the same functionality as the FLASH_READ() macro but will potentially cost less in code space if multiple invocations are required. The flash_copy() function allows duplication of a block of ...
Page 50
Processor-related Features TRIS = 0xFF; This will load the appropriate value into the W register and then call the tris instruction. Those PIC devices which have more than one output port may have definitions for objects: TRISA, TRISB and TRISC, ...
Page 51
C Language Features the appropriate location in program memory. Remember to remove this instruction when program- ming the actual part so you do not destroy the calibration value. 3.3 Files 3.3.1 Source Files The extension used with source files is ...
Page 52
Files Figure 3.1: Library Naming Convention RAM Banks For Midrange processors that have common memory, a letter is used rather than a number. For example, where ’0’, ’1’ or ’2’ might have been used ...
Page 53
C Language Features Since the runtime startup code is generated automatically on every compilation, the generated files associated with this process are deleted after they have been used. If required, the assembler file which contains the runtime startup code can ...
Page 54
Files 3.3.4.2 Clearing the Bss Psects The ANSI standard dictates that those non-auto objects which are not initialized must be cleared before execution of the program begins. The compiler does this by grouping all such uninitialized objects into a bss ...
Page 55
C Language Features Type bit char unsigned char short unsigned short int unsigned int long unsigned long float double you are using a powerup routine and will automatically generate code to jump to it after reset. If you use a ...
Page 56
Supported Data Types and Variables Radix binary octal decimal hexadecimal double by HI-TECH C. Character constants are enclosed by single quote characters ’, for example ’a’. A character constant has char type. Multi-byte character constants are not supported. String constants ...
Page 57
C Language Features static bit init_flag; will be allocated in the bit-addressable psect rbit, and will be visible only in that function. When the following declaration is used outside any function: bit init_flag; init_flag will be globally visible, but located ...
Page 58
Supported Data Types and Variables 3.4.3 8-Bit Integer Data Types and Variables HI-TECH PICC STD supports both signed char and unsigned char 8-bit integral types. If the signed or unsigned keyword is absent from the variable’s definition, the default type ...
Page 59
C Language Features Format IEEE 754 32-bit modified IEEE 754 24-bit Variables may be declared using the signed long int and unsigned long int keyword se- quences, respectively, to hold values of these types. Where only long int is used ...
Page 60
Supported Data Types and Variables Table 3.4: Floating-point format example IEEE 754 Format Number biased expo- nent 32-bit 7DA6B69Bh 11111011b 24-bit 42123Ah 10000100b Variables may be declared using the float and double keywords, respectively, to hold values of these types. ...
Page 61
C Language Features will produce a structure occupying 1 bytes. If foo was ultimately linked at address 10H, the field lo will be bit 0 of address 10H, hi will be bit 7 of address 10H. The least significant bit ...
Page 62
Supported Data Types and Variables struct { const int number; int * const ptr; } record = { 0x55, &i}; 3.4.8 Standard Type Qualifiers Type qualifiers provide information regarding how an object may be used, in addition to its type ...
Page 63
C Language Features 3.4.9.1 Persistent Type Qualifier By default, any C variables that are not explicitly initialised are cleared to zero on startup. This is consistent with the definition of the C language. However, there are occasions where it is ...
Page 64
Supported Data Types and Variables 3.4.10 Eeprom Type Qualifier The eeprom qualifier is used to to place static variables into EEPROM. Since accessing EEPROM memory is a lot less efficient than accessing RAM, only very basic C expressions are supported. ...
Page 65
C Language Features RAM pointers are 8-bits and therefore can only access 256 bytes. A pointer which is unqual- ified or has a bank 1 qualifier can point to any object in bank 0 or bank 1. If the pointer ...
Page 66
Storage Class and Object Placement object’s_type_&_qualifiers * pointer’s_qualifiers pointer’s_name = value; The rule is as follows: if the modifi the left of the * in the pointer declaration, it applies to the object which the pointer references. If ...
Page 67
C Language Features 3.5.1.1 Auto Variables Auto (short for automatic) variables are the default type of local variable. Unless explicitly declared to be static a local variable will be made auto, however the auto keyword may be used if desired. ...
Page 68
Functions _Portvar EQU 06h This construct is primarily intended for equating the address identifier with a microprocessor special function register. To place a user-defined variable at an absolute address, defi separate psect and instruct ...
Page 69
C Language Features movlw 08h movwf ?_test clrf ?_test+1 movf _a,w call (_test) In this example, the parameter b is held in the memory locations ?_test and ?_test+1. If you need to determine, for assembler code for example, the exact ...
Page 70
Function Calling Convention 3.6.2.1 Structure Return Values Composite return values (struct and union) of size 4 bytes or smaller are returned in memory as with 16-bit and 32-bit return values. For composite return values of greater than 4 bytes in ...
Page 71
C Language Features lookup table is accessed after the function called has finished executing. This method allows func- tions to be nested without overflowing the stack, however it does come at the expense of memory and program speed. To disable ...
Page 72
Operators unsigned char count, a=0, b=50; if < 10) count++; The unsigned char result 206 (which is not less than 10), but both a and b are con- verted to signed int via ...
Page 73
C Language Features Operand the unsigned int result was converted back to unsigned char, the final result would be the same 8-bit addition is more efficient than a 16-bit addition, the compiler will ...
Page 74
Psects assembler code. The linker will group all data for a particular psect into a single segment. If you are using PICC to invoke the linker, you don’t need to worry about the information doc- umented here, except as background ...
Page 75
C Language Features intret Is the psect which contains the executable code responsible for restoring saved registers and objects after an interrupt routine has completed executing. jmp_tab Only for the Baseline processors, this is another strings psect used to store ...
Page 76
Interrupt Handling in C rbit_n These psects are used to store all bit variables except those declared at absolute locations. rbss_n These psects contain any uninitialized variables. rdata_n These psects contain any initialised variables. struct Contains any structure which is ...
Page 77
... Context Saving on Interrupts The PIC processor only saves the PC on its stack whenever an interrupt occurs. Other registers and objects must be saved in software. The PICC compiler determines which registers and objects are used by an interrupt function and saves these appropriately. If the interrupt routine calls other functions and these functions are defined before the interrupt code in the same module, then any registers used by these functions will be saved as well ...
Page 78
Interrupt Handling context saving is required, this is performed by code placed psect called intentry which will be placed at the interrupt vector. Any registers or objects to be saved are done so to ...
Page 79
C Language Features In addition, any non-interrupt functions that are called from an interrupt function and also from main-line code may also use the #pragma interrupt_level directive to specify that they will never be called by interrupt functions of one ...
Page 80
Mixing C and Assembler Code 3.10.1.9 Enabling Interrupts Two macros are available in <htc.h> which control the masking of all available interrupts. These macros are ei(), which enable or unmask all interrupts, and di(), which disable or mask all interrupts. ...
Page 81
C Language Features write the routine ensuring arguments are read from the correct location, the return value is loaded to the correct storage location before returning ensure any local variables required by the routine have space reserved by the appropriate ...
Page 82
Mixing C and Assembler Code extern unsigned int add(unsigned a, unsigned b); void main(void) { int a, result read_port(); result = add(5, a); } 3.11.2 #asm, #endasm and asm() PIC instructions may also be directly embedded “in-line” into ...
Page 83
C Language Features When using in-line assembler code, great care must be taken to avoid interacting with compiler- generated code. The code generator cannot scan the assembler code for register usage and so will remain unaware if registers are clobbered ...
Page 84
Preprocessing 3.12 Preprocessing All C source files are preprocessed before compilation. Assembler files can also be preprocessed if the -P command-line option is issued. 3.12.1 Preprocessor Directives HI-TECH PICC STD accepts several specialised preprocessor directives in addition to the standard ...
Page 85
C Language Features Directive Meaning preprocessor null directive nothing generate error if condition false #assert signifies the beginning of in-line #asm assembly define preprocessor macro #define short for #else #if #elif conditionally include source lines #else terminate in-line ...
Page 86
Preprocessing Symbol When set Always HI_TECH_C Always _HTC_VER_MAJOR_ Always _HTC_VER_MINOR_ Always _HTC_VER_PATCH_ Always _HTC_EDITION_ Always __PICC__ Always _MPC_ If 12-bit device _PIC12 If 14-bit device _PIC14 If 16-bit device _PIC16 If common RAM _COMMON_ present Always _BANKBITS_ Always _GPRBITS_ If ...
Page 87
C Language Features Directive Specify function as inline inline Enable JIS character handling in jis strings Disable JIS character handling (de- nojis fault) Specify structure packing pack Enable printf-style format string printf_check checking Rename compiler-defined psect psect Specify additional registers ...
Page 88
Preprocessing 3.12.3.4 The #pragma printf_check Directive Certain library functions accept a format string followed by a variable number of arguments in the manner of printf(). Although the format string is interpreted at runtime, it can be compile-time checked for consistency ...
Page 89
C Language Features unsigned char read_port(void) { return PORTA; } Now, how do we know in which psect the code associated with the function will be placed? Compile you program, including this new module and generate an assembly list file, ...
Page 90
Preprocessing Register Name btemp, btemp+1...btemp+11 fsr tablreg w switch type auto direct where register_list is a comma-separated list of registers names. Those registers not listed are assumed to be unused by the function or routine. The code generator may use ...
Page 91
C Language Features 3.13 Linking Programs The compiler will automatically invoke the linker unless requested to stop after producing assembler code (PICC -S option) or object code (PICC -C option). HI-TECH C, by default, generates Intel HEX. Use the --OUTPUT= ...
Page 92
Linking Programs 3.13.2 Signature Checking The compiler automatically produces signatures for all functions. A signature is a 16-bit value computed from a combination of the function’s return data type, the number of its parameters and other information affecting the calling ...
Page 93
C Language Features Table 3.12: Supported standard I/O functions Function name printf(const char * s, ...) sprintf(char * buf, const char * s, ...) 3.13.3 Linker-Defined Symbols The link address of a psect can be obtained from the value of ...
Page 94
Standard I/O Functions and Serial I Language Features ...
Page 95
Chapter 4 Macro Assembler The Macro Assembler included with HI-TECH PICC STD assembles source files for PIC MCUs. This chapter describes the usage of the assembler and the directives (assembler pseudo-ops and controls) accepted by the assembler in the source ...
Page 96
Assembler Options where the assembler is being called directly, or when they are specified using the command-line driver option --SETOPTION, see Section 2.4.49. The usage of the assembler is similar under all of available operating systems. All command-line options are ...
Page 97
Macro Assembler -A An assembler file with an extension .opt will be produced if this option is used. This is useful when checking the optimized assembler produced using the -O option cross reference file will be produced when ...
Page 98
HI-TECH C Assembly Language -Ooutfile By default the assembler determines the name of the object fi created by stripping any suffix or extension (i.e. the portion after the last dot) from the first source filename and appending .obj. ...
Page 99
Macro Assembler Format 1 label: Format 2 label: Format 3 name Format 4 ; comment only Format 5 <empty line> 4.3.2 Characters The character set used is standard 7 bit ASCII. Alphabetic case is significant for identifiers, but not mnemonics ...
Page 100
HI-TECH C Assembly Language Table 4.3: ASPIC numbers and bases Radix Binary digits 0 and 1 followed by B Octal digits followed Decimal digits followed ...
Page 101
Macro Assembler $ ?$_12345 4.3.5.1 Significance of Identifiers Users of other assemblers that attempt to implement forms of data typing for identifiers should note that this assembler attaches no significance to any symbol, and places no restrictions or expectations on ...
Page 102
HI-TECH C Assembly Language 4.3.5.4 Register Symbols Code in assembly modules may gain access to the special function registers by including pre-defined assembly header files. The appropriate file can be included by add the line: #include <aspic.h> to the assembler ...
Page 103
Macro Assembler 4.3.6 Expressions The operands to instructions and directives are comprised of expressions. Expressions can be made up of numbers, identifiers, strings and operators. Operators can be unary (one operand, e.g. not) or binary (two operands, e.g. +). The ...
Page 104
HI-TECH C Assembly Language Operator Multiplication * Addition + Subtraction - Division / = or eq Equality > Signed greater than > Signed greater than or equal to < Signed less than <= or ...
Page 105
Macro Assembler DS 2 PSECT text0,class=CODE,delta=2 clear_fred clrf _fred return Note that even though the two blocks of code in the text psect are separated by a block in the rbss psect, the two text psect blocks will be contiguous ...
Page 106
HI-TECH C Assembly Language Table 4.5: ASPIC assembler directives Directive Make symbols accessible to other modules or allow reference to GLOBAL other modules’ symbols End assembly END Declare or resume program section PSECT Set location counter ORG Define symbol value ...
Page 107
Macro Assembler Flag abs bit class=name delta=size global limit=address local ovrld pure reloc=boundary size=max space=area with=psect 4.3.8.3 PSECT The PSECT directive declares or resumes a program section. It takes as arguments a name and, optionally, a comma-separated list of flags. ...
Page 108
HI-TECH C Assembly Language A psect defined as global will be combined with other global psects of the same name from other modules at link time. This is the default behaviour for psects, unless the local flag is used. The ...
Page 109
Macro Assembler 4.3.8.4 ORG The ORG directive changes the value of the location counter within the current psect. This means that the addresses set with ORG are relative to the base address of the psect, which is not determined until ...
Page 110
HI-TECH C Assembly Language 4.3.8 used to initialize storage as bytes. The argument is a list of expressions, each of which will be assembled into one byte. Each character of the string will be assembled into one ...
Page 111
Macro Assembler fred(var1, bill(), 2); will generate the assembler directive FNARG _fred,_bill thereby telling the linker that bill() is called while evaluating the arguments for a call to fred(). 4.3.8.12 FNBREAK This directive is used to break links in the ...
Page 112
HI-TECH C Assembly Language where psect is the psect containing the call graph, auto is the prefix on all auto variable symbol names and args is the prefix on all function argument symbol names. This directive normally appears in only ...
Page 113
Macro Assembler 4.3.8.18 IF, ELSIF, ELSE and ENDIF These directives implement conditional assembly. The argument to IF and ELSIF should be an absolute expression non-zero, then the code following the next matching ELSE, ELSIF ...
Page 114
HI-TECH C Assembly Language movlf 2,tempvar expands to: movlw 2 movwf tempvar mod 080h A point to note in the above example: the & character is used to permit the concatenation of macro parameters with other text, but is removed ...
Page 115
Macro Assembler when expanded will include a unique assembler generated label in place of more. For example: down foobar expands to: ??0001 decfsz foobar goto ??0001 if invoked a second time, the label more would expand to ??0002. 4.3.8.21 ALIGN ...
Page 116
HI-TECH C Assembly Language 4.3.8.23 IRP and IRPC The IRP and IRPC directives operate similarly to REPT, however instead of repeating the block a fixed number of times repeated once for each member of an argument list. In ...
Page 117
Macro Assembler 4.3.8.24 PROCESSOR The output of the assembler may vary depending on the target device. The device name is typically set using the --CHIP option to the command-line driver PICC, see Section 2.4.20, or using the assembler -P option, ...
Page 118
HI-TECH C Assembly Language Table 4.7: ASPIC assembler controls 1 Control Include conditional code in the listing COND* Expand macros in the listing output EXPAND Textually include another source file INCLUDE Define options for listing output LIST* Leave conditional code ...
Page 119
Macro Assembler List Option Default 80 c=nnn 59 n=nnn OFF t=ON|OFF n/a p=<processor> hex r=<radix> OFF x=ON|OFF 4.3.9.6 NOEXPAND NOEXPAND disables macro expansion in the listing file. The macro call will be listed instead. See also the EXPAND control in ...
Page 120
HI-TECH C Assembly Language 4.3.9.12 TITLE This control keyword defines a title to appear at the top of every listing page. The string should be enclosed in single or double quotes. See also the SUBTITLE control in Section 4.3.9.11. 4.3.9.13 ...
Page 121
Chapter 5 Linker and Utilities 5.1 Introduction HI-TECH C incorporates a relocating assembler and linker to permit separate compilation of C source files. This means that a program may be divided into several source files, each of which may be ...
Page 122
Program Sections relocation by the ultimate value of a global symbol, or relocation by psect, i.e. relocation by the base address of a particular section of code, for example the section of code containing the actual executable instructions. 5.3 Program ...
Page 123
Linker and Utilities as static. These symbols may be referred to by modules other than the one in which they are defined the linker’s job to match up the definition of a global symbol with the references to ...
Page 124
Compiled Stack Operation Each function in the call graph is allocated an auto/parameter block (APB) for its parameter, auto and temporary variables. Temporary variables act just like auto variables. Local variables which are qualified static are not part of this ...
Page 125
Linker and Utilities stack program, a function must be considered active as soon as its parameter area has been modified in preparation for a call, even though code in that function is not yet being executed and a call to ...
Page 126
Map Files 5.7.2 Implicit Calls to Assembler Library Routines Evaluation of certain C operators will require the use of assembly routines that are precompiled into the object code library files. The code generator will call these routines as required. These ...
Page 127
... A typical map file may begin something like the following. This example has been cut down for clarity and brevity, and should not be used for reference. HI-TECH Software PICC Compiler std#V9.60 Linker command line: --edf=C:\Program Files\HI-TECH Software\pic\std\9.60\dat\en_msgs.txt \ -h+conv.sym -z -Q16F73 -ol.obj -Mconv.map -ver=PICC#std#V9.60 \ ...
Page 128
... C:\DOCUME~1\user\LOCALS~1\Temp\cgta5eHNF.obj conv.obj \ C:\Program Files\HI-TECH Software\pic\std\9.60\lib\pic412-c.lib \ C:\Program Files\HI-TECH Software\pic\std\9.60\lib\pic20--u.lib Object code version is 3.9 Machine type is 16F73 The Linker command line shown is the entire list of options and files that were passed to the linker for the build recorded by this map fi ...
Page 129
Linker and Utilities 5.8.2.2 Call Graph Information A call graph is produced and displayed in the map file for target devices and memory models that use a compiled stack to facilitate parameter passing between functions and auto variables. See Section ...
Page 130
Map Files _convert size 4,0 offset 33 _srv size 2,10 offset 21 _convert size 4,0 offset 33 * _srv size 2,10 offset 21 * _convert size 4,0 offset 33 _init size 0,4 offset 4 indir_func size 0,0 offset 4 Estimated ...
Page 131
Linker and Utilities int test(void) { int if(a) foo(); else bar(); } the function foo will never appear in the call graph. The inclusion of a function into the call graph is controlled by the FNCALL assembler ...
Page 132
Map Files If the ARG flag appears after a function’s name, this implies that the call to this “ARG function” involves other function calls to determine the parameter values for this function. For example, if input and output are both ...
Page 133
Linker and Utilities T UT RIAL I P NTERPRETING A RO COMPILER CALL GRAPH dicates that the program compiled consists of two call trees rooted at the functions: main, which can have up 3 levels of stack used, and intlevel1, ...
Page 134
Map Files The other call tree rooted at intlevel1 relates to the interrupt function. intlevel1 is not a real function, but is used to represent the interrupt level associated with the interrupt function. There is no call from intlevel1 to ...
Page 135
Linker and Utilities a different location and which are mapped before program execution.) The Length of the psect is shown (in units suitable for that psect). The Selector is less commonly used, but the Space field is important as it ...
Page 136
... Modules derived from library files area also shown in this list. The name of the library file is printed as a header, followed by a list of the modules that contributed to the output. Only mod- ules that define symbols that are referenced are included in the program output. For example, the following: C:\program files\HI-TECH Software\PICC-18\9.50\lib\pic86l-c.lib i1aldiv.obj text 174 174 aldiv.obj text indicates that both the i1aldiv.obj and aldiv.obj modules were linked in from the library fi ...
Page 137
Linker and Utilities 5.8.2.5 Segment Listing The class listing in the map file is followed by a listing of segments. A segment is conceptual grouping of contiguous psects, and are used by the linker as an aid in psect placement. ...
Page 138
Operation Global assembly labels; Global EQU/SET assembler directive labels; and Linker-defined symbols. Assembly symbols are made global via the GLOBAL assembler directive, see Section information. linker-defined symbols act like EQU directives, however they are defined by the linker during the ...
Page 139
Linker and Utilities Table 5.1: Linker command-line options Option -8 -Aclass=low-high,... -Cx -Cpsect=class -Cbaseaddr -Dclass=delta -Dsymfile -Eerrfile -F -Gspec -Hsymfile -H+symfile -I -Jnum -K -L -LM -N -Nc -Ns -Mmapfile -Ooutfile -Pspec -Qprocessor -S -Sclass=limit[,bound] -Usymbol -Vavmap -Wwarnlev -Wwidth -X ...
Page 140
Operation 5.9.1 Numbers in linker options Several linker options require memory addresses or sizes to be specified. The syntax for all these is similar. By default, the number will be interpreted as a decimal value. To force interpretation as a ...
Page 141
Linker and Utilities 5.9.5 -Dclass=delta This option allows the delta value for psects that are members of the specified class to be defined. The delta value should be a number and represents the number of bytes per addressable unit of ...
Page 142
Operation or some bank-switched arrangements. In this instance the -G option is used to specify a method for calculating the segment selector. The argument string similar to: A/10h-4h where A represents the load address of the ...
Page 143
Linker and Utilities 5.9.14 -I Usually failure to resolve a reference to an undefined symbol is a fatal error. Use of this option will cause undefined symbols to be treated as warnings instead. 5.9.15 -L When the linker produces an ...
Page 144
Operation -Ppsect=lnkaddr+min/ldaddr+min,psect=lnkaddr/ldaddr, ... There are several variations, but essentially each psect is listed with its desired link and load ad- dresses, and a minimum value. All values may be omitted, in which case a default will apply, depending on previous ...
Page 145
Linker and Utilities This example shows text at zero, data linked at 8000h but loaded after text, bss is linked and loaded at 8000h plus the size of data, and nvram and heap are concatenated with bss. Note here the ...
Page 146
Operation If the bound (boundary) argument is used, the class of psects will start on a multiple of the bound address. This example places the FARCODE class of psects at a multiple of 1000h, but with an upper address limit ...
Page 147
Linker and Utilities 5.10 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 ...
Page 148
Map Files Object code version is 2.4 Machine type is Z80 Name C:\HT-Z80\LIB\rtz80-s.obj vectors bss const text hello.obj text C:\HT-Z80\LIB\z80-sc.lib powerup.obj vectors TOTAL Name CLASS CODE vectors const text CLASS DATA bss SEGMENTS Name vectors bss 5.11.1 Call Graph Information ...
Page 149
Linker and Utilities INDIRECT 4194 INDIRECT 4194 *_isr->_incr size 2,0 offset 15 The graph shows the functions called and the memory usage (RAM) of the functions for their own local objects. In the example above, the symbol _main is associated ...
Page 150
Librarian calls the function incr(), which is shown shorthand in the graph by the -> symbol followed by the called function’s name instead of having that function shown indented on the following line. This is done whenever the calling function ...
Page 151
Linker and Utilities Table 5.2: Librarian command-line options Option -Pwidth -W Table 5.3: Librarian key letter commands 5.12.1 The Library Format The modules in a library are basically just concatenated, but at the beginning of a library is main- tained ...
Page 152
Librarian replaced or extracted respectively. Adding a fi library is performed by requesting the librarian to replace it in the library. Since it is not present, the module will be appended to the library. If the r key ...
Page 153
Linker and Utilities 5.12.5 Listing Format A request to LIBR to list module names will simply produce a list of names, one per line, on standard output. The s keyletter will produce the same, with a list of symbols after ...
Page 154
Objtohex Table 5.4: OBJTOHEX command-line options Option Produce a CP/M-86 output file -8 Produce an ATDOS .atx output file -A Produce a binary file with offset of base. Default file name is -Bbase l.obj Read a list of checksum specifications ...
Page 155
Linker and Utilities 5.13.1 Checksum Specifications If you are generating a HEX file output, please refer to the hexmate section checksums. For OBJTOHEX, the checksum specification allows automated checksum calculation and takes the form of several lines, each line describing ...
Page 156
Cref Table 5.5: CREF command-line options Option -Fprefix -Hheading -Llen -Ooutfile -Pwidth -Sstoplist -Xprefix 5.14.1 -Fprefi often desired to exclude from the cross-reference listing any symbols defined in a system header file, e.g. <stdio.h>. The -F option allows ...
Page 157
Linker and Utilities 5.14.5 -Pwidth This option allows the specification of the width to which the listing formatted, e.g. -P132 will format the listing for a 132 column printer. The default is 80 columns. 5.14.6 -Sstoplist The ...
Page 158
... Table 5.6: CROMWELL format types Key Format Bytecraft COD file COFF file format ELF/DWARF file Extended OMF-51 format HI-TECH Software format ICOFF file format Intel HEX file format Microchip COFF file format OMF-51 file format P&E file format Motorola HEX file format ...
Page 159
Linker and Utilities Table 5.8: -P option architecture arguments for COFF file output. Architecture 68K H8/300 H8/300H SH PIC12 PIC14 PIC16 PIC18 PIC24 PIC30 format the usage of this option must take the form: -Pname,architecture. Table the architectures supported for ...
Page 160
Hexmate 5.15.6 -Okey This option specifies the format of the output file. The key can be any of the types listed in Table 5.6. 5.15.7 -Ikey This option can be used to specify the default input file format. The key ...
Page 161
Linker and Utilities Fill unused memory locations with known data sequences Merge multiple Intel hex files into one output file Convert INHX32 files to other INHX formats (e.g. INHX8M) Detect specific or partial opcode sequences within a hex file Find/replace ...
Page 162
Hexmate Table 5.9: Hexmate command-line options Option Effect Set address fields in all hexmate options to use word addressing -ADDRESSING or other Break continuous data so that a new record begins at a set -BREAK address Calculate and store a ...
Page 163
Linker and Utilities Where file1.hex through to fileN.hex are a list of input Intel hex files to merge using hexmate. Ad- ditional options can be provided to further customize this process. Table options that hexmate accepts. The input parameters to ...
Page 164
Hexmate 5.16.1.3 -ADDRESSING By default, all address parameters in hexmate options expect that values will be entered as byte addresses. In some device architectures the native addressing format may be something other than byte addressing. In these cases it would ...
Page 165
Linker and Utilities Table 5.10: Hexmate Checksum Algorithm Selection Selector - Algorithm is an integer to select which hexmate algorithm to use to calculate the checksum result. A list of selectable algorithms are ...
Page 166
Hexmate will program opcode 1234h in all unused addresses from program memory address 0 to 1FFFh (Note the endianism). -FILL accepts whole bytes of hexadecimal data from bytes in length. Adding the ,data flag to this option ...
Page 167
Linker and Utilities to. Any messaging or reports generated by hexmate will refer to this opcode by the name, ADDXY as this was the title defined for this search. If hexmate is generating a log file, it will contain the ...
Page 168
Hexmate Table 5.11: INHX types used in -FORMAT option Type Cannot program addresses beyond 64K. INHX8M Can program addresses beyond 64K with extended linear address records. INHX32 INHX32 with initialization of upper address to zero. INHX032 Length is optional and ...
Page 169
Linker and Utilities 5.16.1.12 -LOGFILE The -LOGFILE option saves hex file statistics to the named file. For example: -LOGFILE=output.log will analyse the hex file that hexmate is generating and save a report to a file named output.log. 5.16.1.13 -Ofile The ...
Page 170
Hexmate 5.16.1.15 -SIZE Using the -SIZE option will report the number of bytes of data within the resultant hex image to standard output. The size will also be recorded in the log file if one has been requested. 5.16.1.16 -STRING ...
Page 171
Appendix A Library Functions The functions within the standard compiler library are listed in this chapter. Each entry begins with the name of the function. This is followed by information decomposed into the following categories. Synopsis the C declaration of ...
Page 172
Synopsis #include <htc.h> __CONFIG(data) Description This macro is used to program the configuration fuses that set the device into various modes of operation. The macro accepts the 16-bit value update it with. 16-Bit masks have been ...
Page 173
Library Functions __EEPROM_DATA Synopsis #include <htc.h> __EEPROM_DATA(a,b,c,d,e,f,g,h) Description This macro is used to store initial values into the device’s EEPROM registers at the time of program- ming. The macro must be given blocks of 8 bytes to write each time ...
Page 174
Synopsis #include <htc.h> __IDLOC(x) Description This macro places data into the device’s special locations outside of addressable memory reserved for ID. This would be useful for storage of serial numbers etc. The macro will attempt to write 4 nibbles ...
Page 175
Library Functions __IDLOC7 Synopsis #include <htc.h> __IDLOC7(a,b,c,d) Description This macro places data into the device’s special locations outside of addressable memory reserved for ID. This would be useful for storage of serial numbers etc. The macro will attempt to write ...
Page 176
Synopsis void _ram_cell_test(void) Description Should not be called from user code. This routine is called from a loop within the generated runtime startup code if the system requires a RAM integrity test before program execution. Upon entry to this ...
Page 177
Library Functions ABS Synopsis #include <stdlib.h> int abs (int j) Description The abs() function returns the absolute value of j. Example #include <stdio.h> #include <stdlib.h> void main (void) { int a = -5; printf("The absolute value %d\n", ...
Page 178
ACOS Synopsis #include <math.h> double acos (double f) Description The acos() function implements the inverse of cos(), i. passed a value in the range -1 to +1, and returns an angle in radians whose cosine is equal to ...
Page 179
Library Functions ASCTIME Synopsis #include <time.h> char * asctime (struct Description The asctime() function takes the time broken down into the struct tm structure, pointed to by its argument, and returns a 26 character string describing the ...
Page 180
Return Value A pointer to the string. Note The example will require the user to provide the time() routine as it cannot be supplied with the compiler. See time() for more details. 166 Library Functions ...
Page 181
Library Functions ASIN Synopsis #include <math.h> double asin (double f) Description The asin() function implements the converse of sin(), i. passed a value in the range -1 to +1, and returns an angle in radians whose sine is ...
Page 182
ASSERT Synopsis #include <assert.h> void assert (int e) Description This macro is used for debugging purposes; the basic method of usage is to place assertions liberally throughout your code at points where correct operation of the code depends upon certain ...
Page 183
Library Functions ATAN Synopsis #include <math.h> double atan (double x) Description This function returns the arc tangent of its argument, i.e. it returns an angle e in the range - Example #include <stdio.h> #include <math.h> void main (void) { printf("%f\n", ...
Page 184
ATOF Synopsis #include <stdlib.h> double atof (const char * s) Description The atof() function scans the character string passed to it, skipping leading blanks. It then converts an ASCII representation of a number to a double. The number may be ...
Page 185
Library Functions ATOI Synopsis #include <stdlib.h> int atoi (const char * s) Description The atoi() function scans the character string passed to it, skipping leading blanks and reading an optional sign. It then converts an ASCII representation of a decimal ...
Page 186
ATOL Synopsis #include <stdlib.h> long atol (const char * s) Description The atol() function scans the character string passed to it, skipping leading blanks. It then converts an ASCII representation of a decimal number to a long integer. Example #include ...
Page 187
Library Functions BSEARCH Synopsis #include <stdlib.h> void * bsearch (const void * key, void * base, size_t n_memb, size_t size, int (*compar)(const void *, const void *)) Description The bsearch() function searches a sorted array for an element matching a ...
Page 188
See Also ...
Page 189
Library Functions CEIL Synopsis #include <math.h> double ceil (double f) Description This routine returns the smallest whole number not less than f. Example #include <stdio.h> #include <math.h> void main (void) { double j; scanf("%lf", &j); printf("The ceiling of %lf is ...
Page 190
CGETS Synopsis #include <conio.h> char * cgets (char * s) Description The cgets() function will read one line of input from the console into the buffer passed as an ar- gument. It does so by repeated calls to getche(). As ...
Page 191
Library Functions Return Value The return value is the character pointer passed as the sole argument. 177 ...
Page 192
CLRWDT Synopsis #include <htc.h> CLRWDT(); Description This macro is used to clear the device’s internal watchdog timer. Example #include <htc.h> void main (void) { WDTCON=1; /* enable the WDT */ CLRWDT(); } 178 Library Functions ...
Page 193
Library Functions COS Synopsis #include <math.h> double cos (double f) Description This function yields the cosine of its argument, which is an angle in radians. The cosine is calculated by expansion of a polynomial series approximation. Example #include <math.h> #include ...
Page 194
COSH, SINH, TANH Synopsis #include <math.h> double cosh (double f) double sinh (double f) double tanh (double f) Description These functions are the implement hyperbolic equivalents of the trigonometric functions; cos(), sin() and tan(). Example #include <stdio.h> #include <math.h> void ...
Page 195
Library Functions CPUTS Synopsis #include <conio.h> void cputs (const char * s) Description The cputs() function writes its argument string to the console, outputting carriage returns before each newline in the string. It calls putch() repeatedly hosted system ...
Page 196
CTIME Synopsis #include <time.h> char * ctime (time_t * t) Description The ctime() function converts the time in seconds pointed to by its argument to a string of the same form as described for asctime(). Thus the example program prints ...
Page 197
Library Functions DI, EI Synopsis #include <htc.h> void ei (void) void di (void) Description The di() and ei() routines disable and re-enable interrupts respectively. These are implemented as macros defined in pic.h. The example shows the use of ei() and ...
Page 198
DIV Synopsis #include <stdlib.h> div_t div (int numer, int demon) Description The div() function computes the quotient and remainder of the numerator divided by the denomina- tor. Example #include <stdlib.h> #include <stdio.h> void main (void) { div_t ...
Page 199
Library Functions EEPROM_READ, EEPROM_WRITE Synopsis #include <htc.h> unsigned char eeprom_read (unsigned char addr); void eeprom_write (unsigned char addr, unsigned char value); Description These function allow access to the on-chip eeprom (when present). The eeprom is not in the directly- accessible ...
Page 200
EVAL_POLY Synopsis #include <math.h> double eval_poly (double x, const double * d, int n) Description The eval_poly() function evaluates a polynomial, whose coefficients are contained in the array for example x*x*d2 + x*d1 + d0. ...