The Fred Fish Collection 1.5/ffcollection-1-5-1992-11.iso/ff_disks/600-699/ff600.lzh/NCode/NCode.docs/Manual.English

Text File | 1992-02-01 | 24KB | 708 lines

NCode: THE CONDITIONAL MACRO ASSEMBLER (Copyright Edgar Visser).


1.1 Calling the assembler.

The command template for the assembler is:

  NCode <sourcefile>
        [-A<parameter file>] (params will be read from file)
        [-L<listing file>]   (default is output to screen)
        [-O<object file>]
        [-P<page length>]    (-P0 turns off soft-pages)
        [-C<cpu code>]       (-C0/68000,1/68010,2/68020,3/68030)

Standard parameters will be read from the file "NCode.arg". This
parameter file can be adapted to suit your particular needs by
changing it with a simple text editor. It is also possible to
have multiple parameter files, which can be nested to any depth.
This comes in very handy for passing standard parameters to the
assembler; for example concerning the target CPU.

The listing will go, unless specified otherwise, to the screen.
If the listing turned is off then only error-reports will be
send to the listing.

The assembler does not produce an object file unless you request
it explicitly. If an "-O" argument was given and there were no
errors found an object file will be produced. If possible the
assembler will generate an executable file; this code does not
need to be linked and can be executed directly. But does the
sourcecode contain any external references or external
definitions then the produced object file will still need to be
linked.

By using the "-P<page length>" parameter it is possible to give
the page length without having to alter the sourcecode (by using
the PLEN-directive). The default page length is 60 lines. If the
listing is send to the screen there will be NO soft-pages in the
listing, unless explicitly requested for by the PAGE-directive.
It is also possible to suppress soft-pages by calling the
assembler with "-P0" as a parameter. The "-P" parameter is very
useful if placed in the "NCode.arg" file. This makes sure you
don't have to give this parameter every time you call the
assembler. The page length remains variable, because parameters
given on the command line may overwrite arguments given in the
argument file.

NCode can produce code for the Motorola MC68000, MC68010, MC68020
and the MC68030 CPU. By using the "-C<cpu code>" argument you can
tell the assembler for what processor to produce code. Because
this is a setting that will probably not change very often, is
wise to put the "-C" argument in "NCode.arg".

If no "-C" keyword is given the assembler will generate code for
the MC68000 CPU. The "-C" keyword makes sure that instructions
and operands that are not allowed for the specified cpu will
produce error-reports.


1.2  Sourcecode syntax.

One line of sourcecode can be divided into four parts:

Label field         e.g. START:
Opcode field        e.g. MOVE.L
Operand field       e.g. 10(a6),d0
Comment field       e.g. ;teller=max

To separate each field from the next, press the SPACEBAR or TAB
key. This produces a separator character. You may use more than
one separator to separate the fields. Some or all fields may be
omitted.


1.2.1 Labels.

A label should always start on the first position of a new line
in order to be seen as a label by the assembler. A label may be
followed by a newline, tab, space, colon, semi colon or asterisk.
The possibility to end a label with a colon is for compatibility
with other assemblers and is not needed by the assembler. A label
starts with an underscore, dot or character followed by zero or
more underscores, dots, characters and digits. The assembler
distincts between characters in upper and lower case. Only the
first 31 characters are significant, of which a maximum of 16
characters will be printed in the symbol-table-dump.


1.2.2 Comment.

Anything after a semi colon, asterisk or the terminating space of
the operand field is ignored. So the assembler treats any
characters you insert after the terminating space as a comment.


1.2.3 Opcode.

An opcode can be an instruction, assembler directive or macro.
The syntax of the instructions is completely as defined in the
Motorola MC680x0 User's Manual and can be given in upper or lower
case.

To enter instructions and directives that can operate on more
than one data size, you use an optional size-specifier (one
character), which is separated from the opcode by a dot. Possible
size-specifiers are:

 - B Byte data (8 bits)
 - W Word data (16 bits)
 - L Long Word data (32 bits) or Long Branch
 - S Short Branch

The assembler makes no difference between a size-specifier in
upper or lower case.


1.2.4 Operand.

