cartridge

; An Atari 800XL holding a 128 KB XEGS cartridge: sixteen banks of eight
; kilobytes, of which the last is the fixed part the CPU always sees at
; $A000-$BFFF and the other fifteen are storage, brought into $8000-$9FFF one at
; a time by the byte written to $D5FF. A cartridge is ROM the CPU reads where it
; lies, so nothing is loaded and there is no DOS: the machine's whole RAM below
; the cartridge is the program's, $0700 included.
target {
  cpu "6502"

  ; The one Container a machine holding a cartridge takes. A `.xex` needs a DOS
  ; to load it, and this machine has none.
  containers car

  ; Fifteen and not sixteen: the sixteenth bank is the fixed part under another
  ; name, and one set of bytes with two names is one too many.
  units  banks 15
  window switched $8000 .. $9FFF  views banks
}
storage { units banks }

target {
  region ram    $0000 .. $7FFF  ram
  region stack  $0100 .. $01FF  reserved
  region io     $D000 .. $D7FF  register

  ; The part of the cartridge no switch takes away, which is where the solver
  ; puts everything nothing writes. $8000-$9FFF is in no Region at all: it is
  ; the window, it shows one Bank at a time, and only a Pane or storage stands
  ; there — as the boot record's page is in no Region of the diskette's variant.
  region cart   $A000 .. $BFFF  rom

  ; What the driver writes. Any address of $D500-$D5FF is the same register.
  register CARTSEL $D5FF
}

; The OS, the driver for this storage and the decoders the tool ships. Every
; Transition calls the driver and the decoders, so they are resident; a decoder
; nothing uses is dropped.
modules { "atari/os.asm"  "atari/charsets.asm"  "atari/cart.asm"  "stream/zx0.asm" }
resident { os, charsets, cart, zx0 }

; The Atari OS as a Module: what it occupies while it is in memory, and the
; names a program reaches it by. Sections that hold no bytes, pinned where
; the OS lives, so the solver sees memory that is taken rather than a Region
; it may never allocate from — which is what lets a Phase that switches the
; ROM out have those addresses back, once there is a way to say so. See
; 0038 for why what occupies memory for a while is a Module, and 0051 for
; what this first cut settles and what it leaves.
;
; Every Section here is `root`: the OS and the hardware reach them with no
; Reference in any Chunk, so nothing else would keep them. None holds bytes,
; so none has a Payload and no Transition loads one.
;
; This is the OS as an XL or XE ships it. A machine whose OS lives elsewhere
; declares a Module of its own; the variant is what chooses.

.export RTCLOK, SDMCTL, SDLSTL, SDLSTH, CH, SETVBV, XITVBV

; The OS's half of the zero page. The program's own variables live above it,
; in the half the variant leaves to the solver.
.section zeropage at $0000, root
osZero
        .res $12
RTCLOK  .res 3                          ; $0012: the frame counter, three bytes
        .res $6B
.ends

; The OS's variables and buffers. The shadow registers are among them and
; are Labels here rather than registers of the variant: they are the OS's
; memory, which the OS copies to the hardware on every vertical blank, and
; a `register` Region inside this Section would be an address the Section
; may not cover.
.section absolute at $0200, root
osRam
        .res $2F
SDMCTL  .res 1                          ; $022F: shadows DMACTL
SDLSTL  .res 1                          ; $0230: the display list address, low
SDLSTH  .res 1                          ; $0231: and high
        .res $CA
CH      .res 1                          ; $02FC: the last key pressed, $FF for none
        .res $403
.ends

; The ROM, in the two ranges the hardware registers leave between them, and
; the entry points a program calls in the second. The RAM underneath is what
; a Phase without the OS would be given.
.section absolute at $C000, root
osRomLow
        .res $1000
.ends

.section absolute at $D800, root
osRomHigh
        .res $C5C
SETVBV  .res 3                          ; $E45C: A = the stage, X/Y = the routine
        .res 3
XITVBV  .res 3                          ; $E462: the end of a deferred routine
        .res $1B9B
.ends

