Z80 and AY-3-8910 – Part 2

By Kevin on March 2, 2026

I've spent a bit of time looking at the "Tester" part of the AY driver code for Tim Follin's music archive that I talked about in Z80 and AY-3-8910.

This is documenting what I think I've worked out so far for the tester code.

The Sound Tester

As previously mentioned, there are essentially three parts to the code in Follin archive:

The tune and effect data.
Ste Ruddy's Sound Driver.
A tracker-style (ish) tester UI application.

The first part looked at the sound driver itself, and essentially skipped over the tester part of the code. This post picks up on that tester code.

Reminder, from part one, the main structure is as follows:

Code_Start: EQU 40000
Data_Start: EQU 50000

;-----------------------------
ORG Code_Start

; The UI/tester code
TESTER:
  LOOP: Calls the following for each scan:
    HALT - Suspends until an interrupt comes in?
    CALL UPDATE
    CALL REFRESH
    CALL CLOCK
    CALL KEYSCAN
    Repeat as necessary

  KEYSCAN: UI scanning
  CLOCK: Possibly maintain a 50Hz refresh rate clock?
  UPDATE: Loads the internal state of all sound variables from
          the driver and displays them in real time via the UI.

; The sound driver
CODE_TOP:
  TUNE: Select which tune to play.
    TUNE_IN: Init all internal sound state variables for a new tune.
    TUNEOFF: Stop a playing tune, eg to change tune or start an FX.

  FX: Start playing an FX.
    FLOOP: Keep processing FX instructions until complete.

  REFRESH: "run" a scan of the sound driver updating and outputting the sound

The Tester Code

Initialisation information and main screen data:

;**************************************

; Z80 AY MUSIC DRIVER

;**************************************

; ORG 40000
; LOAD 0C000H
        
;======================================
;STACK DEPTHS
                
SD:             EQU 3
                
;======================================
                
ASCII:          EQU 23560                 ; 23560 = $5C08 = System Variable "LAST K"
                
TESTER:         PUSH AF
                PUSH BC
                PUSH DE
                PUSH HL
                
                XOR A                     ; ASCII = MINS = SECS = 0
                LD (ASCII),A
                LD (MINS),A
                LD (SECS),A
                
                CALL TUNEOFF              ; TUNE initialisation
                CALL STACKMESS            ; Kick off the Tester code!
                
                DB CLS                    ; The start of the main UI data
                DB AT,0,0
                DB INK,01010111B
                DB "'AY' MUSIC DRIVE"
                DB "R V2  BY S.RUDDY"

... Skip ...

                DB INK,64+5
                DB "VOLUME          "
                DB "                "
                DB 255

... Skip ...

AT:             EQU 22
INK:            EQU 16
CLS:            EQU 15
                
STACKMESS:      POP IX
                CALL MESS
                JP (IX)

There is a whole lot of screen data in DB blocks which includes some "op codes" that are defined later: AT, INK, CLS. These are special codes that are used by the ROM-based print routines (more here), as used by Sinclair BASIC, but in this case they are spelt out directly, later in code. The final 255 signifies the end of the screen data.

So how are these definitions handled? That all comes up in the "MESS" routine I'll get to in a moment, but first that "STACKMESS" routine needs a bit of explanation.

When a CALL instruction happens, such as the CALL STACKMESS at the start, the current program counter gets pushed onto the stack. In this case the current PC will point to the instruction after the CALL, which happens to be the start of the screen data. So the POP IX will grab the address of the screen data and drop it into IX and then call the "MESS" function to actually get on with it!

But before I get to that, there is some more code after the screen data:

                LD HL,CALC1
                PUSH HL
                LD A,H
                LD DE,4067H    ; Output high byte
                CALL HEX
                POP HL
                LD A,L
                LD DE,4069H    ; Output low byte
                CALL HEX
                
                LD HL,(CALC2)
                PUSH HL
                LD A,H
                LD DE,4071H    ; Output number of Tunes
                CALL HEX
                POP HL
                LD A,L
                LD DE,4073H    ; Output number of effects
                CALL HEX
                
                LD HL,CALC1
                LD DE,(CALC2)
                ADD HL,DE
                PUSH HL
                LD A,H
                LD DE,407CH    ; Not entirely sure what this is outputting...
                CALL HEX
                POP HL
                LD A,L
                LD DE,407EH
                CALL HEX

This is writing some basic data out to the display. CALC1 seems to relate to code section size. I believe CALC2 is the start address of the tune data, which is the following:

                ORG Data_Start

