flashio.6502

\ Common routines for programming and erasing the SST39SF010 flash IC in a
\ MultiROM cartridge. Should work with any SST39SF010-based hardware that has
\ A0-A13 connected 'normally' and A14 connected to the low bit of ROMSEL.

\ ZP locations:
\ romsav (1 byte)   - saved ROM number
\ romptr (2 bytes)  - pointer into ROM

\ Before including this file, set these 'ENABLE_<routinename>' variables to TRUE
\ for routines that you wish to call.
ENABLE_ERASE_CHIP =? FALSE
ENABLE_ERASE_ROM =? FALSE
ENABLE_ERASE_SECTOR =? ENABLE_ERASE_ROM
ENABLE_PRINT_ROMS =? FALSE
ENABLE_PRINT_ROMSTR =? ENABLE_PRINT_ROMS
ENABLE_READ_BYTE =? ENABLE_PRINT_ROMSTR
ENABLE_READ_ID =? ENABLE_PRINT_ROMS
ENABLE_ROM_VALID =? ENABLE_PRINT_ROMS
ENABLE_WRITE_BYTE =? FALSE

DEBUG_ID = FALSE

IF ENABLE_READ_ID
\ Read ROM ID bytes into A and Y
\ Arguments:    X - ROM to select
\ Returns:      A - manufacturer ID
\               Y - product ID
\
\ Uses the (I think) invalid manufacturer ID &00 to indicate an error:
\       Product ID &00 - ROM did not respond to query command
\       Product ID &01 - 'ROM' is actually Sideways RAM
.read_id
{
    JSR prologue
    TXA
    JSR select_rom

    \ Check for sideways RAM before we try writing!
    LDA &8000
    EOR #&FF
    STA &8000
    CMP &8000
    BEQ ram

    LDA #&90:JSR command    \ Enter ID mode
    LDA &8000               \ Read manufacturer ID byte
    LDY &8001               \ Read product ID byte
    PHA
    LDA #&F0:JSR command    \ Exit ID mode
    PLA

\ Check if the first two bytes of the ROM match the ID bytes we just read
    CMP &8000
    BNE got_id
    CPY &8001
    BNE got_id
\... if so, we're almost certainly not looking at a valid flash IC. Return an
\ invalid ID of 00,00
IF DEBUG_ID = FALSE
    LDA #$00
    LDY #$00
ENDIF

.got_id
    JMP epilogue

.ram
\ Oops, it was actually RAM! Restore the byte we clobbered and return an
\ invalid ID of 00,01
    EOR #&FF
    STA &8000
    LDA #$00
    LDY #$01
    JMP epilogue
}
ENDIF

IF ENABLE_ERASE_SECTOR
\ Erase a single 4K sector, pointed to by romptr
\ Arguments:    X - ROM to select
\               romptr (zero page) - address of sector to erase
\ Destroys:     A, Y
.erase_sector
{
    JSR prologue
    TXA
    JSR select_rom
    LDA #&80:JSR command
    JSR magic
    TXA
    JSR select_rom
    LDA #&30
    LDY #0
    STA (romptr), Y
    JMP wait_complete
}
ENDIF

IF ENABLE_ERASE_ROM
\ Erase an entire ROM
\ Arguments:    X - ROM to select
\ Destroys:     A, Y, romptr
.erase_rom
{
    LDA #&00
    STA romptr
    LDA #&80
    STA romptr+1

    JSR erase_sector
    CLC:LDA romptr+1:ADC #&10:STA romptr+1
    JSR erase_sector
    CLC:LDA romptr+1:ADC #&10:STA romptr+1
    JSR erase_sector
    CLC:LDA romptr+1:ADC #&10:STA romptr+1
    JMP erase_sector
}
ENDIF

IF ENABLE_ERASE_CHIP    
\ Erase the whole chip
\ Arguments:    X - ROM to select
\ Destroys:     A, X
.erase_chip
{
    JSR prologue
    TXA
    JSR select_rom
    LDA #&80:JSR command
    LDA #&10:JSR command
    JMP wait_complete
}
ENDIF

