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