initial commit

1 files changed, 162 insertions, 0 deletions

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, >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