. . . len equ 10 ; global version size equ 20 ; note that a local variable ; may now be created and modified test macro size ; local len, label ; local len and label len set size ; modify local len labelres len ; reserve buffer len set len-20 ; endm ; end macro See Also MACRO ENDM MACRO - Declare Macro Definition Syntax label macro [, ..., ] Description A macro is a sequence of instructions that can be inserted in the assembly source code by using a single macro call. The macro must first be defined, then it can be referred to in subsequent source code. A macro can call another macro, or may call itself recursively. Please refer to the chapter "Macro Language" for more information. Example Read macro device, buffer, count movlw device movwf ram 20 movlw buffer ; buffer address movwf ram 21 movlw count ; byte count callsys_21 ; read file call endm See Also ENDM LOCAL IF ELSE ENDIF EXITM MESSG - Create User Defined Message Syntax messg "" Description Causes an informational message to be printed in the listing file. The message text can be up to 255 characters. Issuing a MESSG directive does not set any error return codes. Example macro mssg_macro messg "mssg_macro-001 invoked without argument" endm See Also ERROR NOEXPAND - Turn off Macro Expansion Syntax noexpand Description Turns off macro expansion. See Also EXPAND NOLIST - Turn off Listing Output Syntax NOLIST Description Turn off listing file output. See Also LIST ORG - Set Program Origin Syntax org Description Set the program origin for subsequent code at the address defined in . MPASM outputs relocatable object code, while MPLINK will place the code at the specified address. If is specified, it will be given the value of the . The default origin is zero. Example int_1 org 0x20 ; Vector 20 code goes here int_2 org int_1+0x10 ; Vector 30 code goes here See Also RES FILL PAGE - Insert Listing Page Eject Syntax page Description Inserts a page eject into the listing file. See Also LIST TITLE PROCESSOR - Set Processor Type Syntax processor Description Set the processor type to : [16C54 | 16C55 | 16C56 | 16C57 | 16C71 | 16C84 | 17C42] General processor families can be selected as: [16C5X | 16CXX | 17CXX] to keep pace with new product offerings, assuming maximum memory allowances and boundaries for each family at the time of latest release. Example processor 16C54 See Also LIST RADIX - Specify Default Radix Syntax radix Description Sets the default radix for data expressions. The default radix is hex. Valid radix are: hex, dec, or oct. Example radix dec See Also LIST RES - Reserve Memory Syntax res Description The RES directive is a relative org command. The command causes the program counter to be advanced from its current location by the value specified in . Example buffer res 64 ; reserve 64 words of storage See Also ORG FILL SET - Define an Assembler Variable Syntax set Description assumes the value of the valid MPASM expression specified by . The SET directive is functionally equivalent to the EQU directive except that SET values may be altered by SET directives. Example area set 0 widthset 0x12 length set 0x14 Area set length * width length set length + 1 See Also EQU SPACE - Insert Blank Listing Lines Syntax space Description Insert number of blank lines into the listing file. Example space3 ;Inserts three blank lines See Also LIST SUBTITLE - Specify Program Subtitle Syntax subtitle "" Description is an ASCII string enclosed in double quotes, 60 characters or less in length. This directive establishes a second program header line for use as a subtitle in the listing output. Example subtitle "diagnostic section" See Also TITLE TITLE - Specify Program Title Syntax title "" Description is a printable ASCII string enclosed in double quotes. It must be 60 characters or less in length. This directive establishes the text to be used in the top line of the listing page. Example title "operational code, rev 5.0" See Also LIST SUBTITLE #UNDEFINE - Delete a Substitution Label Syntax #undefine Description is an identifier previously defined with the #DEFINE directive. It must be a valid MPASM label. The symbol named is removed from the symbol table. Example #define length 20 . . . #undefine length See Also #DEFINE IFDEF INCLUDE IFNDEF VARIABLE - Declare Symbol Variable Syntax variable [=,...,[=] ] Description is a valid MPASM label, and is a valid MPASM expression. The expression must be fully resolvable at the time of the assignment. The VARIABLE directive creates symbols for use in MPASM expressions. Variables differ from constants may be used interchangeably in expressions. The VARIABLE directive creates a symbol that is functionally equivalent to those created by the SET directive. The difference being that the VARIABLE directive does not require that symbols be initailized when they are declared. Example Please refer to the CONSTANT example. See Also SET CONSTANT WHILE - Perform Loop While Condition is True Syntax while . . . endw Description is a valid MPASM expression that controls the number of times the loop is performed. An expression that evaluates to zero is considered logically FALSE. An expression that evaluates to any other value is considered logically TRUE. The IF and WHILE directives operate on the logical value of an expression. A relational TRUE expression is guaranteed to return a value of one; FALSE a value of zero. Example test mac macro count variable i i = 0 while i < count movlw i i += 1 endw endm start test mac 5 end See Also ENDW IF MPASM USER'S GUIDE Chapter 4. Macro Language Introduction Macros are user defined sets of instructions and directives that will be included in-line with the assembler source code whenever the macro is invoked. Macros consist of sequences of assembler instructions and directives. They can be written to accept arguments, making them flexible. Their advantages are: ù Higher levels of abstraction, improving readability and reliability. ù Consistent solutions to frequently performed functions. ù Simplified changes. ù Improved testability. Applications might include, creating complex tables, frequently used code and complex operations. Highlights The points that will be highlighed in this chapter are: ù Macro Syntax ù Text Substitution ù Local Symbols ù Recursive Macros ù Macro Usage ù Examples Terms Macro As define before, a macro is a collection of assembler instructions that are included in the assembly code when the macro is invoked by the source code. Macros must be defined before their first invocation; forward references to macros are not allowed. All statements following the MACRO directive (see Chapter 5) are part of the macro definition. Lines consisting of a comment only are not saved in the macro definition. Labels used within the macro must be local to the macro so the macro can be called repetitively. Local Label A local label is one that is defined with the LOCAL directive (see Chapter 5). These labels are particular to a given instance of the macro's instantiation. In other words, the symbols and labels that are declared as local are purged from the symbol table when the ENDM macro is encountered. Recursion This is the concept that a macro, having been defined, can call itself. Great care should be taken when writing recursive macros; it is easy to get caught in an infinite loop where there will be no exit from the recursion. Macro Syntax MPASM macros are defined according to the following syntax: macro [, ...,] . . . endm Where is a valid MPASM label and are any number of optional arguments supplied to the macro. The values assigned to these arguments at the time the macro is invoked will be substituted wherever the argument name occurs in the body of the macro. The body of a macro may be comprised of MPASM directives, PIC16/17 assembly instructions, or MPASM Macro Directives (LOCAL for example). Refer back to Chapter 5. MPASM continues to process the body of the macro until a EXITM or ENDM directive is encountered. NOTE: Once again, forward references to macros are not permitted. Macro Directives As noted in Chapter 5, there are a few directives that are unique to macro definitions. They make no sense out of the macro context (refer to Chapter 5 for details concerning these directives): ù MACRO ù LOCAL ù EXITM ù ENDM When writing macros, you can use any of these directives PLUS any other directives supported by MPASM. NOTE: The previous syntax of the "dot" format for macro specific directives is no longer supported. For compatibility reasons old ASM17 code that uses this format will assemble by MPASM, but as mentioned before, you are encouraged to write new code based on the constructs defined within this document to ensure upward compatibility with MPASM. Text Substitution A variety of string replacement and parsing patterns may appear within the body of a macro. They may be used only within the body of a macro. Command Description Substitute the argument text supplied as part of the macro invocation. #v() Returns the integer value of the simple . Typically, used to create unique variable names with common prefixes or suffixes. Arguments may be used anywhere within the body of the macro, except as part of normal expression. For example, the following macro: define_table macro variable a = 0 while a < 3 entry#v( a ) dw 0 a += 1 endw endm would generate: entry0 dw 0 entry1 dw 0 entry2 dw 0 entry3 dw 0 when invoked. Recursive Macros Macros may invoke themselves. This is known as recursion. Care should be exercised, as in all cases of recursion, to avoid infinite loops. Macros called recursively will generate their own local variables if the LOCAL directive is used (see Chapter 3). Macro Usage Once the macro has been defined, it can be invoked at any point within the source module by using a macro call, as described below. [, ..., ] Where is the name of a previously defined macro, and arguments are supplied, as required. The macro call itself will not occupy any locations in memory. However the macro expansion will begin at the current memory location. Commas may be used to reserve an argument position. In this case, the argument will be NULL. The argument list is terminated by white space or a semicolon-colon. The EXITM directive (see Chapter 3) provides an alternate method for terminating a macro expansion. During a macro expansion, this directive causes expansion of the current macro to stop and all code between the EXITM and the ENDM directives for this macro to be ignored. If macros are nested, EXITM causes code generation to return to the previously level of macro expansion. Examples Eight by Eight Multiply subtitle "macro definitions" page ; ; multiply - eight by eight multiply macro, executing ; in program memory. optimized for speed, straight ; line code. ; ; written for the PIC17C42. ; multiply macro arg1, arg2, dest_hi, dest_lo ; local i ; establish local index variable variable i = 0 ; and initialize it. ; movlw arg1 ; setup multiplier movwf mulplr ; ; movlw arg2 ; setup multiplicand in w reg ; clrf dest_hi ; clear the destination regs clrf dest_lo ; ; bcf _carry ; clear carry for test ; while i < 8 ; do all eight bits addwf dest_hi ; then add multiplicand rrcf dest_hi ; shift right through carry rrcf dest_lo ; shift right again, snag carry ; if set by previous rotate i += 1 ; increment loop counter endw ; break after eight iterations endm ; end of macro. The macro declares all of the required arguments. In this case, there are four. The LOCAL directive then establishes a local variable "i" that will be used as an index counter. It is initialized to zero. A number of assembler instructions are then included. When the macro is executed, these instructions will be written in line with the rest of the assembler source code. The macro writes the multiplication code using an algorithm that uses right shifts and adds for each bit set in the eight bits of the multiplier. The WHILE directive is used for this function, continuing the loop until 'i' is greater than or equal to eight. The end of the loop is noted by the ENDW directive. Execution continues with the statement immediately following the ENDW when the WHILE condition becomes TRUE. The entire macro is terminated by the ENDM directive. Constant Compare For further example, if the following macro were written: include "16cxx.reg" ; ; compare file to constant and jump if file ; >= constant. ; cfl_jge macro file, con, jump_to movlw con & 0Xff subwf file, w btfsc status, carry goto jump_to endm and invoked by: cfl_jge switch_val, max_switch, switch_on it would produce: movlw max_switch & 0xff subwf switch_val, w btfsc status, carr goto switch_on MPASM USER'S GUIDE Chapter 5. Expression Syntax and Operation Introduction This chapter describes various expression formats, syntax, and operations used by MPASM. Highlights The points that will be highlighted in this chapter are: ù Text Strings ù Numeric Constants and Radix ù Arithmetic Operators and Precedence ù High / Low Operators Terms Expressions Expressions are used in the operand field of the source line and may contain constants, symbols, or any combination of constants and symbols separated by arithmetic operators. Each constant or symbol may be preceded by a plus or minus to indicate a positive or negative expression. NOTE: Expressions are evaluated in 32 bit integer math (floating point is not currently supported). Operators Operators are arithmetic symbols, like the plus sign "+" and the minus sign "-", that are used when forming well defined expressions. Each operator has an assigned precedence. Precedence Precedence is the concept that some elements of an expression get evaluated before others. In general, precedence is established from left to right, and expressions within parentheses are always evaluated first. Radix Radix is the base numbering system that the assembler is supposed to use when evaluating expressions. The default radix is hexadecimal (base 16). You can change the default radix (See Chapter 5) and override the default with certain radix override operators. These are described in this chapter. Text Strings A "string" is a sequence of any valid ASCII character (of the decimal range of 0 to 127) enclosed by double quotes. Strings may be of any length that will fit within a 132 column source line. If a matching quote mark is found, the string ends. If none is found before the end of the line, the string will end at the end of the line. While there is no direct provision for continuation onto a second line, it is generally no problem to use a second DW directive for the next line. The DW directive will store the entire string into successive words. If a string has an odd number of characters (bytes), the DW and DATA directives will pad the end of the string with one byte of zeros (00). If a string is used as a literal operand, it must be exactly one character long, or an error will occur. See the examples below for the object code generated by different statements involving strings. 7465 7374 696E dw "testing output string one\n" 6720 6F75 7470 7574 2073 7472 696E 6720 6F6E 650A #define str "testing output string two" B061 movlw "a" 7465 7374 696E data "testing first output string" 6720 6669 7273 7420 6F75 7470 7574 2073 7472 696E 6700 The assembler accepts the ANSI 'C' escape sequences to represent special control characters: TABLE6: ANSI 'C' Escape Sequences Escape Description Character \a Bell (alert) character \b Backspace character \f Form feed character \n New line character \r Carriage return character \t Horizontal tab character \v Vertical tab character \\ Backslash \? Question mark character \' Single quote (apostrophe) \" Double quote character \0OO Octal number (zero, Octal digit, Octal digit) \xHH Hexadecimal number Numeric Constants and Radix MPASM supports the following radix forms: hexadecimal, decimal, octal, binary, and character. The default radix is hexadecimal; the default radix determines what value will be assigned to constants in the object file when they are not explicitly specified by a base descriptor. Constants can be optionally preceded by a plus or minus sign. If unsigned, the value is assumed to be positive. NOTE:Intermediate values in constant expressions are treated as 32-bit unsigned integers. Whenever an attempt is made to place a constant in a field for which it is too large, a truncation warning will be issued. The following table presents the various radix specifications: TABLE 7: Radix Specifications Type Syntax Example Decimal D'' D'100' Hexadecimal H'' H'9f Octal O'' O'777' Binary B'' B'00111001' Character '' 'C' A'' A'C' TABLE 8: Arithmetic Operators and Precedence Operator Example ======================== ================================= ( Left Parenthesis 1 + ( d * 4 ) ) Right Parenthesis ( Length + 1 ) * 256 ! Item NOT (logical if !( a - b ) complement) - Negation (2's -1 * Length complement) high Return high byte movlw high CTRTable low Return low byte movlw low CTRTable * Multiply a = b * c / Divide a = b / c % Modulus entry_len = tot_len % 16 + Add tot_len = entry_len * 8 + 1 - Subtract entry_len = ( tot - 1 ) / 8 << Left shift << flags >> Right shift >> flags >= Greater or equal if entry_idx >= num_entries > Greater than if entry_idx > num_entries < Less than if entry_idx < num_entries <= Less or equal if entry_idx <= num_entries == Equal to if entry_idx == num_entries != Not equal to if entry_idx != num_entries & Bitwise AND flags = flags & ERROR_BIT ^ Bitwise exclusive flags - flags ^ERROR_BIT OR | Bitwise inclusive flags = flags |ERROR_BIT OR ~ Complement flags = flags ~ERROR_BIT && Logical AND if ( len == 512 ) && b == c || Logical OR if ( len == 512 ) || b == c = Set equal to entry_index = 0 += Add to, set equal entry_index += 1 -= Subtract, set entry_index -= 1 equal *= Multiply, set entry_index *= entry_length equal /= Divide, set equal entry_total /= entry_length %= Modulus, set equal entry_index %= 8 <<= Left shift, set flags <<= 3 equal >>= Right shift, set flags >>= 3 equal &= AND, set equal flags &= ERROR_FLAG |= Inclusive OR, set flags |= ERROR_FLAG equal ^= Exclusive OR, set flags ^= ERROR_FLAG equal $ Return program goto $ + 3 counter High / Low Syntax high low Description Where is an appropriate MPASM assembler instruction and is an appropriate argument list for that instruction. The high operators are used to return the high byte or the low byte of a 16-bit label value. This is done to handle dynamic pointer calculations as might be used with table read and write instructions. Example movlw low size ; handle the lsb's movpf wreg, low size_lo movlw high size ; handle the msb's movpf wreg, high size_hi MPASM USER'S GUIDE Chapter 6. MPLIB - MPASM Librarian Introduction A librarian is a tool that allows several different objects to be grouped into one logical collection, or library. MPLIB combines several object modules, created with MPASM, into a single file. When a library file is linked with other modules, only those library functions that are referenced by the other modules are linked into the final binary code. Object modules can be added, deleted, or replaced from the MPLIB Command Line Interface. MPLIB is reserved for a future release. MPASM USER'S GUIDE Chapter 7. MPLINK - MPASM Linker Introduction MPLINK is the MPASM relocatable object linker. It joins any number of object files, together with any library modules, into an executable binary file that is fixed in the PIC16/17's memory. MPLINK can also generate an absolute listing file of the PIC16/17 application. This file can be invaluable when debugging your design; it is in the same general format as the listing file generated for relocatable objects by MPASM. MPLINK accepts options from either its Command Line Interface or a script file. MPLINK is reserved for a future release. MPASM USER'S GUIDE Appendix A. Object Code Formats. Introduction MPASM and MPLINK are capable of outputting several different object file formats, suitable for a variety of programmer and emulator applications. Highlights ù Intel HEX Format (INHX8M) ù Intel Split HEX Format (INHX8S) ù Intel HEX 32 Format (INHX32) Object Code Formats MPLINK and MPASM (with absolute addresses) are capable of producing a number of different output formats. Intel Hex Format (.HEX) This format produces one 8-bit Hex file with a low byte, high byte combination. Since each address can only contain 8 bits in this format, all addresses are doubled. This file format is useful for transferring PIC16/17 series code to third party EPROM programmers. Each data record begins with a 9 character prefix and ends with a 2 character checksum. Each record has the following format: :BBAAAATTHHHH....HHHCC where BB - is a two digit hexadecimal byte count representing the number of data bytes that will appear on the line. AAAA - is a four digit hexadecimal address representing the starting address of the data record. TT - is a two digit record type record type that will always be `00' except for the end-of-file record, which will be `01'. HH - is a two digit hexadecimal data word, presented in low byte, high byte combinations. CC - is a two digit hexadecimal checksum that is the two's compliment of the sum of all preceding bytes in the record including the prefix. Example .HEX :1000000000000000000000000000000000000000F0 :0400100000000000EC :100032000000280040006800A800E800C80028016D :100042006801A9018901EA01280208026A02BF02C5 :10005200E002E80228036803BF03E803C8030804B8 :1000620008040804030443050306E807E807FF0839 :06007200FF08FF08190A57 :00000001FF 8-Bit Split Format (.HXL/.HXH) The Intellec split 8-bit file format produces two output files: .HXL and .HXH. The format is the same as the normal 8-bit format, except that the low bytes of the data word are stored in the .HXL file, and the high bytes of the data word are stored in the .HXH file. Example .HXL :0A0000000000000000000000000000F6 :1000190000284068A8E8C82868A989EA28086ABFAA :10002900E0E82868BFE8C8080808034303E8E8FFD0 :03003900FFFF19AD :00000001FF .HXH :0A0000000000000000000000000000F6 :1000190000000000000000010101010102020202CA :100029000202030303030304040404050607070883 :0300390008080AAA :00000001FF 32-Bit Hex Format (.HEX) The extended 32-bit address hex format is similar to the Hex 8 format described above, except that the Intel extended linear address record is output also to establish the upper 16 bits of the data address. Each data record begins with a 9 character prefix and ends with a 2 character checksum. Each record has the following format: :BBAAAATTHHHH....HHHCC where BB - is a two digit hexadecimal byte count representing the number of data bytes that will appear on the line. AAAA - is a four digit hexadecimal address representing the starting address of the data record. TT - is a two digit record type record type: 00 - Data record 01 - End of File record 02 - Segment address record 04 - Linear address record HH - is a two digit hexadecimal data word. CC - is a two digit hexadecimal checksum that is the two's compliment of the sum of all preceding bytes in the record including the prefix. MPASM USER'S GUIDE Appendix B. Customer Support Keeping Current with Microchip Systems Microchip Technology endeavors at all times to provide the best service and responsiveness possible to it users. The Microchip Technology Systems BBS is one mechanism to facilitate this process. The BBS is supported as a service to its customers. This is where all of the most recent information regarding systems products can be found. The BBS is monitored several times a week for questions. Truly urgent issues should not be left with the BBS, but referred to your local distributor, or Microchip sales office. The BBS is an evolving product. Details of its operation will not be found here. This chapter provides a brief discussion of the general services available. This chapter also describes the Microchip Systems software numbering scheme. Highlights The points that will be highlighted in this chapter are: ù Access to the BBS ù Special Interest Groups ù Files ù Mail ù Software Releases Bulletin Board Access Access to the bulletin board is 24 hours per day, barring technical or mechanical difficulties. Access is gained by calling your local CompuServe access number. Your modem should be set to 8-bits, No parity, 1 stop bit (8-1-N). The service supports baud rates from 300 to 9600 baud. To access the BBS, follow these steps: 1. Dial your local CompuServe access number. 2. Press and a garbage string will appear. 3. Enter + and Host Name: will appear. 4. Enter mchipbbs and you will be connected to the Microchip BBS. There is no charge for connecting to the BBS. There is no charge to dial the CompuServe access number. You do not need to be a CompuServe member to take advantage of this connection (you never actually log in to CompuServe). Bulletin Board Usage The bulletin board is a multifaceted tool. It can provide you with information on a number of different topics. ù Special Interest Groups ù Files ù Mail ù Bug Lists ù Technical Assistance Special Interest Groups Special Interest Groups, or SIGs as they are commonly referred to, provide you with the opportunity to discuss issues and topics of interest with others that share your interest or questions. They may be able to provide you with information not available by any other method because of the broad background of the PIC16/17 user community. There are SIGs for most Microchip systems, including: ù PRO MASTER ù PICMASTER ù MPASM ù Utilities ù Bugs These groups are monitored by the Microchip staff. Files The Microchip BBS is used regularly to distribute technical information, Application Notes' source code, errata sheets, bug reports, and interim patches for Microchip systems software products. Users can contribute files for distribution on the BBS. These files will be monitored, scanned and approved or disapproved by the moderator of the SIG to which the file is submitted. No executable files are accepted from the user community in general to limit the spread of computer viruses. Mail The BBS can be used to distribute mail to other users of the service. This is one way to get answers to your questions and problems from the Microchip staff, as well as to keep in touch with fellow Microchip users worldwide. Consider mailing the moderator of your SIG, or SYSOP, if you have ideas or questions about Microchip products, or the operation of the BBS. Be aware, though, that the SIGs are moderated only about once per day. Truly urgent questions should be referred to your local distributor, sales representative, or FAE. They are your first line of defense. Software Revisions Software products released by Microchip are referred to by version numbers. Version numbers use the form: xx.yy.zz Where xx is the major release number, yy is the minor number, and ZZ is the intermediate number. The status field displays one of the following categories: ù Alpha ù Intermediate ù Beta ù Released Production releases are numbered with major, and minor version numbers like: 3.04 Released Alpha, Beta and Intermediate releases are numbered with the major, minor and intermediate numbers: 3.04.01 Alpha Alpha Release Alpha designated software is engineering software that has not been submitted to any quality assurance testing. In general, this grade of software is intended for software development team access only, but may be sent to selected individuals for conceptual evaluation. Once Alpha grade software has passed quality assurance testing, it may be upgraded to Beta or Intermediate status. Intermediate Release Intermediate released software represents changes to a releasd software system and is designated as such by adding an intermediate number to the version number. Intermediate changes are represented by: ù Bug Fixes ù Special Releases ù Feature Experiments Intermediate released software does not represent our most tested and stable software. Typically, it will not have been subject to a thorough and rigorous test suite, unlike production released versions. Therefore, users should use these versions with care, and only in cases where the features provided by an intermediate release are required. Intermediate releases are primarily available through the BBS. Beta Release Preproduction software is designated as Beta. Beta software is sent to Applications Engineers and Consultants, FAEs, and select customers. The Beta Test period is limited to a few weeks. Software that passes Beta testing without having significant flaws, will be production released. Flawed software will be evaluated, repaired, and updated with a new revision number for a subsequent Beta trial. Production Release Production released software is software shipped with tool products. Example products are PRO MASTER, PICSTART, and PICMASTER. The Major number is advanced when significant feature enhancements are made to the product. The minor version number is advanced for maintenance fixes and minor enhancements. Production released software reresents Microchip's most stable and thoroughly tested software. There will always be a period of time when the Production Released software is not reflected by products being shipped until stocks are rotated. You should always check the BBS for the current production release. MPASM USER'S GUIDE Appendix C. MPALC Conversion Guide Introduction MPASM attempts to be backward compatible with MPALC. It is very possible that your source code will assemble as is. There are, however, a number of inconsistencies between the two assemblers that require some simple changes. In addition, MPASM attempts to provide a clean and simple assembler solution for the future. To that end, there are also a number of changes that are recommended to encourage compatibility going forward. Highlights ù Required Source Code Updates ù Recommended Source Code Updates Required Source Code Updates ù Specify processor type at the very top of the first source file in pro- grams assembled with MPASM using either the PROCESSOR or LIST directives, or specify the processor on the command line. MPASM will not assemble your source without this information. Recommended Source Code Updates ù You are encouraged to move all of your labels to column one, and assembler directives (like LIST and TITLE) to at least column two. An example would be: list p=16c54, r=hex title SampleCode #include "c:\tools\regs.h" #define zero 0 #define one 1 alabel set zero blabel set one org 0x00 goto Start org 0x28 Start goto Start end and so on. ù Specify the radix you are assuming using either the RADIX or LIST directives, or the command line option. ù Change all radix overrides currently included in your code to one of those specified in the MPASM User's Guide. For example: Change: movlw 5D to: movlw D'5' ù Fully qualify moves of label addresses by using the HIGH or LOW directives. MPASM USER'S GUIDE Appendix D. ASM17 Conversion Guide Introduction MPASM attempts to be backward compatible with ASM17. It is very possible that your source code will assemble as is. There are, however, a number of inconsistencies between the two assemblers that require some simple changes. In addition, MPASM attempts to provide a clean and simple assembler solution for the future. To that end, there are also a number of changes that are recommended to encourage compatibility going forward. Highlights ù Required Source Code Updates ù Recommended Source Code Updates Required Source Code Updates ù Specify processor type at the very top of the first source file in pro- grams assembled with MPASM using either the PROCESSOR or LIST directives, or specify the processor on the command line. MPASM will not assemble your source without this information. ù Change DOS paths for ASM17 source code from using two back slashes to one. Example: Change: #include c:\\tools\\regs.h to: #include c:\tools\regs.h ù Recode any macros that use a variable number of arguments to call out specific arguments. This would only be appropriate for ASM17 code, and is a feature that will be included at some point in the future. ù If you are using the ASM17 HALT directive, recode this as a macro or remove it. This feature will be included at some point in the future. ù If you are using the ASM17 FILL directive, temporarily remove it. This feature will be included at some point in the future. Recommended Source Code Updates ù You are encouraged to move all of your labels to column one, and assembler directives (like LIST and TITLE) to at least column two. An example would be: list p=17c42, r=dec title Sample Code #include "c:\tools\regs.h" #define zero 0 #define one 1 alabel set zero blabel set one org 0x00 goto Start org 0x28 Start goto Start end and so on. ù Specify the radix you are assuming using either the RADIX or LIST directives, or the command line option. ù Change all radix overrides currently included in your code to one of those specified in the MPASM User's Guide. For example: Change: movlw 5D to: movlw D'5' ù Fully qualify moves of label addresses by using the HIGH or LOW directives. MPASM USER'S GUIDE Appendix E. Error and Warning Messages The following error and warning messages are produced by MPASM. These messages always appear in the listing file directly above each line in which the error occurred. The error and warning messages are stored in the error file (.ERR) if no MPASM options are specified. If the /e- option is used (turns error file off), then the messages will appear on the screen. If the /q (quiet mode) option is used with the /e-, then the messages will not display on the screen or in an error file. The messages will still appear in the listing file. Error Messages Address exceeds maximum limit available You are trying to access memory that is not available; the current program counter is greater than the maximum program memory limit for the specified processor type. Please refer to the data sheet for this processor to find the valid memory range. Argument out of range The location trying to be accessed or filled is outside of the program memory range for the specified processor type. Please refer to the data sheet for your specific processor to find its program memory boundaries. Attempt to redefine reserved word The words "END", "ERROR", "HIGH", "LOW" and "PAGE" are reserved words in MPASM. You must not use these words as labels or symbols. Remove or rename any occurances of these words and then reassemble. NOTE: It is too costly with regard to both time and space to treat all directives, opcodes and operators as reserved words. MPASM reserves only the above minimal list of words to avoid the most common misuses of directives. Branch or jump out of range A branch or jump statement is addressing the last half of a program memory page. This is not allowed. Any instruction which writes to the Program Counter (CALL, JUMP, BRANCH or GOTO) is limited to the first 256 locations of any program memory page. Call or jump not allowed at this address A call or computed jump statement is addressing the last half of a program memory page. This is not allowed. Any instruction which writes to the Program Counter (CALL, JUMP, BRANCH or GOTO) is limited to the first 256 locations of any program memory page. Couldn't open . . . MPASM couldn't open the specified object file, memory map file, code file, error file, listing file, or cross-reference file. Either the file already exists and is read/write protected, or there is not enough disk space to create or write to the file. Couldn't open source file . . . The source file specified on the command line, or through the interactive menu, does not exist. Check the current directory for the desired file, and verify the spelling of the source file name. Duplicate label or redefining symbol that cannot be redefined You have either used the same label name twice in your program, or a constant, a #DEFINE'd symbol, or an EQU'd symbol has been used on the left- hand side of an equation. MPASM does not know which definition to use. This ERROR message appears before BOTH definitions of the symbol, when appropriate. Error in parameter One of the options used on the MPASM command line was not a valid option, or an option was incorrectly formatted. Type mpasm /h or mpasm /? at the DOS prompt to see a usage message showing the valid command line options. Expected . . . The syntax of the source line is incorrect. MPASM expected to see one thing, but got something different. Check the syntax of the directive or opcode in error in the MPASM User's Guide. File not found The file specified in the shell screen's source file field does not exist in the current directory. This error appears when the shell interface is used to invoke MPASM, rather than the command line interface. Check the spelling of the file name, and verify that you are in the desired directory. Press any key to continue. Illegal argument One of the directive arguments is of the wrong type. It could be that the radix specified with either a LIST directive or the RADIX directive is not one of the valid radix choices. Change the radix to: DEC for decimal, OCT for octal, or HEX for hexadecimal radix. Also, make sure that FILL directives have parentheses around the if it is an opcode expression. Illegal argument ( must be greater than zero) The expression specifiying the memory locations to be filled by the FILL directive evaluates to a number less than or equal to zero. It must be greater than zero. Illegal condition An IF statement is using an illegal comparison operator. The valid conditions which can be checked by an IF statement are: == (equal to) != (not equal to) > (greater than) < (less than) >= (greater than or equal to) <= (less than or equal to). Illegal condition (EOF encountered before END or conditional end directive) The END directive is missing, or a CBLOCK, an IF, a WHILE or a MACRO statement is missing an ENDC, ENDIF, ENDW or ENDM respectively. Illegal conditional compile There is a problem with the construction of the indicated IF / ELSE / ENDIF statements. Illegal character . . . in label . . . The specified label contains an illegal character. Legal characters are: underscore (_), period (.), capital letters (A through Z), lower case letters (a through z), or decimal digits (0 through 9). Illegal digit The specified digit is illegal in the context used. The digit is either incorrect for the radix specified in the source file, or is an unsupported ANSI escape sequence. Check the LIST directive used in the source code to verify the specified radix. See Chapter 5: Expression Syntax and Operation in the MPASM User's Guide for valid radix specifications and ANSI `C' escape sequences. Illegal opcode The indicated opcode or directive is not recognized by MPASM. The opcode may be misspelled, or is no longer supported. Or, an otherwise legal opcode may be used in an illegal context. For example, a valid directive, such as LIST, prepended with a pound sign (#LIST) will generate this "Illegal opcode" error message. Other examples are: using an ELSE without an associated IF, or using an INCLUDE directive inside a macro definition. Include file not found The file to be included does not exist in the current directory. Check the spelling of the include file name, and verify that you are in the desired directory. If necessary, specify the complete DOS path. For example: C:\SOURCE\INCLUDE\FILENAME.H This error may also occur if you do not have a BUFFERS= statement in your DOS CONFIG.SYS system file. Please refer to your DOS manual to add this line. We recommend at least using BUFFERS=10. Include files nested too deep The current include file cannot include another file, because you have reached the maximum level of include file nesting. The maximum number of include files nested within each other is five (5). Macro name missing The term "macro" has been encountered without an associated name for the macro. Macro names can be any legal, unique MPASM label. Macros nested too deep The current macro definition cannot call another macro, because you have reached the maximum level of macro nesting. The maximum number of macros nested within each other is eight (8). Missing argument(s) This opcode, directive, or macro call requires at least one more operand (argument) than is provided. Check the instruction set for the proper syntax. This error can also occur if a #DEFINE'd label is missing a value. In this case, the error message won't appear until the label is used as an operand. This message may also appear if the arguments for a FILL or MACRO directive are not separated by commas. Missing terminator There is an open parenthesis, curly bracket or square bracket without a matching closed parenthesis, curly bracket or square bracket, respectively. This error message can also occur when a comma or blank is expected, but not found. Nested forward reference not allowed The indicated label has not been defined yet, and is not allowed to be used before it is defined. Specifically, forward references to macros are not permitted. If a macro call is generating the error, move the call to a point in the code below the macro definition. This error message also occurs when MPASM cannot tell the type of a given label: variable, constant, address, local variable, or reserved word. The label may be defined more than once. Out of memory All the PC's available memory has been used to create code segments, macros and forward references. Try reducing the number of macros in your source file(s). Also, close out of any terminate-and-stay- resident programs (TSR's) and close any applications, then try assembling the file again. If you are running Windows and assembling from a DOS prompt or from MPSLED, try exiting Windows and assembling directly from DOS. Overwriting previous address contents The location for which MPASM is trying to generate object code has already been used by this program. Usually, an ORG directive for this address occurs prior to the source line that produces this error message. The only time MPASM will allow you to overwrite a previously-used address is if it was reserved with an RES directive. This error also occurs if the FILL directive is trying to fill an address that already has a value. Processor type is undefined No processor type has been specified. Use the LIST or PROCESSOR directive at the top of your source code, or use the /p option on the command line, to define a processor type (PIC16C54, PIC16C55, PIC16C56, PIC16C57, PIC16C58, PIC16C63, PIC16C64, PIC16C65, PIC16C71, PIC16C73, PIC16C74, PIC16C84, or PIC17C42). Processor type previously defined A processor type has already been specified. You cannot change processor types in the middle of a program. Check the LIST or PROCESSOR directive in your source code to see which processor type is defined. If you specify the same processor type two or more times in the same program, no error will occur. Symbol table full All the PC's available memory has been used to create symbols. MPASM requires more memory to create all the symbols defined in this source file. Eliminate any TSR's, and close any applications, then try assembling the file again. If you are running Windows and assembling from a DOS prompt or from MPSLED, try exiting Windows and assembling directly from DOS. You may get the qualifier "Out of macro space (#define)" appended to this message. If this is the case, eliminate #DEFINE symbols in your code by hardcoding as many values as possible. Or, you may see this error message qualified with "more than 8 locals in a macro." The maximum number of local variables allowed per macro is eight (8). Eliminate local variables from the macro definition. Temp file creation error A temporary file could not be created as needed. MPASM uses temporary files when building the symbol table. This error could be caused by a DOS disk write error, if the disk is full. Too many arguments An opcode has been given too many operands, or a macro has been invoked with too many arguments. Check the processor's instruction set for the proper opcode syntax, or verify the number of arguments in the macro definition. Undefined argument A label is being used that has not yet been defined. The label might be used as an operand or as a macro argument. If there is a mistake in the argument list of a macro definition, this error message will appear when the macro is invoked, since the arguments were never properly defined. Unknown error An error has occurred which MPASM cannot understand. It is not any of the errors described in this appendix. Contact your Microchip Field Application Engineer (FAE) if you cannot debug this unknown error. While failed to terminate within 256 iterations The end condition of a WHILE loop was never met. This is flagged as an "Unknown error" because MPASM doesn't know why the WHILE loop didn't terminate. Check your condition statement for proper syntax and logic. Warning Messages Addresses above 32K not currently supported. Using MaxRom. MPASM does not currently allow you to access memory above 0x8000 (32K). Eventually, addresses up to 64K will be supported, when the linker and librarian are implemented. Argument out of range, least significant bits used The operand is not between the maximum and minimum values allowed for this opcode in this processor family. Most "Argument out of range" errors are WARNING messages. The out-of-range argument is truncated to the maximum value allowed. However, any argument that can produce unexpected object code (for example, TRIS 0 would evaluate to a NOP) generates an ERROR message rather than a WARNING. ... Is not currently supported Any directive that is not currently supported generates this WARNING. Please look in the User's Guide for alternative directives, or contact your Microchip Field Applications Engineer for options. LCALL should only be used for multi-paged program memory You are using the LCALL opcode, when you should be using CALL instead. LCALL only applies for processors that have more than one page of program memory (such as the 16C57). LCALL uses 4 execution cycles, while CALL only uses 2. This is only a WARNING, and correct code is generated. This number is being treated as a binary representation The specified number is ambiguous, and could be interpreted as either a binary or hexadecimal number. MPASM is assuming that it is binary. Example: b0101. MPASM expects hexadecimal numbers to be represented as 0xb0101 or as H'b0101'. Warning level superceded by command line value (...) The warning level specified by the LIST directive's "w=" option is not taking effect, because a value has been specified on the command line with the /w option. Information Messages Crossing page boundary -- ensure page bits are set MPASM is informing you that a page boundary has been crossed, and is recommending that you check to see that you have properly set the page bits. Please refer to the data sheet for your specific processor to find its memory boundaries. Filling locations <...> through <...> with the value <...> This information message lets you know the locations and the value the FILL directive is filling. This is needed because the addresses and values are not shown in the object code section of the listing file. ... May not be handled as preprocessor directive The #DEFINE and #UNDEFINE directives generate this WARNING to inform you that these directives do not function exactly as you would expect them to operate in the C language. Please refer to the User's Guide descriptions for these directives to determine how they will behave. The ZERO directive will be discontinued. Please use FILL instead The ZERO directive was provided for backward compatibility. It will not be supported in the future. We highly recommend using the FILL directive in place of ZERO. FILL is more versatile, and is well documented. MPASM USER'S GUIDE Quick Reference This quick reference guide is supplied to give you all of the instructions for the Microchip family of microcontrollers, including their description, function and status bits modified. If more information is required, please refer to the data sheets for the PIC16/17 in question. Highlights ù Directive Summary ù PIC16C5X Instruction Set and Notes ù PIC16CXX Instruction Set and Notes ù PIC17CXX Instruction Set and Notes Terms PIC16C5X Microchip's low-end 8-bit microcontroller with 12-bit wide instruction set currently including: PIC16C54, PIC16C55, PIC16C56, PIC16C57, and PIC16C58. PIC16CXX Microchip's mid-range 8-bit microcontroller with 14-bit wide instruction set currently including: PIC16C71, PIC16C64, and PIC16C84. PIC17CXX Microchip's high-end 8-bit microcontroller family with 16-bit wide instruction set currently including PIC17C42. TABLE 9: Directive Summary Directive Description CBANK Future Feature CBLOCK Define a Block of Constants CONSTANT Declare Symbol Constant DATA Create Numeric and Text Data DB Declare Data of One Byte #DEFINE Define a Text Substitution Label DW Declare Data of One Word ELSE Begin Alternative Assembly Block to IF END End Program Block ENDC End an Automatic Constant Block ENDIF End conditional Assembly Block ENDM End a Macro Definition ENDW End a While Loop EQU Define an Assembly Constant ERROR Issue an Error Message "" EXITM Exit from a Macro EXPAND Expand Macro Listing FILL Specify Memory Fill Value IF Begin ConditionallyAssembled Code Block if IFDEF Execute If Symbol has Been Defined IFNDEF Execute If Symbol has not Been Defined INCLUDE Include Additional Source File LIST Listing Options LOCAL Declare Local Macro Variable MACRO Declare Macro Definition MESSG Create User Defined Message NOEXPAND Turn off Macro Expansion NOLIST Turn off Listing Output ORG Set Program Origin PAGE Insert Listing Page Eject PROCESSOR Set Processor Type RADIX Specify Default Radix RES Reserve Memory SET Define an Assembler Variable SPACE Insert Blank Listing Lines SUBTITLE Specify Program Subtitle TITLE Specify Program Title #UNDEFINE Delete a Substitution Label VARIABLE Declare Symbol Variable WHILE Perform Loop While Condition is True