6502/Ophis
1
0
Fork 0
mirror of https://github.com/michaelcmartin/Ophis.git synced 2024-12-21 12:29:46 +00:00
Code Issues Projects Releases Wiki Activity

Update manuals

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

121
doc/preface.sgm
View File

@ -1,49 +1,81 @@
<preface> <preface>
<title>Preface</title> <title>Preface</title>
<para> <para>
The Ophis project started on a lark back in 2001. My graduate Ophis is an assembler for the 6502 microprocessor - the famous
studies required me to learn Perl and Python, and I'd been playing chip used in the vast majority of the classic 8-bit computers and
around with Commodore 64 emulators in my spare time, so I decided consoles. Its primary design goals are code readability and output
to learn both languages by writing a simple cross-assembler for flexibility - Ophis has successfully been used to create programs
the 6502 chip the C-64 used in both. for the Nintendo Entertainment System, the Atari 2600, and the
Commodore 64.
</para> </para>
<para> <para>
The Perl one&mdash;uncreatively Ophis's syntax is noticably different from the formats
dubbed <quote>Perl65</quote>&mdash;was quickly abandoned, but the traditionally used for these chips; it draws its syntactic
Python one saw more work. When it came time to name it, one of the inspiration primarily from the assemblers for more modern chips,
things I had been hoping to do with the assembler was to produce where the role of tokens is determined more by what they're made
working Apple II programs. <quote>Ophis</quote> is Greek of and their grammatical location on a line rather than their
for <quote>snake</quote>, and a number of traditions also use it absolute position on a line. It also borrows the sophisticated
as the actual <emphasis>name</emphasis> of the serpent in the methods of tracking the location of labels when writing relinkable
Garden of Eden. So, Pythons, snakes, and stories involving really code&mdash;Ophis expects that the final output it produces will have
old Apples all combined to name the only a vague resemblance to the memory image when loaded. Most of
assembler.<footnote><para>Ironically, cross-platform development the alternatives when Ophis was first designed would place
for the Apple II is extremely difficult, and while Ophis has been instructions and data into a memory map and then dump that map.
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>
<para> <para>
Ophis slowly grew in scope and power over the years, and by 2005 That said, there remain many actively used 6502 assemblers out
was a very powerful, flexible macro assembler that saw more use there. If you're already a seasoned 6502 assembly programmer, or
than I'd expect. In 2007 Ophis 1.0 was formally released. want to get your old sources built again, Ophis is likely not for
However, Ophis was written for Python 2.1 and this became more and you&mdash;however, if you are writing new code, or are new to the
more untenable as time has gone by. As I started receiving patches chip while still having other experience, then Ophis is a tool
for parts of Ophis, and as I used it for some projects of my own, built with you in mind.
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> </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> <section>
<title>Getting a copy of Ophis</title> <title>Getting a copy of Ophis</title>
@ -70,6 +102,13 @@
Windows installer will use this. In this case, all you need to Windows installer will use this. In this case, all you need to
do is have <command>ophis.exe</command> in your path. do is have <command>ophis.exe</command> in your path.
</para> </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>
<section> <section>
@ -81,7 +120,11 @@
The code in this book is available in The code in this book is available in
the <literal>examples/</literal> subdirectory, while extra the <literal>examples/</literal> subdirectory, while extra
examples will be in subdirectories of their own with brief 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>
<para> <para>
Most examples will require use of <emphasis>platform 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 assembler know right away where everything is supposed to
be. be.
</para></listitem> </para></listitem>
<listitem><para> Instead of hardcoding in the value $080C, we <listitem><para>
instead use a label to identify the location it's pointing Instead of hardcoding in the value $080C, we instead use a
to. Ophis will compute the address label to identify the location it's pointing to. Ophis
of <literal>next</literal> and put that value in as data. will compute the address of <literal>next</literal> and
We also describe the line number in decimal since BASIC put that value in as data. We also describe the line
line numbers generally <emphasis>are</emphasis> in decimal. number in decimal since BASIC line numbers
Labels are defined by putting their name, then a colon, as generally <emphasis>are</emphasis> in decimal. Labels are
seen in the definition of <literal>next</literal>. defined by putting their name, then a colon, as seen in
the definition of <literal>next</literal>.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Instead of putting in the hex codes for the string part of Instead of putting in the hex codes for the string part of
the BASIC code, we included the string directly. Each the BASIC code, we included the string directly. Each
character in the string becomes one byte. character in the string becomes one byte.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Instead of adding the buffer ourselves, we Instead of adding the buffer ourselves, we
used <literal>.advance</literal>, which outputs zeros until used <literal>.advance</literal>, which outputs zeros until
the specified address is reached. Attempting the specified address is reached. Attempting
to <literal>.advance</literal> backwards produces an 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> </para></listitem>
<listitem><para> <listitem><para>
It has comments that explain what the data are for. The 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. for linking in pre-created graphics or sound data.
</para> </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> <para>
As a sample library, we will expand the definition of As a sample library, we will expand the definition of
the <literal>chrout</literal> routine to include the standard the <literal>chrout</literal> routine to include the standard