Home

MPLAB® Assembler, Linker and Utilities for PIC32 MCUs User's Guide

1. esee 46 listing Ihs width AAA 45 listing Ihs width2 AAA 45 listing rhs width AA 45 Bt EE 54 LMA uie AE 114 124 132 Load Memory Address c oooocccccccnccccccccccno 114 124 132 LOADADDR WEE 132 Loading Input Files A 133 Local Syrribols teet te 65 Location Counter cuina 128 Location Counter Directives align ciega a o a 76 i ES 76 el re KE E e te eet eue 76 SkiD EE 77 Space e nU aee 77 De 77 M cUm 110 MUSUTIX eiit eet etre end 127 Map iiit tO RR EE 110 Map File aia 94 Mapping Sections ccceesceeeceeseeeeeeeseeeeeeesreteaee 135 MAX oa it 132 MD Reni RD 47 MEMORY Commande 117 eese cedes t io cei a ruo 117 DS51833A page 216 2009 Microchip Technology Inc p E 117 EE EES 117 117 Rum eege ee 117 l 117 o MS 117 MIN cuidara tan 132 A eto oe reote a cies 52 Modification Options Archiver Librarian A A AI 144 A 144 Quis EE 144 fuese e eR Eee AER eee 144 ebben Geet 144 esti ON ce eto e A AE 144 Ninus ulmo xn feo re Macri c TE 144 0 EE EE 144 MENSUEL EI EM 144 EE 144 EE E 144 JEE 144 UE 144 Maier etc ANE ee Enn e EE PERDER 144 MPLAB ASM32 enne 7 MEA geed id 7 MPLAB IDE niet Ss 7 MPLAB IDE Build Options Dialog MPLAB PIC32 Assembler Tab 10 MPLAB PIC32 C Compiler Tab 11 MPLAB PIC32 Linker Tab 12 PIC32 Suite Tab
2. 101 DSEQT une ao 123 E Empty Expressions AN 61 Seet Lt le DEE ENTRY EE Escape Characters Evaluation iiie atom fer eret tu Example See Sanaa SINE EXCLUDE FILE Executable Section Expression Syntax and Operation Assembler t aaa 61 EXPIOSSIONS E 61 Expressions Empty ssee 61 Expressions Integer eese 61 EXTERN iia a aa a 126 F fatal warnings sem 46 File Commands Linker Scripts GROUP sot op 115 INCEUDE eet e hes 114 INPUT oo te es 115 OUTPUT ite iet etin cre rete css 115 SEARCH DIR eee 115 HR ARTE 115 File Extensions Assembler nidi iet 19 92 En Ker insu ete ete cse tp EI 92 Files LD Vide 92 Linker Output 94 Linker Sctipt i niet 92 LISTING ii eie DD 21 NEEN o a E E EE EE 94 Object ceste ies 21 92 illt 19 Floating Point NUMDEES AAA 57 FORCE COMMON ALLOCATION 126 G Garbage Collection ooooocnncnnncnnnnnnnccncccnocnnanccnannnn 132 go Sectlohs i e dee tide c E e ERE ead 102 Global Symbols 5 ais 136 GPRS uni Aa 53 GROUP ac ica macte tote po te 115 H Header ici I I 21 Heap Allocation esee 137 Se EE 46 108 Hexadecimal to Decimal Conversion 186 High level Source esee 21 40 l DE 48 e PT MEE 103 INCLUDE eibi 114 Include Files Directives INCL LE 83 Rive Te 5 3 B nS ulnis 84 ut deer 62 I
3. sseeeeeess 153 Options pic32 nm A 149 Seed 149 Bubosunueseeqen esee a 149 Saile EE 149 defined only A 149 extern only ertt 149 peus etum e oe ea 149 OMS unid 149 ie 149 SU DEE 149 EE 149 line NUM erS c ccccoonooccccccccnanncccncnnnnnnnccnnncnna nono 149 d 150 DUTTIeflG S0ort ene 150 DEE 149 SE Ee 150 D EE 150 portability ta 150 SS Te etti 150 print file name cessere 149 ll 150 Edobcrc heer 150 reverse sort coccccccccccconocinonnnn anna cria 150 SE 150 SIZO SOM n tee nec EL Pe Lee s 150 Seed 150 p E EP PM MEM 149 undefined only esee 149 A E E ccs E AT slaset Vaya reuse teste seid textes 150 EE 150 zai 150 Options pic32 objdump A geste de ite ie mi en tite 151 zall header 2 es 153 archive header sss 151 RE 152 e DEE 152 debugging A 152 2009 Microchip Technology Inc DS51833A page 217 32 Bit Assembler Linker and Utilities User s Guide disassemble eeeeeeeseeeet 152 dp 157 disassemble all sees 152 usse etse p i MIRROR OD ME 157 Oleassembler optionms 152 Dissert ri IUE TR 157 poste tete ener E dens 152 preserve dates A 157 file header sss 152 SBnihansunlev xcu 157 le start Context 152
4. 2009 Microchip Technology Inc DS51833A page 21 32 Bit Assembler Linker and Utilities User s Guide 1 4 86 SYMBOL TABLE A symbol table is present if the as option is given to the assembler Both a list of defined and undefined symbols will be given The defined symbols will have the format DEFINED SYMBOLS filename line gt section addr symbol For example DEFINED SYMBOLS foo S 79 text 00000000 main foo S 107 text 00000014 mPORTAClearBits The undefined symbols will have the format UNDEFINED SYMBOLS lt symbol gt For example UNDEFINED SYMBOLS WDTCON WDTCONCLR EXAMPLE 1 2 SAMPLE ASSEMBLER LISTING FILE GAS LISTING foo s page 1 1 H 1 foo S 2 1 lt built in gt d nolist 0 0 3 list 4 5 Hdefine IOPORT BIT 7 1 lt lt 7 6 8 global baz define all global symbols here 9 10 define which section for example text 11 does this portion of code resides in 12 Typically all of your code will reside in the text section as shown 14 15 text 16 17 This is important for an assembly programmer 18 This directive tells the assembler not to 19 optimize the order of the instructions 20 as well as not to insert nop instructions 21 after jumps and branches 22 23 Set noreorder 24 25 ent baz directive that marks symbol baz as 26 a function in ELF output 27 28 29 baz 30 31 Call function to
5. contains a descriptive list of the errors warnings and messages generated by the 32 bit assembler Appendix C Linker Errors Warnings contains a descriptive list of the errors and warnings generated by the 32 bit linker Appendix D Useful Tables lists some useful tables the ASCII character set and hexadecimal to decimal conversion Appendix E GNU Free Documentation License details the license requirements for using the GNU language tools DS51833A page 2 O 2009 Microchip Technology Inc CONVENTIONS USED IN THIS GUIDE Preface The following conventions may appear in this documentation DOCUMENTATION CONVENTIONS Description Represents Examples Arial font Italic characters Referenced books MPLAB IDE User s Guide Emphasized text is the only compiler Initial caps A window the Output window A dialog the Settings dialog A menu selection select Enable Programmer Quotes A field name in a window or Save project before build dialog Underlined italic text with A menu path File gt Save right angle bracket Bold characters A dialog button Click OK A tab Click the Power tab Text in angle brackets lt gt A key on the keyboard Press lt Enter gt lt F1 gt Courier font Plain Courier Sample source code define START Filenames autoexec bat File paths e mec18 h Keywords asm
6. Note Command line options and filename extensions are case sensitive To pass an assembler option from the compilation driver to the assembler use the Wa option option The option argument should not contain white space EXAMPLE 3 1 EXAMPLE COMPILATION DRIVER COMMAND LINE pic32 gcc mprocessor 32MX360F512L I include ASMfile S o ASMfile o DMYMACRO 1 Wa ah ASMfile lst For additional information on the compilation driver see the MPLAB C Compiler for PIC32 MCUS User s Guide DS51686 Note Tousethe pic32 gcc compilation driver from MPLAB IDE be sure to select the Microchip PIC32 C Compiler Toolsuite for your project DS51833A page 34 2009 Microchip Technology Inc Assembler Command Line Interface 3 4 OPTIONS THAT MODIFY THE LISTING OUTPUT The following options are used to control the listing output A listing file is helpful for debugging and general analysis of code operation Use the following options to construct a listing file with information that you find useful e a suboption file listing lhs width num listing 1hs width2 num listing rhs width num listing cont lines num 3 4 1 a suboption file The a option enables listing output The a option supports the following sub options to further control what is included in the assembly listing ac Omit false conditionals ad Omit debugging directives ah Include high level source al Include asse
7. EXAMPLE 3 5 LISTING FILE GENERATED WITH alh COMMAND LINE OPTION GAS LISTING tempfile s page 1 E Section mdebug abi32 2 previous 3 Section debug abbrev Gprogbits 4 Ldebug_abbrevo 5 Section debug info Gprogbits 6 Ldebug_info0 7 section debug line eprogbits 8 Ldebug Linen 9 0000 34000000 text 11 align2 12 globlmain 13 LFBO 14 file 1 src test c 1 src test c Hinclude lt p32xxxx h gt 2 src test c volatile unsigned int testval 3 src test c kx 4 src test c int 5 src test c main void 6 src test c xxx 15 loc 160 16 Setnomips16 17 entmain 18 main 19 frame sp 0 31 vars 0 regs 0 0 args 0 gp 0 20 mask0x00000000 0 21 fmask0x00000000 0 22 setnoreorder 23 Setnomacro 24 7 src test c ee testval 1 25 soe 1 70 26 0000 0000848F lw 4 gp rel testval 28 8 src test c ek return 0 9 src test c week 27 loc 19 0 28 0004 21100000 move 2 0 29 loc T 7 0 30 0008 01008324 addiu 3 4 1 31 000c 000083AF sw 3 gp rel testval 28 32 loc 19 0 33 0010 0800E003 3 31 34 0014 00000000 nop DS51833A page 40 2009 Microchip Technology Inc Assembler Command Line Interface 35 36 Setmacro 37 Setreorder 38 endmain 39 LFEO 40 Sizemain main 41 42 commtestval 4 4 3 4 1 4 al alrequests an assembly listing This sub option may be used with other sub options See the other examples in this section
8. Interrupt Handler A routine that processes special code when an interrupt occurs Interrupt Request An event which causes the processor to temporarily suspend normal instruction exe cution and to start executing an interrupt handler routine Some processors have several interrupt request events allowing different priority interrupts Interrupt Service Routine ALUSO C18 C30 A function that handles an interrupt IDE User generated code that is entered when an interrupt occurs The location of the code in program memory will usually depend on the type of interrupt that has occurred Interrupt Vector Address of an interrupt service routine or interrupt handler IRQ See Interrupt Request ISO See International Organization for Standardization ISR See Interrupt Service Routine DS51833A page 200 O 2009 Microchip Technology Inc Glossary L value An expression that refers to an object that can be examined and or modified An I value expression is used on the left hand side of an assignment Latency The time between an event and its response Librarian See Archiver Library See Archive Linker A language tool that combines object files and libraries to create executable code resolving references from one module to another Linker Script Files Linker script files are the command files of a linker They define linker options and describe available memory on the target platform Listing Direc
9. nodefaultlibs nostartfiles nostdlib output file o file relocatable r i Ur retain symbols file file section start sectionname org script file T file strip all s strip debug S Tbss address Tdata address Ttext address undefined symbol u symbol no undefined wrap symbol 9 4 1 archives start group archives end group Start and end a group The archives should be a list of archive files They may be either explicit file names or 1 options The specified archives are searched repeatedly until no new undefined references are created Normally an archive is searched only once in the order that it is specified on the command line If a symbol in that archive is needed to resolve an undefined symbol referred to by an object in an archive that appears later on the command line the linker would not be able to resolve that reference By grouping the archives they will all be searched repeatedly until all possible references are resolved Using this option has a significant performance cost It is best to use it only when there are unavoidable circular references between two or more archives 9 4 2 d dc dp Force common symbols to be defined Assign space to common symbols even if a relocatable output file is specified with 1 The script command FORCE COMMON ALLOCATION has the same effect 2009 Microchip Technology Inc DS5183
10. 2009 Microchip Technology Inc e MICROCHIP MPLAB Assembler Linker and Utilities for PIC32 MCUs User s Guide Note the following details of the code protection feature on Microchip devices Microchip products meet the specification contained in their particular Microchip Data Sheet Microchip believes that its family of products is one of the most secure families of its kind on the market today when used in the intended manner and under normal conditions There are dishonest and possibly illegal methods used to breach the code protection feature All of these methods to our knowledge require using the Microchip products in a manner outside the operating specifications contained in Microchip s Data Sheets Most likely the person doing so is engaged in theft of intellectual property Microchip is willing to work with the customer who is concerned about the integrity of their code Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code Code protection does not mean that we are guaranteeing the product as unbreakable Code protection is constantly evolving We at Microchip are committed to continuously improving the code protection features of our products Attempts to break Microchip s code protection feature may be a violation of the Digital Millennium Copyright Act If such acts allow unauthorized access to your software or other copyrighted work you may have a
11. A value may be assigned to a symbol in a linker script This will define the symbol as a global symbol 10 6 3 1 SIMPLE ASSIGNMENTS A symbol may be assigned using any of the C assignment operators symbol expression symbol expression symbol expression symbol expression symbol expression symbol expression symbol expression symbol amp expression symbol expression The first case will define symbol to the value of expression In the other cases symbol must already be defined and the value will be adjusted accordingly The special symbol name indicates the location counter This symbol may only be used within a SECTIONS command The semicolon after expression is required Expressions are defined in Section 10 7 Expressions in Linker Scripts Symbol assignments may appear as commands in their own right or as statements within a SECTIONS command or as part of an output section description in a SECTIONS command The section of the symbol will be set from the section of the expression for more information see Section 10 7 6 The Section of an Expression Here is an example showing the three different places that symbol assignments may be used floating point 0 SECTIONS text ORIGIN kseg0 program mem d text begin text stub text text end gt kseg0 program mem 0 _bdata 3 3 data data In this example t
12. CUSTOMER SUPPORT Users of Microchip products can receive assistance through several channels Distributor or Representative Local Sales Office Field Application Engineer FAE Technical Support Customers should contact their distributor representative or field application engineer FAE for support Local sales offices are also available to help customers A listing of sales offices and locations is included in the back of this document Technical support is available through the web site at http support microchip com q eid DS51833A page 6 O 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE 32 Bit Language Tools and MPLAB IDE INTRODUCTION The MPLAB Assembler for PIC32 MCUs formerly MPLAB ASM32 the MPLAB Object Linker for PIC32 MCUs formerly MPLAB LINK32 and 32 bit utilities including the MPLAB Archiver Librarian for PIC32 MCUs formerly MPLAB LIB32 may be used together under MPLAB IDE to provide GUI development of application code for the PIC32MX MCU family of devices The operation of these language tools with MPLAB IDE is discussed here Additionally MPLAB C Compiler for PIC32 MCUs formerly MPLAB C32 is available for free as a lite or standard evalution version with MPLAB IDE or for purchase as a standard version Topics covered in this chapter MPLAB IDE and Tools Installatio
13. DIV instruction with zero register as RT Division by zero This expression attempts to divide by zero Check the operands E Extended instruction in delay slot A MIPS16e extended instruction may not be placed in a jump delay slot as it will cause undefined behavior Move the instruction out of the delay slot F Floating point constant too large The hexadecimal encoding of a floating point constant is too large Make sure that your floating point value is encoded correctly in the 32 bit or 64 bit IEEE format Ignoring changed section attributes for name If section attributes are specified the second time the assembler sees a particular sec tion then they should be the same as the first time the assembler saw the section attri butes The assembler assumes that the first set of section attributes was correct Ignoring changed section entity size for name The section entity size should be the same the second time the assembler sees a par ticular section The assembler assumes that the section entity size the first time it saw the section was correct Ignoring changed section type for name The section type should be the same the second time the assembler sees a particular section The assembler assumes that the section type the first time it saw the section was correct DS51833A page 176 2009 Microchip Technology Inc Assembler Errors Warnings Messages Ignoring incorrect section type for name When switching
14. bend The run time initialization code for use with a program generated with this linker script would include a function to copy the initialized data from the ROM image to its run time address The initialization function could take advantage of the symbols defined by the linker script Writing such a function would rarely be necessary however These functions are pro vided by the C compiler s start up and initialization code See the MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 for more information on the start up code provided with the compiler The assembly source code for the start up routine is pro vided in pic32 libs c startup crto s 10 6 5 12 OUTPUT SECTION REGION A section can be assigned to a previously defined region of memory by using gt region See Section 10 6 4 MEMORY Command Here is a simple example MEMORY rom ORIGIN 0x1000 LENGTH 0x1000 SECTIONS ROM text gt rom DS51833A page 124 2009 Microchip Technology Inc Linker Scripts 10 6 5 13 OUTPUT SECTION FILL A fill pattern can be set for an entire section by using fillexp fillexp as an expression Any otherwise unspecified regions of memory within the output section for example gaps left due to the required alignment of input sections will be filled with the two Least Significant Bytes of the value repeated as necessary The fill value can also be changed with a FILL command in the
15. Input sections that match the wildcard pattern mipsi6 fn are collected and mapped into the output section Input sections that match the wildcard pattern mips16 cal1 are collected and mapped into the output section 11 3 2 Assigning Output Sections to Regions Once the sizes of all output sections are known they are assigned to memory regions Normally a region is specified in the output section definition If a region is not specified the first defined memory region will be used Memory regions are filled sequentially from lower to higher addresses in the same order that sections appear in the section map A location counter unique to each region keeps track of the next available memory location There are two conditions which may cause gaps in the allocation of memory within a region 1 The section map specifies an absolute address for an output section or 2 The output section has a particular alignment requirement In either case any intervening memory between the current location counter and the absolute or aligned address is skipped The exact address of all items allocated in memory may be determined from the link map file For a section containing an aligned memory block with the a1igned attribute in C or align directive in assembly the section must also be aligned to the same or greater alignment value If two or more input sections have different alignment require ments the largest alignment is used for the
16. MEMORY ksegO program mem rx ksegO boot mem exception mem ksegl boot mem debug exec mem config3 config2 configl configO ksegi data mem sfrs we ECTIONS m DD w x ORIGIN 0x9D000000 ORIGIN 0x9FC00490 ORIGIN 0x9FC01000 ORIGIN 0xBFC00000 ORIGIN 0xBFC02000 ORIGIN OxBFCO2FFO ORIGIN OxBFCO2FFA4 ORIGIN OxBFCO2FFS8 ORIGIN OxBFCO2FFC ORIGIN 0xA0000000 ORIGIN 0xBF800000 text ORIGIN kseg0 program mem text begin text stub mipsl6 fn mips16 call text end text gt kseg0 program mem 0 data data begin data data K datal I gnu linkonce d EP gnu linkonce d personality ksegi data mem AT kseg0 program mem bss dynbss bss bss COMMON ALIGN 32 8 gt ksegl_data_mem Stack ALIGN 4 min stack size kseg1 data mem ENGTH 0x8000 ENGTH 0x970 LENGTH 0x1000 ENGTH 0x490 LENGTH OxFFO j ENGTH 0x4 ENGTH 0x4 LENGTH 0x4 ENGTH 0x4 LENGTH 0x2000 LENGTH 0x100000 O 2009 Microchip Technology Inc DS51833A page 93 32 Bit Assembler Linker and Utilities User s Guide 8 4 4 Linker Output Files By default the name of the linker output binary file is a out You can override the default name by specifying the o option on the command line MPLAB IDE s project manager uses t
17. 3 1 INTRODUCTION MPLAB Assembler for PIC32 MCUs pic32 as may be used on the host PC s command line interface eg cmd exe as well as with MPLAB IDE s project manager MPLAB IDE s project manager will automatically call the assembler via the pic32 gcc compilation driver when building a project Many of the commonly used options listed here are available as checkboxes on the IDE s project build options dialog However for a more advanced option you may have to specify the option in the Alternate Settings field of the dialog After you build a project in MPLAB IDE the Output window shows the options passed to the assembler Topics covered in this chapter are Assembler Interface Syntax Compilation Driver Interface Syntax Options that Modify the Listing Output Options that Control Informational Output Options that Control Output File Creation Assembler Symbol Definition and Search Path Options Compilation Driver and Preprocessor Options 3 2 ASSEMBLER INTERFACE SYNTAX The assembler command line may contain options and file names Options may appear in any order and may be before after or between file names The order of file names determines the order of assembly pic32 as options sourcefiles two hyphens by itself names the standard input file explicitly as one of the files for the assembler to translate Except for any command line argument that begins with a hyphen is an option Each opti
18. 3 4 1 5 am am expands macros in a listing Example 3 6 shows a listing where the am option was not used Example 3 7 shows a listing for the same source where the am option was used EXAMPLE 3 6 LISTING FILE GENERATED WITH a1 COMMAND LINE OPTION GAS LISTING foo s page 1 ab A REOS 2 1 lt built in gt 1 macro sum from 0 to 5 0 0 2 long from 3 if Nto M rom 4 sum from 1 to 5 endif 6 endm 7 8 data 9 0000 00000000 long 0 10 0004 0A000000 sum 10 14 10 0B000000 10 0C000000 10 0D000000 10 0E000000 11 0018 00000000 long 0 2009 Microchip Technology Inc DS51833A page 41 32 Bit Assembler Linker and Utilities User s Guide EXAMPLE 3 7 LISTING FILE GENERATED WITH alm COMMAND LINE OPTION GAS LISTING foo s page 1 1 H 1 foo S 2 d 1 lt built in gt 1 macro sum from 0 to 5 0 0 2 long from 3 IIR Nto M rom 4 sum from 1 to 5 endif 6 endm 7 8 data 9 0000 00000000 long 0 10 sum 10 14 10 0004 0A000000 long 10 10 if 14 10 10 gt gum 10 1 14 10 0008 0B000000 gt gt long 10 1 10 gt gt if 14 10 1 10 gt gt sum 10 1 1 14 10 000c 0C000000 gt gt gt Long 10 1 1 10 gt gt gt if 14 10 1 1 10 gt gt gt sum 10 1 1 1 14 10 0010 0D000000 gt gt gt gt long 10 1 1 1 10 gt gt gt gt if 14 10 1 1 1 10 gt gt gt gt sum 10 1 1 1 1 14 10 0014 0E000000 gt gt gt gt gt long 10
19. 39 0331 466781 Netherlands Drunen Tel 31 416 690399 Fax 31 416 690340 Spain Madrid Tel 34 91 708 08 90 Fax 34 91 708 08 91 UK Wokingham Tel 44 118 921 5869 Fax 44 118 921 5820 03 26 09 DS51833A page 222 O 2009 Microchip Technology Inc
20. China Shenzhen Tel 86 755 8203 2660 Fax 86 755 8203 1760 China Wuhan Tel 86 27 5980 5300 Fax 86 27 5980 5118 China Xiamen Tel 86 592 2388138 Fax 86 592 2388130 China Xian Tel 86 29 8833 7252 Fax 86 29 8833 7256 China Zhuhai Tel 86 756 3210040 Fax 86 756 3210049 ASIA PACIFIC India Bangalore Tel 91 80 3090 4444 Fax 91 80 3090 4080 India New Delhi Tel 91 11 4160 8631 Fax 91 11 4160 8632 India Pune Tel 91 20 2566 1512 Fax 91 20 2566 1513 Japan Yokohama Tel 81 45 471 6166 Fax 81 45 471 6122 Korea Daegu Tel 82 53 744 4301 Fax 82 53 744 4302 Korea Seoul Tel 82 2 554 7200 Fax 82 2 558 5932 or 82 2 558 5934 Malaysia Kuala Lumpur Tel 60 3 6201 9857 Fax 60 3 6201 9859 Malaysia Penang Tel 60 4 227 8870 Fax 60 4 227 4068 Philippines Manila Tel 63 2 634 9065 Fax 63 2 634 9069 Singapore Tel 65 6334 8870 Fax 65 6334 8850 Taiwan Hsin Chu Tel 886 3 6578 300 Fax 886 3 6578 370 Taiwan Kaohsiung Tel 886 7 536 4818 Fax 886 7 536 4803 Taiwan Taipei Tel 886 2 2500 6610 Fax 886 2 2508 0102 Thailand Bangkok Tel 66 2 694 1351 Fax 66 2 694 1350 EUROPE Austria Wels Tel 43 7242 2244 39 Fax 43 7242 2244 393 Denmark Copenhagen Tel 45 4450 2828 Fax 45 4485 2829 France Paris Tel 33 1 69 53 63 20 Fax 33 1 69 30 90 79 Germany Munich Tel 49 89 627 144 0 Fax 49 89 627 144 44 Italy Milan Tel 39 0331 742611 Fax
21. SUM Xfrom 1 0 endif endm With that definition sum 0 5 is equivalent to this assembly input long 0 long long long long long UD WN H 2009 Microchip Technology Inc DS51833A page 81 32 Bit Assembler Linker and Utilities User s Guide macro macname macro macname macargs Begin the definition of a macro called macname If your macro definition requires argu ments specify their names after the macro name separated by commas or spaces You can supply a default value for any macro argument by following the name with deflt For example these are all valid macro statements macro comm Begin the definition of a macro called comm which takes no arguments e macro plusi p pl macro plusl p pl Either statement begins the definition of a macro called p1us1 which takes two arguments within the macro definition write Np or p1 to evaluate the arguments e macro reserve str pl 0 p2 Begin the definition of a macro called reserve str with two arguments The first argument has a default value but not the second After the definition is com plete you can call the macro either as reserve str a b with p1 evaluating to a and p2 evaluating to b or as reserve str b with p1 evaluating as the default in this case 0 and p2 evaluating to b When you call a macro you can specify the argument values either by position or by keyword For example SUM 9 17 is equivalent t
22. check the settings below to ensure that the language tools are properly recognized under MPLAB IDE 1 From the MPLAB IDE menu bar select Project gt Set Language Tool Locations to open a dialog to set check language tool executable location FIGURE 1 SET LANGUAGE TOOL LOCATIONS Set Language Tool Locations Registered Tools Microchip 45M30 Toolsuite A Microchip C17 Toolsuite Microchip C18 Toolsuite Microchip C30 Toolsuite Microchip MPASM Toolsuite Microchip PIC32 C Compiler T oolsuite Executables MPLAB 4SM32 Assembler pic32 as exe MPLAB C32 C Compiler pic32 gcc exe MPLAB LIB32 Object Librarian Archiver pic32 ar exe MPLAB LINK32 Object Linker pic32 ld exe v FF Location 2 Inthe dialog under Registered Tools select Microchip PIC32 C Compiler Tool suite Click the to expand 3 Select Executables Click the to expand 4 Select MPLAB C32 Compiler pic32 gcc exe Under Location a path to the executable file should be displayed If no path is displayed enter one or browse to the location of this file The default location is listed in Section MPLAB IDE and Tools Installation 5 Select MPLAB ASM32 Assembler pic32 as exe Under Location a path to the executable file should be displayed If no path is displayed enter one or browse to the location of this file The default location is listed in Section MPLAB IDE and Too
23. each MEMORY region maps to an address segment on the PIC32 MCU e g kseg0 kseg1 See Section 3 of the PIC32MX Family Reference Manual DS61115 for a full description of the user kernel address segments The table below shows how the default linker script maps standard sections to MEMORY regions PIC32 RESERVED STANDARD SECTION NAMES IN DEFAULT LINKER SCRIPT Section Name Generated by Final Location Default Linker Script MEMORY Region reset Reset handler Executable boot code segment kseg0 boot mem bev excpt BEV Exception handler Executable boot code segment ksegO boot mem app excpt General Exception handler Executable boot code segment ksegO boot mem vector n Interrupt Vector n Executable boot code segment ksegO boot mem startup C start up code Executable boot code segment kseg0_boot_mem text Compiler or assembler generated Executable code segment kseg0_program mem instructions rodata Strings and C data declared const Read only data segment kseg0 program mem Sdata2 Small initialized constant global Read only data segment kseg0 program mem and static data sbss2 Uninitialized constant global and Read only data segment kseg0_program_mem static data i e variables which will always be zero data Variables gt n bytes compiled Gn Initialized data segment ksegi data mem amp with an initial
24. gt gt endif T2 endif purgem name Undefine the macro name so that later uses of the string will not be expanded See macro directive rept count endr Repeat the sequence of lines between the rept directive and the next endr direc tive count times For example assembling rept 3 long 0 endr is equivalent to assembling long O0 long 0 long 0 7 10 DIRECTIVES THAT INCLUDE OTHER FILES Directives that include data from other files are e incbin file skip count include file incbin file skip countl The incbin directive includes ile verbatim at the current location The file is assumed to contain binary data The search paths used can be specified with the I command line option see Chapter 3 Assembler Command Line Interface Quotation marks are required around ile The skip argument skips a number of bytes from the start of the file The count argument indicates the maximum number of bytes to read Note that the data is not aligned in any way so itis the user s responsibility to make sure that proper alignment is provided both before and after the incbin directive 2009 Microchip Technology Inc DS51833A page 83 32 Bit Assembler Linker and Utilities User s Guide include file Provides a way to include supporting files at specified points in your source code The code is assembled as if it followed the point of the include When the end of
25. s Strip all symbols Omit all symbol information from the output file 9 4 18 strip debug S Strip debugging symbols Omit debugger symbol information but not all symbols from the output file 9 4 19 Tbss address Set address of bss section Use address as the starting address for the bss segment of the output file address must be a single hexadecimal integer for compatibility with other linkers you may omit the leading Ox usually associated with hexadecimal values Normally the address of this section is specified in a linker script 9 4 20 Tdata address Set address of data section Use address as the starting address for the data segment of the output file address must be a single hexadecimal integer for compatibility with other linkers you may omit the leading Ox usually associated with hexadecimal values Normally the address of this section is specified in a linker script 9 4 21 Ttext address Set address of text section Use address as the starting address for the text segment of the output file address must be a single hexadecimal integer for compatibility with other linkers you may omit the leading Ox usually associated with hexadecimal values Normally the address of this section is specified in a linker script 9 4 22 undefined symbol u symbol Start with undefined reference to symbol Force symbol to be entered in the output file as an undefined symbol Doing t
26. to match any lowercase letter N quotes the following character When a file name is matched with a wildcard the wildcard characters will not match a character used to separate directory names on UNIX A pattern consisting of a single character is an exception it will always match any file name whether it contains a or not In a section name the wildcard characters will match a character File name wildcard patterns only match files which are explicitly specified on the command line or in an INPUT command The linker does not search directories to expand wildcards If a file name matches more than one wildcard pattern or if a file name appears explicitly and is also matched by a wildcard pattern the linker will use the first match in the linker script For example this sequence of input section descriptions is probably in error because the data o rule will not be used data data datal data o data Normally the linker will place files and sections matched by wildcards in the order in which they are seen during the link This can be changed by using the SORT keyword which appears before a wildcard pattern in parentheses e g SORT text When the SORT keyword is used the linker will sort the files or sections into ascending order by name before placing them in the output file To verify where the input sections are going use the M linker option to generate a map file The map file shows precisely
27. void 6 src test c xx 15 loc 16 0 16 Setnomips16 17 entmain 18 main 19 framesfp 8 31 vars 0 regs 1 0 args 0 gp O 20 mask0x40000000 8 21 fmask0x00000000 0 22 Setnoreorder 23 Setnomacro 24 25 0000 F8FFBD27 addiu sp sp 8 26 LCFIO 27 0004 0000BEAF sw fp O sp 28 LCFI1 29 0008 21F0A003 move fp sp 30 LCFI2 7 src test c aK KK testval 1 31 soc 1 720 32 000c 0000828F lw 2 gp rel testval 28 33 0010 01004224 addiu 2 2 1 34 0014 000082AF sw 2 gp rel testval 28 8 src test c kk KK return 0 35 loc 180 36 0018 21100000 move 2 0 9 src test c wee 37 loc 19 0 38 001c 21E8C003 move sp fp 39 0020 0000BE8F lw fp O Sp 40 0024 0800BD27 addiu sp sp 8 41 0028 0800E003 j 31 42 002c 00000000 nop DS51833A page 38 O 2009 Microchip Technology Inc Assembler Command Line Interface 43 44 Setmacro 45 Setreorder 46 endmain 47 LFEO 49 50 commtestval 4 4 88 Letexto 2009 Microchip Technology Inc DS51833A page 39 32 Bit Assembler Linker and Utilities User s Guide 3 4 1 3 ah ah requests a high level language listing High level listings require that the assembly source code was generated by a compiler a debugging option like g was given to the compiler and that assembly listings a1 also be requested a1 requests an output program assembly listing Example 3 5 shows a listing that was generated using the alh command line option
28. 0x8 sizeMlibc a default general exception handler o 0x9d0005bc general exception handler text bootstrap exception handler 0x8 size libc a default bootstrap exception handler o 0x9d0005c4 0x9d0005c4 text on reset 0x9d0005cc 0x9d0005cc text on bootstrap bootstrap exception handler 0x8 size libc a default on reset o on reset 0x9d0005d4 0x8 size libc a default on bootstrap o 0x9d0005d4 on bootstrap text 0x9d0005dc 0x18 size libc a default nmi handler o 0x9d0005dc nmi handler Sdata 0xa00000f4 0x4 load address 0x9d000780 0xa00000f4 Sdata begin heap 0xa0000208 0x800 0xa0000208 heap 0xa0000a08 min heap size fill 0xa0000208 0x800 00 Stack 0xa0000a08 0x400 0xa0000e08 min stack size fill 0xa0000a08 0x400 00 ramfunc 0xa0001000 OxO load address 0x9d000784 0xa0001000 ramfunc begin ramfunc ramfunc 0xa0001000 ALIGN 0x4 0xa0008000 Stack ramfunc length gt 0x0 ramfunc begin 0x4 0xa0008000 OUTPUT test 2 elf elf32 tradlittlemips Cross Reference Table File proc 32MX360F512L1processor o size libc a default nmi handler o size libc a general exception o intermediate test o size crt0 o foo intermediatelcobject o Symbol PORTE main intermediatelcobject o size crt0 o mylabel intermediatelasmobject o funct intermediatelcobject o O 2009 Microchip Technology Inc DS51833A page 97 32 Bit Assembler Linker and Utilities User s Guide NOT
29. 1 1 1 1 10 gt gt gt gt gt if 14 10 1 1 1 1 10 gt gt gt gt gt sum 10 1 1 1 1 1 14 10 gt gt gt gt gt endif 10 gt gt gt gt endif 10 gt gt gt endif 10 gt gt endif 10 gt endif 11 0018 00000000 long 0 Note gt signifies expanded macro instructions DS51833A page 42 2009 Microchip Technology Inc Assembler Command Line Interface 3 4 1 6 an an turns off all forms processing that would be performed by the listing directives psize eject title and sbtt1 Example 3 8 shows a listing where the an option was not used Example 3 9 shows a listing for the same source where the an option was used EXAMPLE 3 8 LISTING FILE GENERATED WITH a1 COMMAND LINE OPTION GAS LISTING foo s page 1 User s Guide Example Listing Options 1 1 foo S 2 1 lt built in gt 1 text 0 0 2 title User s Guide Example 3 Sbttl Listing Options GAS LISTING foo s page 2 User s Guide Example Listing Options 4 psize 10 5 6 0000 01001A3C lui k0 1 7 0004 02001A3C lui k0 2 8 0008 03001A3C lui k0 3 9 eject GAS LISTING foo s page 3 User s Guide Example Listing Options 10 000c 04001A3C lui k0 4 11 0010 05001A3C lui k0 5 EXAMPLE 3 9 LISTING FILE GENERATED WITH aln COMMAND LINE OPTION 1 1 foo S 2 1 lt built in gt 1 text 0 0 2 title User s Guide Example 3 Sbttl Listing Options 4 psize 10 5 6 0000 01001A3C l
30. 11 3 LINKER ALLOCATION Linker allocation is controlled by the linker script and proceeds in two steps 1 Mapping Input Sections to Output Sections 2 Assigning Output Sections to Regions Input sections which appear in the linker script are assigned to specific memory regions in the target devices Addresses within a memory region are allocated sequentially beginning with the lowest address and growing upwards 11 3 14 Mapping Input Sections to Output Sections Input sections are grouped and mapped into output sections according to the section map When an output section contains several different input sections the exact ordering of input sections may be important For example consider the following output section definition Code Sections text ORIGIN kseg0 program mem text stub text gnu linkonce t mipsi6 fn mipsi6 call kseg0 program mem 0 Here the output section named text is defined Notice that the contents of this section are specified within curly braces After the closing brace gt kseg0 program mem indicates that this output section should be assigned to memory region kseg0 program mem The contents of output section text may be interpreted as follows Input sections named text and stub and input sections that match the wild card patterns text and gnu linkonce t are collected and mapped into the output section Grouping these sections ensures locality of reference
31. 3 Microchip s in circuit debuggers that works with MPLAB IDE The ICDs supports Flash devices with built in debug circuitry The main component of each ICD is the pod A complete system consists of a pod header board with a device ICD target board cables and MPLAB IDE software MPLAB ICE 2000 4000 Not recommended for new designs See the MPLAB REAL ICE in circuit emulator Microchip s in circuit emulators that work with MPLAB IDE MPLAB ICE 2000 supports 8 bit PIC MCUs MPLAB ICE 4000 supports PIC18F and PIC24 MCUs and dsPIC DSCs The main component of each ICE is the pod A complete system consists of a pod processor module cables and MPLAB IDE software MPLAB IDE Microchip s Integrated Development Environment MPLAB PM3 A device programmer from Microchip Programs PIC18 microcontrollers and dsPIC digital signal controllers Can be used with MPLAB IDE or stand alone Will replace PRO MATE II MPLAB REAL ICE In Circuit Emulator Microchip s in circuit emulators that works with MPLAB IDE The MPLAB REAL ICE emulator supports PIC18F and PIC24 MCUs and dsPIC DSCs The main component of each ICE is the pod A complete system consists of a pod a driver and potentially a receiver card cables and MPLAB IDE software 2009 Microchip Technology Inc DS51833A page 203 MPLAB Assembler Linker and Utilities for PIC32 MPLAB SIM Microchip s simulator that works with MPLAB IDE in support of PIC MCU and dsPIC DSC dev
32. 89 standard clause 7 is confined to the contents of the standard headers lt float h gt lt iso646 h gt lt limits h gt stdarg h stdbool h stddef h and lt stdint h gt GPR General Purpose Register The portion of device data memory RAM available for general use Halt A stop of program execution Executing Halt is the same as stopping at a breakpoint Heap An area of memory used for dynamic memory allocation where blocks of memory are allocated and freed in an arbitrary order determined at runtime Hex Code Executable instructions stored in a hexadecimal format code Hex code is contained in a hex file Hex File An ASCII file containing hexadecimal addresses and values hex code suitable for programming a device Hexadecimal The base 16 numbering system that uses the digits 0 9 plus the letters A F or a f The digits A F represent hexadecimal digits with values of decimal 10 to 15 The rightmost digit counts ones the next counts multiples of 16 then 16 256 etc High Level Language A language for writing programs that is further removed from the processor than assembly ICD In Circuit Debugger MPLAB ICD 2 and 3 and PICkit 2 and 3 with Debug Express are Microchip s in circuit debuggers ICE In Circuit Emulator MPLAB ICE 2000 MPLAB ICE 4000 and MPLAB REAL ICE system are Microchip s in circuit emulators ICSPTM In Circuit Serial Programming A method of programming
33. A align 0 turns off the auto matic alignment used by the data creating pseudo ops You must make sure that data is properly aligned Reinstate auto alignment with a al ign pseudo instruction The second expression also absolute gives the 111 value to be stored in the pad ding bytes It and the comma may be omitted If it is omitted the padding bytes are zero by default You may wish to use OxFF for Flash regions of memory fill repeat size valuell Reserve repeat copies of size bytes repeat may be zero or more size may be zero or more but if it is more than 8 then it is deemed to have the value 8 The content of each repeat bytes is taken from an 8 byte number The highest order 4 bytes are zero The lowest order 4 bytes are value rendered in the little endian byte order Each size bytes in a repetition is taken from the lowest order size bytes of this number size is optional If the first comma and following tokens are absent size is assumed to be 1 value is optional If the second comma and value are absent value is assumed zero Example text fill 0x3 1 OxFF align 2 mylabel pb org new lc fill The org directive advances the location counter of the current section to new 1c new 1cis either an absolute expression or an expression with the same section as the current subsection That is you can t use org to cross sections if new 1c has the wrong section the org directive is ignored If the
34. Any build errors or warn ings will appear in this window BUILD SUCCEEDED appears in this window when the ELF object file was successfully generated and loaded into MPLAB IDE DS51833A page 30 O 2009 Microchip Technology Inc MPLAB IDE Projects for PIC32 Assembly Code 2 6 DEBUGGING YOUR PROJECT Now that you have a successful build select a debug tool to use in debugging your proj ect In this case we will choose the MPLAB SIM software simulator MPLAB SIM sim ulates the PIC32 MCU core and a number of on chip peripherals without requiring hardware To enable the simulator select tool MPLAB SIM from the Debugger menu MPLAB IDE loads the simulator component which populates the Debugger menu with a number of new menu items specific to the simulator Note Some debug tools such as the MPLAB REAL ICE in circuit emulator or MPLAB ICD 3 require the project to be built with specific options Rebuild ing your project after enabling the debug tool is the best way to ensure that the project was correctly built for the debug tool Use Build All under the Project menu At this point we are ready to begin debugging Set a breakpoint on an assembly instruction in the source code such as nop or b by double clicking the corresponding line in the editor s left side gutter A red breakpoint icon appears in the gutter as shown below lll C My Project first source file S GUHBUHUUHBHHBHHBGHHBHHGHHGHNUE main routi
35. C compiler for PIC32 MCUS dedicates general purpose register 29 as the software Stack Pointer All processor stack operations including function calls inter rupts and exceptions use the software stack The stack grows downward from high addresses to low addresses By default the size of the stack is 1024 bytes The size of the stack may be changed by specifying the size on the linker command line using the defsym min stack size size linker command line option An example of allocating a stack of 2048 bytes using the command line is pic32 gcc foo c Wl defsym min stack size 2048 Note See the MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 for more information on the compiler s usage of the stack The default linker script defines the stack as follows Stack allocation follows the heap Stack ALIGN 4 min stack size kseg1 data mem RAM functions go at the end of our stack and heap allocation Alignment of 2K required by the boundary register BMXDKPBA Wi ramfunc ALIGN 2K ramfunc begin ramfunc ramfunc ALIGN 4 ramfunc end kseg1 data mem AT kseg0 program mem ramfunc image begin LOADADDR ramfunc ramfunc length SIZEOF ramfunc bmxdkpba address ramfunc begin ORIGIN ksegi data mem bmxdudba address LENGTH ksegl data mem t DS51833A page 136 O 2009 Micro
36. Chandler Blvd Chandler AZ 85224 6199 Tel 480 792 7200 Fax 480 792 7277 Technical Support http support microchip com Web Address www microchip com Atlanta Duluth GA Tel 678 957 9614 Fax 678 957 1455 Boston Westborough MA Tel 774 760 0087 Fax 774 760 0088 Chicago Itasca IL Tel 630 285 0071 Fax 630 285 0075 Cleveland Independence OH Tel 216 447 0464 Fax 216 447 0643 Dallas Addison TX Tel 972 818 7423 Fax 972 818 2924 Detroit Farmington Hills MI Tel 248 538 2250 Fax 248 538 2260 Kokomo Kokomo IN Tel 765 864 8360 Fax 765 864 8387 Los Angeles Mission Viejo CA Tel 949 462 9523 Fax 949 462 9608 Santa Clara Santa Clara CA Tel 408 961 6444 Fax 408 961 6445 Toronto Mississauga Ontario Canada Tel 905 673 0699 Fax 905 673 6509 ASIA PACIFIC Asia Pacific Office Suites 3707 14 37th Floor Tower 6 The Gateway Harbour City Kowloon Hong Kong Tel 852 2401 1200 Fax 852 2401 3431 Australia Sydney Tel 61 2 9868 6733 Fax 61 2 9868 6755 China Beijing Tel 86 10 8528 2100 Fax 86 10 8528 2104 China Chengdu Tel 86 28 8665 5511 Fax 86 28 8665 7889 China Hong Kong SAR Tel 852 2401 1200 Fax 852 2401 3431 China Nanjing Tel 86 25 8473 2460 Fax 86 25 8473 2470 China Qingdao Tel 86 532 8502 7355 Fax 86 532 8502 7205 China Shanghai Tel 86 21 5407 5533 Fax 86 21 5407 5066 China Shenyang Tel 86 24 2334 2829 Fax 86 24 2334 2393
37. DS51833A page 14 2009 Microchip Technology Inc Y MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Part 1 MPLAB Assembler for PIC32 MCUs Chapter 1 Assembler Overview Lueeeeeeeeeeeeeeeeeeeeee eene nnn nennen nnne 17 Chapter 2 MPLAB IDE Projects for PIC32 Assembly Code 25 Chapter 3 Assembler Command Line Interface cesses 33 Chapter 4 Assembler Sy inicia 51 Chapter 5 Assembler Expression Syntax and Operation 61 Chapter 6 Assembler Symbols cessere eeeeeeennn nennen nennen 65 Chapter 7 Assembler Directives eeseeeeeeeeeeee eene nennen nennen 67 2009 Microchip Technology Inc DS51833A page 15 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 16 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 1 Assembler Overview INTRODUCTION MPLAB Assembler for PIC32 MCUs pic32 as produces relocatable machine code from symbolic assembly language for the PIC32 MCU family of devices The assembler is a Windows console application that provides a platform for developing assembly language code The assembler is a port of the GNU assembler from the Free Software Foundation Topics cov
38. Development Tools sse 91 TE 92 SA MUVO UPUT F ET e estan roscas tego uer tico arse ea Deui dale Ueveausese dud 92 Chapter 9 Linker Command Line Interface 9 T INTOJUCUON cS 99 9 2 Linker Interface SMOC incre parciales da 99 9 3 Compilation Driver Linker Interface Syntax ooonnonccccnnnccccccnnoccccccnanacinnnnancnons 100 9 4 Options that Control Output File Creation seeeeeeee 101 9 5 Options that Control Run time Initialization seerne 106 9 6 Options that Control Multilib Library Selection 106 9 7 Options that Control Informational Output 107 9 8 Options that Modify the Link Map Output eeee 110 Chapter 10 Linker Scripts TOA lut de ele suspira it 111 10 2 Overview of Linker Scripts AE 111 10 3 Command Line Information sii id Dawe araare 111 10 4 Default Linker Script oem ode opea eeu iaa 111 10 5 Adding a Custom Linker Script to an MPLAB IDE Project 113 10 6 Linker Script Command Language E 114 DS51833A page iv 2009 Microchip Technology Inc Table of Contents 10 7 Expressions in Linker Scripts cei e oed Sepe pete beide escht 127 Chapter 11 Linker Processing TTD is Liu erbaut eerta hate AN C pete A 133 11 2 Overview of Linker Processing WEE 133 IES Linker Allocation NE 135 11 4 Global and Weak Symbols AE 136 RB Selle ION T c rcc E 136 11 6 Heap Allocation meten rA TM T RTL TUE 137 11 7 Interrupt Vector Tables sitos 13
39. Do not assemble with the MIPS16e ISA extension Set noreorder By default the assembler attempts to fill a branch or delay slot automatically by reor dering the instructions around it This feature can be very useful Occasionally you ll want to retain precise control over your instruction ordering Use the set noreorder directive to tell the assembler to suppress this feature until it encounters a set reorder directive Set reorder Allow the assembler to reorder instructions to fill a branch or delay slot DS51833A page 88 O 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Part 2 MPLAB Object Linker for PIC32 MCUs Chapter 8 Linker Overview 91 Chapter 9 Linker Command Line Interface eeeeeeeeeeeeeeeeee 99 Chapter 10 Linker Scripts accionaria ria kd evi cric acr En 111 Chapter 11 Linker PROCESSING uu ceeaclicidudsl escena s deet egene Eet x E Ora blat 133 2009 Microchip Technology Inc DS51833A page 89 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 90 2009 Microchip Technology Inc MICROCHIP MPLAB ASSEMBLER LINKER AND UTILITIES FOR PIC32 MCUs USER S GUIDE Chapter 8 Linker Overview INTRODUCTION MPLAB Object Linker for PIC32 MCUs pic32 1d produces binary code from relo catable object code and archives for the PIC32 MCU family
40. E These changes to the source code and the linker script place your data at a fixed loca tion A 2 3 How can link my customized C start up code Occasionally a project may require modifying the C start up code provided with the C compiler The source file for the start up code is located in the C compiler s pic32 libs c startup crto S file Copy this file to your project directory and make the customizations to the copy Building from MPLAB IDE Once you ve made the customizations to the file add start up code as a source file to your MPLAB IDE project You will also need to tell the compilation driver not to link the default start up code Under the project s build options select the Don t link startup code PIC32 Suite option This checkbox adds the nostartfiles option to the compilation driver s command line 2009 Microchip Technology Inc DS51833A page 163 32 Bit Assembler Linker and Utilities User s Guide FIGURE A 1 PROJECT gt BUILD OPTIONS PROJECT SELECTION MPLAB IDE 8 15 View Project Debugger Programmer Tools Configure Window Project Wizard TE i 4 Mew Open Close D Set Active Project Quickbuild no asm Hie Clean Export Makefile Build All Ctrl F10 Make F10 Build Configuration Build Options Save Project Save Project s Add Files to Project Add New File to Project Remove File From Project Selec
41. EEE ee dee 132 C Character Constant coccccccnncconooonnnnnnnnononnnnnnnona conos 58 EE lee inks siens eB 58 CNECK SECTIONS EE A 107 Code Control Directives setat a a ene er 87 s tautoextend eniinn 87 iSe b macro eh nee eco her Deer naa 87 setmips169 ncn 87 BE le EE 87 set noauloestend 87 E 87 Set pOormiDel e coccconoccconononinnarncnnnnnnnnnarnnnnnnenannos 88 EL 88 Set Teordet instet odas 88 Command Line Information Linker Scripts AA 111 Command Line Interface Archiver Librarian oooononnccnncnnncncnonononnonnnnnns 143 E le 33 A eats chdieiea s 99 COMMENTS iia IA 56 114 Computing Absolute Addresses 134 Conditional Assembly Directives else Lu o tiu i n ESAME 79 elsel isis da dE ere aridus 79 ul TOR e UIDES ICM 79 IE aet esee adi ste ea e eet eon 79 leto cto bL ET 79 NCSC EE 79 Ma E 79 MO ii 79 USR 79 e 80 i e 80 Illu eerte etd Rest on 80 LLE AE re ve I tasa iss 80 Wale E E 80 UE Ee 80 UI icone nA Auto dA nOn Iiis 80 d Wine e GE 80 COnStalllS us das eiue ork cet E LA Me to 127 Floating Point Numbers eees 57 Integer ipe et eet 57 KI Te 57 COPY uan ao 123 mici M 110 Customer Notification Service 5 Customer Support esee 6 D EO M PRo 101 SOG umb ul EE 101 Debug Inform
42. License is a kind of copyleft which means that derivative works of the document must themselves be free in the same sense It complements the GNU General Public License which is a copyleft license designed for free software We have designed this License in order to use it for manuals for free software because free software needs free documentation a free program should come with manuals providing the same freedoms that the software does But this License is not limited to software manuals it can be used for any textual work regardless of subject matter or whether it is published as a printed book We recommend this License principally for works whose purpose is instruction or reference E 2 APPLICABILITY AND DEFINITIONS This License applies to any manual or other work in any medium that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License Such a notice grants a worldwide royalty free license unlimited in duration to use that work under the conditions stated herein The Document below refers to any such manual or work Any member of the public is a licensee and is addressed as you You accept the license if you copy modify or distribute the work in a way requiring permission under copyright law A Modified Version of the Document means any work containing the Document or a portion of it either copied verbatim or with modifications and or translated into a
43. Lp ee EE 38 ADDRi cheer ti eta ios tenete 131 SAN e ewe ee nts 40 ETE 41 ALIGN EE 131 Allocatable Secti0N coccooococcnoncccccncconoocncnnoninanas 117 Allocating Memory ee 134 clum x 41 EE 43 ar utility EE 141 AICRIVED Se cata da federe idk eder era vr abe eus 141 Command Line Interface ssse 143 le 145 Are ETC 55 T E E E id cde E E E eeu 44 ASCII Character Set ee 185 Assembler Command Line Interface seesses 33 BI en 67 Expression Syntax and Operation 61 OverView coocccccccccccccncnnnnnnnnnnonanananananananrn ro non nnonnnos 17 SOUIGe t al 21 SYMONS eege ft enean S 65 Syntax une tetti uuo ed 51 ASE Ticas 126 Assigning Output Sections to Regions 135 Assigning Values A 116 Attributes Reserved Section Names coccoccccnccnnoccccnnncnannn 69 B ET AAA 54 bin2hex utility iiser sses gaha eere 147 Binary File tede 94 BE OGK rx 131 Build Options 1 eret ees 10 Building the Output File esses 134 Built in Functions cesse 130 ADD p RART ATAI TE EE ES 131 7 oia a ea Se clado 131 BLOCK ciuda tutti tt 131 DEFINED einem evene 132 KEES Sites nihii iieri Aa ed 132 LOADADDR eene 132 MAX cnncoccocncccccccnononononononnnnananannnnana ro nor ocn nn n nnn nnns 132 OW 132 NEXT b con torem ene ec tiit e 132 SIZEO Et teta
44. Macro Definitions Add or remove macro definitions Restore Defaults Restore tab default settings Use Alternate Settings Text Box Enter options in a command line non GUI format Diagnostics Category Generate Command Line Diagnostics level Select to display all warnings suppress the display of all warnings or display only fatal warnings These will be shown in the Output window Listing Options If Enable Listing is checked you may select different listing options Equivalent to a suboption file options Include source code ah Expand macros am Include false conditionals ac Omit forms processing an Include assembly a1 List symbols as Omit debugging directives ad Section information ai Restore Defaults Restore tab default settings Use Alternate Settings Text Box Enter options in a command line non GUI format DS51833A page 10 O 2009 Microchip Technology Inc 32 Bit Language Tools and MPLAB IDE Build Options Dialog MPLAB PIC32 C Compiler Tab Although the MPLAB C Compiler for PIC32 MCUs comes with MPLAB IDE it is only the demo version The full version must be purchased See the Microchip web site www microchip com for details A subset of command line options may be specified in MPLAB IDE in the Build Options dialog MPLAB PIC32 C Compiler tab Select a category and then set up
45. Microchip embedded devices using serial communication and a minimum number of device pins IDE Integrated Development Environment MPLAB IDE is Microchip s integrated development environment Identifier A function or variable name O 2009 Microchip Technology Inc DS51833A page 199 MPLAB Assembler Linker and Utilities for PIC32 IEEE Institute of Electrical and Electronics Engineers Import Bring data into the MPLAB IDE from an outside source such as from a hex file Initialized Data Data which is defined with an initial value In C int myVar 5 defines a variable which will reside in an initialized data section Instruction Set The collection of machine language instructions that a particular processor understands Instructions A sequence of bits that tells a central processing unit to perform a particular operation and can contain data to be used in the operation Internal Linkage A function or variable has internal linkage if it can not be accessed from outside the module in which it is defined International Organization for Standardization An organization that sets standards in many businesses and technologies including computing and communications Interrupt A signal to the CPU that suspends the execution of a running application and transfers control to an Interrupt Service Routine ISR so that the event may be processed Upon completion of the ISR normal execution of the application resumes
46. Offset too large The offset must be within the signed extended 32 bit range Opcode not supported on this processor The instruction opcode is not supported on PIC32 MCUs Operand overflow The operand is not within the allowed range for this instruction Operation combines symbols in different segments The left hand side of the expression and the right hand side of the expression are located in two different sections The assembler does not know how to handle this expression R Register value used as expression An expression s operator is a register rather than a valid operator Relocation reloc isn t supported by the current ABI This relocation isn t supported by the PIC32 little endian ELE output format S Seek to end of incbin file failed s Could not find the end of the file specified by incbin Skip ld count ld larger than file size ld The incbin skip value count value is greater than the size of the file Store insn found in delay slot of noreorder code Consider moving the store in front of the branch and using a NOP in the delay instead Symbol s can not be both weak and common Both the weak directive and comm directive were used on the same symbol within the same source file Symbol name is already defined The symbol cannot be redefined Symbol definition loop encountered at s The symbol could not be defined because a self referential loop was encountered A symb
47. The command line options to pic32 1d may be specified in any order and may be repeated at will Repeating most options with a different argument will either have no further effect or override prior occurrences those further to the left on the command line of that option Options that may be meaningfully specified more than once are noted in the descriptions below Non option arguments are object files that are to be linked together They may follow precede or be mixed in with command line options except that an object file argument may not be placed between an option and its argument Usually the linker is invoked with at least one object file but you can specify other forms of binary input files using 1 and the script command language If no binary input files are specified the linker does not produce any output and issues the message No input files 2009 Microchip Technology Inc DS51833A page 99 32 Bit Assembler Linker and Utilities User s Guide If the linker cannot recognize the format of an object file it will assume that it is a linker script A script specified in this way augments the main linker script used for the link either the default linker script or the one specified by using T This feature permits the linker to link against a file that appears to be an object or an archive but actually merely defines some symbol values or uses INPUT or GROUP to load other objects For options whose names are a sing
48. Wizard to create a new project When the Welcome screen displays click Next to continue MPLAB IDE File Edit View Project Debugger Programmer Tools Configure wv New Open Close D Set Active Project gt Quickbuild no asm file Glean Build Configuration D 2 At Step One Select a device use the pull down menu to select the device Click Next to continue Project Wizard Ex Step ne B Select a device PIC32Mx420F032H PIC32MX440F128H PIC32MX440F128L PIC32MX440F256H PIC32MX440F512H PIC32MX460F256L DS51833A page 26 2009 Microchip Technology Inc MPLAB IDE Projects for PIC32 Assembly Code 3 At Step Two Select a language toolsuite choose Microchip PIC32 C Compiler Toolsuite as the Active Toolsuite Then click on each language tool in the tool suite under Toolsuite Contents and check or set up its associated executable location x Step Two E Select a language toolsuite Lo Active Toolsuite Microchip PIC32 C Compiler T oolsuite Toolsuite Contents MPLAB LINK32 Object Linker pic324 dd exe sl Vu an LIDD ah ien AA ah fi I ne re C Program Files Microchip MPLAB C32 bin pic32 as exe Browse Location I Store tool locations in ERE Help My Suite Isn t Listed Show all installed toolsuites A cem MPLAB ASM32 Assembler should point to the as
49. a more appropriate mul tilib library permutation Select Project gt Build Options Project MPLAB PIC32 Linker tab Library Selection category FIGURE A 3 BUILD OPTIONS LIBRARY SELECTION Directories Custom Build Trace PIC32 Suite MPLAB PIC32 Assembler MPLAB PIC32 C Compiler MPLAB PIC32 Linker Categories Library Selection Generate Command Line Optimization Level of Standard Libaries J Exclude Standard Libaries Generate 16 bit code Exclude floating point library code size E Inherit global setting Restore Defaults The dialog allows you to select an optimized permutation of the library Optimization level 2 generally provides a good balance between code size and speed but you may wish to choose level 3 or s as appropriate for your application You can also exclude floating point support and select mips16 code as suitable for your application These options can significantly reduce the code size footprint Note See the MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 for more details on the multilib feature eee 2009 Microchip Technology Inc DS51833A page 165 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 166 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Appendix B Assembler Errors Warnings Messages B 1 INTRODUCTION M
50. add another but you may replace the old one on explicit permission from the previous publisher that added the old one The author s and publisher s of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version E6 COMBINING DOCUMENTS You may combine the Document with other documents released under this License under the terms defined in section 4 above for modified versions provided that you include in the combination all of the Invariant Sections of all of the original documents unmodified and list them all as Invariant Sections of your combined work in its license notice and that you preserve all their Warranty Disclaimers The combined work need only contain one copy of this License and multiple identical Invariant Sections may be replaced with a single copy If there are multiple Invariant Sections with the same name but different contents make the title of each such section unique by adding at the end of it in parentheses the name of the original author or publisher of that section if known or else a unique number Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work In the combination you must combine any sections Entitled History in the various original documents forming one section Entitled History likewise combine any sections Entitled Acknowledgements an
51. all possible instructions for a particular processor is known as its instruction set Machine Language A set of instructions for a specific central processing unit designed to be usable by a processor without being translated Macro Macro instruction An instruction that represents a sequence of instructions in abbrevi ated form Macro Directives Directives that control the execution and data allocation within macro body definitions Makefile Export to a file the instructions to Make the project Use this file to Make your project outside of MPLAB IDE i e with a make Under Project gt Build Options gt Project Directories tab you must have selected Assemble Compile Link in the project directory under Build Directory Policy for this feature to work Make Project A command that rebuilds an application recompiling only those source files that have changed since the last complete compilation MCU Microcontroller Unit An abbreviation for microcontroller Also uC Memory Model C30 A representation of the memory available to the application C18 A description that specifies the size of pointers that point to program memory Message Text displayed to alert you to potential problems in language tool operation A message will not stop operation Microcontroller A highly integrated chip that contains a CPU RAM program memory I O ports and timers Microcontroller Mode One of the possible
52. be represented in the assembler in one of two ways described below 4 3 5 1 SINGLE LINE COMMENT This type of comment extends from the comment character to the end of the line For a single line comment use a number hash sign Note This comment character differs from the character recognized by the MPASM assembler and the MPLAB Assembler for PIC24 MCUs and dsPIC DSCs 4 3 5 2 MULTILINE COMMENT This type of comment can span multiple lines For a multi line comment use These comments cannot be nested Example All of these lines are comments DS51833A page 56 2009 Microchip Technology Inc Assembler Syntax 4 4 CONSTANTS A constant is a value written so that its value is known by inspection without knowing any context Examples are byte 74 0112 0b01001010 0x4A Ox4a J J All the same value ascii Ring the bell 7 HA string constant loat 0f 31415926535897932384626433832795028841971 693993751E 40 4 4 1 Numeric Constants The assembler distinguishes two kinds of numbers according to how they are stored in the machine Integers are numbers that would fit into a 1ong in the C language Float ing point numbers are IEEE 754 floating point numbers 4 4 1 1 INTEGERS A binary integer is Ob or OB followed by zero or more of the binary digits 01 An octal integer is 0 followed by zero or more of the octal digits 01234567 A decimal integer s
53. characters are significant Each symbol has exactly one name Each name in an assembly language program refers to exactly one symbol You may use that symbol name any number of times in a program 6 3 LOCAL SYMBOLS Local symbols are used when temporary scope for a label is needed There are ten local symbol names which can be reused throughout the program They may be referred to using the names 0 1 9 To define a local symbol write a label of the form N N N where N represents any digit 0 9 To refer to the most recent pre vious definition of that symbol write Nb using the same digit as when you defined the label To refer to the next definition of a local label write Nf The b stands for back wards and the f stands for forwards There is no restriction on how you can use these labels and you can reuse them too You can repeatedly define the same local label using the same number N although you can refer to only the most recently defined local label of that number for a back wards reference or the next definition of a specific local label for a forward reference Also note that the first 10 local labels 0 9 are implemented in a slightly more efficient manner than the others Here is an example EXAMPLE 6 1 SYMBOL USAGE 1 b TE 2 b 1b 1 b 2f 2 b 1b Which is the equivalent of label_1 b label_3 2009 Micro
54. compiler options For additional options see the MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 also available on the Microchip web site General Category Generate Command Line Generate debugging Create an ELF file with information to allow debugging of code in information MPLAB IDE Equivalent to g option Isolate each function in a section Place data in its own sec tion Use indirect calls Generate 16 bit code Exclude floating point Do not include floating point information when compiling library Macro Definitions Add or remove macro definitions Restore Defaults Restore tab default settings Use Alternate Settings Text Box Enter options in a command line non GUI format Optimization Category Generate Command Line Optimization Level Click in a circle on the chart to select an optimization level Equiva lent to O option Specific Optimizations Choose specific optimizations Unroll loops unro11 1oops Omit Frame Pointer W14 omit frame pointer Pre Optimization Instruc Choose from default disabled or enabled Equivalent to tion Scheduling fschedule insns option Post Optimization Choose from default disabled or enabled Equivalent to Instruction Scheduling fschedule insns2 option Restore Defaults Restore tab default settings Use Alternate Settings Text Box Enter options in a command line n
55. conditional section of code must be marked by an endif optionally you may include code for the alternative condition flagged by else The assembler also supports the following variants of if ifdecl symbol Assembles the following section of code if the specified symbol has been defined Note a symbol which has been referenced but not yet defined is considered to be undefined ifc string1 string2 This directive assembles the following section of code if the two strings are the same The strings may be optionally quoted with single quotes If they are not quoted the first string stops at the first comma and the second string stops at the end of the line Strings which contain whitespace should be quoted The string comparison is case sensitive ifeq absolute expression This directive assembles the following section of code if the argument is zero ifeqs string1 string2 This directive is another form of ifc The strings must be quoted using double quotes ifge absolute expression This directive assembles the following section of code if the argument is greater than or equal to zero 2009 Microchip Technology Inc DS51833A page 79 32 Bit Assembler Linker and Utilities User s Guide ifgt absolute expression This directive assembles the following section of code if the argument is greater than zero ifle absolute expression This directive assembles the following section of code if the argument is l
56. first word on the line empty lines are allowed and have no effect comments are allowed text after either of the characters or is ignored Whenever you use a list of names as part of the argument to an pic32 ar command you can separate the individual names with either commas or blanks Commas are shown in the explanations below for clarity is used as a line continuation character if appears at the end of a line the text on the following line is considered part of the current command Table 12 3 shows the commands you can use in archiver scripts or when using the archiver interactively Three of them have special significance TABLE 12 3 ARCHIVER SCRIPTS COMMANDS Option Function OPEN Or CREATE Specify a current archive which is a temporary file required for most of the other commands SAVE Commits the changes so far specified by the script Prior to SAVE commands affect only the temporary copy of the current archive ADDLIB ARCHIVE Add all the contents of ARCHIVE or if specified ADDLIB ARCHIVE MODULE each named MODULE from ARCHIVE to the current MODULE MODULE archive Requires prior use of OPEN or CREATE ADDMOD MEMBER MEMBER Add each named MEMBER as a module in the current MEMBER archive Requires prior use of OPEN or CREATE CLEAR Discard the contents of the curr
57. for the current section It is followed by an expression in parentheses Any otherwise unspecified regions of memory within the section for example gaps left due to the required alignment of input sections are filled with the two Least Significant Bytes of the expression repeated as necessary A FILL statement covers memory locations after the point at which it occurs in the section definition by including more than one FILL statement different fill patterns may be used in different parts of an output section This example shows how to fill unspecified regions of memory with the value 0x9090 FILL 0x9090 The FILL command is similar to the illexp output section attribute see Section 10 6 5 9 Output Section Attributes but it only affects the part of the section following the FILL command rather than the entire section If both are used the FILL command takes precedence 10 6 5 8 OUTPUT SECTION DISCARDING The linker will not create an output section which does not have any contents This is for convenience when referring to input sections that may or may not be present in any of the input files For example foo f00 will only create a oo section in the output file if there is a oo section in at least one input file If anything other than an input section description is used as an output section command such as a symbol assignment then the output section will always be created even if there are no match
58. full path name when matching names in the archive The 32 bit archiver librarian cannot create an archive with a full path name such archives are not POSIX compliant but other archive creators can This option will cause the archiver to match file names using a complete path name which can be con venient when extracting a single file from an archive created by another tool Write an object file index into the archive or update an existing one even if no other change is made to the archive You may use this modifier flag either with any operation or alone Running pic32 ar son an archive is equivalent to running ranlib on it Do not generate an archive symbol table This can speed up building a large library in several steps The resulting archive cannot be used with the linker In order to build a symbol table you must omit the S modifier on the last execution of the archiver or you must run ranlib on the archive Normally pic32 ar r inserts all files listed into the archive If you would like to insert only those of the files you list that are newer than existing members of the same names use this modifier The u modifier is allowed only for the operation x replace In particular the combination qu is not allowed since checking the time stamps would lose any speed advantage from the operation q This modifier requests the verbose version of an operation Many operations display additional information such as file n
59. hes 13 MPEAB LEIBS32 eege a 7 MPEAB LEINIS2 cots sets cocotte ot ti eite 7 N NEXT WEE 132 niri Utility EEN 149 pOo Check sechons 108 NOGROSSREFS eege een EE 127 snodefa ltlibs e 103 NEEN ee I id ee 123 nostartfiles ooooonnnncncnncnccnccoooncnnrnnnnnnnnnnnnnonononos 103 A a E 103 no undefined occoococononcnnncnnncnnncnnnnnrncncnnnnnnonononanonos 104 NOW Mi is See 46 no warn mismaltch cesses 108 Numeric Constants ooooccoccccnccncccnnnnnnnnnononononinananononos 57 O e EE 47 103 objdump utility esee 151 Object Elles ttes 21 92 Operands zio eden n EE 53 BaseReg Offset AAA 54 General Purpose Registers 53 literal Malle ssi rro Ele 54 Operators oxide e ere Non 62 128 NS e 62 Prefi EE 62 Options Archiver Librarian le EE 143 DS EE 143 posue Ar E ER AT eae 143 o 143 A A EENS 143 143 TE 144 Options Assembler Informational Out 46 Listing Output 35 Output File Creation 47 Search Palhi cete cerit eit 48 Symbol Definition esses 48 Options Linker Informational Output eese 107 Link Map Output sseeeeeeeeeeeeieeereereerrereenerneee 110 Output File Creation 101 Run time Initialization ccceeceeeeeeeeeeeetees 106 Options pic320 nm ele DEE 150 Options pic320 objdump disassemble zeroes
60. how input sections are mapped to output sections This example shows how wildcard patterns might be used to partition files This linker script directs the linker to place all text sections in text and all bss sections in bss The linker will place the data section from all files beginning with an uppercase character in DATA for all other files the linker will place the Gata section in data SECTIONS text text DATA A Z data data data bss bss DS51833A page 120 O 2009 Microchip Technology Inc Linker Scripts 10 6 5 3 INPUT SECTION FOR COMMON SYMBOLS A special notation is needed for common symbols because common symbols do not have a particular input section The linker treats common symbols as though they are in an input section named COMMON File names may be used with the COMMON section just as with any other input sections This will place common symbols from a particular input file in one section while common symbols from other input files are placed in another section In most cases common symbols in input files will be placed in the bss section in the output file For example bss bss COMMON If not otherwise specified common symbols will be assigned to section bss 10 6 5 4 INPUT SECTION EXAMPLE The following example is a complete linker script It tells the linker to read all of the sections from file a11 o and place them at the start
61. linker script the files will be included in the link at the point at which the linker script file is included This can affect archive searching GROUP file file GROUP file file The GROUP command is like INPUT except that the named files should all be archives and they are searched repeatedly until no new undefined references are created See the description of in Section 9 4 1 archives start group archives end group OUTPUT filename The OUTPUT command names the output file Using OUTPUT filename in the linker script is exactly like using o filename on the command line see Section 9 4 12 output file o file If both are used the command line option takes precedence SEARCH_DIR path The SEARCH DIR command adds path to the list of paths where the linker looks for archive libraries Using SEARCH DIR path is exactly like using L path on the command line see Section 9 4 8 library path dir L lt dir gt lfboth are used then the linker will search both paths Paths specified using the command line option are searched first STARTUP filename The STARTUP command is just like the INPUT command except that filename will become the first input file to be linked as though it were specified first on the command line 2009 Microchip Technology Inc DS51833A page 115 32 Bit Assembler Linker and Utilities User s Guide 10 6 3 Assigning Values to Symbols
62. may not subtract arguments from different sections DS51833A page 62 O 2009 Microchip Technology Inc Assembler Expression Syntax and Operation TABLE 5 2 INFIX OPERATORS CONTINUED Operator Description Example Relational Equal to if x y i Not equal to also lt gt f Ge 1 y lt Less than if x lt 5 lt Less than or equal to if y lt 0 gt Greater than if x gt a gt Greater than or equal to if x gt b Logical amp amp Logical AND 1f x gt 1 amp amp x 10 Logical OR E OU e x y lt 100 2009 Microchip Technology Inc DS51833A page 63 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 64 O 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 6 Assembler Symbols 6 1 INTRODUCTION Symbols are defined and their use with MPLAB Assembler for PIC32 MCUs is discussed Topics covered in this chapter are What are Symbols Local Symbols Giving Symbols Other Values The Special DOT Symbol 6 2 WHAT ARE SYMBOLS A symbol is one or more characters chosen from the set of all letters digits and the two characters underline and period Symbols may not begin with a digit Case is significant e g oo is a different symbol than Foo There is no length limit and all
63. of output section outputa which starts at location 0x10000 All of section input1 from file foo o follows immedi ately in the same output section All of section input2 from foo o goes into output section outputb followed by section input1 from foo1 o All of the remaining input1 and input2 sections from any files are written to output section outputc SECTIONS outputa 0x10000 all o foo o inputl outputb foo o input2 fool o inputl outputc inputl input2 10 6 5 5 OUTPUT SECTION DESCRIPTION The full description of an output section looks like this name address type AT 1ma output section command output section command region AT gt lma_region fillexp Most output sections do not use most of the optional section attributes The white space around name and address is required The colon and the curly braces are also required The line breaks and other white space are optional A section name may consist of any sequence of characters but a name which contains any unusual characters such as commas must be quoted 2009 Microchip Technology Inc DS51833A page 121 32 Bit Assembler Linker and Utilities User s Guide Each output section command may be one of the following asymbol assignment see Section 10 6 3 Assigning Values to Symbols an input section description see Section 10 6 5 1 Input Section Description dat
64. options on the standard output and exit 9 7 4 no warn mismatch Do not warn about mismatched input files Normally pic32 1d will give an error if you try to link together input files that are mismatched for some reason perhaps because they have been compiled for different processors or for different endiannesses This option tells pic32 1a that it should silently permit such possible errors This option should only be used with care in cases when you have taken some special action that ensures that the linker errors are inappropriate 9 7 5 report mem Print a memory usage report Requires v1 05 or later Print a summary of memory usage to standard output during the link This report also appears in the link map 9 7 6 trace t Trace file Print the names of the input files as pic32 1d processes them 9 7 7 trace symbol symbol y symbol Trace mentions of symbol Print the name of each linked file in which symbo1 appears This option may be given any number of times This option is useful when you have an undefined symbol in your link but do not know where the reference is coming from 9 7 8 V Print version and other information 9 7 9 verbose Output lots of information during link Display the version number for pic32 1d Display the input files that can and cannot be opened Display the linker script if using a default built in script 9 7 10 version v Print version information 9 7 11 war
65. program memory configurations of PIC18 microcontrollers In Microcontroller mode only internal execution is allowed Thus only the on chip pro gram memory is available in Microcontroller mode DS51833A page 202 O 2009 Microchip Technology Inc Glossary Microprocessor Mode One of the possible program memory configurations of PIC18 microcontrollers In Microprocessor mode the on chip program memory is not used The entire program memory is mapped externally Mnemonics Text instructions that can be translated directly into machine code Also referred to as opcodes MPASM Assembler EE Technology s relocatable macro assembler for PIC microcontroller devices KEELOQ devices and Microchip memory devices MPLAB ASM30 LINK30 LIB30 Previous names for Microchip s relocatable macro assembler object linker and object archiver librarian supporting 16 bit devices dsPIC30F 33F DSCs and PIC24H F MCUS MPLAB C18 C30 C32 Previous names for various C compilers from Microchip MPLAB C18 supports PIC18CXXX and PIC18FXXXX devices MPLAB C30 supports dsPIC30F 33F DSCs and PIC24H F MCUs and MPLAB C32 supports PIC32MX devices MPLAB Language Tool for Device Microchip s C compilers assemblers and linkers for specified devices Select the type of language tool based on the device you will be using for your application e g if you will be creating C code on a PIC18 MCU select the MPLAB C Compiler for PIC18 MCUS MPLAB ICD 2
66. provides an extra level with which to encode and results in a higher maximum data transfer rate A higher data transfer rate means fewer wires are required as in UW Ultra Wide and UW 2 3 SCSI hard disks which use only 68 wires These devices require a high trans fer rate over short distances Using standard l O transfer SCSI hard drives would require a lot more than 68 wires 2009 Microchip Technology Inc DS51833A page 201 MPLAB Assembler Linker and Utilities for PIC32 Low voltage means that the standard 5 volts is replaced by either 3 3 volts or 1 5 volts LVDS uses a dual wire system running 180 degrees of each other This enables noise to travel at the same level which in turn can get filtered more easily and effectively With standard 1 0 signaling data storage is contingent upon the actual voltage level Voltage level can be affected by wire length longer wires increase resistance which lowers voltage But with LVDS data storage is distinguished only by positive and neg ative voltage values not the voltage level Therefore data can travel over greater lengths of wire while maintaining a clear and consistent data stream Source http www webopedia com TERM L LVDS html Machine Code The representation of a computer program that is actually read and interpreted by the processor A program in binary machine code consists of a sequence of machine instructions possibly interspersed with data The collection of
67. record phdr failed e Can t set bid default target to s e Can not create link hash table 96e Can not make object file e Cannot represent machine s Could not read relocs e Could not read symbols Cref hash lookup failed e Error closing file s Error writing file s Failed to create hash table Failed to merge target specific data 2009 Microchip Technology Inc DS51833A page 179 32 Bit Assembler Linker and Utilities User s Guide File not recognized e Final close failed 96e Final link failed 96e Hash creation failed Out of memory during initialization Symbol t missing from main hash table Target 96s not found Target architecture respecified Unknown architecture 96s Unknown demangling style s Unknown language s in version information C 3 ERRORS The linker errors listed below usually indicate an error in the linker script or command line options passed to the linker An error could also indicate a problem with one or more of the input object files or archives Symbols gc sections and r may not be used together The section garbage collection option and the relocatable output option are not com patible Remove either the gc sections option or the relocatable option relax and r may not be used together The relaxation option and the relocatable output option are not compatible Remove one of the options A Assignment to location co
68. remove sectionz coocccoocccoccccconanancnnncnnnnncnnncnnnns 157 full contents sessssssssss 152 Suiten guai atte dir sg 157 0 decise eee ake TU E UE YU Pe DIVERS 152 157 due EUR 152 SMA Mac 157 Mitad da teet 152 sirip debug es 157 SST 152 Strip syHmbOls eri titre t Mee 157 Ml uev ee eg ge dl ke 152 Strip Upneeded ee ee eeeeeeeeseeeeeeneeeeeeneerenaees 157 a IR EUR 152 PEERS 157 Sen dicte qttod 152 e eater a teres 157 Jne numbere ccccconoccccccncnonancncnnnonnccnnnncnnncnnn 152 A 157 Mi o lr Ee 152 VEFSION ois tos erede ek 157 no show raw insn esssesesesee 152 See T e 157 prefix addresses eese 152 p 157 Eos das stes ee tee Ee P Le ee e ege 152 oic 118 il M iada 152 ORIGIIN s hit t eot ted 118 EE E 152 Other Linker Script Commands SEN 152 ASSER Toco nete Ee 126 ESOO MS 152 ENTRA Vin pe ien 126 section header esses 152 IER Nees oe 126 SNOW FAW INSN cccccccccccccccnnnoncccccnnnnnncnccnnnnnnnns 152 FORCE COMMON ALLOCATION 126 SOMO EE 152 NOCROSSREFS 7 eene 127 Start adress 152 OUTPUT ARGH ue pieces 127 stop address seen 153 OUTPUT FORMAT 127 SMS cj cite toin E E 153 REI 127 eis is vie eei ere vx Eve va d ET E EUR x RET CE 153 Other Options Assembler ER 153 EOS Me C 48 VOS ie 153 d 48 Dl P
69. section of new 1c is absolute pic32 as issues a warning then pretends the section of new 1c is the same as the current subsection DS51833A page 76 2009 Microchip Technology Inc Assembler Directives org may only increase the location counter or leave it unchanged you cannot use org to move the location counter backwards Because the assembler tries to assemble programs in one pass new 1c may not be undefined Beware that the origin is relative to the start of the section not to the start of the sub section When the location counter of the current subsection is advanced the intervening bytes are filled with 111 which should be an absolute expression If the comma and fill are omitted 111 defaults to zero Skip size fill Space size fill These directives emit size bytes each of value i11 Both size and fill are abso lute expressions If the comma and fill are omitted fill is assumed to be zero Struct expression Switch to the absolute section and set the section offset to expression which must be an absolute expression You might use this as follows Struct 0 field1 Struct fieldl 4 field2 Struct field2 4 field3 This would define the symbol ie1d1 to have the value 0 the symbol 1e182 to have the value 4 and the symbol ie1d3 to have the value 8 Assembly would be left in the absolute section and you would need to use a section directive of some sort to ch
70. section perform functions not defined in previous sections 3 7 1 defsym sym value Define symbol sym to given value 3 7 2 I dir Use this option to add dir to the list of directories that the assembler searches for files specified in include directives You may use I as many times as necessary to include a variety of paths The current working directory is always searched first after that the assembler searches any 1 directories in the same order as they were specified left to right on the command line When passed directly to the assembler this option affects the search path used by the assembler s include directive To affect the search path used by the C preprocessor for a include directive pass the corresponding option to the pic32 gcc compila tion driver 3 8 COMPILATION DRIVER AND PREPROCESSOR OPTIONS The compilation driver pic32 gcc and C preprocessor options in this section may be useful for assembly code projects The compilation driver will pass the options to the preprocessor as required See the MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 for more information on the compilation driver and for a more comprehensive list of driver options 3 8 1 mprocessor device Selects the device for which to compile e g mprocessor 32MX360F512L 3 8 2 Wa option Pass option as an option to the assembler If opt ion contains commas it is split into multiple assembler options at the commas The op
71. show raw insn start address address stop address address t syms V version w wide x all headers z disassemble zeroes OBJFILE OBJFILE are the object files to be examined When you specify archives pic32 objdump shows information on each of the member object files 13 4 3 Options The long and short forms of options shown in Table 13 4 as alternatives are equivalent At least one of the following options a d D f g G h H p r R S t T Vor x must be given TABLE 13 4 pic32 objdump OPTIONS Option Function a If any of the OBJFILE files are archives display the archive archive header header information in a format similar to 1s 1 Besides the information you could list with pic32 ar tv pic32 objdump a shows the object file format of each archive member 2009 Microchip Technology Inc DS51833A page 151 32 Bit Assembler Linker and Utilities User s Guide TABLE 13 4 pic32 objdump OPTIONS CONTINUED Option Function d Display the assembler mnemonics for the machine disassemble instructions from OBJFILE This option only disassembles those sections that are expected to contain instructions D Like d but disassemble the contents of all sections not disassemble all just those expected to contain instructions f Display summary information
72. specify the single command line option M you can control it with a script supplied via standard input Topics covered in this chapter are Arichiver Libraian and Other Development Tools Feature Set Input Output Files Syntax Options Scripts 2009 Microchip Technology Inc DS51833A page 141 32 Bit Assembler Linker and Utilities User s Guide 12 2 ARICHIVER LIBRAIAN AND OTHER DEVELOPMENT TOOLS The 32 bit librarian creates an archive file from object files created by the 32 bit assem bler Archive files may then be linked by the 32 bit linker with other relocatable object files to create an executable file See Figure 12 1 for an overview of the tools process flow FIGURE 12 1 TOOLS PROCESS FLOW C Source Files c Compiler Driver Program Assembly Source Files S C Compiler v Source Files s v mbler v ject Fil Archiver Librarian urs SC Object File Libraries Linker Script a 1d i MPLAB IDE Executable File Debug Tool elf Command Line Simulator 12 3 FEATURE SET Notable features of the assembler include Available for Windows Command Line Interface 12 4 INPUT OUTPUT FILES The 32 bit archiver librarian generates archive files a An archive file is a single file holdi
73. sure to use a capitalized s file extension Save the file Add New File to Project x Save in 3 My Project 110 rti 2x first project mcp first projeck mcw File name first source file S Save as type All Files e Cancel Jump to Project Directory m La 3 Verify that your new file opens in an editor window and the file name appears in the project window under Source Files 4 You can now enter your assembly source code into this new file The example code below just provides an empty infinite loop to get you started include lt p32xxxx h gt THEHBHHUHUHBHBHBDHBHBBHBHBHEHHUR main routine THEHBHHUHBHBHBHBHBHBHHBHBHEBUR text Set noreorder ent main main Do something here nop Infinite loop b 1b nop end main globl main 2 5 BUILDING YOUR PROJECT Now that you have a project with an assembly source file you can build the project MPLAB IDE s project manager manages the build steps for you From the Project menu select Make The Make feature determines which source files need to be built and calls the asso ciated language tool as necessary In this case it calls the assembler once for the sin gle source file in our project It then calls the linker to link in the appropriate libraries as indicated by the default linker script The Build tab of MPLAB IDE s Output window shows the language tool commands executed It also shows the output from the language tools
74. that are not preprocessed 4 3 SOURCE CODE FORMAT Assembly source code consists of statements and white spaces White space is one or more spaces or tabs White space is used to separate pieces of a source line White space should be used to make your code easier for people to read Unless within character constants any white space means the same as exactly one space Each statement has the following general format and is followed by a new line label mnemonic operands comment OR label directive arguments comment Label Instruction Mnemonic Operands Directive Arguments Comments 4 3 1 Label A label is one or more characters chosen from the set of all letters digits and the two characters underline and period Labels may not begin with a decimal digit except for the special case of a local symbol See Section 6 3 Local Symbols for more information Case is significant There is no length limit all characters are significant Label definitions must be immediately followed by a colon A space tab end of line or an assembler mnemonic or directive may follow the colon Label definitions may appear on a line by themselves and will reference the next address The value of a label after linking is the absolute address of a location in memory 4 3 2 Instruction Mnemonic Mnemonics tell the assembler what machine instructions to assemble For example addition ADD jumps J o
75. the included file is reached assembly of the original file continues at the statement following the include 7 11 DIRECTIVES THAT CONTROL DIAGNOSTIC OUTPUT Miscellaneous directives are abort ert error string fail expression ident comment print string version string warning string abort Prints out the message abort detected Abandoning ship and exits the program err If the assembler sees an err directive it will print an error message and unless the Z option was used it will not generate an object file This directive can be used to signal an error in conditionally compiled code error string Similar to err except that the specified string is printed fail expression Generates an error or a warning If the value of the expression is 500 or more pic32 as Will print a warning message If the value is less than 500 as will print an error message The message will include the value of expression This can occa sionally be useful inside complex nested macros or conditional assembly ident comment Appends comment to the section named comment This section is created if it does not exist The linker will ignore this section when allocating memory but will combine all comment sections together in link order print string Prints string on the standard output during assembly DS51833A page 84 2009 Microchip Technology Inc Assembler Direc
76. the built in Project Wizard Project Project Wizard In this wizard you will be able to select a language toolsuite that uses the 32 bit assembler e g the Microchip PIC32 C Compiler Toolsuite For more on the wizard and MPLAB IDE projects see MPLAB IDE documentation Once you have a project set up you may then set up properties of the tools in MPLAB IDE 1 From the MPLAB IDE menu bar select Project gt Build Options gt Project to open a dialog to set check project build options 2 Click on the tool tab to modify tool settings Build Options Dialog Build Options Dialog Build Options Dialog Build Options Dialog MPLAB PIC32 Assembler Tab MPLAB PIC32 C Compiler Tab MPLAB PIC32 Linker Tab PIC32 Suite Tab Build Options Dialog MPLAB PIC32 Assembler Tab A subset of command line options may be specified in MPLAB IDE in the Build Options dialog MPLAB PIC32 Assembler tab Select a category and then set up assembler options For additional options see MPLAB Assembler for PIC32 MCUs documentation General Category Generate Command Line Generate debugging information Create an ELF file with information to allow debugging of code in MPLAB IDE Equivalent to g option Keep local symbols Keep local symbols i e labels beginning with L uppercase only Equivalent to keep locals L option Exclude floating point library Do not include floating point information when assembling
77. the default width is 200 columns The assembler generates formfeeds whenever the specified number of lines is exceeded or whenever you explicitly request one using eject If you specify lines as 0 no formfeeds are generated save those explicitly specified with eject sbttl subheading Use subheading as a subtitle third line immediately after the title line when generat ing assembly listings This directive affects subsequent pages as well as the current page if it appears within ten lines of the top title heading Use heading as the title second line immediately after the source file name and page number when generating assembly listings DS51833A page 78 2009 Microchip Technology Inc Assembler Directives 7 8 DIRECTIVES THAT CONTROL CONDITIONAL ASSEMBLY Conditional assembly directives are else elseif expr endif e if expr else Used in conjunction with the i directive to provide an alternative path of assembly code should the if evaluate to false elseif expr Used in conjunction with the i directive to provide an alternative path of assembly code should the i evaluate to false and a second condition exists endif Marks the end of a block of code that is only assembled conditionally if expr Marks the beginning of a section of code that is only considered part of the source program being assembled if the argument expr is non zero The end of the
78. the load address used for the OVERLAY as a whole as with normal section definitions the load address is optional and defaults to the start address the start address is also optional and defaults to the current value of the location counter If the NOCROSSREFS keyword is used and there are any references among the sections the linker will report an error Since the sections all run at the same address it normally does not make sense for one section to refer directly to another For each section within the OVERLAY the linker automatically defines two symbols The symbol load start secname is defined as the starting load address of the section The symbol 1oad stop secname is defined as the final load address of the section Any characters within secname which are not legal within C identifiers are removed C or assembler code may use these symbols to move the overlaid sections around as necessary 2009 Microchip Technology Inc DS51833A page 125 32 Bit Assembler Linker and Utilities User s Guide At the end of the overlay the value of the location counter is set to the start address of the overlay plus the size of the largest section Here is an example Remember that this would appear inside a SECTIONS construct OVERLAY 0x9D001000 AT 0xA0004000 textO o1 o text text1 o2 o text This will define both texto and text1 to start at address 0x9D001000 textO will be loaded at addr
79. the title page itself plus such following pages as are needed to hold legibly the material this License requires to appear in the title page For works in formats which do not have any title page as such Title Page means the text near the most prominent appearance of the work s title preceding the beginning of the body of the text A section Entitled XYZ means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language Here XYZ stands for a specific section name mentioned below such as Acknowledgements Dedications Endorsements or History To Preserve the Title of such a section when you modify the Document means that it remains a section Entitled XYZ according to this definition The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document These Warranty Disclaimers are considered to be included by reference in this License but only as regards disclaiming warranties any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License DS51833A page 188 2009 Microchip Technology Inc GNU Free Documentation License E 3 VERBATIM COPYING You may copy and distribute the Document in any medium either commercially or non commercially provided that this License the copyright notices and the license noti
80. to a special predefined section by name the section s type should match the predefined type The assembler uses the predefined type for the section Immediate for s not in range 0 1023 lu The debugger Break code was not in the valid range Normal user code should not use this instruction reserved for debugger use Improper shift amount lu The shift value for a shift instruction e g SLL SRA SRL is out of range Instruction sne Instruction s result is always false The result of the condition tested by the SNE instruction is always false e g The s operand is the zero register and t is a nonzero constant expression Instruction seq result is always true The result of the condition tested by the SEQ instruction is always false e g The s operand is the zero register and t is the constant O Invalid merge entity size The section merge entity size must be non negative Invalid number The constant was in an unrecognized format Check the constant s prefix and radix J Jump address range overflow 0x lx The target address of the jump instruction is outside the 228 byte page L Left operand is a bignum integer 0 assumed The left operand in the expression is a bignum rather than an integer The assembler performs expression evaluation on only integers so it assumes integer 0 for this oper and Left operand is a float integer 0 assumed The left operand in the expression is a float rather
81. uniquely named section From C code use the section attribute From assembly code use the section directive For example Place string in a user named section const char _ attribute section hellostring absstring Hello World n Once you have created your section customize the linker script to map the input sec tion to a new output section First create a new memory region to contain the new section See Section 10 6 4 MEMORY Command MEMORY ksegO program mem rx ORIGIN 0x9D000000 LENGTH 0x80000 0x1000 LB E BS Create the new region to be used myabspmdata rx ORIGIN 0x9D07F000 LENGTH 0x1000 ksegO boot mem ENGTH 0x970 ORIGIN 0x9FC00490 Z ur The length of the kseg0_program_mem is decreased by the size of the new region The regions must not overlap DS51833A page 162 O 2009 Microchip Technology Inc Frequently Asked Questions Next modify the SECTIONS block to map the custom input section to an output section and place that output section into the new region See Section 10 6 5 SECTIONS Command SECTIONS Create an output section called outputmyabspmdata the containing user named section from the source code Map the output section to the memory region created above x outputmyabspmdata KEEP hellostring gt myabspmdata config BFCO2FFO KEEP config_BFCO2FF0 gt config3
82. value Values copied kseg0 program mem from program memory to data memory at C start up Sdata Variables zn bytes compiled Small initialized data segment ksegi data mem amp Gn with an initial value Used for kseg0 program mem gp relative addressing lit4 Constants usually floating point Small initialized data segment ksegi data mem amp lit8 which the assembler decides to kseg0 program mem store in memory rather than in the instruction stream Used for gp relative addressing Sbss Uninitialized variables lt n bytes Small zero filled segment ksegl data mem compiled Gn Used for gp relative addressing bss Uninitialized larger variables Zero filled segment ksegl data mem heap Heap used for dynamic memory Reserved by linker script ksegi data mem Stack Minimum space reserved for stack Reserved by linker script ksegl data mem DS51833A page 112 2009 Microchip Technology Inc Linker Scripts TABLE 10 1 PIC32 RESERVED STANDARD SECTION NAMES IN DEFAULT LINKER SCRIPT Section Name Generated by Final Location Default Linker Script MEMORY Region ramfunc RAM functions copied from pro Initialized data segment ksegi data mem amp gram memory to data memory at C ksegO0 program mem startup reginfo Debug information Not in load image n a Stab debug line DWARF debug information Not in load image n a comment stident ident strings Not in load ima
83. will be saved Then click Next to continue xl Step Three B Create a new project or reconfigure the active project e Create New Project File cw Project first project lt Back Next gt Cancel Help 5 At Step Four Add any existing files to your project you can add any pre exist ing source files to your project Click ADD gt gt to add it to the list of files to be used for this project on the right If you do not have any existing source files at this point you can add them later x Step Four B Add existing files to your project Yo es 2 2 Add gt gt CH CH 1 03 My Project _emove E a aO E CH aw ao 0 xf gt coca Because we will be using the default built in linker script for this example project we do not need to add the customized linker script to the project If we had a pre existing customized linker script we could add it here Select Next to continue 6 Atthe Summary screen review the Project Parameters to verify that the device toolsuite and project file location are correct If there are errors use Back to return to a previous wizard dialog Otherwise click Finish to create the new project and workspace DS51833A page 28 O 2009 Microchip Technology Inc MPLAB IDE Projects for PIC32 Assembly Code 7 The Project window should open showing our new project I
84. 0004 0x00008000 0x00100000 Oxffffffff Linker script and memory map LOAD size crt0 o 0x00000800 min heap size 0x800 START GROUP LOAD sizeMlibc a LOAD size libm a LOAD size libmchp peripheral 32MX360F512L a END GROUP LOAD C PIC32 Tools bin lib gcc pic32mx 3 4 4 sizeMlibgcc a 0x00000400 PROVIDE min stack size 0x400 0x00000000 PROVIDE min heap size 0x0 LOAD proc 32MX360F512L processor o 0x00000001 PROVIDE vector spacing 0x1 Ox9fc01000 ebase address 0x9fc01000 Oxbfc00000 _RESET ADDR Oxbfc00000 Oxbfc00380 BEV EXCPT ADDR Oxbfc00380 0x9fc01180 GEN EXCPT ADDR ebase address 0x180 reset Oxbfc00000 0x10 reset reset Oxb c00000 0x10 size crt0 o Oxbfc00000 reset bev excpt Oxbfc00380 0x10 bev handler bev handler 0xbfc00380 0x10 size crt0 o vector 0 0x9fc01200 0x0 vector 0 Startup Ox9fc00490 Ox1e0 zl startup Startup 0x9fc00490 OxleO size crt0 o text 0x9d000000 0x678 0x9d000000 text begin text stub text gnu linkonce t text 0x9d000000 0x18 size crt0 o text 0x9d000018 0x110 intermediatelobject o DS51833A page 96 O 2009 Microchip Technology Inc Linker Overview 0x9d000089 testfunct 0x9d0000a0 main 0x9d000018 foo text 0x9d000128 Oxc intermediate est o 0x9d000128 mylabel text general exception 0x9d000134 0x9d000134 OxdO size libc a general exception o general exception context text general exception handler 0x9d0005bc
85. 12 2 32 2 2 3 12288 3 768 3 48 3 3 4 16384 4 1024 4 64 4 4 5 20480 5 1280 5 80 5 5 6 24576 6 1536 6 96 6 6 7 28672 7 1792 7 112 7 7 8 32768 8 2048 8 128 8 8 9 36864 9 2304 9 144 9 9 A 40960 A 2560 A 160 A 10 B 45056 B 2816 B 176 B 11 C 49152 C 3072 C 192 C 12 D 53248 D 3328 D 208 D 13 E 57344 E 3584 E 224 E 14 F 61440 F 3840 F 240 F 15 For example hex A38F converts to 41871 as follows Hex 1000 s Digit Hex 100 s Digit Hex 10 s Digit Hex 1 s Digit Result 40960 768 128 15 41871 Decimal DS51833A page 186 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Appendix E GNU Free Documentation License GNU Free Documentation License Version 1 2 November 2002 Copyright C 2000 2001 2002 Free Software Foundation Inc 59 Temple Place Suite 330 Boston MA 02111 1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document but changing it is not allowed EI PREAMBLE The purpose of this License is to make a manual textbook or other functional and useful document free in the sense of freedom to assure everyone the effective freedom to copy and redistribute it with or without modifying it either commercially or non commercially Secondarily this License preserves for the author and publisher a way to get credit for their work while not being considered responsible for modifications made by others This
86. 30 long 9 31 endif DS51833A page 36 O 2009 Microchip Technology Inc Assembler Command Line Interface EXAMPLE 3 3 LISTING FILE GENERATED WITH alc COMMAND LINE OPTION GAS LISTING asm s page 1 1 1 asm S 2 1 lt built in gt 1 data 0 0 2 T 0 9 else 10 QDE T 11 endif 12 0000 02000000 long 2 13 if 0 15 else 16 0004 04000000 long 4 17 endif 18 endif 19 tE 0 21 elseif 1 22 SEE 0 24 elseif 1 25 0008 07000000 long 7 26 endif 27 elseif 1 29 else Ju endif Note Some lines omitted due to ac option O 2009 Microchip Technology Inc DS51833A page 37 32 Bit Assembler Linker and Utilities User s Guide 3 4 1 2 ad ad omits debugging directives from the listing This option is useful when processing compiler generated assembly code containing debugging information The compiler generated debugging directives will not clutter the listing Example 3 4 shows a listing using both the d and h sub options Compared to using the h sub option alone see next section the listing is much cleaner EXAMPLE 3 4 LISTING FILE GENERATED WITH alha COMMAND LINE OPTION GAS LISTING test s page 1 E Section mdebug abi32 2 previous 10 LtextO0 11 align2 12 globlmain 13 LFBO 14 file 1 sreNNtest c 1 src test c include lt p32xxxx h gt 2 src test c volatile unsigned int testval 3 src test c k x 4 src test c int 5 src test c main
87. 3A page 101 32 Bit Assembler Linker and Utilities User s Guide 9 4 3 defsym sym expr Define a symbol Create a global symbol in the output file containing the absolute address given by expr You may use this option as many times as necessary to define multiple symbols in the command line A limited form of arithmetic is supported for the expr in this context you may give a hexadecimal constant or the name of an existing symbol or use and to add or subtract hexadecimal constants or symbols 3 Note There should be no white space between sym the equals sign and expr 9 4 4 discard all x Discard all local symbols 9 4 5 discard locals X Discard temporary local symbols 9 4 6 gc sections Enable garbage collection of unused input sections This option is not compatible with r The default behavior of not performing this garbage collection can be restored by specifying no gc sections on the command line When link time garbage collection is in use marking sections that should not be elimi nated is often useful Mark the section by surrounding an input section s wildcard entry with KEEP asin KEEP init or KEEP SORT BY NAME ctors 9 4 7 library name 1 name Search for library name Add archive file name to the list of files to link This option may be used any number of times pic32 1d will search its path list for occurrences of 1ibname a for every name spec
88. 480 C startup code Total kseg0_boot_mem used Ox1le0d 480 19 9 of 0x970 Exception Memory Usage section address length dec Description app excpt 0x9fc01180 0x10 16 General Exception handler vector 1 0x9fc01220 0x8 8 Interrupt Vector 1 Total exception mem used 0x18 24 0 6 of 0x1000 ksegl Boot Memory Usage section address length dec Description reset Oxb c00000 0x10 16 Reset handler bev excpt 0xbfc00380 0x10 16 BEV Exception handler Total ksegl1 boot mem used 0x20 32 2 7 of 0x490 Total Program Memory used 0x99c 2460 0 5 of 0x81e00 ksegl Data Memory Usage section address length dec Description data 0xa0000000 Oxf4 244 Initialized data sdata 0xa00000f4 0x4 4 Small initialized data 2009 Microchip Technology Inc DS51833A page 95 sbss 0xa00000f8 0x4 bss 0xa00000fc 0x10c 26 heap 0xa0000208 0x800 204 Stack 0xa0000a08 0x400 102 Total ksegl_data_mem used 0xe08 359 Total Data Memory used 0xe08 359 Memory Configuration Name Origin ksegO program mem 0x9d000000 kseg0 boot mem 0x9fc00490 exception_mem Ox9fc01000 ksegl1 boot mem Oxbfc00000 configO OxbfcO2ffc ksegl data mem 0xa0000000 sfrs Oxbf800000 default 0x00000000 32 Bit Assembler Linker and Utilities User s Guide 4 8 8 4 Small uninitialized data Uninitialized data Dynamic Memory heap Min space reserved for stack 2 11 0 of 0x8000 2 11 0 of 0x8000 Attributes xr Length 0x00080000 0x00000970 0x00001000 0x00000490 0x0000
89. 7 Part 3 Binary Utilities for PIC32 MCUs Chapter 12 MPLAB Object Archiver Librarian for PIC32 MCUs A ee ege 141 12 2 Arichiver Libraian and Other Development Tools sssssss 142 12 3 ENEE 142 124 IngupOutpul Ple catas 142 T26 Syn a ii 143 12 0 OPON Re C emm 143 EE 145 Chapter 13 Other PIC32 MCU Binary Utilities jessica e the A oe eae ae 147 Ig press bonehes UD za i oett exe ra Cre Torey reer M Dime 147 19 9 prcao m DUlty ie nee e e Didier dus 149 13 4 pPres2 0b dump VINY untere Fu eaae Deb a ih ote odes i ees 151 Pr exer Eeer gereest 153 EE er LUN c m 154 13 7 pac32estrings UY sisas P ees obe hrs tiet Ferd anges 155 19 8 pie322strip Utility itti etae RR dir EO ER REN NR eic DEAS 156 Part 4 Appendices Appendix A Frequently Asked Questions Msc m e 161 A 2 List of Frequently Asked Questions FAQ ssseessseeees 161 Appendix B Assembler Errors Warnings Messages Bt luet TE MM m 167 A o S 167 B3 EMOS ts 168 B 4WAamiMds ts oae died he ical Ried A E 175 BS Ee 178 Appendix C Linker Errors Warnings Cot go o ee CE 179 O2 Fatal ES es 179 3 EMOS m 180 O 2009 Microchip Technology Inc DS51833A page v 32 Bit Assembler Linker and Utilities User s Guide E Ed e EE E 182 Appendix D Useful Tables D 1 Introduction E E E E 185 D 2 ASCII Character Set ninia a eA 185 D 3 Hexadecimal to Decimal Conversion oocccccccccnccncnococn
90. 833A page 219 32 Bit Assembler Linker and Utilities User s Guide REPLACE cu ld a 146 SNE ET 145 146 VERBOSE 2 habe diete dogma 146 SEARGH DIR iei tni 115 Section Directives DSS icti tied oe ae Ee Ho ideas 68 data oiim en ege 68 3popsection eee eene 69 ipushsectlorn iet te 68 Sectior NAME ees eeh eebe EEN E 69 jq ERE 71 Section of an Expression oooococccnnccnocococccnnnananccnnnnos 129 SECTIONS Commande 118 section EE 103 Set Language Tool Locations ooooocnncccnnnocccnnccccnnnnss 8 Simple Aeslonments sees 116 ECH Dt a EE 154 ek EE 132 Source Code eet te 9 52 Source Files oie e eret ttes 19 Stack AlloCatiori 5 ans ene hee 136 Start group c c i ENET TETEE 101 STAR TO Press iier etes 115 Statement Format 2 0 cccecceeeceeeeeeeeeeeeeeeteeeeeeeeeneeee 52 SUNS uo ci etim a 58 strings utility rtt tee 155 Strip Utility acce enc or teens 156 SL UNE 104 ee Ee e EE 104 Substitution Expansion Directives Klee m ies 82 ENA iii 80 81 83 OXIUTI len geed ees 80 82 WDC ess EM IMAGO WEE 81 PUT Mit lid 83 BCEE 83 IOs pei tel ate i a 82 ID NEE 80 SUBS coi nd c eg 21 78 Symbol NAMES eret eene 127 Symbol Table ssessss 22 44 114 132 Symbols miii 65 Assembler cursada 65 Syntax Archiver Librarian ooonooccccnnnnnccccccnninancccncnonnnos 143 AsSembl r eai EEG 33 51 Einker nne hau hus 99 AA tenete 147
91. A EEEE EEEE EEE ETETETT ST 149 EI ee elle Tue E 151 pic32 ranlib EE 153 Ee Strings secco ime eit t e de 155 pIc32 strips i nene Uere 156 T EE 104 Mi a ett edes 108 TARGET oro ehe 127 target Puras Ol eter 46 SIDSS inc Det datos 104 ei Re E WEE 104 Miles cto ies EET 78 A i tco it re Pre ever ri cete 21 WACC RE de e ea EE EE cts anes 108 trace symbol etu en ttes 108 Eum S 104 U zt icoaoic ois aue ti rau thee ra EE RCM IIS REA LL Se AATA 104 ndeflned u EE 104 Mp 103 USB EE 211 Utilities oot oe ect 139 V D UN EL DNE ee 108 Mi Ee Seet ee 47 108 ZVetbDOSO scite M R TE 47 108 VefSIOL s et dole e Pu det t Se E 46 108 Virtual Memory Address ccooooooccccccococoncccnncannns 114 124 VMA EE 114 124 WwW EE E EA 46 ENE TA D E e EEA elici eege 46 WarN cCOmMmmMON tics iia 108 SWEDEN dg 109 warn section align eene 109 Watchdog Tuer 211 Weak Symbols esee 136 Web Site Microchip oonoccconnocccnncccconoccnononnnnonnnononnnoos 5 AS utei eter 52 wr rr EC 105 X T Lent 102 2 c EE d Ed 102 Y M 108 Z DECIR eege tnd Sa et asd cd ium 47 DS51833A page 220 2009 Microchip Technology Inc 32 Bit Assembler Linker and Utilities User s Guide NOTES 2009 Microchip Technology Inc DS51833A page 221 MICROCHIP WORLDWIDE SALES AND SERVICE AMERICAS Corporate Office 2355 West
92. Appendix C Linker Errors Warnings INTRODUCTION MPLAB Object Linker for PIC32 MCUs pic32 1d generates errors and warnings A descriptive list of these outputs is shown here This list shows only the most common diagnostic messages from the linker Topics covered in this appendix are Fatal Errors Errors Warnings FATAL ERRORS The following errors indicate that an internal error has occurred in the linker If the linker emits any of the fatal errors listed below and you re using a custom linker script check that the script specifies OUTPUT FORMAT e1f 32 tradlittlemips and OUTPUT ARCH pic32mx Other values may cause the linker to operate in an unsup ported mode Also check that you are passing only fully supported options on the linker s command line Finally make sure that no other applications have the linker s input or output files locked If the fatal error occurs with the correct OUTPUT FORMAT OUTPUT ARCH and command line options contact Microchip Technology at http support microchip com for engineering support Be sure to provide full details about the source code and command line options causing the error Bfd backend error bfd reloc ctor unsupported Did hash allocate failed creating symbol s Did hash lookup failed e Did hash lookup for insertion failed 96e Did hash table init failed e Did hash table init of cref table failed 96e Did link hash lookup failed e Bfd new link order failed Did
93. By default the listing file is displayed on standard output Specify the a file option See Chapter 3 Assembler Command Line Interface on the command line to send the listing file to a specified file A listing file produced by the assembler is composed of the elements listed below Example 1 2 shows a sample listing file 1 4 81 HEADER The header contains the name of the assembler the name of the file being assembled and a page number This is not shown if the an option is specified 1432 TITLE The title line contains the title specified by the title directive This is not shown if the an option is specified 1 4 83 SUBTITLE The subtitle line contains the subtitle specified by the sbtt1 directive This is not shown if the an option is specified 1 4 8 4 HIGH LEVEL SOURCE High level source will be present if the ah option is given to the assembler The format for high level source is line H gt lt filename gt lt source gt For example 1 hello c include lt stdio h gt 1 4 85 ASSEMBLER SOURCE Assembler source will be present if the a1 option is given to the assembler The format for assembler source is line 4 addr encoded bytes source For example 35 0000 80000434 ori a0 zero IOPORT BIT 7 Note 1 Line numbers may be repeated 2 Addresses are relative to sections in this module and are not absolute 3 Instructions are encoded in little endian order
94. C32 MCUs USER S GUIDE Part 4 Appendices Appendix A Frequently Asked Questions cccccsssseeeeeeeeeeeeeseeeeeeeeeeseneeeeeeeeeeees 161 Appendix B Assembler Errors Warnings Messages eees 167 Appendix C Linker Errors Warnings eeeeeeeeeee nennen nennen nnne nnn nnn 179 Appendix D Useful Tables eeeeeeeeeeeeeeeeeeeeeeee einen nnne 185 Appendix E GNU Free Documentation License eese 187 2009 Microchip Technology Inc DS51833A page 159 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 160 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Appendix A Frequently Asked Questions A 1 INTRODUCTION This section answers several frequently asked questions aboutthe MPLAB Assembler Linker and Binary Utilities for PIC32 MCUs A 2 LIST OF FREQUENTLY ASKED QUESTIONS FAQ How can move the Interrupt Vector Table IVT from Boot ROM kseg1 to Appli cation Flash kseg0 e How can I place my data at an absolute address in memory How can I link my customized C start up code How can reduce the C library overhead A 2 1 How can move the Interrupt Vector Table IVT from Boot ROM kseg1 to Application Flash kseg0 Relocating the Interrupt Vector Table In some ca
95. Command The second use of ALIGN is used to define the value of a symbol The built in function NEXT is closely related to ALIGN 10 7 7 4 BLOCK EXP This is a synonym for ALIGN for compatibility with older linker scripts It is most often seen when setting the address of an output section s ______ ___ ua 2009 Microchip Technology Inc DS51833A page 131 32 Bit Assembler Linker and Utilities User s Guide 10 7 7 5 DEFINED SYMBOL Return 1 if symbol is in the linker global symbol table and is defined otherwise return 0 You can use this function to provide default values for symbols For example the following script fragment shows how to set a global symbol begin to the first location in the text section but if a symbol called begin already existed its value is preserved SECTIONS text begin DEFINED begin begin 10 7 7 6 KEEP SECTION When link time garbage collection is in use gc sections marking sections that should not be eliminated is often useful This is accomplished by surrounding an input section s wildcard entry with KEEP as in KEEP init or KEEP SORT BY NAME ctors 10 7 7 7 LOADADDR SECTION Return the absolute LMA of the named section This is normally the same as ADDR but it may b
96. Data which is defined without an initial value In C int myVar defines a variable which will reside in an uninitialized data section Upload The Upload function transfers data from a tool such as an emulator or programmer to the host PC or from the target board to the emulator USB Universal Serial Bus An external peripheral interface standard for communication between a computer and external peripherals over a cable using bi serial transmission USB 1 0 1 1 supports data transfer rates of 12 Mbps Also referred to as high speed USB USB 2 0 supports data rates up to 480 Mbps Vector The memory locations that an application will jump to when either a Reset or interrupt OCCUIS Warning IDE An alert that is provided to warn you of a situation that would cause physical dam age to a device software file or equipment ALU30 C30 Warnings report conditions that may indicate a problem but do not halt processing In MPLAB C30 warning messages report the source file name and line number but include the text warning to distinguish them from error messages Watch Variable A variable that you may monitor during a debugging session in a Watch window Watch Window Watch windows contain a list of watch variables that are updated at each breakpoint Watchdog Timer A timer on a PIC microcontroller that resets the processor after a selectable length of time The WDT is enabled or disabled and set up using Configuration
97. Digital Signal Processing The computer manipulation of digital signals commonly analog signals sound or image which have been converted to digital form sampled Digital Signal Processor A microprocessor that is designed for use in digital signal processing Directives Statements in source code that provide control of the language tool s operation Download Download is the process of sending data from a host to another device such as an emulator programmer or target board DSC See Digital Signal Controller DSP See Digital Signal Processor DWARF Debug With Arbitrary Record Format DWARF is a debug information format for ELF files EEPROM Electrically Erasable Programmable Read Only Memory A special type of PROM that can be erased electrically Data is written or erased one byte at a time EEPROM retains its contents even when power is turned off DS51833A page 196 2009 Microchip Technology Inc Glossary ELF Executable and Linking Format An object file of this format contains machine code Debugging and other information is specified in with DWARF ELF DWARF provide better debugging of optimized code than COFF Emulation The process of executing software loaded into emulation memory as if it were firmware residing on a microcontroller device Emulation Memory Program memory contained within the emulator Emulator Hardware that performs emulation Emulator System The MPLAB ICE 2000 and MP
98. ES DS51833A page 98 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 9 Linker Command Line Interface 9 1 INTRODUCTION MPLAB Object Linker for PIC32 MCUs pic32 1d may be used on the command line interface as well as with MPLAB IDE Topics covered in this chapter are Linker Interface Syntax Compilation Driver Linker Interface Syntax Options that Control Output File Creation Options that Control Run time Initialization Options that Control Informational Output Options that Modify the Link Map Output 9 2 LINKER INTERFACE SYNTAX The linker supports a plethora of command line options but in actual practice few of them are used in any particular context pic32 1d options file Note Command line options are case sensitive For instance a frequent use of pic32 1dis to link object files and archives to produce a binary file To link a file hello o pic32 1d o output hello o 1pic32 This tells pic32 1d to produce a file called output as the result of linking the file hello o with the archive 1ibpic32 a When linking a C application there are typically several archives also known as librar ies which are included in the link command The list of archives may be specified within start group end group options to help resolve circular references pic32 1d o output hello o start group lpic32 lm lc end group
99. FFF000 2009 Microchip Technology Inc DS51833A page 161 32 Bit Assembler Linker and Utilities User s Guide For the PIC32MX360F512L this gives us ebase address 0x9D07F000 The second line to change in the procdefs 1d specifies the memory region for the exception vectors The default lines from procdefs 1d specifying the exception memory region are MEMORY ksegO program mem rx ORIGIN 0x9D000000 LENGTH 0x80000 ksegO boot mem ORIGIN 0x9FC00490 LENGTH 0x970 exception mem ORIGIN 0x9FC01000 LENGTH 0x1000 The value for the ORIGIN of the exception memory must be the same as ebase so we change the line to exception mem ORIGIN 0x9D07F000 LENGTH 0x1000 We must also reduce the size of the ksegO_ program mem region to accommodate the moved exception mem region ksegO program mem rx ORIGIN 0x9D000000 LENGTH 0x80000 0x1000 In summary to relocate the IVT from Boot ROM to App Flash memory the user must first set ebase address to the properly aligned address set the ORIGIN of the exception mem region to the literal value of ebase address and adjust the length of the ksego0 program mem region A 2 2 How can place my data at an absolute address in memory Placing sections at a fixed location You may want to place a string such as a version number at a fixed location in memory The following section summarizes a way to accomplish this goal First place your vari able into a
100. IC32 MCUs User s Guide DS51686 for more details on the C compiler driver EXAMPLE 1 1 SAMPLE ASSEMBLER CODE include lt p32xxxx h gt define IOPORT BIT 7 1 lt lt 7 global main define all global symbols here text define which section for example text does this portion of code resides in Typically all your code will reside in text section as shown below cn Set noreorder This is important for an assembly programmer This directive tells the assembler not to optimize the order of the instructions as well as not to insert nop instructions after jumps and branches El IK main This is where the PIC32 start up code will jump to after initial set up BR KK KK RR RK RR KR RK RRR KK KR RR RR KR RR RR k k KK k k k k k 2009 Microchip Technology Inc DS51833A page 19 32 Bit Assembler Linker and Utilities User s Guide ent main directive that marks symbol main as function in the ELF output main Call function to clear bit relevant to pin 7 of port A The jal instruction places the return address in the ra register Si ori a0 zero IOPORT BIT 7 jal mPORTAClearBits nop endless loop endless j endless nop end main directive that marks end of main function and its size in the ELF output BR KK RK RR RK AAA RARA AA AAA ARA RRA RR KR RARA ARA AA RRA AAA RR RK k k RR k k mPORTAClearBits int bits This fu
101. Keep only symbols listed in file Retain only the symbols listed in the file file discarding all others file is simply a flat file with one symbol name per line This option is especially useful in environments where a large global symbol table is accumulated gradually to conserve run time memory retain symbols file does notdiscard undefined symbols or symbols needed for relocations You may only specify retain symbols file once in the command line It overrides s and S 9 4 15 section start sectionname org Locate a section in the output file at the absolute address given by org You may use this option as many times as necessary to locate multiple sections in the command line org must be a single hexadecimal integer for compatibility with other linkers you may omit the leading 0x usually associated with hexadecimal values Note There should be no white space between sectionname the equals sign and org 2009 Microchip Technology Inc DS51833A page 103 32 Bit Assembler Linker and Utilities User s Guide 9 4 16 script file T file Read linker script Read link commands from the file file These commands replace pic32 1d s default link script rather than adding to it so fi 1e must specify everything necessary to describe the target format If file does not exist pic32 1d looks for it in the directories specified by any preceding L options Multiple T options accumulate 9 4 17 strip all
102. LAB ICE 4000 emulator systems include the pod pro cessor module device adapter target board cables and MPLAB IDE software The MPLAB REAL ICE system consists of a pod a driver and potentially a receiver card target board cables and MPLAB IDE software Endianness The ordering of bytes in a multi byte object Environment IDE The particular layout of the desktop for application development MPLAB PM3 A folder containing files on how to program a device This folder can be transferred to a SD MMC card Epilogue A portion of compiler generated code that is responsible for deallocating stack space restoring registers and performing any other machine specific requirement specified in the runtime model This code executes after any user code for a given function immediately prior to the function return EPROM Erasable Programmable Read Only Memory A programmable read only memory that can be erased usually by exposure to ultraviolet radiation Error File A file containing error messages and diagnostics generated by a language tool Errors Errors report problems that make it impossible to continue processing your program When possible errors identify the source file name and line number where the problem is apparent Event A description of a bus cycle which may include address data pass count external input cycle type fetch R W and time stamp Events are used to describe triggers breakpoints and interrupt
103. N Linker scripts are used to control MPLAB Object Linker for PIC32 MCUs pic32 1d functions By default the linker uses a built in linker script with a device specific include file However you can also customize your linker script for specialized control of the linker in your application Topics covered in this chapter are Overview of Linker Scripts Command Line Information Default Linker Script Adding a Custom Linker Script to an MPLAB IDE Project Linker Script Command Language Expressions in Linker Scripts 10 2 OVERVIEW OF LINKER SCRIPTS Linker scripts control all aspects of the link process including allocation of data memory and program memory mapping of sections from input files into the output file construction of special data structures such as interrupt vector tables Linker scripts are text files that contain a series of commands Each command is either a keyword possibly followed by arguments or an assignment to a symbol 10 3 COMMAND LINE INFORMATION Linker scripts are specified on the command line using either the T option or the script option see Section 9 4 Options that Control Output File Creation pic32 1d o output elf input o script mylinkerscript ld If the linker is invoked through pic32 gcc add the w1 prefix to allow the option to be passed to the linker pic32 gcc o output elf input o Wl script mylinkerscript ld 10 4 DEFAULT LINKER SCRIPT If no linker scrip
104. NEGQ enee en e 123 Informational Output Options Assembler fatal warnings eeeeee 46 SE dtr hh eher 46 D 46 SSNIO WALT oe cor a n er eem Den 46 TAO NOD iio 46 a T ET 47 VeSa e EE 47 ETE OI EEEIEE TE E EE 46 NN ebe E 46 SOWOIM EEEE E ET 46 Informational Output Options Linker Check sections 107 help icri ctc erede 108 p0o Check sechons 108 2009 Microchip Technology Inc DS51833A page 215 32 Bit Assembler Linker and Utilities User s Guide no warn mismatch ccce 108 E 108 Jo M EERN 108 MAC is 108 trace MOL ia 108 Mi EM 108 pm IP 108 A ere cen Eee Er TTD 108 VerSiOn coccccccnncnccnonnnnnconennnnnnnnnnnnonoonnronnnnnnanonnns 108 Warn commonhn essssesseeeeee nennen 108 Warn OnCe niie aadi 109 WAIN SECTION ALIQN ee eeeeeeseeeeeneeeeeneeeeeneeeeees 109 Vict test shea Mert css Mr DUE 108 Initializated Section oooonnnnncnncccccanonononcnnnononononononos 117 Initialization Directives SCM EE 71 e EE 71 DY jet niente tiep diee e ane 71 COUbI iii An 72 lum 72 olio EET 72 PP 73 ele 73 short MM 73 SINQI uoh 72 Jie 73 WONG S rote Meum e rio Ce Ee e 73 Initialized Section esee 117 INPU Titicaca iaa oe ok 115 Input Section Common Symbols sese 121 Example 1 tcI 121 Wildcard Pattems 119 Integer Expressions eeeeeee
105. ODUCTION The MPLAB Object Archiver Librarian for PIC32 MCUs pic32 ar creates modifies and extracts files from archives This tool is one of several utilities An archive is a sin gle file holding a collection of other files in a structure that makes it possible to retrieve the original individual files called members of the archive The 32 bit archiver librarian can maintain archives whose members have names of any length however if an modifier is used the file names will be truncated to 15 charac ters The archiver is considered a binary utility because archives of this sort are most often used as libraries holding commonly needed subroutines The archiver creates an index to the symbols defined in relocatable object modules in the archive when you specify the modifier s Once created this index is updated in the archive whenever the archiver makes a change to its contents save for the q update operation An archive with such an index speeds up linking to the library and allows routines in the library to call each other without regard to their placement in the archive You may use pic32 nm sOrpic32 nm print armap to list this index table If an archive lacks the table another form of the 32 bit archiver librarian called pic32 ranlib can be used to add only the table The 32 bit archiver librarian is designed to be compatible with two different facilities You can control its activity using command line options or if you
106. OLUTE EXP Return the absolute non relocatable as opposed to non negative value of the expression exp Primarily useful to assign an absolute value to a symbol within a section definition where symbol values are normally section relative DS51833A page 130 O 2009 Microchip Technology Inc Linker Scripts 10 7 7 2 ADDR SECTION Return the absolute address the VMA of the named section Your script must previously have defined the location of that section In the following example symbol 1 and symbol 2 are assigned identical values SECTIONS output1 start of output 1 ABSOLUTE Outputb symbol 1 ADDR outputl symbol 2 start of output 1 de 10 273 ALIGN EXP Return the location counter aligned to the next exp boundary exp must be an expression whose value is a power of two This is equivalent to exp 1 exp 1 ALIGN doesn t change the value of the location counter it just does arithmetic on it Here is an example which aligns the output data section to the next 0x2000 byte boundary after the preceding section and sets a variable within the section to the next 0x8000 boundary after the input sections SECTIONS data ALIGN 0x2000 data variable ALIGN 0x8000 The first use of ALIGN in this example specifies the location of a section because it is used as the optional address attribute of a section definition see Section 10 6 5 SECTIONS
107. OURCE CODE WITH REGISTER NUMBER OPERANDS text Add Word li 2 123 li 3 456 add 4 2 3 2009 Microchip Technology Inc DS51833A page 53 32 Bit Assembler Linker and Utilities User s Guide EXAMPLE 4 2 ASSEMBLY SOURCE CODE WITH CONVENTIONAL REGISTER NAMES include lt p32xxxx h gt text Add Word li v0 123 v0 is a return value register li vl 456 vl is a return value register add a0 v0 vl a0 is an argument register 4 3 3 2 LITERAL VALUE OPERANDS Literal values can be hexadecimal octal binary or decimal format Hexadecimal num bers are distinguished by a leading 0x Octal numbers are distinguished by a leading 0 Binary numbers are distinguished by a leading OB or Ob Decimal numbers require no special leading or trailing character Examples Oxe 016 0b1110 and 14 all represents the literal value 14 5 represents the literal value 5 symbol represents the value of symbol 4 3 3 3 BASEREG OFFSET OPERANDS Load and store operations select the memory location using a BaseReg Offset oper and For an operand of this type the effective address is formed by adding the 16 bit signed offset to the contents of a base register A PIC32 MCU data sheet shows this type of operand as Mem R off set EXAMPLE 4 3 USING ASSEMBLY SOURCE CODE WITH BASEREG OFFSET OPERANDS include lt p32xxxx h gt data align 4 MY WORD DATA word 0x10203040 0x8090a0b0 text global exa
108. PLAB Assembler for PIC32 MCUs pic32 as generates errors warnings and mes sages A descriptive list of these outputs is shown here This list shows only the most common diagnostic messages from the assembler Topics covered in this appendix are Fatal Errors Errors e Warnings Messages B 2 FATAL ERRORS The following errors indicate that an internal error has occurred in the assembler Please contact Microchip Technology http support microchip com for support if the assembler generates any of the fatal errors listed below Be sure to provide full details about the source code and command line options causing the error Bad char c Bad defsym format is defsym name value Bad return from bfd install relocation x Broken assembler No assembly attempted Can t allocate elf private section data s Can t continue Can t create group 96s Can t extend frag u chars Can t open a bid on stdout s Can t start writing mdebug section s Cannot write to output file Could not write mdebug section 96s Dwarf2 is not supported for this object file format Emulations not handled in this configuration Error constructing s pseudo op table s Expr c operand bad atof generic return val d Failed sanity check Failed to read instruction table s n Failed to set up debugging information s Index into stored fixups out of bounds Inserting into symbol table failed s Internal bad mips opcode bits Ox l
109. REAL ICE system The box that contains the emulation control circuitry for the ICE device on the header or target board An ICE device can be a production device with built in ICE circuitry or a special ICE version of a production device i e device ICE MPLAB ICD 2 3 The box that contains the debug control circuitry for the ICD device on the header or target board An ICD device can be a production device with built in ICD circuitry or a special ICD version of a production device i e device ICD MPLAB ICE 2000 4000 The external emulator box that contains emulation memory trace memory event and cycle timers and trace breakpoint logic Power on Reset Emulation A software randomization process that writes random values in data RAM areas to simulate uninitialized values in RAM upon initial power application Pragma A directive that has meaning to a specific compiler Often a pragma is used to convey implementation defined information to the compiler MPLAB C30 uses attributes to convey this information Precedence Rules that define the order of evaluation in expressions PRO MATE II No longer in Production See the MPLAB PM3 device programmer A device programmer from Microchip Programs most PIC microcontrollers as well as most memory and KEELOO devices Can be used with MPLAB IDE or stand alone Profile For MPLAB SIM simulator a summary listing of executed stimulus by register Program Counter The location that cont
110. UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Table of Contents Part 1 MPLAB Assembler for PIC32 MCUS Chapter 1 Assembler Overview 1 1 WTEE OG UGG EE ON 17 1 2 Assembler and Other Development Tools seeeeee 17 1 3 FOUN Set ec 18 ele OPUS eelere Eege 19 Chapter 2 MPLAB IDE Projects for PIC32 Assembly Code 2 1 Introduction nnan nn aaaea aera ATEA a E ape els oae E a aiaa 25 2 2 Project Overview eege 25 2 3 Creating a Projet ee ette e t e PR eren ch ex rep Exc mu S E arcere 26 2 4 Adding a Source File to Your Project AA 29 2 5 Building Your Project zoo S oem tumet tetas tds 30 2 6 Debugging Your Project EE 31 Chapter 3 Assembler Command Line Interface Se e ee Te e EE E CL 33 3 2 Assembler Interface Syntax da 33 3 3 Compilation Driver Interface Syntax AAA 34 3 4 Options that Modify the Listing Output ssseeee 35 3 5 Options that Control Informational Output 46 3 6 Options that Control Output File Creation ooooccnncccc noniccccccnonacnncnanancnnnnnncno 47 3 7 Assembler Symbol Definition and Search Path Options 48 3 8 Compilation Driver and Preprocessor Options sseeseee 48 Chapter 4 Assembler Syntax 431 Introduction t ere erede iet 51 4 2 Internal Preprocessor oes e Hoc tnr ty taies M bonia Rp au a gae repu 51 4 3 Source Code BOITIER nito mer aas deat E 52 44 GONSIanis 12251909 4p adt erem dee ee 57 Ca SUMMAN tee ED D abd red
111. Us Missing argument s to option section start The required argument to section start must be sect ionname org 2009 Microchip Technology Inc DS51833A page 181 32 Bit Assembler Linker and Utilities User s Guide Multiple definition of name The linker discovered a symbol that is defined multiple times Eliminate the extraneous definition s Multiple start up files The linker script is attempting to set a start up file but a start up file has already been set There should be only one start up file specified in the linker script N No input files The linker did not find an input file specified on the command line There was nothing for the linker to do Check that you are passing the correct object file names to the linker Nonconstant expression for name name must be a nonconstant expression R region region is full filename section secname The memory region regionis full but section secname has been assigned to it Reloc refers to symbol name which is not being output An instruction references a symbol that is not being output Relocation truncated to fit relocation type name This error indicates that the relocated value of name is too large for its intended use This can happen when an address is out of range for the instruction in question Check that the symbol is both declared and defined in the intended section For instance a variable s declaration and definition must both be either const o
112. _endasm static Command line options Opa Opa Bit values 0 1 Constants OxFF A Italic Courier A variable argument file o where file can be any valid filename Square brackets Optional arguments mpasmwin options file options Curly brackets and pipe character Choice of mutually exclusive arguments an OR selection errorlevel 0 1 Ellipses Replaces repeated text var_name var_name Represents code supplied by user void main void 2009 Microchip Technology Inc DS51833A page 3 32 Bit Assembler Linker and Utilities User s Guide RECOMMENDED READING This documentation describes how to use 32 bit language tools Other useful documents are listed below The following Microchip documents are available and recommended as supplemental reference resources Readme Files For the latest information on Microchip tools read the associated Readme files HTML files included with the software MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 A guide to using the 32 bit C compiler The 32 bit linker is used with this tool 32 Bit Language Tools Libraries DS51685 A descriptive listing of libraries available for Microchip 32 bit devices This includes standard including math libraries and compiler built in functions 32 bit peripheral libraries are described in HTML files provided with each peripheral library type Device Specific Docume
113. a scratch regis ter By default the assembler will quietly use the at 1 register which is reserved as an assembler temporary by convention In some cases the compiler should not use that register The set noat directive prevents the assembler from quietly using that register set at Allow the assembler to quietly use the at 1 register Set noautoextend By default MIPS16 instructions are automatically extended to 32 bits when necessary The directive set noautoextend will turn this off When set noautoextend is in effect any 32 bit instruction must be explicitly extended with the e modifier e g li e 4 1000 The directive eer autoextend may be used to once again automat ically extend instructions when necessary Set autoextend Enable auto extension of MIPS16 instructions to 32 bits Set nomacro The assembler supports synthesized instructions an instruction mnemonic that syn thesizes into multiple machine instructions For instance the sleu instruction assem bles into an s1tu instruction and an xori instruction The set nomacro directive causes the assembler to emit a warning message when an instruction expands into more than one machine instruction Set macro Suppress warnings for synthesized instructions set mipsl6e Assemble with the MIPS16e ISA extension O 2009 Microchip Technology Inc DS51833A page 87 32 Bit Assembler Linker and Utilities User s Guide Set nomipsi6e
114. a values to include directly see Section 10 6 5 7 Output Section Data 10 6 5 6 OUTPUT SECTION ADDRESS The address is an expression for the VMA the virtual memory address of the output section If address is not provided the linker will set it based on region if present or otherwise based on the current value of the location counter If address is provided the address of the output section will be set to precisely that If neither address nor regionis provided then the address of the output section will be setto the current value of the location counter aligned to the alignment requirements of the output section The alignment requirement of the output section is the strictest alignment of any input section contained within the output section For example text text and text text are subtly different The first will set the address of the text output section to the current value of the location counter The second will set it to the current value of the location counter aligned to the strictest alignment of a text input section The address may be an arbitrary expression see Section 10 7 Expressions in Linker Scripts For example to align the section on a 0x10 byte boundary so that the lowest four bits of the section address are zero the command could look like this text ALIGN 0x10 text This works because ALIGN returns the current location counter aligned upward to the specified
115. aa laces 59 Chapter 5 Assembler Expression Syntax and Operation Se a e lee arn nn a a Aone E E AE EENES 61 EES e dE 61 GRO riu M ane ea ide 62 2009 Microchip Technology Inc DS51833A page iii 32 Bit Assembler Linker and Utilities User s Guide Chapter 6 Assembler Symbols 6 1 Mtr dUCtHON RE 65 6 2 What are Symbols iet ee t 65 E Enn 65 6 4 Giving Symbols Other Values AAA 66 6 5 The Special DOT Symbol cian eii 66 Chapter 7 Assembler Directives Ves M niger ee EMT 67 7 2 Directives that Define Sections EEN 68 7 3 Directives that Initialize Constants sssssemm 71 7 4 Directives that Declare Symbols AAA 74 7 5 Directives that Define Symbols AAA 75 7 6 Directives that Modify Section Alignment ooooonnccccnnnnncccccnnoccccnnnanaccnonannncnnn 76 7 7 Directives that Format the Output Listing seeeeeeee 78 7 8 Directives that Control Conditional Assembly sseesssssesss 79 7 9 Directives for Substitution Expansion eese 80 7 10 Directives that Include Other Files AAA 83 7 11 Directives that Control Diagnostic Output seeneeee 84 7 12 Directives for Debug Information ooconnnnononcccnnncncnnnnnnnononononnnnnnnnnnnnnnnnnnnnnnos 85 7 13 Directives that Control Code Generation E 87 Part 2 MPLAB Object Linker for PIC32 MCUs Chapter 8 Linker Overview EUM Introductio EE 91 8 2 Linker and Other
116. adix The number base hex or decimal used in specifying an address RAM Random Access Memory Data Memory Memory in which information can be accessed in any order Raw Data The binary representation of code or data associated with a section Read Only Memory Memory hardware that allows fast access to permanently stored data but prevents addition to or modification of the data Real Time When an in circuit emulator or debugger is released from the Halt state the processor runs in Real Time mode and behaves exactly as the normal chip would behave In Real Time mode the real time trace buffer of an emulator is enabled and constantly captures all selected cycles and all break logic is enabled In an in circuit emulator or debugger the processor executes in real time until a valid breakpoint causes a Halt or until the user halts the execution In the simulator real time simply means execution of the microcontroller instructions as fast as they can be simulated by the host CPU Real Time Watch A Watch window where the variables change in real time as the application is run See individual tool documentation to determine how to set up a real time watch Not all tools support real time watches Recursive Calls A function that calls itself either directly or indirectly Recursion The concept that a function or macro having been defined can call itself Great care should be taken when writing recursive macros it is easy to ge
117. ains the address of the instruction that is currently executing Program Counter Unit ALU30 A conceptual representation of the layout of program memory The program counter increments by 2 for each instruction word In an executable section 2 program counter units are equivalent to 3 bytes In a read only section 2 program counter units are equivalent to 2 bytes Program Memory IDE The memory area in a device where instructions are stored Also the memory in the emulator or simulator containing the downloaded target application firmware ALUSO C30 The memory area in a device where instructions are stored Project A project contains the files needed to build an application source code linker script files etc along with their associations to various build tools and build options Prologue A portion of compiler generated code that is responsible for allocating stack space pre serving registers and performing any other machine specific requirement specified in the runtime model This code executes before any user code for a given function Prototype System A term referring to a user s target application or target board DS51833A page 206 2009 Microchip Technology Inc Glossary PWM Signals Pulse Width Modulation Signals Certain PIC MCU devices have a PWM peripheral Qualifier An address or an address range used by the Pass Counter or as an event before another operation in a complex trigger R
118. ames processed when the modifier v is appended This modifier shows the version number of the 32 bit archiver librarian DS51833A page 144 2009 Microchip Technology Inc MPLAB Object Archiver Librarian for PIC32 MCUs 12 7 SCRIPTS If you use the single command line option M with the archiver you can control its operation with a rudimentary command language pic32 ar M SCRIPT This form of the 32 bit archiver librarian operates interactively if standard input is com ing directly from a terminal During interactive use the archiver prompts for input the prompt is AR gt and continues executing even after errors If you redirect standard input to a script file no prompts are issued and the 32 bit archiver librarian abandons execution with a nonzero exit code on any error The archiver command language is not designed to be equivalent to the command line options in fact it provides somewhat less control over archives The only purpose of the command language is to ease the transition to the 32 bit archiver librarian for devel opers who already have scripts written for the MRI librarian program The syntax for the 32 bit archiver librarian command language is straightforward commands are recognized in upper or lowercase for example LIST is the same as list In the following descriptions commands are shown in uppercase for clarity a single command may appear on each line it is the
119. an unexpected operator type Bad register expression The DWARF debugging directive has an invalid register expression Bignum invalid The bignum value specified in the expression is not valid C Can t parse register list In MIPS16 mode the register list is invalid Can t resolve value for symbol s The assembler could not get a real value for the symbol Constant too large When sign extending a constant offset from a base register the constant was too large Could not skip to num in file filename The skip parameter to the incbin directive was invalid for the given file D Duplicate else Each if directive can have only up to one corresponding else directive E End of file inside conditional The assembler identified a missing conditional end directive Terminate the conditional before the end of the file End of macro inside conditional The assembler identified a missing macro end directive Terminate the macro before the end of the file Expected address expression The expression was illegal absent or bignum but it should have been a constant adaress Expected comma after s The arguments for this directive must be separated by a comma Expected comma after name s in size directive The arguments for this directive must be separated by a comma Expected quoted string The argument should be a quoted string Expected simple number This argument must be a simple number Exp
120. ananacnanarcanin canoa canoas 68 TEEN 80 81 83 oj ene ES 83 A RR RCM OPEM IPS 85 O RII Re 9 A LU E 75 el EE 78 COME 75 SECTION name 69 Ol A s ee o I eere Lee ue 84 SOL at Lise eee eee 87 GEIER A EL M mun 84 A RN 87 A A Ee 80 82 Set macro ENEE 87 E EE 74 et MipST concoccncnnaconincncoriononinnorinnoraninnarinnoran coronan 87 O a deat caAa hace Vat tte 84 HE 87 AAA AN A E ee 85 el moautoenslenmd ENEE 87 TER 76 SO MOMACTO ENEE 87 A E M NL E 72 set nomips16e sssssseeeenn 88 dash end S sce e E N EL R 85 el NOPEOEL ENEE 88 tamen Rn EE 86 el reorder ENEE 88 TEE deett cate LU AE 9 SNO aa 73 doble nk rr mi teleco ade rio E 74 e EE 72 TEE 74 size EE 86 e WEE 72 SD etie ettet fatis otim ds 77 ideritc e enden i E 84 Sleb128 ssssssssssssseeeneeneeeene 86 E 79 Dag es 77 jw vom Ong UO rM RS 79 EU 5 78 lee eier eene 79 SlrUCE Leisure 77 leg E E E A 79 Je i ose lei EE E EE 71 HOS AE EEEE SAA E 79 text section EE 104 RUM ME A Ht 79 ume ee dee Dese 78 Lo MN Ee VE 80 D 86 EE 80 BU 86 HM ecc E RUE E 80 M 85 Lo oM MES DRM RC CERCA 80 KC 85 del cesses etti E 80 week 75 136 del EE EE 73 O 2009 Microchip Technology Inc DS51833A page 213 32 Bit Assembler Linker and Utilities User s Guide uc N 101 or 82 A cC ETHER EESTI ER 35 SOUL Rs EE hos 21 47 103 a file cocoocccccccccccncnonanananananono nono nonnnnnn nono nono nono nonanannnnos 44 A gan E etal eee thee 36
121. andard Libraries lent to O option To see optimization for the following conditions check the check box Exclude standard libraries Generate 16 bit code Exclude floating point library Use Alternate Settings Text Box Enter options in a command line non GUI format Build Options Dialog PIC32 Suite Tab Select a category and then set up output options General All Options Generate Command Line Target Type Build normal target invoke PIC32 linker The files in the project will be built for normal output using the PIC32 linker hex file etc To set linker options see Build Options Dialog MPLAB PIC32 Linker Tab Don t link startup code To exclude the addition of start up code in the build check this checkbox Build library target invoke PIC32 archiver The files in the project will be built into a library using the PIC32 librarian archive file For a library build a generic device family library may be built by checking Build generic library For more on libraries see PIC32 archiver librarian documenta tion c t 2009 Microchip Technology Inc DS51833A page 13 32 Bit Assembler Linker and Utilities User s Guide PROJECT EXAMPLE Chapter 2 MPLAB IDE Projects for PIC32 Assembly Code covers the basics of MPLAB IDE projects setup and use for the assembler For more detailed information on projects see MPLAB IDE documentation
122. andards in the United States Application A set of software and hardware that may be controlled by a PIC microcontroller 2009 Microchip Technology Inc DS51833A page 193 MPLAB Assembler Linker and Utilities for PIC32 Archive A collection of relocatable object modules It is created by assembling multiple source files to object files and then using the archiver to combine the object files into one library file A library can be linked with object modules and other libraries to create executable code Archiver A tool that creates and manipulates libraries ASCII American Standard Code for Information Interchange is a character set encoding that uses 7 binary digits to represent each character It includes upper and lowercase letters digits symbols and control characters Assembler A language tool that translates assembly language source code into machine code Assembly Language A programming language that describes binary machine code in a symbolic form Assigned Section A section which has been assigned to a target memory block in the linker command file Asynchronously Multiple events that do not occur at the same time This is generally used to refer to interrupts that may occur at any time during processor execution Asynchronous Stimulus Data generated to simulate external inputs to a simulator device Attribute Characteristics of variables or functions in a C program which are used to describe machine specif
123. ange to some other section before further assembly 2009 Microchip Technology Inc DS51833A page 77 32 Bit Assembler Linker and Utilities User s Guide 7 7 DIRECTIVES THAT FORMAT THE OUTPUT LISTING Output listing format directives are eject list nolist psize lines columns sbttl subheading title heading eject Force a page break at this point when generating assembly listings list Controls in conjunction with nolist whether assembly listings are generated This directive increments an internal counter which is one initially Assembly listings are generated if this counter is greater than zero Only functional when listings are enabled with the a command line option and forms processing has not been disabled with the an command line option nolist Controls in conjunction with 1ist whether assembly listings are generated This directive decrements an internal counter which is one initially Assembly listings are generated if this counter is greater than zero Only functional when listings are enabled with the a command line option and forms processing has not been disabled with the an command line option psize lines columns Declares the number of lines and optionally the number of columns to use for each page when generating listings If you do not use psize listings use a default line count of 60 You may omit the comma and columns specification
124. anguage Command Line Interface Integrated component of MPLAB IDE DS51833A page 18 2009 Microchip Technology Inc Assembler Overview 1 4 INPUT OUTPUT FILES Standard assembler input and output files are listed below Extension Description Input sS Preprocessed Source File 8 Source File Output O Object File lst Listing File Unlike the MPASM assembler for use with 8 bit PIC MCUs MPLAB Assembler for PIC32 MCUS does not generate error files hex files or symbol and debug files The assembler is capable of creating a listing file and a relocatable object file that may or may not contain debugging information MPLAB Linker for PIC32 MCUs is used with the assembler to produce the final object files map files and final executable file for debugging with MPLAB IDE see Figure 1 1 1 4 1 Source Files The assembler accepts as input a source file that consists of PIC32 instructions assembler directives and comments A sample source file is shown in Example 1 1 Note Microchip Technology strongly suggests a S extension for assembly source files This will enable you to easily use the C compiler driver without having to specify the option to tell the driver that the file should be treated as an assembly file The capitalized S also indicates that the source file should be preprocessed by the C preprocessor before being passed to the assembler See the MPLAB C Compiler for P
125. ar tv SAVE Commits your changes to the current archive and actually saves it as a file with the name specified in the last CREATE or OPEN command Requires prior use of OPEN or CREATE DS51833A page 146 2009 Microchip Technology Inc Y MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 13 Other PIC32 MCU Binary Utilities 13 14 INTRODUCTION Besides the MPLAB Object Archiver Librarian for PIC32 MCUs pic32 ar there are several other binary utilities available for use with the PIC32 MCU assembler and linker Topics covered in this chapter are Utility Description pic32 bin2hex Utility Converts a linked object file into an Intel hex file pic32 nm Utility Lists symbols from an object file pic32 objdump Utility Displays information about object files pic32 ranlib Utility Generates an index from the contents of an archive and stores it in the archive pic32 size Utility List file section sizes and total size pic32 strings Utility Prints the printable character sequences pic32 strip Utility Discards all symbols from an object file 13 2 pic32 bin2hex UTILITY The binary to hexadecimal pic32 bin2hex utility converts binary files from the 32 bit linker to Intel hex format files suitable for loading into device programmers Input Output Files Syntax Options 13 2 1 Input Output Files Input ELF
126. are not in windowed packages Since EPROM needs ultraviolet light to erase its memory only windowed devices are eras able Pass Counter A counter that decrements each time an event such as the execution of an instruction at a particular address occurs When the pass count value reaches zero the event is satisfied You can assign the Pass Counter to break and trace logic and to any sequential event in the complex trigger dialog PC Personal Computer or Program Counter PC Host Any PC running a supported Windows operating system Persistent Data Data that is never cleared or initialized Its intended use is so that an application can preserve data across a device reset Phantom Byte An unimplemented byte in the dsPIC architecture that is used when treating the 24 bit instruction word as if it were a 32 bit instruction word Phantom bytes appear in dsPIC hex files PIC MCUs PIC microcontrollers MCUs refers to all Microchip microcontroller families PICSTART Plus A developmental device programmer from Microchip Programs 8 14 28 and 40 pin PIC microcontrollers Must be used with MPLAB IDE software Plug ins The MPLAB IDE has both built in components and plug in modules to configure the system for a variety of software and hardware tools Several plug in tools may be found under the Tools menu 2009 Microchip Technology Inc DS51833A page 205 MPLAB Assembler Linker and Utilities for PIC32 Pod MPLAB
127. atements onto the end of the text executable code section Example text ent main entry main entry jal main nop jal exit nop b 1b nop end main entry 7 3 DIRECTIVES THAT INITIALIZE CONSTANTS Constant initialization directives are ascii string string asciz strings Lo stringy e byte expri exprjl e double value value e float value l value e single value value hword expri exprjl e Ant expr Expr Long expri exprjl short expri exprjl String str e word expr exprjl ascii string string ascii expects zero or more string literals separated by commas It assembles each string with no automatic trailing zero byte into consecutive addresses asciz string string 2 asciz is just like ascii but each string is followed by a zero byte The z in asciz stands for zero This directive is a synonym for string byte expr expr byte expects zero or more expressions separated by commas Each expression is assembled into the next byte in the current section 2009 Microchip Technology Inc DS51833A page 71 32 Bit Assembler Linker and Utilities User s Guide double value value Assembles one or more double precision 64 bit floating point constants into consecutive addresses in little en
128. ation Directives Sende artt a MEE EIE 85 ensis adi dot 85 Ma eege eege Ke 85 Mask t teste rh ie ei A 85 Tarte at tomo atem ut wo Misa a M fe 86 e HH mr 86 mask attire EN 86 Lipi ege ee ee ER 86 Geh e EES 86 Ay pe ote ertet en 86 leb128 ee i AE 86 DS51833A page 214 2009 Microchip Technology Inc Declare Symbols Directives ohne IM 74 A UR 74 Global eu ted 74 A teats 74 ICOMMs iia ani 74 Weak coc id 75 Define Symbols Directives e EE 75 AQUI 75 DEFINED iter ti 132 OS UE 48 102 defsyms min heap stze reesen 106 defsym min stack size 106 Diagnostic Control Directives ADOM fe 84 ett sisse heu xv 84 EE oeren Zeie EE it 84 A ee eb t Ren 84 le EE eio deut 84 D IERE de e ELEC ede att 84 V loe eene Seege EE ib ende 85 MAI tae 85 Directives lte lu iini tenete 76 Assembler 5 5 rl toe 67 Conditional sies eee teens 79 Debug Information sses 85 Declare Symbols sess 74 Define Symbols esses 75 lw UE e EE 71 Miscellaneous ooocconoccccnnccconcccccnnconnnccccnnnnnnnnns 84 Output listing terree 78 Bechen e ete aee veteris 68 Substitution Expansion ooocccicccnnconoccnincnnncccanno 80 discard all 2 deen Ep me dd 102 discara locals 2 idee BRI Eti 102 Documentation Conventions cocoocccooccconoconononcnnnnnnnnnnnncnonncconnnnnnonnos 3 LayOQut een ai 2 DOT Symbol 25i pesi 66 Dot Varlable 1 td e 128 m lc
129. ator In this MPLAB IDE project C source files are shown as input to the C compiler MPLAB C Compiler for PIC32 MCUs The compiler will generate source files for input into the assembler For more information on the compiler see the compiler documentation listed in Recommended Reading Assembly source files are shown as input to the C preprocessor The resulting source files are input to the assembler The assembler will generate object files for input into the linker or archiver For more information on the assembler see the MPLAB Assembler for PIC32 MCUs documentation Object files can be archived into a library using the archiver librarian For more information on the archiver see the MPLAB Archiver Librarian for PIC32 MCUs documentation The object files and any library files as well as a linker script file generic linker scripts are added automatically are used to generate the project output files via the linker The main output file generated by the linker is the executable file used by the simulator and debug tools For more information on linker script files and using the object linker see the MPLAB Object Linker for PIC32 MCUs documentation For more on projects and related workspaces see MPLAB IDE documentation 2009 Microchip Technology Inc DS51833A page 9 32 Bit Assembler Linker and Utilities User s Guide PROJECT SETUP To set up an MPLAB IDE project for the first time it is advisable to use
130. bits 2009 Microchip Technology Inc DS51833A page 211 MPLAB Assembler Linker and Utilities for PIC32 WDT See Watchdog Timer Workbook For MPLAB SIM stimulator a setup for generation of SCL stimulus WorkSpace A workspace contains MPLAB IDE information on the selected device selected debug tool and or programmer open windows and their location and other IDE configuration settings DS51833A page 212 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Index Symbols MOCOS mtem tetti 80 MVC eee RN IEEE ee eee 66 i RES ADOH esum nee Sah muera i ce a et eL a ee 84 Mialee eS o emu statt tar Mons EE 80 A Leer MELIA 76 ERE 83 IEN 71 dnelude ue 48 51 84 e A ee ah Pics oh 71 AE 73 O cu pos fal ev LUPA MIEL aUe Ef 68 Jm Wed a E Cb me AE WERNER SE d kee Geld 80 DSS SECTION DONN 1 04 121 irpc SEN EE d PM ees EN A A A 71 Meo 74 bee CES 9 A NOROESTE E het AAE AATRE 78 AN 74 A oh E E EEEE ETT 86 comm symbol Jeng 74 MONG etie ete ete debes 73 e PARES NEMO tee Be 68 BEE 81 data section 104 MAS ntn 86 OUP EEN 72 noliet na nano no nono nono nn cnn rca nana nanos 78 EE EE S MP uri T 78 Kop eta 76 else uet n e utes ctf et reete dere 79 popsection eene nennen nennen tenente tenentes 69 ET SEENEN 79 DO is EL 84 o A A PLE ER 85 POSI 78 a o a EU 79 juu 83 endm DEE 82 pushsection c cccncacacornnnorincononancnninc
131. bol references have matching definitions External symbols that are defined as weak receive special processing as explained in Section 11 4 Global and Weak Symbols If any external symbol reference remains undefined an error is generated 11 2 4 Computing Absolute Addresses After the special sections have been created the final sizes of all output sections are known The linker then computes absolute addresses for all output sections and external symbols Each output section is checked to make sure it falls within its assigned memory regions If any section falls outside of its memory region an error is generated Any symbols defined in the linker script are also computed 11 2 5 Building the Output File Finally the linker builds the output file Relocation entries in each section are patched using absolute addresses If the address computed for a symbol does not fit in the relocation entry a link error results This can occur for example when one module ref erences a variable which it thinks is in a small data section while the other defines it in a non small section A link map is also generated if requested with the appropriate option The link map includes a memory usage report which shows the starting address and length of all sections in data memory and program memory For more information about the link map see Section 8 4 5 Map File DS51833A page 134 2009 Microchip Technology Inc Linker Processing
132. cate successful completion This command does not save the output file if you have changed the current archive since the last SAVE command those changes are lost i EXTRACT MODULE MODULE MODULE I Extract each named MODULE from the current archive writing them into the current directory as separate files Equivalent to pic32 ar x ARCHIVE MODULE Requires prior use of OPEN or CREATE LIST Display full contents of the current archive in verbose style regardless of the state of VERBOSE The effect is like pic32 ar tv ARCHIVE This single command is a 32 bit archiver librarian enhancement rather than present for MRI compati bility Requires prior use of OPEN or CREATE OPEN ARCHIV DI Opens an existing archive for use as the current archive required for many other commands Any changes as the result of subsequent commands will not actually affect ARCHIVE until you next use SAVE A REPLACE MODULE MODULE MODULE In the current archive replace each existing MODULE named in the REPLACE arguments from files in the current working directory To execute this command without errors both the file and the module in the current archive must exist Requires prior use of OPEN or CREATE VERBOSE Toggle an internal flag governing the output from DIRECTORY When the flag is on DIRECTORY output matches output from pic32
133. ce saying this License applies to the Document are reproduced in all copies and that you add no other conditions whatsoever to those of this License You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute However you may accept compensation in exchange for copies If you distribute a large enough number of copies you must also follow the conditions in section 3 You may also lend copies under the same conditions stated above and you may publicly display copies EA COPYING IN QUANTITY If you publish printed copies or copies in media that commonly have printed covers of the Document numbering more than 100 and the Documents license notice requires Cover Texts you must enclose the copies in covers that carry clearly and legibly all these Cover Texts Front Cover Texts on the front cover and Back Cover Texts on the back cover Both covers must also clearly and legibly identify you as the publisher of these copies The front cover must present the full title with all words of the title equally prominent and visible You may add other material on the covers in addition Copying with changes limited to the covers as long as they preserve the title of the Document and satisfy these conditions can be treated as verbatim copying in other respects If the required texts for either cover are too voluminous to fit legibly you should put the first ones listed as many as fit r
134. ch a section may not be included in the Modified Version n Do notretitle any existing section to be Entitled Endorsements or to conflict in title with any Invariant Section o Preserve any Warranty Disclaimers DS51833A page 190 O 2009 Microchip Technology Inc GNU Free Documentation License If the Modified Version includes new front matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document you may at your option designate some or all of these sections as invariant To do this add their titles to the list of Invariant Sections in the Modified Version s license notice These titles must be distinct from any other section titles You may add a section Entitled Endorsements provided it contains nothing but endorsements of your Modified Version by various parties for example statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard You may add a passage of up to five words as a Front Cover Text and a passage of up to 25 words as a Back Cover Text to the end of the list of Cover Texts in the Modified Version Only one passage of Front Cover Text and one of Back Cover Text may be added by or through arrangements made by any one entity If the Document already includes a cover text for the same cover previously added by you or by arrangement made by the same entity you are acting on behalf of you may not
135. chip Technology Inc Linker Processing bmxdupba address LENGTH ksegl data mem The actual top of stack should include the gap between the stack section and the beginning of the ramfunc gection caused by the alignment of the ramfunc section minus 1 word If RAM functions do not exist then the top of the stack should point to the end of the data memory Stack ramfunc length gt 0 ramfunc begin 4 2 ORIGIN ksegl data mem LENGTH ksegl1 data mem Notice that the linker script defines a required stack symbol at the beginning of the ramfunc section When RAM functions don t exist the _ stack symbol points to the end of data memory This means that the effective stack is the entire space between the heap and the ramfunc section or the end of data memory The linker s reported size of the stack section is the minimum size required to avoid a link error The effective stack size is usually larger than the reported stack section size 11 6 HEAP ALLOCATION The C runtime heap is an uninitialized area of data memory that is used for dynamic memory allocation using the standard C library dynamic memory management func tions calloc malloc and realloc If you do not use any of these functions directly or indirectly then you do not need to allocate a heap By default the heap size is 0 If you do want to use dynamic memory allocation either directly by calling one of the memory allocation f
136. chip Technology Inc DS51833A page 65 32 Bit Assembler Linker and Utilities User s Guide label 2 b label 1 label 3 b label 4 label 4 b label 3 Local symbol names are only a notational device They are immediately transformed into more conventional symbol names before the assembler uses them These conven tional symbol names are stored in the symbol table and appear in error messages and optionally emitted to the object file 6 4 GIVING SYMBOLS OTHER VALUES A symbol can be given an arbitrary value by writing a symbol followed by an equals sign followed by an expression Example VAR 4 6 5 THE SPECIAL DOT SYMBOL The special symbol refers to the current address being processed by the assembler Thus the expression melvin long defines melvin to contain its own address Assigning a value to is treated the same as a org directive Thus the expression 2 4 is the same as saying space 4 When used in an executable section refers to a Program Counter address On a PIC32 MCU the Program Counter increments by 4 for each 32 bit instruction word User code should take care to properly align instructions after modifying the dot symbol DS51833A page 66 2009 Microchip Technology Inc Y MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 7 Assembler Directives 7 1 INTRODUCTION Directives are assembler commands that appear in the sourc
137. clear bit relevant to pin 32 7 in port A The jal instruction places DS51833A page 22 O 2009 Microchip Technology Inc Assembler Overview 33 the return address in ra 34 35 0000 80000434 ori Sat zero IOPORT BIT 7 36 0004 0500000C jal mPORTAClearBits 37 0008 00000000 nop 38 39 endless loop 40 endless 41 000c 03000008 j endless 42 0010 00000000 nop 43 44 end baz directive that marks end of baz 45 function and registers size in ELF 46 output 47 DEFINED SYMBOLS ABS 00000000 foo S ABS 00000001 DEBUG foo S 56 text 00000014 mPORTAClearBits foo S 38 text 0000000c endless 2009 Microchip Technology Inc DS51833A page 23 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 24 O 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 2 MPLAB IDE Projects for PIC32 Assembly Code 2 1 INTRODUCTION This section covers the basics of MPLAB IDE projects and configuration options for testing the examples and applications in this guide with MPLAB SIM simulator Skip this chapter if you are already familiar with these MPLAB IDE operations or intend to use the assembler for a command line interface Note This is not a step by step procedure to create and build a project but an overview and a checklist to ensure that MPLAB IDE is set up correctly The MPLAB IDE User s Guide ha
138. code and data which the linker will allocate into target memory The entire process is controlled by a linker script also known as a link command file A linker script is required for every link The link process may be broken down into 5 steps 1 Loading Input Files 2 Allocating Memory 3 Resolving Symbols 4 Computing Absolute Addresses 5 Building the Output File 11 2 14 Loading Input Files The initial task of the linker is to interpret link command options and load input files If a linker script is specified that file is opened and interpreted Otherwise an internal default linker script is used In either case the linker script provides a description of the target device including specific memory region information See Chapter 10 Linker Scripts for more details Next the linker opens all of the input object files Each input file is checked to make sure the object format is compatible If the object format is not compatible an error is generated The contents of each input file are then loaded into internal data structures Typically each input file will contain multiple sections of code or data Each section contains a list of relocation entries which associate locations in a section s raw data with relocatable symbols 2009 Microchip Technology Inc DS51833A page 133 32 Bit Assembler Linker and Utilities User s Guide 11 2 2 Allocating Memory After all of the input files have been loaded the linker allocat
139. cont lines option is used to set the maximum number of continu ation lines used for the output data column of the listing By default this is 8 The fol lowing lines are extracted from a listing that was created without using the listing cont lines option The text in bold shows the continuation lines used for the output data column of the listing 2 0000 54686973 ascii This is a long character sequence 2 20697320 2 61206C6F 2 6E672063 2 68617261 Notice that the number of bytes displayed matches the number of bytes in the ASCII string however if the option listing cont lines 2 is used then the output data will be truncated after 2 continuation lines as shown below 2 0000 54686973 ascii This is a long character sequence 2 20697320 2 61206C6F 3 5 OPTIONS THAT CONTROL INFORMATIONAL OUTPUT The options in this section control how information is output Errors warnings and messages concerning code translation and execution are controlled through several of the options in this section Any item in parenthesis shows the short method of specifying the option e g no warn also may be specified as w 3 5 1 fatal warnings Warnings are treated as if they were errors 3 5 2 no warn W Warnings are suppressed If you use this option no warnings are issued This option only affects the warning messages It does not change how your file is assembled Errors are still reported 3 5 3 warn Warnings are i
140. ctions A file name can be specified to include sections from a particular file This would be useful if one of the files contain special data that needs to be at a particular location in memory For example data o data If a file name is specified without a list of sections then all sections in the input file will be included in the output section This is not commonly done but it may be useful on occasion For example data o When a file name is specified which does not contain any wildcard characters the linker will first see if the file name was also specified on the linker command line or in an INPUT command If not the linker will attempt to open the file as an input file as though it appeared on the command line This differs from an INPUT command because the linker will not search for the file in the archive search path 10 6 5 2 INPUT SECTION WILDCARD PATTERNS In an input section description either the file name or the section name or both may be wildcard patterns The file name of seen in many examples is a simple wildcard pattern for the file name 2009 Microchip Technology Inc DS51833A page 119 32 Bit Assembler Linker and Utilities User s Guide The wildcard patterns are like those used by the UNIX shell matches any number of characters matches any single character chars matches a single instance of any of the chars the character may be used to specify a range of characters as in a z
141. d A is the revision level of the document For the most up to date information on development tools see the MPLAB IDE on line help Select the Help menu and then Topics to open a list of available on line help files INTRODUCTION This chapter contains general information that will be useful to know before using 32 bit language tools Items discussed include Document Layout Conventions Used in this Guide Recommended Reading The Microchip Web Site Development Systems Customer Change Notification Service Customer Support 2009 Microchip Technology Inc DS51833A page 1 32 Bit Assembler Linker and Utilities User s Guide DOCUMENT LAYOUT This document describes how to use GNU language tools to write code for 32 bit applications The document layout is as follows 32 Bit Language Tools and MPLAB IDE an overview of using the 32 bit language tools with MPLAB IDE Part 1 MPLAB Assembler for PIC32 MCUs Chapter 1 Assembler Overview gives an overview of assembler operation Chapter 2 MPLAB IDE Projects for PIC32 Assembly Code provides an overview of using the PIC32 language tools with MPLAB IDE in a project Chapter 3 Assembler Command Line Interface details command line options for the assembler Chapter 4 Assembler Syntax describes syntax used with the assembler Chapter 5 Assembler Expression Syntax and Operation provides guide
142. d Utilities User s Guide NOTES DS51833A page 184 2009 Microchip Technology Inc Y MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Appendix D Useful Tables D 1 INTRODUCTION Some useful tables are included for reference The tables are ASCII Character Set Hexadecimal to Decimal Conversion D 2 ASCII CHARACTER SET This table lists the ASCII standard character set Most Significant Character Hex 0 1 2 3 4 5 6 7 0 NUL DLE Space 0 P p 1 SOH DC1 1 A Q a q 2 STX DC2 2 B R b r 3 ETX DC3 3 C S C S 4 EOT DC4 4 D T d t 5 ENQ NAK 5 E U e u Least 6 ACK SYN amp 6 F V f v Significant 7 Bell ETB 7 G W g w Character g BS CAN 8 H X h x 9 HT EM 9 Y i y A LF SUB i E J Z j Z B VT ESC K k C FF FS L D CR GS M m E SO RS gt N A n F Sl US O o DEL 2009 Microchip Technology Inc DS51833A page 185 32 Bit Assembler Linker and Utilities User s Guide D 3 HEXADECIMAL TO DECIMAL CONVERSION This table describes how to convert hexadecimal to decimal For each hex digit find the associated decimal value Add the numbers together High Byte Low Byte Hex 1000 Dec Hex 100 Dec Hex 10 Dec Hex 1 Dec 0 0 0 0 0 0 0 0 1 4096 1 256 1 16 1 1 2 8192 2 5
143. d any sections Entitled Dedications You must delete all sections Entitled Endorsements E 7 COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License and replace the individual copies of this License in the various documents with a single copy that is included in the collection provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects You may extract a single document from such a collection and distribute it individually under this License provided you insert a copy of this License into the extracted document and follow this License in all other respects regarding verbatim copying of that document 2009 Microchip Technology Inc DS51833A page 191 32 Bit Assembler Linker and Utilities User s Guide E 8 AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works in or on a volume of a storage or distribution medium is called an aggregate if the copyright resulting from the compilation is not used to limit the legal rights of the compilation s users beyond what the individual works permit When the Document is included an aggregate this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document Ifthe Cover Text requirement of section 3 is applicable t
144. d sections Symbol Definitions Add or remove symbol definitions Restore Defaults Restore tab default settings Use Alternate Settings Text Box Enter options in a command line non GUI format Diagnostics Category Generate Command Line Generate map file Create a map file Same as Map file option Generate cross refer ence file Create a cross reference table Same as cref option Warn on section realign ment Warn if start of section changes due to alignment Same as warn section align option Trace Symbols Add or remove trace symbols Restore Defaults Restore tab default settings Use Alternate Settings Text Box Enter options in a command line non GUI format DS51833A page 12 2009 Microchip Technology Inc 32 Bit Language Tools and MPLAB IDE Symbols and Output Category Generate Command Line Symbols Specify symbol information in the output Keep all Strip debugging info strip debug S Strip all symbol info strip all s Output Filename Root Enter a root directory for saving output files Restore Defaults Restore tab default settings Use Alternate Settings Text Box Enter options in a command line non GUI format Library Selection Category Generate Command Line Optimization Level of Click in a circle on the chart to select an optimization level Equiva St
145. d symbols that are included in the link as specified in the linker script Outside Cross Reference Table optional shows symbols sorted by name For each symbol a list of file names is given If the symbol is defined the first file listed is the location of the definition The remaining files listed contain references to the symbol DS51833A page 94 2009 Microchip Technology Inc EXAMPLE 8 2 MAP FILE Linker Overview Archive member included because of file symbol size libc a general exception o size crt0 o size libc a defaul size libc size libc a defaul size crt0 o size libc a default on reset o size crt0 o on reset size libc a default on bootstrap o size crt0 o size libc a default nmi handler o size crt0 o nmi handler Microchip PIC32 Memory Usage Report kseg0 Program Memory Usage _on bootstrap _general_exception context t general exception handler o a general exception o t bootstrap exception handler o bootstrap exception handler general exception handler section address length dec Description text 0x9d000000 0x678 1656 Application s executable code rodata 0x9d000678 0x14 20 Read only constant data data 0x9d00068c Oxf 244 Data initialization template Sdata 0x9d000780 0x4 4 Small data initialization template Total kseg0 program mem used 0x784 1924 0 4 of 0x80000 kseg0 Boot Memory Usage section address length dec Description Startup 0x9fc00490 0xl1le0
146. d that you release the Modified Version under precisely this License with the Modified Version filling the role of the Document thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it In addition you must do these things in the Modified Version a Usein the Title Page and on the covers if any a title distinct from that of the Document and from those of previous versions which should if there were any be listed in the History section of the Document You may use the same title as a previous version if the original publisher of that version gives permission b Listonthe Title Page as authors one or more persons or entities responsible for authorship of the modifications in the Modified Version together with at least five of the principal authors of the Document all of its principal authors if it has fewer than five unless they release you from this requirement C State on the Title page the name of the publisher of the Modified Version as the publisher d Preserve all the copyright notices of the Document e Add an appropriate copyright notice for your modifications adjacent to the other copyright notices f Include immediately after the copyright notices a license notice giving the public permission to use the Modified Version under the terms of this License in the form shown in the Addendum below g Preserve in that license notice the full lists of Invariant Sections and
147. deemed to have the value 8 frame outside of ent The frame directive describes the stack frame and therefore must be used within a function incbin count zero ignoring filename The incbin count should be greater than zero reading zero bytes from a file has no effect mask fmask outside of ent The mask fmask stack frame information should be defined within a ent function Make sure that the mask fmask directive is positioned correctly within the source code popsection without corresponding pushsection ignored 2009 Microchip Technology Inc DS51833A page 175 32 Bit Assembler Linker and Utilities User s Guide The assembler cannot pop a section off of the section stack without pushing one onto the stack first previous without corresponding section ignored There s no previous section swap with the current section Make sure that the pre vious directive is positioned correctly within the source code Space repeat count is negative ignored The space size argument must be greater than 0 Space repeat count is zero ignored The space size argument must be greater than 0 A Alignment negative 0 assumed The align alignment must be a non negative power of two value align 0 turns off the automatic alignment used by the data creating pseudo ops Alignment too large 15 assumed The align alignment value is greater than 15 The valid range is 0 15 D Divide by zero
148. define symbol in your partial program its value is made available to other partial programs that are linked with it Otherwise symbol takes its attributes from a symbol of the same name from another file linked into the same program Both spellings glob1 and global are accepted for compatibility with other assemblers lcomm symbol length Reserve length bytes for a local common denoted by symbol The section and value of symbol are those of the new local common The addresses are allocated in the bss section so that at run time the bytes start off zeroed symbol is not declared global so it is normally not visible to the linker DS51833A page 74 2009 Microchip Technology Inc Assembler Directives weak symbol Marks the symbol named symbo1 as weak When a weak defined symbolis linked with a normal defined symbol the normal defined symbol is used with no error When a weak defined symbol is linked and the symbol is not defined the value of the weak symbol becomes zero with no error 7 5 DIRECTIVES THAT DEFINE SYMBOLS Define symbol directives are equ symbol expression equiv symbol expression equ symbol expression This directive sets the value of symbol to expression You may set a symbol any number of times in assembly If you set a global symbol the value stored in the object file is the last value equated to it equiv symbol expression Like equ except that the assembler will signal a
149. dian format Floating point numbers are in IEEE format see Section 4 4 1 2 Floating Point Numbers The following statements are equivalent double 12345 67 double 1 234567e4 double 1 234567e04 double 1 234567e 04 double 1 234567E4 double 234567E04 double 1 234567E 04 T 1 1 I Alternatively you can specify the hexadecimal encoding of a floating point constant The following statements are equivalent and encode the value 12345 67 as a 64 bit double precision number double 0e 40C81CD5C28F5C29 double 0f 40C81CD5C28F5C29 double 0d 40C81CD5C28F5C29 float value value Assembles one or more single precision 32 bit floating point constants into consecutive addresses in little endian format It has the same effect as single Floating point numbers are in IEEE format see Section 4 4 1 2 Floating Point Numbers The following statements are equivalent float 12345 67 float 1 234567e4 float 1 234567e04 float 1 234567e 04 float 1 234567E4 float 1 234567E04 float 1 234567E 04 Alternatively you can specify the hexadecimal encoding of a floating point constant The following statements are equivalent and encode the value 12345 67 as a 32 bit double precision number float 0e 4640E6AE float 0f 4640E6AE float 0d 4640E6AE Single value value l Assembles one or more single precision 32 bit floating point constants into consecutive addresses in little endian format T
150. dress is stored when a function call is made Stack Software Memory used by an application for storing return addresses function parameters and local variables This memory is typically managed by the compiler when developing code in a high level language Static RAM or SRAM Static Random Access Memory Program memory you can read write on the target board that does not need refreshing frequently Status Bar The Status Bar is located on the bottom of the MPLAB IDE window and indicates such current information as cursor position development mode and device and active tool bar Step Into This command is the same as Single Step Step Into as opposed to Step Over follows a CALL instruction into a subroutine Step Over Step Over allows you to debug code without stepping into subroutines When stepping over a CALL instruction the next breakpoint will be set at the instruction after the CALL If for some reason the subroutine gets into an endless loop or does not return properly the next breakpoint will never be reached The Step Over command is the same as Single Step except for its handling of CALL instructions 2009 Microchip Technology Inc DS51833A page 209 MPLAB Assembler Linker and Utilities for PIC32 Step Out Step Out allows you to step out of a subroutine which you are currently stepping through This command executes the rest of the code in the subroutine and then stops execution at the return address to th
151. e script sample below the ROM section is addressed at memory location 0 and does not need to be loaded when the program is run The contents of the ROM section will appear in the linker output file as usual SECTIONS ROM 0 NOLOAD 10 6 5 11 OUTPUT SECTION LMA Every section has a virtual address VMA and a load address LMA The address expression which may appear in an output section description sets the VMA The linker will normally set the LMA equal to the VMA This can be changed by using the AT keyword The expression Ima that follows the AT keyword specifies the load address of the section Alternatively with AT 1ma region expression a memory region may be specified for the section s load address See Section 10 6 4 MEMORY Command This feature is designed to make it easy to build a ROM image For example the following linker script creates three output sections one called text which starts at OxBFCO00000 one called mdata which is loaded at the end of the text section even though its VMA is 0xA0000000 and one called bss to hold uninitialized data at address 0xA0001000 The symbol data is defined with the value 0xA0000000 which shows that the location counter holds the VMA value not the LMA value SECTIONS text OxBFC00000 text _etext mdata 0xA0000000 AT ADDR text SIZEOF text data data edata bss 0xA0001000 bstart bss COMMON
152. e code but are not usually translated directly into opcodes They are used to control the assembler its input output and data allocation Note Assembler directives are nottarget instructions ADD XOR JAL etc For instruction set information consult your target device data sheet While there are many significant similarities with directives supported by the 16 bit MPLAB Assembler for PIC24 MCUs and dsPIC DSCs pic30 as there are many differences in the directive set supported by the 32 bit MPLAB Assembler for PIC32 MCUS pic32 as Topics covered in this chapter are Directives that Define Sections Directives that Initialize Constants Directives that Declare Symbols Directives that Define Symbols Directives that Modify Section Alignment Directives that Format the Output Listing Directives that Control Conditional Assembly Directives for Substitution Expansion Directives that Include Other Files Directives that Control Diagnostic Output Directives for Debug Information Directives that Control Code Generation 2009 Microchip Technology Inc DS51833A page 67 32 Bit Assembler Linker and Utilities User s Guide 7 2 DIRECTIVES THAT DEFINE SECTIONS Sections are locatable blocks of code or data that will occupy contiguous locations in the 32 bit device memory Three sections are pre defined text for executable code data for initialized data and bss for uninitialized data Other sections may be defined the li
153. e different if the AT attribute is used in the output section definition see Section 10 6 5 SECTIONS Command 10 7 7 8 MAX EXP1 EXP2 Returns the maximum of exp1 and exp2 10 7 7 9 MIN EXP1 EXP2 Returns the minimum of exp1 and exp2 10 7 7 10 NEXT EXP Return the next unallocated address that is a multiple of exp This function is equivalent to ALIGN exp 10 7 7 11 SIZEOF SECTION Return the size in bytes of the named section if that section has been allocated If the section has not been allocated when this is evaluated the linker will report an error In the following example symbol 1 and symbol 2 are assigned identical values SECTIONS output Start end 2 symbol 1 end start symbol 2 SIZEOF output DS51833A page 132 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 11 Linker Processing 11 1 INTRODUCTION How the MPLAB Object Linker for PIC32 MCUs pic32 1a builds an application from input files is discussed here Topics covered in this chapter are Overview of Linker Processing Linker Allocation Global and Weak Symbols Stack Allocation Heap Allocation Interrupt Vector Tables 11 2 OVERVIEW OF LINKER PROCESSING A linker combines one or more object files with optional archive files into a single executable output file The object files contain relocatable sections of
154. e name as a keyword by surrounding the symbol name in double quotes SECTION 9 with a space also with a space 10 Since symbols can contain many non alphabetic characters it is safest to delimit symbols with spaces For example A B is one symbol whereas A Bisan expression involving subtraction 2009 Microchip Technology Inc DS51833A page 127 32 Bit Assembler Linker and Utilities User s Guide 10 7 3 The Location Counter The special linker variable dot always contains the current output location counter Since the always refers to a location in an output section it may only appear in an expression within a SECTIONS command The symbol may appear anywhere that an ordinary symbol is allowed in an expression Assigning a value to will cause the location counter to be moved This may be used to create holes in the output section The location counter may never be moved backwards SECTIONS output filel text e a 4210004 file2 text 1000 file3 text 0x1234 In the previous example the text section from i1e1 is located at the beginning of the output section output It is followed by a 1000 byte gap Then the text section from file2 appears also with a 1000 byte gap following before the text section from file3 The notation 0x1234 specifies what data to write in the gaps actually refers to the byte offset from the start of the current conta
155. e subroutine Stimulus Input to the simulator i e data generated to exercise the response of simulation to external signals Often the data is put into the form of a list of actions in a text file Stimulus may be asynchronous synchronous pin clocked and register Stopwatch A counter for measuring execution cycles Storage Class Determines the lifetime of the memory associated with the identified object Storage Qualifier Indicates special properties of the objects being declared e g const Symbol A symbol is a general purpose mechanism for describing the various pieces which comprise a program These pieces include function names variable names section names file names struct enum union tag names etc Symbols in MPLAB IDE refer mainly to variable names function names and assembly labels The value of a symbol after linking is its value in memory Symbol Absolute Represents an immediate value such as a definition through the assembly equ directive System Window Control The system window control is located in the upper left corner of windows and some dia logs Clicking on this control usually pops up a menu that has the items Minimize Maximize and Close Target Refers to user hardware Target Application Software residing on the target board Target Board The circuitry and programmable device that makes up the target application Target Processor The microcontroller device on the target a
156. easonably on the actual cover and continue the rest onto adjacent pages If you publish or distribute Opaque copies of the Document numbering more than 100 you must either include a machine readable Transparent copy along with each Opaque copy or state in or with each Opaque copy a computer network location from which the general network using public has access to download using public standard network protocols a complete Transparent copy of the Document free of added material If you use the latter option you must take reasonably prudent steps when you begin distribution of Opaque copies in quantity to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy directly or through your agents or retailers of that edition to the public It is requested but not required that you contact the authors of the Document well before redistributing any large number of copies to give them a chance to provide you with an updated version of the Document c st 2009 Microchip Technology Inc DS51833A page 189 32 Bit Assembler Linker and Utilities User s Guide E5 MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above provide
157. ected symbol name This argument must be a symbol name DS51833A page 170 2009 Microchip Technology Inc Assembler Errors Warnings Messages Expression out of range The expression is out of range for the directive or instruction e g 32 bit value when a 16 bit value is expected Expression too complex The expression should be a symbol or constant F File not found s The file specified to a directive such as incbin could not be opened as specified File number ld already allocated The file number passed to a file directive is already in use File number less than one The file number passed to a file directive must be gt 1 Floating point number invalid The floating point number is invalid G Global symbols not supported in common sections External symbols are not supported in MRI common sections Ignoring attempt to redefine symbol name The symbol being redefined by the weakext directive has already been defined Improper insert size The width of the field specified to an INS instruction was not valid for the shift position Improper extract size The width of the field specified to an EXT instruction was not valid for the shift position Instruction insn requires absolute expression This instruction requires a constant expression Invalid astatic register list The aregs field of a MIPS16e extended SAVE RESTORE instruction specified an invalid astatic register list Invalid arg reg
158. eeeeeeeeeeneee 61 ue ce cS 57 Internal Dreprorceseor 51 Internet Address Microchip cceeeteeeeeeeeeees 5 Interrupt Vector Tables cccccoonoonnnncconcnonoconocononancnnononnns 137 Invert Sense eee eee Rs 117 J mu 46 K KSU Misa ta 127 KEEBz cente eie teet c eme A 132 keep locals t et 47 L erac MEM to MC 47 102 2p EL 102 ADC WEE 52 65 LENGTH talar cene dette eet 118 A esos alee a N a 141 Command Line Interface 143 SOS E 145 aaloe LA eE eis ieesteeee dele ca E E nasser 102 Library Files aiii 92 ibrary path onte 102 Link Map Options Linker A it Sh RU Re ed Ie 110 SEET 110 lop EE 110 ANEMA DEE 110 Linker Allocation to ce tende 135 Command Line Interface 99 File Extensions n eena 92 Output Elle hi eterna 94 OVerView st ec edere ENEE 91 lee e EE 133 Linker Scripts uc iE 9 111 Command Language 114 Command Line Information 111 Concept EE 114 NIE NEE 127 EE eege US DES 92 File Commandes AAA 114 Other Commande 126 Listing Files cp teet 21 Listing Output Options Assembler 35 salle teca 44 p m 36 cop EET 38 UESTRE 40 SE oss ed cle Lo eee EE 41 38min i A eter hge 41 uM TEMERE 43 44 listing cont lines sees 46 listing Ihs width AA 45 listing Ihs width AAA 45 listing rhs width A 45 listing cont lines
159. ent copy of the Document means a machine readable copy represented in a format whose specification is available to the general public that is suitable for revising the document straightforwardly with generic text editors or for images com posed of pixels generic paint programs or for drawings some widely available draw ing editor and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters A copy made in an otherwise Transparent file format whose markup or absence of markup has been arranged to thwart or discourage subsequent modification by readers is not Transparent An image format is not Transparent if used for any substantial amount of text A copy that is not Transparent is called Opaque Examples of suitable formats for Transparent copies include plain ASCII without markup Texinfo input format LaTeX input format SGML or XML using a publicly available DTD and standard conforming simple HTML PostScript or PDF designed for human modification Examples of transparent image formats include PNG XCF and JPG Opaque formats include proprietary formats that can be read and edited only by proprietary word processors SGML or XML for which the DTD and or processing tools are not generally available and the machine generated HTML PostScript or PDF produced by some word processors for output purposes only The Title Page means for a printed book
160. ent archive canceling the effect of any operations since the last SAVE May be executed with no effect even if no current archive is specified 2009 Microchip Technology Inc DS51833A page 145 32 Bit Assembler Linker and Utilities User s Guide TABLE 12 3 ARCHIVER SCRIPTS COMMANDS CONTINUED Option Function CREATE ARCHIVE Creates an archive and makes it the current archive required for many other commands The new archive is created with a temporary name it is not actually saved as ARCHIVE until you use SAVE You can overwrite existing archives similarly the contents of any existing file named ARCHIVE will not be destroyed until SAVE DELETE MODULE MODULE MODULE Delete each listed MODULE from the current archive equivalent to pic32 ar d ARCHIVE MODULE MODULE Requires prior use of OPEN or CREATE DIRECTORY ARCHIVE MODULE MODULE OUTPUTFILE List each named MODULE present in ARCHIVE The separate command VERBOSE specifies the form of the output when verbose output is off output is like thatofpic32 ar t ARCHIVE MODULE When verbose output is on the listing is like pic32 ar tv ARCHIVE MODULE Output normally goes to the standard output stream however if you specify OUTPUTFILE as a final argument the 32 bit archiver librarian directs the out put to that file Exit from the archiver with a O exit code to indi
161. er and Utilities User s Guide 9 5 OPTIONS THAT CONTROL RUN TIME INITIALIZATION Run time initialization options are defsym min stack size size defsym min heap size size 9 5 1 defsym min stack size size The default linker script provides a minimum stack size of 1024 bytes Use the def sym option to define the min stack size symbol to change this default size value Note that the actual effective stack size may be larger than the minimum size pic32 gcc foo c Wl defsym min stack size 1536 9 5 2 defsym min heap size size The default linker script provides a heap size of O bytes Use the defsym option to define the mn heap size symbol to change this default size value The linker creates a heap with a size defined by this value pic32 gcc foo c Wl defsym min heap size 2048 9 6 OPTIONS THAT CONTROL MULTILIB LIBRARY SELECTION Multilibs are a set of prebuilt target libraries Each target library in the multilib gets built with a different set of compiler options Multilibs provide the linker with the capability to match a target library with the compiler options used to build an application The pre built target libraries represent the most common combinations of compiler options When the compilation driver is called to link an application the driver chooses the ver sion of the target library that corresponds to the application options These options should be passed to the compilation driver not t
162. er pato 104 sgection stait iiinn na i 103 z StarE group eee 101 split iii 104 SInlP C DUG ices aici irene 104 GC EE 104 Mrs 104 Tala x cnet meten 104 STIGXE uio eno tient cU 104 A RU eA Ei 104 kel le ettet 104 STEE 103 mici S 105 D 102 SX Shen na EE 102 n Formats pic32 nm AAA en E 150 S EE 150 Bou denies 150 EE 150 D none Asp me UN 150 ENEE 150 El dose queden nid ent debetis dat 150 Toss ete shai esta i E PER e LEE ERA 150 UE 150 EUN 150 AA EE E E eege 150 Output Listing Directives Ee GE 78 Jet epe eei 78 Mol ies ita 78 PSI iia de 78 Mi rias 78 Mitad a 78 Output Section AQUIOSS tette dc 122 Attribute Sii re cede es 123 RE 122 Description eder eria 121 Discarding ccoo asia ntt 123 Filz edes 125 EMA ee doles abes do 124 Reglor eee 124 Re EE 123 COP GE aU gp head 123 DSECT A shi ueste MERE 123 INFOS usa 123 NOLOAD BEE 123 OVERLAY acs sete itc eed 123 OQUTPUT_ARCG Hiasi a 127 OUTP TFORMAT itt ient ttt 127 OVERLAY 023 ein da Ene RR etg 123 Overlay Descriotion 125 Overview Assembler eee 17 LION cocotero sde e tO RR 91 P esi c 7 pic30 88 Sie hie Ie e Ld et ut ds 7 Ee E Le 7 pic30 ld s nte eedem teen ier etus 7 Dile cin cia 151 157 pic32 ar utility ooooooonccononicononacanonacananannnnarannrarnnnnn 141 pic32 bin2hex utility seen 147 pic32 nrm IDN ee pt tete i deo 149 pic32 objdump utility e
163. ered in this chapter are Assembler and Other Development Tools Feature Set Input Output Files ASSEMBLER AND OTHER DEVELOPMENT TOOLS MPLAB Assembler for PIC32 MCUs translates user assembly source files In addition the MPLAB C Compiler for PIC32 MCUS uses the assembler to produce its object file After the C preprocessor processes the assembly source file S the assembler generates a relocatable object file that can then be put into an archive or linked with other relocatable object files and archives to create an executable file See Figure 1 1 for an overview of the tools process flow FIGURE 1 1 TOOLS PROCESS FLOW C Source Files c i Compiler Assembly Source Driver Files S C Compiler Program v Source Files s y Object Files Archiver Librarian Ven NS l A Object File Libraries Linker Script a 1d d d MPLAB IDE gt Executable File UL Debug Tool elf Command Line gt 8 Simulator 2009 Microchip Technology Inc DS51833A page 17 32 Bit Assembler Linker and Utilities User s Guide 1 3 FEATURE SET Notable features of the assembler include Support for the MIPS32 and MIPS16e instruction sets Support for ELF object format Available for Windows OS Rich Directive Set Flexible Macro L
164. eres 153 OUTPUT ee odit pec ri 115 Mic an 153 SOUDU A AA ada o 103 Mi delata estet dM cerent tte 153 Output File Creation Options Assembler vl PEE 153 keep locals eem ttr 47 Options pic32 ranlib MEE EM 47 Mente tete m rer Re 153 up 47 SE 153 Osee pie UD iu 47 VOS IO ia Ke aerate Eeer 153 por 47 Options pic32 strings Output File Options Linker 156 att dt he ta 101 ANA eimi eae ege 156 5 eee oe e pedet A rt 101 allis uso tease elt rio eed 156 GEES 101 en AE 156 AS EE 102 156 A mne 102 Se UE GEET 156 discard lOCalS A 102 E EE 156 EE MI 101 print file name eee 156 end group 2 ea iue te tede cce 101 SES ET 156 lte RR RICE 102 dran ied nq tini ee eet 156 Va Aaen 103 MAI ica 156 SE MUN M 102 zoll 156 sue ERE teda dieti 102 Options pic32 strip Sl con a 102 discado calido 157 ly Plica ica 102 discard lOcalS cocoa ir 157 eN defaultli hS saminn unen 103 e DE 157 nostariflles sch etre tt ears 103 help 3 5 Rao eee 157 Ge te e 3 0x rne hg BIN ARN 103 jc TEE 157 no undefined esses 104 keep symbols eee 157 SO huis E tada 103 DS51833A page 218 O 2009 Microchip Technology Inc ul 103 d EET 103 relocateable 2 2 on etel 103 retain symbols file sess 103 p eee 104 Sesto ie eedem A dus 104 SEET irc o tete oet e ric der
165. es memory This is accomplished by assigning each input section to an output section The relation between input and output sections is defined by a section map in the linker script An output section may or may not have the same name as an input section Each output section is then assigned to a memory region in the target device Note Input sections are derived from source code by the compiler or the assembler Output sections are created by the linker If an input section is not explicitly assigned to an output section the linker will allocate the unassigned section according to section attributes For more information about linker allocation see Section 11 3 Linker Allocation 11 2 3 Resolving Symbols Once memory has been allocated the linker begins the process of resolving symbols Symbols defined in each input section have offsets that are relative to the beginning of the section The linker converts these values into output section offsets Next the linker attempts to match all external symbol references with a corresponding symbol definition Multiple definitions of the same external symbol result in an error If an external symbol is not found an attempt is made to locate the symbol definition in an archive file If the symbol definition is found in an archive the corresponding archive module is loaded Modules loaded from archives may contain additional symbol references so the process continues until all external sym
166. es that references the symbol If the symbol is defined the first file listed is the location of the definition The remaining files contain references to the symbol Data Directives Data directives are those that control the assembler s allocation of program or data memory and provide a way to refer to data items symbolically that is by meaningful names 2009 Microchip Technology Inc DS51833A page 195 MPLAB Assembler Linker and Utilities for PIC32 Data Memory On Microchip MCU and DSC devices data memory RAM is comprised of General Purpose Registers GPRs and Special Function Registers SFRs Some devices also have EEPROM data memory Debugger Hardware that performs debugging Debugger System The debugger systems include the pod processor module device adapter target board cables and MPLAB IDE software Debugging Information Compiler and assembler options that when selected provide varying degrees of infor mation used to debug application code See compiler or assembler documentation for details on selecting debug options Deprecated Features Features that are still supported for legacy reasons but will eventually be phased out and no longer used Device Programmer A tool used to program electrically programmable semiconductor devices such as microcontrollers Digital Signal Controller A microcontroller device with digital signal processing capability i e Microchip dsPIC DSC devices
167. ess 0x9D001000 and text1 will be loaded immediately after texto The following symbols will be defined load start texto load stop texto load start textl load stop textl C code to copy overlay text1 into the overlay area might look like the following extern char _ load start textl1 load stop textl memcpy char zl 0x9D001000 amp load start textl amp load stop textl amp load start text1 The OVERLAY command is a convenience since everything it does can be done using the more basic commands The above example could have been written identically as follows text0 0x9D001000 AT 0x9D004000 o1 o text load start text0 LOADADDR text0 load stop text0 LOADADDR text0 SIZEOF textO0 textl 0x9D001000 AT 0x9D004000 SIZEOF text0 o2 o text load start textl1 LOADADDR textl1 load stop textl1 LOADADDR text1 SIZEOF textl 0x9D001000 MAX SIZEOF text0 SIZEOF text1 10 6 6 Other Linker Script Commands There are several other linker script commands which are described briefly ASSERT exp message Ensure that exp is non zero If itis zero then exit the linker with an error code and print message ENTRY symbol Specify symbo1 as the first instruction to execute in the program The linker will record the address of this symbol in the output object file header This does not affect the Reset instruction at address zero which must be
168. ess than or equal to zero iflt absolute expression This directive assembles the following section of code if the argument is less than zero ifnc string1 string2 This directive is like ifc but the sense of the test is reversed this assembles the following section of code if the two strings are not the same ifndef symbol This directive assembles the following section of code if the specified symbol has not been defined Both spelling variants are equivalent Note a symbol which has been referenced but not yet defined is considered to be undefined ifnotdef symbol This directive is the same as i ndef ifne absolute expression This directive assembles the following section of code if the argument is not equal to zero in other words this is equivalent to if ifnes string1 string2 This directive is like ifeqs but the sense of the test is reversed this assembles the following section of code if the two strings are not the same 7 9 DIRECTIVES FOR SUBSTITUTION EXPANSION Substitution expansion directives are exitm irp symbol value value endr irpc symbol value endr macro exitm Exit early from the current macro definition See macro directive irp symbol value value endr Evaluate a sequence of statements assigning different values to symbo1 The sequence of statements starts at the irp directive and is terminated by a endr directive For eac
169. executed opcodes appears on the bus as a fetch during the execution of the previous instruction the source data address and DS51833A page 208 O 2009 Microchip Technology Inc Glossary value and the destination data address appear when the opcodes is actually executed and the destination data value appears when the next instruction is executed The trace buffer captures the information that is on the bus at one instance Therefore one trace buffer entry will contain execution information for three instructions The number of cap tured cycles from one piece of information to another for a single instruction execution is referred to as the skew Skid When a hardware breakpoint is used to halt the processor one or more additional instructions may be executed before the processor halts The number of extra instructions executed after the intended breakpoint is referred to as the skid Source Code The form in which a computer program is written by the programmer Source code is written in a formal programming language which can be translated into machine code or executed by an interpreter Source File An ASCII text file containing source code Special Function Registers The portion of data memory RAM dedicated to registers that control I O processor functions I O status timers or other modes or peripherals SQTP See Serialized Quick Turn Programming Stack Hardware Locations in PIC microcontroller where the return ad
170. f not select View gt Project The title bar shows the workspace filename irst proj ect mcw and the single project within our workspace first project mcp shows as a tree of folders CIENT lol E first project mcp Source Files Header Files 3 Object Files Library Files Linker Script Other Files E Pe Symbols You can right click on various items in this window to perform many useful proj ect related functions The right mouse context menu allows you to add new files delete files and open the project s build options 2 4 ADDING A SOURCE FILE TO YOUR PROJECT Once you have created your project you can now add a new source file to it 1 From the project menu select Add New File to Project w first project MPLAB IDE File Edit View Project Debugger Programmer Tools Configure Project Wizard New Close D Set Active Project Quickbuild no asm file Package in zip Clean Locate Headers Export Makefile Build All Ctrl F10 Make F10 Build Configuration gt Save Project Select Language Toolsuite Set Language Tool Locations Version Control 2009 Microchip Technology Inc DS51833A page 29 32 Bit Assembler Linker and Utilities User s Guide 2 The project manager will prompt you for a new filename Use the Jump To con trol to jump to the Project Directory Enter a file name such as first source file S Be
171. formatted binary object files Output Intel hex files 13 2 2 Syntax Command line syntax is pic32 bin2hex options file Example 13 1 hello elf Convert the absolute ELF executable file hello elf to hello hex pic32 bin2hex hello elf 2009 Microchip Technology Inc DS51833A page 147 32 Bit Assembler Linker and Utilities User s Guide 13 2 3 Options The following options are supported TABLE 13 1 pic32 bin2hex OPTIONS Option Function a sort Sort sections by address i virtual Use virtual addresses p physical Use physical addresses default v verbose Print verbose messages help Print a help screen Note See the PIC32MX Family Reference Manual DS61115 for a description of the PIC32MX Virtual to Physical Fixed Memory Mapping EXAMPLE 13 2 v OPTION OUTPUT writing hello hex section PC address byte address length w pad actual length dec reset 0 0 0x8 0x6 6 text 0x100 0x200 0x6a28 0x4f9e 20382 dinit 0x3614 0x6c28 Oxda4 Oxa3b 2619 const 0x3ce6 0x79cc 0x40 0x30 48 ivt 0x4 0x8 Oxf8 Oxba 186 aivt 0x84 0x108 Oxf8 Oxba 186 Total program memory used bytes 0x5b83 23427 DS51833A page 148 O 2009 Microchip Technology Inc Other PIC32 MCU Binary Utilities 13 3 pic32 nmUTILITY The pic32 nm utility produces a list of symbols from object files Each item in the list consists of the symbol value symbol type and symbol name In
172. from the overall header of file header each of the OBJFILE files file start context Specify that when displaying inter listed source code disassembly assumes S from a file that has not yet been displayed extend the context to the start of the file g debugging Display debugging information This attempts to parse debugging information stored in the file and print it out using a C like syntax Only certain types of debugging information have been implemented h gection header header Display summary information from the section headers of the object file File segments may be relocated to nonstandard addresses for example by using the Ttext Tdata or Tbss options to 1d However some object file formats such as a out do not store the starting address of the file segments In those situations although 1d relocates the sections correctly using pic32 objdump h to list the file section headers cannot show the correct addresses Instead it shows the usual addresses which are implicit for the target H help Print a summary of the options to pic32 objdump and exit j name gection name Display information only for section name 1 line numbers Label the display using debugging information with the filename and source line numbers corresponding to the object code or relocs shown Only useful with d D or I M options disassembler options opt
173. ft amp bitwise and 7 left bitwise or 8 left amp amp logical and 9 left logical or 10 right o Conditional 11 lowest right amp Symbol assignments 10 7 5 Evaluation The linker evaluates expressions lazily It only computes the value of an expression when absolutely necessary The linker needs some information such as the value of the start address of the first section and the origins and lengths of memory regions in order to do any linking at all These values are computed as soon as possible when the linker reads in the linker script However other values such as symbol values are not known or needed until after storage allocation Such values are evaluated later when other information such as the sizes of output sections is available for use in the symbol assignment expression The sizes of sections cannot be known until after allocation so assignments dependent upon these are not performed until after allocation Some expressions such as those depending upon the location counter must be evaluated during section allocation If the result of an expression is required but the value is not available then an error results For example a script like the following SECTIONS text 9 this isnt constant text will cause the error message non constant expression for initial address 10 7 6 The Section of an Expression When the linker evaluates an expression the result i
174. ge n a 10 5 ADDING A CUSTOM LINKER SCRIPT TO AN MPLAB IDE PROJECT The standard default 32 bit linker scripts are general purpose and will satisfy the demands of most applications However an occasion may arise where a custom linker script is required To add a custom linker script to an MPLAB IDE project 1 Under Project gt Select Language Toolsuite Active Toolsuite select Microchip PIC32 C Compiler Toolsuite Use this suite for both assembly code and C code projects 2 Create a new text file and save it with a 1d file extension 3 Add the new 1d file to your project It should now appear in the project tree The MPLAB IDE project manager should now pass the 1d file to the linker with the script option when calling the linker via the compilation driver Note While these instructions are based on the project manager in MPLAB IDE v8 15 the steps required for other 8 xx versions should be similar Starting with the default linker script is almost always easier than starting from scratch Use a text editor to copy the contents of the pic32mx lib ldscripts elf32pic32mx x default linker script into your newly created 1d file You may also replace the INCLUDE procdefs 1d directive with the contents of the device specific pic32mx lib proc device procdefs 1d portion of the linker script Customizations that you make to your new 1d file should now affect your project You may wish to retain
175. generated in some other way By convention the 32 bit linker scripts constructa GOTO reset instruction at address zero EXTERN symbol symbol Force symbol to be entered in the output file as an undefined symbol Doing this may for example trigger linking of additional modules from standard libraries Several symbols may be listed for each EXTERN and EXTERN may appear multiple times This command has the same effect as the u command line option FORCE COMMON ALLOCATION This command has the same effect as the command line option to make 32 bit linker assign space to common symbols even if a relocatable output file is specified r DS51833A page 126 O 2009 Microchip Technology Inc Linker Scripts NOCROSSREFS section section This command may be used to tell 32 bit linker to issue an error about any references among certain output sections In certain types of programs when one section is loaded into memory another section will not be Any direct references between the two sections would be errors The NOCROSSREFS command takes a list of output section names If the linker detects any cross references between the sections it reports an error and returns a non zero exit status The NOCROSSREFS command uses output section names not input section names OUTPUT ARCH bfdarch Specify a particular output machine architecture The b darch value is always pic32mx for Microchip PIC32 MCUs OUTPUT FORMAT fo
176. guage file foo o object file 3 8 8 v Print the commands executed during each stage of compilation 3 8 9 help Print a description of the command line options 2009 Microchip Technology Inc DS51833A page 49 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 50 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 4 Assembler Syntax 4 1 INTRODUCTION Syntax for MPLAB Assembler for PIC32 MCUs pic32 as source code is defined here Topics covered in this chapter are Internal Preprocessor Source Code Format Constants Summary 4 2 INTERNAL PREPROCESSOR The assembler has an internal preprocessor The internal processor 1 Adjusts and removes extra white space It leaves one space or tab before the keywords on a line and turns any other white space on the line into a single space 2 Removes all comments replacing them with a single space or an appropriate number of new lines 3 Converts character constants into the appropriate numeric value If you have a single character e g b in your source code this will be changed to the appropriate numeric value If you have a syntax error that occurs at the sin gle character the assembler will not display b but instead display the first digit of the decimal equivalent For example if you had global mybuf b in your source code t
177. h value symbol is setto value and the sequence of statements is DS51833A page 80 O 2009 Microchip Technology Inc Assembler Directives assembled If no value is listed the sequence of statements is assembled once with symbol set to the null string To refer to symbol within the sequence of statements use Nsymbol For example assembling irp reg 0 1 2 3 lw Sa reg 10324 Nreg sp endr is equivalent to assembling lw a0 1032 0 lw a1 1032 1 lw a2 1032 2 lw a3 1032 3 sp sp sp SSP irpc symbol value endr Evaluate a sequence of statements assigning different values to symbo1 The sequence of statements starts at the irpc directive and is terminated by an endr directive For each character in value symbol is set to the character and the sequence of statements is assembled If no value is listed the sequence of statements is assembled once with symbol set to the null string To refer to symbo1 within the sequence of statements use symbol For example assembling lrpc reg 0123 lw Sa reg 10324 Nreg sp endr is equivalent to assembling lw a0 1032 0 lw a1 103241 lw a2 1032 2 lw a3 1032 3 Sep sp Sep sp macro The directives macro and endm allow you to define macros that generate assembly output For example this definition specifies a macro SUM that puts a sequence of numbers into memory macro SUM from 0 to 5 long from ERE o f rom
178. he o option to name the output file projectname elf where projectname is the name of your MPLAB IDE project The format of the binary file is an Executable and Linking Format ELF file The Exe cutable and Linking Format was originally developed and published by UNIX System Laboratories USL as part of the Application Binary Interface ABI The ELF specifi cation is the result of the work of the Tool Interface Standards TIS Committee an association of members of the microcomputer industry formed to work toward stan dardization of the software interfaces visible to development tools The debugging information within the ELF file is in the DWARF Debugging Information format Also a result ofthe work ofthe TIS Committee the DWARF format uses a series of debugging entries to define a low level representation of a source program A DWARF consumer such as MPLAB IDE can then use the representation to create an accurate picture of the original source program 8 4 5 Map File The map files produced by the linker consist of Archive Member Table lists the name of any members from archive files that are included in the link Memory Usage Report shows the starting address and length of all output sections in program memory and data memory It also shows a percent utilization of memory in the region Memory Configuration lists all of the memory regions defined for the link Linker Script and Memory Map shows modules sections an
179. he error message would say Error Rest of line ignored First ignored character is 9 Notice the error message says 9 This is because the b was converted to its decimal equivalent 98 The assembler is actually parsing global mybuf 98 The internal processor does not do 1 macro preprocessing 2 include file handling 3 anything else you may get from your C compiler s preprocessor You can do include file preprocessing with the include directive See Chapter 7 Assembler Directives You can use the C compiler driver to get other C preprocessing style preprocessing by giving the input file a S uppercase suffix See the MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 for more information 2009 Microchip Technology Inc DS51833A page 51 32 Bit Assembler Linker and Utilities User s Guide If the first line of an input file is NO APP or if you use the option white space and comments are not removed from the input file Within an input file you can ask for white space and comment removal in certain portions by putting a line that says APP before the text that may contain white space or comments and putting a line that says amp NO APP after this text This feature is mainly intended to support assembly statements in compilers whose output is otherwise free of comments and white space Note Excess white space comments and character constants cannot be used in the portions of the input text
180. he linker directly The driver s mprocessor option allows the driver to pass the correct device specific include file and library search paths to the linker For instance when specifying mprocessor 32MX360F512L the driver passes the corre sponding device specific library search path pic32mx lib proc 32MX360F512L to the linker This path allows the linker to find the correct default linker script and processor library for the target device The driver also uses the mprocessor option to pass the device specific periph eral library name mchp peripheral 32MX360F512L to the linker The driver accepts the C compiler s optimization ISA mode and floating point support options required to select the appropriate multilib permutation For exam ple when passing the Os size optimization option the driver passes pic32mx lib size asa library search path so that the linker uses the pre compiled libraries optimized for size See the MPLAB C Compiler for PIC32 MCUS User s Guide DS51686 for more information on the C compiler s multilib feature DS51833A page 100 2009 Microchip Technology Inc Linker Command Line Interface 9 4 OPTIONS THAT CONTROL OUTPUT FILE CREATION Output file creation options are archives start group archives end group d dc dp defsym sym expr discard all x discard locals X gc sections e library name 1 name library path dir L lt dir gt
181. he linker proper The compilation driver then translates the options to the appropriate L library search path when calling the linker Note MPLAB IDE 8 20 shows the multilib options on the Library Selection cat egory of the linker tab of the project s build options See the MPLAB C Compiler PIC32 MCUs User s Guide DS51686 for more details on the multilib feature 9 6 1 Size versus speed Os vs 03 Select either Os to optimize for size or 00 through 03 to optimize for speed 00 Select the unoptimized multilib target library permutation This is the default for the command line interface but MPLAB IDE s project manager may pass one of the other optimization options by default O1 Select the multilib target library permutation built with optimization level 1 02 Select the multilib target library permutation built with optimization level 2 This optimi zation level provides a good balance between execution speed and code size This multilib optimization level is a good choice for most applications DS51833A page 106 O 2009 Microchip Technology Inc Linker Command Line Interface 03 Select the multilib target library permutation built with optimization level 3 This optimi zation maximizes execution speed Os Select the multilib target library permutation built optimized for code size Example pic32 gcc foo o Os o project elf 9 6 2 16 bit versus 32 bit mips16 vs mno mips16 Select
182. he machine code generated by an assembler or compiler Object File A file containing machine code and possibly debug information It may be immediately executable or it may be relocatable requiring linking with other object files e g libraries to produce a complete executable program Object File Directives Directives that are used only when creating an object file Octal The base 8 number system that only uses the digits 0 7 The rightmost digit counts ones the next digit counts multiples of 8 then 8 64 etc DS51833A page 204 2009 Microchip Technology Inc Glossary Off Chip Memory Off chip memory refers to the memory selection option for the PIC18 device where memory may reside on the target board or where all program memory may be supplied by the emulator The Memory tab accessed from Options Development Mode pro vides the Off Chip Memory selection dialog box One to One Project Workspace Model The most common configuration for application development in MPLAB IDE to is have one project in one workspace Select Configure Settings Projects tab and check Use one to one project workspace model Opcodes Operational Codes See Mnemonics Operators Symbols like the plus sign and the minus sign that are used when forming well defined expressions Each operator has an assigned precedence that is used to determine order of evaluation OTP One Time Programmable EPROM devices that
183. he most common output section command is an input section description The input section description is the most basic linker script operation Output sections tell the linker how to lay out the program in memory Input section descriptions tell the linker how to map the input files into the memory layout An input section description consists of a file name optionally followed by a list of section names in parentheses The file name and the section name may be wildcard patterns which are described further below The most common input section description is to include all input sections with a particular name in the output section For example to include all input cext sections one would write text Here the is a wildcard which matches any file name To exclude a list of files from matching the file name wildcard EXCLUDE FILE may be used to match all files except the ones specified in the EXCLUDE FILE list For example EXCLUDE FILE crtend o otherfile o ctors will cause all ctors sections from all files except crtend o and otherfile o to be included There are two ways to include more than one section text rodata text rodata The difference between these is the order in which the text and rodata input sections will appear in the output section In the first example they will be intermingled In the second example all text input sections will appear first followed by all rodata input se
184. he symbol floating point will be defined as zero The symbol _text_end will be defined as the address following the last text input section The symbol bdata will be defined as the address following the text output section aligned upward to a 4 byte boundary DS51833A page 116 2009 Microchip Technology Inc Linker Scripts 10 6 3 2 PROVIDE In some cases it is desirable for a linker script to define a symbol only if it is referenced and is not defined by any object included in the link For example traditional linkers defined the symbol etext However ANSI C requires that etext may be used as a function name without encountering an error The PROVIDE keyword may be used to define a symbol such as etext only if it is referenced but not defined The syntax is PROVIDE symbol expression Here is an example of using PROVIDE to define etext SECTIONS text text etext PROVIDE etext The PIC32 default linker script uses the PROVIDE command to define the default min stack size min heap size and vector spacing symbol values PROVIDE min stack size 0x400 PROVIDE min heap size 0 PROVIDE vector spacing 0x00000001 10 6 4 MEMORY Command The linker s default configuration permits allocation of all available memory This can be overridden by using the MEMORY command The MEMORY command describes the location and size of blocks of memory in the target It can be used
185. he symbol is not defined the value of the weak symbol becomes zero with no error W The symbol is a weak symbol that has not been specifically tagged as a weak object symbol When a weak defined symbol is linked with a normal defined symbol the normal defined symbol is used with no error When a weak undefined symbol is linked and the symbol is not defined the value of the weak symbol becomes zero with no error The symbol type is unknown or object file format specific DS51833A page 150 O 2009 Microchip Technology Inc Other PIC32 MCU Binary Utilities 13 4 pic32 objdump UTILITY The pic32 objdump utility displays information about one or more object files The options control what particular information to display The output can provide informa tion similar to that of a disassembly listing Input Files Syntax Options 13 4 1 Input Files Input Object archive files If no object files are listed as arguments pic32 objdump assumes the file a out 13 4 2 Syntax Command line syntax is pic32 objdump a archive headers d disassemble D disassemble all file headers file start context g debugging h section headers headers SI help 1 j name section name 1 line numbers M options disassembler options options prefix addresses r reloc s full contents S source no
186. his directive is a synonym for 1oat Floating point numbers are in IEEE format see Section 4 4 1 2 Floating Point Numbers hword expr exprjl Assembles one or more 2 byte numbers into consecutive addresses in little endian format This directive is a synonym for short DS51833A page 72 2009 Microchip Technology Inc Assembler Directives int expri expr l Assembles one or more 4 byte numbers into consecutive addresses in little endian format This directive is a synonym for long long expr expr Assembles one or more 4 byte numbers into consecutive addresses in little endian format This directive is a synonym for int Short expr exprjl Assembles one or more 2 byte numbers into consecutive addresses in little endian format This directive is a synonym for hword String str This directive is a synonym for asciz word expr expr Assembles one or more 4 byte numbers into consecutive addresses in little endian format 2009 Microchip Technology Inc DS51833A page 73 32 Bit Assembler Linker and Utilities User s Guide 7 4 DIRECTIVES THAT DECLARE SYMBOLS Declare symbol directives are comm symbol length algn extern symbol global symbol globl symbol lcomm symbol length weak symbol comm symbol length align comm declares a common symbol named symbo1 When linking a common symbol in one object file may be me
187. his may for example trigger linking of additional modules from standard libraries u may be repeated with different option arguments to enter additional undefined symbols 9 4 23 no undefined Allow no undefined symbols DS51833A page 104 2009 Microchip Technology Inc Linker Command Line Interface 9 4 24 wrap symbol Use wrapper functions for symbol Use a wrapper function for symbol Any undefined reference to symbol will be resolved to wrap symbol Any undefined referenceto real symbol will be resolved to symbol This can be used to provide a wrapper for a system function The wrapper function should be called wrap symbol If it wishes to call the system function it should call real symbol Here is a trivial example void wrap malloc int c printf malloc called with ld n c return real malloc c If you link other code with this file using wrap malloc then all calls to malloc will call the function wrap malloc instead The callto real_mallocin wrap malloc will call the real malloc function You may wish to provide a real malloc function as well so that links without the wrap option will succeed If you do this you should not put the definition of real mallocin the samefileas wrap malloc ifyou do the assembler may resolve the call before the linker has a chance to wrap it to malloc 2009 Microchip Technology Inc DS51833A page 105 32 Bit Assembler Link
188. his option may be given more than once N symbolname strip symbol symbolname Remove symbol symbolname from the source file This option may be given more than once and may be combined with strip options other than K o file Put the stripped output in file rather than replacing the existing file When this argument is used only one OBJFILE argument may be specified p Preserve the access and modification dates of the preserve dates file R sectionname remove section sectionname Remove any section named sectionname from the output file This option may be given more than once Note that using this option inappropriately may make the output file unusable s strip all Remove all symbols strip unneeded Remove all symbols that are not needed for relocation processing v Verbose output list all object files modified In the verbose case of archives pic32 strip v lists all mem bers of the archive V Show the version number for pic32 strip version X Remove non global symbols discard all X Remove compiler generated local symbols discard locals on These usually start with L or 2009 Microchip Technology Inc DS51833A page 157 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 158 2009 Microchip Technology Inc E MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PI
189. ic properties Attribute Section Characteristics of sections such as executable readonly or data that can be specified as flags in the assembler section directive Binary The base two numbering system that uses the digits 0 1 The rightmost digit counts ones the next counts multiples of 2 then 2 4 etc Bookmarks Use bookmarks to easily locate specific lines in a file Under the Edit menu select Bookmarks to manage bookmarks Toggle enable disable a bookmark move to the next or previous bookmark or clear all bookmarks Breakpoint Hardware Breakpoint An event whose execution will cause a Halt Software Breakpoint An address where execution of the firmware will halt Usually achieved by a special break instruction Build Compile and link all the source files for an application C A general purpose programming language which features economy of expression modern control flow and data structures and a rich set of operators DS51833A page 194 2009 Microchip Technology Inc Glossary Calibration Memory A Special Function Register or registers used to hold values for calibration of a PIC microcontroller on board RC oscillator or other device peripherals Central Processing Unit The part of a device that is responsible for fetching the correct instruction for execution decoding that instruction and then executing that instruction When necessary it works in conjunction with the a
190. ices MPLIB Object Librarian Microchip s librarian that can work with MPLAB IDE MPLIB librarian is an object librar ian for use with COFF object modules created using either MPASM assembler mpasm or mpasmwin v2 0 or MPLAB C18 C compiler MPLINK Object Linker MPLINK linker is an object linker for the Microchip MPASM assembler and the Micro chip C18 C compiler MPLINK linker also may be used with the Microchip MPLIB librar ian MPLINK linker is designed to be used with MPLAB IDE though it does not have to be MRU Most Recently Used Refers to files and windows available to be selected from MPLAB IDE main pull down menus Native Data Size For Native trace the size of the variable used in a Watch window must be of the same size as the selected device s data memory bytes for PIC18 devices and words for 16 bit devices Nesting Depth The maximum level to which macros can include other macros Node MPLAB IDE project component Non Extended Mode In Non Extended mode the compiler will not utilize the extended instructions nor the indexed with literal offset addressing Non Real Time Refers to the processor at a breakpoint or executing single step instructions or MPLAB IDE being run in Simulator mode Non Volatile Storage A storage device whose contents are preserved when its power is off NOP No Operation An instruction that has no effect when executed except to advance the program counter Object Code T
191. ified The linker will search an archive only once at the location where it is speci fied on the command line If the archive defines a symbol that was undefined in some object that appeared before the archive on the command line the linker will include the appropriate file s from the archive However an undefined symbol in an object appear ing later on the command line will not cause the linker to search the archive again See the option for a way to force the linker to search archives multiple times You may list the same archive multiple times on the command line If the format of the archive file is not recognized the linker will ignore it Therefore a version mismatch between libraries and the linker may result in undefined symbol errors 9 4 8 library path lt dir gt L lt dir gt Add dir to library search path Add path dir to the list of paths that pic32 1d will search for archive libraries and pic32 1d control scripts You may use this option any number of times The directo ries are searched in the order in which they are specified on the command line All L options apply to all 1 options regardless of the order in which the options appear The library paths can also be specified in a link script with the SEARCH DIR command Directories specified this way are searched at the point in which the linker script appears in the command line DS51833A page 102 O 2009 Microchip Technology Inc Linker Comma
192. ing popsection DS51833A page 68 O 2009 Microchip Technology Inc Assembler Directives TABLE 7 1 popsection Replace the current section description with the top section on the section stack This section is popped off the stack section name flags type Use the section directive to assemble the following code into a section named name The optional flags argument is a quoted string which may contain any combination of the following characters a Section is allocatable w Section is writable x Section is executable The type argument may be one of progbits Normal section with contents nobits Section does not contain data i e section only occupies space Reserved Section Names The following section names are available for user applications RESERVED SECTIONS DETAILS Section Name Generated by Final Location Default Linker Script MEMORY Region text Compiler or assembler Executable code segment kseg0 program mem generated instructions text Functions when compiled with Executable code segment ksegO0 program mem ffunction sections are out put to uniquely named sections of this form startup C start up code Executable boot code segment kseg0_boot_mem app excpt General Exception handler Executable boot code segment ksegO0 boot mem reset Reset handler Executable boot code segment kseg0_boot_mem bev excpt BEV Exception handler Executable boot code
193. ing input sections The special output section name DISCARD may be used to discard input sections Any input sections which are assigned to an output section named DISCARD are not included in the output file 10 6 5 9 OUTPUT SECTION ATTRIBUTES To review the full description of an output section is name address type AT 1ma output section command output section command gt region AT gt lma_region phdr phdr fillexp name address and output section command have already been described In the following sections the remaining section attributes will be described 10 6 5 10 OUTPUT SECTION TYPE Each output section may have a type The type is a keyword in parentheses The following types are defined NOLOAD The section should be marked as not loadable so that it will not be loaded into memory when the program is run DSECT COPY INFO OVERLAY These type names are supported for backward compatibility with older MIPS and GNU assemblers but are rarely used They all have the same effect the section should be marked as not allocatable so that no memory is allocated for the section when the program is run 2009 Microchip Technology Inc DS51833A page 123 32 Bit Assembler Linker and Utilities User s Guide The linker normally sets the attributes of an output section based on the input sections which map into it This can be overridden by using the section type For example in th
194. ining object Normally this is the SECTIONS statement whose start address is 0 hence can be used as an absolute address If is used inside a section description however it refers to the byte offset from the start of that section not an absolute address Thus in a script like this SECTIONS 0x100 text text 0x200 0x500 data data 0x600 The text section will be assigned a starting address of 0x100 and a size of exactly 0x200 bytes even if there is not enough data in the text input sections to fill this area If there is too much data an error will be produced because this would be an attempt to move backwards The data section will start at 0x500 and it will have an extra 0x600 bytes worth of space after the end of the values from the data input sections and before the end of the data output section itself 10 7 4 Operators The linker recognizes the standard C set of arithmetic operators with the standard bindings and precedence levels DS51833A page 128 O 2009 Microchip Technology Inc Linker Scripts TABLE 10 2 PRECEDENCE OF OPERATORS Precedence Associativity Operators Description 1 highest left S Prefix operators 2 left amp multiply divide modulo 3 left add subtract 4 left gt gt lt lt bit shift right left 5 left gt lt lt gt Relational 6 le
195. int the program version number on the standard output and exit version 13 8 pic32 strip UTILITY The pic32 strip utility discards all symbols from the object and archive files specified At least one file must be given pic32 strip modifies the files named in its argument rather than writing modified copies under different names Input Output Files Syntax Options 13 8 1 Input Output Files Input Object or archive files Output Object or archive files If no object or archive files are listed as arguments pic32 strip assumes the file a out 13 8 2 Syntax Command line syntax is pic32 strip g S strip debug help K symbolname keep symbol symbolname N symbolname strip symbol symbolname o file p preserve dates R sectionname remove section sectionname s strip all strip unneeded v verbose V version x discard all X discard locals OBJFILE DS51833A page 156 2009 Microchip Technology Inc Other PIC32 MCU Binary Utilities 13 8 3 Options The long and short forms of options shown in Table as alternatives are equivalent pic32 strip Options Option Function g Remove debugging symbols only S strip debug help Show a summary of the options to pic32 strip and exit K symbolname keep symbol symbolname Keep only symbol symbolname from the source file T
196. ion Operands must be separated from mnemonics by one or more spaces or tabs Separate multiple operands with commas If commas do not separate your operands the assembler displays a warning and takes its best guess on the separation of the operands For most PIC32 MCU instructions an operand consists of a core general purpose register label literal or basereg offset 4 3 3 1 GENERAL PURPOSE REGISTER OPERANDS The PIC32 MCU core contains thirty two 32 bit general purpose registers used for integer operations and address calculation Most of the PIC32 MCU instructions require one or more GPR operands either for the source the destination or both Register operands are distinguished with a preceding dollar sign The register number immediately follows the dollar sign Example 4 1 shows assembly source code using register number operands However if you use the compilation driver pic32 gcc to preprocess the source code with the CPP style preprocessor before assembling you can take advantage of macros provided in the p32xxxx h header file provided with the C compiler These macros map conventional register names to the corresponding register number Example 4 2 shows assembly source code using conventional register names for operands See the MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 for additional infor mation on PIC32 MCU register conventions and the compiler s runtime environment EXAMPLE 4 1 ASSEMBLY S
197. ion must evaluate to a constant before memory allocation is performed which means that section relative symbols may not be used The keyword ORIGIN may be abbreviated to org or o but not for example ORG The 1enis an expression for the size in bytes of the memory region As with the origin expression the expression must evaluate to a constant before memory allocation is performed The keyword LENGTH may be abbreviated to 1en or 1 In the following example we specify that there are two memory regions available for allocation one starting at 0 for 48 kilobytes and the other starting at 0x800 for two kilobytes The linker will place into the xom memory region every section which is not explicitly mapped into a memory region and is either read only or executable The linker will place other sections which are not explicitly mapped into a memory region into the xam memory region MEMORY rom rx ORIGIN 0 LENGTH 48K ram rx org 0x800 1 2K Once a memory region is defined the linker can be directed to place specific output sections into that memory region by using the gt region output section attribute For example to specify a memory region named mem use gt mem in the output section definition If no address was specified for the output section the linker will set the address to the next available address within the memory region If the combined output sections directed to a memory region are too large for the reg
198. ion the linker will issue an error message 10 6 5 SECTIONS Command The SECTIONS command tells the linker how to map input sections into output sections and how to place the output sections in memory The format of the SECTIONS command is SECTIONS sections command sections command Each SECTIONS command may be one of the following an ENTRY command see Section 10 6 6 Other Linker Script Commands e a symbol assignment see Section 10 6 3 Assigning Values to Symbols an output section description an overlay description The ENTRY command and symbol assignments are permitted inside the SECTIONS command for convenience in using the location counter in those commands This can also make the linker script easier to understand because those commands can be used at meaningful points in the layout of the output file Output section descriptions and overlay descriptions are described below DS51833A page 118 2009 Microchip Technology Inc Linker Scripts If a SECTIONS command does not appear in the linker script the linker will place each input section into an identically named output section in the order that the sections are first encountered in the input files If all input sections are present in the first file for example the order of sections in the output file will match the order in the first input file The first section will be at address zero 10 6 5 1 INPUT SECTION DESCRIPTION T
199. ions Pass target specific information to the disassembler The PIC32 device supports the following target specific options symbolic Will perform symbolic disassembly prefix addresses When disassembling print the complete address on each line This is the older disassembly format r reloc Print the relocation entries of the file If used with d or D the relocations are printed interspersed with the disassembly s full contents Display the full contents of any sections requested S source Display source code intermixed with disassembly if possible Implies d show raw insn When disassembling instructions print the instruction in hex as well as in symbolic form This is the default except when prefix addresses is used no show raw insn When disassembling instructions do not print the instruction bytes This is the default when prefix addresses is used start address address Start displaying data at the specified address This affects the output of the d r and s options DS51833A page 152 2009 Microchip Technology Inc Other PIC32 MCU Binary Utilities TABLE 13 4 pic32 objdump OPTIONS CONTINUED Option Function stop address address Stop displaying data at the specified address This affects the output of the d r and s options t Print the symbol table entries of the file This is similar t
200. ister list The aregs field of a MIPS16e extended SAVE RESTORE instruction specified an invalid arg register list Invalid coprocessor 0 register number An invalid coprocessor 0 register number was passed to this instruction Invalid coprocessor sub selection value ld not in range 0 7 The coprocessor sub selection value must be in the range 0 7 Invalid frame size The frame size is not valid and could not be encoded Invalid identifier for ifdef The specified identifier is not a valid name It must begin with a legal character 2009 Microchip Technology Inc DS51833A page 171 32 Bit Assembler Linker and Utilities User s Guide Invalid register list In MIPS16 mode the register list contained an invalid register Invalid segment 96s Attempting to change the location counter in an invalid segment Invalid static register list The static register list should include only s2 s8 J Jump to misaligned address 0x Ix The jump target address is not aligned Junk at end of line first unrecognized character is char There are extraneous characters after the expected input Junk at end of line first unrecognized character valued Oxval There are extraneous characters after the expected input L Load store address overflow max 32 bits The load store address is greater than 32 bits wide Make sure that the label is correct Local label label is not defined A referenced local label was never defined L
201. ith an initial value Used for kseg0 program mem gp relative addressing Sdata Small variables compiled with Small initialized data segment ksegl data mem amp data sections Used for kseg0 program mem gp relative addressing sbss Uninitialized variables lt n bytes Small zero filled segment ksegl data mem compiled Gn Used for gp relative addressing Sbss Small uninitialized variables com Small zero filled segment ksegl data mem piled with data sections Used for gp relative addressing bss Uninitialized larger variables Zero filled segment ksegl data mem bss Uninitialized variables compiled Zero filled segment ksegl data mem with data sections heap Heap used for dynamic memory Reserved by linker script ksegl data mem Stack Minimum space reserved for stack Reserved by linker script ksegi data mem debug DWARF debug information Not in load image n a Line DWARF debug information Not in load image n a comment ident ident strings Not in load image n a reginfo Information section Not in load image n a Section Directive Examples section foo aw eprogbits foo is initialized Hdata memory section fob aw enobits Hfob is uninitialized but also not zeroed Hdata memory section bar ax eprogbits bar is in program memory DS51833A page 70 O 2009 Microchip Technology Inc Assembler Directives text Definition Assemble the following st
202. ker input and output files are listed below TABLE 8 1 LINKER FILES Extension Description Input 0 Object Files a Library Files ld Linker Script File Output exe out Linker Output Files map Map File Unlike the MPLINK linker the 32 bit linker does not generate absolute listing files The 32 bit linker is capable of creating a map file and a binary ELF file that may or may not contain debugging information For text output similar to the MPLINK linker listing file run the ELF file through the pic32 objdump binary utility 8 4 1 Object Files Relocatable code produced by the assembler The linker accepts the ELF object file format 8 4 2 Library Files A collection of object files grouped together for convenience 8 4 3 Linker Script File Linker scripts or command files Instruct the linker where to locate sections Specify memory ranges for a given part Can be customized to locate user defined sections at specific addresses For more on linker script files see Chapter 10 Linker Scripts nt DS51833A page 92 O 2009 Microchip Technology Inc Linker Overview EXAMPLE 8 1 LINKER SCRIPT Note a complete working linker script This simplified linker script example is for illustrative purposes only it is not OUTPUT FORMAT elf32 tradlittlemips OU PUT ARCH pic32mx ENTRY reset
203. le inserted along with one of the letters a or x to indicate whether the file was appended no old member deleted or replaced t Display a table listing the contents of ARCHIVE or those of the files listed in MEMBER thatare present in the archive Normally only the member name is shown if you also want to see the modes permissions timestamp owner group and size you can request that by also specifying the v modifier If you do not specify a MEMBER all files in the archive are listed For example if there is more than one file with the same name fie in an archive b a then pic32 ar t b a fie lists only the first instance to see them all you must ask for a complete listing in pic32 ar t b a 2009 Microchip Technology Inc DS51833A page 143 32 Bit Assembler Linker and Utilities User s Guide TABLE 12 1 OPERATION TO EXECUTE CONTINUED Option Function x Extract members named MEMBER from the archive You can use the v modifier with this operation to request that the archiver list each name as it extracts it If you do not specify a MEMBER all files in the archive are extracted A number of modifiers MOD may immediately follow the P keyletter to specify variations on an operation s behavior TABLE 12 2 MODIFIERS Option Function Add new files after an existing member of the archive If you use the modifier a the name of an existing archive member mu
204. le letter option arguments must either follow the option letter without intervening white space or be given as separate arguments immediately following the option that requires them For options whose names are multiple letters either one dash or two can precede the option name for example trace symbol and trace symbol are equivalent There is one exception to this rule Multiple letter options that begin with the letter o can only be preceded by two dashes Arguments to multiple letter options must either be separated from the option name by an equals sign or be given as separate arguments immediately following the option that requires them For example trace symbol srec and trace symbol srec are equivalent Unique abbreviations of the names of multiple letter options are accepted 9 3 COMPILATION DRIVER LINKER INTERFACE SYNTAX In practice the linker is usually invoked via pic32 gcc the compilation driver The basic form of the compilation driver command line is pic32 gcc options files Note Command line options and filename extensions are case sensitive To pass a linker option from the compilation driver to the linker use the W1 option option EXAMPLE 9 1 COMPILATION DRIVER COMMAND LINE pic32 gcc mprocessor 32MX360F512L input o o output elf Os Wl defsym min heap size 2048 Map mapfile map cref report mem Calling the linker via the compilation driver has a few advantages over calling t
205. ler uses the predefined type for the section Setting incorrect section type for name When setting section attributes on a special section the section s attributes should match those of the predefined type The assembler uses the predefined type for the section Size negative fill ignored The size argument to the 111 directive must be non negative T Tried to set unrecognized symbol name The symbol in the set directive was not a recognized PIC32 MCU assembler symbol Truncated file filename num1 of num2 bytes read The number of bytes read from the incbin file was fewer than the number specified in the counts argument U Unknown escape lescape in string ignored The string contains an unrecognized backslash escaped character Check that the character following the backslash is correct Used at without set noat This code is using the at assembler temporary register but the assembler may use it when generating synthesized macro instruction Use the zer noat directive to tell the assembler not to quietly use this register B 5 MESSAGES The assembler generates messages when a non critical assumption is made so that the assembler could continue assembling a flawed program Messages may be ignored However messages can sometimes point out bugs in your program DS51833A page 178 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE
206. lines for using complex expressions in assembler source files Chapter 6 Assembler Symbols describes what symbols are and how to use them Chapter 7 Assembler Directives details the available assembler directives Part 2 MPLAB Object Linker for PIC32 MCUs Chapter 8 Linker Overview gives an overview of linker operation Chapter 9 Linker Command Line Interface details command line options for the linker Chapter 10 Linker Scripts describes how to generate and use linker scripts to control linker operation Chapter 11 Linker Processing discusses how the linker builds an applica tion from input files Part 3 Binary Utilities for PIC32 MCUs Chapter 12 MPLAB Object Archiver Librarian for PIC32 MCUs details command line options for the archiver librarian Chapter 13 Other PIC32 MCU Binary Utilities details the other utilities and their operation Utilities include pic32 bin2hex binary to hexadecimal conver sion pic32 nm listing symbols in an object file pic32 objdump displaying infor mation about object files pic32 ranlib creating an archive index pic32 size pic32 strings printing character sequences and pic32 strip discarding all sym bols from an object file Part 4 Appendices Appendix A Frequently Asked Questions lists frequenty asked questions about 32 bit language tool operation Appendix B Assembler Errors Warnings Messages
207. lly used to set the size of function symbols Sleb128 expr exprjl sleb128 stands for signed little endian base 128 This is a compact variable length representation of numbers used by the DWARF symbolic debugging format type name description This sets the type of symbol name to be either a function symbol or an object symbol There are five different syntaxes supported for the type description field in order to provide compatibility with various other assemblers The syntaxes supported are type lt name gt function type lt name gt object type lt name gt function type lt name gt object type lt name gt function type lt name gt object type lt name gt function type lt name gt object type lt name gt STT_FUNCTION type lt name gt STT_OBJECT uleb128 expr expr uleb128 stands for unsigned little endian base 128 This is a compact variable length representation of numbers used by the DWARF symbolic debugging format DS51833A page 86 2009 Microchip Technology Inc Assembler Directives 7 13 DIRECTIVES THAT CONTROL CODE GENERATION Directives controlling assembler code generation behavior are set noat e Set at Set noautoextend Set autoextend Set nomacro set macro e Set mipsl6e e Set nomipsl6e Set noreorder e Set reorder set noat When synthesizing some address formats the assembler may require
208. ls Installation 6 Select MPLAB LINK30 Object Linker pic32 1d exe Under Location a path to the executable file should be displayed If no path is displayed enter one or browse to the location of this file The default location is listed in Section MPLAB IDE and Tools Installation 7 Select LIB30 Archiver pic32 ar exe Under Location a path to the exe cutable file should be displayed If no path is displayed enter one or browse to the location of this file The default location is listed in Section MPLAB IDE and Tools Installation 8 Click OK DS51833A page 8 O 2009 Microchip Technology Inc 32 Bit Language Tools and MPLAB IDE MPLAB IDE PROJECTS A project in MPLAB IDE is a group of files needed to build an application along with their associations to various build tools Below is a generic MPLAB IDE project FIGURE 2 PROJECT RELATIONSHIPS MPLAB IDE Project C Source Files c Assembly Source Files S C Compiler v Source Files s p Assembler E y Object Files 0 p Archiver Librarian Object File Libraries 1 Linker Script a Linker 1d L em m e e e mm mm mm mm mm mm mm min mm i mo m m ed MPLAB IDE ag Debug Tool Executable File ebug 100 exe Command Line Simul
209. lternatives are equivalent TABLE 13 5 pic32 ranlib OPTIONS Option Function v Show the version number of pic32 ranlib V version h Print a help message help 2009 Microchip Technology Inc DS51833A page 153 32 Bit Assembler Linker and Utilities User s Guide 13 6 pic32 size UTILITY The pic32 size Utility lists the section sizes and the total size for each of the object or archive files in its argument list By default one line of output is generated for each object file or each module in an archive Note The linker s report mem memory usage report provides additional information on memory usage Input Output Files Syntax Options Example 13 6 1 Input Output Files Input Object or archive file s Output Standard output 13 6 2 Syntax The pic32 size command line syntax is pic32 size A B format compatibility help da o x radix number t totals v version objfile 13 6 3 Options The pic32 size options are shown below TABLE 13 6 pic32 size OPTIONS Option Function A Using one of these options you can choose whether the out B put from gnu size resembles output from System V size using format compatibility Aor format sysv or Berkeley size using B or format berkeley The default is the one line format similar to Berkeley s help Show a summary of accep
210. mbler has the following prefix operators Each takes one argument which must be absolute TABLE 5 1 PREFIX OPERATORS Operator Description Example Negation Two s complement negation 1 Bit wise not One s complement flags 5 3 2 Infix Operators Infix operators take two arguments one on either side Operators have a precedence by type as shown in the table below but operations with equal precedence are per formed left to right Apart from or both operators must be absolute and the result is absolute TABLE 5 2 INFIX OPERATORS Operator Description Example Arithmetic Multiplication 5 4 20 Division Truncation is the same as the C operator 7 23 4 5 E Remainder 30 4 2 Shift Left Same as the C operator lt lt 2 lt lt 1 4 gt gt Shift Right Same as the C operator gt gt 2 sd b Bit Wise amp Bit wise And 4 amp 6 24 Bit wise Exclusive Or A 7 6622 Bit wise Or Not 0x1010 0x5050 0xBFBF Bit wise Inclusive Or 2 4 6 Simple Arithmetic Addition If either argument is absolute the result has the 4 10 14 section of the other argument You may not add together arguments from different sections Subtraction If the right argument is absolute the result 14 4 10 has the section of the left argument If both arguments are in the same section the result is absolute You
211. mbler programs Normally both the assembler and linker discard such symbols This option tells the assembler to retain those symbols in the object files 3 6 3 o objfile Name the object file output obj file In the absence of errors there is always one object file output when you run the assembler By default it has the name a out Use this option which takes exactly one filename to give the object file a different name Whatever the object file is called the assembler overwrites any existing file with the same name 3 6 4 Z Generate object file even after errors After an error message the assembler normally produces no output If for some reason you are interested in object file output even after the assembler gives an error message use the Z option If there are any errors the assembler continues anyway and writes an object file after a final warning message of the form n errors m warnings generating bad object file 3 6 5 MD file Write dependency information to file The assembler can generate a dependency file This file consists of a single rule suitable for describing the dependencies of the main source file The rule is written to the file named in its argument This feature can be used in the automatic updating of makefiles 2009 Microchip Technology Inc DS51833A page 47 32 Bit Assembler Linker and Utilities User s Guide 3 7 ASSEMBLER SYMBOL DEFINITION AND SEARCH PATH OPTIONS The options in this
212. mbly am Include macro expansions an Omit forms processing as Include symbols a file Output listing to specified file must be in current directory If no sub options are specified the default sub options used are h1s the a option by itself requests high level assembly and symbolic listing You can use other letters to select specific options for the listing output The letters after the a may be combined into one option So for example instead of specifying al an on the command line you could specify aln 2009 Microchip Technology Inc DS51833A page 35 32 Bit Assembler Linker and Utilities User s Guide 3 4 1 1 ac ac omits false conditionals from a listing Any lines that are not assembled because of a false if or ifdef orthe e1seofatrue if or ifdef will be omitted from the listing Example 3 2 shows a listing where the ac option was not used Example 3 3 shows a listing for the same source where the ac option was used EXAMPLE 3 2 LISTING FILE GENERATED WITH a1 COMMAND LINE OPTION GAS LISTING asm s page 1 1 1 asm S 2 1 lt built in gt 1 data 0 2 if 0 3 sd 4 endif 5 long 0 6 if 0 7 long 0 8 endif 9 else 10 ZEE 11 endif 12 0000 02000000 long 2 13 if 0 14 long 3 15 else 16 0004 04000000 long 4 17 endif 18 endif 19 if 0 20 long 5 21 elseif 1 22 if 0 23 long 6 24 elseif 1 25 0008 07000000 long 7 26 endif 27 elseif 1 28 long 8 29 else
213. mple Store Word example la v0 MY WORD DATA lui v1 0x1111 ori v1 v1 0x4432 lui a0 0x5555 ori a0 a0 0x1123 sw vl O vO Mem GPR v0 0 GPR v1 sw a0 4 v0 Mem GPR v0 4 GPR aO lw al O vO GPR al lt Mem GPR v0 0 b a The C compiler supports global pointer relative gp rel addressing Loads and stores to data lying within 32 KB of either side of the address stored in the gp register 64 KB total can be performed in a single instruction using the gp register as the base register DS51833A page 54 2009 Microchip Technology Inc Assembler Syntax The C compiler s Gnum option controls the maximum size of global and static data items that can be addressed in one instruction instead of two The compiler s default gnum value is 8 bytes which is large enough to hold all simple scalar variables Note Toutilize gp relative addressing the compiler and assembler must group all of the small variables and constants into one of the small sections See section 5 7 2 of the MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 for more information on the global pointer and the G option EXAMPLE 4 4 ASSEMBLY SOURCE CODE WITH GP RELATIVE ADDRESSING align 2 globl foo Set nomipsi6 Sent foo foo set noreorder set nomacro lw 3 gp rel testval 28 addiu 2 3 1 Sw 2 gp rel testval 28 j 31 nop set macro set reorder end foo There are a few
214. n This directive attempts to allocate data to a section that isn t allocatable Allocate the data to another section instead Attempt to get value of unresolved symbol name The assembler could not get the value of an unresolved symbol Attempt to set value of section symbol Assignments to section symbols are not legal Backward ref to unknown label abel The referenced label is either not seen or not defined here Bad common segment name Could not determine an appropriate alignment value for a comm symbol A previously seen comm symbol may be incorrect Bad escaped character in string The string uses a non standard backslash escaped characer Bad expression The expression type cannot be determined or an operand is not of the correct type for the expression type Bad floating literal 96s The token could not be converted to a floating point value Bad floating point constant exponent overflow The token could not be converted to a floating point value because of exponent over flow Bad floating point constant unknown error code d The token could not be converted to a floating point value 2009 Microchip Technology Inc DS51833A page 169 32 Bit Assembler Linker and Utilities User s Guide Bad format for ifc or ifnc The arguments to the ifc or ifnc directive are incorrect They must be 2 comma separated double quoted strings Bad or irreducible absolute expression The absolute expression had
215. n MPLAB IDE Setup MPLAB IDE Projects Project Setup Project Example MPLAB IDE AND TOOLS INSTALLATION In order to use the 32 bit language tools with MPLAB IDE you must first install MPLAB IDE The latest versions of this software are available at our web site http Awww microchip com or from any sales office back cover When you install MPLAB IDE you will be installing the 32 bit compiler standard evaluation version assembler object linker and supporting utilities as well The language tools will be installed by default in the directory C Program Files Microchip MPLAB C32 Suite bin The executables for each tool will be in this directory Compiler pic32 gcc exe Assembler pic32 as exe Object Linker pic32 1d exe Archiver Librarian pic32 ar exe Other Utilities pic32 utility exe All include header files are in the directory C Program Files Microchip MPLAB C32 Suite pic32mx include For more on these files see the assembler documentation All device linker script files are in the directory C Program Files Microchip MPLAB C32 Suiten pic32mx lib ldscripts For more on these files see the object linker documentation Code examples are also included in the directory C Program Files Microchip MPLAB C32 Suite examples 2009 Microchip Technology Inc DS51833A page 7 32 Bit Assembler Linker and Utilities User s Guide MPLAB IDE SETUP Once MPLAB IDE is installed on your PC
216. n common Warn about duplicate common symbols Warn when a common symbol is combined with another common symbol or with a symbol definition This option allows you to find potential problems from combining global symbols There are three kinds of global symbols illustrated here by C examples int IL zs 1 DS51833A page 108 2009 Microchip Technology Inc Linker Command Line Interface A definition which goes in the initialized data section of the output file extern int i An undefined reference which does not allocate space There must be either a definition or a common symbol for the variable somewhere int i A common symbol If there are only one or more common symbols for a variable it goes in the uninitialized data area of the output file The linker merges multiple common symbols for the same variable into a single symbol If they are of different sizes it picks the largest size The linker turns a common symbol into a declaration if there is a definition of the same variable The warn common option can produce five kinds of warnings Each warning consists of a pair of lines the first describes the symbol just encountered and the second describes the previous symbol encountered with the same name One or both of the two symbols will be a common symbol Turning a common symbol into a reference because there is already a definition for the symbol file section warning common of symbol overridde
217. n by definition file section warning defined here Turning a common symbol into a reference because a later definition for the symbol is encountered This is the same as the previous case except that the symbols are encountered in a different order File section warning definition of symbol overriding common file section warning common is here Merging a common symbol with a previous same sized common symbol File section warning multiple common of symbol file section warning previous common is here Merging a common symbol with a previous larger common symbol File section warning common of symbol overridden by larger common file section warning larger common is here Merging a common symbol with a previous smaller common symbol This is the same as the previous case except that the symbols are encountered in a different order file section warning common of symbol overriding smaller common file section warning smaller common is here 9 7 12 warn once Warn only once for each undefined symbol rather than once per module that refers to it 9 7 13 warn section align Warn if start of section changes due to alignment This means a gap has been intro duced into the normally sequential allocation of memory Typically an input section will set the alignment The address will only be changed if it is not explicitly specified that is if the SECTIONS command does not specif
218. n error if symbol is already defined Note that a symbol which has been referenced but not actually defined is considered to be undefined Except for the contents of the error message this directive is roughly equivalent to ifdef SYM err endif equ SYM VAL c Ug 2009 Microchip Technology Inc DS51833A page 75 32 Bit Assembler Linker and Utilities User s Guide 7 6 DIRECTIVES THAT MODIFY SECTION ALIGNMENT Directives that explicitly modify section alignment are listed below Note User code must take care to properly align an instruction following a direc tive that modifies the section alignment or location counter e align algn filll fill repeat size value e org new lc fill Skip size fill Space size fill Struct expression align algn fi1111 The align directive pads the location counter in the current subsection to a partic ular storage boundary The first expression which must be absolute is the alignment required specified as the number of low order zero bits the location counter must have after advancement The assembler accepts algn values from 0 up to 15
219. n external input signal logic probe line TRIGIN for setting an event based upon external signals External RAM Off chip Read Write memory Fatal Error An error that will halt compilation immediately No further messages will be produced File Registers On chip data memory including General Purpose Registers GPRs and Special Function Registers SFRs Filter Determine by selection what data is included excluded in a trace display or data file Flash A type of EEPROM where data is written or erased in blocks instead of bytes FNOP Forced No Operation A forced NOP cycle is the second cycle of a two cycle instruction Since the PIC microcontroller architecture is pipelined it prefetches the next instruction in the physical address space while it is executing the current instruction However if the current instruction changes the program counter this prefetched instruction is explicitly ignored causing a forced NOP cycle DS51833A page 198 2009 Microchip Technology Inc Glossary Frame Pointer A pointer that references the location on the stack that separates the stack based arguments from the stack based local variables Provides a convenient base from which to access local variables and other values for the current function Free Standing An implementation that accepts any strictly conforming program that does not use complex types and in which the use of the features specified in the library clause ANSI
220. name and a size Most sections also have an associated block of data known as the section contents A section may be marked as loadable which mean that the contents should be loaded into memory when the output file is run A section with no contents may be allocatable which means that an area in memory should be set aside but nothing in particular should be loaded there in some cases this memory must be zeroed out Every loadable or allocatable output section has two addresses The first is the VMA or virtual memory address This is the address the section will have when the output file is run The second is the LMA or load memory address This is the address at which the section will be loaded In most cases the two addresses will be the same An example of when they might be different is when a section is intended to contain RAM located functions e g the default ramfunc section In this case the program memory address would be the LMA and the data memory address would be the VMA Note Both the VMA and the LMA use the PIC32 MCU s virtual address See the PIC32MX Family Reference Manual DS61115 for a description of the PIC32MX Virtual to Physical Fixed Memory Mapping In addition the family reference manual describes the PIC32 memory layout The sections in an object file can be viewed by using the pic32 objdump program with the h option Every object file also has a list of symbols known as the symbol table A symb
221. nction clears the specified bits of IOPORT A pre condition ra contains return address Input Bit mask in a0 Output none Side effect clears bits in IOPORT A BRK KR RR KKK KK RR KK RR RR RR RR RRR RR KK RR k kk ent mPORTAClearBits mPORTAClearBits function prologue save registers used in this function on stack and adjust stack pointer addiu sp sp 4 sw s0 O sp la s0 LATACLR Sw a0 0 s0 clear specified bits function epilogue restore registers used in this function from stack and adjust stack pointer lw s0 0 sp addiu sp sp 4 return to caller jr ra nop end mPORTAClearBits For more information see also Chapter 4 Assembler Syntax and Chapter 7 Assembler Directives DS51833A page 20 O 2009 Microchip Technology Inc Assembler Overview 1 4 2 Object File The assembler creates a relocatable ELF object file The object files do not yet have addresses resolved and must be linked before they can be used for an executable By default the name of the object file created is a out Specify the o option See Chapter 3 Assembler Command Line Interface on the command line to override the default name 1 4 3 Listing File The assembler has the capability to produce a listing file The listing file is not an abso lute listing file and the addresses that appear in the listing are relative to the start of its section
222. nd Line Interface 9 4 9 nodefaultlibs Do not use the standard system libraries when linking Only the libraries you specify are passed to the linker The compiler may generate calls to memcmp memset and memcpy These entries are usually resolved by entries in the standard compiler librar ies These entry points should be supplied through some other mechanism when this option is specified 9 4 10 nostartfiles Do not pass the default prebuilt C start up file pic32mx 1ib crt0 o to the linker You will provide your own version of the start up code for the application 9 4 11 nostdlib Do not use the standard system start up files or libraries when linking No start up files and only the libraries you specify are passed to the linker The compiler may generate calls to memcmp memset and memcpy These entries are usually resolved by entries in standard compiler libraries These entry points should be supplied through some other mechanism when this option is specified 9 4 12 output file o file Set output ELF file name Use file as the name for the program produced by pic32 14d if this option is not specified the name a out is used by default 9 4 13 relocatable r i Ur Generate relocatable output l e generate an output file that can in turn serve as input to pic32 1d This is often called partial linking If this option is not specified an absolute file is produced 9 4 14 retain symbols file file
223. ne IHUUHUIHUHHBHHBHHBHHGHHGHHNUE text set noreorder ent main Do something here nop Infinite loop b 1b nop end main globl main Now select Run under the Debugger menu to begin the simulation You should momentarily see a progress bar in the bottom status bar of the MPLAB IDE window This progress bar indicates that the simulator target is running Once the simulation reaches the breakpoint a green arrow appears in the gutter on top of the breakpoint icon This green arrow indicates that the target device s program counter halted at the address associated with that line of your source code You have now successfully built a new PIC32 assembly code project in MPLAB IDE and run it in MPLAB SIM You re ready to begin your application development by adding your own code See the online help under MPLAB IDE s Help menu for more information on MPLAB SIM or other debug tools A nio 2009 Microchip Technology Inc DS51833A page 31 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 32 O 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 3 Assembler Command Line Interface
224. ng a collection of other files in a structure that makes it possible to retrieve the orig inal individual files called members of the archive All objects are processed in the ELF object file format pic32 ar is considered a binary utility because archives of this sort are most often used as libraries holding commonly needed subroutines DS51833A page 142 2009 Microchip Technology Inc MPLAB Object Archiver Librarian for PIC32 MCUs 12 5 SYNTAX pic32 ar P MOD RELPOS COUNT ARCHIVE MEMBER pic32 ar M mri script 12 6 OPTIONS When you use the 32 bit archiver librarian with command line options the archiver insists on at least two arguments to execute one key letter specifying the operation optionally accompanied by other key letters specifying modifiers and the archive name pic32 ar P MOD RELPOS COUNT ARCHIVE MEMBER Note Command line options are case sensitive Most operations can also accept further MEMBER arguments specifying archive members Without specifying members the entire archive is used The 32 bit archiver librarian allows you to mix the operation code P and modifier flags MOD in any order within the first command line argument If you wish you may begin the first command line argument with a dash The P keyletter specifies what operation to execute it may be any of the following but you must specify only one of them TABLE 12 1 OPERATION TO EXECUTE Op
225. nker defines several that are useful for locating data in specific areas of 32 bit memory Section directives are bss data pushsection name popsection e Section name flags type text bss Definition Assemble the following statements onto the end of the bss uninitialized data section The bss section is used for local common variable storage You may allocate address space in the bss section but you may not dictate data to load into it before your pro gram executes When your program starts running all the contents of the bss section are zeroed bytes Use the bss directive to switch into the bss section and then define symbols as usual You may assemble only zero values into the section Typically the section will contain only symbol definitions and skip directives Example The following symbols B1 and B2 will be placed in the uninitialized data section bss B1 Space 4 4 bytes reserved for B1 B2 Space 1 1 byte reserved for B2 data Definition Assemble the following statements onto the end of the data initialized data section Example The following symbols D1 and D2 will be placed in the initialized data section data D1 long 0x12345678 H 4 bytes D2 byte OxFF H 1 byte pushsection name This directive pushes the current section onto the top of the section stack and then replaces the current section with name Every pushsect ion should have a match
226. nnnononononononanincnanananonos 186 Appendix E GNU Free Documentation License E Pra Ml ter tette De ebe d dt 187 E 2 Applicability and Definitions cil ia 187 E 3 Verbatim Copylrig cerisier rti idas 189 EA Copying In Quantity E 189 E 5 Modifications 190 E 6 Gombimng Docurmenls secciones 191 E 7 Collections of Documents as aa nnne 191 E 8 Aggregation with Independent Works AAA 192 E 9Fr nslatlOn ME 192 E107 Termlinatiot r c rt cea E TG ec p EE RR YE AE SEA VER NEN E CORNER ES 192 E 11 Future Revisions of this License sseeeeeseeeeee 192 Glossary E 193 O AA e e oil 213 Worldwide Sales and Service ccoooonnnccccccnonnnccccccnnnanannnnnnnnnnnrrrcrnnnnnnrnnrrnnnanannarrnaannnnnn 222 DS51833A page vi 2009 Microchip Technology Inc Y MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Preface NOTICE TO CUSTOMERS All documentation becomes dated and this manual is no exception Microchip tools and documentation are constantly evolving to meet customer needs so some actual dialogs and or tool descriptions may differ from those in this document Please refer to our web site www microchip com to obtain the latest documentation available Documenis are identified with a DS number This number is located on the bottom of each page in front of the page number The numbering convention for the DS number is DSXXXXXA where XXXXX is the document number an
227. nother language A Secondary Section is a named appendix or a front matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Documents overall subject or to related matters and contains nothing that could fall directly within that overall subject Thus if the Document is in part a textbook of 2009 Microchip Technology Inc DS51833A page 187 32 Bit Assembler Linker and Utilities User s Guide mathematics a Secondary Section may not explain any mathematics The relation ship could be a matter of historical connection with the subject or with related matters or of legal commercial philosophical ethical or political position regarding them The Invariant Sections are certain Secondary Sections whose titles are designated as being those of Invariant Sections in the notice that says that the Document is released under this License If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant The Document may contain zero Invariant Sections If the Document does not identify any Invariant Sections then there are none The Cover Texts are certain short passages of text that are listed as Front Cover Texts or Back Cover Texts in the notice that says that the Document is released under this License A Front Cover Text may be at most 5 words and a Back Cover Text may be at most 25 words A Transpar
228. ntable character By default it only prints the strings from the initialized and loaded sections of object files for other types of files it prints the strings from the whole file pic32 strings is mainly useful for determining the contents of non text files Input Output Files Syntax Options 13 7 1 Input Output Files Input ELF object file Output Standard output 13 7 2 Syntax Command line syntax is pic32 strings a all print file name help min len n min len bytes min len t radix radix radix v version FILE 2009 Microchip Technology Inc DS51833A page 155 32 Bit Assembler Linker and Utilities User s Guide 13 7 3 Options The long and short forms of options shown in Table 13 7 as alternatives are equivalent TABLE 13 7 pic32 strings OPTIONS Option Function a Do not scan only the initialized and loaded sections of object files all scan the whole files f Print the name of the file before each string print file name help Print a summary of the program usage on the standard output and exit min len Print sequences of characters that are at least min len n min len characters long instead of the default 4 bytes min len t radix Print the offset within the file before each string The single radix radix character argument specifies the radix of the offset o for octal x for hexadecimal or d for decimal v Pr
229. ntation The Microchip web site contains many documents that describe 32 bit device functions and features Among these are Individual and family data sheets Family reference manuals Programmer s reference manuals DS51833A page 4 2009 Microchip Technology Inc Preface THE MICROCHIP WEB SITE Microchip provides online support via our web site at www microchip com This web site is used as a means to make files and information easily available to customers Accessible by using your favorite Internet browser the web site contains the following information e Product Support Data sheets and errata application notes and sample programs design resources user s guides and hardware support documents latest software releases and archived software General Technical Support Frequently Asked Questions FAQs technical support requests online discussion groups Microchip consultant program member listing Business of Microchip Product selector and ordering guides latest Microchip press releases listing of seminars and events listings of Microchip sales offices distributors and factory representatives DEVELOPMENT SYSTEMS CUSTOMER CHANGE NOTIFICATION SERVICE Microchip s customer notification service helps keep customers current on Microchip products Subscribers will receive e mail notification whenever there are changes updates revisions or errata related to a specified product family or development tool of i
230. nterest To register access the Microchip web site at www microchip com click on Customer Change Notification and follow the registration instructions The Development Systems product group categories are Compilers The latest information on Microchip C compilers assemblers linkers and other language tools These include all MPLAB C compilers all MPLAB assemblers including MPASM assembler all MPLAB linkers including MPLINK object linker and all MPLAB librarians including MPLIB object librarian Emulators The latest information on Microchip in circuit emulators These include the MPLAB REAL ICE MPLAB ICE 2000 and MPLAB ICE 4000 in circuit emulators In Circuit Debuggers The latest information on Microchip in circuit debuggers These include the MPLAB ICD 2 and 3 in circuit debuggers and PICkit 2 and 3 debug express MPLAB IDE The latest information on Microchip MPLAB IDE the Windows9 Integrated Development Environment for development systems tools This list is focused on the MPLAB IDE MPLAB IDE Project Manager MPLAB Editor and MPLAB SIM simulator as well as general editing and debugging features Programmers The latest information on Microchip programmers These include the MPLAB PM3 and PRO MATE II device programmers and the PICSTART Plus and PICkit 1 2 and 3 development programmers 2009 Microchip Technology Inc DS51833A page 5 32 Bit Assembler Linker and Utilities User s Guide
231. o sum to 9 from 17 endm Mark the end of a macro definition exitm Exit early from the current macro definition V The assembler maintains a counter of how many macros it has executed in this pseudo variable you can copy that number to your output with but only within a macro definition In the following example a recursive macro is used to allocate an arbitrary number of labeled buffers macro make buffers num size BUF space size if num 1 make buffers num 1 size endif endm bss create BUFO BUF3 16 bytes each make buffers 4 16 This example macro expands as shown in the following listing 6 make buffers num 1 1size 7 endif 8 endm 9 10 bss 11 H create BUFO BUF3 16 bytes each 12 make buffers 4 16 12 gt BUFO space 16 12 0000 gt space 16 DS51833A page 82 2009 Microchip Technology Inc Assembler Directives 12 gt if 4 1 12 gt make_buffers 4 1 16 12 gt gt BUF1 space 16 12 0010 gt gt space 16 12 gt gt if 4 1 1 12 gt gt make buffers 4 1 1 16 12 gt gt gt BUF2 space 16 12 0020 gt gt gt space 16 12 gt gt gt if 4 1 1 1 12 gt gt gt make buffers 4 1 1 1 16 12 gt gt gt gt BUF3 space 16 12 0030 gt gt gt gt space 16 12 gt gt gt gt if 4 1 1 1 1 12 gt gt gt gt make_buffers 4 1 1 1 1 16 12 gt gt gt gt endif 12 gt gt gt endif 12
232. o the syms information provided by the pic32 nm program V Print the version number of pic32 objdump and exit version W Format some lines for output devices that have more than wide 80 columns x Display all available header information including the all header symbol table and relocation entries Using x is equivalent to specifying allof a h r t zZ Normally the disassembly output will skip blocks of zeroes disassemble zeroes This option directs the disassembler to disassemble those blocks just like any other data 13 5 pic32 ranlib UTILITY The pic32 ranlib utility generates an index to the contents of an archive and stores it in the archive The index lists each symbol defined by a member of an archive that is a relocatable object file You may use pic32 nm sorpic32 nm print armap to list this index An archive with such an index speeds up linking to the library and allows routines in the library to call each other without regard to their placement in the archive Running pic32 ranlib is completely equivalent to executing pic32 ar s i e the 32 bit archiver librarian with the s option Input Output Files Syntax Options 13 5 4 Input Output Files Input Archive file Output Archive file 13 5 2 Syntax Command line syntax is pic32 ranlib v V version ARCHIVE pic32 ranlib h help 13 5 3 Options The long and short forms of options shown here as a
233. o these copies of the Docu ment then if the Document is less than one half of the entire aggregate the Docu ment s Cover Texts may be placed on covers that bracket the Document within the aggregate or the electronic equivalent of covers if the Document is in electronic form Otherwise they must appear on printed covers that bracket the whole aggregate E9 TRANSLATION Translation is considered a kind of modification so you may distribute translations of the Document under the terms of section 4 Replacing Invariant Sections with transla tions requires special permission from their copyright holders but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections You may include a translation of this License and all the license notices in the Document and any Warranty Disclaimers provided that you also include the original English version of this License and the original versions of those notices and disclaimers In case of a disagreement between the translation and the original version of this License or a notice or disclaimer the original version will prevail o If a section in the Document is Entitled Acknowledgements Dedications or History the requirement section 4 to Preserve its Title section 1 will typically require changing the actual title E 10 TERMINATION You may not copy modify sublicense or distribute the Document except as expressly p
234. ochip Technology Incorporated in the U S A Analog for the Digital Age Application Maestro CodeGuard dsPICDEM dsPICDEM net dsPICworks dsSPEAK ECAN ECONOMONITOR FanSense In Circuit Serial Programming ICSP ICEPIC Mindi MiWi MPASM MPLAB Certified logo MPLIB MPLINK mTouch nanoWatt XLP PICkit PICDEM PICDEM net PICtail PIC3 logo PowerCal Powerlnfo PowerMate PowerTool REAL ICE rfLAB Select Mode Total Endurance TSHARC WiperLock and ZENA are trademarks of Microchip Technology Incorporated in the U S A and other countries SQTP is a service mark of Microchip Technology Incorporated in the U S A All other trademarks mentioned herein are property of their respective companies 2009 Microchip Technology Incorporated Printed in the U S A All Rights Reserved gt Printed on recycled paper Microchip received ISO TS 16949 2002 certification for its worldwide headquarters design and wafer fabrication facilities in Chandler and Tempe Arizona Gresham Oregon and design centers in California and India The Company s quality system processes and procedures are for its PIC MCUs and dsPIC DSCs KEELOQ code hopping devices Serial EEPROMs microperipherals nonvolatile memory and analog products In addition Microchip s quality system for the design and manufacture of development systems is ISO 9001 2000 certified DS51833A page ii 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND
235. ochip Technology Inc DS51833A page 85 32 Bit Assembler Linker and Utilities User s Guide frame framereg frameoffset retreg This directive describes the shape of the stack frame The virtual Frame Pointer in use is ramereg normally this is either fp or sp The Frame Pointer is frameoffset bytes below the canonical frame address CFA which is the value of the Stack Pointer on entry to the function The return address is initially located in ret reg until it is saved as indicated in mask loc fileno lineno columnno The object file s debugging information contains a line number matrix that correlates an assembly instruction to a line and column of source code The 1oc directive will add a matrix row corresponding to the assembly instruction immediately following the direc tive The fileno lineno and columnno will be applied to the debug state machine before the row is added mask mask offset Indicate which of the integer registers are saved in the current function s stack frame mask is interpreted a bit mask in which bit n set indicates that register n is saved The registers are saved in a block located o set bytes from the canonical frame address CFA which is the value of the Stack Pointer on entry to the function Size name expression This directive sets the size associated with a symbol name The size in bytes is computed from expression which can make use of label arithmetic This directive is typica
236. of devices The 32 bit linker is a Windows console application that provides a platform for developing executable code The linker is a part of the GNU linker from the Free Software Foundation Topics covered in this chapter are Linker and Other Development Tools Feature Set Input Output Files LINKER AND OTHER DEVELOPMENT TOOLS The PIC32 linker translates object files from the PIC32 assembler and archives files from the PIC32 archiver librarian into an executable file See Figure 8 1 for an overview of the tools process flow FIGURE 8 1 TOOLS PROCESS FLOW C Source Files c d Compiler Assembly Source Driver Files S C Compiler Program Source Files s i t Fil Archiver Librarian Sr M Object File Libraries Linker Linker Script a 1d MPLAB IDE Debug Tool Hf Executable File elf Simulator Command Line 2009 Microchip Technology Inc DS51833A page 91 32 Bit Assembler Linker and Utilities User s Guide 8 3 FEATURE SET Notable features of the linker include User defined minimum stack allocation User defined heap allocation Available for Windows Linker scripts for all current PIC32 devices e Command Line Interface Integrated component of MPLAB IDE 8 4 INPUT OUTPUT FILES Lin
237. ol s definition cannot depend on its own value Syntax error in startof Or sizeof The assembler found either startof or sizeof but did not find the beginning parenthesis or ending parenthesis T This string may not contain 0 The string must be a valid C string and cannot contain o Treating warnings as errors The assembler has been instruction to treat all warnings as errors with the fatal warnings command line option 2009 Microchip Technology Inc DS51833A page 173 32 Bit Assembler Linker and Utilities User s Guide U Unassigned file number num The 1oc directive specifies a file number that is not yet in use Unclosed An open is unmatched with a closing Add the missing Unexpected register in list In MIPS16 mode an invalid register was used Check the operands for this instruction DS51833A page 174 2009 Microchip Technology Inc Assembler Errors Warnings Messages BA WARNINGS The assembler generates warnings when an assumption is made so that the assembler could continue assembling a flawed program Warnings should not be ignored Each warning should be specifically looked at and corrected to ensure that the assembler understands what was intended Warning messages can sometimes point out bugs in your program Symbol end directive missing or unknown symbol The end function debugging info directive is missing or the a
238. ol may be defined or undefined Each symbol has a name and each defined symbol has an address among other information If a C program is compiled into an object file a defined symbol will be created for every defined function and global or static variable Every undefined function or global variable which is referenced in the input file will become an undefined symbol Symbols in an object file can be viewed by using the pic32 nm program or by using the pic32 objdump program with the t option 10 6 2 Commands Dealing with Files Several linker script commands deal with files INCLUDE filename DS51833A page 114 2009 Microchip Technology Inc Linker Scripts Include the linker script filename at this point The file will be searched for in the current directory and in any directory specified with the L option Calls to INCLUDE may be nested up to 10 levels deep INPUT file file INPUT file file The INPUT command directs the linker to include the named files in the link as though they were named on the command line The linker will first try to open the file in the current directory If it is not found the linker will search through the archive library search path See the description of L in Section 9 4 8 library path dir L lt dir gt If INPUT 1file is used pic32 1d will transform the name to libfile a as with the command line argument 1 When the INPUT command appears in an implicit
239. on GUI format 2009 Microchip Technology Inc DS51833A page 11 32 Bit Assembler Linker and Utilities User s Guide Errors and Warnings Category Generate Command Line Make warnings into errors Select to halt compilation based on warnings as well as errors Equivalent to Werror option Additional warnings Enable all warnings Equivalent to Wa11 option Support all ANSI stan dard programs Support all and only ASCI C programs Equivalent to ansi option Strict ANSI warnings Issue all warnings demanded by strict ANSI C Equivalent to pedantic option Restore Defaults Restore tab default settings Use Alternate Settings Text Box Enter options in a command line non GUI format Build Options Dialog MPLAB PIC32 Linker Tab A subset of command line options may be specified in MPLAB IDE in the Build Options dialog MPLAB PIC32 Linker tab Select a category and then set up linker options For additional options see MPLAB Object Linker for PIC32 MCUs documentation General Category Generate Command Line Heap Size Specify the size of the heap in bytes Same as defsym min heap size size option Min Stack Size Specify the minimum size of the stack in bytes Same as defsym min stack size size option Allow overlapped sec tions Do not check section addresses for overlaps Same as no check sections option Remove unuse
240. on changes the behavior of the assembler but no option changes the way another option works Some options require exactly one file name to follow them The file name may either immediately follow the option s letter or it may be the next command line argument For example to specify an output file named test o either of the following options would be acceptable o test o otest o Note Command line options are case sensitive 2009 Microchip Technology Inc DS51833A page 33 32 Bit Assembler Linker and Utilities User s Guide 3 3 COMPILATION DRIVER INTERFACE SYNTAX The compilation driver program pic32 gcc preprocesses compiles assembles and links C and assembly language modules and library archives This driver orches trates the build process so that you often don t need to know which individual programs preprocess compile assemble and link The driver calls the appropriate individual tools to complete the requested build process In practice the assembler is usually invoked via pic32 gcc which determines that it should assemble an input file by its S or s filename extension The compilation driver sends a file with a S uppercase extension through the CPP style preproces sor before it passes the file to the assembler while the driver sends a file with a s lowercase extension directly to the assembler The basic form of the compilation driver command line is pic32 gcc options files
241. or archive The linker assumes that it is a linker script G Group ended before it began help for usage The option appeared on the command line before the option Check that the group is specified correctly on the linker command line Illegal use of name section The section name is reserved For instance the special output section name DISCARD may be used to discard input sections Any input sections which are assigned to an output section named DISCARD are not included in the output file You should not create your own output section named DISCARD Includes nested too deeply The maximum include depth is 10 Invalid argument to option section start The argument to section start must be sectionname org org must be a single hexadecimal integer There should be no white space between sectionname the equals sign 2 and org Invalid assignment to location counter The assignment to the special dot symbol was invalid Invalid syntax in flags The section flags are invalid The accepted flags are za r w x 1 Macros nested too deeply The maximum macro nesting depth is 10 May not nest groups help for usage An archive group is already started Use the option to close the current group before starting another group with the option Member b in archive is not an object The archive member is not a valid object Check that the library archive is correct for the Microchip MPLAB C Compiler for PIC32 MC
242. output section 2009 Microchip Technology Inc DS51833A page 135 32 Bit Assembler Linker and Utilities User s Guide 11 4 GLOBAL AND WEAK SYMBOLS When a symbol reference appears in an object file without a corresponding definition the symbol is declared external By default external symbols have global binding and are referred to as global symbols External symbols may be explicitly declared with weak binding using the weak attribute in C or the weak directive in assembly language As the name implies global symbols are visible to all input files involved in the link There must be one and only one definition for every global symbol referenced If a global definition is not found among the input files archives will be searched and the first archive module found that contains the needed definition will be loaded If no definition is found for a global symbol a link error is reported Weak symbols share the same name space as global symbols but are handled differ ently Multiple definitions of a weak symbol are permitted If a weak definition is not found among the input files archives are not searched and a value of 0 is assumed for all references to the weak symbol A global symbol definition of the same name will take precedence over a weak definition or the lack of one In essence weak symbols are considered optional and may be replaced by global symbols or ignored entirely 11 5 STACK ALLOCATION The MPLAB
243. output section commands see Section 10 6 5 7 Output Section Data Here is a simple example SECTIONS text text 0x9090 10 6 5 14 OVERLAY DESCRIPTION An overlay description provides an easy way to describe sections which are to be loaded as part of a single memory image but are to be run at the same memory address At run time some sort of overlay manager will copy the overlaid sections in and out of the run time memory address as required perhaps by simply manipulating addressing bits Overlays are described using the OVERLAY command The OVERLAY command is used within a SECTIONS command like an output section description The full syntax of the OVERLAY command is as follows OVERLAY start NOCROSSREFS AT ldaddr secnamel output section command output section command phdr fi11 secname2 output section command output section command phdr 111 gt region phdr fill Everything is optional except OVERLAY a keyword and each section must have a name secname1 and secname2 above The section definitions within the OVERLAY construct are identical to those within the general SECTIONS construct except that no addresses and no memory regions may be defined for sections within an OVERLAY The sections are all defined with the same starting address The load addresses of the sections are arranged such that they are consecutive in memory starting at
244. potential pitfalls to using gp relative addressing You must take special care when writing assembler code to declare global i e public or external data items correctly Writable initialized data of gnum bytes or less must be put explicitly into the Sdata section e g Sdata small word 0x12345678 Global common data must be declared with the correct size e g comm small 4 comm big 100 Small external variables must also be declared correctly e g extern smallext 4 If your program has a very large number of small data items or constants the C compiler s G8 option may still try to push more than 64 KB of data into the small region the symptom will be obscure relocation errors relocation truncated when linking Fix it by disabling gp relative addressing with the compiler s Go option and or reducing the space reserved in the small data sections e sbss and sdata in your assembly code 4 3 4 Directive Arguments Each directive takes from 0 up to 3 arguments These arguments give additional information to the directive on how it should carry out the command Arguments must be separated from directives by one or more spaces or tabs Commas must separate multiple arguments More details are provided in Chapter 7 Assembler Directives on the available directives 2009 Microchip Technology Inc DS51833A page 55 32 Bit Assembler Linker and Utilities User s Guide 4 3 5 Comments Comments can
245. pplication board Template Lines of text that you build for inserting into your files at a later time The MPLAB Editor stores templates in template files Tool Bar A row or column of icons that you can click on to execute MPLAB IDE functions Trace An emulator or simulator function that logs program execution The emulator logs pro gram execution into its trace buffer which is uploaded to MPLAB IDE s trace window DS51833A page 210 2009 Microchip Technology Inc Glossary Trace Memory Trace memory contained within the emulator Trace memory is sometimes called the trace buffer Trace Macro A macro that will provide trace information from emulator data Since this is a software trace the macro must be added to code the code must be recompiled or reassembled and the target device must be programmed with this code before trace will work Trigger Output Trigger output refers to an emulator output signal that can be generated at any address or address range and is independent of the trace and breakpoint settings Any number of trigger output points can be set Trigraphs Three character sequences all starting with that are defined by ISO C as replacements for single characters Unassigned Section A section which has not been assigned to a specific target memory block in the linker command file The linker must find a target memory block in which to allocate an unassigned section Uninitialized Data
246. put Files Syntax Options Output Formats 13 3 1 Input Files Input ELF object file If no object files are listed as arguments pic32 nm assumes the file a out 13 3 2 Syntax Command line syntax is pic32 nm A o print file name a debug syms B defined only u undefined only format format format g extern only help 1 line numbers n v numeric sort omf format p no sort P portability r reverse sort s print armap size sort t radix radix radix V version OBJFILE 13 3 3 Options The long and short forms of options shown in Table 13 2 as alternatives are equivalent TABLE 13 2 pic32 nm OPTIONS Option Function A Precede each symbol by the name of the input file or archive 0 member in which it was found rather than identifying the print file name input file once only before all of its symbols a Display all symbols even debugger only symbols normally debug syms these are not listed B The same as format bsd defined only Display only defined symbols for each object file u Display only undefined symbols those external to each object undefined only file format Use the output format format which can be bsd sysv or format format posix The default is bsd Only the first character of format is
247. r MPLAB SIM simulator a particular setup for stimulus control Section A portion of an application located at a specific address of memory Section Attribute A characteristic ascribed to a section e g an access section Sequenced Breakpoints Breakpoints that occur in a sequence Sequence execution of breakpoints is bottom up the last breakpoint in the sequence occurs first Serialized Quick Turn Programming Serialization allows you to program a serial number into each microcontroller device that the Device Programmer programs This number can be used as an entry code password or ID number SFR See Special Function Registers Shell The MPASM assembler shell is a prompted input interface to the macro assembler There are two MPASM assembler shells one for the DOS version and one for the Windows version Simulator A software program that models the operation of devices Single Step This command steps through code one instruction at a time After each instruction MPLAB IDE updates register windows watch variables and status displays so you can analyze and debug instruction execution You can also single step C compiler source code but instead of executing single instructions MPLAB IDE will execute all assembly level instructions generated by the line of the high level C statement Skew The information associated with the execution of an instruction appears on the proces Sor bus at different times For example the
248. r in one byte and its value may be used in numeric expressions A string can contain potentially many bytes and their values may not be used in arithmetic expressions 4 4 2 1 CHARACTERS A single character may be written as a single quote immediately followed by that character or as a single quote immediately followed by that character and another single quote The assembler accepts the following escape characters to represent special control characters TABLE 4 1 ESCAPE CHARACTERS a Hex Escape Character Description Value Na Bell alert character 07 b Backspace character 08 f Form feed character 0C An New line character 0A Nr Carriage return character 0D NC Horizontal tab character 09 v Vertical tab character 0B Backslash 5C Question mark character 3F vi Double quote character 22 digit digit digit Octal character code The numeric code is 3 octal digits Xx hex digits Hex character code All trailing hex digits are combined Either upper or lowercase x works The value of a character constant in a numeric expression is the machine s byte wide code for that character The assembler assumes your character code is ASCII 4 4 2 2 STRINGS A string is written between double quotes It may contain double quotes or null characters The way to get special characters into a string is to escape the characters preceding them with a backslash Y character The same escape
249. r loads LUI Unlike labels that you create yourself mne monics are provided by the PIC32 MCU assembly language Mnemonics are not case sensitive See the data sheet for your target PIC32 MCU for more details on the CPU instruc tion set mnemonics available for the device The assembler also supports a number of synthesized macro instructions intended to make writing assembly code easier The LI load immediate instruction is an example of a synthetic macro instruction The assembler generates two machine instructions to load a 32 bit constant value into a register from this single synthetic instruction DS51833A page 52 O 2009 Microchip Technology Inc Assembler Syntax The assembler synthesizes instructions for A 32 bit Load Immediate A load from a memory location An extended branch conditional A two operand form of some three operand instructions e An unaligned load store instruction Assembly directives such as set noat set nomacro and set noreorder disable these normally helpful features for cases where you require full control over the generated code See Section 7 13 Directives that Control Code Generation 4 3 3 Operands Each machine instruction takes from 0 up to 4 operands See the appropriate data sheet for your target PIC32 MCU for a full list of machine instructions These operands give information to the instruction on the data that should be used and the storage loca tion for the instruct
250. r non const Relocation truncated to fit relocation type name against undefined symbol name This error can occur if the symbol does not exist For instance the code calls a function that has not been defined U Undefined MEMORY region region referenced in expression The expression referenced a MEMORY region that does not exist in the linker script C 4 WARNINGS The linker generates warnings when an assumption is made so that the linker could continue linking a flawed program Warnings should not be ignored Each warning should be specifically looked at and corrected to ensure that the linker understands what was intended Warning messages can sometimes point out bugs in your program C Cannot find entry symbol name If we can t find the specified entry symbol and it s not a number Use the first address in the text section Changing start of section name by num bytes The linker is changing the start of the indicated section due to alignment DS51833A page 182 2009 Microchip Technology Inc Linker Errors Warnings R Redeclaration of memory region name The MEMORY region has been declared more than once in the linker script U Undefined reference to name The symbol is undefined c sti 2009 Microchip Technology Inc DS51833A page 183 32 Bit Assembler Linker an
251. required Cover Texts given in the Document s license notice h Include an unaltered copy of this License i Preserve the section Entitled History Preserve its Title and add to it an item stating at least the title year new authors and publisher of the Modified Version as given on the Title Page If there is no section Entitled History in the Document create one stating the title year authors and publisher of the Document as given on its Title Page then add an item describing the Modified Version as stated in the previous sentence j Preserve the network location if any given in the Document for public access to a Transparent copy of the Document and likewise the network locations given in the Document for previous versions it was based on These may be placed in the History section You may omit a network location for a work that was published at least four years before the Document itself or if the original publisher of the version it refers to gives permission k For any section Entitled Acknowledgements or Dedications Preserve the Title of the section and preserve in the section all the substance and tone of each of the contributor acknowledgements and or dedications given therein Il Preserve all the Invariant Sections of the Document unaltered in their text and in their titles Section numbers or the equivalent are not considered part of the section titles m Delete any section Entitled Endorsements Su
252. rged with a defined or common symbol of the same name in another object file If the linker does not see a definition for the symbol just one or more common symbols then it will allocate 1ength bytes of uninitialized memory length must be an absolute expression If the linker sees multiple common symbols with the same name and they do not all have the same size it will allocate space using the largest size The comm directive takes an optional third argument If a1gn is specified it is the desired alignment of the symbol specified as a byte boundary for example an align ment of 16 means that the Least Significant 4 bits of the address should be zero The alignment must be an absolute expression and it must be a power of two If linker allo cates uninitialized memory for the common symbol it will use the alignment when plac ing the symbol If no alignment is specified the assembler will set the alignment to the largest power of two less than or equal to the size of the symbol up to a maximum of 1 extern symbol The extern directive declares a symbol name that may be used in the current mod ule but it is defined as global in a different module However all symbols are extern by default so this directive is optional global symbol globl symbol The global directive declares a symbol symbol that is defined in the current module and is available to other modules global makes the symbol visible to the linker If you
253. right to sue for relief under that Act Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates lt is your responsibility to ensure that your application meets with your specifications MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED WRITTEN OR ORAL STATUTORY OR OTHERWISE RELATED TO THE INFORMATION INCLUDING BUT NOT LIMITED TO ITS CONDITION QUALITY PERFORMANCE MERCHANTABILITY OR FITNESS FOR PURPOSE Microchip disclaims all liability arising from this information and its use Use of Microchip devices in life support and or safety applications is entirely at the buyer s risk and the buyer agrees to defend indemnify and hold harmless Microchip from any and all damages claims Suits or expenses resulting from such use No licenses are conveyed implicitly or otherwise under any Microchip intellectual property rights QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV ISO TS 16949 2002 Trademarks The Microchip name and logo the Microchip logo Accuron dsPIC KEELOQ KEELOQ logo MPLAB PIC PICmicro PICSTART rfPIC SmartShunt and UNI O are registered trademarks of Microchip Technology Incorporated in the U S A and other countries FilterLab Hampshire Linear Active Thermistor MXDEV MXLAB SEEVAL SmartSensor and The Embedded Control Solutions Company are registered trademarks of Micr
254. rithmetic logic unit ALU to complete the execution of the instruction It controls the program memory address bus the data memory address bus and accesses to the stack Clean Under the MPLAB IDE Project menu Clean removes all intermediary project files such as object hex and debug files for the active project These files are recreated from other files when a project is built COFF Common Object File Format An object file of this format contains machine code debugging and other information Command Line Interface A means of communication between a program and its user based solely on textual input and output Compiler A program that translates a source file written in a high level language into machine code Conditional Assembly Assembly language code that is included or omitted based on the assembly time value of a specified expression Conditional Compilation The act of compiling a program fragment only if a certain constant expression specified by a preprocessor directive is true Configuration Bits Special purpose bits programmed to set PIC microcontroller modes of operation A Configuration bit may or may not be preprogrammed Control Directives Directives in assembly language code that cause code to be included or omitted based on the assembly time value of a specified expression CPU See Central Processing Unit Cross Reference File A file that references a table of symbols and a list of fil
255. rmat name The OUTPUT FORMAT command names the object file format to use for the output file The format name value is always e1 32 tradlittlemips for Microchip PIC32 MCUSs TARGET format name The TARGET command names the object file format to use when reading input files It affects subsequent INPUT and GROUP commands The ormat name value should remain e1 32 tradlittlemips for Microchip PIC32 MCUs 10 7 EXPRESSIONS IN LINKER SCRIPTS The syntax for expressions in the linker script language is identical to that of C expressions All expressions are evaluated as 32 bit integers You can use and set symbol values in expressions The linker defines several special purpose built in functions for use in expressions 10 7 1 Constants All constants are integers As in C the linker considers an integer beginning with o to be octal and an integer beginning with 0x or ox to be hexadecimal The linker considers other integers to be decimal In addition you can use the suffixes K and M to scale a constant by 1024 or 1024 1024 respectively For example the following all refer to the same quantity fourk 1 4K fourk 2 4096 fourk 3 0x1000 10 7 2 Symbol Names Unless quoted symbol names start with a letter underscore or period and may include letters digits underscores periods and hyphens Unquoted symbol names must not conflict with any keywords You can specify a symbol which contains odd characters or has the sam
256. rovided for under this License Any other attempt to copy modify sublicense or distribute the Document is void and will automatically terminate your rights under this License However parties who have received copies or rights from you under this License will not have their licenses terminated so long as such parties remain in full compliance E 11 FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new revised versions of the GNU Free Documentation License from time to time Such new versions will be similar in spirit to the present version but may differ in detail to address new problems or concerns See http www gnu org copyleft Each version of the License is given a distinguishing version number If the Document specifies that a particular numbered version of this License or any later version applies to it you have the option of following the terms and conditions either of that specified version or of any later version that has been published not as a draft by the Free Software Foundation If the Document does not specify a version number of this License you may choose any version ever published not as a draft by the Free Software Foundation DS51833A page 192 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Glossary Absolute Section A section with a fixed absolute address that cannot be changed by the linker Access Memor
257. s Executable Code Software that is ready to be loaded for execution Export Send data out of the MPLAB IDE in a standardized format 2009 Microchip Technology Inc DS51833A page 197 MPLAB Assembler Linker and Utilities for PIC32 Expressions Combinations of constants and or symbols separated by arithmetic or logical operators Extended Microcontroller Mode In Extended Microcontroller mode on chip program memory as well as external mem ory is available Execution automatically switches to external if the program memory address is greater than the internal memory space of the PIC18 device Extended Mode In Extended mode the compiler will utilize the extended instructions i e ADDFSR ADDULNK CALLW MOVSF MOVSS PUSHL SUBFSR and SUBULNK and the indexed with literal offset addressing External Label A label that has external linkage External Linkage A function or variable has external linkage if it can be referenced from outside the module in which it is defined External Symbol A symbol for an identifier which has external linkage This may be a reference or a definition External Symbol Resolution A process performed by the linker in which external symbol definitions from all input modules are collected in an attempt to resolve all external symbol references Any external symbol references which do not have a corresponding definition cause a linker error to be reported External Input Line A
258. s a tutorial for creating projects Topics covered in this chapter are Project Overview Creating a Project Adding a Source File to Your Project Building Your Project Debugging Your Project 2 2 PROJECT OVERVIEW Projects are groups of files associated with language tools such as MPLAB Assembler for PIC32 MCUs in the MPLAB IDE A project consists of source files header files object files library files and a linker script Every project should have one or more source files Typically at least one header file is required to identify the register names of the target microcontroller Header files are typically included by source files and are not explicitly added to the project A project may either use an implicit default linker script included with the language tools or an explicit application specific linker script created by the developer The project s output files consist of executable code to be loaded into the target micro controller as firmware Debugging files are generated to help MPLAB IDE correlate the symbols and function names from the source files with the executable code and memory used for variable storage Most examples and applications in this chapter consist of a project with only one source file and the implicit default linker script 2009 Microchip Technology Inc DS51833A page 25 32 Bit Assembler Linker and Utilities User s Guide 2 3 CREATING A PROJECT 1 Select Project gt Project
259. s either absolute or relative to some section A relative expression is expressed as a fixed offset from the base of a section The position of the expression within the linker script determines whether it is absolute or relative An expression which appears within an output section definition is relative to the base of the output section An expression which appears elsewhere will be absolute A symbol set to a relative expression will be relocatable if you request relocatable output using the r option That means that a further link operation may change the value of the symbol The symbol s section will be the section of the relative expression 2009 Microchip Technology Inc DS51833A page 129 32 Bit Assembler Linker and Utilities User s Guide A symbol set to an absolute expression will retain the same value through any further link operation The symbol will be absolute and will not have any particular associated section You can use the built in function ABSOLUTE to force an expression to be absolute when it would otherwise be relative For example to create an absolute symbol set to the address of the end of the output section data SECTIONS If ABSOLUTE were not used edata would be relative to the data section data data edata ABSOLUTE 10 7 7 Built in Functions The linker script language includes a number of built in functions for use in linker script expressions 10 7 7 1 ABS
260. s multilib permutation based on mips16 or mno mips16 ISA mode Example pic32 gcc foo o 03 mips16 o project elf 9 6 3 Software floating point versus no floating point support The no float library permutations typically have significantly less overhead than the floating point library permutations If your application does not require floating point support use this option mno float Selects the multilib target library permutation that does not support software floating point operations Example pic32 gcc foo o Os mmo mips16 mno float o project elf msoft float Selects the multilib target library permutation with full software floating point support 9 7 OPTIONS THAT CONTROL INFORMATIONAL OUTPUT Information output options are check sections no check sections help no warn mismatch report mem trace t trace symbol symbol y symbol e V e verbose e version v warn common e warn once e warn section align 9 7 1 check sections Check section addresses for overlaps This is the default Normally the linker will perform this check and it will produce a suitable error message if it finds an overlap 2009 Microchip Technology Inc DS51833A page 107 32 Bit Assembler Linker and Utilities User s Guide 9 7 2 no check sections Do not check section addresses for overlaps 9 7 3 help Print option help Print a summary of the command line
261. s seen without a preceding if directive err encountered User error invoked with the err directive lfeqs syntax error Two comma separated double quoted strings were not passed as arguments to the ifeqs directive Set pop with no set push Attempting to pop options off of an empty option stack Use set push before set pop Size expression too complicated to fix up The size expression can be constant or use label subtraction DS51833A page 168 2009 Microchip Technology Inc Assembler Errors Warnings Messages A A bignum with underscores may not have more than 8 hex digits in any word A bignum constant must not have more than 8 hex digits in a single word A bignum with underscores must have exactly 4 words A bignum constant using the underscore notation must have exactly four 8 hexdigit parts Absolute sections are not supported This assembler does not support the absolute section command Alignment not a power of 2 The alignment value must be a power of 2 Modify the alignment to be a power of 2 Alignment too large 15 Assumed An alignment greater than 15 was requested The assembler automatically continues with a alignment value of 15 Arg static registers overlap A MIPS16 mode save restore uses overlapping registers for args and statics Argument must be a string The argument to a error or warning directive must be a double quoted string Attempt to allocate data in common sectio
262. s width2 option is used to set the width of the continuation lines of the output data column of the listing file By default this is set to 1 If the specified width is smaller than the first line this option is ignored The following lines are extracted from a listing The output data column is in bold 2 0000 54686973 ascii This is an example 2 20697320 2 616E2065 2 78616D70 2 6C650000 If the option 1isting lhs width2 3 is used then the same line will appear as follows in the listing 2 0000 54686973 ascii This is an example 2 20697320 616E2065 78616D70 2 6C650000 3 4 4 listing rhs width num The listing rhs width option is used to set the maximum width in characters of the lines from the source file By default this is set to 100 The following lines are extracted from a listing that was created without using the listing rhs width option The text in bold are the lines from the source file 2 0000 54686973 ascii This line is long 2 206C696E 2 65206973 2 206C6F6E 2 67000000 If the option 1isting rhs width 22 is used then the same line will appear as follows in the listing 2 0000 54686973 ascii This line is 2 206C696E 2 65206973 2 206C6F6E 2 67000000 The line is truncated not wrapped in the listing but the data is still there 2009 Microchip Technology Inc DS51833A page 45 32 Bit Assembler Linker and Utilities User s Guide 3 4 5 listing cont lines num The 1isting
263. see 151 pic32 ranlib utility eeeene 153 pic32 size utility eese 154 pic32 strings ut 155 pic32 strip utility oi ss 156 ic eceeeegecne tuees cathe rniret 62 128 Prefix Operators iue cete peint aus 62 Preprocessor Jntemmal 51 e US Te DEE 110 Process Flow Assembler hg ii ca es 17 Librarian iio eee te ts 142 Ein Ker si Eu Me eS 91 Processing Linker sss 133 lge 9 PROVIDE iret tet erede EE 117 R SG 103 ranlib utility c ertet cerne 153 Read Write Section sssssseess 117 Reading Recommended ccceeeeeeeceeeeeeseeeeees 4 Read Only Section sssssssssss 117 relocatable 5 een aeter mondi euet 21 relocateable EH 103 SFEPOM MOM oy doce ee npo petite ndis 108 Resolving Symbol 134 retain symbols file eese 103 Run time Initialization Options Linker defsyms min heap size 106 defsymz min stack size 106 S EE 104 BS eege i csi E E ooh AD dece 104 prinio ES 104 Scripts Librarlaris ue pee ede RR 145 Scripts Archiver Librarian ADDL Barcis RI eg b 145 ADDMOBD 5 iste eii ais 145 CLEAR zu nth 145 CREATE Ionen rd 145 146 RSR EAR GE 146 DIRECTORY a itt ete 146 ENDS s emendet rte ett dee eee 146 EXTRACT eerste ia 146 BCEE 146 OPEN A oett 145 146 2009 Microchip Technology Inc DS51
264. segment kseg0 boot mem vector n Interrupt Vector n Executable boot code segment ksegO boot mem rodata Strings and C data declared Read only data segment kseg0 program mem const rodata Constant data when compiled with Read only data segment kseg0 program mem fdata sections are output to uniquely named sections of this form data Variables gt n bytes compiled Gn Initialized data segment ksegl data mem with an initial value Values copied kseg0 program mem from program memory to data memory at C start up data Large initialized variables com Initialized data segment ksegl data mem amp piled with data sections ksegO0 program mem ramfunc RAM functions copied from pro Initialized data segment ksegl data mem gram memory to data memory at C start up ksegO0 program mem 2009 Microchip Technology Inc DS51833A page 69 32 Bit Assembler Linker and Utilities User s Guide TABLE 7 1 RESERVED SECTIONS DETAILS CONTINUED Default Linker Script Section Name Generated by Final Location MEMORY Region lit4 Constants usually floating point Small initialized data segment ksegl data mem lit8 which the assembler decides to ksegO0 program mem store in memory rather than in the instruction stream Used for gp relative addressing Sdata Variables zn bytes compiled Small initialized data segment ksegl data mem Gn w
265. sembler executable pic32 as exe under Location If it does not enter or browse to the executable location which is by default C Program Files Microchip MPLAB C32 bin pic32 as exe or C Program Files Microchip MPLAB C32 Suite bin pic32 as exe MPLAB C32 C Compiler should point to the compiler executable pic32 gcc exe under Location If it does not enter or browse to the executable location which is by default C Program Files Microchip MPLAB C32 bin pic32 gcc exe or C Program Files Microchip MPLAB C32 Suite bin pic32 gcc exe MPLAB LINK32 Object Linker should point to the linker executable pic32 1d exe under Location If it does not enter or browse to the executable location which is by default C Program Files Microchip MPLAB C32 bin pic32 ld exe or C Program Files Microchip MPLAB C32 Suite bin pic32 ld exe MPLAB LIB32 Object Librarian Archiver should point to the library executable pic32 ar exe under Location If it does not enter or browse to the executable location which is by default C Program Files Microchip MPLAB C32 bin pic32 ar exe or C Program Files Microchip MPLAB C32 bin pic32 ar exe Click Next to continue 2009 Microchip Technology Inc DS51833A page 27 32 Bit Assembler Linker and Utilities User s Guide 4 At Step Three Create a new project or reconfigure the active project select to create a new project file and use Browse to select the folder where the project
266. sequences that apply to strings also apply to characters DS51833A page 58 2009 Microchip Technology Inc Assembler Syntax 4 55 SUMMARY Table 4 2 summarizes the general syntax rules that apply to the assembler TABLE 4 2 SYNTAX RULES Character Character Description Syntax Usage period begins a directive number hash begin single line comment slash asterisk begin multiple line comment asterisk slash end multiple line comment colon end a label definition none required begin a literal value or character in single quotes specifies single character value string character string in double quotes specifies a character string 2009 Microchip Technology Inc DS51833A page 59 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 60 O 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 5 Assembler Expression Syntax and Operation 5 1 INTRODUCTION Expression syntax and operation for MPLAB Assembler for PIC32 MCUs is discussed here Topics covered in this chapter are Expressions Operators 5 2 EXPRESSIONS An expression specifies an address or numeric value White space may precede and or follow an expression The result of an expression must be an absolute number or else an offset into a particular section If an expression is not absolute and there is no
267. ses you may want to move the Interrupt Vector Table IVT from the default location in the Boot ROM kseg1 to the Application Flash ksegO To relocate the IVT two lines must change in the device specific portion of the linker script procdefs 1d Note Consider creating a new custom linker script based on the default linker script as described in Section 10 5 Adding a Custom Linker Script to an MPLAB IDE Project A new linker script is often preferable over mod ifying the existing procdefs 1d file because the changes become specific to your project and will not get overwritten when you upgrade to a later tool version First the location of ebase must be changed to point to the area in Application Flash Here are the lines that specify the default ebase from the procdefs 1d for the PIC32MX360F512L PROVIDE vector spacing 0x00000001 ebase address 0x9FC01000 To place the IVT at the highest possible address set ebase address 0x9D080000 64 vector spacing lt lt 5 OxFFFFF000 where 0x9D080000 is the highest address in the PIC32MX360F512L MCU 64 is the number of interrupt vectors and vector spacing 5 converts the vector spacing value to the actual number of bytes allocated on the PIC32 MCU The bit mask at the end oxFFFFF000 aligns ebase address on a 4K address boundary as required We can simplify the expression to ebase address 0x9D080000 vector spacing lt lt 11 OxFF
268. significant it can be either upper or lowercase g Display only external symbols extern only help Show a summary of the options to pic32 nm and exit 1 For each symbol use debugging information to try to find a line numbers filename and line number For a defined symbol look for the line number of the address of the symbol For an undefined symbol look for the line number of a relocation entry that refers to the symbol If line number information can be found print it after the other symbol information 2009 Microchip Technology Inc DS51833A page 149 32 Bit Assembler Linker and Utilities User s Guide TABLE 13 2 pic32 nm OPTIONS CONTINUED Option Function n vV numeric sort Sort symbols numerically by their addresses rather than alphabetically by their names reverse sort p Do not bother to sort the symbols in any order print them in no sort the order encountered P Use the POSIX 2 standard output format instead of the default portability format Equivalent to f posix r Reverse the order of the sort whether numeric or alphabetic let the last come first s print armap When listing symbols from archive members include the index a mapping stored in the archive by pic32 ar or pic32 ranlib of which modules contain definitions for which names gize sort Sort symbols by size The size is computed as the difference between the val
269. ssociated symbol is not defined Make sure that the end directive is placed appropriately after the ent direc tive end directive without a preceding ent directive The end function debugging info directive does not have an associated ent directive to mark the symbol as a function Make sure that the end directive is positioned appropriately after a ent directive end not in text section The end function debugging info directive must be in a section with executable code end symbol does not match ent symbol The end function debugging info directive s function argument does not match the preceding ent directive s function argument Make sure that the end directive is positioned appropriately after its corresponding ent directive endr encountered without preceeding rept irc or irp The endr directive ends a rept irc or irp sequence however this endr directive does not have a preceeding rept irc or irp directive Make sure that the endr directive is positioned correctly in your code ent or aent not in text section The ent function debugging info directive must be in a section containing executable code fail expr encountered If the value of the your fail expression is 500 or more the assembler will print a warning message The message will include the value of expression fill size clamped to 8 The i11 size value may be zero or more but if it is more than 8 then it is
270. ssued if appropriate This is the default behavior 3 5 4 J No warnings are issued about signed overflow 3 5 5 help The assembler will show a message regarding the command line usage and options The assembler then exits 3 5 6 target help The assembler will show a message regarding the PIC32 target specific command line options The assembler then exits 3 5 7 version The assembler version number is displayed The assembler then exits DS51833A page 46 O 2009 Microchip Technology Inc Assembler Command Line Interface 3 5 8 verbose v The assembler version number is displayed The assembler does not exit If this is the only command line option used then the assembler will print out the version and wait for entry of the assembly source through standard input Use lt CTRL gt D to send an EOF character to end assembly 3 6 OPTIONS THAT CONTROL OUTPUT FILE CREATION The options in this section control how the output file is created For example to change the name of the output object file use o Any item in parenthesis shows the short method of specifying the option e g keep locals may be specified as L also 3 6 1 g Generate symbolic debugging information 3 6 2 keep locals L Keep local symbols i e labels beginning with L uppercase only Normally you do not see such labels when debugging because they are intended for the use of programs like compilers that compose asse
271. st be present as the RELPOS argument before the ARCHIVE specification Add new files before an existing member of the archive If you use the modifier b the name of an existing archive member must be present as the RELPOS argument before the ARCHIVE specification Same as i Create the archive The specified ARCHIVE is always created if it did not exist when you requested an update But a warning is issued unless you specify in advance that you expect to create it by using this modifier Truncate names in the archive The 32 bit archiver librarian will normally permit file names of any length This will cause it to create archives that are not compat ible with the native archiver program on some systems If this is a concern the modifier may be used to truncate file names when putting them in the archive Insert new files before an existing member of the archive If you use the modifier i the name of an existing archive member must be present as the RELPOS argument before the ARCHIVE specification Same as b This modifier is accepted but not used Uses the COUNT parameter This is used if there are multiple entries in the archive with the same name Extract or delete instance COUNT of the given name from the archive Preserve the original dates of members when extracting them If you do not specify this modifier files extracted from the archive are stamped with the time of extraction Use the
272. t enough information when the assembler sees the expression to know its section the assembler terminates with an error message in this situation 5 2 1 Empty Expressions An empty expression has no value itis just white space or null Wherever an absolute expression is required you may omit the expression and the assembler assumes a value of absolute 0 5 2 2 Integer Expressions An integer expression is one or more arguments delimited by operators Arguments are symbols numbers or sub expressions Sub expressions are a left parenthesis followed by an integer expression followed by a right parenthesis or a prefix operator followed by an argument Integer expressions involving symbols in program memory are evaluated in Program Counter PC units In MIPS32 mode the Program Counter increments by 4 for each instruction word For example to branch to the next instruction after label L specify L 4 as the destination Example b L 4 2009 Microchip Technology Inc DS51833A page 61 32 Bit Assembler Linker and Utilities User s Guide 5 3 OPERATORS Operators are arithmetic functions like or Prefix operators are followed by an argument Infix operators appear between their arguments Operators may be preceded and or followed by white space Prefix operators have higher precedence than infix operators Infix operators have an order of precedence dependent on their type 5 3 1 Prefix Operators The asse
273. t Language Toolsuite Set Language Tool Locations Version Control FIGURE A 2 BUILD OPTIONS DIALOG PIC32 SUITE TAB MPLAB PIC32 Assembler MPLAB PIC32 C Compiler MPLAB PIC32 Linker Directories Custom Buld Trace PIC32 Suite Categories General y M Generate Command Line M Target Type Build normal target invoke PIC32 linker y 1 E OG library target invoke PIC32 archiver Restore Defaults Frnostartfles Now when you build your project the compilation driver pic32 gcc will exclude the default startup code object from the link It will use the customized code that is in your project tree instead Building on the Command Line Interface Once you ve made the customizations to the startup code source file add it to the pic32 gcc command line like you would any other source file However when calling pic32 gcc for the link add the nostartfiles option The compilation driver will not pass the default startup code object to the linker DS51833A page 164 2009 Microchip Technology Inc Frequently Asked Questions A 2 4 How can reduce the C library overhead Select Optimized Libraries By default the linker selects the unoptimized software floating point no mips16 mul tilib permutation of the C libraries This safe but expensive default permutation may not be ideal for your application The MPLAB IDE project manager allows you to easily select
274. t caught in an infinite loop where there will be no exit from the recursion Reentrant A function that may have multiple simultaneously active instances This may happen due to either direct or indirect recursion or through execution during interrupt processing Relaxation The process of converting an instruction to an identical but smaller instruction This is useful for saving on code size MPLAB ASM30 currently knows how to RELAX a CALL instruction into an RCALL instruction This is done when the symbol that is being called is within 32k instruction words from the current instruction Relocatable An object whose address has not been assigned to a fixed location in memory 2009 Microchip Technology Inc DS51833A page 207 MPLAB Assembler Linker and Utilities for PIC32 Relocatable Section ALUSO A section whose address is not fixed absolute The linker assigns addresses to relocatable sections through a process called relocation Relocation A process performed by the linker in which absolute addresses are assigned to relo catable sections and all symbols in the relocatable sections are updated to their new addresses ROM Read Only Memory Program Memory Memory that cannot be modified Run The command that releases the emulator from Halt allowing it to run the application code and change or respond to I O in real time Run time Model Describes the use of target architecture resources Scenario Fo
275. t is specified on the command line the linker will use an internal version known as the built in default linker script The default linker script has section mapping that is appropriate for all PIC32 MCUs It uses an INCLUDE directive to include the device specific memory regions The default linker script is appropriate for most PIC32 MCU applications Only applica tions with specific memory allocation needs will require an application specific linker script The default linker script can be examined by invoking the linker with the verbose option pic32 1d verbose 2009 Microchip Technology Inc DS51833A page 111 32 Bit Assembler Linker and Utilities User s Guide TABLE 10 1 In a normal toolsuite installation a copy of the default linker script is located at pic32mx lib ldscripts elf32pic32mx x Note that this file is only a copy of the default linker script The script that the linker uses is internal to the linker The device specific portion of the linker script is located in pic32mx lib proc device procdefs 1d where device is the device value specified to the mprocessor compilation driver pic32 gcc option Note The MPLAB C Compiler for PIC32 MCUs User s Guide DS51686 exam ines the contents of the default linker script in detail The discussion applies to both assembly code and C code projects The default linker script maps each standard input section to one or more specific MEMORY regions In turn
276. table arguments and options d Using one of these options you can control whether the size 0 of each section is given in decimal d or radix 10 octal X o or radix 8 or hexadecimal x or radix 16 In radix number radix number only the three values 8 10 16 are sup ported The total size is always given in two radices decimal and hexadecimal for d or x output or octal and hexadecimal if you re using o t Show totals of all objects listed Berkeley format listing mode totals only V Display the version number of pic32 size version DS51833A page 154 2009 Microchip Technology Inc Other PIC32 MCU Binary Utilities 13 6 4 Example Here is an example of the Berkeley default format of output from size pic32 size format Berkeley ranlib size text data bss dec hex filename 294880 81920 11592 388392 5ed28 ranlib 294880 81920 11888 388688 5ee50 size This is the same data but displayed closer to System V conventions pic32 size format SysV ranlib size ranlib section size addr text 294880 8192 data 81920 303104 bss 11592 385024 Total 388392 size section size addr text 294880 8192 data 81920 303104 bss 11888 385024 Total 388688 13 7 pic32 strings UTILITY For each file given the pic32 strings utility prints the printable character sequences that are at least 4 characters long or the number given in the options and are followed by an unpri
277. tarts with a non zero digit followed by zero or more decimal digits 0123456789 A hexadecimal integer is Ox or OX followed by one or more hexadecimal digits 0123456789abcdefABCDEF To denote a negative integer use the prefix operator 4 4 1 2 FLOATING POINT NUMBERS A floating point number is represented in IEEE 754 format A floating point number is written by writing in order An optional prefix which consists of the digit 0 followed by the letter e f or d in upper or lowercase Because floating point constants are used only with float and double directives the precision of the binary representation is independent of the prefix An optional sign either or An optional integer part zero or more decimal digits An optional fractional part followed by zero or more decimal digits An optional exponent consisting of An E or e Optional sign either or One or more decimal digits At least one of the integer part or fractional part must be present The floating point number has the usual base 10 value Floating point numbers are computed independently of any floating point hardware in the computer running the assembler 2009 Microchip Technology Inc DS51833A page 57 32 Bit Assembler Linker and Utilities User s Guide 4 4 2 Character Constants There are two kinds of character constants A character stands for one characte
278. than an integer The assembler per forms expression evaluation on only integers so it assumes integer 0 for this operand Line numbers must be positive line number 96d rejected This directive accepts only positive integers for the line number Missing close quote assumed The single character quote is not properly closed Missing operand zero assumed An operand probably the right size operand is missing in the expression The assem bler assumes integer 0 and continues O Operand overflow The constant expression used as in the basereg offset operand accepts only 32 bit signed constants 2009 Microchip Technology Inc DS51833A page 177 32 Bit Assembler Linker and Utilities User s Guide R Repeat 0 fill ignored The repeat argument to the 111 directive must be non negative Right operand is a bignum integer 0 assumed The right operand in the expression is a bignum rather than an integer The assembler performs expression evaluation on only integers so it assumes integer 0 for this oper and Right operand is a float integer 0 assumed The right operand in the expression is a float rather than an integer The assembler per forms expression evaluation on only integers so it assumes integer 0 for this operand S Setting incorrect section attributes for name When setting section attributes on a special section the section s attributes should match those of the predefined type The assemb
279. tion Function d Delete modules from the archive Specify the names of modules to be deleted as MEMBER the archive is untouched if you specify no files to delete If you specify the v modifier the 32 bit archiver librarian lists each module as it is deleted m Use this operation to move members in an archive The ordering of members in an archive can make a difference in how programs are linked using the library if a symbol is defined in more than one member If no modifiers are used with m any members you name in the MEMBER arguments are moved to the end of the archive you can use the a b or i modifiers to move them to a specified place instead p Print the specified members of the archive to the standard output file If the v modifier is specified show the member name before copying its contents to standard output If you specify no MEMBER arguments all the files in the archive are printed q Append the files MEMBER into ARCHIVE r Insert the files MEMBER into ARCHIVE with replacement If one of the files named in MEMBER does not exist the archiver displays an error message and leaves undisturbed any existing members of the archive matching that name By default new members are added at the end of the file but you may use one of the modifiers a b or i to request placement relative to some existing member The modifier v used with this operation elicits a line of output for each fi
280. tion argument must not contain white space 3 8 3 Dmacro defn Define macro macro as defn All instances of D on the command line are processed before any U options 3 8 4 Dmacro Define macro macro as 1 All instances of D on the command line are processed before any U options 3 8 5 Umacro Undefine macro macro U options are evaluated after all D options but before any include and imacros options 3 8 6 I dir Add the directory dir to the head of the list of directories to be searched for include preprocessor header files This can be used to override a system header file substitut ing your own version since these directories are searched before the system header file directories If you use more than one 1 option the directories are scanned in left to right order The standard system directories come after DS51833A page 48 O 2009 Microchip Technology Inc Assembler Command Line Interface When passed to the compilation driver this option affects the search path used by the preprocessor s include directive To affect the search path used by the assembler s include directive pass the corresponding option to the assembler using the wa option 3 8 7 save temps Don t delete intermediate files Place them in the current directory and name them based on the source file Thus compiling oo c with c save temps would produce the following files foo i preprocessed file foo s assembly lan
281. tives version string This directive creates a note section and places into it an ELF formatted note of type NT VERSION The note s name is set to string version is supported when the output file format is ELF otherwise it is ignored warning string Similar to the directive error but emits a warning 7 12 DIRECTIVES FOR DEBUG INFORMATION Debug information directives are ent function end file fileno filename fmask mask offset frame framereg frameoffset retreg loc fileno lineno columnno mask mask offset Size name expression sleb128 expr exprjl type name description e uleb128 exprl exprn ent function This directive marks the funct ion symbol as a function similarly to the generic type directive end End program file fileno filename When emitting dwarf2 line number information ile assigns filenames to the debug line file name table The i1eno operand should be a unique positive inte ger to use as the index of the entry in the table The filename operand is a C string literal The detail of filename indices is exposed to the user because the filename table is shared with the debug info section of the dwarf2 debugging information and thus the user must know the exact indices that table entries will have fmask mask offset Not used for current PIC32 MCUs Maintain mask 0x00000000 and offset 0 O 2009 Micr
282. tives Listing directives are those directives that control the assembler listing file format They allow the specification of titles pagination and other listing control Listing File A listing file is an ASCII text file that shows the machine code generated for each C source statement assembly instruction assembler directive or macro encountered in a source file Little Endian A data ordering scheme for multibyte data whereby the Least Significant Byte is stored at the lower addresses Local Label A local label is one that is defined inside a macro with the LOCAL directive These labels are particular to a given instance of a macro s instantiation In other words the symbols and labels that are declared as local are no longer accessible after the ENDM macro is encountered Logic Probes Up to 14 logic probes can be connected to some Microchip emulators The logic probes provide external trace inputs trigger output signal 5V and a common ground Loop Back Test Board Used to test the functionality of the MPLAB REAL ICE in circuit emulator LVDS Low Voltage Differential Signaling A low noise low power low amplitude method for high speed gigabits per second data transmission over copper wire LVDS differs from normal input output UO in a few ways Normal digital UO works with 5 volts as a high binary 1 and 0 volts as a low binary 0 When you use a differential you add a third option 5 volts which
283. to describe which memory regions may be used by the linker and which memory regions it must avoid Sections may then be assigned to particular memory regions The linker will set section addresses based on the memory regions and will warn about regions that become too full The linker will not shuffle sections around to fit into the available regions The syntax of the MEMORY command is MEMORY name attr ORIGIN origin LENGTH len The name is a name used in the linker script to refer to the region The region name has no meaning outside of the linker script Region names are stored in a separate name space and will not conflict with symbol names file names or section names Each memory region must have a distinct name The attr string must consist only of the following characters Read only section Read write section Executable section Allocatable section Initialized section PHP x om DW Same as I Invert the sense of any of the following attributes 2009 Microchip Technology Inc DS51833A page 117 32 Bit Assembler Linker and Utilities User s Guide If an unmapped section matches any of the listed attributes other than it will be placed in the memory region The attribute reverses this test so that an unmapped section will be placed in the memory region only if it does not match any of the listed attributes The origin is an expression for the start address of the memory region The express
284. ue of the symbol and the value of the symbol with the next higher value The size of the symbol is printed rather than the value t radix radix radix Use radix as the radix for printing the symbol values It must be d for decimal o for octal or x for hexadecimal V version Show the version number of pic32 nm and exit 13 3 4 Output Formats The symbol value is in the radix selected by the options or hexadecimal by default If the symbol type is lowercase the symbol is local if uppercase the symbol is global external Table 13 3 shows the symbol types TABLE 13 3 SYMBOL TYPES Symbol Description A The symbol s value is absolute and will not be changed by further linking B The symbol is in the uninitialized data section known as BSS C The symbol is common Common symbols are uninitialized data When linking multiple common symbols may appear with the same name If the symbol is defined anywhere the common symbols are treated as undefined references The symbol is in the initialized data section The symbol is a debugging symbol The symbol is in a read only data section The symbol is in the text code section The symbol is undefined lt C A DI Z UO The symbol is a weak object When a weak defined symbol is linked with a normal defined symbol the normal defined symbol is used with no error When a weak undefined symbol is linked and t
285. ui k0 1 7 0004 02001A3C lui k0 2 8 0008 03001A3C lui k0 3 9 eject 10 000c 04001A3C lui k0 4 11 0010 05001A3C lui k0 5 O 2009 Microchip Technology Inc DS51833A page 43 32 Bit Assembler Linker and Utilities User s Guide 3 4 1 7 as as requests a symbol table listing Example 3 10 shows a listing that was generated using the as command line option Note that both defined and undefined symbols are listed EXAMPLE 3 10 LISTING FILE GENERATED WITH as COMMAND LINE OPTION GAS LISTING example s page 1 DEFINED SYMBOLS ABS 00000000 srclexample c example s 18 text 00000000 main COM 00000004 testval UNDEFINED SYMBOLS bar 34 18 a file file defines the name of the output file This file must be in the current directory DS51833A page 44 2009 Microchip Technology Inc Assembler Command Line Interface 3 4 2 listing lhs width num The listing lhs width option is used to set the width of the output data column of the listing file By default this is set to 1 word The following line is extracted from a listing The output data column is in bold text 2 0000 54686973 ascii This is an example 2 20697320 2 616E2065 2 78616D70 2 6C650000 If the option listing lhs width 2 is used then the same line will appear as follows in the listing 2 0000 54686973 20697320 ascii This is an example 2 616E2065 78616D70 2 6C650000 3 4 3 listing lhs width2 num The listing 1h
286. ui expression not in range 0 65535 The Load Upper Immediate expression should be within the 16 bit range N New line in title The title heading string should be enclosed in double quotes No such section The section name specified in a global directive does not exist e g global foo myscn Non constant expression in elseif statement The elseif statement requires a constant expr expression The argument of the elseif directive must be a constant value able to be resolved on the first pass of the directive Ensure that any equ of a symbol used in this argument is located before the directive See Section 7 8 Directives that Control Conditional Assembly for more details Non constant expression in if statement The if statement requires a constant expr expression The argument of the if directive must be a constant value able to be resolved on the first pass of the directive Ensure that any equ of a symbol used in this argument is located before the directive See Section 7 8 Directives that Control Conditional Assembly for more details Noreorder must be set before nomacro Set noreorder before setting nomacro Number 0x Ix larger than 32 bits Loading a value greater than 32 bits wide into a register Number larger than 64 bits DS51833A page 172 2009 Microchip Technology Inc Assembler Errors Warnings Messages Loading a value greater than 64 bits wide into HI LO registers O
287. unctions or indirectly by using a standard C library function that uses one of these functions then a heap must be created A heap is created by spec ifying its size on the linker command line using the de sym min heap size linker command line option An example of allocating a heap of 512 bytes using the command line is pic32 gcc foo c Wl defsym min heap size 512 The linker allocates the heap immediately before the stack 11 7 INTERRUPT VECTOR TABLES The vector address of a given interrupt is calculated using Exception Base EBASE lt 31 12 gt register which provides a 4 KB page aligned base address value located in the kernel segment kseg address space EBASE is a CPU register The address is calculated by using EBASE and VS INTCTL lt 9 5 gt values The VS bits provide the vector spacing between adjacent vector addresses The linker script creates the corresponding Interrupt Vector Table as follows PROVIDE vector spacing 0x00000001 _ebase_ address 0x9FCO1000 SECTIONS app excpt GEN EXCPT ADDR KEEP gen handler gt exception mem vector 0 ebase address 0x200 KEEP vector_0 O 2009 Microchip Technology Inc DS51833A page 137 32 Bit Assembler Linker and Utilities User s Guide gt exception mem ASSERT vector spacing 0 SIZEOF vector 0 vector spacing 5 function at exception vector 0 too large vector 1 ebase address 0x200
288. unter invalid outside of SECTION An assignment to the special dot symbol can be done only during allocation within a SECTION Check the location of the assignment statement in the linker script Bad unresolved symbols option option The unresolved symbols method option was invalid Note that this option is unsupported Try the default unresolved symbols report all instead C Can not PROVIDE assignment to location counter An assignment to the special dot symbol can be done only during allocation A PROVIDE command cannot use an assignment to the location counter Remove the erroneous statement from the linker script Can not set architecture arch name If you re using a custom linker script check that the OUTPUT ARCH pic32mx com mand appears in the linker script The PIC32 MCU linker currently supports only the pic32mx arch Cannot move location counter backwards from addr1 to addr2 The next dot symbol value must be greater than the current dot symbol value DS51833A page 180 O 2009 Microchip Technology Inc Linker Errors Warnings D Dangerous relocation relocation type A symbol was resolved but the usage is dangerous This can occur for example when the code uses GP relative addressing butthe _ gp initialization symbol was not defined The gp symbol is normally defined in the linker script F File format not recognized treating as linker script One of the input files was not a recognized ELF object
289. unused sections in a custom linker script since unused sections will not impact application memory usage If a section must be removed for a custom script C style comments can be used to disable it 2009 Microchip Technology Inc DS51833A page 113 32 Bit Assembler Linker and Utilities User s Guide 10 6 LINKER SCRIPT COMMAND LANGUAGE Linker scripts are text files that contain a series of commands Each command is either a keyword possibly followed by arguments or an assignment to a symbol Multiple commands may be separated using semicolons White space is generally ignored Strings such as file or format names can normally be entered directly If the file name contains a character such as a comma which would otherwise serve to separate file names the file name may be specified in double quotes There is no way to use a double quote character in a file name Comments may be included just as in C delimited by and As in C comments are syntactically equivalent to white space 10 6 14 Basic Linker Script Concepts The linker combines input files into a single output file The output file and each input file are in a special data format known as an ELF object file format Each file is called an object file Each object file has among other things a list of sections A section in an input file is called an input section similarly a section in the output file is an output section Each section in an object file has a
290. value Specifying address for a section will change the value of the location counter 10 6 5 7 OUTPUT SECTION DATA Explicit bytes of data may be inserted into an output section by using BYTE SHORT LONG or QUAD as an output section command Each keyword is followed by an expression in parentheses providing the value to store The value of the expression is stored at the current value of the location counter The BYTE SHORT LONG and QUAD commands store one two four and eight bytes respectively For example this command will store the four byte value of the symbol addr LONG addr After storing the bytes the location counter is incremented by the number of bytes stored When using data commands in a program memory section it is important to note that the linker considers program memory to be 32 bits wide even though only 24 bits are physically implemented Therefore the Most Significant 8 bits of a LoNG data value are not loaded into device memory Data commands only work inside a section description and not between them so the following will produce an error from the linker SECTIONS text text LONG 1 data data whereas this will work SECTIONS text text LONG 1 data data nit DS51833A page 122 O 2009 Microchip Technology Inc Linker Scripts The FILL command may be used to set the fill pattern
291. vector spacing lt lt 5 1 KEEP vector_1 gt exception mem ASSERT vector spacing 0 SIZEOF vector 1 lt vector spacing 5 function at exception vector 1 too large vector 2 ebase address 0x200 vector spacing 5 2 KEEP vector_2 gt exception mem E SE vector 63 ebase address 0x200 KEEP vector_63 gt exception mem ASSERT vector spacing 0 SIZEOF vector 63 lt vector spacing 5 function at exception vector 63 too large vector spacing 5 63 Each vector in the table is created as an output section located at an absolute address based on values ofthe ebase address and vector spacing symbols There is one output section for each of the 64 vectors in the table I t DS51833A page 138 O 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Part 3 Binary Utilities for PIC32 MCUs Chapter 12 MPLAB Object Archiver Librarian for PIC32 MCUs Chapter 13 Other PIC32 MCU Binary Utilities 2009 Microchip Technology Inc DS51833A page 139 32 Bit Assembler Linker and Utilities User s Guide NOTES DS51833A page 140 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 12 MPLAB Object Archiver Librarian for PIC32 MCUs 12 1 INTR
292. x undefined 96s 96s Internal bad mips opcode mask error s 96s Internal bad mips opcode unknown extension operand type c s 96s Internal bad mips opcode unknown operand type c s s 2009 Microchip Technology Inc DS51833A page 167 32 Bit Assembler Linker and Utilities User s Guide Internal error line d s Internal error unknown dwarf2 format Internal can t hash s s Invalid abi mabi s Invalid listing option c Macros nested too deeply Missing emulation mode name Multiple emulation names specified No compiled in support for 64 bit object file No object file generated Rva not supported Rva without symbol Too many fixups Unrecognized emulation name s B 3 ERRORS The errors listed below usually indicate an error in the assembly source code or com mand line options passed to the assembler Symbol abort detected Abandoning ship User error invoked with the abort directive else without matching if A else directive was seen without a preceding if directive elseif after else A elseif directive specified after a e1se directive Modify your code so that the elseif directive comes before the else directive elseif without matching if A elseif directive was seen without a preceding if directive endfunc missing for previous func A endfunc directive is missing for a previous func directive endif without if A endif directive wa
293. y PIC18 Only Special registers on PIC18 devices that allow access regardless of the setting of the Bank Select Register BSR Access Entry Points Access entry points provide a way to transfer control across segments to a function which may not be defined at link time They support the separate linking of boot and secure application segments Address Value that identifies a location in memory Alphabetic Character Alphabetic characters are those characters that are letters of the arabic alphabet a b Z A B Z Alphanumeric Alphanumeric characters are comprised of alphabetic characters and decimal digits 0 1 9 ANDed Breakpoints Set up an ANDed condition for breaking e breakpoint 1 AND breakpoint 2 must occur at the same time before a program halt This can only be accomplished if a data breakpoint and a program memory breakpoint occur at the same time Anonymous Structure C30 An unnamed structure C18 An unnamed structure that is a member of a C union The members of an anon ymous structure may be accessed as if they were members of the enclosing union For example in the following code hi and lo are members of an anonymous structure inside the union caster union castaway int intval struct char lo accessible as caster lo char hi accessible as caster hi t4 caster ANSI American National Standards Institute is an organization responsible for formulating and approving st
294. y a start address for the section 2009 Microchip Technology Inc DS51833A page 109 32 Bit Assembler Linker and Utilities User s Guide 9 8 OPTIONS THAT MODIFY THE LINK MAP OUTPUT Link map output modifying options are cref print map M Map file 9 8 1 cref Output cross reference table If a linker map file is being generated the cross reference table is printed to the map file Otherwise it is printed on the standard output The format of the table is intention ally simple so that a script may easily process it if necessary The symbols are printed out sorted by name For each symbol a list of file names is given If the symbol is defined the first file listed is the location of the definition The remaining files contain references to the symbol 9 8 2 print map M Print map file on standard output A link map provides information about the link includ ing the following Where object files and symbols are mapped into memory How common symbols are allocated All archive members included in the link with a mention of the symbol which caused the archive member to be brought in 9 8 3 Map file Write a map file Print a link map to the file file See the description of the print map M option DS51833A page 110 O 2009 Microchip Technology Inc MPLAB ASSEMBLER LINKER AND UTILITIES FOR MICROCHIP PIC32 MCUs USER S GUIDE Chapter 10 Linker Scripts 10 1 INTRODUCTIO

MPLAB® Assembler, Linker and Utilities for PIC32 MCUs User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents

MPLAB&reg; Assembler, Linker and Utilities for PIC32 MCUs User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents

MPLAB® Assembler, Linker and Utilities for PIC32 MCUs User's Guide