; The Atari's two codes for the same letters, as Charsets.
;
; `atascii` is what the character I/O takes: the machine's own code, with the
; graphics characters where an ASCII machine keeps its control codes, and the
; letters where ASCII has them — which is why an unprefixed literal of plain
; letters has always worked and why nothing else has. `\n` is `$9B`, the end of
; line, and not `$0A`.
;
; `screen` is what the display reads out of screen memory, which is the same
; letters at other numbers. A program that writes where the display looks
; rather than through the OS wants this one.
;
; The graphics characters are written here as the Unicode the box-drawing and
; block characters have, so a picture drawn in the source is the picture the
; machine draws. A letter in inverse video is one of those too — Unicode squares
; them off in a negative, and `atascii"PRESS 🆂"` is seven bytes with the last
; one inverse. A whole line of inverse text is better asked of a Charset
; derived from this one, `.charset bright : atascii ^ $80`, which is what a
; derivation is for. Two of them have no exact Unicode: `$02` and `$0D` are a
; quarter of a cell where the nearest character is an eighth, and are written
; as `▕` and `▔`. Everything else, the inverse entries included, was read off
; the machine's own font and matches it.
;
; This Module emits nothing: it is two names and two tables.

.export atascii, screen

; tag atascii
.charset atascii
  "♥├▕┘┤┐╱╲◢▗◣▝▘▔▂▖♣┌─┼●▄▎┬┴▌└"                                       = $00
  "↑↓←→"                                                              = $1C
  " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_" = $20
  "♦"                                                                 = $60
  "abcdefghijklmnopqrstuvwxyz"                                        = $61
  "♠"                                                                 = $7B
  "│"                                                                 = $7C
  "\n"                                                                = $9B

  ; Inverse video is the same glyph with the bits the other way round, which
  ; for the blocks and the triangles is another character Unicode draws. Every
  ; one of these was read off the machine's own font and is exact; the rest of
  ; the inverse half has no glyph to be written as, and is reached by adding
  ; $80 or by a Charset derived from this one.
  "▊" = $82        ; ▕
  "◤" = $88        ; ◢
  "▛" = $89        ; ▗
  "◥" = $8A        ; ◣
  "▙" = $8B        ; ▝
  "▟" = $8C        ; ▘
  "▆" = $8D        ; ▔
  "▜" = $8F        ; ▖
  "▀" = $95        ; ▄
  "▐" = $99        ; ▌
  "█" = $A0        ; the space

  ; And the letters, which Unicode squares off in a negative.
  "🅰🅱🅲🅳🅴🅵🅶🅷🅸🅹🅺🅻🅼🅽🅾🅿🆀🆁🆂🆃🆄🆅🆆🆇🆈🆉" = $C1
.endch
; end atascii

.charset screen
  " !\"#$%&'()*+,-./0123456789:;<=>?"                                 = $00
  "@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_"                                 = $20
  "♥├▕┘┤┐╱╲◢▗◣▝▘▔▂▖♣┌─┼●▄▎┬┴▌└"                                       = $40
  "♦"                                                                 = $60
  "abcdefghijklmnopqrstuvwxyz"                                        = $61
  "♠"                                                                 = $7B
  "│"                                                                 = $7C

  ; The same inverses, at the display's numbers.
  "▊" = $C2
  "◤" = $C8
  "▛" = $C9
  "◥" = $CA
  "▙" = $CB
  "▟" = $CC
  "▆" = $CD
  "▜" = $CF
  "▀" = $D5
  "▐" = $D9
  "█" = $80
  "🅰🅱🅲🅳🅴🅵🅶🅷🅸🅹🅺🅻🅼🅽🅾🅿🆀🆁🆂🆃🆄🆅🆆🆇🆈🆉" = $A1
.endch

; The storage driver for a XEGS cartridge: the units are the Banks of the
; variant's `banks`, which the **byte written to `$D5FF`** brings into the
; $8000-$9FFF window — `switched` in the variant — and the stream is a pointer
; into that window that walks on to the next unit at its end. Each role is a
; macro declared with `.driver`, which the routine, the decoders and the tool's
; own Procs expand where they use it as `nga.open`, `nga.read`, `nga.show` and
; `nga.showAt`.
;
; A state of `switched` **is** a Bank number, so this driver holds no table
; where `portb.asm` holds one: the window has no named state to number before
; the Banks, since a cartridge of this kind cannot be switched off, and the
; board wires the byte written straight to the address lines above the window.
; Which is also why `show` is two instructions and nothing else.
;
; The register is written and never read — the board decodes an address and
; latches the data, and gives nothing back — so the bank a Transition left in
; is in this driver's own byte and nowhere else.
;
; Resident, and outside the window: the variant lists this Module in `resident`,
; and the tool holds it outside the window the stream reads through, since code
; that switched the window from inside it would switch itself away.

