pwarren
/
6502
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
6502/vasm/doc/syntax_std.texi

544 lines
19 KiB
Plaintext
Raw Permalink Blame History

This chapter describes the standard syntax module which is available
with the extension @code{std}.
@section Legal
This module is written in 2002-2017 by Volker Barthelmann and
is covered by the vasm copyright without modifications.
@section Additional options for this module
This syntax module provides the following additional options:
@table @option
@item -ac
Immediately allocate common symbols in .bss/.sbss section and
define them as externally visible.
@item -align
Enforces the backend's natural alignment for all data directives
(@code{.word}, @code{.long}, @code{.float}, etc.).
@item -nodotneeded
Recognize assembly directives without a leading dot (@code{.}).
@item -noesc
Ignore escape character sequences in string constants.
@item -sdlimit=<n>
Put data up to a maximum size of n bytes into the small-data
sections. Default is n=0, which means the function is disabled.
@end table
@section General Syntax
Labels have to be terminated with a colon (@code{:}).
Local labels may either be preceded by a '@code{.}' or terminated by
'@code{$}', and consist out of digits only.
Local labels exist and keep their value between two global label definitions.
Make sure that you don't define a label on the same line as a
directive for conditional assembly (if, else, endif)! This is not supported.
The operands are separated from the mnemonic by whitespace.
Multiple operands are separated by comma (@code{,}).
Comments are introduced by the comment character @code{#}. The rest
of the line will be ignored. For the c16x, m68k, 650x, ARM, Z80, 6800
and Jaguar-RISC backends, the comment character is @code{;}
instead of @code{#}, although @code{#} is still allowed when being the
first non-blank character on a line.
Example:
@code{mylabel: inst.q1.q2 op1,op2,op3 # comment}
In expressions, numbers starting with @code{0x} or @code{0X} are
hexadecimal (e.g. @code{0xfb2c}). @code{0b} or @code{0B} introduces
binary numbers (e.g. @code{0b1100101}). Other numbers starting with
@code{0} are assumed to be octal numbers, e.g. @code{0237}. All
numbers starting with a non-zero digit are decimal, e.g. @code{1239}.
C-like escape characters in string constants are allowed by default,
unless disabled by @option{-noesc}.
@section Directives
All directives are case-insensitive.
The following directives are supported by this syntax module (if the
CPU- and output-module allow it):
@table @code
@item .2byte <exp1>[,<exp2>...]
See @code{.uahalf}.
@item .4byte <exp1>[,<exp2>...]
See @code{.uaword}.
@item .8byte <exp1>[,<exp2>...]
See @code{.uaquad}.
@item .ascii <exp1>[,<exp2>,"<string1>"...]
See @code{.byte}.
@item .abort <message>
Print an error and stop assembly immediately.
@item .asciiz "<string1>"[,"<string2>"...]
See @code{.string}.
@item .align <bitorbyte_count>[,<fill>][,<maxpad>]
Depending on the current CPU backend @code{.align} either behaves
like @code{.balign} (x86) or like @code{.p2align} (PPC).
@item .balign <byte_count>[,<fill>][,<maxpad>]
Insert as much fill bytes as required to reach an address which
is dividable by <byte_count>. For example @code{.balign 2} would
make an alignment to the next 16-bit boundary.
The padding bytes are initialized by <fill>, when given. The optional
third argument defines a maximum number of padding bytes to use. When
more are needed then the alignment is not done at all.
@item .balignl <bit_count>[,<fill>][,<maxpad>]
Works like @code{.balign}, with the only difference that the optional
fill value can be specified as a 32-bit word. Padding locations which
are not already 32-bit aligned, will cause a warning and padded by
zero-bytes.
@item .balignw <bit_count>[,<fill>][,<maxpad>]
Works like @code{.balign}, with the only difference that the optional
fill value can be specified as a 16-bit word. Padding locations which
are not already 16-bit aligned, will cause a warning and padded by
zero-bytes.
@item .byte <exp1>[,<exp2>,"<string1>"...]
Assign the integer or string constant operands into successive
bytes of memory in the current section. Any combination of integer
and character string constant operands is permitted.
@item .comm <symbol>,<size>[,<align>]
Defines a common symbol which has a size of <size> bytes. The
final size and alignment will be assigned by the linker, which
will use the highest size and alignment values of all common
symbols with the same name found. A common symbol is allocated
in the .bss section in the final executable. ".comm"-areas of
less than 8 bytes in size are aligned to word boundaries, other-
wise to doubleword boundaries.
@item .double <exp1>[,<exp2>...]
Parse one of more double precision floating point expressions and
write them into successive blocks of 8 bytes into memory using the
backend's endianess.
@item .endm
Ends a macro definition.
@item .endr
Ends a repetition block.
@item .equ <symbol>,<expression>
See @code{.set}.
@item .equiv <symbol>,<expression>
Assign the <expression> to <symbol> similar to @code{.equ} and
@code{.set}, but signals an error when <symbol> has already been
defined.
@item .err <message>
Print a user error message. Do not create an output file.
@item .extern <symbol>[,<symbol>...]
See @code{.global}.
@item .fail <expression>
Cause a warning when <expresion> is greater or equal 500. Otherwise
cause an error.
@item .file "string"
Set the filename of the input source. This may be used by some
output modules. By default, the input filename passed on the
command line is used.
@item .float <exp1>[,<exp2>...]
Parse one of more single precision floating point expressions and
write them into successive blocks of 4 bytes into memory using the
backend's endianess.
@item .global <symbol>[,<symbol>...]
Flag <symbol> as an external symbol, which means that <symbol> is
visible to all modules in the linking process. It may be either
defined or undefined.
@item .globl <symbol>[,<symbol>...]
See @code{.global}.
@item .half <exp1>[,<exp2>...]
Assign the values of the operands into successive 16-bit words of
memory in the current section using the backend's endianess.
@item .if <expression>
Conditionally assemble the following lines if <expression> is non-zero.
@item .ifeq <expression>
Conditionally assemble the following lines if <expression> is zero.
@item .ifne <expression>
Conditionally assemble the following lines if <expression> is non-zero.
@item .ifgt <expression>
Conditionally assemble the following lines if <expression> is
greater than zero.
@item .ifge <expression>
Conditionally assemble the following lines if <expression> is
greater than zero or equal.
@item .iflt <expression>
Conditionally assemble the following lines if <expression> is
less than zero.
@item .ifle <expression>
Conditionally assemble the following lines if <expression> is
less than zero or equal.
@item .ifb <operand>
Conditionally assemble the following lines when <operand> is
completely blank, except an optional comment.
@item .ifnb <operand>
Conditionally assemble the following lines when <operand> is
non-blank.
@item .ifdef <symbol>
Conditionally assemble the following lines if <symbol> is defined.
@item .ifndef <symbol>
Conditionally assemble the following lines if <symbol> is undefined.
@item .incbin <file>
Inserts the binary contents of <file> into the object code at
this position. The file will be searched first in the current
directory, then in all paths defined by @option{-I} or
@code{.incdir} in the order of occurence.
@item .incdir <path>
Add another path to search for include files to the list of
known paths. Paths defined with @option{-I} on the command line are
searched first.
@item .include <file>
Include source text of <file> at this position. The include file
will be searched first in the current directory, then in all
paths defined by @option{-I} or @code{.incdir} in the order of
occurence.
@item .int <exp1>[,<exp2>...]
See @code{.long}.
@item .irp <symbol>[,<val>...]
Iterates the block between @code{.irp} and @code{.endr} for each
@code{<val>}. The current @code{<val>}, which may be embedded in quotes,
is assigned to @code{\symbol}. If no value is given, then the block is
assembled once, with @code{\symbol} set to an empty string.
@item .irpc <symbol>[,<val>...]
Iterates the block between @code{.irp} and @code{.endr} for each
character in each @code{<val>}, and assign it to @code{\symbol}.
If no value is given, then the block is assembled once, with
@code{\symbol} set to an empty string.
@item .lcomm <symbol>,<size>[,<alignment>]
Allocate <size> bytes of space in the .bss section and assign
the value to that location to <symbol>. If <alignment> is given,
then the space will be aligned to an address having <alignment>
low zero bits or 2, whichever is greater.
<symbol> may be made globally visible by the .globl directive.
@item .list
The following lines will appear in the listing file, if it was
requested.
@item .local <symbol>[,<symbol>...]
Flag <symbol> as a local symbol, which means that <symbol> is
local for the current file and invisible to other modules in
the linking process.
@item .long <exp1>[,<exp2>...]
Assign the values of the operands into successive 32-bit words of
memory in the current section using the backend's endianess.
@item .macro <name> [<argname1>[=<default>][,<argname2>...]]
Defines a macro which can be referenced by <name>. The macro
definition is closed by an @code{.endm} directive. The names
of the arguments, which may be passed to this macro, must be
declared directly following the macro name. You can define an
optional default value in the case an argument is left out.
Note that macro names are case-insensitive while the argument
names are case-sensitive.
Within the macro context arguments are referenced by @code{\argname}.
The special argument @code{\@@} inserts a unique id,
useful for defining labels.
@code{\()} may be used as a separator between the name of a macro
argument and the subsequent text.
@item .nolist
The following lines will not be visible in a listing file.
@item .org <exp>
Before any other section directive @code{<exp>} defines the absolute
start address of the program. Within a section @code{<exp>} defines
the offset from the start of this section for the subsequent code.
When <exp> starts with a current-pc symbol followed by a plus (@code{+})
operator, then the directive behaves like @code{.space}.
@item .p2align <bit_count>[,<fill>][,<maxpad>]
Insert as much fill bytes as required to reach an address where
<bit_count> low order bits are zero. For example @code{.p2align 2} would
make an alignment to the next 32-bit boundary.
The padding bytes are initialized by <fill>, when given. The optional
third argument defines a maximum number of padding bytes to use. When
more are needed then the alignment is not done at all.
@item .p2alignl <bit_count>[,<fill>][,<maxpad>]
Works like @code{.p2align}, with the only difference that the optional
fill value can be specified as a 32-bit word. Padding locations which
are not already 32-bit aligned, will cause a warning and padded by
zero-bytes.
@item .p2alignw <bit_count>[,<fill>][,<maxpad>]
Works like @code{.p2align}, with the only difference that the optional
fill value can be specified as a 16-bit word. Padding locations which
are not already 16-bit aligned, will cause a warning and padded by
zero-bytes.
@item .quad <exp1>[,<exp2>...]
Assign the values of the operands into successive quadwords
(64-bit) of memory in the current section using the backend's
endianess.
@item .rept <expression>
Repeats the assembly of the block between @code{.rept} and @code{.endr}
<expression> number of times. <expression> has to be positive.
@item .section <name>[,"<attributes>"][[,@@<type>]|[,%<type>]|[,<mem_flags>]]
Starts a new section named @code{<name>} or reactivate an old one. If
attributes are given for an already existing section, they must
match exactly. The section's name will also be defined as a new
symbol, which represents the section's start address.
The @code{"<attributes>"} string may consist of the following characters:
Section Contents:
@table @code
@item c
section has code
@item d
section has initialized data
@item u
section has uninitialized data
@item i
section has directives (info section)
@item n
section can be discarded
@item R
remove section at link time
@item a
section is allocated in memory
@end table
Section Protection:
@table @code
@item r
section is readable
@item w
section is writable
@item x
section is executable
@item s
section is sharable
@end table
Section Alignment: A digit, which is ignored. The assembler will
automatically align the section to the highest alignment restriction
used within.
Memory flags (Amiga hunk format only):
@table @code
@item C
load section to Chip RAM
@item F
load section to Fast RAM
@end table
The optional @code{<type>} argument is mainly used for ELF output
and may be introduced either by a '%' or a '@@' character.
Allowed are:
@table @code
@item progbits
This is the default value, which means the section data occupies
space in the file and may have initialized data.
@item nobits
These sections do not occupy any space in the file and will be
allocated filled with zero bytes by the OS loader.
@end table
When the optional, non-standard, @code{<mem_flags>} argument is given
it defines a 32-bit memory attribute, which defines where to load
the section (platform specific).
The memory attributes are currently only used in the hunk-format
output module.
@item .set <symbol>,<expression>
Create a new program symbol with the name <symbol> and assign to it
the value of <expression>. If <symbol> is already assigned, it will
contain a new value from now on.
@item .size <symbol>,<size>
Set the size in bytes of an object defined at <symbol>.
@item .short <exp1>[,<exp2>...]
See @code{.half}.
@item .single <exp1>[,<exp2>...]
Same as @code{.float}.
@item .skip <exp>[,<fill>]
Insert <exp> zero or <fill> bytes into the current section.
@item .space <exp>[,<fill>]
Insert <exp> zero or <fill> bytes into the current section.
@item .stabs "<name>",<type>,<other>,<desc>,<exp>
Add an stab-entry for debugging, including a symbol-string and
an expression.
@item .stabn <type>,<other>,<desc>,<exp>
Add an stab-entry for debugging, without a symbol-string.
@item .stabd <type>,<other>,<desc>
Add an stab-entry for debugging, without symbol-string and value.
@item .string "<string1>"[,"<string2>"...]
Like @code{.byte}, but adds a terminating zero-byte.
@item .swbeg <op>
Just for compatibility. Do nothing.
@item .type <symbol>,<type>
Set type of symbol called <symbol> to <type>, which must be one of:
@table @code
@item 1: Object
@item 2: Function
@item 3: Section
@item 4: File
@end table
The predefined symbols @code{@@object} and
@code{@@function} are available for
this purpose.
@item .uahalf <exp1>[,<exp2>...]
Assign the values of the operands into successive 16-bit areas of
memory in the current section regardless of current alignment.
@item .ualong <exp1>[,<exp2>...]
Assign the values of the operands into successive 32-bit areas of
memory in the current section regardless of current alignment.
@item .uaquad <exp1>[,<exp2>...]
Assign the values of the operands into successive 64-bit areas of
memory in the current section regardless of current alignment.
@item .uashort <exp1>[,<exp2>...]
Assign the values of the operands into successive 16-bit areas of
memory in the current section regardless of current alignment.
@item .uaword <exp1>[,<exp2>...]
Assign the values of the operands into successive 16-bit areas
of memory in the current section regardless of current alignment.
@item .weak <symbol>[,<symbol>...]
Flag <symbol> as a weak symbol, which means that <symbol> is
visible to all modules in the linking process and may be replaced
by any global symbol with the same name.
When a weak symbol remains undefined its value defaults to 0.
@item .word <exp1>[,<exp2>...]
Assign the values of the operands into successive 16-bit words of
memory in the current section using the backend's endianess.
@item .zero <exp>[,<fill>]
Insert <exp> zero or <fill> bytes into the current section.
@end table
Predefined section directives:
@table @code
@item .bss
.section ".bss","aurw"
@item .data
.section ".data","adrw"
@item .rodata
.section ".rodata","adr"
@item .sbss
.section ".sbss","aurw"
@item .sdata
.section ".sdata","adrw"
@item .sdata2
.section ".sdata2","adr"
@item .stab
.section ".stab","dr"
@item .stabstr
.section ".stabstr","dr"
@item .text
.section ".text","acrx"
@item .tocd
.section ".tocd","adrw"
@end table
@section Known Problems
Some known problems of this module at the moment:
@itemize @minus
@item None.
@end itemize
@section Error Messages
This module has the following error messages:
@itemize @minus
@item 1001: mnemonic expected
@item 1002: invalid extension
@item 1003: no space before operands
@item 1004: too many closing parentheses
@item 1005: missing closing parentheses
@item 1006: missing operand
@item 1007: scratch at end of line
@item 1008: section flags expected
@item 1009: invalid data operand
@item 1010: memory flags expected
@item 1011: identifier expected
@item 1012: assembly aborted
@item 1013: unexpected "%s" without "%s"
@item 1014: pointless default value for required parameter <%s>
@item 1015: invalid section type ignored, assuming progbits
@item 1019: syntax error
@item 1021: section name expected
@item 1022: .fail %lld encountered
@item 1023: .fail %lld encountered
@item 1024: alignment too big
@end itemize
Reference in New Issue View Git Blame Copy Permalink