Homebrew BreadBoard Computer (BBC!) - hb128bbc

Quick introduction notes on this zip file
Root;
-	readme.txt:	This file
-	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.bat:	This is the build script which reequires cmd or powershell
-				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 bank[0,1,2,3].s files and the
-               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 emulator roms folder to be used under MAME.

All folders contain .s and .i assembler files which are processed by as65.exe
except for these special folders;
-	bank
-	emu
-	rom

Special folder descriptions;
-	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
- 	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.
-	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)

Code source folder structures;
-	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 root folder of the homebrew directory.
-	Invoke ./make.bat from the command line. This rebuilds all source, the
-   output of 4x16KB bin and a single 64KB rom file in the rom folder.  In
-   addition the rom file is compressed and in the emu/roms folder.

Running under mame quick guide (using powershell as the CLI)
-	Your 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;
-     There is a filesystem image which can be mounted to emulate the SD
-     card of the real machine.  When the emulator first boots, you need to
-     do the following;
-       1. Activate kayboard Scroll-Lock to get enable emulator UI controls
-       2. Press the TAB key to bring up the emulator menu
-       3. Select 'File Manager' and press enter on 'harddisk (hard)'
-       4. Navigate to the software\filesystem folder
-       5. Select the file 'sdcard64m.img' (press enter on this file)
-       6. Exit mame menus by pressing ESC until back to the main display
-       7. Disable emulator UI controls (Scroll-Lock)
-       8. Reset the machine using F12 (with F2 as needed for serial)
-     This will reset the machine and there should be no boot up messages
-     about bad SD card or failed to mount the filesystem.  You can easily
-     confirm by entering the command 'dir' which will display the
-     directory.
-     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;
-     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.