After all the work to write a post showing off COMFY-6502’s ability to reproduce the Red Book tone routine, I made a slight mistake in translation. The code I presented differed ever-so-slightly from the Red Book routine in the case where the Y-register reached zero.

In the original, when the Y-register reaches zero, the DEX is still executed. In the code I posted, the expiring “duration tick” skips a count on the pitch. A minor error, but one I should own up to.

Here’s a better effort. COMPILE-SYMBOLIC contains a MACROLET defining MODULE as a call to COMFY-6502:COMPILE.

(compile-symbolic
  (equ speaker #xc030)
  (equ duration 1)
  (equ pitch 0)
  (module
   (comfy-6502:loop
      ;; repeat until some clause loses: actually, only exit is
      ;; through return, so each clause should be ensured of winning.
    (LDX pitch)
    (LDA speaker)
    (not
     (comfy-6502:loop  ;; repeat until whap time
     DEY
     (not (seq zero? (DEC duration) zero? return))
     (seq DEX (not zero?)))))))

resulting in

(; reload-pitch
 (LDX :ZERO-PAGE) (:ZERO-PAGE 0)
 (LDA :ABSOLUTE) (:ABSOLUTE 49200)
 ; spin
 (DEY)
 (BNE) (:BRANCH 6) ; not-duration-tick
 (DEC :ZERO-PAGE) (:ZERO-PAGE 1)
 (BNE) (:BRANCH 2)
 (RTS)
 ; not-duration-tick
 (DEX)
 (BEQ) (:BRANCH 4) ; goto-reload-pitch
 (JMP :ABSOLUTE) (:LONG-BRANCH -12) ; spin
 ; goto-reload-pitch
 (JMP :ABSOLUTE) (:LONG-BRANCH -20) ; reload-pitch
)

For fun, I tried to get the code to emit the RTS at the very end, as in the original.

(compile-symbolic
  (equ speaker #xc030)
  (equ duration 1)
  (equ pitch 0)
  (module
    (alt (loop (seq (LDX pitch) (LDA speaker))
            (not (while
                    (seq DEY (not (seq zero? (seq (DEC duration) zero?)))
                    (seq DEX (not zero?)))))
          RTS)))

(; reload
  (LDX :ZERO-PAGE) (:ZERO-PAGE 0)
  (LDA :ABSOLUTE) (:ABSOLUTE 49200)
  ; spin
  (DEY)
  (BNE) (:BRANCH 5) ; not-duration
  ; duration-tick
  (DEC :ZERO-PAGE) (:ZERO-PAGE 1)
  (BEQ) (:BRANCH 10) ; exit
  ; not-duration
  (DEX)
  (BEQ) (:BRANCH 4) ; goto-reload
  ; goto-spin
  (JMP :ABSOLUTE) (:LONG-BRANCH -11)
  ; goto-reload
  (JMP :ABSOLUTE) (:LONG-BRANCH -19) ; reload
 ; exit
  (RTS))

“Loop tightening” could change (BEQ) (:BRANCH 4) to (BEQ) (:BRANCH -14); the (JMP :ABSOLUTE) (:LONG-BRANCH -19) is then never used, and could be omitted, changing (BEQ) (:BRANCH 10) to (BEQ) (:BRANCH 7).

“Loop compaction” could potentially recognize (BEQ) (:BRANCH -14) (JMP :ABSOLUTE) (:LONG-BRANCH -11), where no other instruction references the JMP, could be converted to (BEQ) (:BRANCH -14) (BNE) (:BRANCH -11), shortening the (BEQ) (:BRANCH 7) one byte more to (BNE) (:BRANCH 6).

Note some interesting equivalents I should probably implement as COMFY macros.

(if A B C) where C is do-nothing-but-win is (not (seq A (not B)). If A wins, B is executed to determine the result of the form. If A loses, the if wins. I will probably call this (when A B).

(if A B C) where B is a do-nothing-but-win is (alt A C), where alt is the “dual” of seq. (alt A B C …) == (not (seq (not A) (not B) (not C) …). For the two-argument case, I would call this (unless A B).

The one twist I can think of is to add an “implied SEQ” to these forms. (when A B C …) would be (when A (seq B C …)). (unless A B C …) would be (unless A (seq B C …)).

As I’ve mentioned before, I’ve become intrigued by Baker’s COMFY assembler, and have been working on porting it to Common Lisp, and making it a bit more powerful in the link stage.

One metric to judge the success of this kind of “medium-level” language is how well it compiles compared to hand-written assembler code. For the 6502, there are a few examples of code created by wizards like Steve Wozniak, which you can find copies of around the web, the largest being the Apple II monitor, the Integer Basic interpreter, and some medium-sized ones like the Apple II 6502 step/trace, the mini-assembler, the floating-point “Wozpack,” and the Sweet-16 virtual machine.

This kind of code has a lot of quirks that make it hard to straight-forwardly translate: lots of shared “tail code”, branches known by the programmer to always be taken (to save a precious extra byte consumed by an unconditional JMP), and the classic “fake RTS trick”, pushing a return address picked from a table onto the stack, then using an RTS instead of a zero-page indirect JMP. Common in Woz’s code is a further shortening of the code by arranging the destination addresses to all be in the same 256-byte page, so the high-order byte is a constant. Some of these ideas will likely be possible with intelligent macros, combined with address labels and computation on those labels. I’m puzzling a bit over how to optimize the “same page” condition: whether to include a “link-time assert”, which will issue an error if the code is emitted so as to cross a page, or an even more intelligent “link-time computation” which, given the current available memory space, can choose a location that meets the constraints.

That’s all still in development. The first test case I used was the classic “Red Book” tone routine.

;; the original
;; location 00: pitch
;; location 01: duration
0002-  AD 30 C0   LDA  $C030 ; whap speaker
0005-  88         DEY
0006-  D0 04      BNE  $000C
0008-  C6 01      DEC  $01   ; y reaches 0: a duration tick
000A-  F0 08      BEQ  $0014 ; duration exhausted when reaches 0
000C-  CA         DEX        ; x counts time to "whap"
000D-  D0 F6      BNE  $0005
000F-  A6 00      LDX  $00   ; x reached 0, reload pitch
0011-  4C 02 00   JMP  $0002 ; and whap
0014-  60         RTS

A few comments:

1. Locating the code in zero-page needlessly wastes valuable zero-page locations. The code is easily relocatable to other locations.
2. X counts from the “pitch value” down to 0 at a fixed rate, “whapping” the speaker each time it reaches zero.
3. Y cycles around continuously at basically the same rate; each time it reaches zero, one tick is subtracted from the duration value. When duration reaches zero, the routine returns.
4. This classic tone routine has the important feature that duration is absolute, and not dependent on pitch
5. Y is uninitialized, which presumably causes a slight jitter in the duration, unless BASIC ensures Y=0. Likewise, X in the first pitch countdown is uninitialized.
6. duration is destroyed by the routine, but pitch is not.

Here is my transcription to COMFY-6502. I have translated the “I”, “J”, and abbreviated “L”, “LI”, etc. opcodes for this example, but not yet changed Baker’s code to accept them.

(let ((comfy-6502::*symbol-table* (make-hash-table)))
  (equ speaker #xc030)
  (equ duration 1)
  (equ pitch 0)
  (comfy-6502-tests::compile-code
     (comfy-6502:loop
       ;; repeat until some clause loses: actually, only exit is
       ;; through return, so each clause should be ensured of winning.
        (LDX pitch)
        (LDA speaker)
        (not (comfy-6502:loop  ;; repeat until whap time; "whap" time is when a clause loses; NOT wins, outer loop continues
                 DEY
                 (if =0? ; has Y reached zero?
                     (not (seq (DEC duration) ; Y has reached zero, duration ticks down
                               =0?       ; if duration has not reached zero, SEQ fails, NOT wins, IF wins, inner loop continues
                               RTS)) ; duration reached zero, return
                     (seq DEX ~=0?))))))) ; Y not zero, count down pitch. If X has reached zero, SEQ loses, IF loses, inner loop exits

To understand the code, the basic COMFY principles must be understood.

1. Conditional tests (such as “=0?”, corresponding to a BEQ or BNE), “win” if they are true, “lose” if they are false.
2. Ordinary machine operations (such as LDA, DEX, RTS) always “win”
3. SEQ sequentially each enclosed form, until one “loses”, in which case SEQ “loses”, or until they all “win”, in which case SEQ “wins.”
4. LOOP executes each enclosed form, until one “loses”, in which case LOOP “loses”, continuing at the top of the loop if every form “wins.” (I have introduced an “implied” seq to Baker’s ELisp implementation.) It is SEQ stuck on potentially endless repeat.
5. NOT executes the single enclosed form, but changes “win” into “lose” and vice-versa. This is useful to keep a nested “loss” from terminating all the enclosing forms.
6. (IF test win-form lose-form) executes TEST. If TEST “wins”, WIN-FORM is executed, and its win/lose result is passed out as the result of the IF. If TEST “loses”, LOSE-FORM is executed, and its win/lose result is passed out as the result of the IF.

Note that I have chosen to initialize X on the first pass through the loop. That makes the code somewhat clearer, and I think is better style.

So what code does COMFY (as of today) generate for this? Behold.

(; reload-pitch
 (LDX :ZERO-PAGE) (:ZERO-PAGE 0)
 (LDA :ABSOLUTE) (:ABSOLUTE 49200)
; spin
 (DEY)
 (BEQ) (:BRANCH 6) ; duration-tick
 (DEX)
 (BNE) (:BRANCH 8 ) ; goto spin
 (BEQ) (:BRANCH 9) ; goto reload-pitch
; duration-tick
 (DEC :ZERO-PAGE) (:ZERO-PAGE 1)
 (BNE) (:BRANCH 2) ; goto-spin
 (RTS)
; goto spin
 (JMP :ABSOLUTE) (:LONG-BRANCH -14)
; goto reload-pitch
 (JMP :ABSOLUTE) (:LONG-BRANCH -22))

This is a symbolic “intermediate” form, not yet relocated and linked. Some keys for interpretation.

1. (BEQ), (JMP :ABSOLUTE) etc. represent one-byte opcodes, with the specified addressing mode (redundant in the case of branch instructions, which have only the branch-relative mode).
2. (:ZERO-PAGE 0) is a single-byte, value 0, tagged to indicate that it represents a reference to zero-page location 0, and is not just a immediate argument of value zero.
3. (:ABSOLUTE 49200) is a two-byte reference to the address #xC030, which will be emitted in the usual 6502 low-byte first as #x30 and #xC0.
4. (:BRANCH n) represents a short branch. It is one byte long. Note that the destination counts relative to the BRANCH byte, not relative to the next instruction, as the 6502 branch values do. (The relocater corrects for this when converting to 6502 code bytes.)
5. (:LONG-BRANCH n) is a long branch. It is two bytes long. JMP is absolute in the 6502; the relocated will deposit the absolute address by adding this value to the location of the first byte of this pair.

I have added this intermediate form because Baker’s Elisp goes directly to bytes in a fixed memory area, starting from high addresses. My goal is for a high level “COMFY module” macro to result in an intermediate form that knows its length in bytes, what zero page locations it uses, and what internal entry points it exports. Otherwise, it is relocatable by the linker. I would also like the feature that the zero-page references are symbolic (e.g. (:ZERO-PAGE duration)), in which case the linker would allocate a byte in zero-page, and all modules referring to “duration” would refer to that address. Even nicer would be the ability to do math, for instance (:ZERO-PAGE (+ duration 1)), or to emit (:ABSOLUTE (- tone-entry 1)) to encode the module entry point in the “off-by-one” method used by the “fake RTS” trick. Similarly, one could have elements such as (:BYTE (HIGH tone-entry)), representing the high-order byte of the tone-entry address, and allowing arbitrary link-time math.

As for the code itself, it has the same similar semantics as the Red book routine.[UPDATE: but not quite. See more recent post for correction.] It has a somewhat minor change in that the DEY is followed by a BNE in the original code (taken 255 out of 256 times), and by a BEQ in the COMFY version (taken only 1 out of 256 times). Any difference in the execution time will, of course, change the pitch emitted. More serious is the fact that COMFY, as coded, is biased toward forward conditional branches. The two JMP instructions after the RTS are reached only through branches that could reach their destination directly. COMFY compiles, as I mentioned, from the last instruction toward the first. Forward branches are trivially resolved, but backward branches don’t know their destination, in particular, whether the destination is a short branch away or not. The backward JMPs are created by the code for LOOP, which first emits a “placeholder” absolute jump, compiles the loop forms, including branches that might land on that jump, then patches the JMP destination to point to the first form of the LOOP.

That suggests that LOOP might be enhanced to include a “loop-tightening” phase which examines the body of the loop for forward branches (:BRANCH x) to jumps (:LONG-BRANCH y), and if x+y+1 is within range of a short branch, replaces it. (The +1 is for the JMP opcode itself.) The result would be

(; reload pitch
 (LDX :ZERO-PAGE) (:ZERO-PAGE 0)
 (LDA :ABSOLUTE) (:ABSOLUTE #XC030)
; spin
 (DEY)
 (BEQ) (:BRANCH 6) ; duration-tick
 (DEX)
 (BNE) (:BRANCH -5) ; spin
 (BEQ) (:BRANCH -12) ; reload-pitch
; duration-tick
 (DEC :ZERO-PAGE) (:ZERO-PAGE 1)
 (BNE) (:BRANCH -11) ; spin
 (RTS)
 (JMP :ABSOLUTE) (:LONG-BRANCH -14)
 (JMP :ABSOLUTE) (:LONG-BRANCH -22))

The two JMPs are now unused. This is a special case, because RTS is itself a jump. Because LOOP knows that it freshly emitted the JMP, no external code can properly reference it. If all the branches to it have been patched, and the last instruction cannot reach it, the JMP itself can be omitted.Assuming I can convince COMFY to be smart enough to omit the (proven) redundant JMPs, we are ready for comparison. Let’s re-write the original code to match the explicit X initialization, and use COMFY’s discovery that moving the LDX to the front of the loop means the absolute JMP $0002 in the original can be replaced by a BEQ.

reload-pitch LDX PITCH
             LDA $CO30
spin         DEY
             BNE not-tick ; actually, takes branch more often
; duration-tick
             DEC duration
             BEQ return
not-tick     DEX
             BNE spin
             BEQ reload-pitch ; save a byte compared to original JMP
return       RTS

COMFY, with the yet-to-be-implemented loop tightening has made the code one byte shorter, and relocatable.As mentioned before, COMFY has luckily or unluckily chosen the branch after DEY to be taken infrequently, while the author of the tone routine chose it to be taken frequently. We cannot know whether the author de-optimized to reach a lower pitch range. If so, to match the timing more closely, I can reverse the sense of the IF, causing it to emit a BNE. In this case, the hypothetical loop-tightening can eliminate one JMP, but not the other.

(; reload-pitch
 (LDX :ZERO-PAGE) (:ZERO-PAGE 0)
 (LDA :ABSOLUTE) (:ABSOLUTE 49200)
; spin
 (DEY)
 (BNE) (:BRANCH 6) ; not-duration
 (DEC :ZERO-PAGE) (:ZERO-PAGE 1)
 (BNE) (:BRANCH -6) ; spin
 (RTS)
; not-duration
 (DEX)
 (BEQ) (:BRANCH -15) ; reload-pitch
; goto-spin
 (JMP :ABSOLUTE) (:LONG-BRANCH -12)

We see this simple change affected the DEY test, but also affected the DEX test, biasing it to be taken less frequently. Perhaps an annotation could added to the COMFY language to indicate “please prefer (or expect?) this test to win/lose.” This would disrupt the tight recursive elegance of the GENBRC routine, but it might prove handy in modern architectures with their branch-prediction tendencies. It is also not so simple to change the test after DEC (:ZERO-PAGE 1) to BEQ to the RTS. That would require moving the RTS to be emitted at the end, i.e. compiled by COMFY first. I’m more interested in implementing the loop-tightening logic than attacking that brain-teaser right now.The moral may be that COMFY (plus yet-to-be-implemented optimization passes) can emit code very much in the ballpark of humans, at least for these toy examples. For cycle-level timing, however, I might follow the lead of Sassy and allow for the human to code branches and jumps explicitly. (Sassy’s example “boot sector” code actually avoids pretty much all the COMFY primitives; however, the documentation also seems to suggest that loop tightening and similar optimizations have been implemented there.) And I have yet to successfully translate Woz’s code into COMFY, probably because I have to understand it first.(Note to self: AVOID the tempting WordPress “code” button. Use the sourcecode tag, although it supports neither assembler nor Lisp.)

While I’m still digesting COMFY in my “ample spare time,” a post on comp.sys.apple2 mentioned some assemblers from “Ron” having a similar flavor: SPL for the 6502 and PIC0 for PIC 10F2xx microcontrollers. They are apparently implemented in Python, and inspired by Forth. They emit assembler.

I’ve been working a bit with Baker’s COMFY-6502 code; a few notes of what I have learned so far.

First, a couple of tiny bugs in the genbrc; the code miscounts the size of the branch instructions, meaning that (- l 2) should be a (+ l 2) and so on. I found it handy to enumerate each clause of the cond. Each clause handles a particular case, such as when the “lose” continuation can be reached by a short branch instruction, while the “win” continuation is far enough away to require an absolute jump.

Second, genbrc, genbr, and compile all provide the address of the resulting “continuation” as the return value. This is perhaps clear when one traces out all the recursion, but it isn’t explicitly mentioned. One interesting case is genbrc when the “win” and “lose” branch destinations are the same: one could simply emit an unconditional branch to that destination, and return the address of that branch but actually returning the destination works just as well. (In the emit routine, if the continuation does not happen to be the next instruction, the unconditional branch is, after all, emitted, moving the continuation to the front of the instruction stream, ready for the non-branching instruction to be emitted just in front of it.)

As for “upgrades” to the package, I have been focused up to this point on moving the knowledge of 6502 opcodes and addressing modes from magic decimal numbers to symbolic processing. Instead of simply emitting a decimal opcode, I have been changing the code to emit symbolic opcodes, such as (ADC ABSOLUTE), with routines to reduce these symbolic forms to the appropriate opcode, including checking for invalid opcodes. Baker’s original code will happily emit opcodes with addressing modes not supported by the chip. Currently, the compiler emits these symbolic codes into the code vector, awaiting a processing step to convert them to the decimal equivalent. Ideally, one would detect invalid addressing modes in the compilation stage, not the post-processing stage.

Some other changes I am contemplating are allowing for symbolic jump destinations, so that object code can be relocated and external labels could be used to relax the restrictions of the current scheme, which requires manually sequencing compilation and storing of addresses.

I encountered Henry G. Baker’s COMFY compiler a couple years ago. (Baker’s site contains a text article, a TeX format article, and an Emacs Lisp implementation. The ACM published the two articles COMFY theory and COMFY-65) COMFY is not a very high-level language, in the conventional sense, but is an attempt to provide a clean but simple set of control structures on top of conventional machine code. Baker calls it ‘medium-level.’

The resulting compiler is very small; its main task in life is to automate the generation of branch instructions, which is one of the tedious parts of tightly optimizing assembly programs. Yet it allows as well for arbitrary Lisp-style macros.

I found the concept intriguing, but I found the article and the compiler code itself rather obscure. Part of the obscurity is the unconventional names for the 6502 operations, unconventional notation for the addressing modes, and decimal numbers for opcodes (because Emacs Lisp does not accept other radixes). Another is that the implementation is lean-and-mean, emitting code bytes directly into a destination vector—the only output to look at is a vector filled with decimal numbers. The manipulations on the 6502 opcodes take advantage of the low-level bit patterns without explanation. Finally, it uses the term ‘continuation’, which, no matter how many times I think I understand it, scares me, probably because it introduces a highly abstract term into an area like assembly programming which is relentlessly concrete.

I’ve been learning about it by going through the code, restructuring a bit as I go. I’m beginning to be impressed by the subtlety of the code. One thing that is just dawning on me is that the return values of the code-emitting functions is as important as the side-effect. (To those of you chuckling, you see how far I have yet to go.) Lisp can hide that from you when it “looks imperative.”

My longer term goal is to see if the same technique can be fruitful even within the more restrictive limits of the PIC. In order to get there, I’m going to have to gain confidence that I understand the formal concept of the ‘win’ and ‘lose’ continuations, which means, I think, having to come up with legible examples that compile to 6502 code, and use that to firm up my understanding of the compiler. Finally, I’ll try to code the ‘genbrc’ routine for PIC branches.

For the “legible examples” part, I think I will try to break the lean-and-mean single-pass direct-to-binary compiler into a “compile to a vector or list with symbolic 6502 mnemonics” followed by a very simple 6502 assembly pass. A similar enhancement might accumulate a relocation table to allow more flexible linking. (I’m still not used to the idea that the code is emitted starting in high memory and working down.) I’ve begun abstracting out the addressing mode bit manipulations, and probably will add error-checking to make sure invalid opcodes are not generated by mistake.

One thing that I think that will have to go in the PIC version is the shallow binding mentioned in the TeX column, but not in the text version; without a stack, I’m not sure where to save anything. I’m also just a bit worried that the PIC has so many idiosyncracies (e.g., register pages controlled by special flags, instead of a uniform zero-page) that even a medium-level language doesn’t help much.

(I should mention in passing Frode Vatvedt Fjeld’s nifty little Lisp code to generate PIC instructions from the bit chart.)

[UPDATE: I should also mention a COMFY-based assember for x86, implemented in Scheme, called `Sassy', although I have never tried to use it.]

It seems that others have also had the desire to upgrade the ADT (Apple Disk Transfer) tool to work with disks other than the Disk II 5-1/4 inch floppy format under DOS 3.3.

ADTPro is a ProDOS-based version of ADT. It should presumably work with all block devices recognized by ProDOS. I e-mailed some code to David Schmidt which allowed ADT to work with the ordinary IIgs serial ports; direct access to the Z8530 chip might allow for faster transfers; that’s a potential project.

This blog is a simple experiment for now, to understand what is available for a “scratchpad on the Web.”

I have a picture which is something more like a lab notebook for my various hacking projects. The requirements are roughly

• access from various places where hacking might happen; an idea for a project can happen at work, but I don’t want my personal laptop with me at all times.
• some kind of permanence, as suits a lab notebook. Various things this might mean:
  

  • version control with timestamping
  • no revisions allowed at all (this seems extreme: one wants to separate a polished presentation view from the underlying archival lab notebook. One can revise slides for a talk without altering the historical record of the lab notebook)
  • ability to archive into a big .tgz for burning to disk as necessary

• flexible project documentation
  

  • easy way to archive associated files; diffs, error messages, screen shots, sketches, links, data sheets downloaded for the web.
  • perhaps I need to wait for my copy of Kanare’s Writing the Laboratory Notebook (as seen on Lispmeister) to arrive to understand what should be required here.

Some projects to comment on here

• work on CADR emulator and MIT-released Lisp machine code
  

  • make it work on Mac OS X/PPC for my laptop
  • make Chaos emulation work on Mac OS X
  • fix some Y2K-type issues, site configuration
  • create Chaos layer in OpenMCL or more portable Common Lisp, to develop gateways to things like

  • AIM/Jabber
  • regular e-mail
  • other retro people running Chaos emulation
  • support versioning file system semantics (e.g. blah.type~version~) on a UNIX FILE host.
  • build a world from the MIT-provided code, alllowing bootstrap

• Apple II file transfer (extend ADT = Apple Disk Transfer) to include 140k, 800k ProDOS and Macintosh HFS floppy formats
• Possibly, an Apple II compatible USB peripheral interface, to allow easy transfers to a Mac/PC with USB connection
• Mac OS X support for foot-pedal shift & mouse-click operations

Interesting that Netscape 7 on Windows gives me little editing widgets on my post that Safari on Mac OS 10.4 didn’t give me (as I recall.) Perhaps I should check, try to add that capability.