MCA-51 Macro Assembler,
MCLINK Linker and Utilities
User's Guide
Phyton
MCA-51
Information in this document is subject to change without notice and does not involve any
commitment on the part of the manufacturer. No part of this manual may be reproduced or
transmitted in any form or by any means, such as copying in electronic form, photocopying,
recording, information storage and retrieval systems, for any purposes other than for the purchaser's use, without a written permission.
Copyright 2000 Phyton, Inc., Microsystems and Development Tools and MicroCOSM, Ltd.
All rights reserved.
Project-51™, PICE-51™, PDS-51™ are trademarks of Phyton, Inc.
MCA-51™ is a trademark of the MicroCOSM, Ltd.
Intel®, MCS-51®, ASM-51®, and PL/M-51® are registered trademarks of Intel Corporation.
Microsoft®, MS-DOS®, and Windows™ are trademarks or registered trademarks of
Microsoft Corporation.
IBM®, PC® are registered trademarks of International Business Machines Corporation.
Keil C-51™, Keil CA-51™ and dScope™ are trademarks of Keil Elektronik GmbH.
C-SPY™ is a trademark of IAR Systems.
MCA-51
Phyton
Table of Contents
Chapter 1. Useful information................................................................ 1
1.1.How to contact Phyton, Inc. .............................................................1
1.2.If you are an experienced user... .......................................................1
1.3.License ..............................................................................................1
Chapter 2. Basic concepts ..................................................................... 3
2.1.Assembler - What is it? ....................................................................3
2.2.Program Development Process .........................................................4
2.3.Concept of module and library .........................................................4
2.4.Address Area Concept ......................................................................7
2.5.Segments .........................................................................................11
2.6.Symbolic Names .............................................................................13
Chapter 3. Assembler Start and Command Line Options ................. 19
3.1.Running Assembler and Output Files .............................................19
3.2.-Ccpu : to specify processor type ...................................................19
3.3.-Ipath : to search for include-files in specified directories .............20
3.4.-d : to generate debug information .................................................20
3.5.@file : to read options from specified file ......................................20
3.6.-a : to disable instruction operands types check .............................21
3.7.-l : to generate listing ......................................................................21
3.8.-Jdir : to place an object file in specified directory ........................21
3.9.-Ldir : to place listing in specified catalog .....................................22
3.10.-x : to generate cross-reference table in the listing .......................22
3.11.-c : to include false conditionals ...................................................22
Phyton
MCA-51
3.12.-g : to generate listing for macro source texts ..............................22
3.13.-e : to generate listing for macro expansions texts .......................22
3.14.-p : to split the listing into 40-line pages ......................................23
3.15.-Pnn : to split the listing into pages with specified length ............23
3.16.-Ennn : to terminate assembling after nnn errors .........................23
3.17.-Wnnn : to display not more than nnn warnings ..........................23
3.18.-b : to produce a beep if an error is detected ................................23
3.19.-s : to display a number of processed lines ...................................24
3.20.-h, -? : to display brief description of options ...............................24
Chapter 4. Basic Syntactic Rules ........................................................ 25
4.1.Vocabulary and Grammar ..............................................................25
4.2.Names and Labels Definition Rules ...............................................25
4.3.Set of Symbols and Delimiters .......................................................26
4.4.Keywords ........................................................................................27
4.5.Assembler Source Line Format ......................................................27
Chapter 5. Arithmetic Expressions ..................................................... 31
5.1.Concept of expression ....................................................................31
5.2.Numbers and their representation in memory ................................31
5.3.Program counter .............................................................................32
5.4.Character strings in expressions .....................................................33
5.5.Segment Names in Expressions ......................................................34
5.6.Conversion and Check of Types in Expressions ............................34
5.7.Comparison Operators ....................................................................37
5.8..SFB, .SFE Operators .....................................................................38
5.9..DATE Operator .............................................................................38
5.10..BYTE, .BIT, .UNTYPED Operators ...........................................38
5.11..HWRD, .LWRD, .HIGH, .LOW, .BYTE3 Operators .................39
5.12..DEFINED Operator .....................................................................40
5.13..ALLOCATION Operator ............................................................40
5.14..OPTYPE Operator .......................................................................42
5.15..TYPE Operator ............................................................................43
5.16..BLANK Operator ........................................................................43
5.17..PARM Operator ...........................................................................44
5.18."Period" (.) Operator .....................................................................45
MCA-51
Phyton
5.19..RBANK Variable ........................................................................46
5.20..AR0...7 Variables ........................................................................46
5.21..MODEL Variable ........................................................................49
5.22..NPARMS Variable ......................................................................49
5.23.List of Operators in Order of Priority ...........................................50
5.24.Predefined Assembler Constants ..................................................52
Chapter 6. Assembler Directives ......................................................... 55
6.1..LSTOUT ........................................................................................56
6.2..LSTCND ........................................................................................56
6.3..LSTMAC .......................................................................................56
6.4..LSTEXP .........................................................................................56
6.5..LSTXRF ........................................................................................57
6.6..LSTWID ........................................................................................57
6.7..TITL ...............................................................................................57
6.8..STITL ............................................................................................58
6.9..PAGE .............................................................................................58
6.10..INCLUDE ....................................................................................58
6.11..LMODULE, .PMODULE ...........................................................58
6.12..LMODULE2 ................................................................................59
6.13..ENDMOD, .END ........................................................................59
6.14..PUBLIC .......................................................................................59
6.15..EXTRN ........................................................................................60
6.16..ASEG, .RSEG ..............................................................................61
6.17..LNKCMD ....................................................................................61
6.18..ORG .............................................................................................62
6.19..DEFINE, .EQU, .SET, = .............................................................62
6.20..DS ................................................................................................63
6.21..DSB, .DSW, .DSD, .DSC, .DSI, .DSL, .DSR, .DST ..................64
6.22..DB1 ..............................................................................................65
6.23..DB2, .DB4 ...................................................................................66
6.24..DCB, .DCW, .DCD, .DCC, .DCI, .DCL, .DCR ..........................67
6.25..BYTE, .BIT .................................................................................68
6.26..WARNING, .ERROR, .MESSAGE ............................................69
6.27..ALIGN .........................................................................................69
6.28..TYPE ...........................................................................................70
Phyton
MCA-51
6.29..FUNC, .ENDF .............................................................................70
6.30..OBJREC ......................................................................................72
6.31..LABELB, LABELW, LABELD, LABELC, LABELI, LABELL,
LABELR, LABELT .............................................................................72
6.32..EXTRNB, .EXTRNW, .EXTRND, .EXTRNC, .EXTRNI, .EXTRNR, .EXTRNT, .EXTRNN ..............................................................74
6.33..EXTRNF ......................................................................................75
Chapter 7. Listing controls .................................................................. 77
Chapter 8. Macrotools, retry blocks and conditional assembling.... 79
8.1.Macros: Purpose & Function ..........................................................79
8.2.Directive .MACRO .........................................................................80
8.3.Directive .EXITM ...........................................................................81
8.4.Directive .ENDMAC ......................................................................81
8.5..REPT Repeat Block .......................................................................81
8.6..IRP - Repeat Block with Parameter Scanning ...............................82
8.7..IRPC - Repeat Block with Scanning a String-Parameter ..............83
8.8.Macro Call and Parameter Substitution ..........................................84
8.9.Passing of Actual Parameters by means of the < and > symbol .....87
8.10.Declaration of Local Labels in Macros ........................................88
8.11.Actual Parameters and Text Concatenation in Macros ................90
8.12.Parameter-to-String Conversion ...................................................91
8.13.Expression-to-Text Conversion at the Macro Call .......................92
8.14.Nested Macro Calls and Definitions .............................................93
8.15.Purpose & Function of Conditional Assembling ..........................94
8.16..IF, .ELSE, .ENDIF - Conditional Assembling Directives ...........94
Chapter 9. MCS-51 architecture specific feature support ................. 95
9.1.Support of Various Processors' Instruction Sets .............................95
9.2.8051 Operands; type check in instructions .....................................95
9.3.Register Banks Support ..................................................................98
9.4.Special Function Registers (SFRs) Support ...................................99
Chapter 10. Assembler messages..................................................... 101
Chapter 11. Purpose and basic operating principles of the Linker 129
11.1.Purpose of the Linker and Linking Process ................................129
MCA-51
Phyton
11.2.Establishing a Set of Modules to be Linked ...............................129
11.3.Resolving External References and Type Check .......................130
11.4.Setting up Address Spaces ..........................................................131
11.5.Relocatable segments linking .....................................................131
11.6.Segment Placement .....................................................................132
11.7.Support of Instruction Sets for Various Processors (Linker) .....134
11.8.Linker's Messages .......................................................................134
Chapter 12. Linker start and options................................................. 137
12.1.Start Line Format ........................................................................137
12.2.-A Option: Address Area Definition ..........................................137
12.3.-C Option: Enables Code Generation in Address Area ..............138
12.4.-K Option: Disables Allocation of Relocatable Segments .........138
12.5.-S Option: Segment Allocation ...................................................139
12.6.-E Option: Specifies Output File Name ......................................140
12.7.-O Option: Specifying Search Paths for Object Files .................141
12.8.-F Option: Specifies Output File Format ....................................141
12.9.-H Option: Specifies HEX-file name extension .........................142
12.10.-Z Option: Increases Segment Size ..........................................142
12.11.-m Option: Generates a MAP-file ............................................143
12.12.-M Option: Not to include Specified Section in the MAP-file .143
12.13.-t Option: Turns off Global Type Checking .............................144
12.14.-w Option: Linker's Warnings Control .....................................144
12.15.-h, -? Options: Displays Brief Description of Options .............145
12.16.@filename Option: Includes File in the Command Line ..........145
12.17.-p, -l, -o Prefixes: Changing Module Types .............................145
Chapter 13. MCLIB library service utility .......................................... 147
13.1.-a: Adds Modules to the Library .................................................147
13.2.-d: Deletes Modules from the Library ........................................147
13.3.-r: Replaces Modules in the Library ...........................................148
13.4.-x: Extracts Modules from the Library into Object Files ...........148
13.5.-X: Extracts Modules from the library into one Object File .......149
13.6.-m: Moves Modules from the Library into Object Files ............149
13.7.-M: Moves Modules from the Library into One Object File ......150
13.8.-l: Displays Library Header on the Console ...............................150
Phyton
MCA-51
13.9.-P: Assigns "Program" Attribute to Modules .............................151
13.10.-L: Assigns the "Library"' Attribute to Modules ......................151
13.11.-O: Assigns the "Low-Priority Library"' Attribute to Modules 151
13.12.-h,-?: Displays Brief Options Description on the Console .......152
13.13.@: Includes File Contents in the Command Line ....................152
13.14.MCLIB Messages .....................................................................152
Chapter 14. MCDUMP utility for printing out object files ................ 155
14.1.MCDUMP messages. .................................................................155
MCA-51
Phyton
Chapter 1. Useful information
1
Chapter 1. Useful information
1.1. How to contact Phyton, Inc.
If you suspect that you have discovered an error in Assembler or related programs, please do the following before you contact us:
• Read the section(s) of this manual related to the error;
• Make sure that you are using the latest version of the product;
• Try to locate the problem so that you can determine, which program specifically contains an error, e.g., the compiler, linker, assembler or other utility,
• Try to reduce your source text to locate the error.
Then, if you were unsuccessful in locating the bug in your program, send your
detailed report to support@phyton.com.
1.2. If you are an experienced user...
If you are quite an experienced user, you will probably have no need in thoroughly studying this manual (forthwith)
See the example in the catalog EXAMPLES\SAMPLE (files sample.m51,
sample1.m51, sample2.m51, make.bat, sample.lnk), and find the answers that you
are looking for in the documentation.
It might be sufficient at first.
1.3. License
Before your acceptance of the MCA-51 (hereinafter referred to as SW) you
should agree to the terms and conditions set out by the license and resolve to
abide by them at all times..
Phyton
MCA-51
2
MCA-51
Chapter 1. Useful information
Phyton
Chapter 2. Basic concepts
3
Chapter 2. Basic concepts
2.1. Assembler - What is it?
Assembler is a development tool intended to facilitate the task of writing computer programs. It transforms a source code (source assembler text) into the
object code ready for execution by a target processor or micro-controller.
MCA-51 Assembler generates the code suitable for execution by any processor
compatible with Intel 8051 in terms of its command system.
In Assembler language, every executable code instruction corresponds to some
mnemonic name (i.e. assembler mnemonics). Assembler mnemonics are worked
out by processors' manufacturers and, as a rule, reflect the essence of corresponding instructions. For example, ADD usually indicates addition.
Instead of using absolute addresses, any sensible symbolic names (identifiers) can
be utilized to indicate addresses of variables, arrays, and jump addresses. It will
make it easier to read and understand your program, facilitating its maintenance
(testing, modification, and documentation).
Any assembly program can include the following:
• description of machine instructions ( e.g., mnemonics and operands),
• assembler directives; e.g., identifier definition directives, macro definitions
etc,
• assembler controls; e.g., listing generation enable/disable directive.
In addition to directives and commands, command line options, specified at the
start, control assembler behavior during translation.
Phyton
MCA-51
Chapter 2. Basic concepts
4
2.2. Program Development Process
Macro Assembler MCA-51 translates assembler source files. Re-locatable object
modules in MCO format are generated as a result of translation.
Object modules, users' and standard (that is, supplied along with cross-tools)
libraries are combined into one program by the MCLINK Linker; output files are
generated in the following formats:
• MCE (absolute object file with debugging information),
• HEX (absolute object file in the Intel HEX-format),
• ZAX (file with debugging information in the ZAX format).
2.3. Concept of module and library
2. 3. 1 . W hat i s a m odul e?
A user's program can be divided into several, relatively independent parts. Each
part may contain some code and/or data fragment. As it is designed in accordance with some conventions, it becomes a module. The Linker links modules
into one executable file.
When programmed in the high-level language (C, for example), every file with
the program source text is a module.
In assembler, every source text file can be divided into several modules by means
of directives .PMODULE, .LMODULE, .ENDMOD and .END. Therefore, an
object file generated by assembler may contain several modules.
2.3.2 . W hat i s a L i brar y ?
Library (library file) is a set of object modules generated from object files by the
MCLIB Librarian.
MCA-51
Phyton
Chapter 2. Basic concepts
5
It is important to realize that not only modules with the 'library' attribute can be
included in a library, but also modules with the 'program' attribute, that is, program modules that are always included in a resulting file by the Linker.
It should be noted that object files could also contain several modules. The main
difference between an object file and a library is that a library has a special
header (catalogue), which is used by the Linker while scanning libraries. That is
why the Linker can scan libraries much faster -- an important element during the
integration of large projects.
2 . 3 . 3 . M o d ul e t y p e s
There are three possible types of modules: program, library, or low-priority
library type. While combining, linker analyses all the modules contained in
object files, the names of which are specified in the command line. All program
modules are linked unconditionally; a library module is linked only if other modules to be linked contain references to this module. The linker only scans low-priority library modules after all program and conventional library modules have
been scanned. Therefore, low-priority library modules are included in the program only if they contain external references, which cannot be resolved by means
of conventional library modules.
In assembly source file, module types are defined by the header directive
(.PMODULE or .LMODULE).
Module type can be temporarily redefined: command line options -p, -1 and -o
instructs the Linker to consider all modules in a certain object file as program,
library or low-priority library ones respectively.
In addition, the type of the module contained in the library can be changed by the
MCLIB library utility.
Phyton
MCA-51
6
Chapter 2. Basic concepts
2. 3. 4 . Ad vantag es of m odul ar pro gram mi ng
Modular approach entails a method of writing programs where the program
under development is divided into fragments (modules) intended for accomplishing certain tasks. Every module can contain both executable code and required
data (data encapsulation), while the module contents are being hidden from other
modules of the program (name hiding). Those data and labels that should be
known to other modules are declared in a special way (as public names). Accordingly, a module may contain external references that are calls to public names.
Such method of the source texts processing is called separate compilation.
The assembler or C-compiler processes source text of every module separately;
at that stage relocatable object modules are generated; external references are not
resolved at this stage. Following this, the relocatable modules are processed by
the linker; at this stage, external references are resolved (inter-modular linking),
addresses are specified, and relocatable modules are merged into resulting absolute object file.
Name hiding makes it possible to use the same symbol names in different modules for identifying different data or labels. It eliminates the necessity of inventing different names for internal data and module labels. For example, variable
COUNTER may be used in one module as the counter of bytes received via serial
communication link, and may also be used in other module for counting transmitted bytes. In such case, variables identified by COUNTER are different in different modules. Such variables are sometimes said to be local variables in the
module.
Data encapsulation can be used for facilitating program composition of ready
modules.
Due to separate compilation, the whole program need not be re-compiled when
changes are introduced in one or several modules. Only the modules that were
changed should be re-compiled, then the Linker must process all modules. This
saves time during large program development.
MCA-51
Phyton
Chapter 2. Basic concepts
7
Modular approach allows to implement structured programming principle and to
further advantages:
• executable code and data are hidden inside modules, thus reducing the probability of “induced” errors,
• if it is necessary to introduce changes into a sensibly structured program, the
area of correction is limited to separate modules rather than the whole source
text,
• sensible division into functionally separate modules and availability of program documentation allows using code fragments written earlier, in new
projects.
2.4. Address Area Concept
2 . 4 . 1 . Pu r p o s e o f a d d r e s s a re a s
As a rule, several memory types are concurrently used in controllers, such as
ROM where executable code is usually stored, and RAM, used for variables,
arrays etc.
Address areas provide support for a variety of memory hardware configurations.
These several address areas (for example, one area - for ROM, and another - for
RAM) can be defined and specified by address ranges including breaks.
Then code and data can be assigned to address spaces as required or default settings may be used.
2 . 4 . 2 . W h a t i s a d d r e s s s p a c e a l l o c a t i o n?
Each address area has an allocation attribute. The Linker requires this attribute to
check the correctness of address area declarations and of placing the segments in
address areas. For example, if a user tries to allocate an external data memory
segment (i.e. segment with allocation==xdata) in code memory (i.e. in address
area with allocation==code), the Linker will generate an error message.
Phyton
MCA-51
Chapter 2. Basic concepts
8
2.4.2.1 Placement of Segments in Address Areas
Every segment has "allocation" attribute specified by user in the source text.
When linking a program, the Linker is instructed as to the way of placing segments in address areas.
Note!
Linker checks allocation attributes of address areas and segments. If
mismatch is detected, the Linker generates an error message.
The Linker can automatically place segments in standard address spaces. Assembler takes into account the allocations of the segments to be placed. Segments
with allocation==bit are placed in BIT address space; segments with allocation==data are placed in DATA address space etc. Automatic segment placing is
performed after all the segments specified for the Linker in -S options have been
placed. Automatic segment placing is carried out according to the table:
Segment
allocation
Name of standart
address space
Size of standard
address space
bit
BIT
000H-0FFH
data
DATA
000H-07FH
bdata
BDATA
020H-02FH
idata
DATA
000H-07FH
sfrs
SFRS
080H-0FFH
xdata
XDATA
000H-0FFFFH
code
CODE
000H-0FFFFH
2.4.2.1.1. Allocation Attributes Supported
Allowable values of allocation attribute and corresponding address ranges are
listed in the table below:
MCA-51
Phyton
Chapter 2. Basic concepts
Allocation
9
Name of standard
address space
Is banking allowed? a
Maximum address
range
bit
BIT
no
000h-0FFh
data
DATA
no
000h-07Fh
bdata
BDATA
no
020h-02Fh
idata
IDATA
no
000h-0FFh
sfrs
SFRS
no
080h-0FFh
xdata
XDATA
YES
000h-0FFFFh
code
CODE
YES
000h-0FFFFh
a. “Is banking allowed==no” means that you can not create address spaces
with the names different from the name of standard address space, that is,
you can change only the size of standard address space.
Bit-type segments are used for reserving space for bit objects (addressable by
means of bit addressing mode). Addresses in the segments with allocation = bit
are addresses of bits. Names defined in segments of this type have the following
specific feature: they can be used only in bit instructions. Note that the higher
half of the BIT address space is reserved for bits in special function registers.
Data-type segments are used for reserving space for directly and indirectly
addressable objects in on-chip RAM.
Bdata-type segments are used for reserving space in on-chip RAM for directly
and indirectly addressable objects, certain bits of which can be addressed in the
bit addressing mode. Names defined in the segments of this type have the following specific feature: they can be used in the bit address calculation operators.
Idata-type segments are used for reserving space in on-chip RAM for indirectly
addressable objects.
Xdata-type segments are used for the work with external data memory (that is,
memory that can be accessed by MOVX instructions). In these segments, you
Phyton
MCA-51
Chapter 2. Basic concepts
10
can reserve space (for RAM and external peripherals support) and initialize
memory with data (for ROM support).
Code-type segments are used for work with code memory. In these segments,
you can use machine instructions, mnemonics, and initialize memory with data
(for generating tables that can later be accessed through MOVC instructions).
Sfrs1-type segments are reserved for defining special function registers (can be
addressed only by means of direct addressing mode). You can use only absolute
segments as segments of this type. Names defined in the segments of this type
have the following specific feature: they can be used in the bit address calculation
operators (the Linker checks if address of the byte for which bit address is calculated is divisible by 8). In addition, such names can not be used anywhere except
for directly addressable machine instructions (what is the point of manipulating
address of the object that can not be addressed indirectly?).
2. 4. 3 . Ad dres s A re as D e c l a r a t i o n
Linker always generates the following standard address areas:
Address area name
Address range
BIT
000H-0FFH
DATA
000H-07FH
BDATA
020H-02FH
IDATA
000H-07FH
SFRS
080H-0FFH
XDATA
000H-0FFFFH
CODE
000H-0FFFFH
1. If you use special function registers definitions from MCA-51 supply set, you will
never immediately need SFRS address space and segments with allocation==sfrs
MCA-51
Phyton
Chapter 2. Basic concepts
11
Size of these address areas can be re-specified by means of the -A option of the
Linker. As a rule, it may be required only for IDATA, XDATA, and CODE.
Other address areas (if necessary) can be declared in the Linker's command line
by -A option. "Allocation" attributes and address range should be specified for
each address area.
Address range of address area should be within the range allowed for given allocation.
For additional information refer to:
2.4.2.1.1.“Allocation Attributes Supported” on page8
2.5. Segments
2 . 5 . 1 . W h a t i s a s e g me n t ?
Segment is a fragment of program memory or data memory. Every segment has a
name assigned by a user; a segment can be absolute or relocatable, and can have
other attributes.
Within a module, code and data may be allocated to several segments. During
program linking, the data from various modules, allocated in segments of the
same names, will be combined into one continuous block.
2.5.2 . Ab sol ute a nd R el ocat abl e S egm ents
Segment type (absolute or relocatable) is specified by the directive of segment
declaration (.ASEG or .RSEG).
Code/data located in an absolute segment are bound to absolute physical
addresses in the source text. Values that are not changed while link(s) ing are
assigned to the names (are) defined in an absolute segment.
Location of code/data placed in a relocatable segment is established at the
assembly stage by the shift from the segment origin (i.e., from the origin of the
Phyton
MCA-51
Chapter 2. Basic concepts
12
segment part located within a given module). Absolute addresses are calculated
at the linking stage, after the segment size has been determined and the segment
has been located starting from certain physical.
2. 5. 3 . "A l lo c ati on" attri bu t e of a segm ent and
i t s p u r p os e
Architecture of many microprocessors assumes the use of various memory types
with various access methods. For example, for 8051 processors:
Memory type
Allowable access methods
bit (bit-organized memory)
bit addressing
data (built-in ROMwithin the
range 0...07FH)
direct and indirect addressing
bdata (built-in ROMwithin the
range 20H...02FH)
direct and indirect addressing;certain
bits can be addressedby bit addressing
idata (add. built-in RAM 8052
within the range080H...0FFH)
indirect addressing only
sfrs (memory area forspecial
function registers)
direct addressing only
xdata (external data memory
MOVX instructions
code (code memory)
instructions are read from here
Assembler should check for the data access correctness. In order to perform this
check, Assembler should recognize the memory type of every operand. In the
Assembler, "allocation" attribute is assigned to every operand.
This is done in the following way. When writing a program, a user places code
and data in segments. Every segment has a special allocation attribute specified
by a user upon declaring a segment. This attribute is automatically assigned from
MCA-51
Phyton
Chapter 2. Basic concepts
13
the segment to any identifier declared by the user within a certain segment, and
later on, the Assembler can check for the correctness of this identifier access.
To learn more about the placement of segments in address areas see
2.4.2.1“Placement of Segments in Address Areas” on page8
Supported allocation attributes are described in detail in 2.4.2.1.1.“Allocation
Attributes Supported” on page 8
2.6. Symbolic Names
2.6.1 . Local , E x ter nal and Pu bl ic n ame s
Names defined within a module can be divided into two categories: local names
(they should be used only in this particular module) and public names (additionally specified by the .PUBLIC directive).
References to public names defined in other modules are allowed. Such references are called external references. External names (used for external references) should be specified in the module by means of .EXTRNx directives.
The same local names may be used for identifying various objects in different
modules; such names would not be in conflict.
Public name can be used for references in other modules (for which it will be an
external name) and therefore should be unique.
2 . 6 . 2 . R el oc a t a b il i t y A t t r i b u t e o f a N a m e
Relocatability attribute of a name instructs the Linker whether it should specify
the name (usually memory address) while linking. If the name is of absolute type
(ABS), its value is determined at the assembling stage and it does not need any
correction. If the name is relocatable (REL, EXT), its value is not known at the
assembling stage and it should be specified
Phyton
MCA-51
Chapter 2. Basic concepts
14
Names defined within absolute segments as well as the names defined by means
of .EQU and .SET directives have the ABS relocation attribute.
Names defined within relocatable segments have the REL relocation attribute.
External names have the EXT relocation attribute.
Generally speaking, any operand, and not only a name, has relocatability. For
example, numbers have ABS relocatability.
The following values of relocatability attribute are possible:
ABS
absolute value
REL
relocatable value
EXT
external value
SEG
segment (for segments only)
SFB
start address of the segment (.SFB operation result)
SFE
end address of the segment (.SFE operation result)
2 . 6 . 3 . Ad v a n t a g e s o f A pp ly i n g D at a Ty p es
8-bit ALU is a core of the MCS-51 family processors. However, bit operations
are also supported. There are several address spaces that can be accessed only if
appropriate addressing mode is used.
Assignment of appropriate types to variables when defining them makes it possible for the Assembler to diagnose a large number of logical errors at the assembling stage. The following are typical examples: the attempt to perform a byte
MCA-51
Phyton
Chapter 2. Basic concepts
15
operation as a bit operation; external data memory (XDATA) location access by
direct addressing, etc.
Types are also important at the debugging stage. They enable the debugger to be
aware of size, signs, and other parameters of variables and will allow showing
them in corresponding form. For example, if a variable is defined by means of the
.DSC directive (an 8-bit signed number), the debugger will show its value
exactly as an 8-bit signed number.
2.6.4 . The "Typ e" Attr ib ute of a Nam e
Every symbolic name defined in the program has type attribute. The following is
a list of available types:
Type
Number
Constant in MCA-51
Description
nothing
0
-
undefined type
char
4
.CHAR
8-bit, signed number
unsigned char
5
.UCHAR
8-bit, unsigned number
int
8
.INT
16-bit, signed number
unsigned int
9
.UINT
16-bit, unsigned number
long
10
.LONG
32-bit, signed number
unsigned long
11
.ULONG
32-bit, unsigned number
float
12
.FLOAT
32-bit, floating-point number
The .DCx, .DSx, .LABELx, .EXTRNx assembler directives automatically
assign type to the data defined by them.
Data on symbol types is included in debugging information and is available during debugging. For example, if you want to ascertain the value of variable VAR
while debugging, the debugger will know its size and sign and will show the right
value in a proper format.
Phyton
MCA-51
Chapter 2. Basic concepts
16
When integrating a program, the Linker checks the type attributes of public and
external names. For example, if in one module the variable VAR is of the .CHAR
type and is declared by the .PUBLIC directive, and other module refers to this
variable by means of the .EXTRNB directive, then in the latter module the variable is of the .UCHAR type and the Linker generates an error message.
Generally speaking, any operands (and not only names) have type attributes. For
example, the result of any arithmetic expression has type == nothing.
2.6.5 . Oper and Ty pe A ttri bu t e of a N am e
The "operand type" attribute is required in order for the Assembler to check if
instruction code matches its operands size.
Operand types
Operands size
BYTE
8 bits
BIT
1 bit
UNTYPED
length is unknown
If an operand type is assigned to a name, the Assembler will check whether the
name is used correctly in instructions. If operand type attribute is not defined for
some name, then the Assembler will consider the name to be UNTYPED. The
UNTYPED names cannot be used in instructions as memory addresses unless
special operators of redefining operand types are used. This helps to avoid the
errors such as "no # before the constant" error .
mov VAR1,#33
MCA-51
The constant is loaded into VAR1
Phyton
Chapter 2. Basic concepts
mov VAR2,44
17
Error: no #. Instead of incorrect code
The Assembler will generate the error message
Because the constants are UNTYPED
movVAR3, .byte 55
This is an example of the use of type
Redefining operator when you need to us
A constant as an address
To use any name (expression) as an operand in any instruction, you can redefine
the operand type of this name.
The .DCx, .DSx, .LABELx, .EXTRNx assembler directives automatically
assign operand type to the data items defined by them. In addition, you can use
the .BYTE, .BIT, .UNTYPED directives (and operators) for the type definition
(and temporary redefinition).
Generally speaking, any operand (and not only names) has the operand type. For
example, numbers have the UNTYPED operand type.
2 . 6 . 6 . Al l oc a t i o n A t t r i b u t e o f a N am e
Public names defined in a segment inherit the allocation attribute of the segment.
Allocation attributes for external names are specified in the .EXTRNx directive.
This attribute is required in order for the Assembler to know which addressing
mode should be used to access memory location identified by a certain name. For
example, if a name has allocation==bit, it can be used in bit instructions only.
It should be noted that during the program integration, the Linker checks if allocation attribute of external name matches allocation attribute of corresponding
public name.
Phyton
MCA-51
18
Chapter 2. Basic concepts
Names that are not associated with any addresses, e.g. the names declared as constants by the .EQU, .SET etc. directives, do not have allocation attributes.
MCA-51
Phyton
Chapter 3. Assembler Start and Command Line Options
19
Chapter 3. Assembler Start and
Command Line Options
3.1. Running Assembler and Output Files
To start the Assembler, specify the following in the command line:
MCA51 [options] Source_File.M51_Name
Detailed description of options is given below. The "@" option makes it possible
to pass any parameters from a disk file to the Assembler. Although the length of
the DOS command line is limited, you can pass any number of parameters to the
Assembler using the "@" option.
It is recommended to use extension .MCA for the MCA-51 Assembler source
files in order not to confuse them with other Assemblers source files (normally
they have extensions .A51, .ASM).
In the process of compilation, the Assembler generates error messages and other
information and displays all the messages on the console.
The Assembler generates output listing file and output object file. Both files have
the same name as the source file name, but their extensions are .lst and .mco
respectively. Assembler output files are included in current directory.
The path for the listing file can be arbitrarily specified by the -L option. A different directory can also be specified for the output object file by the -J option.
3.2. -Ccpu : to specify processor type
-C chip_architecture
Phyton
MCA-51
Chapter 3. Assembler Start and Command Line Options
20
Establishes restriction on the use of certain instructions in accordance with
selected processor architecture type. It should be noted that the Linker can not
link the modules assembled for different architectures.
chip_architecture means:
51
752
original command set of 8051 is used
MOVX, LCALL, LJMP are not supported (for the
Philips 8XC750/1/2 chips)
-C 51 by default.
3.3. -Ipath : to search for include-files in specified directories
-I path
Search for the include files, the path to which is not specified in the source text,
in the directories specified in this option, if they are not found in the current
directory. Directory names are separated by semicolons. Example: I..\..\inc;c:\mc51\my_inc
3.4. -d : to generate debug information
-d
Is used to include debug information in the object file. This information will be
used for the source-level debugging. By default, debug information is not
included in the object file.
3.5. @file : to read options from specified file
@filename
Includes contents of specified file in the command line; <CR>, <LF> are ignored
in this file; you can include comments which should be preceded by the hash
symbol "#"; the remainder of the line after this symbol is ignored.
MCA-51
Phyton
Chapter 3. Assembler Start and Command Line Options
21
3.6. -a : to disable instruction operands types
check
-a
When processing instructions, the Assembler checks if attributes of the instruction operands match the instructions. For example, when processing a jump
instruction, the Assembler checks if the operand (jump address) has the code
allocation. Attribute mismatch results in warning messages. All such warnings
can be disabled by means of the -a option.
We would not recommend using this option for the assembling of regular
assembler programs, as it allows to detect a large number of accidental and logical errors.
On the other hand, we would recommend this option when assembling the program generated by means of some intelligent software. One of the examples (and
the most typical one) is a disassembled text in which numbers (addresses of variables) are used instead of symbolic variables. The use of this option allows to disable the majority of warnings which are not important in this case.
3.7. -l : to generate listing
-l
Generates a listing file under the same name as the source file and with extension
.lst. By default, a listing file is not generated.
3.8. -Jdir : to place an object file in specified
directory
-J <directory_specification>
By default, the Assembler places output object file(s) in current directory. This
option instructs the Assembler to use other directory. Example: -J OBJ.
Phyton
MCA-51
Chapter 3. Assembler Start and Command Line Options
22
Assembler will place object file(s) in the OBJ subdirectory of current directory.
Please, make sure that this subdirectory exists.
3.9. -Ldir : to place listing in specified catalog
-L <directory_specification> By default, the Assembler places the listing in
the current directory. This option instructs the Assembler to use other directory.
Example: -L c:\tmp\listings.
3.10. -x : to generate cross-reference table in
the listing
-x
Generates cross-reference table in the listing file.
3.11. -c : to include false conditionals
-c
Includes false conditionals in the listing.
3.12. -g : to generate listing for macro source
texts
-g
Generates listing for macro definitions' source texts.
3.13. -e : to generate listing for macro expansions texts
-e
Generates listing for the text of macro expansions. False conditionals placed
within macro expansions will be included in the listing only if listing generation
is enabled for both macro expansions and false conditionals.
MCA-51
Phyton
Chapter 3. Assembler Start and Command Line Options
23
3.14. -p : to split the listing into 40-line pages
-p
Splits listing file into 40-line pages. By default, listing file is not split into pages.
3.15. -Pnn : to split the listing into pages with
specified length
-P pagelen
Splits listing file into pages with a length of pagelen. By default, listing file is not
split into pages.
3.16. -Ennn : to terminate assembling after nnn
errors
-E nnn
Terminates assembling after nnn errors have been detected. By default, all error
messages are displayed.
3.17. -Wnnn : to display not more than nnn
warnings
-W nnn
Stops displaying warnings after nnn error warnings; if nnn is equal to 0, the output of warnings is disabled. By default, all warnings are displayed.
3.18. -b : to produce a beep if an error is
detected
-b
To produce a beep if an error is detected.
Phyton
MCA-51
Chapter 3. Assembler Start and Command Line Options
24
3.19. -s : to display a number of processed
lines
-s
Displays the number of lines assembled. Only line numbers divisible by 8 are
displayed. By default, the display is disabled. Note that in many computer systems the speed of assembling decreases substantially if this option is enabled.
3.20. -h, -? : to display brief description of
options
-h
-?
Displays brief description of options on the console. This information is also displayed if the Assembler is run without parameters.
MCA-51
Phyton
Chapter 4. Basic Syntactic Rules
25
Chapter 4. Basic Syntactic Rules
4.1. Vocabulary and Grammar
As any other language, the Assembler language consists of the vocabulary (set of
words used in expressions - terms and tokens) and grammar (set of rules defining
the ways of combining terms to express ideas (notions) and actions).
Assembler language source line is a basic assembler language unit. The source
line may contain an assembler mnemonics or directive.
Correct lines should be formed from correct tokens arranged in a certain order (in
compliance with grammar rules). The Assembler accepts all ASCII characters,
however, some of the characters have special meaning. Incorrectly written lines
cause Assembler error messages to be displayed. Such concepts as numbers,
delimiters, reserved words and identifiers are defined in detail below.
4.2. Names and Labels Definition Rules
Identifiers (names) are symbolic names defined by user that are utilized for specifying addresses, constants, macro definitions etc. in the program text.
A name may consist of Latin letters, numbers, question marks and underscores. It
should not contain any delimiters (e.g. spaces); it should not begin with a digit.
The name length should not exceed 255 characters.
When defining and using names, remember that the names are case-sensitive. For
example, BUFFER and buffer are different identifiers.
Label is a name that ends with a colon.
Phyton
MCA-51
Chapter 4. Basic Syntactic Rules
26
Character String is a sequence of ASCII characters enclosed in single quotes (').
If you use quotation mark symbol within a Character String you should write it
twice ("). The maximum String length allowed is 255 characters.
It should be noted that strings by themselves do not end with zero bytes (which is
customary in C). If you need a line ending with zero, you should add a zero byte
at the end of the string.
4.3. Set of Symbols and Delimiters
In the source text of assembler programs you can use Latin letters, numbers and
special symbols listed below.
Any symbols can be used in comments.
Delimiters are used for separating terms (tokens) in the Assembler expressions.
Allowed delimiters with brief descriptions are listed below:
MCA-51
Symbol
Code
Name
Description (function)
SPACE
Space
Separates fields, delimits identifiers
HT
Horizontal tabulation
The same as for space
‘
Single quote
Delimits character strings.
.
Period
Directive prefix, "period" operator
,
Comma
Separates arguments
;
Semicolon
Starts comments
:
Colon
Delimits label on its right
#
Hash mark
Operand prefix
“
Quote
Floating-point number prefix
Phyton
Chapter 4. Basic Syntactic Rules
Symbol
Code
()
27
Name
Brackets
Description (function)
Delimit expressions
4.4. Keywords
Keywords (reserved words) are the names that have special meaning for the
Assembler and, hence, they are inaccessible to the user for redefining. The
assembler structures mnemonics, allocation attributes names (bit, data, bdata,
idata, sfrs, xdata, code), as well as names R0...R7, A, DPTR, AB, C are keywords.
Keywords are not case-sensitive.
See also:
2.4.2.1.1.“Allocation Attributes Supported” on page8.
4.5. Assembler Source Line Format
Assembler program source text line consists of 4 fields: label field, operation
field, operand field and comment field:
[Label: | Name] [Operation] [Operands] [;Comment] <CR,LF>
Label field
[Label: | Name]
This field contains either a label or a name. Unlike a name field, a label field
should end with a colon. A label can be placed in a separate line, while a name
can be put only before machine instructions, macros calls, and assembly directives. The value of a name or a label is the current value of the Assembler program counter.
Phyton
MCA-51
Chapter 4. Basic Syntactic Rules
28
Operation field
[Operation]
This field contains a machine instruction code mnemonics, a directive mnemonics or a macro name defined by user.
Operands field
[Operands]
Contents and syntax are subject to peculiarities of the operation specified in this
line.
Comment field
[;Comment]
Serves to place comments on any line of the program. Comments are ignored by
the Assembler but are included in the listing file. Comment field should begin
with a semicolon(;). The remainder of the line (after ';') should be considered as
comment.
Additional rules
5. Assembler does not support line splitting. All parameters of one operator
should fit into one line.
6. Every line should end with either the line feed or carriage return symbol.
7. Spaces may be used anywhere in the line but not within tokens.
MCA-51
Phyton
Chapter 4. Basic Syntactic Rules
29
8. Programs may contain empty lines.
9. A line containing a label should be placed within some segment only.
Phyton
MCA-51
30
MCA-51
Chapter 4. Basic Syntactic Rules
Phyton
Chapter 5. Arithmetic Expressions
31
Chapter 5. Arithmetic Expressions
5.1. Concept of expression
Expressions are normally used to define addresses and constants.
Definition. Expression is a syntactic structure corresponding to one of the following variants:
• a single basic operand,
• unary operator applied to expression,
• binary operator applied to a couple of expressions.
In practice, this means that the user can introduce expressions into the program
source text in accordance with common notation known since school.
The following are the basic (simple) operands:
•
•
•
•
•
numbers,
names defined by a user,
the $ symbol,
character strings,
segment names.
More detailed descriptions are given in the following sections.
5.2. Numbers and their representation in memory
Numbers should be represented by a correct sequence of digits ending with a suffix defining the radix. Hexadecimal numbers should always start with a digit;
therefore, for example, instead of ABCDH you should write 0ABCDH.
Numbers
Phyton
Radix
Digits
Suffix
Binary
2
01
B
Octal
8
01234567
O
Decimal
10
0123456789
Da
MCA-51
Chapter 5. Arithmetic Expressions
32
Numbers
Hexadecimal
Radix
16
Digits
0123456789ABCDEF
Suffix
H
a. Suffix for decimal is optional as the format is used by
default
All numbers are stored in memory as 32-bit integer values, so they should fit in
32 bits.
Floating-point numbers format is also supported, for example, you can write:
3.2645E+4. Floating-point numbers are stored in 32 bits in compliance with the
IEEE754 standard for single-precision real numbers. Such numbers can not be
used in arithmetic expressions, but should be used only for memory initialization
(specifying initial variable values and constant tables) in the programs containing
calculations with single-precision real numbers that comply with the IEEE754
standard.
Information on number types:
Allocation
Operand type
Type
Relocatability
<none>
UNTYPED
0
ABS
5.3. Program counter
When generating the code, the Assembler uses its internal variable for tracing
addresses. This variable is called the program counter. You can refer to its current value by means of the $ symbol. The returned value will be equal to the program counter value BEFORE the current line assembling.
It should be noted that the Assembler program counter always belongs to some
segment. It means that every segment contains its own program counter, and the
MCA-51
Phyton
Chapter 5. Arithmetic Expressions
33
Assembler uses program counter of the active (current) segment as a current
counter.
Since a segment can be either relocatable or absolute, the value returned by the $
symbol is of the ABS or REL type, respectively.
Information on the value returned by the $ symbol's types:
Allocation
Operand type
Type
taken from the current segment
UNTYPED
nothing
Relocatability
taken from the current
segment
5.4. Character strings in expressions
Character Strings may be used in the .DCx directives and in comparison operations.
If the character string length does not exceed four characters, the string can be
used as an operand in arithmetic expressions. In such case the far right symbol of
the string will be placed in the least significant byte (byte with the lowest
address). For example, the value of string '1234' is 031323334H.
Information string values 1 types:
Allocation
Operand type
Type
Relocatability
<none>
UNTYPED
nothing
ABS
See also:
4.2.“Names and Labels Definition Rules” on pag e25.
1. is applied only to the strings not longer than 4 characters
Phyton
MCA-51
Chapter 5. Arithmetic Expressions
34
5.5. Segment Names in Expressions
The value of a segment name used in an expression is equal to the segment fragment origin (absolute address) in the current module. The usage of segment
names in expressions is essentially restricted. For more details see the next sections.
Information on segment name values types:
Allocation
Operand type
Type
Relocatability
-
-
SEG
Obtained from the segment
5.6. Conversion and Check of Types in Expressions
Every operand has a set of attributes:
•
•
•
•
allocation,
operand type,
type,
relocatability.
When expression is computed, attributes are checked for compatibility and converted according to a rather complicated set of the rules listed below. It should be
noted that types of operands are not checked and the result always has the "nothing" type.
If the result of computed expression has ABS relocatability, this expression is
called absolute, otherwise, it is called relocatable.
If not explicitly specified otherwise in operation description, the following rules
of types check and conversion are applied:
MCA-51
Phyton
Chapter 5. Arithmetic Expressions
35
5 . 6 . 1 . Bi n a r y o p e r a t i o n s
Operands should have the same allocation attributes. The result has the same
allocation attribute as initial operands. If one of the operands does not have an
allocation attribute, then allocation of the result is taken from the other operand.
Combination of two operands without allocation is allowable. Subtraction of two
relocatable operands declared in one segment presents a special case - irrespective of allocation attributes of the operands, the result does not have allocation.
That is, the result is a number.
Operand type attributes of operands should be the same, or one of the operands
should be UNTYPED, otherwise, the Assembler will generate a warning. If
operand types are the same, the result will have the same type as the operands. If
operand types are not the same, and one of the operands is UNTYPED, then the
type of the other operand will be assigned to the result. If operand types are not
the same, and neither of the operands is UNTYPED, then the result will be
UNTYPED.
Relocatability is checked and converted in a rather complicated way.
All operations are allowed between ABS-type operands, and the result is of ABS
type too. It's worth mentioning that non-ABS type operand can not be subtracted
from ABS-type operand.
The following binary operations are allowable for the REL-type operands: addition to an ABS type operand (result type is REL), subtraction of an ABS-type
operand from a REL-type operand (result type is REL), and subtraction operation for two REL-type operands declared in the same segment (result type is
ABS). Other binary operations are not allowed for the REL-type operands.
The following binary operations are allowable for the EXT-type operands: addition to an ABS type operand (result type is EXT) and subtraction of an ABS type
operand from an EXT type operand (result type is EXT). Other binary operations
are not allowed for the EXT-type operands.
Phyton
MCA-51
Chapter 5. Arithmetic Expressions
36
SEG-type operands (segment names) can be added to the ABS-type operands.
ABS-type operands can be subtracted from the SEG-type operands. In both
cases, relocatability attribute of the result is SEG. Other binary operations are not
allowed for the SEG-type operands.
The following binary operations are allowable for the SFB (SFE)-type operands:
addition to an ABS type operand (result type is SFB or SFE) and subtraction of
an ABS type operand from an SFB type operand (result type is SFB) or from an
SFE operand (result type is SFE). Other binary operations are not allowed for the
SFB-type and SFE-type operands.
5. 6. 2 . U nary o pera t io ns
Allocation attribute of the result is inherited from the operand.
Operand type attribute of the result is inherited from the operand, except for the
special operand type conversion operations (.BYTE, .WORD etc).
Relocatability attribute is checked and converted in the following way.
.SBF and .SFE operations can only be applied to the SEG-type operands (segment names). Relocatability attribute of the result is SBF or SFE, respectively.
Other unary operations are not allowed for the SEG-type operands.
All unary operations can be applied to the ABS-type operands. Result type is
ABS.
Part extraction operations (.HWRD, .LWRD etc.) are only allowable for the
operands of the REL, EXT, SFB, SFE types. The result will inherit the relocatability attribute from the operand; no arithmetic operations (neither unary, nor
binary) can be applied to the result later on.
MCA-51
Phyton
Chapter 5. Arithmetic Expressions
37
5.7. Comparison Operators
Syntax:
Expression comparison_operator expression
Comparison operators:
< ,.LT
signed LESS THAN
<=,.LE
signed LESS OR EQUAL
> ,.GT
signed GREATER THAN
>=,.GE
signed GREATER THAN OR EQUAL
.ULT
unsigned LESS THAN
.UGT
unsigned GREATER THAN
==,.EQ
EQUAL
<>,.NE
NOT EQUAL
Comparison operations return the number equal to:-1 (.TRUE, 0FFFFFFFFh), if
the result of comparison is true, or 0 (.FALSE), if the result of the comparison is
false.
Comparison operations can be applied not only to numbers but also to the strings
with the length of more than 4 characters.
• strings are considered equal, if they are completely identical,
• one string is considered greater, than the other, if this string is farther from
the beginning of the list arranged in alphabetical order, for example:
'ABCDEFG' is greater than 'ABCD'
'ABCCCCC' is less than 'ABCD'
Signed and sign-insensitive comparison operators should be used for the comparison of character strings.
Phyton
MCA-51
Chapter 5. Arithmetic Expressions
38
5.8. .SFB, .SFE Operators
Syntax:
.SFB segment_name
.SFE segment_name
The .SFB and .SFE unary operators can be applied only to the segment names,
defined in the current module; .SFB returns absolute start address of the segment
and .SFE returns absolute end address of the segment. The result is calculated by
the Linker at the program linking stage.
Severe restrictions are imposed on the use of these operations result. See section
5.6.“Conversion and Check of Types in Expressions” on page34 for details.
5.9. .DATE Operator
Syntax:
.DATE absolute_expression
The result of the .DATE operation is a number that depends on its argument
value:
.DATE 1
current time (seconds) 0-59
.DATE 2
current time (minutes) 0-59
.DATE 3
current time (hours) 0-23
.DATE 4
current date (day) 1-31
.DATE 5
current date (month) 1-12
.DATE 6
current date (year minus 1900)
Argument of the DATE operator should be absolute and should be within the
range 1 - 6.
5.10. .BYTE, .BIT, .UNTYPED Operators
Syntax:
MCA-51
Phyton
Chapter 5. Arithmetic Expressions
39
.BYTE (expression)
.BIT (expression)
.UNTYPED (expression)
These operations make it possible to use expressions as operands in assembler
instructions without disabling strict type check.
.BYTE operation changes values of the expression operand type and allocation
attributes. Operand type becomes equal to BYTE, and allocation attribute
becomes equal to data.
.BIT operation sets operand type == BIT, allocation == bit.
.UNTYPED sets operand type == UNTYPED
Examples:
mov A,.byte (11+20)
clr .bit 54
;send a byte to the address 31 in A
;clear a bit at the address 54
For additional information refer to:
2.6.5.“Operand Type Attribute of a Name” on page 16.
5.11. .HWRD, .LWRD, .HIGH, .LOW, .BYTE3
Operators
Syntax:
.HWRD expression
.LWRD expression
.HIGH expression
.LOW expression
.BYTE3 expression
Phyton
MCA-51
Chapter 5. Arithmetic Expressions
40
These unary operators are also called part extraction operators; they return the
following values:
.HWRD
.LWRD
.HIGH
.LOW
.BYTE3
high word of the operand,
low word of the operand,
low byte of the operand's low word,
high byte of the operand's low word,
low byte of the operand's high word.
Certain restrictions are imposed on the use of these operations result.
See also:
5.6.“Conversion and Check of Types in Expressions” on page34.
5.12. .DEFINED Operator
Syntax:
.DEFINED name
Returns -1 (.TRUE), if the name is defined, and returns 0 (.FALSE) otherwise.
Forward references always return .FALSE. External references return .FALSE,
if external name is not declared in the earlier lines of the source text.
Example:
moo .set 1
.EXTRNN boo
aa = .DEFINED moo
aa = .DEFINED boo
aa = .DEFINED foo
aa = .DEFINED zoo
foo .set 2
;true
;true
;false
;false
5.13. .ALLOCATION Operator
Syntax:
MCA-51
Phyton
Chapter 5. Arithmetic Expressions
41
.ALLOCATION expression
Returns a numeric value corresponding to allocation attribute of the operand.
Forward references are forbidden. This operator is appropriate in macros for conditional code generation.
This operator has very low priority. Therefore, parentheses are required, as a
rule:
.if (.allocation FOO) .eq 2
...
Allocation
Returned value
<none>
0
Bit
1
Data
2
bdata
3
Idata
4
Sfrs
5
xdata
6
Code
8
Example:
moo .set 1
.extrnt boo
.extrnb (data) foo
.rseg seg1,xdata
zoo:
.rseg seg2,code
too:
aa = .ALLOCATION moo
aa = .ALLOCATION boo
Phyton
;
;
;
;
;
;
;
;returns 0
;returns 1
MCA-51
Chapter 5. Arithmetic Expressions
42
aa = .ALLOCATION foo
aa = .ALLOCATION zoo
aa = .ALLOCATION too
aa = .ALLOCATION noo
noo .set 2
.end
;returns 2
;returns 6
;returns 7
;error - forward reference
5.14. .OPTYPE Operator
Syntax:
.OPTYPE expression
Returns a numeric value corresponding to the operand type of expression. Forward references are forbidden. This operator is appropriate in macros for conditional code generation.
This operator has very low priority. Therefore, parentheses are required, as a
rule:
.if (.optype FOO) .eq 2
...
Operand type
Returned value
BYTE
1
BIT
4
UNTYPED
0
Example:
.rseg RD,data
.extrnt boo
zoo .dsb
too:
aa = .OPTYPE boo
MCA-51
;
;define external unsigned char boo
;define integer (signed word) zoo
;define untyped name too
;optype returns 4
Phyton
Chapter 5. Arithmetic Expressions
aa = .OPTYPE zoo
aa = .OPTYPE too
aa = .OPTYPE noo
noo .set 2
.end
43
;optype returns 1
;optype returns 0
;ERROR - forward reference
;define untyped name noo
;
5.15. .TYPE Operator
Syntax:
.TYPE name
Returns type number of the name. Forward references are forbidden. For type
numbers refer to section:
This operator has very low priority. Therefore, parentheses are required, as a
rule:
.if (.type FOO) .eq .uchar
...
See also:
2.6.4.“The "Type" Attribute of a Name” on page15.
5.16. .BLANK Operator
Syntax:
.BLANK formal_parameter_name
Returns -1 (.TRUE), if actual argument passed to the macro as a substitution for
the formal_parameter_name is empty (that is, it is omitted in a macro call). Otherwise returns 0 (.FALSE). This operator can be used only within a macro body.
Example:
foo .macro par1,par2
.if .blank par1 == .false
Phyton
MCA-51
Chapter 5. Arithmetic Expressions
44
.dcb par1
.else
.dcb 0
.endif
.if .blank par2 == .false
.dcb par2
.else
.dcb 0
.endif
.endmac
.rseg RC,code
foo 1,2
foo ,2
foo
;will be expanded to:
;.dcb 1
;.dcb 2
;will be expanded to:
;.dcb 0
;.dcb 2
;will be expanded to:
;.dcb 0
;.dcb 0
.end
5.17. .PARM Operator
Syntax:
.PARM expression
This operator can be used only within macros. It returns the text of actual argument specified in the position number "expression" of a macro call. If such
parameter is not specified, .PARM operator returns nothing.
MCA-51
Phyton
Chapter 5. Arithmetic Expressions
45
The expression should be of absolute type and should not contain forward references. .PARM 1 returns the first parameter, .PARM 2 returns the second parameter etc.; .PARM 0 returns a name of the macro.
Example:
...
clear .MACRO
@parm_no = .NPARMS
.REPT @parm_no
clr .PARM @parm_no
@parm_no = @parm_no - 1
.ENDMAC
.ENDMAC
...
.rseg RC,code
clear foo,zoo,boo
...
.end
;
;define temporary local name
;initiate repeat block
;use .PARM
;decrement temporary variable
;
;
;
;
;example of the use of macro
;
;
Generated code:
clr boo
clr zoo
clr foo
;note the sequence:
boo, zoo, foo
;
5.18. "Period" (.) Operator
"." (period) operator calculates the value of the bit address. Expression with allocation = bdata or sfrs (that is, a byte that can be addressed bit by bit), and operand type = BYTE, should be on the left of ".". Absolute-type expression without
forward references, with the value between 0 and 7 (number of bit in the byte)
should be on the right of ".". The result has operand type = BIT and allocation =
bit.
Note!
"Period" operation can not be used anywhere except for Assembler instructions.
Phyton
MCA-51
Chapter 5. Arithmetic Expressions
46
Note!
No operations can be applied to the "period" operation result.
Note!
Only those special function registers can be addressed bit by bit, the
addresses of which are divisible by 8 without remainder.
Example:
.extrnb (bdata) RG
.rseg RCODE,code
clr RG.1
clr RG.(1+1)
clr (RG+1).(1+1)
clr (RG.1)+1
RG1 .equ RG.1
;external bit-addressable variable
;
;OK
;OK
;OK
;error
;error
5.19. .RBANK Variable
Syntax:
.RBANK
This variable returns the value equal to the number of the working register bank
that was previously specified in the module in the .USING directive. It returns 0,
if there has been no .USING directive yet.
5.20. .AR0...7 Variables
Syntax:
.ARn
(n is a register number: 0,1,2,3,4,5,6 or 7)
.AR0...7 variables have the values that can be used as direct addresses for the
access to registers R0...7 of the current bank through direct addressing. It is
required for executing PUSH/POP .ARn instruction (there is no PUSH/POP Rn
instruction in MCS-51). Current bank is the bank that was selected with the
.USING directive in the earlier text (or bank 0 if there has been no .USING
directive).
These variables return the following value (with the following attributes):
MCA-51
Phyton
Chapter 5. Arithmetic Expressions
47
value
8 * current_bank + register number
Optype
BYTE
Allocation
data
Type
undefined type
5.20.1. .USING
.USING <bank_number>
This directive indicates to the Assembler that it is intended to use the working
registers bank under the number of <bank_number> further on in the program
text. Bank number should be an absolute expression without any forward references within the range from 0 to 3.
Built-in variable .RBANK assumes the value of bank_number. Built-in names
.AR0-.AR7 assume the values that will allow to use them as direct addresses for
the access to the R0-R7 registers of specified bank through direct addressing.
First access to the Rn register (in instruction) or built-in name .ARn (anywhere)
after the .USING rb directive results in the generation of the directive:
.LNKCMD '-K data(start-end)'
where: start = 8*rb; end = 8*rb+7.
Thus a space for register banks is reserved in built-in data memory.
Note!
If you switch working register banks, you should apply the .USING
directive so that the Assembler might reserve built-in data memory area,
otherwise register bank might overlay other data, and the program will
be operating incorrectly.
Bank number 0 is used by default (DATA 000H...007H). Any use of Rn or .ARn
before .USING results in reserving [0...7] address area.
Phyton
MCA-51
Chapter 5. Arithmetic Expressions
48
Note!
Directive .USING does not switch register banks itself; it only indicates
to the Assembler which register bank is intended to be used further in
the module text. Do not forget to switch register banks after having
changed corresponding bits in the processor PSW.
Example:
.ASEG ABIT,bit
.ORG 0d3h
RS0 .DST
RS1 .DST
.rseg RCODE,code
.using 1
setb RS0
clr RS1
mov A,R0
push .AR0
.using 3
setb RS0
setb RS1
mov A,R0
push .AR0
.end
;
;
;bit 0 of the register bank number
;bit 1 of the register bank number
;
;
;indicates that we want to use bank 1
;switch bank 1
;-";[08h-0fh] area is reserved here
;[08h] location is pushed into stack
;indicates that we want to use bank 3
;switch bank 3
;-";[18h-1fh] area is reserved here
;[18h] location is pushed into stack
See also:
.RBANK Variable
.AR0...7 Variables
5.19.“.RBANK Variable” on pag e46.
MCA-51
Phyton
Chapter 5. Arithmetic Expressions
49
5.21. .MODEL Variable
Syntax:
.MODEL
Returns the value depending on processor type specified in the -C option of the
Assembler. In combination with conditional assembling, this variable can be
used for the generation of various code options depending on processor types.
51
0
5.22. .NPARMS Variable
Syntax:
.NPARMS
This variable can be used within macro definitions only. It returns the number of
actual arguments specified in a macro call. Omitted parameters are also taken
into consideration: in fact, this operator returns the number of commas (,) in a
macro call line plus 1.
Example:
foo .macro p1,p2
.if .nparms > 0
.dcb p1
.endif
.if .nparms > 1
.dcb p2
.endif
.endmac
.rseg RC,code
foo 1,2
Phyton
;expands to:
;.dcb 1
MCA-51
Chapter 5. Arithmetic Expressions
50
foo 1
foo
foo ,1
;.dcb 2
;expands to:
;.dcb 1
;expands to nothing
;
;expands to:
;.dcb- error!
;.dcb 1
.end
5.23. List of Operators in Order of Priority
Operator
Description
Priority
()
brackets
0 (the highest)
.
computes bit address X
value of .MODEL
returns the number of
a current register bank
returns address of the
R0...R7 register
changes a number sign
operand inversion
high word extraction
low word extraction
high byte of low word's
extraction
low byte extraction
low byte of high word's
1
.RBANK
.AR0...7
.NOT
.HWRD
.LWRD
.HIGH
.LOW
.BYTE3
see comments
1
1
1
1
1
1
1
1
1
1."Period" operation can not be used anywhere except for Assembler instructions. No operations can be applied to the "period" operation result.
MCA-51
Phyton
Chapter 5. Arithmetic Expressions
.SFB
.SFE
.DATE
.WORD
.BYTE
.DWORD
.UNTYPED
.DEFINED
.MODEL
.BLANK
.NPARMS
.PARM
*
/
.MOD
.IDIV
Phyton
extraction
returns start address of a
segment
returns end address of a
segment
returns current date
changes operand type for
WORD
changes operand type for
BYTE
changes operand type for
DWORD
changes operand type for
UNTYPED
returns 0, if the name is
defined
returns the number of
memory model
returns 0, if macro
parameter is not specified
returns number of macro's
parameters
returns the text of actual
argument
unsigned multiplication
unsigned division
unsigned remainder
selection
signed division
51
1
1
1
1
1
1
1
1
1
1
1
1
2
2
2
2
MCA-51
Chapter 5. Arithmetic Expressions
52
.IMOD
.SHL
.SHR
.SHRL
+
& .AND
| .OR
^ .XOR
< .LT
<= .LE
> .GT
>= .GE
.ULT
.UGT
== .EQ
<> .NE
.ALLOCATION
.OPTYPE
.TYPE
signed remainder selection
left shift
arithmetic right shift
logical right shift
addition
subtraction
bit logical "AND
bit logical "OR
bit logical "XOR
signed LESS THAN
signed LESS THAN OR
EQUAL
signed GREATER THAN
signed GREATER THAN
OR EQUAL
unsigned LESS THAN
unsigned GREATER THAN
EQUAL
NOT EQUAL
returns operand allocation
returns operand type of
the operand
returns type of operand
2
2
2
2
3
3
"4
"5
"5
6
6
7
7
7
7
7
7
8
8
8
5.24. Predefined Assembler Constants
.TRUE
.FALSE
.CHAR
.UCHAR
.INT
.UINT
MCA-51
-1 (0FFFFFFFFH)
0
4
5
8
9
Phyton
Chapter 5. Arithmetic Expressions
.LONG
.ULONG
.FLOAT
Phyton
53
10
11
12
MCA-51
54
MCA-51
Chapter 5. Arithmetic Expressions
Phyton
Chapter 6. Assembler Directives
55
Chapter 6. Assembler Directives
.PMODULE, .LMODULEBegins a program/library module.
.ENDMOD, .END
Ends a module.
.INCLUDE
Includes a file in a source file.
.ASEG, .RSEG
Selects/declares a n absolute/relocatable segment.
.FUNC/ENDF
Defines a subroutine.
.DEFINE
Defines a name for all modules in the file.
.EQU, .SET, =
Defines a name for current module.
.LABELx
Defines a typed label.
.DSx
Defines a typed variable.
.DCx
Initializes memory with typed data.
.PUBLIC
Defines a public name.
.EXTRNx
Declares a typed external name.
.EXTRNF
Declares an external subroutine.
.USING
Specifies what register bank is used.
.LNKCMD
Passes parameters to the Linker.
.WARNING,.ERROR,
.MESSAGE
Displays messages on the console.
.ORG
Sets program counter.
.ALIGN
Aligns program counter.
.BYTE,.BIT
Assigns operand type to an untyped name.
.TYPE
Assigns type to an untyped name.
.EXTRN
Declares an external untyped name.
.LMODULE2
Starts a low-priority library module.
.DS
Reserves specified number of bytes.
.DB1
Initializes memory (1 byte step).
.DB2/.DB4
Initializes memory (2/4 byte step).
.OBJREC
Direct output of data into an object file.
Phyton
MCA-51
Chapter 6. Assembler Directives
56
6.1. .LSTOUT
.LSTOUT unconditionally disables listing generation.
.LSTOUT +
unconditionally enables listing generation.
.LSTOUT .
enables listing generation, if -l option was specified.
In order not to include some fragment of the source text into the listing, use
.LSTOUT - to disable listing generation, and use .LSTOUT . to restore the mode
specified in the command line.
.LSTOUT + enables unconditional listing generation. Listing file has the same
name as the source file and extension .LST.
See also: 3.7.“-l : to generate listing” on page 21.
6.2. .LSTCND
.LSTCND .LSTCND +
.LSTCND .
unconditionally disables.
unconditionally enables.
enables if -c option was specified (default).
This command controls the inclusion of the false conditionals into a listing file. If
a listing file is not generated, those lines will not be included in the listing anyway.
6.3. .LSTMAC
.LSTMAC .LSTMAC +
.LSTMAC .
unconditionally disables.
unconditionally enables.
enables if -g option was specified (default) .
This command controls the including of macro definitions source text into listing. If the listing is not generated, macro definitions text will not be included in
the listing anyway.
6.4. .LSTEXP
.LSTEXP .LSTEXP +
MCA-51
unconditionally disables.
unconditionally enables.
Phyton
Chapter 6. Assembler Directives
.LSTEXP .
57
enables, if -e option was specified (default).
This command controls the including of macro expansions into listing. False conditionals placed within macro expansions, will be included in the listing only if
the inclusion of macro expansions into listing is enabled and, at the same time,
the inclusion of false conditionals into listing is also enabled by -c option or
.LSTCND command.
If listing is not generated, macro expansions text will not be included in the listing anyway.
6.5. .LSTXRF
.LSTXRF .LSTXRF +
.LSTXRF .
unconditionally disables.
unconditionally enables.
enables, if -x option was specified (default).
This command controls cross-reference table listing generation. We would recommend to use this command, for example, when source file contains several
modules. Then you can enable cross-reference table listing generation for some
modules and disable it for other modules.
6.6. .LSTWID
.LSTWID .LSTWID +
.LSTWID .
unconditionally disables.
unconditionally enables.
enables, if -w option was specified (default).
This command controls "wide" listing generation. Additional column is included
in "wide" listing. Status of include-files nesting is shown in this column.
6.7. .TITL
.TITL 'string'
Specifies the 'string' (title) to be printed out on the top of every listing page.
Example:
.TITL 'CONTROL SYSTEM ONE'
Phyton
MCA-51
Chapter 6. Assembler Directives
58
6.8. .STITL
.STITL 'string'
Specifies the 'string' to be printed out as subtitle on every listing page.
Example:
.STITL 'Keyboard service routines'
6.9. .PAGE
.PAGE
This command starts a new page of the listing.
6.10. .INCLUDE
.INCLUDE ‘[Path\]File_Name’
Includes the contents of the File_Name file into the source text immediately after
this directive. Quotation marks are required. The file included by the .INCLUDE
directive may also contain .INCLUDE directives. If the path is not specified, the
Assembler will search for the file in current catalog as well as in the catalogs
specified in the -I option.
6.11. .LMODULE, .PMODULE
.LMODULE Module_Name
.PMODULE Module_Name
Declares the beginning of module. Module_Name specifies module name under
which the module will be placed in the object file; this name should be unique
within a program. The length of module name should not exceed 255 symbols.
.LMODULE defines a library module that will be included in the program only
if there are external references to this module.
.PMODULE defines a program module that is, unlike a library module, always
included in the program.
MCA-51
Phyton
Chapter 6. Assembler Directives
59
Scope and accessibility of non-public identifiers and labels defined in the module
is limited to the module.
If the file contains the source text of one module only and there are no .LMODULE, .PMODULE directives, then one program module will be generated as a
result of compilation. This module will have the same name as the source file
(path and extension are omitted).
6.12. .LMODULE2
.LMODULE2 Module_Name
Declares the beginning of a low-priority library module. In other respects, this
directive is similar to the .LMODULE directive.
Low-priority library modules are scanned by the Linker after scanning standard
library modules. Hence, a low-priority library module is included in the program
only if there are such external references in the program that can not be resolved
by means of standard library modules.
6.13. .ENDMOD, .END
.ENDMOD
This directive indicated the end of module. Every module, except the last one in
the file, should be ended with this directive.
.END
This directive indicates both the end of module and the end of the source file.
Last module in the file should be ended with this directive.
If the file contains the source text of one module only and there are no .LMODULE, .PMODULE directives, .END directive is required anyway.
6.14. .PUBLIC
.PUBLIC Name [,Name] ...
Declares names as public ones, that is, as accessible for external references from
other modules. Such names should be defined in current module. Macro names,
Phyton
MCA-51
Chapter 6. Assembler Directives
60
module names, reserved words and symbols declared as external, can not be
defined as public ones.
6.15. .EXTRN
.EXTRN (allocation) name [,name]...
This directive declares a name as external. This name should be declared as a
public one in some other module, otherwise an error will occur while linking.
This directive is normally used for the definition of external code labels. As there
is a special .EXTRNF directive available for declaring external subroutines, it is
assumed, that the .EXTRN directive will be used rarely.
Allocation attribute should be specified, therefore, this directive cannot be used
for declaring the external name which is just a number.
This directive does not assign any attributes to external names, except allocation,
therefore we would not recommend to use it for declaring data.
The Linker checks whether attributes of external names correspond to attributes
of the appropriate public names. Therefore, when external name is declared in
such a way, it might be necessary to specify appropriate attributes by means of
the .TYPE, .BYTE, .WORD, .DWORD directives.
For example, variable RAT is declared in a certain program module:
...
.RSEG DC,data
...
RAT .DSB 1
.PUBLIC RAT
...
;data, BYTE, unsigned char
;declare a name as public
Then to get access to this variable from the other module, this name should be
declared as external and the appropriate types should be specified:
MCA-51
Phyton
Chapter 6. Assembler Directives
...
.EXTRN (data)RAT
data
.BYTE RAT
.TYPE RAT(.uchar)
...
61
;RAT was declared in the segment with allocation
;operand type BYTE is declared
;type unsigned char is declared
Note that the .EXTRNx directives declare external names with the appropriate
operand types and types, so that, if these directives are used, the last fragment of
the program can be replaced by:
...
.EXTRNB (data)RAT
...
6.16. .ASEG, .RSEG
{ .ASEG | .RSEG } Segment_name [,allocation ]
.ASEG directive manipulates absolute segments, and .RSEG directive manipulates relocatable segments.
If the Segment_name is not yet declared in the module, the directive declares a
new segment and switches the Assembler to it. Allocation attribute should be
specified.
If the Segment_name segment is already declared, you need not specify allocation (note, that if it is still specified, it should be the same as in the segment declaration). In such a case, this directive just switches the Assembler to an
appropriate segment.
.RSEG directives can not be used for the declaration of segments with the sfrs
allocation attribute.
If some segment is used in different modules, the declaration of this segment
should be the same in all those modules.
6.17. .LNKCMD
.LNKCMD 'command_line_parameters_for_linker'
Phyton
MCA-51
Chapter 6. Assembler Directives
62
This directive is used for specifying some options for the Linker right in the
source assembly file. If a module containing this directive was linked to the program, everything within quotation marks is passed to the Linker as command line
parameters. Only -A, -S and -N options can be used.
For additional information refer to sections:
-A Option: Address Area Definition,
-S Option: Segment Allocation,
-K Option: Disables Allocation of Relocatable Segments.
6.18. .ORG
.ORG Expression
Sets the value of the current segment program counter equal to the value of
expression. Expression should not contain forward references. Relocatability of
the expression should be the same as the segment type, that is, the expression
should be absolute in the absolute segment, and should be relocatable in the relocatable segment. For example, .ORG $+5.
Part extraction operators (.HWRD, .LWRD etc.) can not be used in expressions.
6.19. .DEFINE, .EQU, .SET, =
Name .DEFINE Expression
Name .EQU Expression
Name .SET Expression
Name = Expression
Defines a name and assigns the value of the expression to it. The name declared
by the .DEFINE directive keeps its value through all the following modules of
the source file, while the scope of the name defined by the .EQU directive is
within the current module only. Expression in the .DEFINE directive should be
of the ABS type. Unlike the .EQU and .DEFINE directives, values assigned to
names by means of the .SET or = directives may be redefined in the current module by using the same directives.
MCA-51
Phyton
Chapter 6. Assembler Directives
63
All types of declared name are acquired from the expression.
6.20. .DS
[Name] .DS Expression
Reserves the number of bytes in the object file specified by the expression, without assigning specific values to them. The expression should be of an absolute
type and should not contain any forward references.
This directive is used for the memory reservation only (for example, for a variable in RAM); it does not generate any code and just increments program counter
value.
Directive .DS can be used in any segments, except those that have bit or code
allocation.
If a name is specified, the following attributes are assigned to it:
value
allocation
operand type
type
relocatability
Note!
- current value of the Assembler program counter,
- allocation of current segment,
- UNTYPED,
- nothing,
- relocatability of current segment.
In order to reserve space for a variable and assign an operand type (as
well as the "type" attribute) to the variable, it would be better to use
the .DSx directives.
Also see:
6.21.“.DSB, .DSW, .DSD, .DSC, .DSI, .DSL, .DSR, .DST” on pag e64.
Phyton
MCA-51
Chapter 6. Assembler Directives
64
6.21. .DSB, .DSW, .DSD, .DSC, .DSI, .DSL,
.DSR, .DST
name .DSB [expression]
name .DSW [expression]
name .DSD [expression]
name .DSC [expression]
name .DSI [expression]
name .DSL [expression]
name .DSR [expression]
name .DST [expression]
;unsigned value, 8 bits
;unsigned value, 16 bits
;unsigned value, 32 bits
;signed value, 8 bits
;signed value, 16 bits
;signed value, 32 bits
;floating-point value, 32 bits
;bit value
This is a group of directives for the definition of variables and arrays of specified
type (memory reservation without initialization). A name is assigned to the variable. If the expression is not specified or is equal to 1, then one variable is
defined. If the expression is greater than 1, then an array of expression variables
of specified size/type is defined. Expression should be of the absolute type and
should not contain any forward references.
Directive .DST can be used only in the segments that have a bit allocation
attribute. The rest of directives can be used in any segments, except those having
bit allocation.
The following attribute are assigned to the name:
value
allocation
relocatability
- current value of the Assembler
program counter, alignment considered
- allocation of current segment
- relocatability of current segment
operand type, type and alignment:
MCA-51
directive
operand type
type
.DSB
.DSW
.DSD
.DSC
BYTE
BYTE
BYTE
BYTE
unsigned char
unsigned int
unsigned long
char
Phyton
Chapter 6. Assembler Directives
.DSI
.DSL
.DSR
.DST
BYTE
BYTE
BYTE
BIT
65
int
long
float
nothing
6.22. .DB1
[Name] .DB1 Expression_Or_String [,Expression_Or_String] ...
Reserves required number of bytes in the object file and assigns values to them.
This directive can be used, for example, for generating byte tables in ROM.
The expression can be absolute or relocatable, but it should be within the range
from -128 to 255. For relocatable expressions, the check of the value range is performed at the linking stage. If a string is specified, then every symbol of the
string initializes one byte of memory. String length may exceed 4 symbols.
If a name is specified, the following attributes are assigned to it:
value
allocation
operand type
type
relocatability
- current value of the Assembler program counter,
- allocation of current segment,
- UNTYPED,
- nothing,
- relocatability of current segment.
It should be noted that operand type should be assigned to the name. It would
also be advisable to assign the type to the name. It can be done by means of separate directives; however, it would be easier to do it by means of the .DCB and
.DCC directives.
Directive .DB1 can be used only in the segments that have xdata or code allocation attribute.
Phyton
MCA-51
Chapter 6. Assembler Directives
66
6.23. .DB2, .DB4
[Name] .DB2 Expression [,Expression] ...
[Name] .DB4 Expression [,Expression] ...
Defines 2-byte or 4-byte data and assigns values to it.
Expression in the .DB2 directive can be absolute or relocatable, but it should be
within the range from -32768 to 65535.
Expression in the .DB4 directive can be absolute or relocatable, but its value
should be within the range from -2147483647 to 4294967295. A floating-point
number can be used as an expression.
For relocatable expressions the check of value range is performed at the linking
stage.
If a name is specified, the following attributes are assigned to it:
value
allocation
operand type
type
relocatability
Note!
- current value of the Assembler program counter,
- allocation of current segment,
- UNTYPED,
- nothing,
- relocatability of current segment.
Operand type should be assigned to the name. Also, it would be advisable to assign the type to the name. It can be done by means of separate directives; however, it would be easier to do it by means of the
.DCW, .DCI, .DCD, .DCL, .DCR directives.
Directives .DB2 and .DB4 can be used only in the segments that have xdata or
code allocation attribute.
MCA-51
Phyton
Chapter 6. Assembler Directives
67
6.24. .DCB, .DCW, .DCD, .DCC, .DCI, .DCL,
.DCR
[name] .DCB expr_or_string [,expr_or_string] ...
[name] .DCW expression [,expression] ...
[name] .DCD expression [,expression] ...
[name] .DCC expr_or_string [,expr_or_string] ...
[name] .DCI expression [,expression] ...
[name] .DCL expression [,expression] ...
[name] .DCR expression [,expression] ...
These directives can be used only in the segments that have xdata or code allocation attribute.
This is a group of directives normally used for the declaration of tables in ROM
(memory reservation with initialization). Each of these directives specifies
required data alignment, operand type and type attributes for the Name. The
name is an optional parameter.
Not only expressions but also character strings can be specified in the .DCB and
.DCC directives. The .DCR directive assigns the "float" type to the Name, therefore it is expected (though not checked by the Assembler) that a floating-point
number will be entered as Expression.
Maximum and minimum value of the Expression depend on reserved memory
location size:
Directive
Value Range
.DCB, .DCC
.DCW, .DCI
.DCD, .DCL, .DCR
-128...255
-32768...65535
-2147483647...4294967295
For relocatable expression the value range is checked at the linking stage.
The following value and attributes are assigned to the name:
value
Phyton
- current value of the Assembler program counter,
MCA-51
Chapter 6. Assembler Directives
68
allocation
relocatability
- allocation of current segment,
- relocatability of current segment.
operand type and type:
directive
operand type
type
.DCB
.DCW
.DCD
.DCC
.DCI
.DCL
.DCR
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
unsigned char
unsigned int
unsigned long
char
int
long
float
6.25. .BYTE, .BIT
.BYTE name [,name] ...
.BIT name [,name] ...
These directives specify operand type for a name. Operand type should be
defined only once. Operand type is set automatically for the names defined by the
.DCx, .DSx, .LABELx, .EXTRNx directives.
Example:
.rseg RD,data
NAME1: .DS 2
NAME2: .DS 2
.BYTE NAME1
.rseg RC,code
mov A,NAME1
mov A,NAME1+1
mov A,NAME2
mov A,NAME2+1
MCA-51
;
;defines NAME1 with operand type UNTYPED
;defines NAME2 with operand type UNTYPED
;assigns operand type == BYTE to NAME1
;
;OK
;OK
;warning
;warning
Phyton
Chapter 6. Assembler Directives
.end
69
;
6.26. .WARNING, .ERROR, .MESSAGE
.WARNING 'string'
.ERROR 'string'
.MESSAGE 'string'
Having encountered this directive, the Assembler issues a 'string' message with
appropriate caption, file name and line number. Message numbers are fixed: message 1 is for the .ERROR directive and message 2 is for the .WARNING directive.
Example:
.WARNING 'Might be a problem...'
.ERROR 'Invalid macro call!'
.MESSAGE 'Complete.'
Display on the console:
Warning[2] filename.ext(1,0): Might be a problem...
Error[1] filename.ext(2,0): Invalid macro call!
Message from filename.ext(3,0): Complete.
6.27. .ALIGN
.ALIGN expression
Expression should be of absolute type and should not contain any forward references.
This directive produces the alignment of the current program counter on boundary of 2 to the expression power:
0 - no alignment,
1 - alignment on even addresses,
2 - alignment on the address divisible by 4,
etc.
Phyton
MCA-51
Chapter 6. Assembler Directives
70
For absolute segments the correctness of the alignment produced by the .ALIGN
directive is checked up by the Assembler.
The Linker automatically adjusts start address of every relocatable segment so
that the alignment is maintained for all of the .ALIGN directives contained in
this segment.
After the segments are linked, the Linker checks the alignment specified by
the.ALIGN directives; if misalignment is detected, the Linker issues an appropriate error message. Therefore, the .ALIGN directive provides 100% guarantee for
obtaining the required alignment.
6.28. .TYPE
.TYPE name(expression) [,name(expression)] ...
Expression value is associated with a name as the type attribute; expression
should be of the absolute type and should not contain any forward references. It
is recommended to use predefined constants.
The type set by the .TYPE directive is used for the generation of the source-level
debugging information and for the check of intermodular links (the Linker
checks whether external names' types match public names' types).
It should be noted that normally this directive is not required, as the names
defined with the basic set of the Assembler directives already have appropriately
assigned type attributes.
See also:
2.6.4.“The "Type" Attribute of a Name” on page15.
6.29. .FUNC, .ENDF
.FUNC func_name . . . (subroutine body) . . . .ENDF
.FUNC directive is used for declaring a subroutine. The directive declares
func_name with the following attributes:
MCA-51
Phyton
Chapter 6. Assembler Directives
value:
operand type:
type:
relocatability:
allocation:
71
current value of the Assembler program counter,
UNTYPED,
<subroutine>,
the same as the segment's,
code.
Directive .FUNC can be used only in the segments that have code allocation
attribute.
It is recommended to use .FUNC/.ENDF for the declaration of subroutines.
Local labels (identifiers starting with an underscore) can be used within subroutines declared by these directives. Upon the program exit, local labels are cancelled and can be used in other subroutines, which makes it unnecessary to invent
long unique names for the local labels of subroutines. Another advantage of
using .FUNC/.ENDF is a possibility to use productivity analyzer during debugging.
.ENDF should be in the same segment as the previous .FUNC. Current segment
address (about the segment fragment beginning) should be greater than the function entry point address. Directive .FUNC can not be used between .FUNC and
.ENDF.
Local names in functions are non-external names defined within functions and
starting with underscores.
Such names:
- are cancelled after .ENDF,
- are not included in debug information,
- can not be declared as public names.
If a name starts with an underscore but was defined before the beginning of function, it is not changed upon the function exit (not cancelled). This name is visible
within the function.
An external name starting with an underscore can be declared within a function.
This name will not be cancelled after .ENDF and will be included in debug information.
Example:
.rseg RD,data
Phyton
;switch to data segment
MCA-51
Chapter 6. Assembler Directives
72
_XVAR .dsb
;a variable is declared in the data segment
;is NOT local because
;it is not within any
;function.
.rseg RC,code
;switch to code segment
.FUNC MY_SUBROUTINE;open the function
clr A
;
mov _var,#33
;_var is a local variable
mov _XVAR,_var
;_XVAR is a normal variable
jb _var.7,_1
;_1 is a local label
mov A,#0ffh
;
_1: ret
;declaration of the local label _1
.rseg BC,bdata
;switch to the bdata-type segment
_var .dsb
;a local (within the function) variable is declared
.rseg RC
;return to the code segment
.ENDF
;the function is closed
.end
;
6.30. .OBJREC
.OBJREC Expression [,Expression] ...
Normally this directive is not needed. It may be used for various tricks. To use
this directive, one should know the format of relocatable object files perfectly
well in order not to damage the Assembler output file .
This directive writes the sequence of bytes defined by the expressions directly to
the object file. The expressions should be of the absolute type and should range
in value from -128 to 255.
6.31. .LABELB, LABELW, LABELD, LABELC,
LABELI, LABELL, LABELR, LABELT
Name .LABELB
Name .LABELW
MCA-51
;unsigned value, 8 bits
;unsigned value, 16 bits
Phyton
Chapter 6. Assembler Directives
Name .LABELD
Name .LABELC
Name .LABELI
Name .LABELL
Name .LABELR
Name .LABELT
73
;unsigned value, 32 bits
;signed value, 8 bits
;signed value, 16 bits
;signed value, 32 bits
;floating-point value, 32 bits
;bit value
This group of directives is used for defining labels. It is normally used for declaring start address of some data area. Operand type and type attributes are assigned
to the label. The Assembler program counter does not change.
Directive .LABELT can be used only in the segments that have bit allocation
attribute. Other directives can be used in any segments, except those that have bit
allocation.
Note that the structure of the following form:
name: . . .
also declares a label though it is not typed; we would recommend to use such
labels only as jump addresses within subroutines.
The following attributes are specified for the label:
value
allocation
relocatability
- current value of the Assembler program counter,
- allocation of current segment,
- relocatability of current segment.
operand type and type:
Phyton
Directive
Operand type
Type
.LABELB
.LABELW
.LABELD
.LABELC
.LABELI
BYTE
BYTE
BYTE
BYTE
BYTE
unsigned char
unsigned int
unsigned long
char
int
MCA-51
Chapter 6. Assembler Directives
74
.LABELL
.LABELR
.LABELT
BYTE
BYTE
BIT
long
float
nothing
Examples:
...
.rseg TABLES,code
MyTable .labelw
.dcb 22,44,77,88
.dcb 66,33,55,99
...
.rseg RD,data
MyVar .labelw
MyVarLo .dsb
MyVarHi .dsb
...
;defines table in ROM:
;opens segment to be ROMed
;sets appropriate label
;...table contents...
;...table contents...
;defines overlapped variables:
;opens data segment
;sets word label
;defines storage for low byte
;defines storage for high byte
6.32. .EXTRNB, .EXTRNW, .EXTRND, .EXTRNC,
.EXTRNI, .EXTRNR, .EXTRNT, .EXTRNN
.EXTRNB (allocation) name [,name] ...
.EXTRNW (allocation) name [,name] ...
.EXTRND (allocation) name [,name] ...
.EXTRNC (allocation) name [,name] ...
.EXTRNI (allocation) name [,name] ...
.EXTRNL (allocation) name [,name] ...
.EXTRNR (allocation) name [,name] ...
.EXTRNT name [,name] ...
.EXTRNN name [,name] ...
MCA-51
Phyton
Chapter 6. Assembler Directives
75
This group of directives is used for the declaration of completely typed external
names. The .EXTRNN directive is used for the declaration of external names
without allocation attribute (that is, numbers). The .EXTRNT directive is used
for the declaration of external bit variables (allocation==bit). Other directives can
be used for the declaration of external names of variables, arrays, tables etc.
Note!
It is recommended to use the .EXTRNF directive for the declaration of
external names which are subroutines' addresses.
The following attributes are assigned to declared external name:
value
allocation
relocatability
- external, to be refined by the Linker,
- allocation, specified in the directive,
- EXT.
operand type and type:
Directive
Operand type
Type
.EXTRNB
.EXTRNW
.EXTRND
.EXTRNC
.EXTRNI
.EXTRNL
.EXTRNR
.EXTRNT
.EXTRNN
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BIT
UNTYPED
unsigned char
unsigned int
unsigned long
char
int
long
float
nothing
nothing
6.33. .EXTRNF
.EXTRNF func_name
Phyton
MCA-51
Chapter 6. Assembler Directives
76
The .EXTRNF directive is intended for the declaration of the Assembler external
subroutines (specified in other modules by .FUNC/.ENDF). The directive
declares a func_name with the following attributes:
operand type:
type:
relocatability:
allocation:
value :
UNTYPED,
<subroutine>,
EXT,
code,
<is not determined before linking>.
Example:
;
;suppose MY_SUB is an external subroutine
;
.EXTRNF MY_SUB ;the subroutine is declared
...
...
;
;the use of external subroutine:
.rseg RC,code
...
...
lcall MY_SUB
;function call
...
...
.end
.USING
For detailed description, see:
5.20.1.“.USING” on page47.
MCA-51
Phyton
Chapter 7. Listing controls
77
Chapter 7. Listing controls
.LSTOUT
.LSTCND
.LSTMAC
.LSTEXP
.LSTXRF
.LSTWID
.TITL
.STITL
.PAGE
Phyton
Controls listing output.
Controls output of false conditionals.
Controls output of macro definitions.
Controls output of macro expansions.
Controls output of cross-reference.
Enables "wide" format of listing.
Specifies a title.
Specifies a subtitle.
Inserts page break.
MCA-51
78
MCA-51
Chapter 7. Listing controls
Phyton
Chapter 8. Macrotools, retry blocks and conditional assembling
79
Chapter 8. Macrotools, retry blocks and
conditional assembling
8.1. Macros: Purpose & Function
Macros are special means for the development and use of the source text "patterns" that allow parameter substitution.
When writing programs you will notice quite often that very similar sequences of
instructions are repeated several times, and the difference between them is very
slight (for example, only operands are different).
For example, when writing a program, you have to make a subroutine that copies
5 bytes from one memory location to another. Later you may realize that you are
writing the similar code, but for copying 4 bytes. If both subroutines operate in a
similar way, you will see that they are nearly identical with the exception of three
parameters: number of bytes and two memory addresses. In many cases, creating
such a code by means of macros appears to be more convenient than writing similar subroutines several times.
Advantages provided by macros:
• as you have to type shorter text, the probability of making errors is reduced,
• scope of name and labels that are used only within a macro can be limited so
that they are "visible" to the Assembler within a macro only. Therefore,
when writing a program you do not have to worry about these names being
unique, Macro written in such a way can be used any number of times, and
"internal" (local) names of the macro will not be duplicated,
• if a logical error is detected within a macro, you will have to correct it only
once in contrast to the situation, when you have to scan the whole source
program text in order to find similar code fragments and correct the error in
all of them,
• if similar program fragments are developed by means of a macro, it is much
easier to modify those fragments as you have just to modify the macro,
Phyton
MCA-51
80
Chapter 8. Macrotools, retry blocks and conditional assembling
• the efficiency of programmers' work increases as the time is not spent for
duplicating source text. Besides, the most frequently used macros can be
made accessible to other programmers.
Difference between macros and subroutines.
• A subroutine is a part of the program executable code, it can be called from
other parts of the code at the stage of program execution. A macro is defined
in the source program text and if called, it is included into the program
source text at the compilation stage. There can be several macro inclusions.
• When a subroutine is called, the same code is executed every time. Every
time a macro is called, a unique sequence of program lines is formed in
accordance with the pattern specified by the macro definition.
• Every subroutine call increases the time of program execution. If you use a
macro, program execution time is not increased, but the total program size in
increased.
• Strictly speaking, macros are the means of structuring program source text,
while subroutines are the means of structuring executable code.
8.2. Directive .MACRO
name .MACRO [formal_parameters]
Declares the beginning of a macro definition (macro body).
Name is a macro name to be used at the macro calls.
Formal_parameters are symbolic names defined by user. They should be separated by commas and their number should not exceed 33. At the macro extension,
the Assembler will substitute actual parameters for formal parameters. Macro
body is a scope for formal parameters.
Macro body can contain any mnemonics of machine instructions and required
directives, for example, conditional compilation directives. Calls to other macros
can also be included in a macro.
MCA-51
Phyton
Chapter 8. Macrotools, retry blocks and conditional assembling
81
Certain special operators and other special features can be used within macros.
See also:
.BLANK Operator
.PARM Operator
.NPARMS Variable
Declaration of Local Labels in Macros.
Actual Parameters and Text Concatenation in Macros.
8.3. Directive .EXITM
.EXITM
If the .EXITM directive is encountered, a macro extension is immediately terminated. It can be convenient if conditional block is used in the macro body.
.EXITM can be located only within a macro body or within a repeat block.
8.4. Directive .ENDMAC
.ENDMAC
This directive indicates the end of a macro body or a repeat block.
8.5. .REPT Repeat Block
.REPT expression
Number of repeat block body repetitions is equal to expression. The expression
should be absolute and should not contain any forward references. Expression
value range is - 0...65535.
Example:
.rseg CODESEG,code
PARM = 0
.REPT 5
Phyton
MCA-51
Chapter 8. Macrotools, retry blocks and conditional assembling
82
.dcb PARM
PARM = PARM + 1
.ENDMAC
.end
Listing:
1
2 00000000
3
4
5
6
+ 00000000 00
+ 00000001
+ 00000001 01
+ 00000002
+ 00000002 02
+ 00000003
+ 00000003 03
+ 00000004
+ 00000004 04
+ 00000005
7
.rseg CODESEG,code
PARM = 0
.REPT 5
.dcb PARM
PARM = PARM + 1
.ENDMAC
.dcb PARM
PARM = PARM + 1
.dcb PARM
PARM = PARM + 1
.dcb PARM
PARM = PARM + 1
.dcb PARM
PARM = PARM + 1
.dcb PARM
PARM = PARM + 1
.end
Repeat block can not be called by name, unlike a macro declared by the
.MACRO directive; it is expanded in the same place where it is declared.
8.6. .IRP - Repeat Block with Parameter Scanning
.IRP formal_parameter,(actual_arguments)
This directive will repeat a repeat block body once with each of the actual arguments replacing a formal parameter. The number of repetitions is equal to the
MCA-51
Phyton
Chapter 8. Macrotools, retry blocks and conditional assembling
83
number of actual arguments. Actual arguments should be separated by commas,
their number should not exceed 32.
Example:
.rseg CODESEG,code
.IRP PARM,(25,36,47,58,69)
.dcb PARM
.ENDMAC
.end
Listing:
1
2
3
4
+ 00000000 19
+ 00000001 24
+ 00000002 2F
+ 00000003 3A
+ 00000004 45
4
5
.rseg CODESEG,code
.IRP PARM,(25,36,47,58,69)
.dcb PARM
.ENDMAC
.dcb 25
.dcb 36
.dcb 47
.dcb 58
.dcb 69
.ENDMAC
.end
Repeat block can not be called by name, unlike a macro declared by the
.MACRO directive; it is expanded in the same place where it is declared.
8.7. .IRPC - Repeat Block with Scanning a
String-Parameter
.IRPC formal_parameter,'string'
Repetition of the repeat block body with each of the string characters replacing a
formal parameter. Number of repetitions is determined by the number of characters in the string. A specified formal parameter is replaced by a character in quo-
Phyton
MCA-51
Chapter 8. Macrotools, retry blocks and conditional assembling
84
tation marks, that is, by a string containing one character. The length of the string
is practically not limited and may reach 400 characters.
Example:
.rseg CODESEG,code
.IRPC PARM,'HELLO'
.dcb PARM
.ENDMAC
.end
Listing:
1
2
3
4
+ 00000000 48
+ 00000001 45
+ 00000002 4C
+ 00000003 4C
+ 00000004 4F
4
5
.rseg CODESEG,code
.IRPC PARM,'HELLO'
.dcb PARM
.ENDMAC
.dcb 'H'
.dcb 'E'
.dcb 'L'
.dcb 'L'
.dcb 'O'
.ENDMAC
.end
Repeat block can not be called by name, unlike a macro declared by the
.MACRO directive; it is expanded in the same place where it is declared.
8.8. Macro Call and Parameter Substitution
[label:] macro_name [actual_arguments]
Macro_name is a name of a called macro. Actual_arguments are a list of actual
arguments separated by commas. You may specify up to 16 actual arguments.
Label is an optional label defined by user.
MCA-51
Phyton
Chapter 8. Macrotools, retry blocks and conditional assembling
85
Once a macro has been defined, it can be called any number of times in the program. A macro call consists of the macro name and actual parameters. At the
invocation of a macro, the call is replaced with a macro body, and all the formal
parameters are replaced with actual arguments. This process is called macro
expansion.
Macro can be called only within the module where it is defined.
A list of actual arguments should not necessarily correspond to the list of formal
parameters specified in a macro definition. However, the number of actual arguments should be not greater than the number of formal parameters (this limitation
is not applied if .NPARMS or .PARM operator is used in the macro body). In
the macro body the Assembler substitutes actual parameters for all the tokens
corresponding to the formal parameters. If an actual argument is not specified for
some formal parameter, the formal parameter is replaced with a NULL character
(is removed).
When specifying actual arguments in a macro call, you may use some special
features of the Assembler; for more information refer to the sections:
Passing of Actual Parameters by means of the < and > symbol.
Expression-to-Text Conversion at the Macro Call.
Example:
FILLX .MACRO ADDR,DATA,COUNT;macro definition
Mov DPTR,#ADDR ;
Mov A,#DATA
;
Mov R0,#COUNT
;
@loop:
;
movx @DPTR,A
;
inc DPTR
;
djnz R0,@loop
;
.ENDMAC
;
;
.rseg XDATASEG,xdata;array in xdata
MyArrayLen .equ 100;array length is 100
MyArray .dsb MyArrayLen;array definition
Phyton
MCA-51
Chapter 8. Macrotools, retry blocks and conditional assembling
86
;
.rseg CODESEG,code;
FILLX MyArray,55,MyArrayLen;macro call
.end
;
Listing:
1
2
3
4
5
6
7
8
9
10
11
12 00000064
13 00000000
14
15
16 00000000
+ 00000000 900000
+ 00000003 7437
+ 00000005 7864
+ 00000007
+ 00000007 F0
+ 00000008 A3
+ 00000009 D8FC
+
17
MCA-51
FILLX .MACRO ADDR,BYTE,COUNT
mov DPTR,#.byte ADDR
mov A,#BYTE
mov R0,#COUNT
@loop:
movx @DPTR,A
inc DPTR
djnz R0,@loop
.ENDMAC
.rseg XDATASEG,xdata
MyArrayLen .equ 100
MyArray .dsb MyArrayLen
.rseg CODESEG,code
FILLX MyArray,55,MyArrayLen
mov DPTR,#MyArray
mov A,#55
mov R0,#MyArrayLen
@loop:
movx @DPTR,A
inc DPTR
djnz R0,@loop
.end
Phyton
Chapter 8. Macrotools, retry blocks and conditional assembling
87
8.9. Passing of Actual Parameters by means of
the < and > symbol
A name, expression or character string is normally passed as an actual argument.
If it is necessary to pass any parameter that contains separators (for example,
commas or spaces) but is not a character string (that is, not enclosed within single
quotes), then this parameter should be enclosed within angle brackets.
Note!
Passing of actual arguments containing parentheses is impossible even
with the use of the < and > symbols.
When actual argument in angle brackets is passed, one pair of angle brackets is
removed; hence, if this parameter should be passed from within one macro to
another macro, two pairs of angle brackets are required etc.
Example:
CAT .MACRO par1
.dcb par1
.ENDMAC
RAT .MACRO par1,par2
CAT par1
.dcw par2
.ENDMAC
.rseg CODESEG,code
RAT 0,1
RAT <<3+1,4+2>>,<7+8,9+10>
.end
Listing:
1
2
3
Phyton
CAT .MACRO par1
.dcb par1
.ENDMAC
MCA-51
Chapter 8. Macrotools, retry blocks and conditional assembling
88
4
RAT .MACRO par1,par2
5
CAT par1
6
.dcw par2
7
.ENDMAC
8
.rseg CODESEG,code
9 00000000
RAT 0,1
+ 00000000
CAT 0
+ 00000000 00
.dcb 0
+
+ 00000001 0100
.dcw 1
+
10 00000003
RAT <<3+1,4+2>>,<7+8,9+10>
+ 00000003
CAT <3+1,4+2>
+ 00000003 0406
.dcb 3+1,4+2
+
+ 00000005 0F001300.dcw 7+8,9+10
+
11
.end
8.10. Declaration of Local Labels in Macros
If a name defined in a macro definition begins with the "@" symbol, then upon
every macro call it will be unrolled into a unique name. "@name" will be
replaced with "@number@name", where number is a 4-digit hexadecimal ordinal number of a macro call in this source file.
Such names can not be declared as public or external, they can not be segment
names either.
Example:
.extrnb (sfrs) P1
.extrnb (data) foo
wait_p1 .MACRO val
@label:
MCA-51
Phyton
Chapter 8. Macrotools, retry blocks and conditional assembling
89
mov
a,val
cjne
a,P1,@label
.ENDMAC
.rseg CODESEG,code
wait_p1 #33
wait_p1 foo
.end
Listing:
1
.extrnb (sfrs) P1
2
.extrnb (data) foo
3
wait_p1 .MACRO val
4
@label:
5
mov a,val
6
cjne a,P1,@label
7
.ENDMAC
8
.rseg CODESEG,code
9 00000000
wait_p1 #33
+ 00000000
@0001@label:
+ 00000000 7421
mov a,#33
+ 00000002 B500FB cjne a,P1,@0001@label
+
10 00000005
wait_p1 foo
+ 00000005
@0002@label:
+ 00000005 E500 mov a,foo
+ 00000007 B500FB cjne a,P1,@0002@label
+
11
.end
Phyton
MCA-51
Chapter 8. Macrotools, retry blocks and conditional assembling
90
8.11. Actual Parameters and Text Concatenation in Macros
If there is an ampersand (&) symbol to the left (right) of the formal parameter in
a macro definition, the & symbol will be removed at the macro expansion, and
the corresponding (actual) argument will be concatenated to the text preceding
(following) the ampersand.
Spaces and tabulation characters immediately surrounding the & symbol do not
affect concatenation in any way. That is, during the expansion, spaces and tabulation characters are removed together with the & symbol.
In other words, the & symbol applied to a formal parameter in a macro definition,
acts as a special concatenation operation. Note that the & symbol also indicates a
"bitwise AND" operation, so if a bitwise AND operation on a formal parameter is
required within a macro definition, .AND should be used.
Note that concatenation is impossible within character strings. For example, if a
macro definition contains the text:
'&parameter&'
where parameter is a formal parameter name, then at the macro extension everything will remain as it is.
Example:
const_66 .equ 1
CONCAT .macro p1,p2
label_ & p1 & : mov A,# const_ & p2
.endmac
.rseg CODESEG,code
CONCAT 55,66
.end
MCA-51
Phyton
Chapter 8. Macrotools, retry blocks and conditional assembling
91
Listing:
1 00000001
2
3
4
5
6 00000000
+ 00000000 7401
+
7
const_66 .equ 1
CONCAT .macro p1,p2
label_ & p1 & : mov A,# const_ & p2
.endmac
.rseg CODESEG,code
CONCAT 55,66
label_55: mov A,# const_66
.end
Restriction:
Actual arguments can not be concatenated with the text beginning with a
NUMBER:
X .macro Y
mov Y & 2_lo,0
mov Y & _2_lo,0
.endmac
;concatenation will not occur here
;but it will occur here
8.12. Parameter-to-String Conversion
If there is the { symbol on the left of a formal parameter and the } symbol on the
right of the same formal parameter in a macro definition, then while expanding
the { and } symbols are replaced with quotation marks, that is, an actual argument is converted into a string.
Spaces and tabulation characters located between a formal parameter and the {
and } symbols are removed together with these symbols.
Phyton
MCA-51
Chapter 8. Macrotools, retry blocks and conditional assembling
92
Example:
BOO .macro p1
label_ & p1 .dcb 'Actual parameter: ',{p1},0
.endmac
.rseg CODESEG,code
BOO lambada
.end
Listing:
1
BOO .macro p1
2
label_ & p1 .dcb 'Actual parameter: ',{p1},0
3
.endmac
4
.rseg CODESEG,code
5 00000000
BOO lambada
+ 00000000 41637475label_lambada .dcb 'Actual parameter: ','lambada',0
00000004 616C2070
00000008 6172616D
0000000C 65746572
00000010 3A206C61
00000014 6D626164
00000018 6100
+
6
.end
8.13. Expression-to-Text Conversion at the
Macro Call
If, at the macro call, there is a percentage sign % preceding some actual argument, the Assembler will calculate the value of this argument and will use this
value as a substitution for corresponding formal parameter.
MCA-51
Phyton
Chapter 8. Macrotools, retry blocks and conditional assembling
93
Decimal representation is used in substitution, with leading zeros being removed.
The actual argument with which the % sign is used should be an absolute-type
expression containing no forward references.
Example:
MOO .macro p1
label_ & p1: mov
.endmac
.rseg RCODE,code
MOO %66+22
.end
A,#p1
Listing:
1
2
3
4
5 00000000
+ 00000000 7458
+
6
MOO .macro p1
label_ & p1: mov
.endmac
.rseg RCODE,code
MOO %66+22
label_88: mov
A,#p1
A,#88
.end
8.14. Nested Macro Calls and Definitions
When defining a macro, you can provide for a macro call from other macros.
Consequences of this will show at the call of the enclosed macro. Possible number of the nesting levels of such calls is limited only by available memory space.
In addition, repeat blocks and macro definitions can contain repeat blocks. Possible number of the nesting levels of repeat blocks is limited only by available
memory space.
Phyton
MCA-51
94
Chapter 8. Macrotools, retry blocks and conditional assembling
In this version of the Assembler, macro definitions can not be nested into repeat
blocks and macro definitions.
8.15. Purpose & Function of Conditional
Assembling
Directives of conditional assembling provide an opportunity to control the
sequence of assembling at the source text fragments level. The choice of variants
is made in accordance with the results of calculations performed during assembling.
In many cases it appears to be convenient to use conditional assembling within
macros, which makes macros more flexible.
8.16. .IF, .ELSE, .ENDIF - Conditional Assembling Directives
.IF expression .
.ENDIF
.
.
[.ELSE .
.
.]
A fragment between .IF and .ELSE (if .ELSE is used, otherwise up to .ENDIF)
is assembled, if the expression value is not equal to 0. If the expression value is
equal to 0 (.FALSE), then, if .ELSE is used, a fragment between .ELSE and
.ENDIF is assembled.
Expression should be absolute, without any forward references.
Conditional blocks can be nested into each other. Nesting level is limited only by
available working memory space.
MCA-51
Phyton
Chapter 9. MCS-51 architecture specific feature support
95
Chapter 9. MCS-51 architecture
specific feature support
9.1. Support of Various Processors' Instruction
Sets
Different processors of the MCS-51 family have different instruction sets. For
example, the Philips 80C750 processor does not have the MOVX instruction, but
this instruction is included in the 8051 processor instruction set
The Assembler has a special -C option for additional checking and support of the
modularity concept. This option controls the use of instructions in the Assembler.
See also:
3.2.“-Ccpu : to specify processor type” on p age19 to specify processor type.
9.2. 8051 Operands; type check in instructions
When processing instructions, the Assembler checks if attributes of the instruction operands match the instructions. For example, when processing a jump
instruction, the Assembler checks if the operand (jump address) has the code
allocation. Attribute mismatch results in issuing warnings. All such warnings can
be disabled by means of the -a option.
The description of instruction operand types, allowed values of operand type
(optype) and allocation attributes as well as allowed range of operands values is
given below.
Rn, A, DPTR, @Ri, AB, @A+DPTR, @A+PC, @DPTR, C operands
Phyton
MCA-51
Chapter 9. MCS-51 architecture specific feature support
96
These operands are not in fact operands from the Assembler's standpoint, but
they are parts of instruction mnemonics. No type of check is performed for such
operands, for there is no subject for a type check.
Direct Operand
Directly addressable byte-oriented operand.
Allowed values of attributes:
optype
allocation
value
= BYTE;
= data, bdata, sfrs;
= {0...0xFF} (unsigned).
#data8 operand
Immediately addressable 8-bit operand. The use of SFRs' addresses and bits as
such operands does not make any sense because SFRs and bits can not be indirectly addressed (they are directly addressed).
Allowed values of attributes:
optype
allocation
value
= NOT BIT;
= NOT sfr, bit;
= {0...0xFF} (unsigned).
#data16 Operand
Immediately addressable 16-bit operand. It is used in the MOV DPTR,#data16
instruction only. DPTR is used in the following instructions only: MOVX
A,@DPTR; MOVX @DPTR,A; MOVC A,@A+DPTR; INC DPTR; JMP
@A+DPTR. It is worth using only addresses in code and XDATA as such operator.
Allowable values of attributes:
optype
allocation
value
= NOT BIT;
= xdata, code, free;
= {0...0xFFFF} (unsigned).
Addr16 operand
Absolute jump address within 64K.
Allowed value of attributes:
MCA-51
Phyton
Chapter 9. MCS-51 architecture specific feature support
optype
allocation
value
97
= UNTYPED;
= code;
= {0...0xFFFF} (unsigned).
Addr11 operand
Absolute address for the jump within 2K-page.
Allowed values of attributes:
optype
= UNTYPED;
allocation
= code;
value
= (within 2K-page that contains the first byte of the next
instruction) (unsigned).
Rel8 operand
Offset for the -128...+127 byte jump relative to the first byte of the next instruction. In the Assembler, an address (for example, a label), and not an offset, is
used for this operand; the offset is calculated and substituted by the Assembler or
Linker. To use the numbers, you can write the expression in the form of: ($ +
offset), the result will have allocation = code, optype = UNTYPED.
Note!
When generating the code, the Assembler uses its internal variable for
tracing addresses. This variable is called the Assembler program
counter. You can refer to its current value by means of the $ sign. The
value returned by such reference will be equal to the Assembler program counter value before the assembling of the current line. On the
other hand, the rel8 operand is an offset relative to the first byte of the
next instruction. Therefore, the (destination_addresslength_of_current_instruction-$) value is generated for the object code.
If expression ($+offset) is used as an operand, the (offsetlength_of_current_instruction) value is generated for the object code.
Allowed values of attributes:
optype
allocation
Phyton
= UNTYPED;
= code;
MCA-51
Chapter 9. MCS-51 architecture specific feature support
98
value
Note!
= {($+LOCI-128)...($+LOCI+127)} (signed).
LOCI := length_of_current_instruction, is equal to 2 or 3 depending on
instruction.
Bit Operand
Directly addressable bit operand.
Allowed values of attributes:
optype
allocation
value
= BIT,
= bit,
= {0...0xFF} (unsigned).
9.3. Register Banks Support
Register banks are located in the very beginning of the processor's built-in data
memory. The use of some register bank should be followed by the reservation of
corresponding data memory fragment, otherwise the program will be operating
incorrectly. The Assembler can automatically reserve data memory space for register banks.
In addition, it is necessary to provide access to the working registers (R0...R7
registers of the active bank) through direct addressing. Actually, it is required for
the only purpose of using the registers in the PUSH and POP instructions (these
instructions do not support register addressing).
Directive .USING <bank_number> indicates to the Assembler that it is intended
to use working registers bank number <bank_number> further in the program.
Built-in names .AR0....AR7 assume the values that allow to use them as direct
addresses for the access to the R0...R7 registers of specified bank through direct
addressing.
MCA-51
Phyton
Chapter 9. MCS-51 architecture specific feature support
99
In addition, built-in variable .RBANK has the value equal to the current (selected
by the .USING directive) register bank number.
See also:
.USING
.RBANK Variable
.AR0...7
Note!
Variables
The .USING directive does not switch register banks itself; it only indicates to the Assembler which register bank you intend to use further in
the module text. Do not forget to switch register banks after having
changed corresponding bits in the processor PSW.
9.4. Special Function Registers (SFRs) Support
The files containing definitions of SFRs for the most widely used processors, are
supplied along with the Assembler.
To use those files, do the following. Specify the .INCLUDE directive with the
corresponding includefile from the INC subdirectory (it is convenient to use the
Assembler's -I option for this purpose) in those modules where SFRs access is
required.
The following is a list of include-files:
Phyton
Processors
Include-files
Atmel 89C51, Intel 80©31, 8X©51
Philips 80©31, 8X©51, RUS 1816/1830VE31
Atmel 89C52, 89C55, Intel 80©32, 8X©52
Philips 80©32, 8X©52, 89C535, 89C536, 89C538
Siemens C501, C502
Intel 8XC51RA, 8XC51RB, 8XC51RC
Philips 8XC51RA+, 8XC51RB+,
8XC51RC+, 8XC51RD+
reg51.inc
reg51.inc
reg52.inc
reg52.inc
reg52.inc
reg51rx.inc
reg51rx.inc
MCA-51
100
Chapter 9. MCS-51 architecture specific feature support
Intel 8XC51FX, Philips 8XC51FX
Intel 8XC152JX
Intel 8XC51GB
Atmel 89C1051
Atmel 89C2051, 89C4051
Atmel 89S8252, 89S8253
Philips 8XC451
Philips 8XC524, 8XC528
Philips 8XC550
Philips 8XC552, 8XC562
Philips 8XC575, 8XC576
Philips 8XC851
Philips 8XC652, 8XC654
Philips 8XC751, 8XC750
Philips 8XC752
Siemens C511
Siemens C513
Siemens C515, SAB80C515, SAB80C535
Siemens C515A, C535A
Siemens C515C
Siemens C517, SAB80C517, SAB80C537
Siemens C517A, SAB80C517A
Note!
MCA-51
reg51fx.inc
reg152jx.inc
reg51gb.inc
reg1051.inc
reg2051.inc
reg8252.inc
reg451.inc
reg524.inc
reg550.inc
reg552.inc
reg575.inc
reg851.inc
reg652.inc
reg751.inc
reg752.inc
regc511.inc
regc513.inc
regc515.inc
regc515a.inc
regc515c.inc
regc517.inc
regc517a.inc
For the Philips 8XC751 and 8XC751 processors, XDATA bit is defined
under the _XDATA name, because XDATA is a reserved keyword of the
Assembler.
Phyton
Chapter 10. Assembler messages
101
Chapter 10. Assembler messages
10.1. Warning #2 <user-defined warning message>
It is a warning message defined by the user and displayed by the .WARNING
directive.
See also:
.WARNING, .ERROR, .MESSAGE.
10.2. Warning #30 Jump/call to data memory
Warning: the Assembler detected an attempt to execute a jump instruction (or
subroutine call) by the label allocated in data memory and not in code memory.
The MCS-51 processor can not execute a code that is not in code memory, hence,
the use of such operations is ambiguous .
You can disable this warning with the -a option.
Note!
A label (name, identifier) is allocated in data memory if its allocation
attribute is not equal to code.
Example:
.rseg DSEG,data
noo:
.rseg XSEG,xdata
xoo:
.rseg CSEG,code
ljmp xoo
lcall noo
.end
;warning here
;warning here
See also 2.6.6.“Allocation Attribute of a Name” on page17 and 3.6.“-a : to disable instruction operands types check” on pa ge21.
Phyton
MCA-51
Chapter 10. Assembler messages
102
10.3. Warning #53 Operand type mismatch
Operand type of the operand is not the same as the type expected for this instruction. Probably, there is an error in the program.
To suppress such messages, use operand type redefining operators or the -a
option.
For more details refer to the following sections:
2.6.5.“Operand Type Attribute of a Name” on page 16
5.10.“.BYTE, .BIT, .UNTYPED Operators” on page38
3.6.“-a : to disable instruction operands types check” on page21
9.2.“8051 Operands; type check in instructions” on page 95
10.4. Warning #54 Operand type required
An operand with the UNTYPED operand type is specified in the instruction.
There may be a logical error in the program.
It is recommended to explicitly specify operand type by means of some operand
typeredefining operator (.BYTE, .BIT) or to use a TYPED operand instead of an
UNTYPED one.
To suppress such messages, use operand type redefining operators or the -a
option.
For more details refer to the following sections:
2.6.5.“Operand Type Attribute of a Name” on page 16
5.10.“.BYTE, .BIT, .UNTYPED Operators” on page38
3.6.“-a : to disable instruction operands types check” on page21
9.2.“8051 Operands; type check in instructions” on page 95
10.5. Warning #72 Too many warnings
Assembler has displayed too many warnings, which means that the number of
displayed warnings has exceeded the limit specified by the -W option. There will
be no more warnings displayed.
For detailed description, see also:
MCA-51
Phyton
Chapter 10. Assembler messages
103
3.17.“-Wnnn : to display not more than nnn warnings” on page23.
10.6. Warning #84 Operand allocation required
Warning: operand of this instruction is supposed to have allocation attribute, but
it does not have one (that is, it is not allocated in memory and is just a number).
As a rule, this warning indicates a logical error in the program.
This warning can be disabled with the -a option.
Example:
.rseg CSEG,code
ljmp 0200h
.aseg ACSEG,code
.org 0200h
L0200H:
.rseg CSEG
ljmp L0200H
.end
;
;warning here
;getting round this problem...
;
;
;
;OK
;
For more details refer to the following sections:
2.6.6.“Allocation Attribute of a Name” on page17
3.6.“-a : to disable instruction operands types check” on page21
9.2.“8051 Operands; type check in instructions” on page 95
10.7. Warning #85 Bad operand allocation
Warning: operand of this instruction has invalid allocation attribute. For example, a directly addressable operand should have allocation attribute equal to data,
bdata or sfrs, but it has allocation=xdata.
As a rule, this warning indicates a logical error in the program.
This warning can be disabled with the -a option.
Example:
Phyton
MCA-51
Chapter 10. Assembler messages
104
.extrnb (xdata)xvar
.extrnb (data)dvar
.extrnb (sfrs)sfr
.extrnt bitvar
.extrnf funct
.rseg CSEG,code
mov A,xvar
mov A,.BYTE xvar
mov A,dvar
mov A,#sfr
mov A,#bitvar
mov A,#44
mov DPTR,#dvar
mov DPTR,#bitvar
mov DPTR,#sfr
mov DPTR,#xvar
mov DPTR,#funct
mov DPTR,#4444
setb dvar
setb bitvar
setb .BIT 20
.end
;variable in xdata
;variable in data
;sfr
;bit
;code address
;
;warning here
;ok - warning suppressed
;ok
;warning here
;warning here
;ok
;warning here
;warning here
;warning here
;ok
;ok
;ok
;warning here
;ok
;ok - warning suppressed
;
For more details refer to the following sections:
2.6.6.“Allocation Attribute of a Name” on page17
3.6.“-a : to disable instruction operands types check” on page21
9.2.“8051 Operands; type check in instructions” on page 95
10.8. Error #1 <user-defined error message>
It is an error message defined by user. It is displayed by the .ERROR directive.
See also: .WARNING, .ERROR, .MESSAGE
MCA-51
Phyton
Chapter 10. Assembler messages
105
10.9. Error #3 '(' required
Error: an opening bracket is probably missing in one of the Assembler directives.
See also:
6.32.“.EXTRNB, .EXTRNW, .EXTRND, .EXTRNC, .EXTRNI, .EXTRNR,
.EXTRNT, .EXTRNN” on pag e74
6.15.“.EXTRN” on pag e60
6.28.“.TYPE” on page 70
6.29.“.FUNC, .ENDF” on page70
10.10. Error #4 ')' required
Error: a closing bracket is probably missing in one of the Assembler directives or
arithmetic expression.
See also:
6.32.“.EXTRNB, .EXTRNW, .EXTRND, .EXTRNC, .EXTRNI, .EXTRNR,
.EXTRNT, .EXTRNN” on pag e74
6.15.“.EXTRN” on pag e60
6.28.“.TYPE” on page 70
6.29.“.FUNC, .ENDF” on page70
Chapter 5.“Arithmetic Expressions” on page 31
Note!
If you miss out a comma in the .FUNC directive (in the list of function
parameter types), the Assembler will issue exactly this error message.
10.11. Error #5 '+', '-' or '.' required
Error: one of the +, - or . symbols is requires in the listing control command.
See also:
Chapter 7.“Listing controls” on page77
Phyton
MCA-51
Chapter 10. Assembler messages
106
10.12. Error #6 ',' required
Error: a comma is required here, but it is missing.
10.13. Error #8 .ENDF address is less than address of
function
Error: as a result of some tricky operations (probably, with absolute segments or
the .ORG directives), the .ENDF directive was encountered at the Assembler
program counter value which is less than the Assembler program counter value
which was at the processing of the corresponding .FUNC directive. It should not
happen.
Example:
.aseg ACODE,code
.org 100
.func Foo
nop
.org 50
ret
.endf
See also:
6.29.“.FUNC, .ENDF” on page70
10.14. Error #9 ASCII constant too long
Error : ASCII-number (string)is too long.
Only the strings not longer than 5 characters can be used as numbers.
See also:
5.4.“Character strings in expressions” on pag e33
4.2.“Names and Labels Definition Rules” on pag e25
MCA-51
Phyton
Chapter 10. Assembler messages
107
10.15. Error #10 Absolute expression required
Error: Absolute expression is required in this context but it is missing.
See also:
5.6.“Conversion and Check of Types in Expressions” on page34.
10.16. Error #11 Allocation required
Error: allocation attribute is required in this context but it is either missing or
specified incorrectly.
See also:
2.4.2.1.1.“Allocation Attributes Supported” on page8
10.17. Error #12 Bad allocation
Error: allocation attribute is required in this context but it is specified incorrectly.
See also:
2.4.2.1.1.“Allocation Attributes Supported” on page8
10.18. Error #13 Bad number of arguments
Error: wrong number of arguments is specified in this Assembler instruction (or
directive).
It should be noted that this error often results from other error ("induced" error).
10.19. Error #14 Division by zero
Error: when evaluating arithmetic expression, the Assembler encountered the
"division by zero" operation.
10.20. Error #15 Duplicate label <lname>
Error: name lname was declared more than once in the current scope.
Phyton
MCA-51
Chapter 10. Assembler messages
108
The same name can not be declared in a module more than once. The only exception is local labels of the function unique within a function, and not within a module.
Example:
.rseg RDATA,data
X
.rseg RCODE,code
X:
inc X
ret
.dsb
; error here
See also:
2.6.“Symbolic Names” on page 13
6.29.“.FUNC, .ENDF” on page70
10.21. Error #16 Duplicate macro <mname>
Error: the Assembler encountered more than one macro definition under mname.
There can not be two macros under the same name in a module.
See also:
8.2.“Directive .MACRO” on page 80
10.22. Error #27 Expression <> current relocation
Error: .ORG directive contains the expression, the relocatability attribute of
which does no match current segment relocatability.
See also:
6.18.“.ORG” on pag e62
10.23. Error #18 Expression not absolute
Error: absolute expression is required in this context, but specified expression is
not absolute.
MCA-51
Phyton
Chapter 10. Assembler messages
109
See also:
5.6.“Conversion and Check of Types in Expressions” on page34.
10.24. Error #19 Expression required
Error: an expression is required in this context but it is missing.
10.25. Error #20 Extra characters on line
Error: some extra characters are found at the end of the line.
It should be noted that this error is often caused by a missing comma or results
from other error ("induced" error.)
10.26. Error #21 Identifier required
Error: an identifier is missing in this directive. This error is usually made in the
.PUBLIC, .EXTRNx, .BYTE, .BIT, .TYPE directives.
An extra comma (right after a closing bracket) in the .EXTRNx directive may
cause this error.
See also:
6.14.“.PUBLIC” on page 59
6.32.“.EXTRNB, .EXTRNW, .EXTRND, .EXTRNC, .EXTRNI, .EXTRNR,
.EXTRNT, .EXTRNN” on pag e74
6.25.“.BYTE, .BIT” on pag e68
6.28.“.TYPE” on page 70
10.27. Error #22 Illegal instruction
Error: illegal instruction or Assembler directive is specified. This error often
occurs if a colon is missing after a label name or a dot is missing before Assembler directive.
It should be noted that this error often results from other error ("induced" error).
See also:
4.2.“Names and Labels Definition Rules” on pag e25
Phyton
MCA-51
Chapter 10. Assembler messages
110
4.5.“Assembler Source Line Format” on page27
10.28. Error #23 Illegal use of local variable <_name>
Error: illegal use of local (in function) identifier _name.
Local identifiers can not be declared as public, that is, they should not be found in
the .PUBLIC directive.
See also:
6.29.“.FUNC, .ENDF” on page70
10.29. Error #24 Illegal use of macro name <mname>
Error: illegal use of the mname macro.
Macro name can be used for the macro call (expansion) only. For example, a
macro can not be an operand of the machine instruction or Assembler directive.
See also:
8.8.“Macro Call and Parameter Substitution” on pag e84
10.30. Error #25 Inappropriate use of variable symbol
Error: incorrect use of a variable identifier.
Identifier that can have a variable value (that is, can be re-defined) is formed by
means of the .SET directive or the equals symbol (=). As a value of such identifier can be changed anywhere in the source text, its use is restricted. For example,
it can not be used in the .PUBLIC directive.
Identifier, the value of which can not be changed (and which can be used in the
.PUBLIC directive), is formed with the .EQU directive.
See also:
6.19.“.DEFINE, .EQU, .SET, =” on pag e62
MCA-51
Phyton
Chapter 10. Assembler messages
111
6.14.“.PUBLIC” on page 59
10.31. Error #26 Instruction operand required
Error: at least one more operand is required in the instruction.
10.32. Error #27 Invalid alignment
Error: the Assembler detected that there is a misaligned operand in the instruction. For example, in the instruction operating on words, the operands should
have even addresses.
10.33. Error #28 Invalid operand combination
Error: invalid operand combination is specified in machine instruction.
10.34. Error #29 Invalid syntax
Error: invalid syntax. Typical example:
.rseg RCODE,code
zzz .macro abc
4&abc:
.endmac
zzz def
.end
10.35. Error #31 Label <ident> already typified
Error: an attempt to change a value of the operand type of the ident identifier
which already has some value of the type attribute different from UNTYPED.
Phyton
MCA-51
Chapter 10. Assembler messages
112
If an identifier already has a value of the operand type attribute which is different
from UNTYPED, it can not be specified in the .BYTE directive
See also:
6.25.“.BYTE, .BIT” on pag e68
5.10.“.BYTE, .BIT, .UNTYPED Operators” on page38
2.6.5.“Operand Type Attribute of a Name” on page 16
10.36. Error #32 Label required for this directive
Error: current Assembler directive must be labeled, that is, some identifier is
always defined by means of the directive.
See also:
6.19.“.DEFINE, .EQU, .SET, =” on pag e62
6.31.“.LABELB, LABELW, LABELD, LABELC, LABELI, LABELL,
LABELR, LABELT” on page 72
2.4.2.1“Placement of Segments in Address Areas” on page8
10.37. Error #33 SFRs must be in absolute segment
Error: an attempt to declare a relocatable segment with allocation=sfrs.
Segments with sfrs allocation attribute can be of absolute type only. Such segments are used for the definition of SFRs.
See also:
6.16.“.ASEG, .RSEG” on page61
2.4.2.1“Placement of Segments in Address Areas” on page8
10.38. Error #34 Misplaced .ELSE
Error: inappropriate use of the .ELSE directive.
MCA-51
Phyton
Chapter 10. Assembler messages
113
Directive .ELSE can be place within a conditional block only, that is, between
.IF and .ENDIF.
See also:
8.16.“.IF, .ELSE, .ENDIF - Conditional Assembling Directives” on page94
10.39. Error #35 Misplaced .ENDIF
Error: inappropriate use of the .ENDIF directive.
Directive .ENDIF can be placed at the end of a conditional block only, that is,
after .IF or .ELSE.
See also:
8.16.“.IF, .ELSE, .ENDIF - Conditional Assembling Directives” on page94
10.40. Error #36 Misplaced .ENDMAC
Error: inappropriate use of the .ENDMAC directive.
Directive .ENDMAC can be placed at the end of a macro definition only.
See also:
8.2.“Directive .MACRO” on page 80
8.4.“Directive .ENDMAC” on pag e81
10.41. Error #37 Misplaced .EXITM
Error: inappropriate use of the .EXITM directive.
Directive .EXITM can be placed within a macro definition only, that is, between
.MACRO and .ENDMAC.
See also:
8.2.“Directive .MACRO” on page 80
Phyton
MCA-51
Chapter 10. Assembler messages
114
8.3.“Directive .EXITM” on page 81
8.4.“Directive .ENDMAC” on pag e81
10.42. Error #38 Misplaced operator .PARM
Error: inappropriate use of the .PARM operator. The .PARM operator can be
used within macro definitions only.
See also:
5.17.“.PARM Operator” on page44
8.2.“Directive .MACRO” on page 80
10.43. Error #39 Module name required
Error: a module name is not specified (or specified incorrectly) in the .PMODULE/.LMODULE/.LMODULE2 directive.
See also:
6.11.“.LMODULE, .PMODULE” on page58
6.12.“.LMODULE2” on page59
4.2.“Names and Labels Definition Rules” on pag e25
10.44. Error #40 Nested macro definitions
Error: the Assembler detected an attempt to nest macro definitions. It is prohibited.
See also:
8.14.“Nested Macro Calls and Definitions” on page93
8.8.“Macro Call and Parameter Substitution” on pag e84
8.2.“Directive .MACRO” on page 80
MCA-51
Phyton
Chapter 10. Assembler messages
115
10.45. Error #42 Invalid bank number
Error: wrong number of the working registers bank is specified in the .USING
directive.
See also:
5.20.1.“.USING” on page47
10.46. Error #41 No .END directive
Error: there is no .END directive at the end of the source file.
Source file is, probably, damaged.
See also:
6.13.“.ENDMOD, .END” on pag e59
10.47. Error #43 No .ENDIF directive
Error: some conditional block .IF does not have the .ENDIF directive at the end.
See also:
8.16.“.IF, .ELSE, .ENDIF - Conditional Assembling Directives” on page94
10.48. Error #44 No .ENDMAC directive
Error: some macro definition does not have the .ENDMAC directive at the end.
See also:
8.2.“Directive .MACRO” on page 80
8.4.“Directive .ENDMAC” on pag e81
Phyton
MCA-51
Chapter 10. Assembler messages
116
10.49. Error #45 No .FUNC directive
Error: detection of function end (the .ENDF directive), for which there is no corresponding function start (that is, the .FUNC directive) in the preceding program
text.
See also:
6.29.“.FUNC, .ENDF” on page70
10.50. Error #46 Relocatability conflict
Error: a conflict between relocatability attributes of the arithmetic expression
operands.
See also:
5.6.“Conversion and Check of Types in Expressions” on page34
10.51. Error #47 No module prolog
Error: the Assembler encountered a module end, but this module start was not
found anywhere in the foregoing text.
Usually this error occurs due to extra .END or .EMDMOD directive.
See also:
6.13.“.ENDMOD, .END” on pag e59
10.52. Error #48 No segment declaration
Error: an attempt to generate code (or to put a label) outside any segment.
Such error is usually found in the beginning of a source file. To eliminate the
error message, insert directive .RSEG or .ASEG before the line that caused the
error, which will activate certain segment.
See also:
MCA-51
Phyton
Chapter 10. Assembler messages
117
6.16.“.ASEG, .RSEG” on page61
2.5.“Segments” on pag e11
10.53. Error #51 Operand required
Error: an operand is required in the arithmetic expression, but it is missing.
Usually this message means exactly what it says: there is an arithmetic operation in some expression, and not all of the operands are specified for the operation.
10.54. Error #52 Operand syntax
Error: incorrect operand syntax in arithmetic expression.
10.55. Error #55 Operator not allowed here
Error: illegal use of a part extraction operator (.HWRD, .LWRD, .HIGH,
.LOW, .BYTE3).
Example:
.externn abc
;external value
X = .LWRD(.LOW(abc));successive application
;several operators of part
;extraction
;
FOO: .DB1 .HWRD abc;a byte is required, and not a word
Fore more details refer to sections:
5.11.“.HWRD, .LWRD, .HIGH, .LOW, .BYTE3 Operators” on page39
5.6.“Conversion and Check of Types in Expressions” on page34
Phyton
MCA-51
Chapter 10. Assembler messages
118
10.56. Error #56 Out of range
Error: some value is beyond allowable value range.
The most probable reason for this error is a jump to the address located too far
from current program counter value (for example, JZ can execute a jump within 128...+127 byte relative to the first byte of the next instruction).
Example:
.rseg RCODE,code
label:
nop
.org $+1024
jz label
;error
10.57. Error #57 Segment mismatch for function
<fname>
Error: directive .ENDF that ends the fname function is not in the segment where
it is required. It should be in the same segment where corresponding .FUNC
fname directive is allocated.
See also:
6.29.“.FUNC, .ENDF” on page70
10.58. Error #58 Segment name required
Error: a segment name is not specified in the .RSEG/.ASEG directive or a wrong
segment name is specified. For example, allocation attributes' names can not be
used as segment names.
See also:
6.16.“.ASEG, .RSEG” on page61
4.2.“Names and Labels Definition Rules” on pag e25
2.4.2.1.1.“Allocation Attributes Supported” on page8
MCA-51
Phyton
Chapter 10. Assembler messages
119
10.59. Error #59 Something after .END directive
Error: there is some text following the .END directive. Directive .END indicates
the end of file and the end of the last module in the file, so there should be no text
after it.
See also:
6.13.“.ENDMOD, .END” on pag e59
10.60. Error #61 Module should be closed with .ENDMOD
Error: before opening the next module with the .PMODULE or .LMODULE
directive, you should close the previous module with the .ENDMOD directive.
See also:
6.11.“.LMODULE, .PMODULE” on page58
6.13.“.ENDMOD, .END” on pag e59
10.61. Error #62 Segment <sname> must be declared
before using
Error: you can not use a segment if it was not declared in the earlier text. To
declare a segment, add a comma and allocation.
See also:
6.16.“.ASEG, .RSEG” on page61
2.4.2.1.1.“Allocation Attributes Supported” on page8
Phyton
MCA-51
Chapter 10. Assembler messages
120
10.62. Error #63 String required
Error: a string is required here, but it is missing. This error usually occurs in the
.WARNING, .ERROR, .MESSAGE, .LNKCMD directives.
See also:
6.26.“.WARNING, .ERROR, .MESSAGE” on page69
6.17.“.LNKCMD” on page61
10.63. Error #64 String too long
Error: a character string is too long, that is, its length exceeds 255 characters.
See also:
4.2.“Names and Labels Definition Rules” on pag e25
10.64. Error #65 Superfluous label <lname>
Error: an extra label. Directives .BYTE, .BIT, .PUBLIC, .EXTRN, .TYPE and
.FUNC can not be labeled.
See also:
6.25.“.BYTE, .BIT” on pag e68
6.14.“.PUBLIC” on page 59
6.15.“.EXTRN” on pag e60
6.28.“.TYPE” on page 70
6.29.“.FUNC, .ENDF” on page70
4.2.“Names and Labels Definition Rules” on pag e25
MCA-51
Phyton
Chapter 10. Assembler messages
121
10.65. Error#69 Too many macro arguments
Error: too many macro arguments were specified. Not more than 33 arguments
are allowed for usual macros, and not more than 32 arguments are allowed for
repeat blocks .IRP.
See also:
8.2.“Directive .MACRO” on page 80
8.6.“.IRP - Repeat Block with Parameter Scanning” on page82
10.66. Error #73 Type conflict
Error: conflict of types.
Example:
.rseg ttt,xdata
aa .equ 16
.type aa(1)
.type aa(2)
.end
10.67. Error #74 Unclosed function <fname>
Error: function fname is not ended with the .ENDF directive.
See also:
6.29.“.FUNC, .ENDF” on page70
10.68. Error #75 Incompatible optype and allocation
Error: operand type is incompatible with allocation attribute in the .EXTRNx
directive. Such error most often occurs in a case of the attempt to declare a nonbit variable with allocation == bit.
Operand type
Phyton
Allocation attribute compatible with the operand type
MCA-51
Chapter 10. Assembler messages
122
BIT
BYTE
bit, free
data, bdata, idata, sfrs, xdata, code, free
Example:
.extrnb (xdata) gg
.extrnb (bit) hh
;ok
;error
See also:
6.32.“.EXTRNB, .EXTRNW, .EXTRND, .EXTRNC, .EXTRNI, .EXTRNR,
.EXTRNT, .EXTRNN” on pag e74
2.6.5.“Operand Type Attribute of a Name” on page 16
2.4.2.1.1.“Allocation Attributes Supported” on page8
10.69. Error #78 Unknown label <id>
Error: an unknown name (label, identifier) is specified to the Assembler in the
source text.
10.70. Error #79 Instruction is illegal for this CPU type
Error: this machine instruction is not supported by selected processor type or is
inaccessible in selected memory model.
See also:
3.2.“-Ccpu : to specify processor type” on p age19
10.71. Error #81 Incompatible segment relocation
Error: wrong segment switch directive was used. If a segment was declared with
the.RSEG directive, you can not switch to it with the .ASEG directive, and vice
versa.
Example:
MCA-51
Phyton
Chapter 10. Assembler messages
123
...
.RSEG RCODE,code ; declaration of segment Code
...
.RSEG RCODE
; switch to Code
...
.ASEG RCODE
; switch to Code - ERROR
...
See also:
6.16.“.ASEG, .RSEG” on page61
10.72. Error #82 Incompatible segment allocation
Error: certain action can not be performed in the current segment, because it is
not allowed at this value of the segment allocation attribute. Such error most
often occurs in case of the attempt to define a bit variable in a non-bit segment,
and in case of the attempt to define a non-bit variable in a bit segment.
Example:
.rseg RBIT,bit
aa .dst
bb .dsb
.rseg RDATA,data
cc .dsb
dd .dst
ee .labelb
ff .labelt
.end
;
;ok
;error
;
;ok
;error
;ok
;error
;
10.73. Error #83 Illegal forward reference
Error: illegal forward reference. Operations .ALLOCATION and .OPTYPE do
not allow the use of forward references as their operands.
Phyton
MCA-51
Chapter 10. Assembler messages
124
See also:
5.13.“.ALLOCATION Operator” on page40
5.14.“.OPTYPE Operator” on page42
10.74. Error #86 Too many nested macro calls
Too many nested macro calls. As a rule, such error occurs in case of macro calls
cycling.
See also:
8.14.“Nested Macro Calls and Definitions” on page93
10.75. Error #87 Incorrect segment allocation specified
At the switch to the segment, incorrect allocation attribute was specified. The
easiest way to eliminate this error is to delete allocation attribute along with preceding comma from the segment-switch directive.
Example:
.rseg RCODE,code
...
.rseg RCODE
...
.rseg RCODE,code
...
.rseg RCODE,data
...
.end
;declaration of segment RCODE - OK
;switch to segment RCODE - OK
;switch to segment RCODE - OK
;ERROR
See also:
6.16.“.ASEG, .RSEG” on page61
MCA-51
Phyton
Chapter 10. Assembler messages
125
2.6.6.“Allocation Attribute of a Name” on page17
10.76. Fatal #0 No such file or directory (<filename>)
Assembler can not find include-file filename. Further assembling is impossible.
See also:
6.10.“.INCLUDE” on page58
3.3.“-Ipath : to search for include-files in specified directories” on pa ge20
10.77. Fatal #49 No source file name
Error: Source file name was not specified to the Assembler at the start. Program
execution terminates immediately.
See also:
Chapter 3.“Assembler Start and Command Line Options” on page19
10.78. Fatal #60 Source line too long
Source line is too long, therefore the Assembler can not process this file.
Generally speaking, maximum line length, which is 1000 characters, is more than
sufficient. Perhaps, there is something wrong with a file.
10.79. Fatal #66 Too many errors
Assembler has detected too many errors, which means that the number of
detected errors exceeded the limit specified by the -E option.
See also:
3.16.“-Ennn : to terminate assembling after nnn errors” on page23
Phyton
MCA-51
Chapter 10. Assembler messages
126
10.80. Fatal #67 Too many externals
Too many external names were declared in the module. Maximum allowable
number of external names is 1023.
10.81. Fatal #70 Too many segments
Too many segments were declared in the module. Maximum allowable number
of segments is 1023.
10.82. Fatal #71 Too many source files
There are too many include-files (included with the .INCLUDE directive) in a
source file.
Maximum allowable number of include-files is 1023.
10.83. Fatal #76 Unknown CPU model <cpu_id>
Unknown processor type <cpu_id> is specified to the Assembler in the -C option.
Assembling will be immediately terminated.
See also:
3.2.“-Ccpu : to specify processor type” on p age19
10.84. Fatal #77 Unknown command-line option
<bad_option>
Unknown option bad_option is specified to the Assembler. Assembling will be
immediately terminated.
See also:
Chapter 3.“Assembler Start and Command Line Options” on page19
MCA-51
Phyton
Chapter 10. Assembler messages
127
10.85. Fatal #80 Command-line too long
Specified command line is too long. Assembling will be immediately terminated.
Use option files to avoid this problem.
See also:
3.5.“@file : to read options from specified file” on page20
Phyton
MCA-51
128
MCA-51
Chapter 10. Assembler messages
Phyton
Chapter 11. Purpose and basic operating principles of the Linker
129
Chapter 11. Purpose and basic
operating principles of the Linker
11.1. Purpose of the Linker and Linking Process
MCLINK Linker links modules contained in object files and libraries, into a single executable file.
Linking process consists of the following stages:
•
•
•
•
•
•
•
establishing a set of modules to be linked and resolving external references,
definition of size and composition of address areas,
definition of size and composition of segments,
segment allocation in appropriate address areas,
calculation of absolute values of the names defined in relocatable segments,
evaluation of relocatable external references values,
generation of output files and a MAP-file.
11.2. Establishing a Set of Modules to be
Linked
At the first stage, a set of modules to be linked is established. The Linker scans
the object and library files specified on the command line, and, as a rule, a number of passes is required for this.
Naturally, at the first pass, all the program modules are included in the list of
modules to be linked.
During the second pass, the Linker starts to check a module list and to add some
library modules to it. A library module is added only if it contains definitions of
some public names, which can resolve some external references unresolved by
then (that is, references to public names).
Phyton
MCA-51
130
Chapter 11. Purpose and basic operating principles of the Linker
At the end of each pass, the Linker checks some conditions.
If all the external references are resolved, the Linker terminates the scanning of
input files and proceeds to the next linking stage. If there are some unresolved
references the Linker starts the next pass.
If, after a certain pass the Linker did not add any module to the list, but there are
still some unresolved references, then it stops scanning input files and an error
message is generated.
The repeated scanning procedure described above leaves you worry-free about
the order of specifying files with library modules on the command line.
Note that all the program modules are guaranteed to be linked before library
modules are linked. It is also guaranteed that all library modules will be linked
before low-priority library modules.
The necessity of linking is resolved for a library module faster than for a module
contained in an object file, as the lists of external and public names of this module are included in the library header.
11.3. Resolving External References and Type
Check
The Linker resolves references to external names within a module by the search
for the matching public names in other modules.
If a matching public name is found, all the attributes (allocation, operand type,
type) of the public name and external name are checked. If the types of even one
attribute mismatch, a possible error warning is generated. If the -t option is specified, types are not checked.
MCA-51
Phyton
Chapter 11. Purpose and basic operating principles of the Linker
131
Relocatable external references like any other relocatable references are resolved
only after all the segments have been allocated.
11.4. Setting up Address Spaces
The Linker always sets up the following standard address spaces:
Address space
Address range
BIT
DATA
BDATA
IDATA
SFRS
XDATA
CODE
000H-0FFH
000H-07FH
020H-02FH
000H-07FH
080H-0FFH
000H-0FFFFH
000H-0FFFFH
Size of these address spaces can be redefined with the linker option -A. As a rule,
it may be required for IDATA, XDATA, CODE only.
Other address spaces (if necessary) are declared on the command line with the
same option -A. Allocation attribute and address range should be specified for
each of the address spaces.
Note!
Address range of the address space should be within the range allowed
for this allocation.
See also:
2.4.2.1.1.“Allocation Attributes Supported” on page8
11.5. Relocatable segments linking
After establishing a set of modules to be linked, the Linker examines these modules and defines the names of all the program segments. Segments that are used
in several modules should have identical definitions in all these modules (and
Phyton
MCA-51
132
Chapter 11. Purpose and basic operating principles of the Linker
therefore must have identical allocation and relocatability attributes), otherwise a
warning is issued.
Then the Linker binds the fragments in a single segment (a fragment is a segment
part defined in one module). When a fragment is added, its alignment attribute is
taken into consideration, and so the resulting segment may contain unused gaps
between fragments. After the binding has been completed, the Linker knows the
size and alignment attribute of the segment.
After the binding of relocatable segments has been completed, the Linker proceeds to the allocation of segments in address areas.
11. 5 . 1 . O n t h e s e g m e n t a l i g n m e n t
Alignment attribute (or simply alignment) defines the boundary for the alignment
of the segment start address; it is required so that the .ALIGN directive of the
Assembler might operate correctly.
Alignment attribute of the whole segment is defined as the maximum value of
alignment attributes of fragments of this segment.
Alignment of a segment fragment is equal to the maximum alignment of all
alignments specified in the .ALIGN directives found in this fragment. If there are
no.ALIGN directives in the fragment, its alignment is equal to 0.
11.6. Segment Placement
After the binding of relocatable segments has been completed, the Linker proceeds to the allocation of segments in address areas. The main principles of this
process are the following:
• some address spaces overlay each other. It means that when one address area
is filled up, some space is also used in the other address area,
MCA-51
Phyton
Chapter 11. Purpose and basic operating principles of the Linker
133
• standard address spaces are automatically filled with segments in established
order: (1) bdata-segments (segments with allocation == bdata), (2) bit-segments, (3) data-segments, (4) idata-segments. The rest of address spaces are
filled in arbitrarily,
• the user can explicitly indicate to the Linker where to place a segment. It can
be done with the -S option. Such segments are placed before the automatic
allocation of the rest of segments,
• absolute segments are automatically taken into account when relocatable
segments are allocated. Address area occupied by an absolute segment with
certain allocation attribute, is reserved in all address spaces that have the
same allocation. It is implied that if banked memory model is used, absolute
segments should be in all the banks,
• the Linker always allocates relocatable segments so that they do not overlap
with each other. When allocating relocatable segments, the Linker takes into
account their alignment attributes.
The following table illustrates the overlay of address spaces:
Address spaces
Overlay range
DATA, IDATA
000H...01FH
DATA, IDATA, BDATA, BIT
DATA, IDATA
020H...02FH1
030H...07FH
Segments that are allocated "manually", are processed by the Linker in the order
in which they are specified in -S options. You can additionally specify a left or
right boundary in the -S options. If a left boundary (start address) or a right
boundary (end address) is specified for a relocatable segment, then the Linker
puts the segment as close to this boundary as possible.If neither left nor right
boundary is specified for a segment, then the Linker automatically puts the segment close to the beginning of the address area. You can not specify boundaries
for an absolute segment.
1. For BIT, overlay range is 000H...07FH
Phyton
MCA-51
134
Chapter 11. Purpose and basic operating principles of the Linker
A segment that is not specified in any of the -S options, is automatically allocated
in the appropriate address area. If such a segment is relocatable, it is automatically put close to the beginning of address area.
After the allocation of segments has been completed, all the relocatable names
(including public names) assume absolute values.
11.7. Support of Instruction Sets for Various
Processors (Linker)
The Assembler has a special -C option for the performance of additional checks
and for the support the modularity concept. This option controls the use of
machine instructions.
Modules assembled for different instruction sets are incompatible.
For additional information see:
3.2.“-Ccpu : to specify processor type” on p age19
5.21.“.MODEL Variable” on page49
11.8. Linker's Messages
11. 8 . 1 . Wa r n i n g # 3 0 " Se gm e n t ' s s s ' a u t o p l a c e d in t h e . . . ' a a a ' "
The address space in which segment sss is to be placed, was not specified to the
Linker. The Linker has allocated it in the default address space (aaa).
As a rule, this is exactly how the segments should be placed. This warning is
issued for information only. It can easily be disabled with the -w option of the
Linker.
MCA-51
Phyton
Chapter 11. Purpose and basic operating principles of the Linker
135
See also:
11.6.“Segment Placement” on pag e132
2.4.2.1“Placement of Segments in Address Areas” on page8
11.8.2 . Er ror # 46 " U ndefi ne d ext ern name
'xnam e' i n mo dul e 'm name ' "
The Linker failed to resolve external reference to xname that was made from the
mname module. In other words, external name xname is declared in module
mname, but this name was not declared as public with the .PUBLIC directive in
any other module.
11. 8 . 3 . F a t a l # 1 " Ad d r e s s a r e a ' a a n a m e '
e x c e e d s p r e d e f i n e d li m it s "
Address range specified for address area aaname is beyond the limits allowable
for this memory model.
For more details refer to section:
2.4.2.1.1.“Allocation Attributes Supported” on page8
Note!
Phyton
The Linker determines memory model by the records contained in relocatable object files. All the relocatable object files should be assembled
for the same memory model.
MCA-51
136
MCA-51
Chapter 11. Purpose and basic operating principles of the Linker
Phyton
Chapter 12. Linker start and options
137
Chapter 12. Linker start and options
12.1. Start Line Format
MCLINK [options] [prefix] obj_or_lib_file [prefix] obj_or_lib_file ...
If the Linker input file name extension is .MCO or .MCL, it can be omitted.
The use of spaces within options is not allowed.
12.2. -A Option: Address Area Definition
-A (allocation)addr_area_name(range_list) addr_area_name is a name of the
address area being defined. This name is defined by a user. If you specify a name
of a standard address area (for example, IDATA), then the size of this address
area will be redefined.
allocation is the allocation attribute of this address area.
range_list - a list of address ranges allowed for the use in this address area; the
Linker will allocate segments only within these ranges. Address ranges should be
within the boundaries specified for address areas within given allocation. For
more information about address area boundaries see section: Syntax for
range_list: start_addr-end_addr[,start_addr-end_addr]...
Start_addr and end_addr can be specified in decimal, binary, octal and hexadecimal form; binary numbers should begin with '0' and end with letter 'B'( both
lower-case and upper-case letters can be used); octal numbers should begin with
'0' and end with letter 'Q' or 'O' (both lower-case and upper-case letters can be
used); hexadecimal numbers should begin with '0' and end with letter 'H' (both
lower- and upper-case letters can be used).
Example:
Phyton
MCA-51
Chapter 12. Linker start and options
138
-A (code)CODE(0-0FFFh,02000H-03000H)
The Linker will redefine the size of a standard address area CODE; this address
area will contain two ranges: 0-0FFFH and 02000H-03000H. Allocation
Attributes Supported
For detailed description, see
2.4.2.1.1.“Allocation Attributes Supported” on page8
12.3. -C Option: Enables Code Generation in
Address Area
-C addr_area_name addr_area_name - address area name.
The Linker enables the allocation of code in specified address area, in other
words, enables code generation in this area. The user should specify this option
for the address areas, where executable code, constant tables etc. will be allocated. Code generation cannot be enabled for the register address areas.
If code generation is not enabled for a certain address area, then only the segments that do not contain code can be allocated in such address area. Otherwise
the Linker will issue an error message.
Example:
-C CODE_1 # enables code generation for CODE_1
12.4. -K Option: Disables Allocation of Relocatable Segments
-K allocation(range_list) allocation - allocation type of address area.
range_list - list of address ranges specified in accordance with the same rules as
for the -A option.
MCA-51
Phyton
Chapter 12. Linker start and options
139
The Linker excludes range_list from the list of address ranges, where relocatable
segments can be placed, in all address areas with the same allocation attribute as
the one specified in the option.
The Assembler can transfer this option to the Linker by means of the .LNKCMD
directive.
12.5. -S Option: Segment Allocation
-S addr_area_name(seg_list) addr_area_name - name of address area.
seg_list - a list of segments to be allocated in this address area; for relocatable
segments you may specify a boundary, and the Linker will put a segment close to
this boundary.
Syntax for seg_list: segname[>|<address][%pagesize] [,segname[>|<address][%pagesize]]...
Character '>' symbol between segname and address instructs the Linker to allocate this segment starting from address. If it is not possible to do so, then the
Linker will allocate the segment starting from the nearest suitable address greater than the specified one.
Character < between segname and address instructs the Linker to allocate this
segment so that it ends at an address. If it is not possible to do so, then the Linker
will allocate the segment so that it ends at the nearest suitable address - less than
the specified one.
Start or end address can be specified for relocatable segments only.
Phyton
MCA-51
Chapter 12. Linker start and options
140
Address can be specified in decimal, binary, octal and hexadecimal form; binary
numbers should start with '0' and end with letters 'B'(both lower-case and uppercase letters can be used); octal numbers should start with '0' and end with letter
'Q' or 'O' (both lower-case and upper-case letters can be used); hexadecimal numbers should start with '0' and end with letter 'H' (both lower-case and upper-case
letters can be used).
Pagesize should be a number which is multiple of an integer power of 2. If it is
specified, the Linker will allocate a segment so that the whole segment can be
placed on the page which is the size of the pagesize. It means, actually, that the
segment should not cross the boundary of the page which is the size of pagesize,
that is, the segment should be within the pagesize*n...pagesize*n+1 (n >= 0)
range.
Examples:
-S CODE(CODESEG1>8000H,CODESEG2<8000H)
-S CODE(CODESEG3%2048,CODESEG4%2048)
You can specify segment start/end address and pagesize at the same time:
-S CODE(CODESEG>0100H%2048,CONSTSEG<0FF00H%8192)
12.6. -E Option: Specifies Output File Name
-E [path]filename This option is used for specifying a name and a path for output
file (files). You cannot specify a name extension; if specified, it will be ignored,
as it is automatically chosen by the Linker in accordance with specified output
format. If a path is not specified, output files will be created in the current directory.
If the -E option is not specified, the output file name will be the same as the name
of the first file from the list of files to be linked. The same applies to the path.
MCA-51
Phyton
Chapter 12. Linker start and options
141
Example:
-E c:\myproj\project1
Output files will be created in the c:\myproj directory and their names will be
project1.*.
12.7. -O Option: Specifying Search Paths for
Object Files
-O path This option instructs the Linker to search for the object and library files,
the paths of which are not explicitly specified, in specified directories if they are
not found in the current directory. Names of directories should be separated with
semicolons, for example:
-O c:\mca51\lib;c:\myproj\my_obj
At first the linker will search for files in directory c:\mca51\lib, and then - in
directory c:\myproj\my_obj.
12.8. -F Option: Specifies Output File Format
-F format_name[format_name]...
This option specifies output file format. If you specify several output formats,
then several output files in appropriate formats will be generated.
format_name can be the following: M - Phyton-Microcosm format of executable
files, I - Intel HEX, Z - debug information in ZAX format.
Executable files of Phyton-Microcosm format have extension .MCE.
By default, HEX-files have extension .Hnn, where nn is the number of address
area (numbers of address areas can be found in the MAP-file). It is more convenient to use option -H, which allows to specify explicitly a HEX-file extension
for each address area.
The same applies to ZAX-files.
HEX-files are not generated for address areas that do not contain code.
Example:
-F MI
Phyton
MCA-51
142
Chapter 12. Linker start and options
The Linker will generate files in MCE format (for debugging) and HEX format
(you can use HEX-files when working with any programmer).
12.9. -H Option: Specifies HEX-file name extension
-H addr_area_name(hex-extension[,zax-extension]) This option allows you to
explicitly specify what extensions (instead of default extensions .Hnn and .Znn)
will be used for the output HEX-files and ZAX-files containing debug information.
For example, the option: -H XDATA(HE1) means the following: output HEXfile of address area XDATA will have extension .HEX.
addr_area_name is a name of address area.
hex-extension - specifies extension of the HEX-file corresponding to specified
address area.
zax-extension is an optional parameter; it is used for specifying the extension of
ZAX-file corresponding to specified address area.
12.10. -Z Option: Increases Segment Size
-Z segname(new_size) This option makes it possible to specify the size of segments at the linking stage and not in the source text, which might be convenient
in some instances.
segname is a segment name. This segment should be relocatable and should not
contain code.
new_size is a new segment size (in bytes). It should be greater than original size
of this segment (established as a sum of the sizes of all fragments of this segment
from all the modules where it is used). Segment size is specified in the same way
as in the -A directive.
MCA-51
Phyton
Chapter 12. Linker start and options
143
Example:
-Z STACK(0100h)
# sets stack size to 256 bytes
12.11. -m Option: Generates a MAP-file
-m This option instructs the Linker to generate a MAP-file (Linker's report). A
MAP-file has the same name as the output file, but the MAP-file name's extension is .MAP.
12.12. -M Option: Not to include Specified Section in the MAP-file
-M nn This option allows to omit the unnecessary information in the MAP-file,
and, thus, facilitates subsequent analysis of the Linker's operation. Linker does
not include the section specified by nn in the MAP-file (option -M can be specified many times):
0
1
10
2
20
21
3
4
5
6
- original list of Linker's options,
- process of linking program modules,
- public/external names in program modules,
- process of adding library modules,
- public/external names in the linked library modules,
- a list of unlinked library modules,
- complete set of Linker's options,
- report on segment building,
- a list of address areas,
- report on the results of relocatable segments allocation,
60 - process of relocatable segments allocation,
7
8
80
9
- allocation map of address areas (memory map),
- a table of public and external names,
- a table of reserved/internal public and external names,
- report on output files.
Recommendation for most purposes:
Phyton
MCA-51
Chapter 12. Linker start and options
144
-M 10
-M 20
-M 21
-M 60
tion
-M 80
# not to include public/external names in program modules
# not to include public/external names in library modules
# not to include a list of unlinked library modules
# not to include the process of relocatable segments alloca# not to include a list of reserved and internal names
12.13. -t Option: Turns off Global Type Checking
-t Disables type checking while resolving external references.
For additional information see section: Resolving External References and Type
Check
For detailed description, see
11.3.“Resolving External References and Type Check” on page130
12.14. -w Option: Linker's Warnings Control
-w This option instructs the Linker not to display on console the messages on the
automatic segment allocation in standard address areas.Segments that are not
specified in the -S are displayed automatically.
As a rule, automatic segment allocation is performed quite satisfactorily, and it is
better to specify option -w.
For additional information see section: Segment Placement
For detailed description, see
11.6.“Segment Placement” on pag e132
MCA-51
Phyton
Chapter 12. Linker start and options
145
12.15. -h, -? Options: Displays Brief Description of Options
-h -? These options instruct the Linker to display brief description of options on
the console. The same takes place if the Linker is started without specifying any
parameters.
12.16. @filename Option: Includes File in the
Command Line
@filename
Includes contents of specified file in the command line; <CR> and <LF> are
ignored in this file. You can include comments which should be preceded by a
hash mark ("#"); the rest of the line after this mark is ignored.
12.17. -p, -l, -o Prefixes: Changing Module
Types
-p, -l, -o
Any of the -p, -l or -o prefixes can be put before each of the files to be linked,
which means the following: -p all modules in this file to be considered program
modules, -l all modules in this file to be considered library modules, -o all modules in this file to be considered low-priority library modules,
Phyton
MCA-51
146
MCA-51
Chapter 12. Linker start and options
Phyton
Chapter 13. MCLIB library service utility
147
Chapter 13. MCLIB library service
utility
The MCLIB utility (Librarian) is intended for creating libraries (library files with
.MCL extension). It also provides various services for libraries. The Librarian
can add, delete, extract, substitute modules in libraries as well as change
attributes of modules.
You can control the Librarian by means of command line options described
below. You can also control the Librarian via option files. Only one option can be
specified for one run of MCLIB.
13.1. -a: Adds Modules to the Library
-a library_file obj_file1 [obj_file2] ...
To add all the modules from specified object file (files) to the library_file library.
If the library_name library does not exist, it is created.
If, in the existing library, there is a module with the same name as the name of
one of the modules to be added, then the "duplicate module" error will occur.
13.2. -d: Deletes Modules from the Library
-d library_file module1 [module2] ...
Delete specified module (modules) from the library. If the modules are not found,
then the "unknown module" error will occur. Naturally, the library_file library
file should exist.
Phyton
MCA-51
148
Chapter 13. MCLIB library service utility
13.3. -r: Replaces Modules in the Library
-r library_file obj_file1 [obj_file2] ...
To update the library: to substitute modules of specified object file (files) for the
modules with the same names in the library_file library.
If the library_name library does not exist, it is created.
If some object file contains a module that was not included in the library being
updated, it will be added to the library.
13.4. -x: Extracts Modules from the Library into
Object Files
-x library_file module1 [module2] ...
Extract modules from the library into object files. Modules are not deleted from
the library.
Each extracted module will be placed into an separate object file with extension
.MCO, and its name will be formed according to the following rules: - if a module name consists of not more than 8 characters, then the object file name will be
the same as the module name; - if a module name contains more than 8 characters, then the object file name will be produced by cutting this name down (from
the right to the left) to 8 characters.
If specified modules are not found, then the "unknown module" error occurs. The
specified library_file library file is assumed to exist.
MCA-51
Phyton
Chapter 13. MCLIB library service utility
149
13.5. -X: Extracts Modules from the library into
one Object File
-X object_file library_file module1 [module2] ...
To extract modules form the library and place them into one object file with the
object_file name and extension .MCO. If other extension is specified for the
object file, it will be created with this extension.
Modules are not deleted from the library.
If specified modules are not found in the library, the "unknown module" error
occurs. The specified library_file library file is assumed to exist.
13.6. -m: Moves Modules from the Library into
Object Files
-m library_filemodule1[module2] ...
To extract and move modules from the library into object files. Modules are
deleted from the library.
Each specified module is placed in a separate object file with the .MCO extension, and its name is formed according to the following rules: - if a module name
consists of not more than 8 characters, then the object file name will be the same
as the module name; - if a module name contains more than 8 characters, then the
object file name will be produced by reducing this name down (from the right to
the left) to 8 characters.
If specified modules are not found in the library, the "unknown module" error
occurs. The specified library_file library file is assumed to exist.
Phyton
MCA-51
Chapter 13. MCLIB library service utility
150
13.7. -M: Moves Modules from the Library into
One Object File
-M object_file library_file module1 [module2] ...
To extract modules from the library and move them into one object file with the
object_file name and the .MCO extension. If other extension is specified for the
object file, it will be created with this extension.
Modules are deleted from the library.
If specified modules are not found in the library, the "unknown module" error
occurs. The specified library_file library file is assumed to exist.
13.8. -l: Displays Library Header on the Console
-l library_file Displays the header (catalogue) of the specified library on the console. If the header is too long and can not be fully displayed on the console, you
can reassign standard output to the file (by means of the angle character >) or use
the MORE DOS-utility.
Example:
mclink -l mylib >mylib.txt
The Librarian will direct the header of the mylib.mcl library to the standard output; DOS will capture this data and allocate it in the mylib.txt file.
MCA-51
Phyton
Chapter 13. MCLIB library service utility
151
13.9. -P: Assigns "Program" Attribute to Modules
-P library_file module1 [module2] ...
Assign the "program" attribute to specified modules from the library_file library.
If specified modules are not found in the library, the "unknownmodule" error
occurs. The specified library_file library file is assumed to exist.
13.10. -L: Assigns the "Library"' Attribute to
Modules
-L library_file module1 [module2] ...
Assign the "library" attribute to specified modules from the library_file library.
If specified modules are not found in the library, the "unknownmodule" error
occurs. The specified library_file library file is assumed to exist.
13.11. -O: Assigns the "Low-Priority Library"'
Attribute to Modules
-O library_file
module1
[module2] ...
Assign the "low-priority library" attribute to specified modules from the
library_file library.
Phyton
MCA-51
Chapter 13. MCLIB library service utility
152
If specified modules are not found in the library, the "unknownmodule" error
occurs. The specified library_file library file is assumed to exist.
13.12. -h,-?: Displays Brief Options Description
on the Console
-h -? To display brief description of options on the console. The Linker will do
the same if it is started without any parameters specified.
13.13. @: Includes File Contents in the Command Line
@filename
Includes the contents of specified file in the command line; <CR> and <LF> are
ignored in this file. You can enter comments which should be preceded by the
hash mark ("#"), the rest of the line after this mark is ignored.
Note!
Only one option can be specified for each run of the Linker.
13.14. MCLIB Messages
13.1 4.1. E rro r #4 " D upl i c ate modu le
'mod _nam e'"
The Librarian detected the attempt to add to the library a module with the same
name as the name of one of the modules already included in the library.
MCA-51
Phyton
Chapter 13. MCLIB library service utility
153
In this case, either use the -d option in order to delete the module with the same
name before adding a new one, or use the -r option which is intended especially
for the replacing of the module in the library.
1 3 . 1 4. 2 . F at a l # 3 "B a d o bj ec t f i l e ' o b j _ f i l e' "
The Librarian detected the attempt to add modules from the object file of invalid
format to the library. Object file is the most probably damaged.
Phyton
MCA-51
154
MCA-51
Chapter 13. MCLIB library service utility
Phyton
Chapter 14. MCDUMP utility for printing out object files
155
Chapter 14. MCDUMP utility for printing
out object files
The MCDUMP Object-to-Text Converter is intended for conversion object files
into the form convenient for reading. It can read and convert object files (.MCO),
libraries (.MCL) and executable object files (.MCE).
MCDUMP displays data on the console (standard output device). If there is not
enough space for data on the screen, you can re-direct standard output to the file
(by means of > operator) or useDOS-utility MORE.
Start line format:
MCDUMP [option(s)] library_or_object_file
If none of the -e, -m, -p, -s, -H options are specified, but a file is specified, then
the whole contents of the file are displayed.If some of the following options are
specified: -e, -m, -p, -s, then MCDUMP executes only the last one.
Options:
14.1. MCDUMP messages.
1 4 . 1 . 1 . - e : Pri n t s O u t R e c o r d s w i t h t h e
D escri pt i on of Mo dul es an d E x terna l N a m es
-e To print the records of an object or library file with the description of modules
and external names contained in it. This option is illegal for MCE-files.
1 4 . 1 . 2 . - m: Pr in t s o u t R ec o r d s w i t h t h e M o d u l e
D es c ri pt i on
-m To print the records of an object or library file with the description of modules
contained in it. This option is illegal for MCE-files.
Phyton
MCA-51
Chapter 14. MCDUMP utility for printing out object files
156
1 4 . 1 . 3 . - p : Pri n t s O u t R e c o r d s w i t h t h e
D es c ri pt i on of Mo dul es an d P ubl i c N a m e s
-p To print the records of an object or library file with the description of modules
and external names contained in it. This option is not illegal for MCE-files.
1 4 . 1 . 4 . - s : P ri nt s O u t R ec o r d s w i t h t h e D es c r ip t i on o f Mo d u l e s and Se gme n t s
-s To print the records of an object or library file with the description of modules
and segments contained in it. This option is illegal for MCE-files.
14. 1 . 5. -H : P ri nt s o ut Li bra ry ' s H e a d e r
-H To print a library header. This option is ignored for files in MCO and MCE
format.
14. 1 . 6. -r: Di s pl ay s D a t a i n T r a n s p a r e n t M o d e
-r Transparent mode. All the references to preceding records are displayed on the
console in numeric form, and not in symbolic form.
1 4 . 1 . 7 . - h , - ? : D i s p l a y s B ri ef D es c r ip t io n o f
MC D U MP O p t io ns on t h e C ons o le
-h -? To display brief option description on the console. MCDUMP will do the
same if it is started without any parameters specified.
1 4 . 1 . 8 . @ : I n c l u d e s F i l e C on t e n t s i n t o t h e
D ump er C om man d Lin e
@filename
Include the contents of specified file in the command line; <CR> and <LF> are
ignored in this file. You can include comments which should be preceded by the
hash mark ("#"). The rest of the line after this mark is ignored.
MCA-51
Phyton
Chapter 14. MCDUMP utility for printing out object files
157
14.1 . 9. Fa tal #1 B ad versi on o f MC E form at i n
< f il en ame >
File filename.MCE has inappropriate format. MCDUMP can not convert it into a
readable form.
Object file is the most probably damaged.
14.1 . 10. Fata l #2 B ad versi on of M CL for mat in
< f il en ame >
Library filename.MCL has inappropriate format. MCDUMP can not convert it
into a readable form.
Library file is the most probably damaged.
14.1 . 11. Fa tal # B ad ver s io n of M C O for mat in
< f il en ame >
File filename.MCO has inappropriate format. MCDUMP can not convert it into a
readable form.
Object file is the most probably damaged.
14.1 . 12. F atal #4
14.1 . 13. F atal #5
14.1 . 14. F atal #6
14.1 . 15. F atal #7
14.1 . 16. F atal #8
14.1 . 17. F atal #9
14.1 . 18. F atal #1 0
Phyton
MCA-51
158
Chapter 14. MCDUMP utility for printing out object files
14.1 . 19. F atal #11
14.1 . 20. F atal #1 2
MCA-51
Phyton