If present, the operand field contains one or more operands to
the instruction or directive, and must be separated from it by at
least one space or tab. If you have two or more operands in this
field, you must separate them with a comma. The operand field
terminates with a space, tab, comment or newline character.


1.3   Expressions.

An expression is a combination of symbols, constants, algebraic
operators and parentheses that you can use to specify the operand
field to instructions or directives. You may include relative
symbols in an expression, but they can only be operated on by a
subset of the operators.


1.3.1 Operators.

The available operators are listed below in order of precedence.

1. Unary Minus, Logical NOT (- and ~)
2. Leftshift, Rightshift (<< and >>)
3. Logical AND, OR and XOR (&, ! or |,  ^)
4. Multiply, Divide (* and /)
5. Add, Subtract (+ and -)

All operators are allowed on absolute operands. But when using
the Add operator (+) only relative+absolute and absolute+relative
is allowed (result is relative). When using the Subtract operator
(-) relative-relative is allowed if both relatives are dependent
of the same section (result is absolute). Relative-absolute is
also allowed, which results in a relative value.


1.3.2 Constants

Constants can be part of an expression and always have an
absolute value. They take one of the following formats:

 - Decimal
   a string of decimal digits
   e.g. 33458

 - Hexadecimal
   $ followed by a string of hex digits
   e.g. $89AB

 - Octal
   @ followed by a string of octal digits
   e.g. @678

 - Binary
   % followed by zeros and ones
   e.g. %10100010

 - ASCII Literal
   up to 4 ASCII characters within single or double quotes
   e.g. 'WTG'

Strings of less than 4 characters are justified to the right,
using null as the packing character. To obtain a quote character
in the string, you can use two quotes e.g. 'Ed''s' the same can
be achieved by "Ed's".


1.4  Addressing modes.

The syntax of the addressing modes is in standard Motorola syntax
as given in the following table. "Dn" represents one of the data
registers (D0-D7), "An" represents one of the address registers
(A0-A7 and SP), "Xn" represents an index register (data of
address register) optionally followed by an ".W" or ".L" size-
specifier and (MC68020/30) a "*Scale" scale (value 1,2,4 or 8).

  Syntax            Description

  Dn                data register direct
  An                address register direct
  (An)              address register indirect
  (An)+             address register indirect postincrement
  -(An)             address register indirect predecrement
  d16(An)           address register indirect displacement
  d8(An,Xn)         address register indirect index
* (bd,An,Xn)        address register indirect base displacement
* ([bd,An],Xn,od)   memory indirect postindexed
* ([bd,An,Xn],od)   memory indirect preindexed
  xxx.W or (xxx).W  absolute short
  xxx.L or (xxx).L  absolute long
  d16(PC)           program counter indirect displacement
  d8(PC,Xn)         program counter indirect index
* (bd,PC,Xn)        program counter indirect base displacement
* ([bd,PC],Xn,od)   PC memory indirect postindexed
* ([bd,PC,Xn],od)   PC memory indirect preindexed
  #<data>           immediate

USP,CCR,VBR etc.    special addressing modes


The with an "*" marked addressing modes are only allowed for the
MC68020 and MC68030. Of these marked addressing modes any part of
the operand may be omitted (suppressed). This suppressed part
will not be taken in account when calculating the effective
address of the operand. At the PC-modes it is possible to
explicitly suppress the PC to make sure that the assembler does
not see it as an suppressed address register. This is done by
typing "ZPC" at the position of the suppressed PC. Examples are:
([A5],lab), ([A2,D4.W*4]), (basdp,ZPC,A3*8) or even ([]).


1.5  Instruction variations.

Certain instructions (e.g. ADD en MOVE) have an address variant
for different types of operands, there is for example a MOVEA for
address register as destination. NCode is capable of choosing the
right address variant for the specified operand. This allows you
to write, for example, CMP (Ax)+,(Ay)+ instead of writing CMPM
(Ax)+,(Ay)+.

NCode is also capable of converting branches without size-
specifier that do not jump forward to a short branch if the
branch distance allows this.


1.6  Assembler directives.

Assembler directives are instructions to the assembler. They may
tell the assembler how to translate the code, how and what to
list, start macro definitions, etc. The following table lists the
directives by function.


1.6.1 Pseudopcodes.

 - SECTION

