SW500007 Microchip Technology, SW500007 Datasheet
SW500007
Specifications of SW500007
778-1002
778-1002
Related parts for SW500007
SW500007 Summary of contents
Page 1
...
Page 2
... HI-TECH PICC-18 STD Compiler HI-TECH Software. Copyright (C) 2008 HI-TECH Software. All Rights Reserved. Printed in Australia. PICC-18 is licensed exclusively to HI-TECH Software by Microchip Technology Inc. Produced on: February 21, 2008 HI-TECH Software Pty. Ltd. web: http://www.htsoft.com ACN 002 724 549 45 Colebard Street West Acacia Ridge QLD 4110 Australia email: hitech@htsoft ...
Page 3
Contents Table of Contents List of Tables 1 Introduction 1.1 Typographic conventions 2 PICC-18 Command-line Driver 2.1 Long Command Lines 2.2 Default Libraries . . . . . . . . . . . . . . . . . ...
Page 4
CONTENTS 2.4.17 -X: Strip Local Symbols 2.4.18 --ASMLIST: Generate Assembler .LST Files 2.4.19 --CALLGRAPH=type: Control level of information displayed in call graph 2.4.20 --CHAR=type: Make Char Type Signed or Unsigned 2.4.21 --CHECKSUM=start-end@address<,specs>: Calculate, store and ver- ify a checksum 2.4.22 ...
Page 5
CONTENTS 2.4.52 --SUMMARY=type: Select Memory Summary Output Type 2.4.53 --VER: Display The Compiler’s Version Information 2.4.54 --WARN=level: Set Warning Level 2.4.55 --WARNFORMAT=format: Set Warning Message Format 3 C Language Features 3.1 ANSI Standard Issues 3.1.1 Divergence from the ANSI C ...
Page 6
CONTENTS 3.4.6 32-Bit Integer Data Types and Variables 3.4.7 Floating Point Types and Variables 3.4.8 Structures and Unions 3.4.8.1 Bit-fields in Structures 3.4.8.2 Structure and Union Qualifiers 3.4.9 Standard Type Qualifiers 3.4.9.1 Const and Volatile Type Qualifiers 3.4.10 Special Type ...
Page 7
CONTENTS 3.10.2 Context Saving on Interrupts 3.10.3 Context Retrieval 3.10.4 Interrupt Levels 3.10.5 Interrupt Registers 3.11 Mixing C and Assembler Code 3.11.1 External Assembly Language Functions 3.11.2 Accessing C objects from within Assembly Code 3.11.2.1 Accessing special function register names ...
Page 8
CONTENTS 4.3.5 Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 ...
Page 9
CONTENTS 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.7. ...
Page 11
CONTENTS 5.14.1 -Pname[,architecture] 5.14 ...
Page 12
CONTENTS Index xii CONTENTS 451 ...
Page 13
List of Tables 2.1 PICC18 file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 14
LIST OF TABLES 4.2 ASPIC18 statement formats 4.3 ASPIC18 numbers and bases 4.4 ASPIC18 operators . . . . . . . . . . . . . . . . . . . . . . . . . ...
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-18 Command-line Driver PICC18 is the driver invoked from the command line to compile and/or link C programs. PICC18 has the following basic command format: PICC18 [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-18 Command-line Driver 2.4 PICC18 Compiler Options Most aspects of the compilation can be controlled using the command-line driver, PICC18. The driver will configure and execute all required applications, such as the code generator, assembler and linker. PICC18 recognizes the ...
Page 20
... PICC18 Command-line Options Meaning Selects size/kind of double types Select the type of external memory interface used Add or remove specific software workarounds for sil- icon errata issues. Format error message strings to the given style Sets the maximun number of errors displayed Specify a hexadecimal opcode to program in all un- used program memory locations ...
Page 21
PICC-18 Command-line Driver Option --STRICT --SUMMARY=type --VER --WARN=level --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 ...
Page 22
PICC18 Compiler Options located in read-only directories. To compile three source files main.c, module1.c and asmcode.as to object files you could use a command similar to: PICC18 --CHIP=18F242 -C main.c module1.c asmcode.as The compiler will produce three object files main.obj, ...
Page 23
PICC-18 Command-line Driver The -E option also allows errors to be appended to an existing file by specifying an addition charac- ter the start of the error filename, for example: PICC18 --CHIP=18F242 -E+x.err y.c If you wish to ...
Page 24
PICC18 Compiler Options will include source-level debugging information for test.c only because module1.c was not com- piled with the -G option. The --IDE option will typically enable the -G option. 2.4.6 -Ipath: Include Search Path Use -I to specify an ...
Page 25
PICC-18 Command-line Driver The -L option is especially useful when linking code which contains extra program sections (or psects), as may be the case if the program contains C code which makes use of the #pragma psect directive or assembler ...
Page 26
... PICC18 Compiler Options files are not preprocessed. 2.4.13 -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.14 -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 27
PICC-18 Command-line Driver 2.4.18 --ASMLIST: Generate Assembler .LST Files The --ASMLIST option tells PICC18 to generate an assembler listing file for each module being compiled. The list file shows both the original C code, and the generated assembler code and ...
Page 28
PICC18 Compiler Options Table 2.3: Additional --checksum specifications Specification Select a checksum algorithm algorithm Add a value to result offset Byte width of result width will not be performed if the --FILL option is also used to allow a different ...
Page 29
PICC-18 Command-line Driver Suboption 24 32 fast32 pointers refer to Section 3.4.12. Note that it is critical that the compilation stages for all source files in a project and the link stage apply consistent code pointer sizes. 2.4.26 --CR=file: Generate ...
Page 30
... Specify to add or remove specific errata workarounds This option allows specification of the types of software workarounds to apply in order to overcome documented silicon errata issues. The chip configuration file nominates a default set of errata issues that apply to each device ...
Page 31
PICC-18 Command-line Driver When reading EEPROM, the contents EEPROMRD of the EEDATA register may become cor- rupted in the second instruction cycle after setting the RD bit (EECON1<0>). The result returned from an EEPROM EEPROMADR read operation can be corrupted ...
Page 32
PICC18 Compiler Options 2.4.31 --ERRFORMAT=format: Define Format for Compiler Messages If the --ERRFORMAT option is not used, the default behaviour of the compiler is to display any errors in a “human readable” format line with a caret “^” and error ...
Page 33
PICC-18 Command-line Driver set HTC_WARN_FORMAT=WARNING: file %f; line %l; column %c; %s set HTC_ERR_FORMAT=ERROR: %a: file %f; line %l; column % Using the previous source code, the output from the compiler when using the above environment variables would ...
Page 34
... English. English is the default language and some messages are only ever printed in English regardless of the language specified with this option. Table 2.8 shows those langauges currently supported. 20 PICC-18 Command-line Driver Table 2.7: Supported IDEs IDE HI-TECH Software’s HI-TIDE Microchip’s MPLAB ...
Page 35
PICC-18 Command-line Driver en, english fr, french,francais de, german, deutsch 2.4.38 --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 ...
Page 36
PICC18 Compiler Options Option name 1..9 asm debug all none Option name lib intel tek aahex mot ubrof bin mcof cof cod elf 22 Table 2.9: Optimization Options File format Select code generation level 1 through 9 Select assembler optimizations ...
Page 37
PICC-18 Command-line Driver 2.4.43 --PRE: Produce Preprocessed Source Code The --PRE option is used to generate preprocessed C source files with an extension .pre. This may be useful to ensure that preprocessor macros have expanded to what you think they ...
Page 38
PICC18 Compiler Options /* Prototypes from test extern functions - include these in a header file */ #if PROTOTYPES extern int add(int *, int *); extern void printlist(int *, int); #else /* PROTOTYPES */ extern int add(); extern ...
Page 39
PICC-18 Command-line Driver 2.4.46 --ROM=lo-hi,<lo-hi,...>|tag: Specify Additional ROM Ranges 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 specifies ...
Page 40
PICC18 Compiler Options Table 2.11: Runtime environment suboptions Suboption The code present in the startup mod- init ule that copies the idata, ibigdata and ifardata psects’ ROM-image to RAM. Built-in verification of --checksum speci- checksum fications. The inclusion of library ...
Page 41
PICC-18 Command-line Driver 2.4.49 --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 42
PICC18 Compiler Options Table 2.12: Memory Summary Suboptions Suboption Summary of psect usage. psect General summary of memory used. mem Summary of address used within the hex hex file. Whether summary information is shown file on the screen or shown ...
Page 43
Chapter 3 C Language Features HI-TECH PICC-18 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.1 Processor Support HI-TECH PICC-18 STD supports the full range of Microchip PIC 18 processors. Additional code- compatible processors may be added by editing the picc-18.ini file in the DAT directory. User- defined processors should be placed at ...
Page 45
C Language Features 3.2.3 ID Locations Some PIC18 devices have location outside the addressable memory area that can be used for storing program information, such number. The __IDLOC macro may be used to place data into these ...
Page 46
Processor-related Features EEPROM_WRITE(address,value); To read a byte of data from an address in EEPROM memory, and store variable: variable=EEPROM_READ(address); For convenience, __EEPROMSIZE predefines the number of bytes of EEPROM available on chip. 3.2.4.2 Flash Access To copy ...
Page 47
C Language Features Peripheral Description tag USBRAM USB dual-port RAM BOOTROM Boot sector in flash memory BOOT256, Boot sector in flash BOOT512, memory BOOT1K, BOOT2K, BOOT4K 3.2.6 Bit Instructions Wherever possible, HI-TECH PICC-18 STD will attempt to use the PIC18 ...
Page 48
Files the TMRxL register often must be read before trying to read the TMRxH register to obtain a valid 16-bit result. Although it is possible to define an absolute non-char C variable to map over such registers, the order in ...
Page 49
C Language Features Figure 3.1: Library naming convention 3.3.3 Output File Formats The compiler is able to directly produce a number of the output file formats which are used by common PROM programmers and in-circuit emulators. The default behaviour of ...
Page 50
Files Library type c (standard) l (+long) f (+float) w (full featured) Memory Model is either l for large or s for small model. Double Type is - for 24-bit doubles, and d for 32-bit doubles. Library Type is c ...
Page 51
C Language Features Figure 3.2: Peripheral Library Nomenclature Table 3.3: Peripheral Library Configuration Bitmask Bit index 0 Device implementing EEDATA errata workaround for EEPROM reads 1 Device has more than 256 bytes of EEPROM on board 2 Device implementing 4000h ...
Page 52
Files Table 3.4: Program Memory Errata Bitmask Bit index 0 Library implements additional NOPs when reading beyond program space at -40C 1 Library implements 4000h boundary errata workaround 2 Library uses 24-bit pointers to code space The value y is ...
Page 53
C Language Features 3.3.5.1 Initialization of Data psects One job of the runtime startup code is ensure that any initialized variables contain their initial value before the program begins execution. Initialized variables are those which are not auto objects and ...
Page 54
Files The abbreviation "bss" stands for Block Started by Symbol and was an assembler pseudo- op used in IBM systems back in the days when computers were coal-fired. The contin- ued usage of this term is still appropriate. The name ...
Page 55
C Language Features Type bit char unsigned char short unsigned short int unsigned int long unsigned long float double 3.3.5.4 The powerup Routine Some hardware configurations require special initialization, often within the first few cycles of ex- ecution after reset. ...
Page 56
Supported Data Types and Variables Radix binary octal decimal hexadecimal 3.4.1 Radix Specifiers and Constants The format of integral constants specifies their radix. HI-TECH PICC-18 STD supports the ANSI standard radix specifiers as well as ones which enable binary constants ...
Page 57
C Language Features HI-TECH C will use the same storage location and label for strings that have identical character sequences, except where the strings are used to initialise an array residing in the data space as shown in the last ...
Page 58
Supported Data Types and Variables it will be cleared by the assignment since the least significant bit of data is zero. If you want to set a bit variable depending on whether the larger integral ...
Page 59
C Language Features types are simply the smallest four possible integer sizes, and behave in all respects like integers. The reason for the name “char” is historical and does not mean that char can only be used ...
Page 60
Supported Data Types and Variables Format IEEE 754 32-bit modified IEEE 754 24-bit Table 3.8: Floating-point format example IEEE 754 Format Number biased expo- nent 32-bit 7DA6B69Bh 11111011b 24-bit 42123Ah 10000100b 3.4.7 Floating Point Types and Variables Floating point is ...
Page 61
C Language Features where 23 is the number of bits taken up by the mantissa, to give 0.302447676659. Add one to this fraction. The floating-point number is then given by: 0 124 302447676659 Variables may be declared ...
Page 62
Supported Data Types and Variables unsigned unsigned unsigned } foo bit-field is declared in a structure that is assigned an absolute address, no storage will be allocated for the structure. Absolute structures would be used when mapping a ...
Page 63
C Language Features 3.4.9 Standard Type Qualifiers Type qualifiers provide information regarding how an object may be used, in addition to its type which defines it storage size and format. HI-TECH PICC-18 STD supports both ANSI qualifiers and additional special ...
Page 64
Supported Data Types and Variables void test(void) { persistent int intvar; /* WRONG! */ ... other code ... } because intvar is of class auto. To declare intvar as a persistent variable local to function test(), write: static persistent int ...
Page 65
C Language Features 3.4.10.3 Far Type Qualifier The far type qualifier is used to place variables of permanent duration into external program space of the PIC18 for those devices which can support additional memory. Accesses to far variables are less ...
Page 66
Supported Data Types and Variables 3.4.12.1 RAM Pointers All RAM pointer objects on these PIC18 devices are 16 bits wide, with the exception of pointers to objects qualified as near which are 8 bits wide. A pointer to RAM, for ...
Page 67
C Language Features then ignored. If Bit number 21 is clear, then the address is assumed object in the program space and the access is performed using table read or table write instructions. Again, no writes ...
Page 68
Storage Class and Object Placement The first example is a pointer called nip. It contains the address of an int object that is qualified near. Since a near object is in the access bank the pointer is only 8 bits ...
Page 69
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 70
Storage Class and Object Placement 3.5.2 Absolute Variables A global or static variable can be located at an absolute address by following its declaration with the construct @ address, for example: volatile unsigned char Portvar @ 0xF80; will declare a ...
Page 71
C Language Features 3.6 Functions 3.6.1 Function Argument Passing The method used to pass function arguments depends on the size of the argument or arguments. If there is only one argument, and it is one byte in size ...
Page 72
Functions 3.6.2 Function Return Values Function return values are passed to the calling function as follows: 3.6.2.1 8-Bit Return Values Eight-bit values are returned from a function in the W register. For example, the function: char return_8(void){ return 0; } ...
Page 73
C Language Features struct fred { int ace[4]; }; struct fred return_struct(void){ struct fred wow; return wow; } will exit with the following code: movlw low(?a_return_struct) movwf fsr0l movlw high(?a_return_struct) movwf fsr0h movlw structret movwf fsr1l clrf fsr1h movlw 8 ...
Page 74
Register Usage single byte objects are also placed in one of the “big” psects (“big” refers to the size of the psect, not the size of the objects within the psect). All auto and parameter variables from all functions are ...
Page 75
C Language Features The unsigned char result 206 (which is not less than 10), but both a and b are con- verted to signed int via integral promotion before the subtraction takes place. The result ...
Page 76
Psects Operand 3.8.2 Shifts applied to integral types The ANSI standard states that the result of right shifting (> > operator) signed integral types is implementation defined when the operand is negative. Typically, the possible ...
Page 77
C Language Features you should read this section carefully. A psect can be created in assembler code by using the PSECT assembler directive (see Section 4.3.8.3 user-defined psects can be created by using the #pragma psect preprocessor di- ...
Page 78
Psects init Used by initialisation code which, for example, clears RAM. end_init Used by initialization code which, for example, clears RAM. clrtext Used by some startup routines for copying the data psects. The compiler-generated psects which are placed in RAM ...
Page 79
C Language Features rbit This psect is used to store all bit variables. All bit objects are near by default and are placed in the access bank. struct Contains any structure larger than 4 bytes in size which is returned ...
Page 80
... Context Saving on Interrupts The PIC18 processor only saves the program counter on its stack whenever an interrupt occurs. Other registers and objects must be saved in software. PICC-18 automatically 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 81
C Language Features will save further context necessary and then jump to code directly related to the interrupt function. The interrupt function code is also placed in a text psect. All objects saved are done so to ...
Page 82
Interrupt Handling in C #pragma interrupt_level 1 void bill(){ int 23 two interrupt functions calling same non-interrupt function */ #pragma interrupt_level 1 void interrupt fred(void){ bill(); } #pragma interrupt_level 1 void interrupt joe(void){ bill(); } ...
Page 83
C Language Features PORTB; // Read PORTB to clear any mismatch RBIF = 0; // clear event flag // process interrupt here } } 3.11 Mixing C and Assembler Code Assembly language code can be mixed with C code using ...
Page 84
Mixing C and Assembler Code T UT RIAL An assembly routine is required which can add two 16-bit values together. The routine must be callable from C code. Both the values are passed in as arguments when the routine is ...
Page 85
C Language Features T UT RIAL To continue the previous example, here is a code snippet that declares the operation of the assembler routine, then calls the routine. extern unsigned int add(unsigned a, unsigned b); void main(void) { int a, ...
Page 86
Mixing C and Assembler Code C identifiers are assigned different symbols in the output assembly code so that an as- sembly identifier cannot conflict with an identifier defined in C code. If assembly pro- grammers choose identifier names that do ...
Page 87
C Language Features The asm() statement is used to embed a single assembler instruction. This form looks and be- haves like a C statement, however each instruction must be encapsulated within an asm() statement. You should not use a #asm ...
Page 88
Preprocessing 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 assembly #endasm ...
Page 89
C Language Features 3.12.2 Predefined Macros The compiler drivers define certain symbols to the preprocessor (CPP), allowing conditional compi- lation based on chip type etc. The symbols listed in the table below show the more common symbols defined by the ...
Page 90
Preprocessing Symbol Always _FLASH_ERASE_SIZE Always _FLASH_WRITE_SIZE __MPLAB_ICD2__ --DEBUGGER=ICD2 MPLAB_ICD --DEBUGGER=ICD2 _ICDROM_START --DEBUGGER=ICD2 _ICDROM_END --DEBUGGER=ICD2 Always _ERRATA_TYPES When chip selected _chipname Always __FILE__ Always __LINE__ Always __DATE__ Always __TIME__ 3.12.3 Pragma Directives There are certain compile-time directives that can be used ...
Page 91
C Language Features Directive Allow interrupt function to be interrupt_level called from main-line code. See Section 3.10.4. Enable JIS character handling in jis strings Disable JIS character handling (de- nojis fault) Enable printf-style format string printf_check checking Rename compiler-defined psect ...
Page 92
Preprocessing Note that the warning level must be set below for this option to have any visible effect. See Section 2.4.54. 3.12.3.3 The #pragma psect Directive Normally the object code generated by the compiler is broken into ...
Page 93
C Language Features Now, how do we know in which psect the code associated with the function will be placed? Compile you program, inlcuding this new module and generate an assembly list file, see Section 2.4.18. Look for the definition ...
Page 94
Preprocessing Register Name wreg status pclat prodl, prodh btemp, btemp+1...btemp+11 xbtemp fsr0, fsr1, fsr2 switch type auto direct The #pragma regsused directive allows the programmer to indicate register usage for functions that will not be “seen” by the code generator, ...
Page 95
C Language Features Specifying the direct option to the #pragma switch directive forces the compiler to generate the table look-up style switch method. This is mostly useful where timing is an issue for switch statements (i.e.: state machines). This pragma ...
Page 96
Linking Programs For example, if you wished to make changes to the library function max() which resides in the file max.c in the SOURCES directory, you could make a copy of this source file, make the appropriate changes and then ...
Page 97
C Language Features Table 3.15: Supported standard I/O functions Function name printf(const char * s, ...) sprintf(char * buf, const char * s, ...) and compile it to assembler code using PICC18 -S x.c The resultant assembler code includes the ...
Page 98
Debugging Information You will find samples of serial code which implements the putch() and getch() functions in the file serial.c in the SAMPLES directory. 3.15 Debugging Information 3.15.1 MPLAB-specific information Certain options and compiler features are specifically intended to help ...
Page 99
Chapter 4 Macro Assembler The Macro Assembler included with HI-TECH PICC-18 STD assembles source files for PIC18 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 100
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.50. The usage of the assembler is similar under all of available operating systems. All command-line options are ...
Page 101
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 assembly produced using the -O assembler option. Thus if both -A and -O are used ...
Page 102
HI-TECH C Assembly Language -Llistfile This option requests the generation of an assembly listing file. If listfile is specified then the listing will be written to that file, otherwise it will be written to the standard output. An assembly listing ...
Page 103
Macro Assembler Table 4.2: ASPIC18 statement formats Format 1 label: Format 2 label: Format 3 name Format 4 ; comment only Format 5 <empty line> assembler directives are documented in this section. 4.3.1 Statement Formats Legal statement formats are shown ...
Page 104
HI-TECH C Assembly Language Table 4.3: ASPIC18 numbers and bases Radix Binary digits 0 and 1 followed by B Octal digits followed Decimal digits followed ...
Page 105
Macro Assembler 4.3.4.2 Character Constants and Strings A character constant is a single character enclosed in single quotes ’. Multi-character constants, or strings, are a sequence of characters, not including carriage return or newline characters, enclosed within matching quotes. Either ...
Page 106
HI-TECH C Assembly Language 4.3.5.3 Location Counter The current location within the active program section is accessible via the symbol $. This symbol expands to the address of the currently executing instruction. Thus: goto $ will represent code that will ...
Page 107
Macro Assembler Here, the label frank will ultimately be assigned the address of the mov instruction, and simon44 the address of the clrf instruction. Regardless of how they are defined, the assembler list file produced by the assembler will always ...
Page 108
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 109
Macro Assembler The following is an example showing some executable instructions being placed in the text psect, and some data being placed in the rbss psect. PSECT text,class=CODE adjust: goto clear_fred increment: incf _fred PSECT bss,class=BANK0,space=1 fred PSECT ...
Page 110
HI-TECH C Assembly Language Table 4.5: ASPIC18 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 111
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.2 END END is optional, but if present should be at the very end of the program. It will terminate the assembly and not ...
Page 112
HI-TECH C Assembly Language The class flag specifies a class name for this psect. Class names are used to allow local psects to be referred class name at link time, since they cannot be referred to by ...
Page 113
Macro Assembler Some examples of the use of the PSECT directive follow: PSECT fred PSECT bill,size=100h,global PSECT joh,abs,ovrld,class=CODE,delta=2 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 ...
Page 114
HI-TECH C Assembly Language 4.3.8.6 SET This pseudo-op is equivalent to EQU except that allows a symbol to be re-defined. For example thomas SET 0h 4.3.8 used to initialize storage as bytes. The argument is a list ...
Page 115
Macro Assembler 4.3.8.11 FNARG The directive FNARG fun1,fun2 tells the linker that evaluation of the arguments to function fun1 involves a call to fun2, thus the memory argument memory allocated for the two functions should not overlap. For example, the ...
Page 116
HI-TECH C Assembly Language 4.3.8.14 FNCONF The FNCONF directive is used to supply the linker with configuration information for a call graph. FNCONF is written as follows: FNCONF psect,auto,args where psect is the psect containing the call graph, auto is ...
Page 117
Macro Assembler 4.3.8.17 FNROOT This directive tells the assembler that a function is a root function and thus forms the root of a call graph. It could either be the C main() function or an interrupt function. For example, the ...
Page 118
HI-TECH C Assembly Language ;descr: Loads two registers with the value in the variable: ldtwo MACRO arg1,arg2 movlw &arg2 movwf &arg1 ENDM When used, this macro will expand to the 2 instructions in the body of the macro, with the ...
Page 119
Macro Assembler 4.3.8.20 LOCAL The LOCAL directive allows unique labels to be defined for each expansion of a given macro. Any symbols listed after the LOCAL directive will have a unique assembler generated symbol substituted for them when the macro ...
Page 120
HI-TECH C Assembly Language REPT 3 addwf fred,w ENDM will expand to addwf fred,w addwf fred,w addwf fred,w 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 ...
Page 121
Macro Assembler will expand to: PSECT romdata,class=CODE,delta=2 DB ’A’ DB ’B’ DB ’C’ PSECT text 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 ...
Page 122
HI-TECH C Assembly Language Table 4.7: DSPIC 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 123
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 Alternatively, the LIST control may includes options to control the assembly and the listing. The options are listed in Table 4.8. See also ...
Page 124
HI-TECH C Assembly Language 4.3.9.10 SPACE The SPACE control will place a number of blank lines in the listing output as specified by its param- eter. 4.3.9.11 SUBTITLE SUBTITLE defines a subtitle to appear at the top of every listing ...
Page 125
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 126
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 127
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 128
Operation Table 5.1: Linker command-line options Option -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 -Z 5.7.1 Numbers in linker ...
Page 129
Linker and Utilities 5.7.2 -Aclass=low-high,... Normally psects are linked according to the information given option (see below) but some- times it is desired to have a class of psects linked into more than one non-contiguous address range. ...
Page 130
Operation 5.7.4 -Cpsect=class This option will allow a psect to be associated with a specific class. Normally this is not required on the command line since classes are specified in object files. 5.7.5 -Dclass=delta This option allows the delta value ...
Page 131
Linker and Utilities 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 ...
Page 132
Operation 5.7.13 -K 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 ...
Page 133
Linker and Utilities 5.7.20 -Pspec Psects are linked together and assigned addresses based on information supplied to the linker via -P options. The argument to the -P option consists basically of comma-separated sequences thus: -Ppsect=lnkaddr+min/ldaddr+min,psect=lnkaddr/ldaddr, ... There are several variations, ...
Page 134
Operation -Ptext=0,data=8000h/,bss/. -Pnvram=bss,heap 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 135
Linker and Utilities Note that to set an upper limit to a psect, this must be set in assembler code (with a limit= fl PSECT directive). If the bound (boundary) argument is used, the class of psects will ...
Page 136
Invoking the Linker 5.8 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 137
Linker and Utilities the linker performs additional operations to minimise the memory consumed by the program by overlaying each function’s APB where possible. In assembly code variables within a function’s APB are referenced via special symbols, which marks the start ...
Page 138
Compiled Stack Operation one parameter as the ANSI standard does not dictate the order in which function parameters must be evaluated. Such a condition is best illustrated by an example, which is shown in the following tutorial RIAL ...
Page 139
Linker and Utilities 5.10 Map Files The map file contains information relating to the relocation of psects and the addresses assigned to symbols within those psects. 5.10.1 Generation If compilation is being performed via HI-TIDE having to adjust the compiler ...
Page 140
... 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 141
Linker and Utilities First the program is compiled without using this option and the following linker class definition is noted in the linker command line: -ACODE=0-03FFFhx2 The class name may vary between compilers and the selected target device, however there ...
Page 142
Map Files The estimated call tree depth. These features are discussed below. The call graph produced by PRO versions compilers is very similar to that produced by Standard version compilers, however there are differences. A typical PRO compiler call graph ...
Page 143
Linker and Utilities The functions that the root function calls, or may call, are indented one level and listed below the root node. If any of these functions call (or might call) other functions, these called functions are indented and ...
Page 144
Map Files need to be saved into the function’s temporary variable if that register is required for code generation purposes, in which case they do not contribute to the function’s parameter size, but increase the size of the auto area. ...
Page 145
Linker and Utilities After each tree in call tree, there is an indication of the maximum call depth that might be realised by that tree. This may be used as a guide to the stack usage of the program. No ...
Page 146
Map Files The function byteconv may call several functions: float, ldiv, crv and srv. (Any function name that does not start with an underscore must be an assembly routine. The routine float and ldiv in this case relating to floating ...
Page 147
Linker and Utilities 5.10.2.3 Psect Information listed by Module The next section in the map file lists those modules that made a contribution to the output, and information regarding the psects these modules defined. This section is heralded by the ...
Page 148
... 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 149
Linker and Utilities For cases where a user-defined routine, with the same name as a library routine, is present in the programs source file list, to confirm that the user-defined routine was linked in preference to the library routine. 5.10.2.4 ...
Page 150
Map Files and is followed by a list of classes and the memory still available in each class defined in the program. If there is more than one range in a class, each range is printed on a separate line. ...
Page 151
Linker and Utilities psect name may be symbols that have never been used throughout the program, or relate to symbols that are not directly associated with a psect. Note that a symbol table is also shown in each assembler list ...
Page 152
Librarian Table 5.2: Librarian command-line options Option -Pwidth -W Table 5.3: Librarian key letter commands LIBR options k file.lib file.obj ... Interpreting this, LIBR is the name of the program, options is zero or more librarian options which affect the ...
Page 153
Linker and Utilities This command deletes the object modules a.obj, b.obj and c.obj from the library file.lib: LIBR d file.lib a.obj b.obj c.obj 5.11.4 Supplying Arguments Since it is often necessary to supply many object file arguments to LIBR, and ...
Page 154
Objtohex 5.11.6 Ordering of Libraries The librarian creates libraries with the modules in the order in which they were given on the com- mand line. When updating a library the order of the modules is preserved. Any new modules added ...
Page 155
Linker and Utilities 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 ...
Page 156
Cref 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 first, where1 should be less than where2, and vice versa. ...
Page 157
Linker and Utilities Table 5.5: CREF command-line options Option -Fprefix -Hheading -Llen -Ooutfile -Pwidth -Sstoplist -Xprefix 5.13.3 -Llen Specify the length of the paper on which the listing produced, e.g. if the listing printed ...
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.7: CROMWELL command-line options Option -Pname[,architecture -Okey -Ikey - argument to this option which also specifies the processor architecture is required. Hence for this format the usage of ...
Page 160
Cromwell Table 5.8: -P option architecture arguments for COFF file output. Architecture 68K H8/300 H8/300H SH PIC12 PIC14 PIC16 PIC18 PIC24 PIC30 5.14.5 -F When generating a COD file, this option can be used to force all local symbols to ...
Page 161
Linker and Utilities 5.14. formats that support different endian types, use this option to specify big-endian byte ordering. 5.14.11 -M When generating COD files this option will remove the preceding underscore character from sym- bols. 5.14.12 -V Turns ...
Page 162
Hexmate Filling unused memory locations with an instruction to send the known location if it gets lost. Storage of a serial number at a fixed address. Storage of a string (e.g. time stamp fixed address. ...
Page 163
Linker and Utilities 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 ...
Page 164
Hexmate r100-1FFs2000,myfile.hex will shift the block of data from 100h-1FFh to the new address range 2100h-21FFh. Be careful when shifting sections of executable code. Program code shouldn’t be shifted unless it can be guaranteed that no part of the program ...
Page 165
Linker and Utilities 5.15.1.5 -CK The -CK option is for calculating a checksum. The usage of this option is: -CK=start-end@destination[+offset][wWidth][tCode][gAlogithm] where: Start and End specify the address range that the checksum will be calculated over. Destination is the address where ...
Page 166
Hexmate Table 5.10: Hexmate Checksum Algorithm Selection Selector - Start and End specify the address range that this fill will apply to. For example: -FILL=3412@0-1FFF,data will program opcode 1234h in all unused addresses ...
Page 167
Linker and Utilities Start and End limit the address range to search through. Align is optional. It specifies that a code sequence can only match if it begins on an address which is a multiple of this value ...
Page 168
Hexmate Code is a little endian hexadecimal code to replace the sequences that match the -FIND crite- ria. Mask is an optional bit mask to specify which bits within Code will replace the code sequence that has been matched. This ...
Page 169
Linker and Utilities 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 5.15.1.11 -HELP ...
Page 170
Hexmate Increment is optional and allows the value of Code to change by this value with each repetition (if requested). Address is the location to store this code, or the first repetition thereof. Interval is optional and specifies the address ...
Page 171
Linker and Utilities will store the ASCII data for the string, My favourite string (including null terminator) at ad- dress 1000h. Another example: -STRING@1000t34="My favourite string" will store the same string with every byte in the string being trailed with ...
Page 172
Hexmate 158 Linker and Utilities ...
Page 173
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 analysed into the following headings. Synopsis This is the C ...
Page 174
Synopsis void __checksum_failed(void) Description This routine will be called during the execution of compiler-generated startup code if it has been requested that a built-in checksum and verification routine be included, and the result of the veri- fication does not ...
Page 175
Library Functions __CONFIG Synopsis #include <htc.h> __CONFIG(n, data) Description This macro is used to program the configuration fuses that set the device into various modes of operation. The macro accepts the number corresponding to the configuration register ...
Page 176
Synopsis void __delay_ms(int) Description This routine when called will invoke a fixed delay of 400 instruction cycles multiplied by the value passed to the function as a parameter. Also consider an additional instruction cycle overhead in ...
Page 177
Library Functions Table A.1: Maximum delay versus system frequency System frequency 40 MHz 20 MHz 10 MHz __delay_ms Synopsis __delay_ms(x) Description This routine is defined as a preprocessor macro. The macro interfaces with library routine __de- lay_400_cycles(). The parameter in ...
Page 178
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 it is ...
Page 179
Library Functions __IDLOC 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 ...
Page 180
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 181
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 182
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 183
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 184
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. 170 Library Functions ...
Page 185
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 186
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 187
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 188
ATAN2 Synopsis #include <math.h> double atan2 (double x, double x) Description This function returns the arc tangent of y/x. Example #include <stdio.h> #include <math.h> void main (void) { printf("%f\n", atan2(10.0, -10.0)); } See Also sin(), cos(), tan(), asin(), acos(), atan() ...
Page 189
Library Functions 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 ...
Page 190
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 number to ...
Page 191
Library Functions 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. ...
Page 192
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 particular key. ...
Page 193
Library Functions while(gets(inbuf)) { sscanf(inbuf,"%s %d", values[i].name, &values[i].value); i++; } qsort(values, i, sizeof values[0], val_cmp bsearch("fred", values, i, sizeof values[0], val_cmp); if(!vp) printf("Item ’fred’ was not found\n"); else printf("Item ’fred’ has value %d\n", vp->value); } ...
Page 194
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 %lf\n", j, ...
Page 195
Library Functions 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 ...
Page 196
Return Value The return value is the character pointer passed as the sole argument. 182 Library Functions ...
Page 197
Library Functions 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(); } 183 ...
Page 198
Synopsis #include <htc.h> unsigned int config_read(void); void config_write(unsigned char, unsigned int); Description These functions allow access to the device configuration registers which determine many of the behavioural aspects of the device itself. config_read() accepts a single parameter to ...
Page 199
Library Functions Return Value config_read() returns the 16-Bit value contained in the nominated configuration register. Note The functions config_read() config_write() are only applicable to such devices that support this feature. 185 ...
Page 200
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 <stdio.h> #define ...