TUNES:          EQU 5
EFFECTS:        EQU 21

All three of these sections are outputting a 16-bit value in two single-byte chunks using the "HEX" routine, which takes a screen address (in the range $4000-$57FF) and outputs a hex number at that screen location.

So while I'm at it then, how is that HEX function working?

;--------------------------------------
HEX:            INC DE             ; DE contains the screen address to use
                PUSH AF            ; Start with DE+1
                CALL ONEnib        ; Write out the LOW 4-bits
                POP AF
                RRA                ; A = A>>4
                RRA                ; to write out HIGH 4-bits
                RRA
                RRA
                DEC DE             ; Back to original DE screen address
ONEnib:         AND 15             ;  A = A & 0xF
                ADD A              ; BC = A * 2
                LD C,A
                LD B,0
                LD HL,ROM_TAB      ; Read from ROM_TAB[BC]
                ADD HL,BC
                LD A,(HL)
                INC HL
                LD H,(HL)
                LD L,A             ; HL = (uint16_t)ROM_TAB[A]
MIKESbug:       LD C,D             ; So HL now points to character bitmap in ROM
                LD B,8             ; Write out 8 bytes to display memory directly
PRloop:         LD A,(HL)          ; (DE) = (HL)
                LD (DE),A
                INC HL             ; HL++
                INC D              ; NB: Layout of display mem means D++ is next line of char
                                   ;     for same value of E.
                DJNZ PRloop        ; WHILE (B-- > 0)
                LD D,C             ; (Restore D before returning, so DE still = screen addr)
                RET
                
ROM_TAB:        DW 3D80H           ; ROM character set: 3D80 = "0"
                DW 3D88H           ; Each char = 8 x 8 bits
                DW 3D90H
                DW 3D98H
                DW 3DA0H
                DW 3DA8H
                DW 3DB0H
                DW 3DB8H
                DW 3DC0H
                DW 3DC8H           ; = "9"
                DW 3E08H           ; = "A"
                DW 3E10H
                DW 3E18H
                DW 3E20H
                DW 3E28H
                DW 3E30H           ; = "F"

This is making use of the character set stored in the Spectrum ROM (more here) which is indexed via a 16-word jump table mapping the characters onto each of the 16 hex characters: 0..9, A..F.

Then each byte, 8 in total, of the character is written directly out to the Spectrum screen memory taking advantage of the odd formatting of the screen memory to easily skip to the next line of the display for each line of the character (more here).

So before I get into the main update loop, how the screen initialised and set up? That happens in the "MESS" and some ancillary functions.

MESS:           LD A,(IX+0)         ; At this point, McursorX, McursorY = (0,0)
                INC IX              ; So read a byte of screen data
                OR A
                RET M               ; Stop IF A=255 (i.e. negative)
                CP 32
                JR C,Mcontrol       ; IF A<32 process control character then RET back to "MESS"
                CALL Mgetchar       ; ELSE Process character
                CALL Mgetaddr       ; Get screen address for next output in DE
                CALL MIKESbug       ; Output the character
                CALL PRattr         ; Set the colour attributes
                CALL INCcursor      ; Update the screen position for the next byte of screen data
                JR MESS
                
Mcontrol:       LD HL,MESS          ; Stick the address of "MESS" on the stack for the RET
                PUSH HL
                CP 15               ; IF A == CLS
                JR Z,Mcls
                CP 22               ; IF A == AT
                JP Z,Mat
                CP 16               ; IF A == INK
                JR Z,Mink
                RET                 ; RETurn to "MESS"
                
Mcolour:        DB 0                ; Working variables for cursor position and colour
McursorX:       DB 0
McursorY:       DB 0                ; Has to be directly after McursorX (see later)
                
Mink:           LD A,(IX+0)         ; Process INK to set colour
                INC IX
                LD (Mcolour),A
                RET
                
Mcls:           LD HL,4000H         ; Process CLS to clear screen
                LD (HL),L
                LD DE,4001H
                LD BC,1AFFH
                LDIR 
                LD (McursorX),BC
                RET
                
INCcursor:      LD HL,McursorX      ; Moves the cursor on one position
                LD A,(HL)
                INC A
                AND 31
                LD (HL),A           ; X++; X = X % 32
                RET NZ              ; IF X==0; Y++
                INC HL              ; Assumes McursorY is McursorX++
                INC (HL)
                RET
                
