Introduction
============

This repository contains the original source code for the Acorn 6502
Tube ROM, version 1.20.

Internal 65C102 Master Co Processors with version 1.20 of the ROM have
been confirmed to exist in the wild, and appear to be identical to the
version created from these sources.

No examples have been found yet of External 65C02 Second Processors
with 1.20 ROMs; these all seem to contain 1.10 (or earlier) ROMs.

The much rarer Acorn Turbo (256K) variant has never had it's ROM dumped.

The structure of the repository is as follows:

    original_sources.zip
              - a copy of the original Tube ROM source files, with the
                original <cr> line endings.

    adfs/     - disk images in ADFS (adl and dat) formats;
                these are generated by the make_disk_images.sh script
                which uses COEUS's AcornFsUtils package.

    logs/     - MASM build logs

    src/      - the Tube ROM source files

    tools/    - binaries for MASM (both DFS and non-DFS versions)

    uadesrc/  - the 1.10 Tube ROM Source in the original UADE format
                (this is complete, but not buildable within this distribution)

Assembling the Tube ROM Source Code
===================================

An Acorn Turbo (256K) 6502 Co Processor is needed to assemble the Tube
ROM sources. As originals are exceedingly rare, an alternative is the
emulated version provided by PiTubeDirect Fer-De-Lance (and later) as
Co Pro 17. The reset banner should say: "Acorn TUBE 6502 256K".

The source code is in Acorn MASM format, and a copy of the "Turbo"
version of MASM (called TurMASM) is included in the disk images.

Using ADFS:
===========

The disk organization on ADFS involves a single disk image containing
the tools (TurMASM), build scripts, source code, and sufficient free
space for the build process.

In the adfs/ directory are the following versions:

   Acorn6502TubeROM.adl - this is a 640KB interleaved disk image,
   suitable for writing to a floppy disk.

   Acorn6502TubeROM.dat - this is a 640KB non-interleaved disk image,
   suitable for using with BeebSCSI (e.g. rename it to scsi0.dat).

Transfer one of these disk images onto your physical hardware.

To assemble the sources, you just need to boot the disk (it contains
an appropriate !BOOT file)

Three versions of the Tube ROM are generated in the root directory:

The Normal Tube ROM for the external 6502 Co Processor, called NTOS:
    (this has a MD5SUM of 57759a36f9dccbdf6052aa299e519d07)

The Master Tube ROM for the internal 6502 Co Processor, called MTOS:
    (this has a MD5SUM of f77689f677e625f87f42985532fef8b9)

The Turbo Tube ROM for the Acorn 256K Turbo 6502 Co Processor, called TTOS:
    (this has a MD5SUM of b060f88964d530b5a0339ac35c945142)

Notes:
======

The sources contain the following change history:

; First version for MNG 24/10/85 (1.10)

; Second release 65C102 Boot ROM    SKS 16/01/87 (1.20)
; Also second release 6502 Boot ROM SKS 16/01/87 (1.20)
; ECR supplied by DBell 12-Jan-87

; Differences from first release :

;       Converted from UADE format to MASM format
;       Fixed bug in *GO   : *GO char in range &3A-&3F was legal before
;       Fixed bug in *HELP : *HELP subject now keeps quiet (unless subject = .)
;       OSWORD &0E number of parameter bytes bugs fixed (eg. for TIME$)
;       OSWORD &14 number of parameter bytes bugs fixed (ref. BCockburn)
;       *HELP code shortened by common abbreviation checking
;       Easy to change version numbers - only change at start of TOS01 file
;       Lots of MACROs added to clarify code
;       Labels changed to local labels where applicable
;       Turbo (extended 2nd Proc) versions can be conditionally assembled

There appear to a bug in the conditionally assembled Turbo extensions,
which I have called the "Reg0 corruption on IRQ exit" bug.

The bug affects all R4 IRQ (data trasfer) with a type 0..5, and the
affect is that REG0 receives an unnecessary ASL at the end of the IRQ
handler (without a preceeding ROR at the start). The result is the
turbo enabble/disable bit becomes indeterminate.

A fix for this involves adding 3 to the target of two branch
instructions to avoid an unnecessary ASL REG0.

See lines marked with <<<<<<<<<<<<<<<<<<<<<< below

This v1.20 ROM has probably never been used in real hardware. Or in
real hardware the indeterminate state is always turbo enabled, which
might have gone unnoticed, but would break compatibility with
non-turbo apps.

The version included in PiTubeDirect has two one-byte patches to fix
this bug.

TUBADD ROUT

        STA     NMIIND          ; RC from Host
        TYA                     ; Save Y
        PHA
        LDY     NMIIND

        LDAAY   NMILOTAB        ; New NMI routine
        STA     NMIIND
        LDAAY   NMIHITAB
        STA     NMIIND+1

        R4BYTE                  ; Read R4 (Tube owner handle)

        CPYIM   5               ; Reserved RC
        BEQ     TYARTI + 3      ; <<<<<<<<<<<<<<<<<<<<<<

        R4BYTE                  ; Ignore just one MSB of hi order addr
        R4BYTE                  ; Set up data ptr in &F6
        STA     Turbo+dataptr
        R4BYTE
        STA     dataptr+1
        R4BYTE
        STA     dataptr

        BIT     R3DATA
        BIT     R3DATA

        R4BYTE                  ; Read R4

        CPYIM   6               ; If not RC 6/7 then return
        BCC     TYARTI + 3      ; <<<<<<<<<<<<<<<<<<<<<<
        BNE     TRC7            ; C set here for RC 6/7

; .............................................................................

TRC6 ROUT ; 256 byte : Turbo -> Host

        ROR     REG0            ; Turbo on. C set on entry
        LDYIM   0

10TRC6  BIT     R3STAT
        BPL     .-3             ; NB. BPL !
        LDAIY   dataptr
        STA     R3DATA
        INY
        BNE     #10TRC6

        BIT     R3STAT
        BPL     .-3
        STA     R3DATA

; .............................................................................

TYARTI  ASL     REG0            ; Restore Turbo state, Y, A
        PLA
        TAY
        LDA     IRQatmp
        RTI

Acknowledgements:
=================

Many thanks to Stuart Swales and Paul Fellows (ex Acornsoft) for
discovering these long-lost sources and making them available to the
Acorn community.

Many thanks to Graham Toal (ex Acorn) for finding the 1.10 Tube ROM
source in the original UADE Format.