Homebrew BreadBoard Computer (BBC!) - hb128bbc

Quick introduction notes on this zip file

All folders contain .s and .i assembler files which are processed by as65.exe
except for these special folders;
-	readme.txt:	This file
-   build:      The main folder to build the source (see below for details)
-   docs:       Where I will eventually put design and other docs (WIP)
- 	EMU:        Emulation folder containing a custom version of mame
		        The make file writes the combined ROM to the emu folder space
		        This custom version of mame created by Nigel Barnes, a mighty
		        mame developer which has made a release to GitHub possible!
                How to use the emulator is described later in this doc.
-   Projects:   In each folder is a project which is in essence a standalone
                environment to build larger binaries. This is WIP
-	rom:        Binaries and final ROM image
		        bank*.bin is the assembled binary for each 16KB bank
		        HB-BBC-128.ROM is the combined 64KB ROM file for the whole system
		        This 64K ROM can be burnt or used in the mame emulator (as above)
-   SDCARD:     A copy of the SD card that the homebrew will boot rom.
                Note the actual sd card image for MAME is in the EMU/software
                folder and the two need to be kept manually in sync.

build:          This folder is the root for source files to build the
                ROM software. Source code folders are described below
                this section which explains non-source folders and
                behaviour.
-	as65.exe: 	I have packaged the as65 assembler by Kingswood Consulting
-	as65.man: 	As per Kingswood Consulting terms, this file is distributed
 				with their assembler and provides detailed information on
 				usage.
-	make.ps1:	This is the powershell build script which reequires to run.
				It will re-assemble all source and generate a ROM file that
				also is copied to the emulator folder, ready to run.
                In summary, the make file builds four 16KB bin files using
                the information in the build/bank[0,1,2,3].s files and the
                build/bank/extern.mak file. The 16KB binaries are combined
                into a single 64K ROM which can be burnt to an EEPROM.
                This file is also copied to the EMU/roms folder as a zip
                to be used under MAME (the EMU/hb128bbc.exe file).
-	bank:       Configuration of 4x16KB banks in the ROM
		        The bank*.sym and bank*.lst are generated by as65 assembly
		        bank.i is the macro used to enable globally accessible routines
	            During assembly, ROM banks are constructed in this folder.
		        bank[0,1,2,3].s import the assembly for each bank.
		        the .lst files are listing files from assembly
		        extern.mak defines which routines are to be cross-bank accessible
		        autogen.s is created by the make file and generates the build date
-	cia:	    65c22 VIA handling (including memory bank selection)
-	dflat:	    dflat interpreter files
-	inc:	    include files
-	kernel:	    reset, interrupt, boot and cross-bank call handling
-	keyboard:   keyboard handling
-	monitor:    basic monitor
-	rtc:	    Realtime clock handling
-	sdcard:	    SD card protocol and FAT16 filesystem handling
-	serial:	    ACIA handling
-	sound:	    AY-3-8910 handling (including joystick)
-	utils:	    Helper routines (including integer math)
-	vdp:	    Graphics handling (including system fonts)

Build quick quide (using powershell as the CLI);
    You need to be in the build folder of the homebrew directory.
	Invoke ./make.ps1 which rebuilds all source, the output of 4x16KB bin and
    a single 64KB rom in the rom folder.  In addition the rom file is compressed
    and copied to the emu/roms folder.

Running under mame *very* quick guide (using powershell as the CLI)
	You need to be in the EMU folder of the homebrew directory
	Type ./hb128bbc hb128bbc
    This will start the emulator - press tab to skip the machine info screen
    If the warning screen shows, press tab
    Tab key is used on startup to get to the config menu:
        Navigate to File Manager
        Select harddisk
        If sdcard64m.img is not shown then navigate to it and select
        Select Reset system
    By now the machine should be fired up with filesystem reported as mounted.

    Keyboard mapping note on my PC keyboard:
        underscore is to the left of 1
        pund is shift and that key noted above
        hash symbol is shift 3
        and symbol is shift 6
        single quote is shift 7
        open bracket is shift 8
        close bracket is shift 9
        equals is shift - (the minus key)
        plus is shift ;
        colon is '
        multiply is shift '
        at symbol is #

    Now, let's try a game. Type:
        chdir "games/tetris" (goes to the indicated folder)
        load "tetris3.prg"   (loads the program - takes about 20 seconds)
        _start()             (starts the game)
        When the game starts, use the left and right arrows to turn music
        off or on.  The arrows keys act like the joystick and the fire
        button is ctrl.
        It's tetris, so need I say more!

Running under mame guide (using powershell as the CLI)
	You need to be in the EMU folder of the homebrew directory
	Invoke mame in one of the  following ways;
     1. ./hb128bbc hb128bbc *OR*
     2. ./hb128bbc hb128bbc -serial terminal *OR*
     3. ./hb128bbc hb128bbc -serial null_modem -bitb socket.localhost:6502
    The file hb128bbc.exe is actually a minimal build of mame by Nigel Barnes
    (hugely grateful for his help!). Mame is a complex beast with many
    options beyond my knowledge, but there are a couple of important things
    about you need to know to make best use of emulation.
    Option 1 starts in normal mode (i.e. PC keyboard acts as input).
    Option 2 starts with mame's default terminal program
    Option 3 starts with a local websocket as the serial port which allows you
    to attach regular terimal program such as Tera Term or PuTTY.
    When using serial, my preferred is option 3. 
    Press enter to skip the mame start up messages and warnings.
    Main PC key to know about is F12 which is the reset key which causes the
    machine to go through a power up cycle.
    Press F12 with F2 to boot with serial port as input.  If no key
    is pressed during reset the machine boots to regular keyboard mode by
    default.
    To control the mame emulator options, you need to enable the UI controls
    by activating Scroll-Lock on your keyboard (mame briefly indicates when UI
    controls are enabled or disabled).

SD-card image under MAME;
    The image is 64MB to keep the binary size down, but works fine even
    though the real machine supports a 1GB card.  This image can also
    be mounted using many ISO mount utilities (I use ImDisk) which allows
    access to the image as a disk volume.  You must not be in the emulator
    to do this, and you must release any images mounted on the PC before
    running the emulator.

Serial input/output emulation;
    My homebrew computer supports input through a real keyboard or through
    the serial port, which Mame supports very well through the start up
    options I listed above.
    If you use option 3 (local socket) then some quick guidance;
    1. Never use the Mame machine reset option as it disconnects serial
    2. Always use F12 which will cause the homebrew computer to reboot
    3. Start the emulator before the terminal program and press F12 + F2
    4. This will start transmitting over the socket and establish comms
    Why go through all this hassle vs using Mame's built in terminal?
    The answer is that gives a truer experience and access to features
    such as XMODEM transfers.  Also Tera Term or PuTTY are much nicer
    Than the basic Mame terminal and are not stuck on the side of the
    emulation.