cartSelect     = $D5FF                  ; any address of $D500-$D5FF; the data is the bank
cartWindow     = $8000
cartWindowEnd  = cartWindow + $2000     ; one past the window: the high byte of the first address outside it
cartUnitPages  = $20                    ; a unit, in pages: what an offset carries by

.driver open    cartOpen
.driver read    cartRead
.driver stream  switched
.driver show    switched cartShow
.driver showAt  switched cartShowAt

.transform copy cartCopy

.macro cartOpen
        jsr cartOpenStream
.endm

.macro cartRead
        jsr cartReadByte
.endm

; The state to show, which is the Bank: the window shows nothing else.
.macro cartShow state
        lda #state
        sta cartSelect
.endm

; X = the state to show.
.macro cartShowAt
        stx cartSelect
.endm

; The stream: where the next byte is, and which unit is in. A plain zero-page
; Section rather than Temporaries, because the value has to survive between one
; call and the next while nothing here is running.
.section zeropage
cartPtr         .res 2
cartUnit        .res 1
.ends

; A = the unit, X/Y = the offset in it: the stream stands there. An offset past
; the unit's end carries into the units after, since the routine counts on in a
; Frame without knowing where a unit ends: a unit is $2000 bytes, so the
; offset's top three bits are units.
.proc cartOpenStream
        sta cartUnit
        stx cartPtr
        tya
@carry
        cmp #cartUnitPages
        bcc @within
        sbc #cartUnitPages
        inc cartUnit
        jmp @carry
@within
        clc
        adc #>cartWindow
        sta cartPtr+1
        lda cartUnit
        sta cartSelect
        rts
.endp

; A = the next byte of the stream. X and Y are not preserved.
.proc cartReadByte
        ldy #0
        lda (cartPtr),y
        inc cartPtr
        bne @done
        inc cartPtr+1
        ldy cartPtr+1
        cpy #>cartWindowEnd
        bne @done
        pha
        jsr cartNextUnit
        pla
@done
        rts
.endp

; The window's end: the next unit in, and the pointer back at its start.
.proc cartNextUnit
        inc cartUnit
        lda cartUnit
        sta cartSelect
        lda #0
        sta cartPtr
        lda #>cartWindow
        sta cartPtr+1
        rts
.endp

; The decoder of `copy`: X/Y = the destination, the stream at the stored size
; and then the bytes. Reads the window through the pointer rather than through
; cartReadByte, which is what a driver's own decoder is for: a run at a time,
; where a run ends at the source's page end or at the size, so that the inner
; loop is `(zp),y` down to zero — the window's end is a page end, so a unit is
; never crossed inside a run.
cartDst  .ztemp 2
cartSize .ztemp 2
cartRun  .ztemp 1                       ; bytes in the run, zero for 256

.proc cartCopy
        stx cartDst
        sty cartDst+1
        jsr cartReadByte
        sta cartSize
        jsr cartReadByte
        sta cartSize+1
@run
        lda cartSize
        ora cartSize+1
        beq @done
        lda cartPtr                     ; to the end of the source's page
        eor #$FF
        clc
        adc #1
        sta cartRun
        lda cartSize+1
        bne @copy                       ; at least a page left: the run stands
        lda cartRun
        beq @cap                        ; a whole page, and less than one left
        cmp cartSize
        bcc @copy
@cap
        lda cartSize
        sta cartRun
@copy
        ldy cartRun
@byte
        dey
        lda (cartPtr),y
        sta (cartDst),y
        tya
        bne @byte
        ldx cartRun                     ; the run, as 256 where it is zero
        bne @counted
        inc cartPtr+1
        inc cartDst+1
        dec cartSize+1
        jmp @crossed
@counted
        txa
        clc
        adc cartPtr
        sta cartPtr
        bcc @source
        inc cartPtr+1
@source
        txa
        clc
        adc cartDst
        sta cartDst
        bcc @destination
        inc cartDst+1