IF ENABLE_WRITE_BYTE
\ Write a byte to (romptr),y
\ Arguments:    A - byte to write
\               X - ROM to select
\               (romptr), Y - address to write
\ Destroys:     A
\ Preserves:    X, Y
.write_byte
{
    PHA
    JSR prologue
    TXA
    JSR select_rom
    LDA #&A0
    JSR command
    TXA
    JSR select_rom
    PLA
    STA (romptr),Y
    \ Fall through to wait_complete
}
ENDIF

IF ENABLE_ERASE_CHIP OR ENABLE_ERASE_ROM OR ENABLE_ERASE_SECTOR OR ENABLE_WRITE_BYTE
\ SST39SF010 indicates an operation in progress by toggling bit 6 on every
\ subsequent read. Repeatedly read from ROM until we get the same value twice.
\ Preserves:    X, Y
\ Destroys:     A
.wait_complete
{
.loop
    LDA &8000
    CMP &8000
    BNE loop
    JMP epilogue
}
ENDIF

IF ENABLE_READ_BYTE
\ Read a byte from (romptr),y
\ Arguments:    X - ROM to select
\               (romptr), Y - address to write
\ Returns:      A - byte from ROM
\ Preserves:    X, Y
.read_byte
{
    PHA
    JSR prologue
    TXA
    JSR select_rom
    PLA
    LDA (romptr),Y
    JMP epilogue
}
ENDIF

IF ENABLE_PRINT_ROMS
\ Print list of ROMs, formatted as a table
\ Destroys:     A, X, Y, romptr
.print_roms
{
    LDA #&00:STA romptr
    LDA #&80:STA romptr+1

\ Loop through all ROMs and print ROM #, type, rom name, version string (if present), and version byte
    LDX #&0F
.loop
    TXA:PHA
    JSR print_hex           \ Print ROM #

    JSR print_space
    JSR read_id             \ Read ROM ID bytes
    
IF DEBUG_ID
    PHA
    JSR print_byte
    JSR print_space
    TYA
    JSR print_byte
    JSR print_space
    PLA
ENDIF

    CMP #0:BNE checkflash   \ mfg ID nonzero, check if we're a flash chip
    CPY #1:BEQ ram          \ mfg ID 0, product ID 1 = writeable memory
    PLA:TAX:PHA
    JSR rom_valid:BNE empty \ Otherwise, we're rom, check if the ROM is valid
    LDA #'R':JMP print_type
.checkflash
    CMP #&BF:BNE unknown
    CPY #&B5:BNE unknown    
    LDA #'F':JMP print_type \ We only consider SST39SF010 (ID byte &BF &BE) to be Flash
.ram
    LDA #'W':JMP print_type
.unknown
    JSR rom_valid:BNE empty \ Check for a rom signature; a bogus ID could be 
    LDA #'?':JMP print_type \ just noise from an undriven bus
.empty
    LDA #'-'
.print_type
    JSR osasci

    PLA:TAX
    JSR rom_valid:BNE nextrom   \ No point printing name string for invalid ROMs
    \ Side-effect of rom_valid call saves offset of copyright string into zeropage

    JSR print_space
    LDY #&08
    JSR read_byte
    JSR print_byte          \ Byte at offset &08 is a binary version number
    
    JSR print_space
    LDY #&09
    JSR print_romstr        \ String at offset &09 is ROM name
    CPY copyright_offset    \ Check if we have reached the offset of the copyright string yet
    BEQ nextrom             \...If yes, we're done
    INY                     \...If not, there's a second string with version info
    JSR print_space
    JSR print_romstr

.nextrom
    JSR osnewl
    DEX
    BPL loop
    RTS
}

\ Print a space
\ Preserves:    X, Y
\ Destroys:     A
.print_space
    LDA #' ':JMP osasci

