From e2ba8458a5cfdfacfaf103e7ba97d610afa6c970 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Mon, 29 Aug 2022 16:11:13 -0400 Subject: initial commit --- dasm2atasm.rst | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 dasm2atasm.rst (limited to 'dasm2atasm.rst') diff --git a/dasm2atasm.rst b/dasm2atasm.rst new file mode 100644 index 0000000..cc7b582 --- /dev/null +++ b/dasm2atasm.rst @@ -0,0 +1,162 @@ +.. RST source for dasm2atasm(1) man page. Convert with: +.. rst2man.py dasm2atasm.rst > dasm2atasm.1 +.. rst2man.py comes from the SBo development/docutils package. + +========== +dasm2atasm +========== + +---------------------------------------------------------------------- +Convert 6502 assembly source from dasm syntax to atasm or ca65 syntax. +---------------------------------------------------------------------- + +.. include:: manhdr.rst + +SYNOPSIS +======== + +dasm2atasm **-[aclmr]** *infile.dasm* [*outfile.m65*] + +DESCRIPTION +=========== + +**dasm2atasm** tries its best to convert **dasm**'s syntax into something that +**atasm** or **ca65** can use. Since **atasm**'s syntax is 99% compatible with that +of **MAC/65**, **dasm2atasm** can be used for that as well. + +OPTIONS +======= + +-a + Atari EOLs. The output will have all UNIX **\\n** characters replaced + with the EOL character **0x9b** used on the Atari. + +-c + ca65 output. See **CA65 NOTES**\, below. + +-l + Line numbers. Each line in the output file will be numbered, + starting from **1000** and counting by **10**. + +-m + MAC/65 mode. Shortcut for **-a -l**. Output will be suitable for + loading in MAC/65 with the ENTER command (not LOAD!). + +-r + Process include files recursively. This is done by spawning a + new **dasm2atasm** process for each included file, which is somewhat + resource-intensive if there are lots of nested include files. + +NOTES +===== + +**dasm2atasm** is written in Perl, so it requires a Perl interpreter +to be available at runtime. If your installed perl binary is not located +at **/usr/bin/perl**, simply edit the **dasm2atasm** script and +change the location of perl in the first line (the one beginning with +*#!/usr/bin/perl*). Alternatively, you may run **dasm2atasm** with +a command like **perl dasm2atasm**, though the **-r** option will +not work correctly in that case. + +There are a few **dasm** pseudo-ops that just aren't present in +**atasm**: + +*processor* + **dasm** supports several target CPUs with different instruction sets, + and requires a **processor** directive in the source code to set the + CPU type. **atasm** only supports the 6502. **dasm2atasm** includes + the **processor** directive as a comment, in the output file. + echo + + **dasm**'s **echo** directive allows multiple arguments, and can interpolate + values. Example:: + + echo $100-*, " bytes of zero page left" + + **atasm**'s closest equivalent is **.warn**, but it only accepts one + argument, which it treats as a constant string. **dasm2atasm** includes + all **echo**\s in the input as comments in the output. + +*seg, seg.u* + **atasm** doesn't support these at all. **dasm2atasm**'s output will + include them as comments. + +*sta.w, sty.w, stx.w* + + **atasm** doesn't provide a way to force word addressing, when the operand + of a store instruction will allow zero page addressing to be used. You'll + run into this a lot in Atari 2600 code, or any other 6502 code that has to + maintain sync with an external piece of hardware: using word addressing + causes the 6502 to use an extra CPU cycle, which is a commonly used + method of adding a 1-cycle delay. + + **dasm2atasm** will convert any such instructions into **.byte** + pseudo-ops that will generate the correct code. Example:: + + ;;;;; dasm2atasm: was `sta.w COLUPF', using .byte to generate opcode + .byte $8d, COLUPF + + **dasm** actually supports the *.w* and *.b* extensions to + most instructions and a few pseudo-ops. **dasm2atasm** doesn't handle + this in the general case. + +*. (dot) as program counter* + + **dasm** allows the use of either **.** or ***** for the current + program counter. **atasm** only allows *****. **dasm2atasm** doesn't + attempt to translate this, as it doesn't include a full expression parser. + +*( ) (parentheses)* + + **dasm** allows parentheses or square brackets in expressions: + *(1+2)\*3* and *[1+2]\*3* are equivalent. **atasm** + only allows square brackets. **dasm2atasm** does not attempt to + translate this currently, though a future version may. + +*macro arguments* + + **dasm** uses **{1}**, **{2}**, etc. to refer to macro arguments + within a macro definition. **atasm** uses **$1**, **$2**, etc. + **dasm2atasm** makes no attempt to translate these. + +CA65 NOTES +========== + +**ca65** output is actually the same as the **atasm** output, with +the addition of **.FEATURE pc_assignment** and +**.FEATURE labels_without_colons** at the beginning of the source. + +Most Atari source written with **dasm** is intended to be assembled +with the **-f3** option (raw output). The equvalent option for +**atasm** is **-r**, and for **ca65** (and its linker, +**ld65**) it is **-t none**. + +However, **ca65**'s linker (**ld65**) will not correctly handle +files with multiple **ORG** directives, when using **-t none**. Example:: + + start ORG $0600 ; or *= $0600 in atasm + ; 5 bytes of code here + LDA #1 ; example code, doesn't do anything useful + STA 0 + RTS + + ; dasm or atasm will include 251 bytes of filler here + ; (dasm fills with $00 by default; atasm fills with $ff) + + ORG $0700 ; or *= $0700 in atasm + ; 5 more bytes of code here + LDA #2 + STA 1 + RTS + +With **dasm -f3** or **atasm -r**, the output will be 261 bytes of +object code. With **ca65 -t none** and **ld65 -t none**, the filler +bytes will not be included, and the output will be only 10 bytes long. +The correct solution to this would be to rewrite the code so that it +doesn't include any Atari-specific header information (e.g. binary +load headers as data bytes), then use **-t atari** to have **ca65** +generate the binary load headers (though as far as the author knows, +**ca65** doesn't know how to generate other records such as Atari +boot disk or cartridge headers). + +.. include:: manftr.rst -- cgit v1.2.3