6502
/
Ophis
mirror of https://github.com/michaelcmartin/Ophis.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update manuals

This commit is contained in:
Michael Martin 2012-06-12 23:13:55 -07:00
parent 51583ce5e0
commit 0faae3f5b4
4 changed files with 123 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
doc/cmdref.sgm
View File

@ -117,7 +117,7 @@
<listitem><para><literal>&lt;$D000+32</literal> evaluates to $20</para></listitem>
<listitem><para><literal>&gt;$D000+32</literal> evaluates to $F0</para></listitem>
<listitem><para><literal>&gt;[$D000+32]</literal> evaluates to $D0</para></listitem>
<listitem><para><literal>&gt;$D000-275</literal> evaluates to $CE</para></listitem>
<listitem><para><literal>&gt;[$D000-275]</literal> evaluates to $CE</para></listitem>
</itemizedlist>
</section>
<section>
@ -371,15 +371,16 @@
</listitem>
<listitem>
<para>
<literal>.advance</literal> <emphasis>address</emphasis>:
Forces the program counter to
be <emphasis>address</emphasis>. Unlike
<literal>.advance</literal> <emphasis>address</emphasis>
[, <emphasis>filler</emphasis>]: Forces the program
counter to be <emphasis>address</emphasis>. Unlike
the <literal>.org</literal>
directive, <literal>.advance</literal> outputs zeroes
until the program counter reaches a specified
address. Attempting to <literal>.advance</literal> to a
point behind the current program counter is an
assemble-time error.
directive, <literal>.advance</literal> outputs bytes (the
value of <emphasis>filler</emphasis>, or zeroes if it is
unspecified) until the program counter reaches a
specified address. Attempting
to <literal>.advance</literal> to a point behind the
current program counter is an assemble-time error.
</para>
</listitem>
<listitem>
@ -423,10 +424,14 @@
</listitem>
<listitem>
<para>
<literal>.incbin</literal> <emphasis>filename</emphasis>:
Inserts the contents of the file specified as binary
data. Use it to include graphics information, precompiled
code, or other non-assembler data.
<literal>.incbin</literal> <emphasis>filename</emphasis>
[, <emphasis>offset</emphasis>
[, <emphasis>length</emphasis>]]: Inserts the contents of
the file specified as binary data. Use it to include
graphics information, precompiled code, or other
non-assembler data. You may also optionally specify an
index to start including from, or a length to only
include a subset.
</para>
</listitem>
<listitem>

121
doc/preface.sgm
View File