@destination
        sec
        lda cartSize
        stx cartRun
        sbc cartRun
        sta cartSize
        bcs @crossed
        dec cartSize+1
@crossed
        lda cartPtr+1
        cmp #>cartWindowEnd
        bne @run
        jsr cartNextUnit                ; the window's end: the next unit in
        jmp @run
@done
        rts
.endp

; The decoder of `zx0` over any driver's stream: Einar Saukas's ZX0, version
; 2's standard forward stream, decoded as the reference dzx0.c does, driven
; by the stream's own end marker. Written here from the format, not ported:
; nothing of the reference's text is in it, and it is licensed as everything
; under lib/ is, see lib/LICENSE. Entered with X/Y = the destination and the
; stream at the stored size, which it reads past. A match is copied a byte
; at a time, forward, from what was written, which is what makes an offset
; shorter than its length — the run — come out right. Resident, and outside
; the driver's window.
;
;   zx0Bits      the bit buffer, a sentinel one above the bits still unread
;   zx0Offset    the last offset
;   zx0Length    the length in hand, or an offset's MSB while one is read
;   zx0Invert    one while an offset's MSB is read, whose data bits the
;                stream carries complemented; zero otherwise

.transform zx0 zx0Decode

zx0Dst    .ztemp 2
zx0Src    .ztemp 2
zx0Bits   .ztemp 1
zx0Offset .ztemp 2
zx0Length .ztemp 2
zx0Invert .ztemp 1

; The next bit of the stream, in A as zero or one and in the Z flag. The
; buffer holds a sentinel above the unread bits, so shifting it to nothing is
; the signal to fetch the next byte and put the sentinel back below it.
.proc zx0Bit
        asl zx0Bits
        bne @have
        nga.read
        rol                     ; the carry the asl left is the sentinel
        sta zx0Bits
@have
        lda #0
        rol
        rts
.endp

; An interlaced Elias gamma value into zx0Length: a control bit says whether
; a data bit follows, and the value begins at one. Three Procs chained by
; `then` because the value after an offset is entered with its first control
; bit already read, at zx0EliasData: the first falls through into the
; second, and the second branches into the third, which the chain is what
; allows.
.proc zx0Elias
        lda #1
        sta zx0Length
        lda #0
        sta zx0Length+1
.endp then zx0EliasMore
.proc zx0EliasMore
        jsr zx0Bit
        beq zx0EliasData        ; zero: a data bit follows
        rts
.endp then zx0EliasData
.proc zx0EliasData
        jsr zx0Bit
        eor zx0Invert
        lsr
        rol zx0Length
        rol zx0Length+1
        jmp zx0EliasMore
.endp

; One byte written: the destination moves on and the length in hand comes
; down, leaving Z set when it reaches zero.
.proc zx0Step
        inc zx0Dst
        bne @moved
        inc zx0Dst+1
@moved
        lda zx0Length
        bne @low
        dec zx0Length+1
@low
        dec zx0Length
        lda zx0Length
        ora zx0Length+1
        rts
.endp

; The length in hand copied from zx0Dst less the last offset to zx0Dst.
.proc zx0Copy
        sec
        lda zx0Dst
        sbc zx0Offset
        sta zx0Src
        lda zx0Dst+1
        sbc zx0Offset+1
        sta zx0Src+1
@byte
        ldy #0
        lda (zx0Src),y
        sta (zx0Dst),y
        inc zx0Src
        bne @from
        inc zx0Src+1
@from
        jsr zx0Step
        bne @byte
        rts
.endp

.proc zx0Decode
        stx zx0Dst
        sty zx0Dst+1
        nga.read             ; the stored size, which the end marker makes unnecessary
        nga.read
        lda #$80
        sta zx0Bits             ; an empty buffer: the sentinel alone
        lda #1
        sta zx0Offset
        lda #0
        sta zx0Offset+1         ; the last offset begins at one
        sta zx0Invert
@literals
        jsr zx0Elias
@literal
        nga.read
        ldy #0
        sta (zx0Dst),y
        jsr zx0Step
        bne @literal
        jsr zx0Bit
        bne @offset
        jsr zx0Elias            ; a match at the last offset
        jsr zx0Copy
        jsr zx0Bit
        beq @literals