syntax: [<label>] SECTION <name>[,CODE|DATA|BSS][,CHIP|FAST]

This directive tells the assembler to restore the counter to
the last location allocated in the named section (or to zero
if used for the first time).

   CODE indicates that the section contains relocatable code.
        This is the default.
   DATA indicates that section contains initialized data
        (only).
   BSS  indicates that the section contains uninitialized data.

   CHIP indicates that the requested type of memory (CODE,
        DATA, BSS) is to be placed in the memory part
        accessible by the custom chips.
   FAST the section of memory is to be placed in the memory
        inaccessible by the custom chips.

The assembler can maintain up to 255 sections. Initially,
the assembler begins with an unnamed CODE section. The
assembler assigns the optional symbol <labels> to the value
of the program counter AFTER it has executed the SECTION
directive. In addition, where a section is unnamed, the
shorthand for that section is the keyword CODE. If CHIP or
FAST memory is not explicitly requested, then the choice
for the type of memory is left to the Operating System.

 - END

syntax: [<label>] END

The END directive tells the assembler that the source is
finished, and the assembler ignores subsequent source
statements. When the assembler encounters the END directive
during the first pass, it begins the second pass. If the
label field is present, then the assembler assigns the value
of the current program counter to the label before it
executes the END-directive.

 - EQU

syntax: <label> EQU <exp>

The EQU directive assigns the value of the expression in the
operand field to the symbol in the label field. The value
assigned is permanent, so you may not define the label
anywhere else in the program. Forward or external references
are not allowed within the expression.

 - SET

syntax: <label> SET <exp>

The SET directive assigns the value of the expression in the
operand field to the symbol in the label field. SET is
identical to EQU, apart from the fact that within SET the
label may be redefined. You can always change SET later on
in the program. You should not insert forward references
within the expression.

 - EQUR

syntax: <label> EQUR <register>

This directive lets you equate one of the processor
registers with a user symbol. Only the Address and Data
registers are valid (An, Dn and SP), so special registers
like SR, CCR, and USP are illegal here. The label assignment
is permanent, so you cannot define the label anywhere else
in the program. The register must not be a forward reference
to another EQUR statement. But you can use labels previously
defined by use of the EQUR directive.

 - REG

syntax: <label> REG <register list>

The REG directive assigns a value to the label, such that
the assembler can translate the label into a register list
mask format used in the MOVEM instruction.

<register list> is the form

   R1[-R2][/R3[-R4]]...

Where Rx is a data or address register (possibly defined by
the EQUR directive) or a previously defined register list.

 - DC

syntax: [<label>] DC[.<size>] <list>

The DC directive defines a constant value in memory. It may
have any number of operands, separated by commas. The
values in the list must be capable of being held in the data
location whose size is given by the size-specifier on the
directive. If you do not give a size specifier, DC assumes
it is ".W". If the size is ".B", then there is one other
data type that can be used: that of the ASCII string. This
is an arbitrarily long series of ASCII characters, contained
within single or double quotation marks. As with ASCII
literals; if you require a quotation mark in the string,
then you must enter two quotation marks. If the size is ".W"
or ".L", then the assembler aligns the data onto a Word
boundary.

 - DS

syntax: [<label>] DS[.<size>] <absexp>

To reserve memory locations, you use the DS directive. DS,
however, does no initialization. The amount of space the
assembler allocates depends on the data size (the size
specifier of the directive), and the value of the expression
in the operand field. The assembler interprets this as the
number of data items of that size to allocate. As with DC,
if the size specifier is ".W" or ".L", DS aligns the space
to a word boundary. So, DS.W 0 has the effect of aligning
to a word boundary only. If you do not give a size
specifier, DS assumes a default of ".W".

See CNOP and EVEN for a more general way of handling
alignment.

 - RS

syntax: [<label>] RS[.<size>] <absexp>

As the DS directive, except that this directive does not
reserve any memory. This pseudop can be used to define a
list of offsets. If a label is present it will be assigned
the offset to the beginning of the list of offsets. How much
a offset increases to from the last offset depends on the
<size> (default ".W") and the value of the absolute
expression in the operand field.

See also the DS directive.

 - RSSET

