rewritten docs/Upgrade.txt

git-svn-id: https://svn.code.sf.net/p/acme-crossass/code-0/trunk@265 4df02467-bbd4-4a76-a152-e7ce94205b78
This commit is contained in:
marcobaye 2020-06-28 12:18:35 +00:00
parent 7038cecfec
commit ca6b6d8771
2 changed files with 104 additions and 84 deletions

View File

@ -149,8 +149,9 @@ Section: New in release 0.95.3
Added "c64dtv2" cpu type so you can use its SIR, SAC and BRA opcodes;
along with the undocumented ("illegal") opcodes of the 6510.
Added Martin Piper's "--msvc" patch so error output can be configured
to be in Visual Studio format.
Added "--msvc" CLI switch so error output can be configured to be in
Visual Studio format. Thanks to Martin Piper for writing this
patch!
Merged third-party patch (who wrote it?) to output label dump in VICE
format. Still needs work to be configurable about the types of
symbols actually output.

View File

@ -4,116 +4,135 @@
...the ACME Crossassembler for Multiple Environments
--- compatibility problems ---
--- upgrading from earlier versions ---
If you haven't used ACME before, you don't need to read this text.
It is only of use to people who upgraded from ACME 0.05 (or earlier)
to ACME 0.07 (or later).
You might encounter some slight incompatibilities: I have done a few
changes to ACME's workings.
Because backwards compatibility is the root of all evil (*g*), I did
not include any possibility to enforce the old behaviour. If one of
the following changes applies to your source files, assemble them with
this new release of ACME and then compare new and old output files.
Sorry for this inconvenience, but at least I think that there won't be
any further changes in the future.
----------------------------------------------------------------------
Section: Offset assembly / segment assembly
Upgrading from earlier releases to ACME release 0.95.2
----------------------------------------------------------------------
In 6510 mode, ACME now outputs 0x0b instead of 0x2b when assembling
the undocumented ("illegal") ANC #imm8 instruction. Both opcodes do
the same thing, this was only changed because all other mnemonics use
the smallest possible opcode as well.
Forcing the old behavior via the "--dialect" switch is not supported.
----------------------------------------------------------------------
Upgrading from earlier releases to ACME release 0.94.12
----------------------------------------------------------------------
The pseudo opcode "!for" has a new syntax. The old syntax still works,
but gives a warning.
You can use the "--dialect 0.94.8" CLI switch to get the old behavior.
----------------------------------------------------------------------
Upgrading from earlier releases to ACME release 0.94.8
----------------------------------------------------------------------
The pseudo opcodes "!cbm", "!subzone" and "!realpc" no longer give
warnings, but have now been disabled.
You can use the "--dialect 0.94.6" CLI switch to get the old behavior.
----------------------------------------------------------------------
Upgrading from earlier releases to ACME release 0.94.6
----------------------------------------------------------------------
The "to-the-power-of" operator ('^') is now right-associative, so
b^c^d will now give b^(c^d) instead of (b^c)^d
If you have never used the operator in this way, you don't need to
worry about it.
You can use the "--dialect 0.86" CLI switch to get the old behavior.
----------------------------------------------------------------------
Upgrading from earlier releases to ACME release 0.89
----------------------------------------------------------------------
The "logical shift right" operator has been changed. Note: This is
about ACME's expression parser and has nothing to do with the 6502
mnemonic called "LSR".
Older versions were supposed to work like this:
a = b >> c ; alias "LSR", do a logical shift right
But what they actually did depended on the compiler that was used to
create the ACME binary: many binaries did an "arithmetic shift right"
instead. This has now been fixed and changed to:
a = b >> c ; alias "ASR", do an arithmetic shift right
a = b >>> c ; alias "LSR", do a logical shift right
If you have never applied the old ">>"/"LSR" operator to a negative
value, you do not need to worry about this. If you have, please check
what you expected to happen in those instances (arithmetic or logical
shift) and update your source codes accordingly (use either ">>"/"ASR"
or ">>>"/"LSR").
Forcing the old behavior via the "--dialect" switch is not possible,
because as explained above, the old behavior was compiler-dependent
anyway.
----------------------------------------------------------------------
Upgrading from earlier releases to ACME release 0.07
----------------------------------------------------------------------
Re-defining the program counter via "* = NEW_VALUE" no longer starts
offset assembly. Instead, ACME will change its pointer into the output
buffer to the given value, so you can write your code in distinct
segments. These segments can be given in any order. After assembly,
ACME stores everything from the lowest address used to the highest
address used. Have a look at "AllPOs.txt" for an example on how to use
this facility.
Offset assembly is now done using a new pseudo opcode called
"!pseudopc". Have a look at "AllPOs.txt" for further information on
its syntax and usage.
The old way of just redefining the program counter by using more than
one "* = EXPRESSION" statements does something totally different now:
Whenever the program counter is redefined, ACME will actually change
its pointer into the output buffer, so you can write your code in
distinct segments. These segments can be given in any order. After
assembly, ACME stores everything from the lowest address used to the
highest address used. Have a look at "AllPOs.txt" for an example on
how to use this facility.
The pseudo opcode "!end" has been removed. Use "!eof" instead.
----------------------------------------------------------------------
Section: Argument order of MVP/MVN
----------------------------------------------------------------------
The mnemonic BIT can no longer be assembled without any argument. If
you want to insert the opcode only to mask the next instruction, use
!src <6502/std.a>
to get the definitions for these two macros:
+bit8 ; output $24 to mask following 1-byte command
+bit16 ; output $2c to mask following 2-byte command
The syntax of the 65816 opcodes MVN and MVP is usually given as
When using the 65816 cpu, ACME now uses the correct argument order for
the MVN and MVP mnemonics, which is:
mnemonic source_bank, destination_bank
MVN source_bank, destination_bank
All previous versions of ACME did it the other way round: First the
destination bank, then the source bank. This has been fixed, ACME now
uses the syntax given above.
----------------------------------------------------------------------
Section: Typecast
----------------------------------------------------------------------
You can use leading zeros to make ACME use a bigger addressing mode
than needed. Until now, this did not work when using labels. The
source code
label1 = $fa
Using leading zeroes in hexadecimal or binary values makes ACME use
bigger addressing modes than needed. This has now been extended to
symbols as well:
label2 = $00fa
lda $fa
lda $00fa
lda label1
lda label2
will be assembled to:
ad fa 00 lda $00fa
was assembled to:
Forcing the old behavior via the "--dialect" switch is not supported.
lda $fa
lda $00fa
lda $fa
lda $fa
Release 0.07 of ACME now correctly assembles the given source code to:
lda $fa
lda $00fa
lda $fa
lda $00fa
----------------------------------------------------------------------
Section: !endoffile
Upgrading from earlier releases to ACME release 0.04 beta
----------------------------------------------------------------------
Previous versions of ACME knew a pseudo opcode called "!end" that
marks the end of a source code file. Because the word "end" doesn't
actually specify *what* is about to end, I changed this to
"!endoffile". You can also use a short version, called "!eof". The old
PO "!end" no longer works.
The pseudo opcode "!module" has been removed. Use "!zone" instead.
Forcing the old behavior via the "--dialect" switch is not supported.
----------------------------------------------------------------------
Section: Using the BIT command without parameters
Upgrading from earlier releases to ACME release 0.03 beta
----------------------------------------------------------------------
Release 0.07 of ACME will complain if you try to assemble BIT without
any parameter. Previous versions did just output the byte $2c - a
commonly known trick to mask the following 2-byte command on the 6502
processor. If you still want to do this, use
It is no longer possible to have more than one label in a single line.
Forcing the old behavior via the "--dialect" switch is not supported.
!src <6502/std.a> ; parse library file
to include some standard macros. Then you can use
+bit8 ; output $24 to mask following 1-byte command
and
+bit16 ; output $2c to mask following 2-byte command
respectively.
That's all. Again, sorry for the inconvenience...