Mgetchar:       LD L,A              ; HL = A*8 + 3C00
                LD H,0              ; Note: A > 32; where 32="Space"
                ADD HL,HL           ;       In ROM, space is address 3D00
                ADD HL,HL           ;       32 * 8 = 0x100
                ADD HL,HL
                LD BC,3C00H
                ADD HL,BC           ; HL = Start address of character map for char in A in ROM
                RET

.... skip ....

Mgetaddr:       LD A,(McursorY)     ; Calculate the screen address for (McursorX, McursorY)
                AND 18H
                OR 40H
                LD D,A
                LD A,(McursorY)
                RRCA 
                RRCA 
                RRCA 
                AND 0E0H
                LD E,A
                LD A,(McursorX)
                ADD E
                LD E,A
                RET                 ; DE = required screen address
                
Mat:            LD A,(IX+0)         ; Set cursor to provided X, Y in screen data
                LD (McursorX),A
                INC IX
                LD A,(IX+0)
                LD (McursorY),A
                INC IX
                RET
                
PRattr:         LD A,D              ; Get address of ATTRibute memory
                RRA
                RRA
                RRA
                AND 3
                OR 58H
                LD D,A
                LD A,(Mcolour)
                LD (DE),A           ; And set the colour
                RET

Basically this loop keeps working on the provided screen data until the value 255 is found, at which point it returns. There are two paths for handling the data:

IF the value is < 32 then it is a control value. Only CLS, AT and INK are recognised.
ELSE the value is assumed to be an ASCII character and is displayed.

Whatever is happening, happens at the coordinates given by (McursorX, McursorY) which start out as (0,0) and get updated automatically when a character is output, or in response to an AT command. INK will set the required colour in Mcolour, which again starts out as 0. This is applied after the character is written to the screen, using the PRattr function.

There is a fun bit of optimisation going on in Mcontrol. At the start it pushes the address of the MESS function on the stack, which means that the RET will jump back to the start of MESS rather than where the jump happened to Mcontrol itself.

There is another shortcut in the Mcls function: LDIR. From http://z80-heaven.wikidot.com/instructions-set:ldir: "Repeats LDI (LD (DE),(HL), then increments DE, HL, and decrements BC) until BC=0." By setting the contents of HL (the first byte of the display) to zero, this will tile that same value across the display memory until BC, which starts at $1AFF, is zero. This will zero the whole display – both pixels and attributes – from 0x4000 through to 0x5AFF.

Now finally, we get to the main update loop.

LOOP:           
                HALT 
                CALL UPDATE       ; Update the display from the current Sound parameters
                LD A,2
                OUT (254),A       ; Set border to 2
                CALL REFRESH      ; Update the sound driver parameters
                XOR A
                OUT (254),A       ; Set border to 0
                CALL CLOCK        ; Run 50Hz clock
                CALL KEYSCAN      ; Guess what - scans the keyboard 
                LD A,07FH
                IN A,(254)        ; Reads 0x7FFE which is the bottom row of the keyboard
                AND 1
                JP NZ,LOOP        ; Checks bit 0, which is the SPACE key
                LD BC,65533       ; AY OUTPUT PORTS (FFFD, BFFD)
                LD A,7
                OUT (C),A
                LD BC,49149
                LD A,63           ; Set AY register 7 to 63 - i.e. all channels OFF
                OUT (C),A
                
                POP HL
                POP DE
                POP BC
                POP AF
                RET

I'm not going through the sub routines of the loop, other than to note the following:

UPDATE is a whole series of instructions that basically do the following to output the HEX value of a sound parameter:

LD A, (contents of one of the sound variables)
LD DE, (corresponding screen address for the variable to be displayed)
CALL HEX

REFRESH runs the sound driver itself, as described in Z80 and AY-3-8910.
CLOCK decrements the FIFTY variable and every time it gets to zero updates SECS and MINS and writes them out to the display. As it also uses the HEX routine, I guess it is storing the time using binary-coded decimal (BCD).
KEYSCAN reads the last key pressed from the system variable location stored in ASCII (23560 / 0x5C08).

At some point I might come back and work out what keys do what…

Closing Thoughts

I'd really like to get some of this code running on some of the alternate Z80 platforms I have. Getting the sound output shouldn't be too much of an issue, but I'd really like to have some kind of display too.

But as can be seen above, the tester UI is pretty well tied into the oddities of the ZX Spectrum display, so porting it won't be trivial.

I suspect there are already some existing AY/chiptune players that perhaps would be a better starting point, but from what I've seen they tend to stream the register data after having sampled it at regular intervals, which isn't quite what I was after… there would be something really quite interesting about actually running Ste Ruddy's Sound Driver with a Tim Follin soundtrack programmed in.

Kevin