path: root/dasm2atasm.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "DASM2ATASM" 1 "2022-08-27" "0.2.0" "Urchlay's Atari 8-bit Tools"
.SH NAME
dasm2atasm \- Convert 6502 assembly source from dasm syntax to atasm or ca65 syntax.
.\" RST source for dasm2atasm(1) man page. Convert with:
.
.\" rst2man.py dasm2atasm.rst > dasm2atasm.1
.
.\" rst2man.py comes from the SBo development/docutils package.
.
.SH SYNOPSIS
.sp
dasm2atasm \fB\-[aclmr]\fP \fIinfile.dasm\fP [\fIoutfile.m65\fP]
.SH DESCRIPTION
.sp
\fBdasm2atasm\fP tries its best to convert \fBdasm\fP\(aqs syntax into something  that
\fBatasm\fP or \fBca65\fP can use.  Since \fBatasm\fP\(aqs syntax is 99% compatible with that
of \fBMAC/65\fP, \fBdasm2atasm\fP can be used for that as well.
.SH OPTIONS
.INDENT 0.0
.TP
.B  \-a
Atari EOLs. The output will have all UNIX \fB\en\fP characters replaced
with the EOL character \fB0x9b\fP used on the Atari.
.TP
.B  \-c
ca65 output. See \fBCA65 NOTES\fP, below.
.TP
.B  \-l
Line  numbers.  Each  line  in the output file will be numbered,
starting from \fB1000\fP and counting by \fB10\fP\&.
.TP
.B  \-m
MAC/65 mode. Shortcut for \fB\-a \-l\fP\&. Output  will  be  suitable  for
loading in MAC/65 with the ENTER command (not LOAD!).
.TP
.B  \-r
Process  include  files  recursively. This is done by spawning a
new \fBdasm2atasm\fP process for each included file, which is somewhat
resource\-intensive if there are lots of nested include files.
.UNINDENT
.SH NOTES
.sp
\fBdasm2atasm\fP is written in Perl, so it requires a Perl interpreter
to be available at runtime. If your installed perl binary is not located
at \fB/usr/bin/perl\fP, simply edit the \fBdasm2atasm\fP script and
change the location of perl in the first line (the one beginning with
\fI#!/usr/bin/perl\fP). Alternatively, you may run \fBdasm2atasm\fP with
a command like \fBperl dasm2atasm\fP, though the \fB\-r\fP option will
not work correctly in that case.
.sp
There are a few \fBdasm\fP pseudo\-ops that just aren\(aqt present in
\fBatasm\fP:
.INDENT 0.0
.TP
.B \fIprocessor\fP
\fBdasm\fP supports several target CPUs with different instruction sets,
and requires a \fBprocessor\fP directive in the source code to set the
CPU type. \fBatasm\fP only supports the 6502. \fBdasm2atasm\fP includes
the \fBprocessor\fP directive as a comment, in the output file.
echo
.sp
\fBdasm\fP\(aqs \fBecho\fP directive allows multiple arguments, and can interpolate
values. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
echo $100\-*, " bytes of zero page left"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBatasm\fP\(aqs closest equivalent is \fB\&.warn\fP, but it only accepts one
argument, which it treats as a constant string. \fBdasm2atasm\fP includes
all \fBecho\fPs in the input as comments in the output.
.TP
.B \fIseg, seg.u\fP
\fBatasm\fP doesn\(aqt support these at all. \fBdasm2atasm\fP\(aqs output will
include them as comments.
.UNINDENT
.sp
\fIsta.w, sty.w, stx.w\fP
.INDENT 0.0
.INDENT 3.5
\fBatasm\fP doesn\(aqt provide a way to force word addressing, when the operand
of a store instruction will allow zero page addressing to be used. You\(aqll
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.
.sp
\fBdasm2atasm\fP will convert any such instructions into \fB\&.byte\fP
pseudo\-ops that will generate the correct code. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
;;;;; dasm2atasm: was \(gasta.w COLUPF\(aq, using .byte to generate opcode
\&.byte $8d, <COLUPF, >COLUPF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBdasm\fP actually supports the \fI\&.w\fP and \fI\&.b\fP extensions to
most instructions and a few pseudo\-ops. \fBdasm2atasm\fP doesn\(aqt handle
this in the general case.
.UNINDENT
.UNINDENT
.sp
\fI\&. (dot) as program counter\fP
.INDENT 0.0
.INDENT 3.5
\fBdasm\fP allows the use of either \fB\&.\fP or \fB*\fP for the current
program counter. \fBatasm\fP only allows \fB*\fP\&. \fBdasm2atasm\fP doesn\(aqt
attempt to translate this, as it doesn\(aqt include a full expression parser.
.UNINDENT
.UNINDENT
.sp
\fI( ) (parentheses)\fP
.INDENT 0.0
.INDENT 3.5
\fBdasm\fP allows parentheses or square brackets in expressions:
\fI(1+2)*3\fP and \fI[1+2]*3\fP are equivalent. \fBatasm\fP
only allows square brackets. \fBdasm2atasm\fP does not attempt to
translate this currently, though a future version may.
.UNINDENT
.UNINDENT
.sp
\fImacro arguments\fP
.INDENT 0.0
.INDENT 3.5
\fBdasm\fP uses \fB{1}\fP, \fB{2}\fP, etc. to refer to macro arguments
within a macro definition. \fBatasm\fP uses \fB$1\fP, \fB$2\fP, etc.
\fBdasm2atasm\fP makes no attempt to translate these.
.UNINDENT
.UNINDENT
.SH CA65 NOTES
.sp
\fBca65\fP output is actually the same as the \fBatasm\fP output, with
the addition of \fB\&.FEATURE pc_assignment\fP and
\fB\&.FEATURE labels_without_colons\fP at the beginning of the source.
.sp
Most Atari source written with \fBdasm\fP is intended to be assembled
with the \fB\-f3\fP option (raw output). The equvalent option for
\fBatasm\fP is \fB\-r\fP, and for \fBca65\fP (and its linker,
\fBld65\fP) it is \fB\-t none\fP\&.
.sp
However, \fBca65\fP\(aqs linker (\fBld65\fP) will not correctly handle
files with multiple \fBORG\fP directives, when using \fB\-t none\fP\&. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
start ORG $0600 ; or *= $0600 in atasm
 ; 5 bytes of code here
 LDA #1 ; example code, doesn\(aqt 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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With \fBdasm \-f3\fP or \fBatasm \-r\fP, the output will be 261 bytes of
object code. With \fBca65 \-t none\fP and \fBld65 \-t none\fP, 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\(aqt include any Atari\-specific header information (e.g. binary
load headers as data bytes), then use \fB\-t atari\fP to have \fBca65\fP
generate the binary load headers (though as far as the author knows,
\fBca65\fP doesn\(aqt know how to generate other records such as Atari
boot disk or cartridge headers).
.SH COPYRIGHT
.sp
WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
.SH AUTHOR
.INDENT 0.0
.IP B. 3
Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&.
.UNINDENT
.SH SEE ALSO
.sp
\fBa8eol\fP(1),
\fBa8utf8\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBblob2c\fP(1),
\fBcart2xex\fP(1),
\fBdasm2atasm\fP(1),
\fBfenders\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBxexcat\fP(1),
\fBxexsplit\fP(1),
\fBxfd2atr\fP(1).
.sp
Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC  Reference
Manual\fP,  the  \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc.
.\" Generated by docutils manpage writer.
.