From 0faae3f5b470b6b932e78c847c8d0aff88f94835 Mon Sep 17 00:00:00 2001 From: Michael Martin Date: Tue, 12 Jun 2012 23:13:55 -0700 Subject: [PATCH] Update manuals --- doc/cmdref.sgm | 31 +++++++------ doc/preface.sgm | 121 ++++++++++++++++++++++++++++++++---------------- doc/tutor1.sgm | 28 ++++++----- doc/tutor3.sgm | 7 +++ 4 files changed, 123 insertions(+), 64 deletions(-) diff --git a/doc/cmdref.sgm b/doc/cmdref.sgm index 89ddfe0..4787a13 100644 --- a/doc/cmdref.sgm +++ b/doc/cmdref.sgm @@ -117,7 +117,7 @@ <$D000+32 evaluates to $20 >$D000+32 evaluates to $F0 >[$D000+32] evaluates to $D0 - >$D000-275 evaluates to $CE + >[$D000-275] evaluates to $CE
@@ -371,15 +371,16 @@ - .advance address: - Forces the program counter to - be address. Unlike + .advance address + [, filler]: Forces the program + counter to be address. Unlike the .org - directive, .advance outputs zeroes - until the program counter reaches a specified - address. Attempting to .advance to a - point behind the current program counter is an - assemble-time error. + directive, .advance outputs bytes (the + value of filler, or zeroes if it is + unspecified) until the program counter reaches a + specified address. Attempting + to .advance to a point behind the + current program counter is an assemble-time error. @@ -423,10 +424,14 @@ - .incbin filename: - Inserts the contents of the file specified as binary - data. Use it to include graphics information, precompiled - code, or other non-assembler data. + .incbin filename + [, offset + [, length]]: 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. diff --git a/doc/preface.sgm b/doc/preface.sgm index c86cdea..e3b52eb 100644 --- a/doc/preface.sgm +++ b/doc/preface.sgm @@ -1,49 +1,81 @@ Preface - 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. - The Perl one—uncreatively - dubbed Perl65—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. Ophis is Greek - for snake, and a number of traditions also use it - as the actual name of the serpent in the - Garden of Eden. So, Pythons, snakes, and stories involving really - old Apples all combined to name the - assembler.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. + 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—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. - 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. - - - This is an updated edition of Programming With - Ophis, 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 To HLL and - Back 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—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. +
+ History of the project + + 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. + + + The Perl one—uncreatively + dubbed Perl65—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. Ophis is + Greek for snake, and a number of traditions also + use it as the actual name of the serpent in + the Garden of Eden. So, Pythons, snakes, and stories involving + really old Apples all combined to name the + assembler.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. + + + 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. + + + This is an updated edition of Programming With + Ophis, 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 To HLL + and Back essays I wrote using Ophis and Perl65 as + example languages. + +
Getting a copy of Ophis @@ -70,6 +102,13 @@ Windows installer will use this. In this case, all you need to do is have ophis.exe in your path. + + 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. +
@@ -81,7 +120,11 @@ The code in this book is available in the examples/ subdirectory, while extra examples will be in subdirectories of their own with brief - descriptions. + descriptions. They are largely all simple Hello + world 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. Most examples will require use of platform diff --git a/doc/tutor1.sgm b/doc/tutor1.sgm index b4b0263..04c5295 100644 --- a/doc/tutor1.sgm +++ b/doc/tutor1.sgm @@ -144,26 +144,30 @@ next: .word 0 ; End of program assembler know right away where everything is supposed to be. - 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 next and put that value in as data. - We also describe the line number in decimal since BASIC - line numbers generally are in decimal. - Labels are defined by putting their name, then a colon, as - seen in the definition of next. + + 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 next and + put that value in as data. We also describe the line + number in decimal since BASIC line numbers + generally are in decimal. Labels are + defined by putting their name, then a colon, as seen in + the definition of next. - 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. Instead of adding the buffer ourselves, we used .advance, which outputs zeros until the specified address is reached. Attempting to .advance 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: .advance 2064,$FF, for + instance.) It has comments that explain what the data are for. The diff --git a/doc/tutor3.sgm b/doc/tutor3.sgm index 313ed27..25dd6bc 100644 --- a/doc/tutor3.sgm +++ b/doc/tutor3.sgm @@ -34,6 +34,13 @@ for linking in pre-created graphics or sound data. + + If you only wish to include part of a binary + file, .incbin takes up to two optional + arguments, naming the file offset at which to start reading and + the number of characters to read. + + As a sample library, we will expand the definition of the chrout routine to include the standard