@offset
        lda #1
        sta zx0Invert
        jsr zx0Elias            ; the new offset's MSB, complemented in the stream
        lda #0
        sta zx0Invert
        lda zx0Length
        beq @done               ; 256 is the end marker, and the one value with a low byte of zero
        lsr                     ; offset = MSB * 128 - LSB / 2
        sta zx0Offset+1
        lda #0
        ror
        sta zx0Offset
        nga.read
        lsr                     ; the LSB's low bit is the length's first control bit
        php
        eor #$FF
        sec
        adc zx0Offset
        sta zx0Offset
        bcs @subtracted
        dec zx0Offset+1
@subtracted
        plp
        lda #1
        sta zx0Length
        lda #0
        sta zx0Length+1
        bcs @counted            ; a control bit of one: the value is one
        jsr zx0EliasData
@counted
        inc zx0Length           ; a match at a new offset is one longer than written
        bne @copy
        inc zx0Length+1
@copy
        jsr zx0Copy
        jsr zx0Bit
        bne @offset
        jmp @literals
@done
        rts
.endp

; The Transition routine. Called by `jsr` from a `.transition`, with the
; statement's list right behind the call: the Phase to enter, and per Phase
; the code may be in, the unit and offset where the edge's Frame waits.
; nga.open and nga.read are the driver's roles, macros of the driver's
; Module expanded here; ngaShowBases is the Proc the tool generates beside
; the dispatcher, which reads from the Frame the base the entered Phase gives
; every Window and shows it, the stream's last; and ngaCurrentPhase is the
; Cell the tool generates. Everything else the edge has to say waits in the
; Frame, in storage. See docs/spec/transition.md.
;
; Its zero page is Temporaries: nothing of it is needed once the routine has
; jumped to the entered Phase's entry, and a `.transition` is a jump into the
; routine, so whatever the statement's Section had on the zero page is dead by
; then too. Two Temporaries never live at once share an address — see
; docs/decisions/0034-trace.md.

.export ngaTransition

ngaPtr .ztemp 2
ngaEntry .ztemp 2
ngaDst .ztemp 2
ngaValue .ztemp 2
ngaOffset .ztemp 2
ngaFramePos .ztemp 2
ngaWanted .ztemp 1
ngaCount .ztemp 1
ngaFrameUnit .ztemp 1
ngaUnit .ztemp 1

.proc ngaTransition
        pla
        sta ngaPtr
        pla
        sta ngaPtr+1            ; the return address: one below the statement's list
        ldy #1
        lda (ngaPtr),y
        sta ngaWanted           ; the Phase to enter
        iny
        lda (ngaPtr),y
        sta ngaCount            ; entries that follow
        lda ngaPtr
        clc
        adc #3
        sta ngaPtr
        bcc @scan
        inc ngaPtr+1
@scan
        lda ngaCount
        bne @check
        brk                     ; no entry for the current Phase: unreachable while the static rule holds
@check
        ldy #0
        lda (ngaPtr),y
        cmp ngaCurrentPhase
        beq @found
        lda ngaPtr              ; the next entry: four bytes on
        clc
        adc #4
        sta ngaPtr
        bcc @skipped
        inc ngaPtr+1
@skipped
        dec ngaCount
        jmp @scan
@found
        iny
        lda (ngaPtr),y
        sta ngaFrameUnit        ; the unit the Frame waits in
        iny
        lda (ngaPtr),y
        sta ngaFramePos
        iny
        lda (ngaPtr),y
        sta ngaFramePos+1       ; and where in it
.endp then ngaEnter

; The rest of it, and the way in for a Container that has no current Phase to
; look one up by: ngaWanted holds the Phase to enter and ngaFrameUnit and
; ngaFramePos where its Frame waits. The cold start comes here — see
; docs/decisions/0216-a-car-names-its-format-and-the-cold-start-is-an-edge.md.
.export ngaEnter
.proc ngaEnter
        jsr ngaFrameOpen
        nga.read
        sta ngaEntry
        nga.read
        sta ngaEntry+1
        nga.read
        sta ngaCount            ; blocks that follow
        lda #3
        jsr ngaFrameSkip
