SW500011 Microchip Technology, SW500011 Datasheet
SW500011
Specifications of SW500011
778-1007
778-1007
Related parts for SW500011
SW500011 Summary of contents
Page 1
Manual ...
Page 2
... HI-TECH C TOOLS for the PIC32 MCU Family HI-TECH Software Copyright (C) 2008 HI-TECH Software. All Rights Reserved. Printed in Australia. HI-TECH Software Pty. Ltd. web: http://microchip.htsoft.com Produced on: July 22, 2008 ACN 002 724 549 45 Colebard Street West Acacia Ridge QLD 4110 Australia email: hitech@htsoft.com ...
Page 3
Contents Table of Contents List of Tables 1 Introduction 1.1 Typographic conventions 2 PICC32 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.3.3 The Powerup Routine 2.3.4 The printf Routine 2.4 Debugging Information 2.4.1 Output File Formats 2.4.2 Symbol Files 2.5 Compiler Messages . . . . . . . . . . . . . . . . . . ...
Page 5
CONTENTS 2.6.25 --ERRFORMAT=format: Define Format for Compiler Messages 2.6.26 --ERRORS=number: Maximum Number of Errors 2.6.27 --FILL=opcode: Fill Unused Program Memory 2.6.28 --GETOPTION=app,file: Get Command-line Options 2.6.29 --HELP<=option>: Display Help 2.6.30 --IDE=type: Specify the IDE being used 2.6.31 --INTERRUPTS=suboption,<suboption>: Specify the ...
Page 6
CONTENTS 3 C Language Features 3.1 ANSI Standard Issues 3.1.1 Divergence from the ANSI C Standard 3.1.2 Implementation-defined behaviour 3.1.3 Non-ANSI Operations 3.2 Processor-related Features 3.2.1 Processor Support 3.2.2 Configuration Fuses 3.2.3 Multi-byte SFRs 3.3 Supported Data Types and Variables ...
Page 7
CONTENTS 3.5.2 Function Argument Passing 3.5.3 Function Return Values 3.5.4 Function Stack Frame 3.6 Register Usage Conventions 3.7 Operators . . . . . . . . . . . . . . . . . . . . . ...
Page 8
CONTENTS 4 Macro Assembler 4.1 Assembler Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 9
CONTENTS 4.3.10.16 LOCAL 4.3.10.17 ALIGN 4.3.10.18 REPT 4.3.10.19 IRP and IRPC 4.3.10.20 PROCESSOR 4.3.10.21 SIGNAT 4.3.11 Assembler Controls 4.3.11.1 ASMOPT_ON 4.3.11.2 ASMOPT_OFF 4.3.11.3 FORCE_EXTEND 4.3.11.4 NEVER_EXTEND 4.3.11.5 AUTO_EXTEND 4.3.11.6 COND 4.3.11.7 EXPAND 4.3.11.8 INCLUDE 4.3.11.9 LIST 4.3.11.10 NOCOND 4.3.11.11 NOEXPAND ...
Page 10
CONTENTS 5.7.6 -Dsymfi 142 ...
Page 11
CONTENTS 5.10.6 Ordering of Libraries 5.10.7 Error Messages 5.11 Objtohex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 12
CONTENTS 5.14.1.13 -MASK 5.14.1.14 -Ofile 5.14.1.15 -SERIAL 5.14.1.16 -SIZE 5.14.1.17 -STRING 5.14.1.18 -STRPACK A Library Functions __CONFIG . . . . . . . . . . . . . . . . . . . . . . . ...
Page 13
CONTENTS ISDIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 14
CONTENTS STRTOK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 15
List of Tables 2.1 PICC32 input file types 2.2 Default configuration settings 2.3 Support languages . . . . . . . . . . . . . . . . . . . . . . . . . ...
Page 16
LIST OF TABLES 4.3 MIPS16e Assembly Instruction Operand Variants 4.4 ASPIC32 statement formats 4.5 ASPIC32 numbers and bases 4.6 ASPIC32 operators . . . . . . . . . . . . . . . . . . . ...
Page 17
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 18
Typographic conventions 18 Introduction ...
Page 19
Chapter 2 PICC32 Command-line Driver PICC32 is the driver invoked from the command line to perform all aspects of compilation, includ- ing C code generation, assembly and link steps the recommended way to use the compiler as it ...
Page 20
Invoking the Compiler File Type .c .p1 .lpp .as .obj .lib .hex 2.1 Invoking the Compiler This chapter looks at how to use PICC32 as well as the tasks that it and the internal applications perform during compilation. PICC32 has ...
Page 21
PICC32 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 22
The Compilation Sequence Figure 2.1: Flow diagram of the initial compilation sequence .lst 2.2 The Compilation Sequence PICC32 will check each file argument and perform appropriate actions on each file. The entire compilation sequence can be thought of as the ...
Page 23
PICC32 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 24
The Compilation Sequence generated filename RIAL S INGLE STEP COMPILATION and c_sb.lpp are to be compiled. To perform this in a single step, the following com- mand line can be used as a starting point for the project ...
Page 25
PICC32 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 26
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 27
PICC32 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 28
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 assembler-level routines that are ...
Page 29
PICC32 Command-line Driver PICC32 then “writes” the assembler code which will perform the startup sequence. This code is stored into a file which is then assembled and linked into the remainder of the program automatically. The runtime startup code is ...
Page 30
Runtime Files With this part of the runtime startup code absent, the contents of initialized variables will be unpre- dictable when the program begins execution. Code relying on variables containing their initial value will fail. Since auto objects are dynamically ...
Page 31
PICC32 Command-line Driver With this part of the runtime startup code absent, the contents of uninitialized variables will be unpredictable when the program begins execution. Variables whose contents should be preserved over a reset, or even power off, should be ...
Page 32
Runtime Files C W ONFIG ORD 0xBFC02FFC 0xBFC02FF8 0xBFC02FF4 Table 2.2: Default configuration settings 2.3.2.6 Default Configuration Words (--RUNTIME=config) With this runtime sub-option enabled the driver will check to ensure that the config words at the top of boot flash ...
Page 33
PICC32 Command-line Driver enable instruction caching and enable predictive prefetch cache on all regions. 2.3.3 The Powerup Routine Some hardware configurations require special initialization, often within the first few instruction cycles after reset. To achieve this there is a hook ...
Page 34
Runtime Files function for the project being compiled. After parsing, the p-code output derived from doprnt.c is then combined with the remainder of the C program in the final code generation step RIAL C A program contains one ...
Page 35
PICC32 Command-line Driver the compiler will detect that the argument being printed has double type, thus the only valid placeholders would be those that print floating point types, for example %e, %f and %g. No aspect of this operation is ...
Page 36
Compiler Messages PICC32 --CHIP=32MX360F512L -Gtest.sym test.c init.c This option will also generate other symbol files for each module compiled. These files are produced by the code generator and do not contain absolute address. These files have the extension .sdb. The ...
Page 37
PICC32 Command-line Driver If a language other than English is selected, and the message cannot be found in the appropriate non-English MDF, the alert system tries to find the message in the English MDF English message string is ...
Page 38
Compiler Messages any remaining modules. Unless prevented by some driver option or another error message, the project will be linked and the requested output file(s) will be generated. Error Messages indicate source code that is illegal and that compilation of ...
Page 39
PICC32 Command-line Driver Table 2.4: Messaging environment variables Variable HTC_MSG_FORMAT HTC_WARN_FORMAT HTC_ERR_FORMAT Placeholder % specify the placeholders, as DOS interprets a single percent character as an argument and will not pass this on to ...
Page 40
Compiler Messages the line of source code and highlighted the position at which the warning was first detected, as well as show the actual warning message string. The -E option is now used and the compiler issues the same messages, ...
Page 41
PICC32 Command-line Driver 2.5.5.1 Disabling Messages Each warning message has a default number indicating a level of importance. This number is speci- fied in the MDF and ranges from - The higher the number, the more important the ...
Page 42
PICC32 Driver Option Descriptions PICC32 recognizes the compiler options listed in the table below. The case of the options is not important, however command shells in UNIX-based operating systems are case sensitive when it comes to names of files. All ...
Page 43
PICC32 Command-line Driver where text is the textual substitution required. Thus, the command: PICC32 --CHIP=32MX360F512L -Ddebug -Dbuffers=10 test.c will compile test.c with macros defined exactly as if the C source code had included the directives: #define debug 1 #define buffers ...
Page 44
PICC32 Driver Option Descriptions 2.6.4 -Gfile: Generate Source-level Symbol File The -G option generates a source-level symbol file (i.e. a file which allows tools to determine which line of source code is associated with machine code instructions, and determine which ...
Page 45
PICC32 Command-line Driver 2.6.6 -Llibrary: Scan Library The -L option is used to specify additional libraries which are to be scanned by the linker and code generator. Libraries specified using the -L option are scanned before any C standard libraries. ...
Page 46
PICC32 Driver Option Descriptions alternate settings in the linker tab in an MPLAB Build options... dialogue, these are the driver options (not linker options), but which are used by the driver to generate the appropriate linker options during the linking ...
Page 47
PICC32 Command-line Driver for a project links several psects in the following fashion. -pone=600h,two,three which links one at 600h, then follows this with two, then three. It has been decided that the psects should be linked so that one follows ...
Page 48
... 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. 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 fi ...
Page 49
PICC32 Command-line Driver 2.6.15 -V: Verbose Compile The -V is the verbose option. The compiler will display the command lines used to invoke each of the compiler applications or compiler passes. Displayed will be the name of the compiler application ...
Page 50
PICC32 Driver Option Descriptions 2.6.19 --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 be appended as a comma separated list to ...
Page 51
PICC32 Command-line Driver Thus this option can not be used when using any compilation process that compiles each source file separately using the -C or --PASS1 options. Such is the case for most IDEs, including HI-TIDE, and makefiles. 2.6.23 --DEBUGGER=type: ...
Page 52
... The interrupt scheme is specified using sub-options to this driver option in a similar fashion to the --runtime option. Sub-options are divided into three groups which are as follows: sub-options which affect the type of interrupt vectors (see Table 2.7); 52 Table 2.6: Supported IDEs IDE HI-TECH Software’s HI-TIDE Microchip’s MPLAB PICC32 Command-line Driver ...
Page 53
PICC32 Command-line Driver OPTION EANING (default) For each interrupt function assigned a specific rom vector to service, a corresponding entry is made in the table which jumps only to this function. At each entry in the ...
Page 54
PICC32 Driver Option Descriptions OPTION EANING (default) All interrupt service requests will be serviced at a multi calculated address. In all cases the spaceing between vectors in 32 bytes. All other exceptions are still serviced at ...
Page 55
PICC32 Command-line Driver 2.6.34 --MEMMAP=file: Display Memory Map This option will display a memory map for the specified map file. This option is seldom required, but would be useful if the linker is being driven explicitly, i.e. instead of in ...
Page 56
PICC32 Driver Option Descriptions 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 ...
Page 57
PICC32 Command-line Driver Type tag lib lpp intel tek aahex mot ubrof bin cof cod elf specifying an output file format list containing, e.g. lib or all will over-ride the non-library output types, and only the library file will be ...
Page 58
PICC32 Driver Option Descriptions option is omitted, the preprocessed source for printf will be retained in the file doprnt.pre. 2.6.45 --PROTO: Generate Prototypes The --PROTO option is used to generate .pro files containing both ANSI and K&R style function declarations ...
Page 59
PICC32 Command-line Driver extern void printlist(int *, int); #else /* PROTOTYPES */ extern int add(); extern void printlist(); #endif /* PROTOTYPES */ 2.6.46 --RAM=lo-hi,<lo-hi,...>: Specify Additional RAM Ranges This option is used to specify memory, in addition to any RAM ...
Page 60
PICC32 Driver Option Descriptions --ROM=default,+100-2ff for example. To only use an external range and ignore any on-chip memory, use: --ROM=100-2ff This option may also be used to reserve memory ranges already defined as on-chip memory in the chip configuration file. ...
Page 61
PICC32 Command-line Driver Suboption Test for a non maskable interrupt and invoke nmi it’s handler if necessary. Test for a soft-reset condition and invoke the soft applicable interrupt function. Initialise the system coprocessor. See Section cp0 2.3.2.3. Initialise some general ...
Page 62
PICC32 Driver Option Descriptions For example, to store the one byte value program memory address 1000h, use the option --SERIAL=00@1000. Use the option --SERIAL=00000000@1000 to store the same value as a four byte quantity. This option is functionally ...
Page 63
PICC32 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
PICC32 Driver Option Descriptions and constructs. The higher the warning level, the more important the warning message. The default warning level is 0 and will allow all normal warning messages. Use this option with care as some warning messages indicate ...
Page 65
Chapter 3 C Language Features HI-TECH C PRO for the PIC32 MCU Family 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 ...
Page 66
Processor-related Features operator, but no rotate operator. The code generator encodes matching sequences using assembly rotate instructions where possible. The code sequence to implement a rotate right by 1 bit looks like: var = (var > > (var ...
Page 67
C Language Features For example, to set a PIC32Cxx1 chip to have Code Protect and Boot Flash write-protect dis- abled, ICE Communication Channnel enabled, and the watchdog timer enabled with a post scale factor of 1:1, the following could be ...
Page 68
Supported Data Types and Variables Type bit char unsigned char signed char short unsigned short signed short int unsigned int signed int long unsigned long signed long float double Radix binary octal decimal hexadecimal 68 Table 3.1: Basic data types ...
Page 69
C Language Features 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 to indicate that it must be assigned ...
Page 70
Supported Data Types and Variables static bit init_flag; will be allocated in the bit-addressable psect rbit, and will be visible only in that function. When the following declaration is used outside any function: bit init_flag; init_flag will be globally visible, ...
Page 71
... Therefore, bit number 3 (the fourth bit in the byte since numbering starts with 0) in byte number 5 is actually absolute bit number 43 (that is 8bits/byte * 5 bytes + 3 bits). For example, to access the software reset detection flag bit in the RCON register, declare RCON object at absolute address BF80F600h, then declare a bit variable at absolute bit address 27: static unsigned long RCON @ 0xBF80F600 ...
Page 72
Supported Data Types and Variables Variables may be declared using the signed short int and unsigned short int keyword sequences, respectively, to hold values of these types. When specifying a short int type, the keyword int may be omitted. Thus ...
Page 73
C Language Features Format Sign IEEE 754 32-bit x Table 3.4: Floating-point format example IEEE 754 Number biased expo- nent 7DA6B69Bh 11111011b (251) The sign bit is zero; the biased exponent is 251, so the exponent is 251-127=124. Take the ...
Page 74
Supported Data Types and Variables unsigned unsigned unsigned } foo; will produce a structure occupying 4 bytes. If foo was ultimately linked at address 10H, the field lo will be bit 0 of address 10H, hi will be bit 7 ...
Page 75
C Language Features In this case, the structure will be placed into the program space and each member will, obviously, be read-only. Remember that all members must be initialized if a structure is const as they cannot be initialized at ...
Page 76
Supported Data Types and Variables incremented, but the same operation performed on a volatile object will load the W register with 1 and then store this to the appropriate address. Objects that are not qualified volatile may be removed by ...
Page 77
C Language Features 3.3.10.2 cp0 Type Qualifier The cp0 type qualifier is used to facilitate access within C programs to the registers of the system coprocessor 0 (CP0). Any 4-byte unsigned integer variable may be so qualified. These variables must ...
Page 78
Supported Data Types and Variables 3.3.10.4 __strictcall Function Qualifier If the __strictcall qualifier is used, only the first 4 a registers are used for passing parameters to this function. If the __strictcall qualifier is not used, the HI-TECH C PRO ...
Page 79
C Language Features rectly, must ensure that the contents of any non-active table registers are preserved. Saving both TBLPTRH and TBLPTRU will ensure that this requirement is met. 3.3.11.2 Function Pointers Function pointers can be defined to indirectly call functions ...
Page 80
Storage Class and Object Placement calls to a function, unless explicitly modified via a pointer. Static variables are not subject to any architectural limitations on the PIC32. Static variables which are initialised are allocated in the data psect are only ...
Page 81
C Language Features 3.5 Functions 3.5.1 Absolute Functions The generated code associated with a function can be placed at an absolute address. This can be accomplished by using an @ address construct in a similar fashion to that used with ...
Page 82
Register Usage Conventions Figure 3.1: General Function Stack Frame 3.5.4 Function Stack Frame Figure 3.1 illustrates the general arrangement of function stack frames used by the compiler. 3.6 Register Usage Conventions Some of the general purpose registers of the device ...
Page 83
C Language Features register will always contain the return address from that function. In non-leaf functions the contents of the register is preserved on the stack. 3.7 Operators HI-TECH C PRO for the PIC32 MCU Family supports all the ANSI ...
Page 84
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 85
C Language Features Operand Right shifts of unsigned integral values always clear the most significant bit of the result. Left shifts (< < operator), signed or unsigned, always clear the least significant bit of the ...
Page 86
Psects The compiler-generated psects which are loaded in internal boot flash are: init Runtime startup code which performs initialisation, for example, clearing the RAM. powerup Used to load any user-defined routine in powerup.as. config Used to store the configuration words. ...
Page 87
C Language Features stack This psect contains the program stack. heap This psect contains the program heap. heapstack This psect contains the program heap and stack. 3.9 Interrupt Handling in C The compiler incorporates features allowing interrupts to be handled ...
Page 88
Mixing C and Assembly Code <pic32.h>. Only one interrupt function may be assigned this duty and only at compile time interrupt function is assigned this duty the compiler will generate a default handler which consists solely of an ...
Page 89
C Language Features 3.10.1 External Assembly Language Functions Entire functions may be coded in assembly language as separate .as source files, assembled by the assembler, ASPIC32 , and combined into the binary image using the linker. This technique allows arguments ...
Page 90
Mixing C and Assembly Code This way we do not need to use any additional linker options use an ordinary looking psect that you would see in assembly code produced by the compiler. The psect’s name is text32. ...
Page 91
C Language Features { short a, result read_port(); result = add(5, a); } Another example, suppose you have an assembly language function to double an unsigned byte value: extern __strictcall char twice(char); declares an external function called twice() ...
Page 92
Mixing C and Assembly Code 3.10.2 #asm, #endasm and asm() PIC32 instructions may also be directly embedded “in-line” into C code using the directives #asm, #endasm or the statement asm(). The #asm and #endasm directives are used to start and ...
Page 93
C Language Features constructs such as if, while, do etc. then you should use only the asm("") form, which statement and will correctly interact with all C flow-of-control structures. 3.10.3 Accessing C objects from within Assembly Code ...
Page 94
Mixing C and Assembly Code 3.10.3.1 Accessing special function register names from assembler If writing separate assembly modules, SFR definitions will not automatically be present. If writing assembly code from within a C module, SFRs may be accessed by referring ...
Page 95
C Language Features T UT RIAL P ROCESSING OF ABSOLUTE PSECTS be located at address 210h in the data space. The assembly file contains: PSECT lkuptbl,class=RAM,space=1,abs,ovlrd ORG 210h lookup: ds 20h When the project is compiled, this file is assembled ...
Page 96
Preprocessing int input; but this variable is only ever used in assembly code. The assembly module(s) can simply declare and link in to this symbol using the GLOBAL assembler directive, and them make use of the symbol. GLOBAL _input PSECT ...
Page 97
C Language Features Both these comment styles can be used, in addition to the standard assembly comment (see Section 4.3.5), in assembly source code if the -P command-line option is issued, see Section 2.6.11. All comments are removed by the ...
Page 98
Preprocessing Always __TIME__ Always __LANGUAGE_C__ _PLIB --runtime=plib –opt=speed __OPTIMIZE_SPEED__ –opt=size __OPTIMIZE_SIZE__ _INTERRUPTS_SINGLE --interrupts=single --interrupts=multi or by default _INTERRUPTS_MULTI _INTERRUPTS_GENEX --interrupts=genex _INTERRUPTS_PFM --interrupts=pfm --interrupts=boot or by default _INTERRUPTS_BOOT _INTERRUPTS_RAM --interrupts=ram --interrupts=rom or by default _INTERRUPTS_ROM _INTERRUPTS_NONE --interrupts=none --isa=mips32r2 or by default ...
Page 99
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 100
Preprocessing Directive Enable JIS character handling in jis strings Disable JIS character handling (de- nojis fault) Enable printf-style format string printf_check checking Specify registers which are used in regsused an interrupt Specify code generation for switch switch statements Control messaging ...
Page 101
C Language Features checked for consistency with the remaining arguments. This directive enables this checking for the named function, e.g. the system header file <stdio.h> includes the directive #pragma printf_check(printf) const to enable this checking for printf(). You may also ...
Page 102
Preprocessing Register Name wreg status pclat prodl, prodh fsr0, fsr1, fsr2 tblptrl, tblptrh, tblptru switch type auto direct #pragma switch switch_type where switch_type is one of the available switch methods listed in Table . Specifying the direct option to the ...
Page 103
C Language Features 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) { near int c; /* etc */ } ...
Page 104
Linking Programs 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 warning pragma and only affects messages generated by the parser or code generator. The ...
Page 105
C Language Features The program statistics shown after the summary provides more concise information based on each memory area of the device. This can be used as a guide to the available space left in the device. More detailed memory ...
Page 106
Linking Programs At link time the linker will report any mismatch of signatures. HI-TECH C PRO for the PIC32 MCU Family is only likely to issue a mismatch error from the linker when the routine is either a precompiled object ...
Page 107
C Language Features Table 3.11: 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 the value of ...
Page 108
Standard I/O Functions and Serial I/O 108 C Language Features ...
Page 109
Chapter 4 Macro Assembler The Macro Assembler included with HI-TECH C PRO for the PIC32 MCU Family assembles source files for PIC32 MCUs. This chapter describes the usage of the assembler and the directives (assem- bler pseudo-ops and controls) accepted ...
Page 110
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.51. The usage of the assembler is similar under all of available operating systems. All command-line options are ...
Page 111
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 112
Assembler Options -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 file contains ...
Page 113
Macro Assembler 4.3 HI-TECH C Assembly Language The source language accepted by the macro assembler, ASPIC32 , is described below. All opcode mnemonics and operand syntax are strictly PIC32 assembly language. Additional mnemonics and assembler directives are documented in this ...
Page 114
HI-TECH C Assembly Language 4.3.2 Instruction Operand Variants Many of the operand assembly machine and in-built instructions have variants with less operands supported by the assembler. These variants have been enumerated in Tables both MIPS32r2 and MIPS16e ...
Page 115
Macro Assembler V ARIANT ADD rd, rt ADDU rd, rt ADDI rt, immediate ADDIU rt, immediate AND rd, rt ANDI rt, immediate CLO rd CLZ rd MUL rd, rt NEG rd NEGU rd NOR rd, rt NOT rd OR rd, ...
Page 116
HI-TECH C Assembly Language V ARIANT ADDU rx, ry NEG rx SLL rx, sa SRA rx, sa SRL rx, sa SUBU rx, ry Table 4.3: MIPS16e Assembly Instruction Operand Variants Table 4.4: ASPIC32 statement formats Format 1 label: Format 2 ...
Page 117
Macro Assembler Table 4.5: ASPIC32 numbers and bases Radix Binary digits 0 and 1 followed by B Octal digits followed Decimal digits followed nothing ...
Page 118
HI-TECH C Assembly Language bytes, words or sports cars. No special syntax is needed or provided to define the addresses of bits or any other data type, nor will the assembler issue any warnings if a symbol is used in ...
Page 119
Macro Assembler Operator Multiplication * Addition + Subtraction - Division / = or eq Equality > Signed greater than > Signed greater than or equal to < Signed less than < Signed ...
Page 120
HI-TECH C Assembly Language apply. The operators listed may all be freely combined in both constant and relocatable expressions. The HI-TECH linker permits relocation of complex expressions, so the results of expressions involving relocatable identifiers may not be resolved until ...
Page 121
Macro Assembler Note that even though the two blocks of code in the text32 psect are separated by a block in the bss psect, the two text32 psect blocks will be contiguous when loaded by the linker. In other words, ...
Page 122
HI-TECH C Assembly Language Table 4.7: ASPIC32 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 123
Macro Assembler Flag abs bit class=name delta=size global isa limit=address local ovrld pure reloc=boundary size=max space=area with=psect abs defines the current psect as being absolute, i. start at location 0. This does not mean that this module’s ...
Page 124
HI-TECH C Assembly Language A psect defined as local will not be combined with other local psects at link time, even if there are others with the same name. Where there are two local psects in the one module, they ...
Page 125
Macro Assembler Table 4.9: psect isa flag suboptions. Suboption Meaning none (default) Indicates that the psect contains no executable assembly code of any (ISA). This option is usually used by data, bss or const type psects. Indicates that the psect ...
Page 126
HI-TECH C Assembly Language 4.3.10.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.10 used to initialize storage as bytes. The argument is a list ...
Page 127
Macro Assembler 4.3.10.12 DS This directive reserves, but does not initialize, memory locations. The single argument is the number of bytes to be reserved. Examples: alabel ;Reserve 23 bytes of memory xlabel: DS 2+3 ;Reserve 5 bytes of ...
Page 128
HI-TECH C Assembly Language goto denver ELSE goto grapes ENDIF 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 ...
Page 129
Macro Assembler When invoking a macro, the argument list must be comma-separated desired to include a comma (or other delimiter such as a space argument then angle brackets < and > may be used to ...
Page 130
HI-TECH C Assembly Language 4.3.10.17 ALIGN The ALIGN directive aligns whatever is following, data storage or code etc., to the specified boundary in the psect in which the directive is found. The boundary is specifi number following the ...
Page 131
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 132
HI-TECH C Assembly Language Table 4.10: PIC32 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 133
Macro Assembler 4.3.11.2 ASMOPT_OFF From this point onwards in the current module within the current psect instruct the assembler to not perform optimisations even if assembler optimisations have been turned on with the driver option --opt. 4.3.11.3 FORCE_EXTEND Forces the ...
Page 134
HI-TECH C Assembly Language 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.11.9 LIST If the listing was previously turned off using the NOLIST control, the LIST control on its own will turn ...
Page 135
Macro Assembler 4.3.11.14 PAGE PAGE causes a new page to be started in the listing output. A Control-L (form feed) character will also cause a new page when encountered in the source. 4.3.11.15 SPACE The SPACE control will place a ...
Page 136
HI-TECH C Assembly Language 136 Macro Assembler ...
Page 137
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 138
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 139
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 140
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 141
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 142
Operation 5.7.5 -Dclass=delta This option allows the delta value for psects that are members of the specified class to be defined. The delta value should be a number and represents the number of bytes per addressable unit of objects within ...
Page 143
Linker and Utilities or some bank-switched arrangements. In this instance the -G option is used to specify a method for calculating the segment selector. The argument string similar to: A/10h-4h where A represents the load address ...
Page 144
Operation 5.7.14 -I Usually failure to resolve a reference to an undefined symbol is a fatal error. Use of this option will cause undefined symbols to be treated as warnings instead. 5.7.15 -L When the linker produces an output file ...
Page 145
Linker and Utilities -Ppsect=lnkaddr+min/ldaddr+min,psect=lnkaddr/ldaddr, ... There are several variations, but essentially each psect is listed with its desired link and load ad- dresses, and a minimum value. All values may be omitted, in which case a default will apply, depending ...
Page 146
Operation 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 use of ...
Page 147
Linker and Utilities If the bound (boundary) argument is used, the class of psects will start on a multiple of the bound address. This example places the FARCODE class of psects at a multiple of 1000h, but with an upper ...
Page 148
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 149
... 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 150
... C:\DOCUME~1\user\LOCALS~1\Temp\cgta5eHNF.obj conv.obj \ C:\Program Files\HI-TECH Software\pic\std\9.60\lib\pic412-c.lib \ C:\Program Files\HI-TECH Software\pic\std\9.60\lib\pic20--u.lib Object code version is 3.9 Machine type is 16F73 The Linker command line shown is the entire list of options and files that were passed to the linker for the build recorded by this map fi ...
Page 151
Linker and Utilities 5.9.2.2 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 152
... 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 153
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.9.2.3 ...
Page 154
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 155
Linker and Utilities If the psect of a symbol is shown as (abs), this implies that the symbol is not directly associated with a psect as is the case with absolute C variables. Linker-defined symbols showing this as the psect ...
Page 156
Librarian Table 5.2: Librarian command-line options Option -Pwidth -W Table 5.3: Librarian key letter commands 5.10.2 Using the Librarian The librarian program is called LIBR, and the format of commands follows: LIBR options k file.lib file.obj ...
Page 157
Linker and Utilities in their existing order, and will appear after the re-ordered modules. 5.10.3 Examples Here are some examples of usage of the librarian. The following lists the global symbols in the modules a.obj, b.obj and c.obj: LIBR s ...
Page 158
Objtohex LIBR -P80 s file.lib will list all modules in file.lib with their global symbols, with the output formatted for an 80 column printer or display. 5.10.6 Ordering of Libraries The librarian creates libraries with the modules in the order ...
Page 159
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 160
Cref addr1-addr2 where1-where2 +offset All of addr1, addr2, where1, where2 and offset are hex numbers, without the usual H suffix. Such a specification says that the bytes at addr1 through to addr2 inclusive should be summed and the sum placed ...
Page 161
Linker and Utilities Table 5.5: CREF command-line options Option -Fprefix -Hheading -Llen -Ooutfile -Pwidth -Sstoplist -Xprefix 5.12.2 -Hheading The -H option takes a string as an argument which will be used as a header in the listing. The default heading ...
Page 162
... Table 5.6: CROMWELL format types 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 163
Linker and Utilities Table 5.7: CROMWELL command-line options Option -Pname[,architecture -Okey -Ikey - 5.13.1 -Pname[,architecture] The -P options takes a string which is the name of the processor used. CROMWELL may use ...
Page 164
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.13.4 -C This option will attempt to identify if the specified input files are one of the formats ...
Page 165
Linker and Utilities 5.13.9 -E Use this option to tell CROMWELL to ignore any filename extensions that were given. The default extension will be used instead. 5.13. formats that support different endian types, use this option to specify ...
Page 166
Hexmate Merging a bootloader or debug module into a main application at build time Calculating a checksum over a range of program memory and storing its value in program memory or EEPROM Filling unused memory locations with an instruction to ...
Page 167
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 168
Hexmate will use myfile.hex as input, but only process data which is addressed within the range 100h-1FFh (inclusive read from myfile.hex. An address shift can be applied with the specification sOffset . If an address shift is used, ...
Page 169
Linker and Utilities 5.14.1.4 -BREAK This option takes a comma separated list of addresses. If any of these addresses are encountered in the hex file, the current data record will conclude and a new data record will recommence from the ...
Page 170
Hexmate Table 5.10: Hexmate Checksum Algorithm Selection Selector - 5.14.1.6 -FILL The -FILL option is used for filling unused memory locations with a known value. The usage of this option is: ...
Page 171
Linker and Utilities 5.14.1.7 -FIND This option is used to detect and log occurrences of an opcode or partial code sequence. The usage of this option is: -FIND=Findcode[mMask]@Start-End[/Align][w][t”Title”] where: Findcode is the hexadecimal code sequence to search for and is ...
Page 172
Hexmate 5.14.1.8 -FIND...,DELETE If DELETE is used in conjunction with a -FIND option and a sequence is found that matches the -FIND criteria, it will be removed. This function should be used with extreme caution and is not recommended for ...
Page 173
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 disregarded. In ...
Page 174
Hexmate 5.14.1.13 -MASK Use this option to logically AND a memory range with a particular bitmask. This is used to ensure that the unimplemented bits in program words (if any) are left blank. The usage of this option is as ...
Page 175
Linker and Utilities will store hex code 00001h to address EFFEh. Another example: -SERIAL=0000+2@1000+10r5 will store 5 codes, beginning with value 0000 at address 1000h. Subsequent codes will appear at address intervals of +10h and the code value will change ...
Page 176
Hexmate 5.14.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 177
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 178
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 a number corresponding to the configuration register program, then ...
Page 179
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 180
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 181
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 182
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. 182 Library Functions ...
Page 183
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 184
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 185
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 186
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 187
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 188
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 189
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 190
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 191
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 192
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 193
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 194
Return Value The return value is the character pointer passed as the sole argument. 194 Library Functions ...
Page 195
Library Functions COS Synopsis #include <math.h> double cos (double f) Description This function yields the cosine of its argument, which is an angle in radians. The cosine is calculated by expansion of a polynomial series approximation. Example #include <math.h> #include ...
Page 196
COSH, SINH, TANH Synopsis #include <math.h> double cosh (double f) double sinh (double f) double tanh (double f) Description These functions are the implement hyperbolic equivalents of the trigonometric functions; cos(), sin() and tan(). Example #include <stdio.h> #include <math.h> void ...
Page 197
Library Functions CPUTS Synopsis #include <conio.h> void cputs (const char * s) Description The cputs() function writes its argument string to the console, outputting carriage returns before each newline in the string. It calls putch() repeatedly hosted system ...
Page 198
CTIME Synopsis #include <time.h> char * ctime (time_t * t) Description The ctime() function converts the time in seconds pointed to by its argument to a string of the same form as described for asctime(). Thus the example program prints ...
Page 199
Library Functions DIV Synopsis #include <stdlib.h> div_t div (int numer, int demon) Description The div() function computes the quotient and remainder of the numerator divided by the denomina- tor. Example #include <stdlib.h> #include <stdio.h> void main (void) { div_t x; ...
Page 200
EVAL_POLY Synopsis #include <math.h> double eval_poly (double x, const double * d, int n) Description The eval_poly() function evaluates a polynomial, whose coefficients are contained in the array for example x*x*d2 + x*d1 + d0. ...