mirror of
https://github.com/pfusik/xasm.git
synced 2024-12-21 09:29:39 +00:00
Reword the manual.
This commit is contained in:
Piotr Fusik
parent
1a90ca04d3
commit
8c7ef1a922
179
xasm.1.asciidoc
179
xasm.1.asciidoc
@ -24,31 +24,30 @@ OPTIONS
|
||||
-------
|
||||
|
||||
*-c*::
|
||||
Specifies that lines skipped due to a false condition
|
||||
should be included in the listing file.
|
||||
The listing should include conditionally skipped lines.
|
||||
|
||||
[[new_deflabel]]*-d* 'LABEL'='VALUE'::
|
||||
Defines a label.
|
||||
'LABEL' should be a valid label name.
|
||||
'VALUE' may be any expression (may reference to labels defined in source files).
|
||||
You may use several *-d* options to define many labels from the command line.
|
||||
'VALUE' may be any expression (potentially referencing labels defined in source files).
|
||||
You may use several *-d* options to define many labels on the command line.
|
||||
|
||||
*-i*::
|
||||
Excludes included files from the listing file.
|
||||
The listing file should exclude included files.
|
||||
|
||||
*-l* '[LISTING_FILE]'::
|
||||
Generates listing file.
|
||||
Generates a listing file.
|
||||
If 'LISTING_FILE' is omitted, the listing filename
|
||||
is 'SOURCE_FILE' with the extension changed to `.lst`.
|
||||
|
||||
[[new_makefile]]*-M*::
|
||||
Prints a rule for use in a `Makefile`.
|
||||
Prints a `Makefile` rule.
|
||||
First line of the rule lists 'OBJECT_FILE' as the target of the rule
|
||||
and all source files (including the ones specified with `icl` and `ins` directives)
|
||||
as dependencies. The second line contains the command line with `OBJECT_FILE`
|
||||
replaced by the *make* macro `$@` and `SOURCE_FILE` replaced by the macro `$<`.
|
||||
and all source files (including the ones specified with `icl` and `ins`) as dependencies.
|
||||
The second line contains the command line with 'OBJECT_FILE'
|
||||
replaced by the *make* macro `$@` and 'SOURCE_FILE' replaced by the macro `$<`.
|
||||
Dollars in the command line are doubled.
|
||||
Your `make` or shell may require further escaping.
|
||||
Your *make* or shell may require further escaping.
|
||||
|
||||
*-o* 'OBJECT_FILE'::
|
||||
Sets output file name.
|
||||
@ -60,12 +59,12 @@ Prints absolute paths in listing and error messages.
|
||||
[[new_quiet]]*-q*::
|
||||
Quiet mode. Prevents *xasm* from printing its banner and compilation summary.
|
||||
|
||||
*-t*' [LABEL_FILE]'::
|
||||
Generates label table.
|
||||
*-t* '[LABEL_FILE]'::
|
||||
Generates a label table.
|
||||
If 'LABEL_FILE' is omitted then the table is appended at the end of the listing.
|
||||
|
||||
[[new_unlabels]]*-u*::
|
||||
Issues a warning message for each label whose value is unused.
|
||||
Issues warnings for unreferenced labels.
|
||||
|
||||
Alternatively, you may use DOS-style options, for example:
|
||||
|
||||
@ -73,7 +72,7 @@ Alternatively, you may use DOS-style options, for example:
|
||||
xasm /i /d:DEBUG=1 /l:listing.lst source.asx
|
||||
-----------------------------------------------------------
|
||||
|
||||
These are however deprecated because they are incompatible with MSYS.
|
||||
These are deprecated because they are incompatible with https://www.msys2.org[MSYS2].
|
||||
|
||||
SYNTAX
|
||||
------
|
||||
@ -83,22 +82,22 @@ LF, CR, CR/LF and Atari ($9b) line terminators are supported.
|
||||
Labels and instructions are case-insensitive.
|
||||
|
||||
*xasm* is backward compatible with Quick Assembler.
|
||||
To compile QA sources with *xasm*, simply replace ATASCII-specific characters
|
||||
with their integer codes. You also have to update all `OPT` directives,
|
||||
but usually you can simply remove them.
|
||||
To compile QA sources with *xasm*, simply replace ATASCII characters
|
||||
in string literals with the corresponding integers.
|
||||
Also update all `OPT` directives, but often you can omit them.
|
||||
|
||||
'Label' is a symbol that represents a signed 32-bit integer.
|
||||
A 'label' is a symbol that represents a signed 32-bit integer.
|
||||
You define a label by putting its name at the beginning of a line
|
||||
(with no spaces before).
|
||||
The label will be assigned the current value of the 'origin counter'
|
||||
(i.e. the address of the compiled instruction),
|
||||
unless you use it with the `EQU` directive where it is assigned
|
||||
the value of the `EQU` argument.
|
||||
(that is, the address of the compiled instruction),
|
||||
unless you use it with the `EQU` directive to assign the specified value.
|
||||
|
||||
Any label name starting with `?` (question mark) refers to a 'local label'.
|
||||
[[new_locallabel]]
|
||||
Any label name starting with a `?` (question mark) is a 'local label'.
|
||||
It is implicitly prefixed with the name of the most recently defined
|
||||
'global label' (i.e. a label without any `?` in name),
|
||||
and stays visible until another global label is defined.
|
||||
'global label' (that is, a label without any `?` in name),
|
||||
and remains visible until another global label is defined.
|
||||
It is still possible to access a local label from anywhere in the source
|
||||
by specifying its full name.
|
||||
Local labels provide a way to reuse common, short label names while keeping
|
||||
@ -117,7 +116,7 @@ bar lda baz
|
||||
bne ?loop ; ERROR: Undeclared label: BAR?LOOP
|
||||
----
|
||||
|
||||
Instructions and directives must be preceded with some whitespace.
|
||||
'Instructions' and 'directives' must be preceded with some whitespace.
|
||||
Without leading whitespace they are treated as label names.
|
||||
For example:
|
||||
----
|
||||
@ -130,7 +129,7 @@ nop
|
||||
(without leading space) defines a label called `nop`.
|
||||
|
||||
Whole-line comments must start with a semicolon, an asterisk or a pipe,
|
||||
with optional label definition and spaces before.
|
||||
with an optional label definition and spaces before.
|
||||
Here are examples of whole-line comments:
|
||||
--------------------
|
||||
; this is a comment
|
||||
@ -144,12 +143,12 @@ To assemble a single line several times,
|
||||
precede the repeat count with a colon, for example:
|
||||
-----------------
|
||||
:4 asl @
|
||||
mask_lookup :32 dta $80,$40,$20,$10,8,4,2,1
|
||||
mask_lookup :32 dta $80,$40,$20,$10,$08,$04,$02,$01
|
||||
-----------------
|
||||
|
||||
In lines with instructions or directives, a comment starts immediately
|
||||
after the instruction/directive has been successfully parsed.
|
||||
That is, in such lines *xasm* does not require a special character
|
||||
That is, in such lines *xasm* does 'not' require any special character
|
||||
to start a comment.
|
||||
-------------------------------------------------------------
|
||||
lda foo ; this is a comment
|
||||
@ -183,14 +182,14 @@ for 6502 indirect addressing.
|
||||
|
||||
A number is:
|
||||
|
||||
- a 32-bit decimal integer, e.g. `-12345`
|
||||
- a 32-bit decimal integer, e.g. `12345`
|
||||
- a 32-bit hexadecimal integer, e.g. `$abcd`
|
||||
- a 32-bit binary integer, e.g. `%10100101`
|
||||
- an ASCII character, e.g. `'a'` or `"a"`
|
||||
- origin counter: `*`
|
||||
- the current value of the origin counter: `*`
|
||||
- a hardware register (see below), e.g. `^4e`
|
||||
- [[new_opcode]]an opcode (see below), e.g. `{lda #0}` is `$a9`
|
||||
- [[new_linecnt]]the line repeat counter (see below): `#`
|
||||
- [[new_linecnt]]the current value of the line repeat counter (see below): `#`
|
||||
|
||||
Abbreviations of Atari hardware registers are provided
|
||||
to save two characters (`$d40e` vs `^4e`)
|
||||
@ -258,7 +257,8 @@ The following 'unary operators' are supported:
|
||||
- `<` Low (extracts the low byte)
|
||||
- `>` High (extracts the high byte)
|
||||
|
||||
The operator precedence is following:
|
||||
Although the operators are similar to those used in C, C++, C# and Java,
|
||||
their precedence is different:
|
||||
|
||||
- first: `[]` (brackets)
|
||||
- `+ - ~ < >` (unary)
|
||||
@ -269,19 +269,16 @@ The operator precedence is following:
|
||||
- `&&` (binary)
|
||||
- last: `||` (binary)
|
||||
|
||||
NOTE: Although the operators are similar to those used in C, C++ and Java,
|
||||
their priorities are different.
|
||||
|
||||
Compare and logical operators assume that zero is false and a non-zero
|
||||
is true. They return 1 for true.
|
||||
The compare and logical operators assume that zero is false
|
||||
and a non-zero is true. They return 1 for true.
|
||||
|
||||
Expressions are calculated in signed 32-bit arithmetic.
|
||||
"Arithmetic overflow" error signals overflow of the 32-bit range.
|
||||
An overflow is signalled with an "Arithmetic overflow" error.
|
||||
|
||||
DIRECTIVES
|
||||
----------
|
||||
|
||||
*EQU* - assign value of expression to label::
|
||||
*EQU* - assign the value of an expression to a label::
|
||||
|
||||
Examples:
|
||||
+
|
||||
@ -294,16 +291,16 @@ here equ *
|
||||
|
||||
Six options are available:
|
||||
|
||||
- `F` - fill the space between memory areas with `$FF`
|
||||
- `G` - Atari 5200 mode for hardware register abbreviations
|
||||
- `F` - fill the space between noncontiguous memory areas with `$FF` bytes
|
||||
- `G` - Atari 5200 mode for hardware register abbreviations (`^xx`)
|
||||
- `H` - generate Atari executable headers
|
||||
- `L` - write to the listing
|
||||
- `O` - write to the object file
|
||||
- `L` - write the listing
|
||||
- `O` - write the object file
|
||||
- `U` - warn of unused labels
|
||||
|
||||
+
|
||||
You can turn any of these on or off.
|
||||
The default (if no `OPT` specified) is `opt f-g-h+l+o+u+`.
|
||||
The default (before the first `OPT`) is `opt f-g-h+l+o+u+`.
|
||||
For compatibility with MADS, `opt ?+` is accepted and ignored.
|
||||
Examples:
|
||||
+
|
||||
@ -314,13 +311,13 @@ Examples:
|
||||
opt ?+ MADS compatibility, no effect
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
*ORG* - change value of the origin counter::
|
||||
*ORG* - set the origin counter::
|
||||
|
||||
If Atari executable headers are enabled, you can include an operand prefix:
|
||||
If Atari executable headers are enabled (`opt h+`), you can include an operand prefix:
|
||||
|
||||
- `a:` starts a new block even if it's superfluous
|
||||
because the new address equals the current address.
|
||||
- `f:` is same as `a:`, but additionally generates a double-`$FF` prefix
|
||||
- `f:` is same as `a:`, but additionally generates a double `$FF` prefix
|
||||
before the new header. This prefix is automatically generated
|
||||
at the beginning of the file (no need to include `f:` in the first `ORG`).
|
||||
|
||||
@ -337,10 +334,10 @@ In the latter example `table` points to 100 bytes
|
||||
of uninitialized data (label is assigned with `*`
|
||||
before the `ORG` directive is executed).
|
||||
+
|
||||
[[new_orgr]]Starting with version 2.6.0, *xasm* supports code
|
||||
that is relocated at run time. Let's say you want your code
|
||||
to be located on page zero. You can't normally load it directly into this
|
||||
place, so you load it at a different address and then move in your program.
|
||||
[[new_orgr]]*xasm* supports code that is relocated at run time.
|
||||
Let's say you want your code to be located on page zero for best performance.
|
||||
You can't safely load it directly into this place,
|
||||
so you load it at a different address and then move in your program.
|
||||
`org r:` changes the address that it used for code generation
|
||||
but not the address used for generating Atari executable headers.
|
||||
Example:
|
||||
@ -434,18 +431,18 @@ Examples:
|
||||
icl 'lib/fileio'
|
||||
-----------------
|
||||
+
|
||||
NOTE: for portability, use only relative paths and slash as the separator.
|
||||
This way your sources will compile under Windows and Linux.
|
||||
NOTE: For Windows/macOS/Linux portability use relative paths
|
||||
and slashes as path separators.
|
||||
|
||||
*END* - end assembling file::
|
||||
*END* - end this source file::
|
||||
|
||||
May be used if the source file ends with something which shouldn't
|
||||
be read by *xasm* (e.g. your notes).
|
||||
|
||||
*INS* - insert contents of file::
|
||||
*INS* - insert binary file contents::
|
||||
|
||||
Copies every byte of the specified file into the object file and updates
|
||||
the origin counter, as if these bytes were written using `DTA`.
|
||||
the origin counter, as if these bytes were specified in a `DTA`.
|
||||
You may specify a range of the file to insert. The syntax is:
|
||||
+
|
||||
-----------------------------
|
||||
@ -458,11 +455,11 @@ Examples:
|
||||
+
|
||||
-----------------------------------------------
|
||||
ins 'picture.raw'
|
||||
ins 'file',-256 insert last 256 bytes of file
|
||||
ins 'file',10,10 insert bytes 10..19 of file
|
||||
ins 'file',-256 ; insert last 256 bytes of file
|
||||
ins 'file',10,10 ; insert bytes 10..19 of file
|
||||
-----------------------------------------------
|
||||
|
||||
*RUN* - set run address in the Atari executable format::
|
||||
*RUN* - set the Atari executable run address::
|
||||
|
||||
+
|
||||
---------
|
||||
@ -476,7 +473,7 @@ is equivalent to:
|
||||
dta a(main)
|
||||
------------
|
||||
|
||||
*INI* - set init address in the Atari executable format::
|
||||
*INI* - set the Atari executable init address::
|
||||
|
||||
Example:
|
||||
+
|
||||
@ -484,7 +481,7 @@ Example:
|
||||
ini showloadingpic
|
||||
------------
|
||||
|
||||
*ERT* - generate error if expression evaluates to true::
|
||||
*ERT* - abort the assembly with an error if an expression is true::
|
||||
|
||||
Examples:
|
||||
+
|
||||
@ -516,7 +513,7 @@ widescr equ 1
|
||||
sta $22f
|
||||
-------------
|
||||
+
|
||||
NOTE: The above example may be rewritten using the 'repeat line' feature:
|
||||
NOTE: Alternatively, the above example can be written using the 'repeat line' feature:
|
||||
+
|
||||
--------------------------
|
||||
noscr equ 1
|
||||
@ -529,7 +526,7 @@ widescr equ 1
|
||||
|
||||
PSEUDO COMMANDS
|
||||
---------------
|
||||
'Pseudo commands' are built-in macros. There are no user-defined macros in *xasm*.
|
||||
'Pseudo commands' are built-in macros. There are 'no' user-defined macros in *xasm*.
|
||||
|
||||
*ADD* - add without carry::
|
||||
|
||||
@ -540,7 +537,7 @@ to use a `CLC` before `ADC` for every simple addition.
|
||||
|
||||
*SUB* - subtract::
|
||||
|
||||
It is `SEC` and `SBC`.
|
||||
It is `SEC` followed by `SBC`.
|
||||
|
||||
[[new_repskip]]*RCC, RCS, REQ, RMI, RNE, RPL, RVC, RVS* - conditional repeat::
|
||||
|
||||
@ -558,11 +555,11 @@ The above code copies a 256-byte memory block from $500 to $600.
|
||||
Here is the same written with standard 6502 commands only:
|
||||
+
|
||||
--------------------
|
||||
ldx #0
|
||||
ldx #0
|
||||
copy_loop lda $500,x
|
||||
sta $600,x
|
||||
inx
|
||||
bne copy_loop
|
||||
sta $600,x
|
||||
inx
|
||||
bne copy_loop
|
||||
--------------------
|
||||
|
||||
*SCC, SCS, SEQ, SMI, SNE, SPL, SVC, SVS* - conditional skip::
|
||||
@ -583,7 +580,7 @@ In the above example the 16-bit variable `ptr` is incremented by 40.
|
||||
*JCC, JCS, JEQ, JMI, JNE, JPL, JVC, JVS* - conditional jump::
|
||||
|
||||
These are long branches. While standard branches (such as `BNE`)
|
||||
have range of -128..+127, these jumps have range of 64 kB.
|
||||
have range of -128..+127 bytes, these jumps have range of 64 KB.
|
||||
For example:
|
||||
+
|
||||
---------
|
||||
@ -612,7 +609,7 @@ is equivalent to:
|
||||
sne:inc dest+1
|
||||
---------------
|
||||
|
||||
*MVA, MVX, MVY* - move byte using accumulator, X or Y::
|
||||
*MVA, MVX, MVY* - move a byte using the accumulator, X or Y::
|
||||
|
||||
Each of these pseudo commands requires two operands
|
||||
and substitutes two commands:
|
||||
@ -651,7 +648,7 @@ When `<immed` equals `>immed` and `immed` is not forward-referenced,
|
||||
sta dest+1
|
||||
----------------
|
||||
+
|
||||
If possible, `MWX` and `MWY` use increment/decrement commands.
|
||||
If possible, `MWX` and `MWY` use increment/decrement instructions.
|
||||
For example, `mwx #1 dest` expands to:
|
||||
+
|
||||
-----------
|
||||
@ -664,11 +661,11 @@ For example, `mwx #1 dest` expands to:
|
||||
ADDRESSING MODES
|
||||
----------------
|
||||
|
||||
All addressing modes are entered in the standard 6502 convention
|
||||
except for the accumulator addressing mode,
|
||||
which should be marked with the `@` character (as in Quick Assembler).
|
||||
Addressing modes are entered in the standard 6502 convention.
|
||||
An exception is the accumulator mode marked with the `@` character
|
||||
for compatibility with Quick Assembler.
|
||||
|
||||
For Quick Assembler compatibility, there are two extra immediate
|
||||
Also for Quick Assembler compatibility there are two extra immediate
|
||||
addressing modes: `<` and `>`, which use the low/high byte of a 16-bit word constant.
|
||||
Unlike in Quick Assembler, you can alternatively use
|
||||
the more common syntax: `#<` and `#>`.
|
||||
@ -725,7 +722,7 @@ Version 3.1.0 (2014-07-20)
|
||||
- `INS` can be repeated (suggested by Marek Pavlik) and taken "opcode" of
|
||||
- `OPT U-` disables <<new_unlabels,*/u*>> unused label warnings
|
||||
(suggested by Marek Pavlik)
|
||||
- if the file to be included cannot be opened, report error in the `ICL` line
|
||||
- if the file to be included cannot be opened, report an error in the `ICL` line
|
||||
(suggested by Peter Dell)
|
||||
- removed duplicate filenames for <<new_makefile,*/M*>>
|
||||
- implemented <<new_fullpaths,*/p*>> outside Windows
|
||||
@ -738,7 +735,7 @@ Version 3.0.2 (2009-10-17)
|
||||
for backward branches
|
||||
- <<new_makefile,new command-line option */M* prints a Makefile rule>>
|
||||
- command-line options are now case-insensitive
|
||||
- on Windows error messages are printed in red, warnings in yellow
|
||||
- on Windows, error messages are printed in red, warnings in yellow
|
||||
|
||||
Version 3.0.1 (2007-04-22)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -751,9 +748,9 @@ Version 3.0.0 (2005-05-22)
|
||||
- rewritten from the x86 assembly language to the
|
||||
http://dlang.org/[D programming language] - Linux version
|
||||
is now available and DOS is no longer supported
|
||||
- no limits for line length, number of `ICLs`, `ORGs`,`IFTs` and labels
|
||||
- no limits on line length, number of `ICLs`, `ORGs`,`IFTs` and labels
|
||||
- Unix-style command-line options are supported
|
||||
- */e* option is no longer supported
|
||||
- the */e* option is removed
|
||||
- the label table is now sorted alphabetically
|
||||
|
||||
Version 2.6.1 (2005-05-21)
|
||||
@ -782,8 +779,7 @@ Version 2.6.0 (2005-02-07)
|
||||
- <<new_linecnt,line repeat counter>>
|
||||
- label values are now 32-bit, not just 17-bit
|
||||
- command-line options */n* and */s* are no longer supported
|
||||
- fatal I/O errors (such as floppy not ready) no longer print the annoying
|
||||
"Abort, Retry, Ignore" message
|
||||
- fatal I/O errors no longer print the annoying "Abort, Retry, Ignore" message
|
||||
|
||||
Version 2.5.2 (2002-10-03)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -798,7 +794,7 @@ Version 2.5.1 (2002-08-21)
|
||||
|
||||
Version 2.5 (2002-07-08)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
- fixed another bug, very similar to the previous one, e.g.
|
||||
- fixed another bug similar to the previous one, for example:
|
||||
+
|
||||
----------
|
||||
ift 0
|
||||
@ -830,14 +826,13 @@ Version 2.4 (2002-05-22)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
- fixed incorrect unary operator precedence
|
||||
- fixed wrong label value after a skip pseudo command
|
||||
- the assembler is .EXE (.COM caused problems with DJGPP *make* due
|
||||
- the assembler is an .EXE (.COM caused problems with DJGPP *make* due
|
||||
to a bug in the DJGPP runtime)
|
||||
- the assembler executable is not compressed (so it occupies less space in the ZIP)
|
||||
- improved command-line parsing: options may be used before source file name,
|
||||
tab character is a valid separator, slash may be used as a directory separator
|
||||
- the assembler executable is no longer compressed
|
||||
- improved command-line parsing: options may be used before the source file name,
|
||||
tab is a valid separator, slash may be used as a directory separator
|
||||
- error and warning messages are written to stderr, not stdout
|
||||
- added `==` (equals) operator, which is equivalent to `=`,
|
||||
but more natural for C/C++/Java programmers
|
||||
- added `==` (equals) operator, equivalent to `=`, but familiar to C/C++/Java programmers
|
||||
- <<new_deflabel,added `/d:label=value` option: define a label>>
|
||||
- <<new_fullpaths,added `/p` option: print full paths
|
||||
in listing and error messages>>
|
||||
@ -865,11 +860,11 @@ Version 2.2 (1999-09-10)
|
||||
- fixed `ICL` in last line
|
||||
- fixed `OPT H-H+`
|
||||
- fixed first `ORG *`
|
||||
- no need to set origin counter until it's used
|
||||
- no need to set the origin counter until it's needed
|
||||
- allow Unix, Macintosh and Atari EOLs
|
||||
- value of 'true' changed to 1
|
||||
- command-line option to set environment variables on error
|
||||
- commane-line option to assemble only if source is newer than object file
|
||||
- commane-line option to assemble only if the source is newer than the object file
|
||||
- <<new_opcode,opcode extracting>>
|
||||
- <<new_linerep,repeat line>>
|
||||
- <<new_pairing,two instructions in line>>
|
||||
@ -878,7 +873,7 @@ Version 2.2 (1999-09-10)
|
||||
|
||||
Version 2.0 (1998-11-12)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
- fixed: name of object file was truncated
|
||||
- fixed: object filename was truncated
|
||||
- fixed forward references in `EQU` and `DTA`
|
||||
- fixed hex numbers
|
||||
- `.OBX` is now the default extension for the object file
|
||||
|
||||
Loading…
Reference in New Issue
Block a user