SW500010 Microchip Technology, SW500010 Datasheet
SW500010
Specifications of SW500010
778-1006
778-1006
Related parts for SW500010
SW500010 Summary of contents
Page 1
Manual ...
Page 2
... HI-TECH C Tools for the PIC10/12/16 MCU Family HI-TECH Software. Copyright (C) 2008 HI-TECH Software. All Rights Reserved. Printed in Australia. Produced on: July 29, 2008 HI-TECH Software Pty. Ltd. ACN 002 724 549 45 Colebard Street West Acacia Ridge QLD 4110 Australia email: hitech@htsoft.com web: http://microchip.htsoft.com ...
Page 3
Contents Table of Contents List of Tables 1 Introduction 1.1 Typographic conventions 2 PICC Command-line Driver 2.1 Invoking the Compiler 2.1.1 Long Command Lines 2.2 The Compilation Sequence 2.2.1 Single-step Compilation 2.2.2 Generating Intermediate Files 2.2.3 Special Processing 2.2.3.1 Printf ...
Page 4
CONTENTS 2.5 Compiler Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 ...
Page 5
CONTENTS 2.6.29 --ERRORS=number: Maximum Number of Errors 2.6.30 --FILL=opcode: Fill Unused Program Memory 2.6.31 --FLOAT=type: Select kind of Float Types 2.6.32 --GETOPTION=app,file: Get Command-line Options 2.6.33 --HELP<=option>: Display Help 2.6.34 --IDE=type: Specify the IDE being used 2.6.35 --LANG=language: Specify the ...
Page 6
CONTENTS 3.2.2 Configuration Fuses 3.2.3 ID Locations 3.2.4 Bit Instructions 3.2.5 EEPROM Access 3.2.5.1 The eeprom variable qualifier 3.2.5.2 The __EEPROM_DATA() macro 3.2.5.3 EEPROM Access Functions 3.2.5.4 EEPROM Access Macros 3.2.6 Flash Runtime Access 3.2.6.1 Flash Access Macros 3.2.6.2 Flash ...
Page 7
CONTENTS 3.4 Storage Class and Object Placement 3.4.1 Local Variables 3.4.1.1 Auto Variables 3.4.1.2 Static Variables 3.4.2 Absolute Variables 3.4.3 Objects in Program Space 3.5 Functions . . . . . . . . . . . . . . ...
Page 8
CONTENTS 3.11.3 Pragma Directives 3.11.3.1 The #pragma inline Directive 3.11.3.2 The #pragma jis and nojis Directives 3.11.3.3 The #pragma pack Directive 3.11.3.4 The #pragma printf_check Directive 3.11.3.5 The #pragma regsused Directive 3.11.3.6 The #pragma switch Directive 3.11.3.7 The #pragma warning ...
Page 9
CONTENTS 4.3.8.4 ORG 4.3.8.5 EQU 4.3.8.6 SET 4.3.8.7 DB 4.3.8.8 DW 4.3.8.9 DS 4.3.8.10 DABS 4.3.8.11 FNADDR 4.3.8.12 FNARG 4.3.8.13 FNBREAK 4.3.8.14 FNCALL 4.3.8.15 FNCONF 4.3.8.16 FNINDIR 4.3.8.17 FNSIZE 4.3.8.18 FNROOT 4.3.8.19 IF, ELSIF, ELSE and ENDIF 4.3.8.20 MACRO and ...
Page 10
CONTENTS 5 Linker and Utilities 5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 11
CONTENTS 5.10 Map Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 12
CONTENTS 5.14. ...
Page 13
CONTENTS BSEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 14
CONTENTS MEMSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 15
CONTENTS STRTOK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 16
CONTENTS 16 CONTENTS ...
Page 17
List of Tables 2.1 PICC input file types 2.2 Support languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 18
LIST OF TABLES 4.1 ASPIC command-line options 4.2 ASPICstatement formats 4.3 ASPIC numbers and bases 4.4 ASPIC operators . . . . . . . . . . . . . . . . . . . . . . ...
Page 19
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 20
Typographic conventions 20 Introduction ...
Page 21
Chapter 2 PICC Command-line Driver PICC is the driver invoked from the command line to perform all aspects of compilation, including C code generation, assembly and link steps the recommended way to use the compiler as it hides ...
Page 22
Invoking the Compiler File Type .c .p1 .lpp .as .obj .lib .hex 2.1 Invoking the Compiler This chapter looks at how to use PICC as well as the tasks that it and the internal applications perform during compilation. PICC has ...
Page 23
PICC Command-line Driver directives. These modules are then passed to the remainder of the compiler applications. Thus, a module may consist of several source and header files. A module is also often referred translation unit. These terms ...
Page 24
The Compilation Sequence Figure 2.1: Flow diagram of the initial compilation sequence .lst 2.2 The Compilation Sequence PICC will check each file argument and perform appropriate actions on each file. The entire compi- lation sequence can be thought of as ...
Page 25
PICC Command-line Driver Figure 2.2: Flow diagram of the final compilation sequence .map debug The link and post-link steps are graphically illustrated in Figure 2.2. This diagram shows .hex files as additional input file type not considered in the initial ...
Page 26
The Compilation Sequence randomly generated filename RIAL S INGLE STEP COMPILATION a_sb.lib and c_sb.lpp are to be compiled. To perform this in a single step, the following command line can be used as a starting point for the ...
Page 27
PICC Command-line Driver Compile all modified assembler source files to relocatable object files using the -C driver option Compile all p-code and relocatable object files into a single output object file The final step not only involves the link stage, ...
Page 28
Runtime Files 2.2.3.1 Printf check An extra execution of the code generator is performed for prior to the actual code generation phase. This pass is part of the process by which the printf library function is customized, see Section for ...
Page 29
PICC Command-line Driver By default, libraries appropriate for the selected driver options are automatically passed to the code generator and linker. Although individual library functions or routines will be linked in once referenced in C code, the compiler still requires ...
Page 30
Runtime Files 2.3.1.1 Standard Libraries The C standard libraries contain a standardised collection of functions, such as string, math and input/output routines. The range of these functions are described in Appendix A. These libraries also contain C routines that are ...
Page 31
PICC Command-line Driver --RUNTIME=default,-keep If the startup module is kept, it will be called startup.as and will be located in the current working directory. If you are using an IDE to perform the compilation the destination directory is dictated by ...
Page 32
Runtime Files Since auto objects are dynamically created, they require code to be positioned in the function in which they are defined to perform their initialization also possible that their initial value changes on each instance of the ...
Page 33
PICC Command-line Driver modification of the linker options, and the command-line driver will automatically check the size of these psects to determine if block-clear code is required. Variables placed into psects other than the compiler-defined bss psects will not be ...
Page 34
Runtime Files This template file is found in the LIB directory of the compiler distribution and is called doprnt.c. It contains a minimal implementation of the printf function, but with the more advanced features included as conditional code which can ...
Page 35
PICC Command-line Driver void my_print(const char * mes) { printf(mes); } the compiler cannot determine the exact format string, but can see that there are no additional arguments to printf following the format string represented by mes. Thus, the only ...
Page 36
Debugging Information C PRO for the PIC10/12/16 MCU Family. The File Type column lists the filename extension which will be used for the output file. In addition to the options shown, the -O option may be used to request generation ...
Page 37
PICC Command-line Driver 2.5 Compiler Messages All compiler applications, including the command-line driver, PICC, use textual messages to report feedback during the compilation process. A centralized messaging system is used to produce the messages which allows a consistancy during all ...
Page 38
Compiler Messages 2.5.2 Message Language HI-TECH C PRO for the PIC10/12/16 MCU Family Supports more than one language for displayed messages. There is one MDF for each language supported. The language used for messaging may be specified with each compile ...
Page 39
PICC Command-line Driver Table 2.3: Messaging environment variables Variable HTC_MSG_FORMAT HTC_WARN_FORMAT HTC_ERR_FORMAT Fatal Error Messages indicate a situation that cannot allow compilation to proceed and which re- quired the the compilation process to stop immediately. The requested output files will ...
Page 40
Compiler Messages Placeholder % specify the placeholders, as DOS interprets a single percent character as an argument and will not pass this on to the compiler. For example: --ERRFORMAT=”file %%f: Environment variables, in turn, ...
Page 41
PICC Command-line Driver main.c: 12: (362) redundant "&" applied to array (warning) (492) attempt to position absolute psect "text" is illegal (error) Notice that now all message follow a more uniform format and are displayed on a single line. The ...
Page 42
PICC Driver Option Descriptions or higher will be displayed by default. The information in this option is propagated to all compiler applications, so its effect will be observed during all stages of the compilation process. Warnings may also be disabled ...
Page 43
PICC Command-line Driver as a comma-separated list following an equal character, =, e.g. --OUTPUT=hex,cof. The exact format of the options varies and are described in detail in the following sections. Some commonly used suboptions include default, which represent the default ...
Page 44
PICC Driver Option Descriptions 2.6.3 -Efile: Redirect Compiler Errors to a File This option has two purposes. The first is to change the format of displayed messages. The second is to optionally allow messages to be directed to a file ...
Page 45
PICC Command-line Driver Note that all source files for which source-level debugging is required should be compiled with the -G option. The option is also required at the link stage, if this is performed separately. For example: PICC --CHIP=16F877A -G ...
Page 46
PICC Driver Option Descriptions If you wish the linker to scan libraries whose names do not follow the above naming convention or whose locations are not in the LIB subdirectory, simply include the libraries’ names on the com- mand line ...
Page 47
PICC Command-line Driver normally linked using the linker option: -pentry=CODE Which places entry anywhere in the memory defined by the CODE class. The pro- grammer then re-links the project, but now using the driver option: -L-pentry=CODE+800h to ensure that the ...
Page 48
... The -P option causes the assembler files to be preprocessed before they are assembled thus allowing the use of preprocessor directives, such as #include, with assembler code. By default, assembler files are not preprocessed. 2.6.12 -Q: Quiet Mode This option places the compiler in a quiet mode which suppresses the HI-TECH Software copyright notice from being displayed. 48 PICC Command-line Driver ...
Page 49
PICC Command-line Driver 2.6.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 file passed on the command line. The command: PICC --CHIP=16F877A ...
Page 50
PICC Driver Option Descriptions Table 2.5: Compiler responses to bank qualifiers Selection bank qualifiers are ignored ignore attempt to locate variable according to bank qualifier, if bank unavailable try elsewhere request attempt to locate variable according to bank qualifier, if ...
Page 51
PICC Command-line Driver Table 2.6: Default values for filling unprogrammed code space 2.6.20 --CHECKSUM=start-end@destination<,specs>: Calculate a checksum This option will perform a checksum over the address range specified and store the result at the destination address specified. Additional specifications can ...
Page 52
PICC Driver Option Descriptions 2.6.22 --CHIPINFO: Display List of Supported Processors The --CHIPINFO option simply displays a list of processors the compiler supports. The names listed are those chips defined in the chipinfo file and which may be used with ...
Page 53
PICC Command-line Driver Suboption Debugger selected No debugger none icd or icd1 MPLAB ICD MPLAB ICD2 icd2 MPLAB PICKit2 pickit2 2.6.26 --DOUBLE=type: Select kind of Double Types This option allows the kind of double types to be selected. By default ...
Page 54
PICC Driver Option Descriptions Suboption double 24 32 fast32 2.6.30 --FILL=opcode: Fill Unused Program Memory This option allows specification of a hexadecimal opcode that can be used to fill all unused program memory locations with a known code sequence. Multi-byte ...
Page 55
... The messagelist is a comma-separated list of warning numbers that are to be disabled. If the number of an error is specified, it will be ignored by this option. If the message list is specifi then all warnings are disabled. Table 2.9: Supported IDEs IDE HI-TECH Software’s HI-TIDE Microchip’s MPLAB Table 2.10: Supported languages Suboption Language ...
Page 56
PICC Driver Option Descriptions 2.6.38 --MSGFORMAT=format: Set Advisory Message Format This option sets the format of advisory messages produced by the compiler. See Section information. 2.6.39 --NODEL: Do not remove temporary files Specifying --NODEL when building will instruct PICCnot to ...
Page 57
PICC Command-line Driver Option name Select global optimization level (1 through 9) 1..9 Select optimizations of assembly derived from C source asm Select optimizations of assembly source files asmfile Favor accurate debugging over optimization debug Enable all compiler optimizations all ...
Page 58
PICC Driver Option Descriptions 2.6.45 --PASS1: Compile to P-code The --PASS1 option is used to generate a p-code intermediate files (.p1 file) from the parser, then stop compilation. Such a file needs to be generated if creating a p-code library ...
Page 59
PICC Command-line Driver } void printlist(int * list, int count) { while (count--) printf("%d ", * list++); putchar(’\n’); } If compiled with the command: PICC --CHIP=16F877A --PROTO test.c PICC will produce test.pro containing the following declarations which may then be ...
Page 60
PICC Driver Option Descriptions --RAM=0-ff This option may also be used to reserve memory ranges already defined as on-chip memory in the chipinfo file this supply a range prefixed with a minus character, -, for example: --RAM=default,-100-103 will ...
Page 61
PICC Command-line Driver Table 2.13: Runtime environment suboptions Suboption The code present in the startup module init that copies the idata, ibigdata and ifardata psects’ ROM-image to RAM. The inclusion of library files into the output clib code by the ...
Page 62
PICC Driver Option Descriptions 2.6.51 --SCANDEP: Scan for Dependencies When this option is used, a .dep (dependency) file is generated. The dependency file lists those files on which the source file is dependant. Dependencies result when one file is #included ...
Page 63
PICC Command-line Driver Table 2.14: Memory Summary Suboptions Suboption Summary of psect usage. psect General summary of memory used. mem Summary of class usage. class Summary of address used within the hex hex file. Whether summary information is shown file ...
Page 64
PICC Driver Option Descriptions 2.6.57 --VER: Display The Compiler’s Version Information The --VER option will display what version of the compiler is running. 2.6.58 --WARN=level: Set Warning Level The --WARN option is used to set the compiler warning level. Allowable ...
Page 65
Chapter 3 C Language Features HI-TECH C PRO for the PIC10/12/16 MCU Family supports a number of special features and exten- sions to the C language which are designed to ease the task of producing ROM-based applications. This chapter documents ...
Page 66
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 67
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 68
Processor-related Features serial_number will never revert back to the original 0x1234 value, even after reset, unless explicitly programmed to do so. Note the compiler only support basic assignment operations on eeprom qualified objects complex expression involving an eeprom ...
Page 69
C Language Features #include <htc.h> void eetest(void){ unsigned char value = 1; unsigned char address = 0; // write value to EEPROM address eeprom_write(address,value); // read from EE at address value = eeprom_read(address); } These functions test and wait for ...
Page 70
Processor-related Features In the case of EEPROM_READ(), there is another very important detail to note. Unlike eep- rom_read(), this macro does not wait for any concurrent EEPROM writes to complete before pro- ceeding to select and read EEPROM. Had the ...
Page 71
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 72
Processor-related Features For example, to make all the bits on the output port high impedance, the following code can be used after including pic.h. TRIS = 0xFF; This will load the appropriate value into the W register and then call ...
Page 73
C Language Features Type bit char unsigned char short unsigned short int unsigned int short long unsigned short long long unsigned long float double be saved from the last ROM location before it is erased. The constant must then be ...
Page 74
Supported Data Types and Variables Radix binary octal decimal hexadecimal Any integral constant will have a type which is the smallest type that can hold the value without overflow. The suffi may be used with the constant ...
Page 75
C Language Features const char * cp = "hello " "world"; assigned the pointer with the string "hello world". 3.3.2 Bit Data Types and Variables HI-TECH C PRO for the PIC10/12/16 MCU Familysupports bit integral types which can hold the ...
Page 76
Supported Data Types and Variables The psects in which bit objects are allocated storage are declared using the bit PSECT directive flag. Eight bit objects will take up one byte of storage space which is indicated by the psect’s scale ...
Page 77
C Language Features 3.3.5 24-Bit Integer Data Types HI-TECH C PRO for the PIC10/12/16 MCU Family supports four 24-bit integer types. short long are 24-bit two’s complement signed integer types, representing integral values from -8,388,608 to +8,388,607 inclusive. Unsigned short ...
Page 78
Supported Data Types and Variables Format IEEE 754 32-bit modified IEEE 754 24-bit Table 3.4: Floating-point format example IEEE 754 Format Number biased expo- nent 32-bit 7DA6B69Bh 11111011b 24-bit 42123Ah 10000100b mantissa is the mantissa, which is to the right ...
Page 79
C Language Features member. The members of structures and unions may not be objects of type bit, but bit-fields are fully supported. Structures and unions may be passed freely as function arguments and return values. Pointers to structures and unions ...
Page 80
Supported Data Types and Variables 3.3.8.2 Structure and Union Qualifiers HI-TECH C supports the use of type qualifiers on structures. When a qualifier is applied to a struc- ture, all of its members will inherit this qualification. In the following ...
Page 81
C Language Features The volatile type qualifier is used to tell the compiler that an object cannot be guaranteed to retain its value between successive accesses. This prevents the optimizer from eliminating appar- ently redundant references to objects declared volatile ...
Page 82
Supported Data Types and Variables 3.3.10.2 Near Type Qualifier The near type qualifi recommendation to place static variables in the common memory of the PIC MCU. Near objects are represented by 8 bit addresses and are always accessible ...
Page 83
C Language Features A RAM pointer to an eeprom int: eeprom int * nptr; EEPROM access is described in further detail in section 3.2.5.2. 3.3.12 Pointer Types There are two basic pointer types supported by HI-TECH C PRO for the ...
Page 84
Supported Data Types and Variables volatile int * volatile vivp ; The first example is a pointer called vip. It contains the address of an int objects that are qualified volatile. The pointer itself — the variable that holds the ...
Page 85
C Language Features – Address is an offset into either bank 0 (extending into bank 1) or bank 2 (extending into bank 3) A 16-bit pointer capable of accessing the entire data memory space; An 8-bit pointer capable of accessing ...
Page 86
Supported Data Types and Variables One positive aspect of tracking pointer targets is less of a dependence on pointer qualifiers. The standard qualifiers const and volatile must still be used in pointer definitions to indicate a read-only or externally-modifiable target ...
Page 87
C Language Features 3.3.12.4 Pointers to Both Memory Spaces When a pointer is assigned the address of one or more objects allocated memory in the data space, and also assigned the address of one or more const objects, the pointer ...
Page 88
Storage Class and Object Placement 3.4 Storage Class and Object Placement Objects are positioned in different memory areas dependant on their storage class and declaration. This is discussed in the following sections. 3.4.1 Local Variables A local variable is one ...
Page 89
C Language Features 3.4.1.2 Static Variables Uninitialized static variables are allocated a fixed memory location which will not be overlapped by storage for other functions. Static variables are local in scope to the function in which they are declared, but ...
Page 90
Functions location encapsulated in a RETLW instructions which can be called and which return with the value in WREG. All const-qualified data objects and string literals are placed in the strings psect. See also Section 3.3.12. 3.5 Functions 3.5.1 Function ...
Page 91
C Language Features 3.5.2 Function Return Values Function return values are passed to the calling function as follows: 3.5.2.1 8-Bit Return Values Eight-bit values are returned from a function in WREG. For example, the function: char return_8(void) { return 0; ...
Page 92
Function Calling Convention struct fred { int ace[4 struct fred return_struct(void) { struct fred wow; return wow; } will exit with the following code: retlw ??_return_struct+0 3.6 Function Calling Convention The baseline PIC devices have a two-level deep ...
Page 93
C Language Features The midrange PIC devices have larger stacks and are thus allow a higher degree of function nesting. These devices do not use the lookup table method when calling functions. The compiler assumes that bank zero will be ...
Page 94
Operators Another problem that frequently occurs is with the bitwise compliment operator, “~”. This operator toggles each bit within a value. Consider the following code. unsigned char count 0x55; if 0xAA) count++; If c contains ...
Page 95
C Language Features Operand Left shifts (< < operator), signed or unsigned, always clear the least significant bit of the result. 3.7.3 Division and modulus with integral types The sign of the result of division ...
Page 96
Psects config Used to store the configuration word. eeprom_data Used to store data into EEPROM memory. end_init Used by initialisation code which, for example, clears RAM. float_textn Used by some library routines, and in particular by arithmetic routines.It is possible ...
Page 97
C Language Features text Is a global psect used for executable code for some library functions. textn These psects (where number) contain all executable code for the Midrange processors. They also contains any executable code after the ...
Page 98
... The PIC processor only saves the PC on its stack whenever an interrupt occurs. Other registers and objects must be saved in software. The HI-TECH C PRO for the PIC10/12/16 MCU Family 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 defi ...
Page 99
C Language Features If 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 areas ...
Page 100
Mixing C and Assembler Code made to both of these functions as if they were independently written. This feature allows the programmer to write code which is independent of whether the target device allows re-entrant functions. PRO compilers will have ...
Page 101
C Language Features ensure any symbol used to hold arguments to the routine is globally accessible ensure any symbol used to hold a return value is globally accessible optionally, use a signature value to enable type checking when the function ...
Page 102
Mixing C and Assembler Code To call an assembly routine from C code, a declaration for the routine must be provided. This ensures that the compiler knows how to encode the function call in terms of parameters and return values, ...
Page 103
C Language Features #endasm // or like this asm("bcf 0,3"); asm("rlf _var"); asm("rlf _var+1"); } 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 ...
Page 104
Mixing C and Assembler Code #include <htc.h> void main(void) { PORTA = 0x55; asm("movlw #0xAA"); asm("movwf _PORTA); 3.10.4 Interaction between Assembly and C Code HI-TECH C PRO for the PIC10/12/16 MCU Family incorporates several features designed to allow C code ...
Page 105
C Language Features generator to ensure that these address spaces are not used by C code. The linker will also be told to remove these ranges from those available, and this reservation will be observable in the map file. The ...
Page 106
Preprocessing 3.11 Preprocessing All C source files are preprocessed before compilation. Assembler files can also be preprocessed if the -P command-line option is issued. 3.11.1 Preprocessor Directives HI-TECH C PRO for the PIC10/12/16 MCU Family accepts several specialised preprocessor direc- ...
Page 107
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 108
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 common RAM _COMMON_ present Always _BANKBITS_ Always _GPRBITS_ If compiling for __MPLAB_ICD__ MPLAB ...
Page 109
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 Specify registers used by function regsused Specify ...
Page 110
Preprocessing Register Name fsr wreg status 3.11.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 ...
Page 111
C Language Features switch type auto direct The register names are not case sensitive and a warning will be produced if the register name is not recognised. A blank list indicates that the specified function or routine uses no registers. ...
Page 112
Preprocessing T UT RIAL D ISABLING A WARNING qualifying an auto object being disabled, number 348. void main(void) { #pragma warning disable 348 near int c; #pragma warning enable 348 / * etc * / } int rv(int a) { ...
Page 113
C Language Features the messaging system is retrieved by the use of the warning pop pragma. The warning error/warning pragma It is also possible to change the type of some messages. This is only possible by the use of the ...
Page 114
Linking Programs HI-TECH C, by default, generates Intel HEX. Use the --OUTPUT= option to specify a different output format. After linking, the compiler will automatically generate a memory usage map which shows the address used by, and the total sizes ...
Page 115
C Language Features At link time the linker will report any mismatch of signatures. HI-TECH C PRO for the PIC10/12/16 MCU Family is only likely to issue a mismatch error from the linker when the routine is either a pre- ...
Page 116
Standard I/O Functions and Serial I/O Table 3.12: Supported standard I/O functions Function name printf(const char * s, ...) sprintf(char * buf, const char * s, ...) 3.12.3 Linker-Defined Symbols The link address of a psect can be obtained from ...
Page 117
Chapter 4 Macro Assembler The Macro Assembler included with HI-TECH C PRO for the PIC10/12/16 MCU Family assembles source files for PIC MCUs. This chapter describes the usage of the assembler and the directives (assembler pseudo-ops and controls) accepted by ...
Page 118
Assembler Options where the assembler is being called directly, or when they are specified using the command-line driver option --SETOPTION, see Section 2.6.53. The usage of the assembler is similar under all of available operating systems. All command-line options are ...
Page 119
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 120
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 121
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 122
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 123
Macro Assembler An_identifier an_identifier an_identifier1 $ ?$_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 ...
Page 124
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 125
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 126
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 127
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 128
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 129
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 130
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 131
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 132
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 133
Macro Assembler 4.3.8.11 FNADDR This directive tells the linker that a function has its address taken, and thus could be called indirectly through a function pointer. For example FNADDR _func1 tells the linker that func1() has its address taken. 4.3.8.12 ...
Page 134
HI-TECH C Assembly Language 4.3.8.14 FNCALL This directive takes the form: FNCALL fun1,fun2 FNCALL is usually used in compiler generated code. It tells the linker that function fun1 calls function fun2. This information is used by the linker when performing ...
Page 135
Macro Assembler 4.3.8.17 FNSIZE The FNSIZE directive informs the linker of the size of the local variable and argument area associ- ated with a function. These values are used by the linker when building the call graph and assigning addresses ...
Page 136
HI-TECH C Assembly Language In this example, if ABC is non-zero, the first jmp instruction will be assembled but not the second or third. If ABC is zero and DEF is non-zero, the second jmp will be assembled but the ...
Page 137
Macro Assembler If an argument is preceded by a percent sign %, that argument will be evaluated as an expression and passed as a decimal number, rather than as a string. This is useful if evaluation of the argument inside ...
Page 138
HI-TECH C Assembly Language 4.3.8.22 ALIGN The ALIGN directive aligns whatever is following, data storage or code etc., to the specified bound- ary in the psect in which the directive is found. The boundary is specifi number following ...
Page 139
Macro Assembler would expand to: PSECT idata_0 DW 4865h DW 6C6Ch DW 6F00h PSECT text0 Note that you can use local labels and angle brackets in the same manner as with conventional macros. The IRPC directive is similar, except it ...
Page 140
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 ...
Page 141
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.2 EXPAND When EXPAND is in effect, the code generated by macro expansions will appear in the listing output. See also the NOEXPAND ...
Page 142
HI-TECH C Assembly Language 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 Section 4.3.9.2. Assembly macro are discussed in Section 4.3.8.20. 4.3.9.7 NOLIST This control ...
Page 143
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 144
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 145
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 146
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 147
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 148
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 149
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 150
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 151
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 152
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 153
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 154
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 155
Linker and Utilities used, 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 ...
Page 156
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 157
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 158
... 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\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 159
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 160
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 161
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 162
Map Files be stored temporarily in the functions scratch area. Variables which are passed via a register may need to be saved into the function’s temporary variable if that register is required for code generation purposes, in which case they ...
Page 163
Linker and Utilities _get size 0,0 offset 47 ; _prep2 may call by _get 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 ...
Page 164
Map Files at the same time as init is active, so its APB can overlap with that of init and is placed at offset 4 within the auto/parameter psect. The function byteconv may call several functions: float, ldiv, crv and ...
Page 165
Linker and Utilities reserved and used by the program. The difference shows the amount of memory saved by overlapping of these blocks by the linker. 5.10.2.3 Psect Information listed by Module The next section in the map file lists those ...
Page 166
... 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 ...
Page 167
Linker and Utilities This information in this section of the map file can be used to observe several details; To confirm that a module is making a contribution to the output file by ensuring that the module appears in the ...
Page 168
Map Files 5.10.2.6 Unused Address Ranges The last of the memory summaries Just before the symbol table in the map fi list of memory which was not allocated by the linker. This memory is thus unused. The linker ...
Page 169
Linker and Utilities Although these symbols are used to represent the local autos and parameters of a function, they themselves must be globally accessible to allow each calling function to load their contents. The C auto and parameter variable identifiers ...
Page 170
Librarian Table 5.2: Librarian command-line options Option -Pwidth -W Table 5.3: Librarian key letter commands not all the modules, on the first pass. On the second pass it need read only those modules which are required, seeking over the others. ...
Page 171
Linker and Utilities Under the d key letter, the named object files will be deleted from the library. In this instance error not to give any object file names. The m and s key letters will list ...
Page 172
Objtohex 5.11.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 each module ...
Page 173
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 174
Cref 5.12.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 one checksum. ...
Page 175
Linker and Utilities Table 5.5: CREF command-line options Option -Fprefix -Hheading -Llen -Ooutfile -Pwidth -Sstoplist -Xprefix 5.13.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 ...
Page 176
Cromwell 5.13.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.13.6 -Sstoplist The -S option ...
Page 177
... 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 Description Processor name and architecture Identify code classes Dump input fi ...
Page 178
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 additional argument to this option which also specifies the processor architecture is required. Hence for this format the ...
Page 179
Linker and Utilities the COD file. 5.14.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.14.7 -Ikey This option can be used to specify the default ...
Page 180
Hexmate 5.15 Hexmate The Hexmate utility is a program designed to manipulate Intel HEX files. Hexmate is a post-link stage utility that provides the facility to: Calculate and store variable-length checksum values Fill unused memory locations with known data sequences ...
Page 181
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 182
Hexmate 5.15.1.1 specifications,filename.hex Intel hex files that can be processed by hexmate should be in either INHX32 or INHX8M format. Additional specifications can be applied to each hex file to put restrictions or conditions on how this file should be ...
Page 183
Linker and Utilities in the device’s native format. To facilitate this, the -ADDRESSING option is used. This option takes exactly one parameter which configures the number of bytes contained per address location. If for example a device’s program memory naturally ...
Page 184
Hexmate Table 5.10: Hexmate Checksum Algorithm Selection Selector - typical example of the use of the checksum option is: -CK=0-1FFF@2FFE+2100w2 This will calculate a checksum over the range 0-1FFFh and ...
Page 185
Linker and Utilities 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 ...
Page 186
Hexmate it is applied 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 ...
Page 187
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 Length is ...
Page 188
Hexmate 5.15.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.15.1.13 -MASK Use this option ...
Page 189
Linker and Utilities Interval is optional and specifies the address shift per repetition of this code. Repetitions is optional and specifies the number of times to repeat this code. For example: -SERIAL=000001@EFFE will store hex code 00001h to address EFFEh. ...
Page 190
Hexmate 5.15.1.18 -STRPACK This option performs the same function as -STRING but with two important differences. Firstly, only the lower seven bits from each character are stored. Pairs of 7 bit characters are then concatenated and stored ...
Page 191
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 192
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 193
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 194
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 195
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 196
Synopsis __delay_ms(x) // request a delay in milliseconds __delay_us(x) // request a delay in microseconds // request a delay for a number of instruction cycles void _delay_ms(unsigned long n) Description The when code calls _delay(n), the code ...
Page 197
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 198
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 199
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 200
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. 200 Library Functions ...