@ -1,49 +1,81 @@
<preface>
<title>Preface</title>
<para>
The Ophis project started on a lark back in 2001. My graduate
studies required me to learn Perl and Python, and I'd been playing
around with Commodore 64 emulators in my spare time, so I decided
to learn both languages by writing a simple cross-assembler for
the 6502 chip the C-64 used in both.
Ophis is an assembler for the 6502 microprocessor - the famous
chip used in the vast majority of the classic 8-bit computers and
consoles. Its primary design goals are code readability and output
flexibility - Ophis has successfully been used to create programs
for the Nintendo Entertainment System, the Atari 2600, and the
Commodore 64.
</para>
<para>
The Perl one&mdash;uncreatively
dubbed <quote>Perl65</quote>&mdash;was quickly abandoned, but the
Python one saw more work. When it came time to name it, one of the
things I had been hoping to do with the assembler was to produce
working Apple II programs. <quote>Ophis</quote> is Greek
for <quote>snake</quote>, and a number of traditions also use it
as the actual <emphasis>name</emphasis> of the serpent in the
Garden of Eden. So, Pythons, snakes, and stories involving really
old Apples all combined to name the
assembler.<footnote><para>Ironically, cross-platform development
for the Apple II is extremely difficult, and while Ophis has been
very successfully used to develop code for the Commodore 64,
Nintendo Entertainment System, and Atari 2600, it has yet to
actually be deployed on any of the Apples which inspired its
name.</para></footnote>
Ophis's syntax is noticably different from the formats
traditionally used for these chips; it draws its syntactic
inspiration primarily from the assemblers for more modern chips,
where the role of tokens is determined more by what they're made
of and their grammatical location on a line rather than their
absolute position on a line. It also borrows the sophisticated
methods of tracking the location of labels when writing relinkable
code&mdash;Ophis expects that the final output it produces will have
only a vague resemblance to the memory image when loaded. Most of
the alternatives when Ophis was first designed would place
instructions and data into a memory map and then dump that map.
</para>
<para>
Ophis slowly grew in scope and power over the years, and by 2005
was a very powerful, flexible macro assembler that saw more use
than I'd expect. In 2007 Ophis 1.0 was formally released.
However, Ophis was written for Python 2.1 and this became more and
more untenable as time has gone by. As I started receiving patches
for parts of Ophis, and as I used it for some projects of my own,
it became clear that Ophis needed to be modernized and to become
better able to interoperate with other toolchains. It was this
process that led to Ophis 2.
</para>
<para>
This is an updated edition of <emphasis>Programming With
Ophis</emphasis>, including documentation for all new features
introduced and expanding the examples to include simple
demonstration programs for platforms besides the Commodore 64. It
also includes updated versions of the <emphasis>To HLL and
Back</emphasis> essays I wrote using Ophis and Perl65 as example
languages.
That said, there remain many actively used 6502 assemblers out
there. If you're already a seasoned 6502 assembly programmer, or
want to get your old sources built again, Ophis is likely not for
you&mdash;however, if you are writing new code, or are new to the
chip while still having other experience, then Ophis is a tool
built with you in mind.
</para>
<section>
<title>History of the project</title>
<para>
The Ophis project started on a lark back in 2001. My graduate
studies required me to learn Perl and Python, and I'd been
playing around with Commodore 64 emulators in my spare time, so
I decided to learn both languages by writing a simple
cross-assembler for the 6502 chip the C64 used in both.
</para>
<para>
The Perl one&mdash;uncreatively
dubbed <quote>Perl65</quote>&mdash;was quickly abandoned, but
the Python one saw more work. When it came time to name it, one
of the things I had been hoping to do with the assembler was to
produce working Apple II programs. <quote>Ophis</quote> is
Greek for <quote>snake</quote>, and a number of traditions also
use it as the actual <emphasis>name</emphasis> of the serpent in
the Garden of Eden. So, Pythons, snakes, and stories involving
really old Apples all combined to name the
assembler.<footnote><para>Ironically, cross-platform development
for the Apple II is extremely difficult, and while Ophis has
been very successfully used to develop code for the Commodore
64, Nintendo Entertainment System, and Atari 2600, it has yet to
actually be deployed on any of the Apples which inspired its
name.</para></footnote>
</para>
<para>
Ophis slowly grew in scope and power over the years, and by 2005
was a very powerful, flexible macro assembler that saw more use
than I'd expect. In 2007 Ophis 1.0 was formally released.
However, Ophis was written for Python 2.1 and this became more
and more untenable as time has gone by. As I started receiving
patches for parts of Ophis, and as I used it for some projects
of my own, it became clear that Ophis needed to be modernized
and to become better able to interoperate with other
toolchains. It was this process that led to Ophis 2.
</para>
<para>
This is an updated edition of <emphasis>Programming With
Ophis</emphasis>, including documentation for all new features
introduced and expanding the examples to include simple
demonstration programs for platforms besides the Commodore
64. It also includes updated versions of the <emphasis>To HLL
and Back</emphasis> essays I wrote using Ophis and Perl65 as
example languages.
</para>
</section>
<section>
<title>Getting a copy of Ophis</title>
@ -70,6 +102,13 @@
Windows installer will use this. In this case, all you need to
do is have <command>ophis.exe</command> in your path.
</para>
<para>
If you are working on a system with Python installed but to
which you do not wish to install software, there is also a
standalone pure-Python edition with an ophis.py script. This may
be placed anywhere and running ophis.py will temporarily set the
library path to point to your directory.
</para>
</section>
<section>
@ -81,7 +120,11 @@
The code in this book is available in
the <literal>examples/</literal> subdirectory, while extra
examples will be in subdirectories of their own with brief
descriptions.
descriptions. They are largely all simple <quote>Hello
world</quote> applications, designed mainly to demonstrate how
to package assembled binaries into forms that emulators or ROM
loaders can use. They are not primarily intended as tutorials
for writing for the platforms themselves.
</para>
<para>
Most examples will require use of <emphasis>platform

28
doc/tutor1.sgm
View File

@ -144,26 +144,30 @@ next: .word 0 ; End of program
assembler know right away where everything is supposed to
be.
</para></listitem>
<listitem><para> Instead of hardcoding in the value $080C, we
instead use a label to identify the location it's pointing
to. Ophis will compute the address
of <literal>next</literal> and put that value in as data.
We also describe the line number in decimal since BASIC
line numbers generally <emphasis>are</emphasis> in decimal.
Labels are defined by putting their name, then a colon, as
seen in the definition of <literal>next</literal>.
<listitem><para>
Instead of hardcoding in the value $080C, we instead use a
label to identify the location it's pointing to. Ophis
will compute the address of <literal>next</literal> and
put that value in as data. We also describe the line
number in decimal since BASIC line numbers
generally <emphasis>are</emphasis> in decimal. Labels are
defined by putting their name, then a colon, as seen in
the definition of <literal>next</literal>.
</para></listitem>
<listitem><para>
Instead of putting in the hex codes for the string part of
the BASIC code, we included the string directly. Each
character in the string becomes one byte.
Instead of putting in the hex codes for the string part of
the BASIC code, we included the string directly. Each
character in the string becomes one byte.
</para></listitem>
<listitem><para>
Instead of adding the buffer ourselves, we
used <literal>.advance</literal>, which outputs zeros until
the specified address is reached. Attempting
to <literal>.advance</literal> backwards produces an
assemble-time error.
assemble-time error. (If we wanted to output something
besides zeros, we could add it as a second
argument: <literal>.advance 2064,$FF</literal>, for
instance.)
</para></listitem>
<listitem><para>
It has comments that explain what the data are for. The

7
doc/tutor3.sgm
View File

@ -34,6 +34,13 @@
for linking in pre-created graphics or sound data.
</para>
<para>
If you only wish to include part of a binary
file, <literal>.incbin</literal> takes up to two optional
arguments, naming the file offset at which to start reading and
the number of characters to read.
</para>
<para>
As a sample library, we will expand the definition of
the <literal>chrout</literal> routine to include the standard