syntax: [<label>] RSSET <absexp>

Starts a list of offsets defined by the RS directive. The
first offset, defined by RS, is assigned the value as given
in <absexp>.

 - RSRESET

syntax: [<label>] RSRESET

Starts a list of offsets defined by the RS directive. The
first offset, is assigned the absolute value zero.

 - LIST

syntax: LIST

The LIST directive tells the assembler to produce the
assembly listing file. Listing continues until it encounters
either an END or a NOLIST directive. The NOLIST directive
has only effect when the assembler is producing a listing
file. The LIST directive does not appear on the output
listing.

 - NOLIST

syntax: NOLIST

The NOLIST directive turns off the production of the
assembly listing file. Listing ceases until the assembler
encounters either an END or a LIST directive. The NOLIST
directive does not appear on the program listing.

 - MLIST

syntax: MLIST

Makes sure that expansions of macros are listed (unless
NOLIST is active). This directive does not appear on the
output listing.

 - NOMLIST

syntax: NOMLIST

Makes sure that expansions of macro are not listed. This
directive does not appear on the output listing.


 - CLIST

syntax: CLIST

If a condition of conditional assembly is not taken then the
sourcecode that is not assembled will still be listed. A 'F'
(= False) will be displayed in the listing. This directive
does not appear on the output listing.

 - NOCLIST

syntax: NOCLIST

Makes sure that lines of code, that are not being assembled
because of a false conditional, will not appear in the
listing. This directive does not appear on the output
listing.

 - PAGE

syntax: PAGE

PAGE advances the assembly listing to the top of the next
page. Every page start with page-number, copyright
announcement, version-number, and an user specified header.
The PAGE  directive does not appear on the output listing.

 - NOPAGE

syntax: NOPAGE

The NOPAGE directive turns off the printing of page throws
and title headers to the assembly listing. This directive
does not appear on the output listing.

 - PLEN

syntax: PLEN <absexp>

The PLEN directive sets the page length, in lines, of the
assembly listing file to the value you specified in the
operand field. The value must lie between 20 and 200 and you
can only set it once in the program. The default page length
is 60 lines.

 - TTL

syntax: TTL <title string>

The TTL directive sets the title of the program to the
string you gave in the operand field. This string appears as
the page heading in the assembly listing. The string starts
at the first nonblank character after the TTL, and continues
until the end of line. It must not be longer than 60
characters in length. The TTL directive does not appear on
the program listing.

 -  FAIL

syntax: FAIL

The FAIL directive tells the assembler to flag an error for
this input line. This directive together with conditional
assembly can be used in macro expansions to test the number
of actual parameters given to the macro call.

 - EVEN

syntax: [<label>] EVEN

Forces the next binary code to a word address (even)
boundary (by inserting a 0-byte if necessarily). If the
label field is present, then the assembler assigns the even
value of the program counter to the label.

 - CNOP

syntax: [<label>] CNOP <number>,<number>

This directive is an extension from the Motorola standard
and allows a section if code to be aligned on any boundary.
In particular, it allows any data structure or entry point
to be aligned to a long word boundary. The first expression
represents an offset, while the second expression represents
the alignment required for the base. The code is aligned to
the specified offset from the nearest required alignment
boundary. For instance CNOP 0,4 aligns code to the next long
word boundary.

 - MACRO

syntax: <label> MACRO

MACRO introduces a macro definition. ENDM terminates a macro
definition. You must provide a label, which the assembler
uses as the name of the macro; subsequent uses of that label
as an operand will expand the contents of the macro and
insert it into the sourcecode. A macro can contain any
opcode, most assembler directives, or any previously defined
macro. Line numbers will not increase during macro
expansion. If you use a macro name, you may append a number
of arguments, separated by commas. If the argument contains
a space or tab then you must enclose the entire argument
within '<' and '>' symbols.

The assembler stores up and saves the sourcecode that you
enter (after a MACRO directive and before an ENDM directive)
as the contents of the macro. The code can contain normal
sourcecode. In addition, it may contain system indexes and
formal parameters. Formal parameters are the form "\X",
where X (0-9) stands for the number of the actual parameter
at the macro call. The "\0" takes a special place; this
parameter takes the value of the size specifier. If an
argument is omitted, at the macro call, than nothing is
inserted for the formal parameter. A backslash followed by
the symbol '@' tells the assembler to generate the next
system index. This takes the form of "_nnn", where nnn is
the number of times this macro has been expanded. This is
normally used to generate unique labels within a macro.