@block
        lda ngaCount
        beq @cells
        jsr ngaFrameOpen        ; back to the Frame: a block's stream replaced it
        nga.read
        sta ngaUnit
        nga.read
        sta ngaOffset
        nga.read
        sta ngaOffset+1
        nga.read
        sta ngaDst
        nga.read
        sta ngaDst+1
        nga.read
        pha                     ; the decoder's number
        lda #6
        jsr ngaFrameSkip
        lda ngaUnit
        ldx ngaOffset
        ldy ngaOffset+1
        nga.open                ; the block's stream: its stored size, then its bytes
        pla
        ldx ngaDst
        ldy ngaDst+1
        jsr ngaTransform
        dec ngaCount
        jmp @block
@cells
        jsr ngaFrameOpen
        nga.read
        sta ngaCount            ; Cell writes that follow, read in one stream
@cell
        lda ngaCount
        beq @enter
        nga.read
        sta ngaDst
        nga.read
        sta ngaDst+1
        nga.read
        sta ngaValue
        nga.read
        sta ngaValue+1
        ldy #0
        lda ngaValue
        sta (ngaDst),y          ; a Cell stands outside the driver's window
        iny
        lda ngaValue+1
        sta (ngaDst),y
        dec ngaCount
        jmp @cell
@enter
        jsr ngaShowBases        ; the entered Phase's base in every Window, read from the Frame
        lda ngaWanted
        sta ngaCurrentPhase     ; the Phase the program is in from here on
        jmp (ngaEntry)
.endp

; The Frame's stream, from where the routine last left it.
.proc ngaFrameOpen
        lda ngaFrameUnit
        ldx ngaFramePos
        ldy ngaFramePos+1
        nga.open
        rts
.endp

; A bytes on in the Frame, which is where its stream is opened next.
.proc ngaFrameSkip
        clc
        adc ngaFramePos
        sta ngaFramePos
        bcc @done
        inc ngaFramePos+1
@done
        rts
.endp

; Where the cold start's Frame waits: a unit and an offset in it, which the
; Container writes here once PlaceStorage has put it somewhere. `readonly`
; because nothing writes it and it belongs in the ROM a cartridge is.
.export ngaColdFrame
.section absolute, readonly
ngaColdFrame
        .byte 0                 ; the unit
        .word 0                 ; and where in it
.ends

; What a cartridge's run vector points at, and what the OS therefore jumps to:
; the entry Phase is entered as any Phase is entered, by the routine, from a
; Frame. `root`, since the hardware reaches it and no Chunk of the program does,
; and exported because the Container writes its address into the run vector.
.export ngaStart
.proc ngaStart, root
        lda #0
        sta ngaWanted
        lda ngaColdFrame
        sta ngaFrameUnit
        lda ngaColdFrame+1
        sta ngaFramePos
        lda ngaColdFrame+2
        sta ngaFramePos+1
        jmp ngaEnter
.endp

ngaCurrentPhase

; The cartridge header: the six bytes at $BFFA the OS reads before it runs
; anything of a cartridge. $BFFC being zero is what says one is there, and the
; OS then tests that $BFFB cannot be written, which it cannot, being ROM. See
; docs/spec/car.md.

.export ngaCartStart
.section absolute at $BFFA, root, readonly
ngaCartStart
        .word 0                 ; the program's start, which the Container
                                ; patches once addresses exist: the OS jumps
                                ; through it after E: is open on IOCB 0, and
                                ; again on every reset
        .byte 0                 ; $BFFC: a cartridge is here
        .byte $04               ; $BFFD: started through $BFFA, no disk boot,
                                ; and not the diagnostic cartridge bit 7 would
                                ; make it
        .root
        .word ngaCartInit       ; $BFFE: called in the middle of the cold start
.ends

; The init vector points here and here does nothing on purpose: it is called
; before the OS has finished its own cold start and before E: exists, so
; anything run there would run in a machine half set up.
.proc ngaCartInit, root
        rts
.endp

; The dispatcher over the decoders the program declared, in the order the
; tool numbered them. See docs/spec/transition.md.
.export ngaShowBases
.proc ngaShowBases
        rts
.endp
.export ngaRestore
.proc ngaRestore
        rts
.endp
.export ngaTransform
.proc ngaTransform
        cmp #0
        bne @not0
        jmp cartCopy
@not0
        brk
.endp