\ Print a byte as hex
\ Arguments:    A - byte to print
\ Preserves:    X, Y
\ Destroys:     A
.print_byte
    PHA:LSR A:LSR A:LSR A:LSR A:JSR print_hex
    PLA
.print_hex
{
    AND #&0F
    ORA #'0'
    CMP #':'
    BCC out
    ADC #$06
.out
    JMP osasci
}
ENDIF

IF ENABLE_PRINT_ROMSTR
\ Print a string from ROM, stopping at the first control character
\ Arguments:    (romptr), Y - start address of string
\               X - ROM number
\ Returns:      Y incremented to end of string
\ Preserves:    X, romptr
\ Destroys:     A
.print_romstr
{
    JSR read_byte
    CMP #&20:BMI done       \ Stop as soon as we hit a control char
    CMP #&7F:BPL skip_char  \ Skip chars &7F and above
    JSR osasci
.skip_char
    INY
    BNE print_romstr
.done
    RTS
}
ENDIF

IF ENABLE_ROM_VALID
\ Check for a valid ROM (existence of copyright string)
\ Arguments:    X - ROM number
\               romptr must be &8000
\ Returns:      A=0 if valid, nonzero if invalid
\               copyright_offset = contents of offset &07
\ Preserves:    X, romptr
\ Destroys:     Y
.rom_valid
{
    LDY #&07:JSR read_byte  \ Offset &07 = start of copyright string
    STA copyright_offset
    TAY:JSR read_byte:CMP #0  :BNE done \ Copyright string must start with NUL + '(C)'
    INY:JSR read_byte:CMP #'(':BNE done
    INY:JSR read_byte:CMP #'C':BNE done
    INY:JSR read_byte:CMP #')':BNE done
.done
    RTS
}
ENDIF

\*******************************************************************************
\ Private routines used within this source file.

\ Disable interrupts and save current ROM
\ Preserves:    A, X, Y
.prologue
{
    PHA
    SEI
    LDA romzp
    STA romsav
    PLA
    RTS
}

\ Re-enable interrupts and page original ROM back in
\ Preserves:    A, X, Y
.epilogue
{
    PHA
    LDA romsav
    JSR select_rom
    CLI
    PLA
    RTS
}

\ Page in a ROM
\ Arguments:    A - rom number to page in
\ Preserves:    A, X, Y
.select_rom
{
\ Workaround for Electron's odd handling of ROM selection
\ To correctly select ROMs < 8, we must first select a ROM between &C and &F.
\ For explanation see https://beebwiki.mdfs.net/Paged_ROM#Electron and
\ https://stardot.org.uk/forums/viewtopic.php?p=6681#6681
    CMP #&08:BCS do_select
    PHA
    LDA #&0F:STA romzp:STA romsel
    PLA
.do_select
    STA romzp
.*romsel_sta    \ export this label so that we can patch the address of ROMSEL on Electron
    STA romsel
    RTS
}

\ Select low ROM
\ Preserves:    X, Y
\ Destroys:     A
.low_rom
{
    LDA romzp
    AND #&FE
    JSR select_rom
    RTS
}

\ Select high ROM
\ Preserves:    X, Y
\ Destroys:     A
.high_rom
{
    LDA romzp
    ORA #&01
    JSR select_rom
    RTS
}

\ Send 'magic write' sequence to the currently paged-in ROM
\ Preserves:    X, Y
\ Destroys:     A
.magic
{
    JSR high_rom
    LDA #&AA:STA &9555      \ Write &AA to &5555
    JSR low_rom
    LDA #&55:STA &AAAA      \ Write &55 to &2AAA
    RTS
}

\ Send a command to the currently paged-in ROM
\ Arguments:    A - command byte to send
\ Preserves:    A, X, Y
.command
{
    PHA
    JSR magic   \ Write &AA to &5555, &55 to &2AAA
    JSR high_rom
    PLA
    STA &9555   \ Write command byte to &5555
    RTS
}