You may not nest macro definitions, that is, you cannot
define a macro within a macro, although you can call a macro
you previously defined. There is a limit to the level of
nesting of macro calls. This limit is set at 16.

Macro expansion stops when the assembler encounters the end
of the stored macro text, or when it encounters a MEXIT
directive.

 - NARG

syntax: NARG

The symbol NARG (Number of ARGuments) is a special reserved
symbol and the assembler assigns it the index of the last
argument passed to the macro in the parameter list (even
nulls). Outside of a macro expansion, NARG has the value
zero.

 - ENDM

syntax: ENDM

This terminates a macro definition introduced by a MACRO
directive.

 - MEXIT

syntax: MEXIT

You use this directive to exit from macro expansion mode,
usually in conjunction with the conditional assembly
directives. It allows conditional expansion of macros.

 - XDEF

syntax: XDEF <label>[,<label>...]

One or more absolute or relocatable labels may follow the
XDEF directive. Each label defined by XDEF generates an
external symbol definition. You can make references to the
symbol in other modules (possibly from a highlevel language)
and satisfy the references with a linker. If you use this
directive or XREF, then you cannot directly execute the code
produced by the assembler.

 - XREF

syntax: XREF <label>[,<label>...]

One or more labels that must not have been defined elsewhere
in the program follow the XREF directive. Subsequent uses of
the label tell the assembler to generate an external
reference for that label. You use the label as if it
referred to an absolute or relocatable value depending on
whether the matching XDEF referred to an absolute or
relocatable symbol. The actual value used is filled in, from
another module, by a linker.

 - INCDIR

syntax: INCDIR <path>[,<path>...]

This tells the assembler in what directories to search for
the include files if it cannot find them in the current
directory.

 - INCLUDE

syntax: INCLUDE <file name>

The INCLUDE directive allows the inclusion of external files
into the program source. You set up the file that INCLUDE
inserts with the string description in the operand field.
You can nest INCLUDE directives up to a depth of 16 possibly
inclosing the file name within quotes. INCLUDE is especially
useful when you require a standard set of macro definitions
or EQUs in several programs.

It is often convenient to place NOLIST and LIST directives
at the head and tail of files you intend to include.

 - IDNT

syntax: IDNT <string>

A module can be given a name. If the linker finds two
modules with the same name it combines both modules.


1.6.2 Conditional assembly.

Conditional assembly allows a part of the sourcecode to be
assembled or not, depending on the condition given. Lines of code
that will not be assembled are of no direct importance to the
program. Therefore, the listing of not assembled lines of
sourcecode can be turned off by using the NOCLIST directive. The
CLIST directive turns the listing of these lines back on. The
'conditional assembly directives' all take the form of:
     IFxx <operand>
       <source code>
     ENDC

The following 'conditional assembly directives' are supported:

 - IFC
   IFNC

syntax: IFC <string>,<string>
        IFNC <string>,<string>

The strings must be a series of ASCII characters optionally
enclosed in single or double quotes, for example, 'WTG' or
(the empty string). If the condition is not TRUE, assembly
ceases (that is, it is disabled). Again the conditional
assembly switch remains active until the assembler finds a
matching ENDC statement.

 - IFD
   IFND

syntax: IFD <symbol name>
        IFND <symbol name>

Depending on whether or not you have already defined the
symbol, the assembler enables or disables assembly until it
finds the matching ENDC.

 - IFEQ, IFNE, IFGT, IFGE, IFLT and IFLE

syntax: IFxx <absexp>

Lines of sourcecode following the condition will be
assembled if <absexp> ==0 (IFEQ), <>0 (IFNE), >0 (IFGT), >=0
(IFGE), <0 (IFLT) or <=0 (IFLE).

 - ENDC

syntax: ENDC

To terminate a conditional assembly, you use the ENDC
directive, set up with any of the ten IFxx directive above.
ENDC matches the most recently encountered condition
directive.