diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index 2eadb3ce..00000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,26 +0,0 @@ -name: CI - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v2 - - uses: rlespinasse/github-slug-action@1.1.0 - - - name: Install Dependencies - run: | - sudo apt-get install libncurses-dev - - name: Build - run: | - make - make clean - rm -rf .git - - name: Upload Archive - uses: actions/upload-artifact@v1 - with: - name: RomWBW-${{env.GITHUB_REF_SLUG}}-${{env.GITHUB_SHA_SHORT}} - path: . diff --git a/.github/workflows/commit.yml b/.github/workflows/commit.yml new file mode 100644 index 00000000..7cdbe1a0 --- /dev/null +++ b/.github/workflows/commit.yml @@ -0,0 +1,31 @@ +name: Commit Build + +on: + push: + branches: + - master + tags-ignore: + - v* + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: rlespinasse/github-slug-action@1.1.0 + + - uses: actions/checkout@v2 + + - name: Build + run: | + sudo apt-get install libncurses-dev + make + make clean + rm -rf .git* + + - name: Upload Artifact + uses: actions/upload-artifact@v1 + with: + name: RomWBW-${{env.GITHUB_REF_SLUG}}-${{env.GITHUB_SHA_SHORT}} + path: . \ No newline at end of file diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..5e5fbaaf --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,51 @@ +name: Release Build + +on: + release: + types: published + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + + - name: Create Package Label + run: | + LABEL=`echo "$GITHUB_REF" | sed "s|^refs/tags/||"` + echo "::set-env name=PKGLBL::$LABEL" + + - name: Display Diagnostics + run: | + echo PKGLBL: "$PKGLBL" + echo Upload URL: "${{github.event.release.upload_url}}" + echo GITHUB_TOKEN: "${{secrets.GITHUB_TOKEN}}" + + - name: Build + run: | + sudo apt-get install libncurses-dev + make + make clean + rm -rf .git* + + - name: Upload Artifact + uses: actions/upload-artifact@v1 + with: + name: RomWBW-${{env.PKGLBL}}-Package + path: . + + - name: Create Package Archive + run: | + zip -r Package.zip . + + - name: Upload Release Asset + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} + with: + upload_url: ${{github.event.release.upload_url}} + asset_path: Package.zip + asset_name: RomWBW-${{env.PKGLBL}}-Package.zip + asset_content_type: application/zip \ No newline at end of file diff --git a/Doc/cpm3_command_guide.pdf b/Doc/CPM3 Command Summary.pdf similarity index 100% rename from Doc/cpm3_command_guide.pdf rename to Doc/CPM3 Command Summary.pdf diff --git a/Doc/cpm3_programmers_guide.pdf b/Doc/CPM3 Programmers Guide.pdf similarity index 100% rename from Doc/cpm3_programmers_guide.pdf rename to Doc/CPM3 Programmers Guide.pdf diff --git a/Doc/cpm3_system_guide.pdf b/Doc/CPM3 System Guide.pdf similarity index 100% rename from Doc/cpm3_system_guide.pdf rename to Doc/CPM3 System Guide.pdf diff --git a/Doc/cpm3_users_guide.pdf b/Doc/CPM3 Users Guide.pdf similarity index 100% rename from Doc/cpm3_users_guide.pdf rename to Doc/CPM3 Users Guide.pdf diff --git a/Doc/Contrib/LinuxBuild.txt b/Doc/Contrib/LinuxBuild.txt deleted file mode 100644 index 6855fe0f..00000000 --- a/Doc/Contrib/LinuxBuild.txt +++ /dev/null @@ -1,49 +0,0 @@ -Assembling the RomWBW firmware under Linux. - -Note: This process is generally deprecated as it has not been maintained. -This document remains in the hope that someday it will be useful for -resurrecting a Linux build. - -Note: Updated on 6/25/2013 to eliminate the need for the separate Linux -makefile. The standard makefile now has conditionals to allow it to be -used under Windows or Linux (I hope) --WW - -This method has been used under Ubuntu Linux and may have to be adapted for -other distributions. It is a bit more involved than the Windows procedure. - -What you need -You will need the TASM assembler, make, dos2unix and cpmtools. - -The TASM assembler is shareware and the Linux version is only available as -source code from the Author. I found one bug during compiling version 3.2 for -Ubuntu. In /src/tasm.c change the reference CLK_TIC to CLOCKS_PER_SEC. -After compiling install the tasm executable to /usr/local/bin and the table -files to /usr/local/lib. If you choose to place them somewhere else you will -have to edit the "makefile.linux" file to suit. - -The make, dos2unix and cpmtools packages are found in the Linux repository and -installed as for any other package. - -Before assembly -Some changes need to be made to cater for the differences between Linux and the -DOS/Windows environments. The examples below refer to the /RomWBW/current -directory, you'll have to allow for the stable or branches directories if used. -These are all done from a terminal. (: is end of the command prompt) - -1. Go to the RomWBW Source directory.e.g. -:cd /n8vem/RomWBW/current/Source - -2. The Linux version of TASM can't handle the CR-LF line endings. So from the -command prompt use dos2unix to convert all the source files. -:~/RomWBW/current/Source dos2unix -f *.asm *.inc *.z80 *.lib diskdefs - -3. You'll have to alter the disk definitions for the cpmtools package to cater -for the new roms. Easiest way is to copy the one given in the source over the -old. This must be done as superuser. -:~/RomWBW/current/Source sudo cp diskdefs /etc/cpmtools/diskdefs - -4. From now on it's the same as using the DOS/Windows instructions in Build.txt. -Make any last changes, go to the Source directory and make -:~/RomWBW/current/Source make clean ; make - -DGG diff --git a/Doc/Contrib/Z180 Clocking.txt b/Doc/Contrib/Z180 Clocking.txt deleted file mode 100644 index 846c73b0..00000000 --- a/Doc/Contrib/Z180 Clocking.txt +++ /dev/null @@ -1,19 +0,0 @@ -The table below can be used to determine the correct value for CLKDIV AND CNTLB -in an Z180 (N8) configuration file. OSC Freq refers to the hardware clock -oscillator frequency you are using. You can then choose a CLKDIV value which -will result in the CPU speed (frequency) shown below the oscillator frequency. - -Using your oscillator frequency (OSC) and chosen value for CLKDIV, you can -use the appropriate column to derive values to use for CNTLB for different -baud rates. - - ----- CLKDIV = 0 ----- ----- CLKDIV = 1 ----- -OSC Freq (MHz) 6.144 12.288 18.432 6.144 12.288 18.432 -CPU Freq (MHz) 3.072 6.144 9.216 6.144 12.288 18.432 - -1200 baud 04H 05H 24H 05H 06H 25H -2400 baud 03H 04H 23H 04H 05H 24H -4800 baud 02H 03H 22H 03H 04H 23H -9600 baud 01H 02H 21H 02H 03H 22H -19200 baud 00H 01H 20H 01H 02H 21H -38400 baud --- 00H --- 00H 01H 20H \ No newline at end of file diff --git a/Doc/NZCOM Manual.pdf b/Doc/NZCOM Users Manual.pdf similarity index 100% rename from Doc/NZCOM Manual.pdf rename to Doc/NZCOM Users Manual.pdf diff --git a/Doc/ReadMe.txt b/Doc/ReadMe.txt index 9f596272..276003d6 100644 --- a/Doc/ReadMe.txt +++ b/Doc/ReadMe.txt @@ -10,6 +10,7 @@ This directory ("Doc") is part of the RomWBW System Software distribution archive. It contains documentation for components of the system. + CPM Manual ("CPM Manual.pdf") ----------------------------- @@ -18,23 +19,64 @@ considered the primary reference for system operation. The section on CP/M 2 Alteration can be ignored since this work has already been completed as part of the RomWBW distribution. + +CPM3 Command Summary ("CPM3 Command Summary.pdf") +CPM3 Programmer's Guide ("CPM3 Programmers Guide.pdf") +CPM3 System Guide ("CPM3 System Guide.pdf") +CPM3 User's Guide ("CPM3 Users Guide.pdf") +------------------------------------------------------ + +The original DRI CP/M 3.0 Operating System Documentation Set. This +should be considered the primary reference for CP/M 3 system operation. + + DDTZ Manual ("DDTZ.doc") ------------------------ Manual for the DDTZ v2.7 debug tool included on the ROM drive. + FDisk Manual ("FDisk Manual.pdf") --------------------------------- The operational manual for John Coffman's hard disk partitioning program. This program is included in RomWBW as FDISK80. + +Floppy Disk Utility Documentation ("FDU.tst") +--------------------------------------------- + +Operational documentation for the RomWBW FDU application. + + +Hard Disk Anatomy ("Hard Disk Anatomy.pdf") +------------------------------------------- + +Diagram of a CP/M & MS-DOS (FAT) hybrid hard disk layout. + + +NZCOM User's Manual ("NZCOM Users Manual.pdf") +---------------------------------------------- + +NZCOM operating system operation manual. + + RomWBW Architecture ("RomWBW Architecture.pdf") ----------------------------------------------- Document describing the architecture of the RomWBW HBIOS. It includes reference information for the HBIOS calls. + +Z180 ASCI Baud Rate Options ("Z180 ASCI Baud Rate Options.pdf") +--------------------------------------------------------------- + +The Z180 processor's ASCI serial ports have a limited set of +baud rate divisors. These divisors are relative to the CPU +clock rate. This document provides a list of the possible +baud rates for typical CPU clock rates. + + ZCPR Manual ("ZCPR Manual.pdf") ------------------------------- @@ -43,6 +85,7 @@ manual for ZCPR 1.x as included in RomWBW. The installation instructions can be ignored since that work has already been completed as part of the RomWBW distribution. + ZSDOS Manual ("ZSDOS Manual.pdf") --------------------------------- diff --git a/Doc/RomWBW Architecture.pdf b/Doc/RomWBW Architecture.pdf index 0f81ccd7..0c2782cc 100644 Binary files a/Doc/RomWBW Architecture.pdf and b/Doc/RomWBW Architecture.pdf differ diff --git a/Doc/RomWBW Getting Started.pdf b/Doc/RomWBW Getting Started.pdf new file mode 100644 index 00000000..fa0f8640 Binary files /dev/null and b/Doc/RomWBW Getting Started.pdf differ diff --git a/Doc/ZCPR Manual.pdf b/Doc/ZCPR Manual.pdf index ce5f80b8..50668527 100644 Binary files a/Doc/ZCPR Manual.pdf and b/Doc/ZCPR Manual.pdf differ diff --git a/ReadMe.md b/ReadMe.md new file mode 100644 index 00000000..0b5dcde6 --- /dev/null +++ b/ReadMe.md @@ -0,0 +1,1027 @@ +# RomWBW + +## Z80/Z180 System Software + +Version 2.9.2 +Friday 20 March 2020 + +Wayne Warthen + +### Download + + - [RomWBW Distribution + Package](https://github.com/wwarthen/RomWBW/releases) + +### Related Pages + + - [RomWBW Architecture + Document](https://www.retrobrewcomputers.org/lib/exe/fetch.php?media=software:firmwareos:romwbw:romwbw_architecture.pdf) + - [RomWBW + Applications](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps) + - [RomWBW + Errata](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:errata) + +# Overview + +RomWBW provides a complete software system for a wide variety of +hobbyist Z80/Z180 CPU-based systems produced by these developer +communities: + + - [RetroBrew Computers](https://www.retrobrewcomputers.org) + - [RC2014](https://rc2014.co.uk) + - [retro-comp](https://groups.google.com/forum/#!forum/retro-comp) + +General features include: + + - Banked memory services for several banking designs + - Disk drivers for RAM, ROM, Floppy, IDE, CF, and SD + - Serial drivers including UART (16550-like), ASCI, ACIA, SIO + - Video drivers including TMS9918, SY6545, MOS8563, HD6445 + - Real time clock drivers including DS1322, BQ4845 + - Multiple OS support including CP/M 2.2, ZSDOS, CP/M 3, ZPM3 + - Built-in VT-100 terminal emulation support + +RomWBW is distributed as both source code and pre-built ROM and disk +images. Some of the provided software can be launched directly from the +ROM firmware itself: + + - System monitor + - Operating systems (CP/M 2.2, ZSDOS) + - ROM BASIC (Nascom BASIC and Tasty BASIC) + - ROM Forth + +A dynamic disk drive letter assignment mechanism allows mapping +operating system drive letters to any available disk media. +Additionally, mass media devices (IDE Disk, CF Card, SD Card) support +the use of multiple slices (up to 256 per device). Each slice contains a +complete CP/M filesystem and can be mapped independently to any drive +letter. This overcomes the inherent size limitations in legacy OSes +providing up to 2GB of accessible storage on a single device. + +The pre-built ROM firmware images are generally optimal for most users. +However, it is also very easy to modify and build custom ROM images that +fully tailor the firmware to your specific preferences. All tools +required to build custom ROM firmware are included – no need to install +assemblers, etc. Any modern computer running Windows, Linux, or MacOS +can be used. + +Multiple disk images are provided in the distribution. Most disk images +contain a complete, bootable, ready-to-run implementation of a specific +operating system. A “combo” disk image contains multiple slices, each +with a full operating system implementation. If you use this disk image, +you can easily pick whichever operating system you want to boot without +changing media. + +# Installation + +The latest RomWBW distribution downloads are maintained on GitHub in the +[RomWBW Repository](https://github.com/wwarthen/RomWBW). The fully-built +distributions are found on the [releases +page](https://github.com/wwarthen/RomWBW/releases) of the repository. On +this page, you will probably see both pre-releases as well as normal +releases. Unless you have a specific reason, I suggest you stick to the +most recent normal release (not pre-release). Expand the “Assets” +drop-down for the release you want to download, then select the asset +named RomWBW-vX.X.X-Package.zip. The Package asset includes all +pre-built ROM and Disk images as well as full source code. The other +assets are Source Code only and do not have the pre-built ROM or disk +images. + +The pre-built ROM images will automatically detect and support a +reasonable range of devices including serial ports, video adapters, +on-board disk interfaces, and PropIO/ParPortProp boards without building +a custom ROM. The distribution is a .zip archive. After downloading it +to a working directory on your modern computer (Windows/Linux/Mac) use +any zip tool to extract the contents of the archive. + +In general, you will just program your system’s ROM chip with the +appropriate ROM image from the RomWBW distribution. Depending on how you +got your system, you may have already been provided with a +pre-programmed ROM chip. If so, use that initially. Otherwise, you will +need to use a ROM programmer to initially program your ROM chip. Please +refer to the documentation that came with your ROM programmer for more +information. Once you have a running RomWBW system, you can generally +update your ROM to a newer version in-situ with an included ROM Flashing +tool (Will Sowerbutts’ FLASH application) as described in the Upgrading +section below. + +Looking at the extracted distribution archive, You will see that the +distribution is broken up into a few sub-directories. The Binary +directory contains the pre-built ROM and disk images. The ROM image +files all end in “.rom”. Based on the table below, **carefully** pick +the appropriate ROM image: + +| Platform | ROM Image File | Baud | Description | +| ------------- | --------------- | -----: | ----------------------------------------------- | +| SBC V1/V2 | SBC\_std.rom | 38400 | RetroBrew SBC v1 or v2 ECB Z80 | +| Zeta V1 | ZETA\_std.rom | 38400 | RetroBrew Zeta V1 Z80, ParPortProp (optional) | +| Zeta V2 | ZETA2\_std.rom | 38400 | RetroBrew Zeta V2 Z80, ParPortProp (optional) | +| N8 | N8\_std.rom | 38400 | RetroBrew N8 Z180, date code \>= 2312 | +| Mark IV | MK4\_std.rom | 38400 | RetroBrew Mark IV ECB Z180 | +| RC2014 Z80 | RCZ80\_std.rom | 115200 | RC2014 w/ Z80 CPU, requires 512K RAM/ROM module | +| RC2014 Z180\* | RCZ180\_ext.rom | 115200 | RC2014 w/ Z180 CPU & 512K banked RAM/ROM module | +| RC2014 Z180\* | RCZ180\_nat.rom | 115200 | RC2014 w/ Z180 CPU & 512K native RAM/ROM module | +| Easy Z80 | EZZ80\_std.rom | 115200 | Sergey Kiselev’s Easy Z80 | +| SC126 | SCZ180\_126.rom | 115200 | Stephen Cousin’s SC126 Z180 | +| SC130 | SCZ180\_130.rom | 115200 | Stephen Cousin’s SC130 Z180 | +| SC131 | SCZ180\_131.rom | 115200 | Stephen Cousin’s SC131 Z180 | +| Dyno | DYNO\_std.rom | 38400 | Steve Garcia’s Z180 Dyno Computer | + +\*The RC2014 Z180 requires a separate RAM/ROM memory module. There are +two types of these modules and you must pick the ROM for your type of +memory module. The “ext” ROM supports Spencer’s official 512K RAM/ROM +banked memory module. The “nat” ROM supports any of the third-party Z180 +native memory modules. + +RomWBW will automatically attempt to detect and support typical add-on +components for each of the systems supported. More information on the +required system configuration and optional supported components for each +ROM is found in the file called “RomList.txt” in the Binary directory. +All pre-built ROM images are simple 512KB binary images. If your system +utilizes a larger ROM chip, you can just program the image into the +first 512KB of the ROM. + +Connect a serial terminal or computer with terminal emulation software +to the primary serial port of your CPU board. You may need to refer to +your hardware provider’s documentation for details. A null-modem +connection may be required. Set the baud rate as indicated in the table +above. Set the line characteristics to 8 data bits, 1 stop bit, no +parity, and no flow control. If possible, select VT-100 terminal +emulation. + +Upon power-up, your terminal should display a sign-on banner within 2 +seconds followed by hardware inventory and discovery information. When +hardware initialization is completed, a boot loader prompt allows you to +choose a ROM-based operating system, system monitor, application, or +boot from a disk device. + +Initially, you should try the ROM boot options. By selecting either CP/M +2.2 or Z-System, the operating system will be loaded from ROM and you +will see the a `B>` disk prompt. In this scenario, A: will be an empty +RAM disk and B: will refer to your ROM disk containing some typical +applications. This provides a simple environment for learning to use +your system. Be aware that files saved to the RAM disk (A:) will +disappear at the next power on (RAM is generally not persistent). Also +note that attempts to save files to the ROM disk (B:) will fail because +ROM is not writable. + +# Upgrading + +Upgrading to a newer release of RomWBW is essentially just a matter of +updating the ROM chip in your system. If you have spare ROM chips for +your system and a ROM programmer, it is always safest to keep your +existing, working ROM chip and program a new one with the new firmware. +If the new one fails to boot, you can easily return to the known working +ROM. + +Prior to attempting to reprogram your actual ROM chip, you may wish to +“try” the upgrade. With RomWBW, you can upload a new system image and +load it from the command line. For each ROM image file (.rom) in the +Binary directory, you will also find a corresponding application file +(.com). For example, for SBC\_std.rom, there is also an SBC\_std.com +file. You can upload the .com file to your system using XModem, then +simply run the .com file. You will see your system go through the normal +startup process just like it was started from ROM. However, your ROM has +not been updated and the next time you boot your system, it will revert +to the system image contained in ROM. You may find that you are unable +to load the .com file because it is too large to fit in available +application RAM (TPA). Unfortunately, in this case, you will not be able +to use the .com file mechanism to start your system. + +If you do not have easy access to a ROM programmer, it is usually +possible to reprogram your system ROM using the FLASH utility from Will +Sowerbutts. This application called FLASH.COM can be found on the ROM +drive of any running system. In this case, you would need to transfer +the new ROM image (.rom) over to your system using XModem (or one of the +other mechanisms described in the Transferring Files section below). The +ROM image will be too large to fit on your RAM drive, so you will need +to transfer it to a larger storage drive. Once the ROM image is on your +system, you can use the FLASH application to update your ROM. The +following is a typical example of transferring ROM image using XModem +and flashing the chip in-situ. + + E>xm r rom.img + + XMODEM v12.5 - 07/13/86 + RBC, 28-Aug-2019 [WBW], ASCI + + Receiving: E0:ROM.IMG + 7312k available for uploads + File open - ready to receive + To cancel: Ctrl-X, pause, Ctrl-X + + Thanks for the upload + + E>flash write rom.img + FLASH4 by Will Sowerbutts version 1.2.3 + + Using RomWBW (v2.6+) bank switching. + Flash memory chip ID is 0xBFB7: 39F040 + Flash memory has 128 sectors of 4096 bytes, total 512KB + Write complete: Reprogrammed 2/128 sectors. + Verify (128 sectors) complete: OK! + +Obviously, there is some risk to this approach since any issues with the +programming or ROM image could result in a non-functional system. + +To confirm your ROM chip has been successfully updated, restart your +system and boot an operating system from ROM. Do not boot from a disk +device yet. Review the boot messages to see if any issues have occurred. + +Once you are satisfied that the ROM is working well, you will need to +update the system images and RomWBW custom applications on your disk +drives. The system images and custom applications are matched to the +RomWBW ROM firmware in use. If you attempt to boot a disk or run +applications that have not been updated to match the current ROM +firmware, you are likely to have odd problems. + +The simplest way to update your disk media is to just use your modern +computer to overwrite the entire media with the latest disk image of +your choice. This process is described below in the Disk Images section. +If you wish to update existing disk media in your system, you need to +perform the following steps. + +If the disk is bootable, you need to update the system tracks of the +disk. This is done using a SYSCOPY command such as `SYSCOPY +C:=B:ZSYS.SYS`. For a ZSDOS boot disk, use ZSYS.SYS. For a CP/M 2.2 +disk, use CPM.SYS. For a CP/M 3 or ZPM3 disk, use CPMLDR.SYS. CPMLDR.SYS +is not provided on the ROM disk, so you would need to upload it from the +distribution. + +Finally, if you have copies of any of the RomWBW custom applications on +your hard disk, you need to update them with the latest copies. The +following applications are found on your ROM disk. Use COPY to copy them +over any older versions of the app on your disk: + + - ASSIGN.COM + - FORMAT.COM + - OSLDR.COM + - SYSCOPY.COM + - TALK.COM + - FDU.COM (was FDTST.COM) + - XM.COM + - MODE.COM + - RTC.COM + - TIMER.COM + - INTTEST.COM + +For example: `B>COPY ASSIGN.COM C:` + +# Using Disks + +While the RAM/ROM disks provide a functional system, they are not useful +in the long term because you cannot save data across power cycles. They +are also constrained by limited space. + +The systems supported by RomWBW all have the ability to use persistent +disk media. I am referring to all kinds of disk devices including floppy +drives, hard disks, CF Cards, and SD Cards. Some systems have disk +interfaces built-in, while others will require add-in cards. You will +need to refer to the documentation for your system for your specific +options. + +In the RomWBW bootup messages, you will see hardware discovery messages. +If you have a disk drive interface, you should see messages listing +device types like FD:, IDE:, PPIDE:, SD:. Additionally, you will see +messages indicating the media that has been found on the interfaces. As +an example, here are the messages you might see if you have an IDE +interface in your system with a single CF Card inserted in the primary +side of the interface: + + IDE: IO=0x80 MODE=MK4 + IDE0: 8-BIT LBA BLOCKS=0x00773800 SIZE=3815MB + IDE1: NO MEDIA + +The messages you see will vary depending on your hardware and the media +you have installed. But, they will all have the same general format as +the example above. + +Once your your system has working disk devices, you can boot an +operating system and the operating system will have access to the media. +At the boot loader prompt, select either either CP/M 2.2 or Z-System to +boot from ROM. As the operating system starts up, you should see a list +of drive letters assigned to the disk media you have installed. Here is +an example of this: + + Configuring Drives... + + A:=MD1:0 + B:=MD0:0 + C:=IDE0:0 + D:=IDE0:1 + +You will probably see more drive letters than this. The drive letter +assignment process is described in more detail later in this document. +Be aware that RomWBW will only assign drive letters to disk interfaces +that actually have media in them. If you do not see drive letters +assigned as expected, refer to the prior system boot messages to ensure +media has been detected in the interface. Actually, there is one +exception to this rule: floppy drives will be assigned a drive letter +regardless of whether there is any media inserted at boot. + +Notice how each drive letter refers back to a specific disk hardware +interface like IDE0. This is important as it is telling you what each +drive letter refers to. Also notice that mass storage disks (like IDE) +will normally have multiple drive letters assigned. The extra drive +letters refer to additional “slices” on the disk. The concept of slices +is also explained later in this document. + +Once you are seeing drive letters referring to your disk media, you can +follow the instructions below to begin using the disk media with the +operating system. Your disk media **must** be initialized prior to being +used. There are two ways to initialize your media for use. + +You can initialize the media in-place using your RomWBW system. This +process is described below under Disk Initialization. In this scenario, +you will need to subsequently copy any files you want to use onto the +newly initialized disk (see Transferring Files). + +Alternatively, you can use your modern Windows, Linux, or Mac computer +to copy a disk image onto the disk media. RomWBW comes with a variety of +disk images that are ready to use and have a much more complete set of +files than you will find on the ROM disk. This process is covered below +under Disk Images. + +## Disk Initialization + +To use a disk device, you will need to initialize the directory of the +filesystem. On RomWBW, the initialization is done using the CLRDIR +application. For example if your C: drive has been assigned to a storage +device, you would use `CLRDIR C:` to initialize C: and prepare it hold +files. Note that CLRDIR will prompt you for confirmation and you must +respond with a **capital** ‘Y’ to confirm. Once `CLDIR` has completed, +you can copy files onto the drive, for example `COPY *.* C:`. Be very +careful to pay attention to your drive letter assignments prior to +running `CLRDIR` to avoid accidentally wiping out a filesystem that has +data on it. + +Running `CLRDIR` on a disk device is roughly equivalent to running +FORMAT on MS-DOS. Note that unlike MS-DOS you do **not** partition your +mass storage device. CP/M knows nothing about disk partitions. You may +notice a partitioning application on your ROM disk (FDISK80), but this +is strictly for an advanced technique of adding an MS-DOS FAT filesystem +to your media in addition to the CP/M area. Do not use FDISK80 unless +you are specifically attempting to add an MS-DOS FAT filesystem to your +media. + +If you are using a floppy drive, you will need to physically format your +floppy disk prior to use. This is only required for floppy disks, not +hard disk, CF Cards, or SD Cards, etc. To format a floppy drive, you can +use the interactive application `FDU`. FDU is not terribly user +friendly, but is generally documented in the file “FDU.txt” found in the +Doc directory of the distribution. It is not necessary to run `CLRDIR` +on a floppy disk after physically formatting it – the directory is +cleared as part of the formatting. + +Once you have initialized a disk device and copied your desired files +onto it, you may want to make the disk bootable. On CP/M filesystems, +you must perform one additional step to make a disk bootable. +Specifically, you need to place a copy of the operating system on the +system tracks of the disk. This is done using the `SYSCOPY` command. +Let’s say you have prepared drive C: by initializing it with `CLRDIR` +and copied some files onto it. You can now make C: bootable by running +the following command: + +`B>SYSCOPY C:=B:ZSYS.SYS` + +This command means: copy the Z-System operating system onto the system +tracks of drive C:. In this example, it is assumed that you have booted +from ROM, so B: is the ROM disk drive. Additionally, this example +assumes you want the Z-System operating system to be booted from C:. If +you want CP/M 2.2 instead, you would replace `B:ZSYS.SYS` with +`B:CPM.SYS`. Here is a full example of this process. + + B>SYSCOPY C:=B:ZSYS.SYS + + SYSCOPY v2.0 for RomWBW CP/M, 17-Feb-2020 (CP/M 2 Mode) + Copyright 2020, Wayne Warthen, GNU GPL v3 + + Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y + Reading image... Writing image... Done + +Once this process succeeds, you will be able to boot directly to the +disk from the boot loader prompt. See the instructions in Booting Disks +for details on this. + +## Disk Images + +As mentioned previously, RomWBW includes a variety of disk images that +contain a full set of applications for the operating systems supported. +It is generally easier to use these disk images instead of copying all +the files over using XModem. You use your modern computer (Windows, +Linux, MacOS) to place the disk image onto the disk media, then just +move the media over to your system. In this scenario you **do not** run +`CLRDIR` or `SYSCOPY` on the drive(s). The directory is prepared and the +disk is already bootable, if it is an operating system boot disk image. + +To copy the disk image files onto your actual media (floppy disk, CF +Card, SD Card, etc.), you need to use an image writing utility on your +modern computer. Your modern computer will need to have an appropriate +interface or slot that accepts the media. To actually copy the image, +you can use the `dd` command on Linux or MacOS. On Windows, in the +“Tools” directory of the distribution there are two tools you can use. +For floppy media, you can use RawWriteWin and for hard disk media, you +can use Win32DiskImager. In all cases, the image file should be written +to the media starting at the very first block or sector of the media. +This will **destroy** any other data on the media. + +The disk image files are found in the Binary directory of the +distribution. Floppy disk images are prefixed with “fd\_” and hard disk +images are prefixed with “hd\_”. The floppy images are specifically for +1.44M floppy media only. Each disk image has the complete set of normal +applications and tools distributed with the associated operating system +or application suite. + +The following table shows the disk image files available. Note that the +images in the “Hard” column are fine for use on CF Cards, SD Cards, as +well as real spinning hard disks. + +| Floppy | Hard | Description | +| ------------- | ------------- | ---------------------------- | +| fd\_cpm22.img | hd\_cpm22.img | DRI CP/M 2.2 boot disk | +| fd\_zsdos.img | hd\_zsdos.img | ZSDOS 1.1 boot disk | +| fd\_nzcom.img | hd\_nzcom.img | NZCOM boot disk | +| fd\_cpm3 | hd\_cpm3.img | DRI CP/M 3 boot disk | +| fd\_zpm3 | hd\_zpm3.img | ZPM3 boot disk | +| fd\_ws4 | hd\_ws4.img | WordStar v4 application disk | + +In addition to the disk images above, there is also a special hard disk +image called hd\_combo.img. This image contains all of the images above, +but in a single image with 6 slices (see below for information on disk +slices). At the boot loader prompt, you can choose a disk with the combo +image, then select the specific slice you want. This allows a single +disk to have all of the possible operating system options. + +This is the layout of the hd\_combo disk image: + +| Slice | Description | +| ------- | ---------------------------- | +| Slice 0 | DRI CP/M 2.2 boot disk | +| Slice 1 | ZSDOS 1.1 boot disk | +| Slice 2 | NZCOM boot disk | +| Slice 3 | DRI CP/M 3 boot disk | +| Slice 4 | ZPM3 boot disk | +| Slice 5 | WordStar v4 application disk | + +Note that unlike the ROM firmware, you do **not** need to choose a disk +image specific to your hardware. Because the RomWBW firmware provides a +hardware abstraction layer, all hard disk images will work on all +hardware variations. Yes, this means you can remove an SD Card from one +system and put it in a different system. The only constraint is that the +applications on the disk media must be up to date with the firmware on +the system being used. + +All of the disk images that indicate they are bootable (boot disk) will +boot from disk as is. You do not need to run `SYSCOPY` on them to make +them bootable. However, if you upgrade your ROM, you should use +`SYSCOPY` to update the system tracks. + +## Booting Disks + +When starting your system, following the hardware initialization, you +will see the Boot Loader prompt. In addition, to the ROM boot options, +you will see another line listing the Disk boot options. This line lists +the disk devices that you can choose to boot directly. + +You will notice that you do not have an option to boot a drive letter +here (like C:). This is because the operating system is not yet loaded. +When you ran `SYSCOPY` previously, remember that C: was assigned to +IDE0:0 which means device IDE0, slice 0. So, to boot the disk that you +just setup with `SYSCOPY`, you would choose option 1. You will then be +prompted for the slice on IDE0 that you want to boot. For now, just +press enter to choose slice 0. Once you are familiar with slices, you +can `SYSCOPY` and boot alternate slices. Here is what you would see when +booting to a disk device: + + MARK IV Boot Loader + + ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM + Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1 + + Boot Selection? 2 Slice(0-9)[0]? + + Booting Disk Unit 2, Slice 0... + + Reading disk information... + Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive + + Loading... + +Following this, you would see the normal operating system startup +messages. However, your operating system prompt will be `A>` and when +you look at the drive letter assignments, you should see that A: has +been assigned to the disk you selected to boot. + +If you receive the error message “Disk not bootable\!”, you have either +failed to properly run `SYSCOPY` on the target disk or you have selected +the wrong disk/slice. + +Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed +in the Disk boot line, they are not “bootable” disks because they have +no system tracks on them. Attempting to boot to one of them, will fail +with a “Disk not bootable\!” error message and return to the loader +prompt. + +# General Usage + +Each of the operating systems and ROM applications included with RomWBW +are sophisticated tools in their own right. It is not reasonable to +document their usage here. However, you will find complete manuals in +PDF format in the Doc directory of the distribution. The intention of +this section is to document the RomWBW specific enhancements to these +operating systems. + +## ROM Disk + +In addition to the ROM-based operating systems and applications, the ROM +also contains a ROM disk with a small CP/M filesystem. The contents of +the ROM disk have been chosen to provide a core set of tools and +applications that are helpful for either CP/M 2.2 or ZSDOS. Since ZSDOS +is CP/M 2.2 compatible, this works fairly well. However, you will find +some files on the ROM disk that will work with ZSDOS, but will not work +on CP/M 2.2. For example, `LDDS`, which loads the ZSDOS date/time +stamper will only run on ZSDOS. + +## Drive Letter Assignment + +In legacy CP/M-type operating systems, drive letters were generally +mapped to disk drives in a completely fixed way. For example, drive A: +would **always** refer to the first floppy drive. Since RomWBW supports +a wide variety of hardware configurations, it implements a much more +flexible drive letter assignment mechanism so that any drive letter can +be assigned to any disk device. + +At boot, you will notice that RomWBW automatically assigns drive letters +to the available disk devices. These assignments are displayed during +the startup of the selected operating system. Additionally, you can +review the current drive assignments at any time using the `ASSIGN` +command. CP/M 3 and ZPM3 do not automatically display the assignments at +startup, but you can use `ASSIGN` do display them. + +The drive letter assignments **do not** change during an OS session +unless you use the `ASSIGN` command yourself to do it. Additionally, the +assignments at boot will stay the same on each boot as long as you do +not make changes to your hardware configuration. Note that the +assignments **are** dependent on the media currently inserted in hard +disk drives. So, notice that if you insert or remove an SD Card or CF +Card, the drive assignments will change. Since drive letter assignments +can change, you must be careful when doing destructive things like using +`CLRDIR` to make sure the drive letter you use is referring to the +desired media. + +When performing a ROM boot of an operating system, note that A: will be +your RAM disk and B: will be your ROM disk. When performing a disk boot, +the disk you are booting from will be assigned to A: and the rest of the +drive letters will be offset to accommodate this. This is done because +most legacy operating systems expect that A: will be the boot drive. + +## Slices + +The vintage operating systems included with RomWBW were produced at a +time when mass storage devices were quite small. CP/M 2.2 could only +handle filesystems up to 8MB. In order to achieve compatibility across +all of the operating systems supported by RomWBW, the hard disk +filesystem format used is 8MB. This ensures any filesystem will be +accessible to any of the operating systems. + +Since storage devices today are quite large, RomWBW implements a +mechanism called slicing to allow up to 256 8MB filesystems on a single +large storage device. This allows up to 2GB of useable space on a single +media. You can think of slices as a way to refer to any of the first 256 +8MB chunks of space on a single media. + +Of course, the problem is that CP/M-like operating systems have only 16 +drive letters (A:-P:) available. Under the covers, RomWBW allows you to +use any drive letter to refer to any slice of any media. The `ASSIGN` +command is provided to allow you to view or change the drive letter +mappings at any time. At startup, the operating system will +automatically allocate a reasonable number of drive letters to the +available storage devices. The allocation will depend on the number of +large storage devices available at boot. For example, if you have only +one hard disk type media, you will see that 8 drive letters are assigned +to the first 8 slices of that media. If you have two large storage +devices, you will see that each device is allocated four drive letters. + +Referring to slices within a storage device is done by appending a :n +where n is the device relative slice number from 0-255. For example, if +you have an IDE device, it will show up as IDE0: in the boot messages +meaning the first IDE device. To refer to the fourth slice of IDE0, you +would type “IDE0:3”. So, if I wanted to use drive letter L: to refer to +the fourth slice of IDE0, I could use the command `ASSIGN L:=IDE0:3`. + +There are a couple of rules to be aware of when assigning drive letters. +First, you may only refer to a specific device/slice with one drive +letter. Said another way, you cannot have multiple drive letters +referring to a single device/slice at the same time. Second, there must +always be a drive assigned to A:. Any attempt to violate these rules +will be blocked by the `ASSIGN` command. + +Unlike MS-DOS partitions, slices are not allocated – there is no +partitioning of slices. Think of every hard disk type device as having a +pre-allocated set of 256 8MB slices at the start of the media. You can +refer to any of them simply by assigning a drive letter. RomWBW will not +check to see if there is anything else on the hard disk in the slice you +are referring to, nor will it verify that the hard disk media is large +enough to have a slice at the location you refer to. If you attempt to +write past the end of your media, you will get an I/O error displayed, +so you will know if you make a mistake. There is no tracking of your use +of slices – you will need to keep track of your use of slices yourself. + +Nothing automatically initializes a slice as a file system. You must do +that yourself using `CLRDIR`. Since `CLRDIR` works on drive letters, +make absolutely sure you know what media and slice are assigned to that +drive letter before using `CLRDIR`. + +While it is probably obvious, you cannot use slices on any media less +than 8MB in size. Specifically, you cannot slice RAM disks, ROM disks, +floppy disks, etc. + +# Inbuilt ROM Applications + +In addition to CP/M 2.2 and Z-System, there are several ROM applications +that can be launched directly from ROM. These applications are not +hosted by an operating system and so they are unable to save files to +disk devices. + +The following ROM applications are available at the boot loader prompt: + +| Application | | +| ----------- | ------------------------------------------------------ | +| Monitor | Z80 system debug monitor w/ Intel Hex loader | +| Forth | Brad Rodriguez’s ANSI compatible Forth language | +| Basic | Nascom 8K BASIC language | +| Tasty BASIC | Dimitri Theuling’s Tiny BASIC implementation | +| Play | A simple video game (requires ANSI terminal emulation) | + +In general, the command to exit these applications and restart the +system is `BYE`. The exceptions are the Monitor which uses `B` and Play +which uses `Q`. + +Space is available in the ROM image for the inclusion of other software. +Any inbuilt application can be set up to launch automatically at +startup. + +# RomWBW Custom Applications + +The operation of the RomWBW hosted operating systems is enhanced through +several custom applications. These applications are functional on all of +the OS variants included with RomWBW. + +The following custom applications are found on the ROM disk and are, +therefore, globally available. + +| Application | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| ASSIGN | Add, change, and delete drive letter assignments. Use ASSIGN /? for usage instructions. | +| SYSCOPY | Copy system image to a device to make it bootable. Use SYSCOPY with no parms for usage instructions. | +| FDU | Format and test floppy disks. Menu driven interface. | +| OSLDR | Load a new OS on the fly. For example, you can switch to Z-System when running CP/M. Use OSLDR with no parms for usage instructions. | +| FORMAT | Will someday be a command line tool to format floppy disks. Currently does nothing\! | +| MODE | Reconfigures serial ports dynamically. | +| XM | XModem file transfer program adapted to hardware. Automatically uses primary serial port on system. | +| FDISK80 | John Coffman’s Z80 hard disk partitioning tool. See documentation in Doc directory. | +| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). | +| FLASH | Will Sowerbutts’ in-situ ROM programming utility. | +| CLRDIR | Initialize the directory area of a CP/M disk (Max Scane). | + +Some custom applications do not fit on the ROM disk. They are found on +the disk image files or the individual files can be found in the +Binary\\Apps directory of the distribution. + +| Application | Description | +| ----------- | ----------------------------------------------------------- | +| TUNE | Play .PT2, .PT3, .MYM audio files. | +| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). | + +There is additional documentation on some of these applications at the +[RomWBW Applications +Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps). + +# Operating Systems + +One of the primary goals of RomWBW is to expose a set of generic +hardware functions that make it easy to adapt operating systems to any +hardware supported by RomWBW. As a result, there are now 5 operating +systems that have been adapted to run under RomWBW. The adaptations are +identical for all hardware supported by RomWBW because RomWBW hides all +hardware specifics from the operating system. + +Note that all of the operating systems included with RomWBW support the +same basic filesystem format. As a result, a formatted filesystem will +be accessible to any operating system. The only possible issue is that +if you turn on date/time stamping using the newer OSes, the older OSes +will not understand this. Files will not be corrupted, but the date/time +stamps may be lost. + +The following sections briefly describe the operating system options +currently available. + +## Digital Research CP/M 2.2 + +This is the most widely used variant of the Digital Research operating +system. It has the most basic feature set, but is essentially the +compatibility metric for all other CP/M-like operating systems including +all of those listed below. The Doc directory contains a manual for CP/M +usage (“CPM Manual.pdf”). If you are new to the CP/M world, I would +recommend using this CP/M variant to start with simply because it is the +most stable and you are less likely to encounter problems. + +## ZSDOS 1.1 + +ZSDOS is the most popular non-DRI CP/M “clone” which is generally +referred to as Z-System. Z-System is intended to be an enhanced version +of CP/M and should run all CP/M 2.2 applications. It is optimized for +the Z80 CPU (as opposed to 8080 for CP/M) and has some significant +improvements such as date/time stamping of files. For further +information on the RomWBW implementation of Z-System, see the wiki page +[Z-System +Notes](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:zsystem). +Additionally, the official documentation for Z-System is included in the +RomWBW distribution Doc directory (“ZSDOS Manual.pdf” and “ZCPR +Manual.pdf”). + +## NZCOM Automatic Z-System + +NZCOM is a much further refined version of Z-System (ZCPR 3.4). NZCOM +was sold as an enhancement for existing users of CP/M 2.2 or ZSDOS. For +this reason, (by design) NZCOM does not provide a way to boot directly +from disk. Rather, it is loaded after the system boots into a host OS. +On the RomWBW NZCOM disk images, the boot OS is ZSDOS 1.1. + +To use, NZCOM, you must run through a simple configuration process. This +is well documented in the NZCOM manual in the “NZCOM Users Manual.pdf” +file in the RomWBW Doc directory. Additionally, there are instructions +for automatically launching NZCOM when the disk is booted under the host +OS via an auto command submission process. + +## Digital Research CP/M 3 + +This is the Digital Research follow-up product to their very popular +CP/M 2.2 operating system. While highly compatible with CP/M 2.2, it +features many enhancements. It makes direct use of banked memory to +increase the user program space (TPA). It also has a new suite of +support tools and help system. + +Note that to make a CP/M 3 boot disk, you actually place CPMLDR.SYS on +the system tracks of the disk. You do not place CPM3.SYS on the system +tracks. + +## Simeon Cran’s ZPM3 + +ZPM3 is an interesting combination of the features of both CP/M 3 and +ZCPR 3. Essentially, it has the features of and compatibility with both. + +Like CP/M 3, to make ZPM3 boot disk, you put CPMLDR.SYS on the system +tracks of the disk. + +## FreeRTOS + +Note that Phillip Stevens has also ported FreeRTOS to run under RomWBW. +FreeRTOS is not provided in the RomWBW distribution. You can contact +Phillip for availability. + +# Transferring Files + +Transferring files between your modern computer and your RomWBW system +can be achieved in a variety of ways. The most common of these are +described below. All of these have a certain degree of complexity and I +encourage new users to use the available community forums to seek +assistance as needed. + +## Serial Port Transfers + +RomWBW provides an serial file transfer program called XModem that has +been adapted to run under RomWBW hardware. The program is called `XM` +and is on your ROM disk as well as all of the pre-built disk images. + +You can type `XM` by itself to get usage information. In general, you +will run `XM` with parameters to indicate you want to send or receive a +file on your RomWBW system. Then, you will use your modern computers +terminal program to complete the process. + +The `XM` application generally tries to detect the hardware you are +using and adapt to it. However, you must ensure that you have a reliable +serial connection. You must also ensure that the speed of the connection +is not too fast for XModem to service. Alternatively, you can ensure +that hardware flow control is working properly. + +There is an odd interaction between XModem and partner terminal programs +that can occur. Essentially, after launching `XM`, you must start the +protocol on your modern computer fairly quickly (usually in about 20 +seconds or so). So, if you do not pick a file on your modern computer +quickly enough, you will find that the transfer completes about 16K, +then hangs. The interaction that causes this is beyond the scope of this +document. + +## Disk Image Transfers + +It is possible to pass disk images between your RomWBW system and your +modern computer. This assumes you have an appropriate media slot on your +modern computer for the media you want to use (CF Card, SD Card, or +floppy drive). + +The general process to get files from your modern computer to a RomWBW +computer is: + +1. Use `cpmtools` on your modern computer to create a RomWBW CP/M + filesystem image. +2. Insert your RomWBW media (CF Card, SD Card, or floppy disk) in your + modern computer. +3. Use a disk imaging tool to copy the RomWBW filesystem image onto the + media. +4. Move the media back to the RomWBW computer. + +This process is a little complicated, but it has the benefit of allowing +you to get a lot of files over to your RomWBW system quickly and with +little chance of corruption. + +The process can be run in reverse to get files from your RomWBW computer +to a modern computer. + +The exact use of these tools is a bit too much for this document, but +the tools are all included in the RomWBW distribution along with usage +documents. + +Note that the build scripts for RomWBW create the default disk images +supplied with RomWBW. It is relatively easy to customize the contents of +the disk images that are part of RomWBW. This is described in more +detail in the Source\\Images directory of the distribution. + +## FAT Filesystem Transfers + +RomWBW provides a mechanism that allows it to read and write files on a +FAT formatted disk. This means that you can generally use your modern +computer to make an SD Card or CF Card with a standard FAT32 filesystem +on it, then place that media in your RomWBW computer and access the +files. + +When formatting the media on your modern computer, but sure to pick the +FAT filesystem. NTFS and other filesystems will not work. + +On your RomWBW computer you can use the `FAT` application to access the +FAT media. The `FAT` application allows you to read files, write files, +list a directory, and erase files on the FAT media. It can handle +subdirectories as well. It will only see 8.3 character filenames +however. Longer filenames will show up as a truncated version. + +The `FAT` application is not on your ROM disk because it is too large to +fit. You will find it on all of the pre-built disk images as well as in +the Binary\\Apps directory of the distribution. + +For advanced users, it is possible to create a hybrid disk that contains +CP/M slices at the beginning and a FAT filesystem after. Such a hybrid +disk can be used to boot an operating system and still have access to +FAT files on the FAT portion of the disk. David Reese has prepared a +document describing how to do this. It is called +“SC126\_How-To\_No\_2\_Preparing\_an\_SD\_Card\_for\_Use\_with\_SC126\_Rev\_1-5.pdf” +and can be found in the Doc\\Contrib directory of the distribution. + +# Startup Command Processing + +Each of the operating systems supported by RomWBW provide a mechanism to +run commands at boot. This is similar to the AUTOEXEC.BAT files from +MS-DOS. + +With the exception of ZPM3, all operating systems will look for a file +called `PROFILE.SUB` on the system drive at boot. If it is found, it +will be processed as a standard CP/M submit file. You can read about the +use of the SUBMIT facility in the CP/M manuals included in the RomWBW +distribution. Note that the boot disk must also have a copy of +`SUBMIT.EXE`. + +In the case of ZPM3, the file called `STARTZPM.COM` will be run at boot. +To customize this file, you use the ZCPR ALIAS facility. You will need +to refer to ZCPR documentation for more information on the ALIAS +facility. + +Note that the automatic startup processing generally requires booting to +a disk drive. Since the ROM disk is not writable, there is no simple way +to add/edit a `PROFILE.SUB` file there. If you want to customize your +ROM and add a `PROFILE.SUB` file to the ROM Disk, it will work, but is a +lot harder than using a boot disk. + +# ROM Customization + +The pre-built ROM images are configured for the basic capabilities of +each platform. Additionally, some of the typical add-on hardware for +each platform will be automatically detected and used. If you want to go +beyond this, RomWBW provides a very flexible configuration mechanism +based on configuration files. Creating a customized ROM requires running +a build script, but it is quite easy to do. + +Essentially, the creation of a custom ROM is accomplished by updating a +small configuration file, then running a script to compile the software +and generate the custom ROM and disk images. There are build scripts for +Windows, Linux, and MacOS to accommodate virtually all users. All +required build tools (compilers, assemblers, etc.) are included in the +distribution, so it is not necessary to setup a build environment on +your computer. + +The process for building a custom ROM is documented in the ReadMe.txt +file in the Source directory of the distribution. + +For those who are interested in more than basic system customization, +note that all source code is provided (including the operating systems). +Modification of the source code is considered an expert level task and +is left to the reader to pursue. + +Note that the ROM customization process does not apply to UNA. All UNA +customization is performed within the ROM setup script. + +# UNA Hardware BIOS + +John Coffman has produced a new generation of hardware BIOS called UNA. +The standard RomWBW distribution includes it’s own hardware BIOS. +However, RomWBW can alternatively be constructed with UNA as the +hardware BIOS portion of the ROM. If you wish to use the UNA variant of +RomWBW, then just program your ROM with the ROM image called +“UNA\_std.rom” in the Binary directory. This one image is suitable on +**all** of the platforms and hardware UNA supports. + +UNA is customized dynamically using a ROM based setup routine and the +setup is persisted in the system NVRAM of the RTC chip. This means that +the single UNA-based ROM image can be used on most of the RetroBrew +platforms and is easily customized. UNA also supports FAT file system +access that can be used for in-situ ROM programming and loading system +images. + +While John is likely to enhance UNA over time, there are currently a few +things that UNA does not support: + + - Floppy Drives + - Terminal Emulation + - Zeta 1, N8, RC2014, Easy Z80, and Dyno Systems + - Some older support boards + +The UNA version embedded in RomWBW is the latest production release of +UNA. RomWBW will be updated with John’s upcoming UNA release with +support for VGA3 as soon as it reaches production status. + +Please refer to the [UNA BIOS Firmware +Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:una:start) +for more information on UNA. + +# RomWBW Distribution + +All source code and distributions are maintained on GitHub. Code +contributions are very welcome. + +[RomWBW GitHub +Repository](https://github.com/wwarthen/RomWBW%7Chttps://github.com/wwarthen/RomWBW) + +## Distribution Directory Layout + +The RomWBW distribution is a compressed zip archive file organized in a +set of directories. Each of these directories has it’s own ReadMe.txt +file describing the contents in detail. In summary, these directories +are: + +| Application | Description | +| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| Binary | The final output files of the build process are placed here. Most importantly, are the ROM images with the file names ending in “.rom”. | +| Doc | Contains various detailed documentation including the operating systems, RomWBW architecture, etc. | +| Source | Contains the source code files used to build the software and ROM images. | +| Tools | Contains the MS Windows programs that are used by the build process or that may be useful in setting up your system. | + +# Acknowledgements + +While I have heavily modified much of the code, I want to acknowledge +that much of the work is derived from the work of others in the +RetroBrew Computers Community including Andrew Lynch, Dan Werner, Max +Scane, David Giles, John Coffman, and probably many others I am not +clearly aware of (let me know if I omitted someone\!). + +I especially want to credit Douglas Goodall for contributing code, time, +testing, and advice. He created an entire suite of application programs +to enhance the use of RomWBW. However, he is looking for someone to +continue the maintenance of these applications and they have become +unusable due to changes within RomWBW. As of RomWBW 2.6, these +applications are no longer provided. + + - David Giles contributed support for the CSIO support in the SD Card + driver. + - Ed Brindley contributed some of the code that supports the RC2014 + platform. + - Phil Summers contributed Forth and BASIC in ROM as well as a long + list of general code enhancements. + - Curt Mayer contributed the Linux / MacOS build process. + - UNA BIOS is a product of John Coffman. + +Contributions of all kinds to RomWBW are very welcome. + +# Getting Assistance + +The best way to get assistance with RomWBW or any aspect of the +RetroBrew Computers projects is via the community forums: + + - [RetroBrew Computers + Forum](https://www.retrobrewcomputers.org/forum/) + - [RC2014 Google + Group](https://groups.google.com/forum/#!forum/rc2014-z80) + - [retro-comp Google + Group](https://groups.google.com/forum/#!forum/retro-comp) + +Submission of issues and bugs are welcome at the [RomWBW GitHub +Repository](https://github.com/wwarthen/RomWBW). + +Also feel free to email Wayne Warthen at . diff --git a/ReadMe.txt b/ReadMe.txt index 3140b02f..e7bd9d64 100644 --- a/ReadMe.txt +++ b/ReadMe.txt @@ -1,319 +1,1059 @@ -*********************************************************************** -*** *** -*** R o m W B W *** -*** *** -*** Z80/Z180 System Software *** -*** *** -*********************************************************************** - -Wayne Warthen (wwarthen@gmail.com) -Version 2.9.2-pre.35, 2020-03-12 -https://www.retrobrewcomputers.org/ - -RomWBW is a ROM-based implementation of CP/M-80 2.2 and Z-System for -all RetroBrew Computers Z80/Z180 hardware platforms including SBC -1/2, Zeta 1/2, N8, Mark IV, RC2014, SC, Easy Z80, and Dyno. -Virtually all RetroBrew hardware is supported including floppy, hard -disk (IDE, CF Card, SD Card), Video, and keyboard. VT-100 terminal -emulation is built-in. - -The RomWBW ROM loads and runs the built-in operating systems directly -from the ROM and includes a selection of standard/useful applications -accessed via a ROM disk drive. A RAM disk drive is also provided -to allow temporary file storage. - -Pre-built ROM images are included for all platforms. Detailed system -customization is achieved by making simple modifications to a -configuration file and running a build script to generate a custom -ROM image. All source and build tools are included in the -distribution. Build scripts are provided for most modern computers -including Windows (32 or 64 bit compatible), Linux, or Mac. - -John Coffman's UNA hardware BIOS is fully supported by RomWBW. In the -case of UNA, a single ROM image (pre-built) is used for all supported -platforms and is customized using a ROM-based setup program. See the -UNA section below for more information. - -Quick Start ------------ - -A pre-built ROM image is included for each of the hardware platforms -supported. These ROM images are found in the Binary directory of the -distribution and have a file extension of ".rom". Simply program the -ROM of your system with the appropriate ROM image. Please see the -RomList.txt file in the Binary directory for details on selecting the -correct ROM image for your system and platform specific information. - -================================================================= -=== It is critical that you pick the right ROM image for your === -=== system. Please be sure to review the RomList.txt file to === -=== ensure you pick the right one. === -================================================================= - -Connect a serial terminal or computer with terminal emulation -software to the primary RS-232 port of your CPU board. A null-modem -connection is generally required. Set the line characteristics to -38400 baud, 8 data bits, 1 stop bit, no parity, and no flow control. -Select VT-100 terminal emulation. For RC2014 platforms (including -Stephen Cousins' kits) the baud rate is 115,200. - -Upon power-up, your terminal should display a sign-on banner within 2 -seconds followed by hardware inventory and discovery information. -When hardware initialization is completed, a boot loader prompt -allows you to choose a ROM-based operating system, system monitor, or +RomWBW + +Z80/Z180 System Software + +Version 2.9.2 +Friday 20 March 2020 + +Wayne Warthen wwarthen@gmail.com + +Download + +- RomWBW Distribution Package + +Related Pages + +- RomWBW Architecture Document +- RomWBW Applications +- RomWBW Errata + +Overview + +RomWBW provides a complete software system for a wide variety of +hobbyist Z80/Z180 CPU-based systems produced by these developer +communities: + +- RetroBrew Computers +- RC2014 +- retro-comp + +General features include: + +- Banked memory services for several banking designs +- Disk drivers for RAM, ROM, Floppy, IDE, CF, and SD +- Serial drivers including UART (16550-like), ASCI, ACIA, SIO +- Video drivers including TMS9918, SY6545, MOS8563, HD6445 +- Real time clock drivers including DS1322, BQ4845 +- Multiple OS support including CP/M 2.2, ZSDOS, CP/M 3, ZPM3 +- Built-in VT-100 terminal emulation support + +RomWBW is distributed as both source code and pre-built ROM and disk +images. Some of the provided software can be launched directly from the +ROM firmware itself: + +- System monitor +- Operating systems (CP/M 2.2, ZSDOS) +- ROM BASIC (Nascom BASIC and Tasty BASIC) +- ROM Forth + +A dynamic disk drive letter assignment mechanism allows mapping +operating system drive letters to any available disk media. +Additionally, mass media devices (IDE Disk, CF Card, SD Card) support +the use of multiple slices (up to 256 per device). Each slice contains a +complete CP/M filesystem and can be mapped independently to any drive +letter. This overcomes the inherent size limitations in legacy OSes +providing up to 2GB of accessible storage on a single device. + +The pre-built ROM firmware images are generally optimal for most users. +However, it is also very easy to modify and build custom ROM images that +fully tailor the firmware to your specific preferences. All tools +required to build custom ROM firmware are included – no need to install +assemblers, etc. Any modern computer running Windows, Linux, or MacOS +can be used. + +Multiple disk images are provided in the distribution. Most disk images +contain a complete, bootable, ready-to-run implementation of a specific +operating system. A “combo” disk image contains multiple slices, each +with a full operating system implementation. If you use this disk image, +you can easily pick whichever operating system you want to boot without +changing media. + +Installation + +The latest RomWBW distribution downloads are maintained on GitHub in the +RomWBW Repository. The fully-built distributions are found on the +releases page of the repository. On this page, you will probably see +both pre-releases as well as normal releases. Unless you have a specific +reason, I suggest you stick to the most recent normal release (not +pre-release). Expand the “Assets” drop-down for the release you want to +download, then select the asset named RomWBW-vX.X.X-Package.zip. The +Package asset includes all pre-built ROM and Disk images as well as full +source code. The other assets are Source Code only and do not have the +pre-built ROM or disk images. + +The pre-built ROM images will automatically detect and support a +reasonable range of devices including serial ports, video adapters, +on-board disk interfaces, and PropIO/ParPortProp boards without building +a custom ROM. The distribution is a .zip archive. After downloading it +to a working directory on your modern computer (Windows/Linux/Mac) use +any zip tool to extract the contents of the archive. + +In general, you will just program your system’s ROM chip with the +appropriate ROM image from the RomWBW distribution. Depending on how you +got your system, you may have already been provided with a +pre-programmed ROM chip. If so, use that initially. Otherwise, you will +need to use a ROM programmer to initially program your ROM chip. Please +refer to the documentation that came with your ROM programmer for more +information. Once you have a running RomWBW system, you can generally +update your ROM to a newer version in-situ with an included ROM Flashing +tool (Will Sowerbutts’ FLASH application) as described in the Upgrading +section below. + +Looking at the extracted distribution archive, You will see that the +distribution is broken up into a few sub-directories. The Binary +directory contains the pre-built ROM and disk images. The ROM image +files all end in “.rom”. Based on the table below, carefully pick the +appropriate ROM image: + + -------------------------------------------------------------------------- + Platform ROM Image File Baud Description + ---------- ---------------- -------- ------------------------------------- + SBC V1/V2 SBC_std.rom 38400 RetroBrew SBC v1 or v2 ECB Z80 + + Zeta V1 ZETA_std.rom 38400 RetroBrew Zeta V1 Z80, ParPortProp + (optional) + + Zeta V2 ZETA2_std.rom 38400 RetroBrew Zeta V2 Z80, ParPortProp + (optional) + + N8 N8_std.rom 38400 RetroBrew N8 Z180, date code >= 2312 + + Mark IV MK4_std.rom 38400 RetroBrew Mark IV ECB Z180 + + RC2014 Z80 RCZ80_std.rom 115200 RC2014 w/ Z80 CPU, requires 512K + RAM/ROM module + + RC2014 RCZ180_ext.rom 115200 RC2014 w/ Z180 CPU & 512K banked + Z180* RAM/ROM module + + RC2014 RCZ180_nat.rom 115200 RC2014 w/ Z180 CPU & 512K native + Z180* RAM/ROM module + + Easy Z80 EZZ80_std.rom 115200 Sergey Kiselev’s Easy Z80 + + SC126 SCZ180_126.rom 115200 Stephen Cousin’s SC126 Z180 + + SC130 SCZ180_130.rom 115200 Stephen Cousin’s SC130 Z180 + + SC131 SCZ180_131.rom 115200 Stephen Cousin’s SC131 Z180 + + Dyno DYNO_std.rom 38400 Steve Garcia’s Z180 Dyno Computer + -------------------------------------------------------------------------- + +*The RC2014 Z180 requires a separate RAM/ROM memory module. There are +two types of these modules and you must pick the ROM for your type of +memory module. The “ext” ROM supports Spencer’s official 512K RAM/ROM +banked memory module. The “nat” ROM supports any of the third-party Z180 +native memory modules. + +RomWBW will automatically attempt to detect and support typical add-on +components for each of the systems supported. More information on the +required system configuration and optional supported components for each +ROM is found in the file called “RomList.txt” in the Binary directory. +All pre-built ROM images are simple 512KB binary images. If your system +utilizes a larger ROM chip, you can just program the image into the +first 512KB of the ROM. + +Connect a serial terminal or computer with terminal emulation software +to the primary serial port of your CPU board. You may need to refer to +your hardware provider’s documentation for details. A null-modem +connection may be required. Set the baud rate as indicated in the table +above. Set the line characteristics to 8 data bits, 1 stop bit, no +parity, and no flow control. If possible, select VT-100 terminal +emulation. + +Upon power-up, your terminal should display a sign-on banner within 2 +seconds followed by hardware inventory and discovery information. When +hardware initialization is completed, a boot loader prompt allows you to +choose a ROM-based operating system, system monitor, application, or boot from a disk device. -CPU Speed ---------- +Initially, you should try the ROM boot options. By selecting either CP/M +2.2 or Z-System, the operating system will be loaded from ROM and you +will see the a B> disk prompt. In this scenario, A: will be an empty RAM +disk and B: will refer to your ROM disk containing some typical +applications. This provides a simple environment for learning to use +your system. Be aware that files saved to the RAM disk (A:) will +disappear at the next power on (RAM is generally not persistent). Also +note that attempts to save files to the ROM disk (B:) will fail because +ROM is not writable. + +Upgrading + +Upgrading to a newer release of RomWBW is essentially just a matter of +updating the ROM chip in your system. If you have spare ROM chips for +your system and a ROM programmer, it is always safest to keep your +existing, working ROM chip and program a new one with the new firmware. +If the new one fails to boot, you can easily return to the known working +ROM. + +Prior to attempting to reprogram your actual ROM chip, you may wish to +“try” the upgrade. With RomWBW, you can upload a new system image and +load it from the command line. For each ROM image file (.rom) in the +Binary directory, you will also find a corresponding application file +(.com). For example, for SBC_std.rom, there is also an SBC_std.com file. +You can upload the .com file to your system using XModem, then simply +run the .com file. You will see your system go through the normal +startup process just like it was started from ROM. However, your ROM has +not been updated and the next time you boot your system, it will revert +to the system image contained in ROM. You may find that you are unable +to load the .com file because it is too large to fit in available +application RAM (TPA). Unfortunately, in this case, you will not be able +to use the .com file mechanism to start your system. + +If you do not have easy access to a ROM programmer, it is usually +possible to reprogram your system ROM using the FLASH utility from Will +Sowerbutts. This application called FLASH.COM can be found on the ROM +drive of any running system. In this case, you would need to transfer +the new ROM image (.rom) over to your system using XModem (or one of the +other mechanisms described in the Transferring Files section below). The +ROM image will be too large to fit on your RAM drive, so you will need +to transfer it to a larger storage drive. Once the ROM image is on your +system, you can use the FLASH application to update your ROM. The +following is a typical example of transferring ROM image using XModem +and flashing the chip in-situ. + + E>xm r rom.img + + XMODEM v12.5 - 07/13/86 + RBC, 28-Aug-2019 [WBW], ASCI + + Receiving: E0:ROM.IMG + 7312k available for uploads + File open - ready to receive + To cancel: Ctrl-X, pause, Ctrl-X + + Thanks for the upload + + E>flash write rom.img + FLASH4 by Will Sowerbutts version 1.2.3 + + Using RomWBW (v2.6+) bank switching. + Flash memory chip ID is 0xBFB7: 39F040 + Flash memory has 128 sectors of 4096 bytes, total 512KB + Write complete: Reprogrammed 2/128 sectors. + Verify (128 sectors) complete: OK! + +Obviously, there is some risk to this approach since any issues with the +programming or ROM image could result in a non-functional system. + +To confirm your ROM chip has been successfully updated, restart your +system and boot an operating system from ROM. Do not boot from a disk +device yet. Review the boot messages to see if any issues have occurred. + +Once you are satisfied that the ROM is working well, you will need to +update the system images and RomWBW custom applications on your disk +drives. The system images and custom applications are matched to the +RomWBW ROM firmware in use. If you attempt to boot a disk or run +applications that have not been updated to match the current ROM +firmware, you are likely to have odd problems. + +The simplest way to update your disk media is to just use your modern +computer to overwrite the entire media with the latest disk image of +your choice. This process is described below in the Disk Images section. +If you wish to update existing disk media in your system, you need to +perform the following steps. + +If the disk is bootable, you need to update the system tracks of the +disk. This is done using a SYSCOPY command such as +SYSCOPY C:=B:ZSYS.SYS. For a ZSDOS boot disk, use ZSYS.SYS. For a CP/M +2.2 disk, use CPM.SYS. For a CP/M 3 or ZPM3 disk, use CPMLDR.SYS. +CPMLDR.SYS is not provided on the ROM disk, so you would need to upload +it from the distribution. + +Finally, if you have copies of any of the RomWBW custom applications on +your hard disk, you need to update them with the latest copies. The +following applications are found on your ROM disk. Use COPY to copy them +over any older versions of the app on your disk: + +- ASSIGN.COM +- FORMAT.COM +- OSLDR.COM +- SYSCOPY.COM +- TALK.COM +- FDU.COM (was FDTST.COM) +- XM.COM +- MODE.COM +- RTC.COM +- TIMER.COM +- INTTEST.COM + +For example: B>COPY ASSIGN.COM C: + +Using Disks + +While the RAM/ROM disks provide a functional system, they are not useful +in the long term because you cannot save data across power cycles. They +are also constrained by limited space. + +The systems supported by RomWBW all have the ability to use persistent +disk media. I am referring to all kinds of disk devices including floppy +drives, hard disks, CF Cards, and SD Cards. Some systems have disk +interfaces built-in, while others will require add-in cards. You will +need to refer to the documentation for your system for your specific +options. + +In the RomWBW bootup messages, you will see hardware discovery messages. +If you have a disk drive interface, you should see messages listing +device types like FD:, IDE:, PPIDE:, SD:. Additionally, you will see +messages indicating the media that has been found on the interfaces. As +an example, here are the messages you might see if you have an IDE +interface in your system with a single CF Card inserted in the primary +side of the interface: + + IDE: IO=0x80 MODE=MK4 + IDE0: 8-BIT LBA BLOCKS=0x00773800 SIZE=3815MB + IDE1: NO MEDIA + +The messages you see will vary depending on your hardware and the media +you have installed. But, they will all have the same general format as +the example above. + +Once your your system has working disk devices, you can boot an +operating system and the operating system will have access to the media. +At the boot loader prompt, select either either CP/M 2.2 or Z-System to +boot from ROM. As the operating system starts up, you should see a list +of drive letters assigned to the disk media you have installed. Here is +an example of this: + + Configuring Drives... + + A:=MD1:0 + B:=MD0:0 + C:=IDE0:0 + D:=IDE0:1 + +You will probably see more drive letters than this. The drive letter +assignment process is described in more detail later in this document. +Be aware that RomWBW will only assign drive letters to disk interfaces +that actually have media in them. If you do not see drive letters +assigned as expected, refer to the prior system boot messages to ensure +media has been detected in the interface. Actually, there is one +exception to this rule: floppy drives will be assigned a drive letter +regardless of whether there is any media inserted at boot. + +Notice how each drive letter refers back to a specific disk hardware +interface like IDE0. This is important as it is telling you what each +drive letter refers to. Also notice that mass storage disks (like IDE) +will normally have multiple drive letters assigned. The extra drive +letters refer to additional “slices” on the disk. The concept of slices +is also explained later in this document. + +Once you are seeing drive letters referring to your disk media, you can +follow the instructions below to begin using the disk media with the +operating system. Your disk media must be initialized prior to being +used. There are two ways to initialize your media for use. + +You can initialize the media in-place using your RomWBW system. This +process is described below under Disk Initialization. In this scenario, +you will need to subsequently copy any files you want to use onto the +newly initialized disk (see Transferring Files). + +Alternatively, you can use your modern Windows, Linux, or Mac computer +to copy a disk image onto the disk media. RomWBW comes with a variety of +disk images that are ready to use and have a much more complete set of +files than you will find on the ROM disk. This process is covered below +under Disk Images. + +Disk Initialization + +To use a disk device, you will need to initialize the directory of the +filesystem. On RomWBW, the initialization is done using the CLRDIR +application. For example if your C: drive has been assigned to a storage +device, you would use CLRDIR C: to initialize C: and prepare it hold +files. Note that CLRDIR will prompt you for confirmation and you must +respond with a capital ‘Y’ to confirm. Once CLDIR has completed, you can +copy files onto the drive, for example COPY *.* C:. Be very careful to +pay attention to your drive letter assignments prior to running CLRDIR +to avoid accidentally wiping out a filesystem that has data on it. + +Running CLRDIR on a disk device is roughly equivalent to running FORMAT +on MS-DOS. Note that unlike MS-DOS you do not partition your mass +storage device. CP/M knows nothing about disk partitions. You may notice +a partitioning application on your ROM disk (FDISK80), but this is +strictly for an advanced technique of adding an MS-DOS FAT filesystem to +your media in addition to the CP/M area. Do not use FDISK80 unless you +are specifically attempting to add an MS-DOS FAT filesystem to your +media. + +If you are using a floppy drive, you will need to physically format your +floppy disk prior to use. This is only required for floppy disks, not +hard disk, CF Cards, or SD Cards, etc. To format a floppy drive, you can +use the interactive application FDU. FDU is not terribly user friendly, +but is generally documented in the file “FDU.txt” found in the Doc +directory of the distribution. It is not necessary to run CLRDIR on a +floppy disk after physically formatting it – the directory is cleared as +part of the formatting. + +Once you have initialized a disk device and copied your desired files +onto it, you may want to make the disk bootable. On CP/M filesystems, +you must perform one additional step to make a disk bootable. +Specifically, you need to place a copy of the operating system on the +system tracks of the disk. This is done using the SYSCOPY command. Let’s +say you have prepared drive C: by initializing it with CLRDIR and copied +some files onto it. You can now make C: bootable by running the +following command: + +B>SYSCOPY C:=B:ZSYS.SYS + +This command means: copy the Z-System operating system onto the system +tracks of drive C:. In this example, it is assumed that you have booted +from ROM, so B: is the ROM disk drive. Additionally, this example +assumes you want the Z-System operating system to be booted from C:. If +you want CP/M 2.2 instead, you would replace B:ZSYS.SYS with B:CPM.SYS. +Here is a full example of this process. -RomWBW ROM images support virtually any CPU speed your system is -running. However, there are some hardware-oriented caveats to be -aware of. + B>SYSCOPY C:=B:ZSYS.SYS -The use of high density floppy disks requires a CPU speed of 8 MHz or -greater. + SYSCOPY v2.0 for RomWBW CP/M, 17-Feb-2020 (CP/M 2 Mode) + Copyright 2020, Wayne Warthen, GNU GPL v3 + + Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y + Reading image... Writing image... Done + +Once this process succeeds, you will be able to boot directly to the +disk from the boot loader prompt. See the instructions in Booting Disks +for details on this. + +Disk Images + +As mentioned previously, RomWBW includes a variety of disk images that +contain a full set of applications for the operating systems supported. +It is generally easier to use these disk images instead of copying all +the files over using XModem. You use your modern computer (Windows, +Linux, MacOS) to place the disk image onto the disk media, then just +move the media over to your system. In this scenario you do not run +CLRDIR or SYSCOPY on the drive(s). The directory is prepared and the +disk is already bootable, if it is an operating system boot disk image. + +To copy the disk image files onto your actual media (floppy disk, CF +Card, SD Card, etc.), you need to use an image writing utility on your +modern computer. Your modern computer will need to have an appropriate +interface or slot that accepts the media. To actually copy the image, +you can use the dd command on Linux or MacOS. On Windows, in the “Tools” +directory of the distribution there are two tools you can use. For +floppy media, you can use RawWriteWin and for hard disk media, you can +use Win32DiskImager. In all cases, the image file should be written to +the media starting at the very first block or sector of the media. This +will destroy any other data on the media. + +The disk image files are found in the Binary directory of the +distribution. Floppy disk images are prefixed with “fd_” and hard disk +images are prefixed with “hd_”. The floppy images are specifically for +1.44M floppy media only. Each disk image has the complete set of normal +applications and tools distributed with the associated operating system +or application suite. + +The following table shows the disk image files available. Note that the +images in the “Hard” column are fine for use on CF Cards, SD Cards, as +well as real spinning hard disks. + + Floppy Hard Description + -------------- -------------- ------------------------------ + fd_cpm22.img hd_cpm22.img DRI CP/M 2.2 boot disk + fd_zsdos.img hd_zsdos.img ZSDOS 1.1 boot disk + fd_nzcom.img hd_nzcom.img NZCOM boot disk + fd_cpm3 hd_cpm3.img DRI CP/M 3 boot disk + fd_zpm3 hd_zpm3.img ZPM3 boot disk + fd_ws4 hd_ws4.img WordStar v4 application disk + +In addition to the disk images above, there is also a special hard disk +image called hd_combo.img. This image contains all of the images above, +but in a single image with 6 slices (see below for information on disk +slices). At the boot loader prompt, you can choose a disk with the combo +image, then select the specific slice you want. This allows a single +disk to have all of the possible operating system options. + +This is the layout of the hd_combo disk image: + + Slice Description + --------- ------------------------------ + Slice 0 DRI CP/M 2.2 boot disk + Slice 1 ZSDOS 1.1 boot disk + Slice 2 NZCOM boot disk + Slice 3 DRI CP/M 3 boot disk + Slice 4 ZPM3 boot disk + Slice 5 WordStar v4 application disk + +Note that unlike the ROM firmware, you do not need to choose a disk +image specific to your hardware. Because the RomWBW firmware provides a +hardware abstraction layer, all hard disk images will work on all +hardware variations. Yes, this means you can remove an SD Card from one +system and put it in a different system. The only constraint is that the +applications on the disk media must be up to date with the firmware on +the system being used. + +All of the disk images that indicate they are bootable (boot disk) will +boot from disk as is. You do not need to run SYSCOPY on them to make +them bootable. However, if you upgrade your ROM, you should use SYSCOPY +to update the system tracks. + +Booting Disks + +When starting your system, following the hardware initialization, you +will see the Boot Loader prompt. In addition, to the ROM boot options, +you will see another line listing the Disk boot options. This line lists +the disk devices that you can choose to boot directly. + +You will notice that you do not have an option to boot a drive letter +here (like C:). This is because the operating system is not yet loaded. +When you ran SYSCOPY previously, remember that C: was assigned to IDE0:0 +which means device IDE0, slice 0. So, to boot the disk that you just +setup with SYSCOPY, you would choose option 1. You will then be prompted +for the slice on IDE0 that you want to boot. For now, just press enter +to choose slice 0. Once you are familiar with slices, you can SYSCOPY +and boot alternate slices. Here is what you would see when booting to a +disk device: + + MARK IV Boot Loader + + ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM + Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1 + + Boot Selection? 2 Slice(0-9)[0]? + + Booting Disk Unit 2, Slice 0... + + Reading disk information... + Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive + + Loading... + +Following this, you would see the normal operating system startup +messages. However, your operating system prompt will be A> and when you +look at the drive letter assignments, you should see that A: has been +assigned to the disk you selected to boot. + +If you receive the error message “Disk not bootable!”, you have either +failed to properly run SYSCOPY on the target disk or you have selected +the wrong disk/slice. + +Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed +in the Disk boot line, they are not “bootable” disks because they have +no system tracks on them. Attempting to boot to one of them, will fail +with a “Disk not bootable!” error message and return to the loader +prompt. + +General Usage + +Each of the operating systems and ROM applications included with RomWBW +are sophisticated tools in their own right. It is not reasonable to +document their usage here. However, you will find complete manuals in +PDF format in the Doc directory of the distribution. The intention of +this section is to document the RomWBW specific enhancements to these +operating systems. + +ROM Disk + +In addition to the ROM-based operating systems and applications, the ROM +also contains a ROM disk with a small CP/M filesystem. The contents of +the ROM disk have been chosen to provide a core set of tools and +applications that are helpful for either CP/M 2.2 or ZSDOS. Since ZSDOS +is CP/M 2.2 compatible, this works fairly well. However, you will find +some files on the ROM disk that will work with ZSDOS, but will not work +on CP/M 2.2. For example, LDDS, which loads the ZSDOS date/time stamper +will only run on ZSDOS. + +Drive Letter Assignment + +In legacy CP/M-type operating systems, drive letters were generally +mapped to disk drives in a completely fixed way. For example, drive A: +would always refer to the first floppy drive. Since RomWBW supports a +wide variety of hardware configurations, it implements a much more +flexible drive letter assignment mechanism so that any drive letter can +be assigned to any disk device. + +At boot, you will notice that RomWBW automatically assigns drive letters +to the available disk devices. These assignments are displayed during +the startup of the selected operating system. Additionally, you can +review the current drive assignments at any time using the ASSIGN +command. CP/M 3 and ZPM3 do not automatically display the assignments at +startup, but you can use ASSIGN do display them. + +The drive letter assignments do not change during an OS session unless +you use the ASSIGN command yourself to do it. Additionally, the +assignments at boot will stay the same on each boot as long as you do +not make changes to your hardware configuration. Note that the +assignments are dependent on the media currently inserted in hard disk +drives. So, notice that if you insert or remove an SD Card or CF Card, +the drive assignments will change. Since drive letter assignments can +change, you must be careful when doing destructive things like using +CLRDIR to make sure the drive letter you use is referring to the desired +media. + +When performing a ROM boot of an operating system, note that A: will be +your RAM disk and B: will be your ROM disk. When performing a disk boot, +the disk you are booting from will be assigned to A: and the rest of the +drive letters will be offset to accommodate this. This is done because +most legacy operating systems expect that A: will be the boot drive. + +Slices + +The vintage operating systems included with RomWBW were produced at a +time when mass storage devices were quite small. CP/M 2.2 could only +handle filesystems up to 8MB. In order to achieve compatibility across +all of the operating systems supported by RomWBW, the hard disk +filesystem format used is 8MB. This ensures any filesystem will be +accessible to any of the operating systems. + +Since storage devices today are quite large, RomWBW implements a +mechanism called slicing to allow up to 256 8MB filesystems on a single +large storage device. This allows up to 2GB of useable space on a single +media. You can think of slices as a way to refer to any of the first 256 +8MB chunks of space on a single media. + +Of course, the problem is that CP/M-like operating systems have only 16 +drive letters (A:-P:) available. Under the covers, RomWBW allows you to +use any drive letter to refer to any slice of any media. The ASSIGN +command is provided to allow you to view or change the drive letter +mappings at any time. At startup, the operating system will +automatically allocate a reasonable number of drive letters to the +available storage devices. The allocation will depend on the number of +large storage devices available at boot. For example, if you have only +one hard disk type media, you will see that 8 drive letters are assigned +to the first 8 slices of that media. If you have two large storage +devices, you will see that each device is allocated four drive letters. + +Referring to slices within a storage device is done by appending a :n +where n is the device relative slice number from 0-255. For example, if +you have an IDE device, it will show up as IDE0: in the boot messages +meaning the first IDE device. To refer to the fourth slice of IDE0, you +would type “IDE0:3”. So, if I wanted to use drive letter L: to refer to +the fourth slice of IDE0, I could use the command ASSIGN L:=IDE0:3. + +There are a couple of rules to be aware of when assigning drive letters. +First, you may only refer to a specific device/slice with one drive +letter. Said another way, you cannot have multiple drive letters +referring to a single device/slice at the same time. Second, there must +always be a drive assigned to A:. Any attempt to violate these rules +will be blocked by the ASSIGN command. + +Unlike MS-DOS partitions, slices are not allocated – there is no +partitioning of slices. Think of every hard disk type device as having a +pre-allocated set of 256 8MB slices at the start of the media. You can +refer to any of them simply by assigning a drive letter. RomWBW will not +check to see if there is anything else on the hard disk in the slice you +are referring to, nor will it verify that the hard disk media is large +enough to have a slice at the location you refer to. If you attempt to +write past the end of your media, you will get an I/O error displayed, +so you will know if you make a mistake. There is no tracking of your use +of slices – you will need to keep track of your use of slices yourself. + +Nothing automatically initializes a slice as a file system. You must do +that yourself using CLRDIR. Since CLRDIR works on drive letters, make +absolutely sure you know what media and slice are assigned to that drive +letter before using CLRDIR. + +While it is probably obvious, you cannot use slices on any media less +than 8MB in size. Specifically, you cannot slice RAM disks, ROM disks, +floppy disks, etc. -Upgrading from Previous Versions --------------------------------- +Inbuilt ROM Applications -Program a new ROM chip from an image in the new distribution. Install -the new ROM chip and boot your system. At the boot loader "Boot:" -prompt, select either CP/M or Z-System to load the OS from ROM. +In addition to CP/M 2.2 and Z-System, there are several ROM applications +that can be launched directly from ROM. These applications are not +hosted by an operating system and so they are unable to save files to +disk devices. -If you have spare rom chips for your system, it is always safest to -keep your existing, working ROM chip and program a new one so that you -can return to the old one if the new one does not work properly. +The following ROM applications are available at the boot loader prompt: -If you use a customized ROM image, it is recommended that you first -try the pre-built ROM image first and then move on to generating a -custom image. + Application + ------------- -------------------------------------------------------- + Monitor Z80 system debug monitor w/ Intel Hex loader + Forth Brad Rodriguez’s ANSI compatible Forth language + Basic Nascom 8K BASIC language + Tasty BASIC Dimitri Theuling’s Tiny BASIC implementation + Play A simple video game (requires ANSI terminal emulation) -It is entirely possible to reprogram your system ROM using the FLASH -utility from Will Sowerbutts on your ROM drive (B:). In this case, -you would need to transfer the new ROM image to your system using -X-Modem. Obviously, there is some risk to this approach since any -issues with the programming or ROM image could result in a -non-functional system. +In general, the command to exit these applications and restart the +system is BYE. The exceptions are the Monitor which uses B and Play +which uses Q. -If your system has any bootable drives, then update the OS image on -each drive using SYSCOPY. For example, if C: is a bootable drive -with the Z-System OS, you would update the OS image on this drive -with the command: +Space is available in the ROM image for the inclusion of other software. +Any inbuilt application can be set up to launch automatically at +startup. - B>SYSCOPY C:=B:ZSYS.SYS +RomWBW Custom Applications -If you have copies of any of the system utilities on drives other -than the ROM disk drive, you need to copy the latest version of the -programs from the ROM drive (B:) to any drives containing these -programs. For example, if you have a copy of the ASSIGN.COM program -on C:, you would update it from the new ROM using the COPY command: - - B>COPY B:ASSIGN.COM C: - -The following programs are maintained with the ROM images and all -copies of these programs should be updated when upgrading to a new -ROM version: - - - ASSIGN.COM - - FORMAT.COM - - OSLDR.COM - - SYSCOPY.COM - - TALK.COM - - FDU.COM - - XM.COM - - RTC.COM - - FAT.COM - - TIMER.COM - - INTTEST.COM +The operation of the RomWBW hosted operating systems is enhanced through +several custom applications. These applications are functional on all of +the OS variants included with RomWBW. -UNA Hardware BIOS ------------------ +The following custom applications are found on the ROM disk and are, +therefore, globally available. -John Coffman has produced a new generation of hardware BIOS called -UNA. In addition to the classic ROM images, RomWBW comes with a -UNA-based image that combines the UNA BIOS with the RomWBW OS -implementations and applications. + -------------------------------------------------------------------------- + Application Description + ------------- ------------------------------------------------------------ + ASSIGN Add, change, and delete drive letter assignments. Use ASSIGN + /? for usage instructions. -UNA is customized dynamically using a ROM based setup routine and the -setup is persisted in the system NVRAM of the RTC chip. This means -that a single UNA-based ROM image can be used on most of the -RetroBrew platforms and is easily customized. UNA also supports FAT -file system access that can be used for in-situ ROM programming and -loading system images. - -While John is likely to enhance UNA over time, there are currently a -few things that UNA does not support: - - - Floppy Drives - - Video/Keyboard/Terminal Emulation - - Zeta 1, N8, RC2014, SC, and Easy Z80 systems - - Some older support boards - -If you wish to try the UNA variant of RomWBW, then just program your -ROM with the ROM image called "UNA_std.rom" in the Binary directory. -This one image is suitable on all of the platforms and hardware UNA -supports. - -Please refer to the RetroBrew Computers Wiki for more information on -UNA. - -CP/M vs. Z-System ------------------ - -There are two OS variants included in this distribution and you may -choose which one you prefer to use. Both variants are now included -in the pre-built ROM images. You will be given the choice to boot -either CP/M or Z-System at startup. - -The traditional Digital Research (DRI) CP/M OS is the first choice. -The Doc directory contains a manual for CP/M usage ("CPM -Manual.pdf"). If you are new to the RetroBrew Computer systems, I -would currently recommend using the CP/M variant to start with simply -because it has gone through more testing and you are less likely to -encounter problems. - -The other choice is to use the most popular non-DRI CP/M "clone" -which is generally referred to as Z-System. It is intended to be -functionally equivalent to CP/M and should run all CP/M 2.2 code. It -is optimized for the Z80 CPU (as opposed to 8080 for CP/M) and has -some potentially useful improvements. Please refer to "ZSDOS -Manual.pdf" and "ZCPR Manual.pdf" in the Doc directory for more -information on Z-System usage. - -CP/M 3 ------- - -CP/M 3 exists in an experimental state. CP/M 3 must be started -from a disk drive. In the distribution archive, in the Binary -directory, you will find a cpm_hd.img file that can be copied -over to a CF or SD Card. Start your system with this card -installed and boot to CP/M 2.2 or ZSystem as usual. Switch to -the drive containing the CP/M 3 image and use the CPMLDR command -to load CP/M. It will ask you for the disk unit number containing -the CP/M 3 system files which are on the disk image you created. - -ZPM3 ----- - -Like CP/M 3, ZPM3 exists in an experimental state and is started -just like CP/M 3 above. Just use the zpm_hd.img file to create -your CF or SD Card. There is an issue with the ZPMLDR app used -to start ZPM. Instead, just use CPMLDR which works exactly the -same way. - -Note that ZPM3 seems to be completely constrainted to use drive -A: as the boot drive. So, the RomWBW adaptation of ZPM3 will -"swap" the initial drive A: (typically RAM drive) with the -ZPM3 boot drive at startup. + SYSCOPY Copy system image to a device to make it bootable. Use + SYSCOPY with no parms for usage instructions. + + FDU Format and test floppy disks. Menu driven interface. + + OSLDR Load a new OS on the fly. For example, you can switch to + Z-System when running CP/M. Use OSLDR with no parms for + usage instructions. + + FORMAT Will someday be a command line tool to format floppy disks. + Currently does nothing! + + MODE Reconfigures serial ports dynamically. + + XM XModem file transfer program adapted to hardware. + Automatically uses primary serial port on system. + + FDISK80 John Coffman’s Z80 hard disk partitioning tool. See + documentation in Doc directory. + + FAT Access MS-DOS FAT filesystems from RomWBW (based on FatFs). + + FLASH Will Sowerbutts’ in-situ ROM programming utility. + + CLRDIR Initialize the directory area of a CP/M disk (Max Scane). + -------------------------------------------------------------------------- + +Some custom applications do not fit on the ROM disk. They are found on +the disk image files or the individual files can be found in the +Binary\Apps directory of the distribution. + + Application Description + ------------- ------------------------------------------------------------- + TUNE Play .PT2, .PT3, .MYM audio files. + FAT Access MS-DOS FAT filesystems from RomWBW (based on FatFs). + +There is additional documentation on some of these applications at the +RomWBW Applications Page. + +Operating Systems + +One of the primary goals of RomWBW is to expose a set of generic +hardware functions that make it easy to adapt operating systems to any +hardware supported by RomWBW. As a result, there are now 5 operating +systems that have been adapted to run under RomWBW. The adaptations are +identical for all hardware supported by RomWBW because RomWBW hides all +hardware specifics from the operating system. + +Note that all of the operating systems included with RomWBW support the +same basic filesystem format. As a result, a formatted filesystem will +be accessible to any operating system. The only possible issue is that +if you turn on date/time stamping using the newer OSes, the older OSes +will not understand this. Files will not be corrupted, but the date/time +stamps may be lost. + +The following sections briefly describe the operating system options +currently available. + +Digital Research CP/M 2.2 + +This is the most widely used variant of the Digital Research operating +system. It has the most basic feature set, but is essentially the +compatibility metric for all other CP/M-like operating systems including +all of those listed below. The Doc directory contains a manual for CP/M +usage (“CPM Manual.pdf”). If you are new to the CP/M world, I would +recommend using this CP/M variant to start with simply because it is the +most stable and you are less likely to encounter problems. + +ZSDOS 1.1 + +ZSDOS is the most popular non-DRI CP/M “clone” which is generally +referred to as Z-System. Z-System is intended to be an enhanced version +of CP/M and should run all CP/M 2.2 applications. It is optimized for +the Z80 CPU (as opposed to 8080 for CP/M) and has some significant +improvements such as date/time stamping of files. For further +information on the RomWBW implementation of Z-System, see the wiki page +Z-System Notes. Additionally, the official documentation for Z-System is +included in the RomWBW distribution Doc directory (“ZSDOS Manual.pdf” +and “ZCPR Manual.pdf”). + +NZCOM Automatic Z-System + +NZCOM is a much further refined version of Z-System (ZCPR 3.4). NZCOM +was sold as an enhancement for existing users of CP/M 2.2 or ZSDOS. For +this reason, (by design) NZCOM does not provide a way to boot directly +from disk. Rather, it is loaded after the system boots into a host OS. +On the RomWBW NZCOM disk images, the boot OS is ZSDOS 1.1. + +To use, NZCOM, you must run through a simple configuration process. This +is well documented in the NZCOM manual in the “NZCOM Users Manual.pdf” +file in the RomWBW Doc directory. Additionally, there are instructions +for automatically launching NZCOM when the disk is booted under the host +OS via an auto command submission process. + +Digital Research CP/M 3 + +This is the Digital Research follow-up product to their very popular +CP/M 2.2 operating system. While highly compatible with CP/M 2.2, it +features many enhancements. It makes direct use of banked memory to +increase the user program space (TPA). It also has a new suite of +support tools and help system. + +Note that to make a CP/M 3 boot disk, you actually place CPMLDR.SYS on +the system tracks of the disk. You do not place CPM3.SYS on the system +tracks. + +Simeon Cran’s ZPM3 + +ZPM3 is an interesting combination of the features of both CP/M 3 and +ZCPR 3. Essentially, it has the features of and compatibility with both. + +Like CP/M 3, to make ZPM3 boot disk, you put CPMLDR.SYS on the system +tracks of the disk. + +FreeRTOS + +Note that Phillip Stevens has also ported FreeRTOS to run under RomWBW. +FreeRTOS is not provided in the RomWBW distribution. You can contact +Phillip for availability. + +Transferring Files + +Transferring files between your modern computer and your RomWBW system +can be achieved in a variety of ways. The most common of these are +described below. All of these have a certain degree of complexity and I +encourage new users to use the available community forums to seek +assistance as needed. + +Serial Port Transfers + +RomWBW provides an serial file transfer program called XModem that has +been adapted to run under RomWBW hardware. The program is called XM and +is on your ROM disk as well as all of the pre-built disk images. + +You can type XM by itself to get usage information. In general, you will +run XM with parameters to indicate you want to send or receive a file on +your RomWBW system. Then, you will use your modern computers terminal +program to complete the process. + +The XM application generally tries to detect the hardware you are using +and adapt to it. However, you must ensure that you have a reliable +serial connection. You must also ensure that the speed of the connection +is not too fast for XModem to service. Alternatively, you can ensure +that hardware flow control is working properly. + +There is an odd interaction between XModem and partner terminal programs +that can occur. Essentially, after launching XM, you must start the +protocol on your modern computer fairly quickly (usually in about 20 +seconds or so). So, if you do not pick a file on your modern computer +quickly enough, you will find that the transfer completes about 16K, +then hangs. The interaction that causes this is beyond the scope of this +document. + +Disk Image Transfers + +It is possible to pass disk images between your RomWBW system and your +modern computer. This assumes you have an appropriate media slot on your +modern computer for the media you want to use (CF Card, SD Card, or +floppy drive). + +The general process to get files from your modern computer to a RomWBW +computer is: + +1. Use cpmtools on your modern computer to create a RomWBW CP/M + filesystem image. +2. Insert your RomWBW media (CF Card, SD Card, or floppy disk) in your + modern computer. +3. Use a disk imaging tool to copy the RomWBW filesystem image onto the + media. +4. Move the media back to the RomWBW computer. + +This process is a little complicated, but it has the benefit of allowing +you to get a lot of files over to your RomWBW system quickly and with +little chance of corruption. + +The process can be run in reverse to get files from your RomWBW computer +to a modern computer. + +The exact use of these tools is a bit too much for this document, but +the tools are all included in the RomWBW distribution along with usage +documents. + +Note that the build scripts for RomWBW create the default disk images +supplied with RomWBW. It is relatively easy to customize the contents of +the disk images that are part of RomWBW. This is described in more +detail in the Source\Images directory of the distribution. + +FAT Filesystem Transfers + +RomWBW provides a mechanism that allows it to read and write files on a +FAT formatted disk. This means that you can generally use your modern +computer to make an SD Card or CF Card with a standard FAT32 filesystem +on it, then place that media in your RomWBW computer and access the +files. + +When formatting the media on your modern computer, but sure to pick the +FAT filesystem. NTFS and other filesystems will not work. + +On your RomWBW computer you can use the FAT application to access the +FAT media. The FAT application allows you to read files, write files, +list a directory, and erase files on the FAT media. It can handle +subdirectories as well. It will only see 8.3 character filenames +however. Longer filenames will show up as a truncated version. + +The FAT application is not on your ROM disk because it is too large to +fit. You will find it on all of the pre-built disk images as well as in +the Binary\Apps directory of the distribution. + +For advanced users, it is possible to create a hybrid disk that contains +CP/M slices at the beginning and a FAT filesystem after. Such a hybrid +disk can be used to boot an operating system and still have access to +FAT files on the FAT portion of the disk. David Reese has prepared a +document describing how to do this. It is called +“SC126_How-To_No_2_Preparing_an_SD_Card_for_Use_with_SC126_Rev_1-5.pdf” +and can be found in the Doc\Contrib directory of the distribution. + +Startup Command Processing + +Each of the operating systems supported by RomWBW provide a mechanism to +run commands at boot. This is similar to the AUTOEXEC.BAT files from +MS-DOS. + +With the exception of ZPM3, all operating systems will look for a file +called PROFILE.SUB on the system drive at boot. If it is found, it will +be processed as a standard CP/M submit file. You can read about the use +of the SUBMIT facility in the CP/M manuals included in the RomWBW +distribution. Note that the boot disk must also have a copy of +SUBMIT.EXE. + +In the case of ZPM3, the file called STARTZPM.COM will be run at boot. +To customize this file, you use the ZCPR ALIAS facility. You will need +to refer to ZCPR documentation for more information on the ALIAS +facility. + +Note that the automatic startup processing generally requires booting to +a disk drive. Since the ROM disk is not writable, there is no simple way +to add/edit a PROFILE.SUB file there. If you want to customize your ROM +and add a PROFILE.SUB file to the ROM Disk, it will work, but is a lot +harder than using a boot disk. ROM Customization ------------------ The pre-built ROM images are configured for the basic capabilities of -each platform. If you add board(s) to your system, you will need to -customize your ROM image to include support for the added board(s). - -Essentially, the creation of a custom ROM is accomplished by updating -a small configuration file, then running a script to compile the -software and generate the custom ROM image. +each platform. Additionally, some of the typical add-on hardware for +each platform will be automatically detected and used. If you want to go +beyond this, RomWBW provides a very flexible configuration mechanism +based on configuration files. Creating a customized ROM requires running +a build script, but it is quite easy to do. + +Essentially, the creation of a custom ROM is accomplished by updating a +small configuration file, then running a script to compile the software +and generate the custom ROM and disk images. There are build scripts for +Windows, Linux, and MacOS to accommodate virtually all users. All +required build tools (compilers, assemblers, etc.) are included in the +distribution, so it is not necessary to setup a build environment on +your computer. + +The process for building a custom ROM is documented in the ReadMe.txt +file in the Source directory of the distribution. + +For those who are interested in more than basic system customization, +note that all source code is provided (including the operating systems). +Modification of the source code is considered an expert level task and +is left to the reader to pursue. + +Note that the ROM customization process does not apply to UNA. All UNA +customization is performed within the ROM setup script. -Build scripts are provided for Windows (32 or 64 bit versions), Linux, -and Mac. All tools (compilers, assemblers, etc.) are included in the -distribution, so it is not necessary to setup a build environment -on your computer. +UNA Hardware BIOS -For those who are interested in more than basic system customization, -note that all source code is included (including the operating -systems). +John Coffman has produced a new generation of hardware BIOS called UNA. +The standard RomWBW distribution includes it’s own hardware BIOS. +However, RomWBW can alternatively be constructed with UNA as the +hardware BIOS portion of the ROM. If you wish to use the UNA variant of +RomWBW, then just program your ROM with the ROM image called +“UNA_std.rom” in the Binary directory. This one image is suitable on all +of the platforms and hardware UNA supports. -Note that the ROM customization process does not apply to UNA. All -UNA customization is performed within the ROM setup script. +UNA is customized dynamically using a ROM based setup routine and the +setup is persisted in the system NVRAM of the RTC chip. This means that +the single UNA-based ROM image can be used on most of the RetroBrew +platforms and is easily customized. UNA also supports FAT file system +access that can be used for in-situ ROM programming and loading system +images. -Complete documentation of the customization process is found in the -ReadMe.txt file in the Source directory. +While John is likely to enhance UNA over time, there are currently a few +things that UNA does not support: -Inbuilt ROM Applications ------------------------- +- Floppy Drives +- Terminal Emulation +- Zeta 1, N8, RC2014, Easy Z80, and Dyno Systems +- Some older support boards -Additonal software other than the CP/M and Z-System application can -be included in the ROM image for execution from the ROM loader. +The UNA version embedded in RomWBW is the latest production release of +UNA. RomWBW will be updated with John’s upcoming UNA release with +support for VGA3 as soon as it reaches production status. -Current inclusions are: +Please refer to the UNA BIOS Firmware Page for more information on UNA. - Monitor - Z80 debug monitor with hexload capability. - Forth - Brad Rodriguez's ANS compatible Forth. - Basic - Nascom 8K BASIC. - Tasty BASIC - Dimitri Theulings Tiny BASIC implementation. - - Note: To exit type B in Monitor and BYE in other applications. - -Space is available in the ROM image for the inclusion of other -software. Any inbuild application can be set up to launch -automatically at startup. +RomWBW Distribution -Source Code Respository ------------------------ +All source code and distributions are maintained on GitHub. Code +contributions are very welcome. -All source code and distributions are maintained on GitHub at -"https://github.com/wwarthen/RomWBW". Code contributions are very -welcome. +RomWBW GitHub Repository Distribution Directory Layout ------------------------------ -The RomWBW distribution is a compressed zip archive file organized in -a set of directories. Each of these directories has it's own -ReadMe.txt file describing the contents in detail. In summary, these -directories are: +The RomWBW distribution is a compressed zip archive file organized in a +set of directories. Each of these directories has it’s own ReadMe.txt +file describing the contents in detail. In summary, these directories +are: + + -------------------------------------------------------------------------- + Application Description + ------------- ------------------------------------------------------------ + Binary The final output files of the build process are placed here. + Most importantly, are the ROM images with the file names + ending in “.rom”. - Binary: The final output files of the build process are placed - here. Most importantly, are the ROM images with the - file names ending in ".rom". + Doc Contains various detailed documentation including the + operating systems, RomWBW architecture, etc. - Doc: Contains various detailed documentation including the - operating systems, RomWBW architecture, etc. + Source Contains the source code files used to build the software + and ROM images. - Source: Contains the source code files used to build the software - and ROM images. - - Tools: Contains the MS Windows programs that are used by the - build process or that may be useful in setting up your - system. + Tools Contains the MS Windows programs that are used by the build + process or that may be useful in setting up your system. + -------------------------------------------------------------------------- Acknowledgements ----------------- While I have heavily modified much of the code, I want to acknowledge -that much of the work is derived or copied from the work of others in -the RetroBrew Computers project including Andrew Lynch, Dan Werner, -Max Scane, David Giles, John Coffman, and probably many others I am -not clearly aware of (let me know if I omitted someone!). - -I especially want to credit Douglas Goodall for contributing code, -time, testing, and advice. He created an entire suite of application -programs to enhance the use of RomWBW. However, he is looking for -someone to continue the maintenance of these applications and they -have become unusable due to changes within RomWBW. As of RomWBW 2.6, -these applications are no longer provided. - -David Giles has contributed support for the CSIO support in the SD -Card driver. - -The UNA BIOS is a product of John Coffman. +that much of the work is derived from the work of others in the +RetroBrew Computers Community including Andrew Lynch, Dan Werner, Max +Scane, David Giles, John Coffman, and probably many others I am not +clearly aware of (let me know if I omitted someone!). + +I especially want to credit Douglas Goodall for contributing code, time, +testing, and advice. He created an entire suite of application programs +to enhance the use of RomWBW. However, he is looking for someone to +continue the maintenance of these applications and they have become +unusable due to changes within RomWBW. As of RomWBW 2.6, these +applications are no longer provided. + +- David Giles contributed support for the CSIO support in the SD Card + driver. +- Ed Brindley contributed some of the code that supports the RC2014 + platform. +- Phil Summers contributed Forth and BASIC in ROM as well as a long + list of general code enhancements. +- Curt Mayer contributed the Linux / MacOS build process. +- UNA BIOS is a product of John Coffman. + +Contributions of all kinds to RomWBW are very welcome. Getting Assistance ------------------- The best way to get assistance with RomWBW or any aspect of the -RetroBrew Computers projects is via the community forum at -"https://www.retrobrewcomputers.org/forum/". +RetroBrew Computers projects is via the community forums: -Also feel free to email Wayne Warthen at wwarthen@gmail.com. +- RetroBrew Computers Forum +- RC2014 Google Group +- retro-comp Google Group -Documentation To Do -------------------- +Submission of issues and bugs are welcome at the RomWBW GitHub +Repository. - - Formatting Media - - Making a Disk Bootable - - Assigning disks/slices to drives - - Managing the Console +Also feel free to email Wayne Warthen at wwarthen@gmail.com. diff --git a/Source/BuildDoc.cmd b/Source/BuildDoc.cmd deleted file mode 100644 index f2683b30..00000000 --- a/Source/BuildDoc.cmd +++ /dev/null @@ -1,4 +0,0 @@ -@echo off -setlocal - -setlocal & cd Doc && call Build || exit /b 1 & endlocal \ No newline at end of file diff --git a/Source/CBIOS/cbios.asm b/Source/CBIOS/cbios.asm index 065e81e2..5482cbc1 100644 --- a/Source/CBIOS/cbios.asm +++ b/Source/CBIOS/cbios.asm @@ -192,18 +192,18 @@ LD_UL1 .EQU 0 ; -> LPT1: #ELSE -LD_TTY .EQU CIODEV_CONSOLE ; -> COM0: -LD_CRT .EQU CIODEV_CONSOLE ; -> CRT: +LD_TTY .EQU CIO_CONSOLE ; -> COM0: +LD_CRT .EQU CIO_CONSOLE ; -> CRT: LD_BAT .EQU DEV_BAT -LD_UC1 .EQU CIODEV_CONSOLE ; -> COM1: -LD_PTR .EQU CIODEV_CONSOLE ; -> COM1: -LD_UR1 .EQU CIODEV_CONSOLE ; -> COM2: -LD_UR2 .EQU CIODEV_CONSOLE ; -> COM3: -LD_PTP .EQU CIODEV_CONSOLE ; -> COM1: -LD_UP1 .EQU CIODEV_CONSOLE ; -> COM2: -LD_UP2 .EQU CIODEV_CONSOLE ; -> COM3: -LD_LPT .EQU CIODEV_CONSOLE ; -> LPT0: -LD_UL1 .EQU CIODEV_CONSOLE ; -> LPT1: +LD_UC1 .EQU CIO_CONSOLE ; -> COM1: +LD_PTR .EQU CIO_CONSOLE ; -> COM1: +LD_UR1 .EQU CIO_CONSOLE ; -> COM2: +LD_UR2 .EQU CIO_CONSOLE ; -> COM3: +LD_PTP .EQU CIO_CONSOLE ; -> COM1: +LD_UP1 .EQU CIO_CONSOLE ; -> COM2: +LD_UP2 .EQU CIO_CONSOLE ; -> COM3: +LD_LPT .EQU CIO_CONSOLE ; -> LPT0: +LD_UL1 .EQU CIO_CONSOLE ; -> LPT1: #ENDIF ; @@ -2009,45 +2009,24 @@ AUTOSUB: ; ; SETUP AUTO SUBMIT COMMAND (IF REQUIRED FILES EXIST) LD A,(DEFDRIVE) ; GET DEFAULT DRIVE - - ;CALL PRTHEXBYTE - - PUSH AF - + PUSH AF ; SAVE DEFAULT DRIVE INC A ; CONVERT FROM DRIVE NUM TO FCB DRIVE CODE LD (FCB_SUB),A ; SET DRIVE OF SUBMIT.COM FCB LD (FCB_PRO),A ; SET DRIVE OF PROFILE.SUB FCB ; LD C,13 ; RESET DISK SYSTEM - CALL BDOS - - ;CALL PC_PERIOD - - POP AF -; - ;DEC A ; BACK TO ZERO INDEX - - ;LD E,A ; PUT IN E - ;LD C,14 ; SELECT DISK FUNCTION - ;CALL BDOS ; DO IT - - ;CALL PC_PERIOD + CALL BDOS ; DO IT + POP AF ; RESTORE DEFAULT DRIVE ; LD C,17 ; BDOS FUNCTION: FIND FIRST LD DE,FCB_SUB ; CHECK FOR SUBMIT.COM CALL BDOS ; INVOKE BDOS TO LOOK FOR FILE - - ;CALL PRTHEXBYTE - INC A ; CHECK FOR ERR, $FF --> $00 RET Z ; ERR, DO NOT ATTEMPT AUTO SUBMIT ; LD C,17 ; BDOS FUNCTION: FIND FIRST LD DE,FCB_PRO ; CHECK FOR PROFILE.SUB CALL BDOS ; INVOKE BDOS TO LOOK FOR FILE - - ;CALL PRTHEXBYTE - INC A ; CHECK FOR ERR, $FF --> $00 RET Z ; ERR, DO NOT ATTEMPT AUTO SUBMIT ; @@ -2423,7 +2402,8 @@ DRV_INIT8: CP E ; COMPARE TO CUR SLICE JR NZ,DRV_INIT8A ; IF NE, OK TO CONTINUE INC E ; IS BOOT DU/SLICE, SKIP IT - JR DRV_INIT8 ; AND RESTART LOOP + DJNZ DRV_INIT8 ; LOOP AS NEEDED + RET ; DONE ; DRV_INIT8A: ; ENTRY POINT TO SKIP BOOT DISK/LU CHECK ; @@ -2541,22 +2521,6 @@ DRV_INIT3A: RET ; AND RETURN ; DRV_INIT4: ; SET SLICES PER VOLUME (HDSPV) BASED ON HARD DISK VOLUME COUNT - -; ; *** DEBUG *** -; CALL NEWLINE2 -; LD A,(DRVLSTC) -; LD B,A -; CALL PRTHEXBYTE -; LD A,' ' -; CALL COUT -; LD HL,DRVLST -;TEMP1: -; LD A,(HL) -; INC HL -; CALL PRTHEXBYTE -; DJNZ TEMP1 -; ; *** DEBUG *** - LD A,E ; HARD DISK VOLUME COUNT TO A LD E,8 ; ASSUME 8 SLICES PER VOLUME DEC A ; DEC ACCUM TO CHECK FOR COUNT = 1 @@ -2569,14 +2533,6 @@ DRV_INIT4: ; SET SLICES PER VOLUME (HDSPV) BASED ON HARD DISK VOLUME COUNT DRV_INIT5: LD A,E ; SLICES PER VOLUME VALUE TO ACCUM LD (HDSPV),A ; SAVE IT -; -; ; SETUP TO ENUMERATE DEVICES TO BUILD DRVMAP -; LD B,BF_SYSGET -; LD C,BF_SYSGET_DIOCNT -; RST 08 ; E := DISK UNIT COUNT -; LD B,E ; COUNT TO B -; LD C,0 ; USE C AS DEVICE LIST INDEX -; LD DE,(BOOTVOL) ; BOOT VOLUME (UNIT, SLICE) LD A,1 ; ROM DISK UNIT? CP D ; CHECK IT @@ -2627,7 +2583,8 @@ DRV_INIT8: CP E ; COMPARE TO CUR SLICE JR NZ,DRV_INIT8A ; IF NE, OK TO CONTINUE INC E ; IS BOOT DU/SLICE, SKIP IT - JR DRV_INIT8 ; AND RESTART LOOP + DJNZ DRV_INIT8 ; LOOP AS NEEDED + RET ; DONE ; DRV_INIT8A: ; ENTRY POINT TO SKIP BOOT DISK/LU CHECK ; @@ -2712,20 +2669,7 @@ DPH_INIT1: CALL PRTDRV ; PRINT DRIVE INFO LD A,D ; A := UNIT PUSH HL ; SAVE DRIVE MAP POINTER - ;PUSH AF ; SAVE UNIT - ;; MATCH AND SAVE DEFAULT DRIVE BASED ON BOOT UNIT/SLICE - ;LD HL,BOOTVOL + 1 ; POINT TO BOOT UNIT - ;LD A,D ; LOAD CURRENT UNIT - ;CP (HL) ; MATCH? - ;JR NZ,DPH_INIT1A ; BYPASS IF NOT BOOT UNIT - ;DEC HL ; POINT TO BOOT SLICE - ;LD A,E ; LOAD CURRENT SLICE - ;CP (HL) ; MATCH? - ;JR NZ,DPH_INIT1A ; BYPASS IF NOT BOOT SLICE - ;LD A,C ; LOAD THE CURRENT DRIVE NUM - ;LD (DEFDRIVE),A ; SAVE AS DEFAULT DPH_INIT1A: - ;POP AF ; RESTORE UNIT LD DE,(DPHTOP) ; GET ADDRESS OF NEXT DPH PUSH DE ; ... AND SAVE IT ; INVOKE THE DPH BUILD ROUTINE @@ -2857,7 +2801,6 @@ MAKDPH2: PUSH HL ; MOVE ALLOC RESULT PTR POP BC ; ... TO BC POP HL ; RECOVER DPH PTR TO HL - ;JR NZ,ERR_HEAPOVF ; HANDLE POSSIBLE ALLOC OVERFLOW HERE JR C,ERR_HEAPOVF ; HANDLE POSSIBLE ALLOC OVERFLOW HERE LD (HL),C ; SAVE CKS/ALS BUF INC HL ; ... ADDRESS IN @@ -2876,7 +2819,6 @@ ALLOC: PUSH DE ; AND SAVE FOR RETURN VALUE ADD HL,DE ; ADD REQUESTED SPACE, HL := NEW HEAP TOP JR C,ALLOCX ; TEST FOR CPU MEMORY SPACE OVERFLOW - ;LD DE,(HEAPLIM) ; LOAD DE WITH HEAP LIMIT LD DE,HEAPEND ; LOAD DE WITH HEAP LIMIT EX DE,HL ; DE=NEW HEAPTOP, HL=HEAPLIM SBC HL,DE ; HEAPLIM - HEAPTOP diff --git a/Source/CPM3/boot.z80 b/Source/CPM3/boot.z80 index 38418b3a..a252faff 100644 --- a/Source/CPM3/boot.z80 +++ b/Source/CPM3/boot.z80 @@ -14,7 +14,7 @@ extrn @date,@hour,@min,@sec extrn @srch1 extrn addhla, bcd2bin, bin2bcd - ;extrn cout, phex8 + extrn cout, phex8, phex16, crlf, crlf2 include c:ver.lib @@ -85,7 +85,6 @@ cinit$1: rr l ; ... into correct vector position djnz cinit$1 ; loop as needed - ;ld hl,8000H ; device 0 ld (@civec),hl ; assign to console input ld (@covec),hl ; assign to console output @@ -100,8 +99,7 @@ cinit$1: ld hl,4000h ; assume aux on second char device jr nz,cinit$2 ; if console on unit 0, assumption good ld hl,8000h ; otherwise, aux goes to first char device -cinit$2: - ;ld hl,4000H ; device 1 +cinit$2: ld (@aivec),hl ; assign to aux input ld (@aovec),hl ; assign to aux output cinit$3: @@ -113,6 +111,7 @@ cinit$3: call addhla ; Skip used entries xor a ; Zero to accum ld (hl),0 ; Set table terminator + ret ; done dinit: ; loop through all disk devices to count hard disk units @@ -178,24 +177,7 @@ dinit3a: inc e ; increment hard disk count ret ; and return - dinit4: ; set slices per volume (hdspv) based on hard disk volume count - -; ; *** debug *** -; ;call newline2 -; ld a,(drvlstc) -; ld b,a -; call phex8 -; ld a,' ' -; call cout -; ld hl,drvlst -;temp1: -; ld a,(hl) -; inc hl -; call phex8 -; djnz temp1 -; ; *** debug *** - ld a,e ; hard disk volume count to a ld e,8 ; assume 8 slices per volume dec a ; dec accum to check for count = 1 @@ -250,6 +232,7 @@ dinit6: rlca ; *2 for word entry ld hl,@dtbl ; start of dtbl call addhla ; hl now points to entry + dinit6a: xor a ; zero accum ld (hl),a ; zero lsb @@ -277,7 +260,8 @@ dinit8: ; test to avoid reallocating boot disk unit/slice cp e ; compare to cur slice jr nz,dinit8a ; if ne, ok to continue inc e ; is boot du/slice, skip it - jr dinit8 ; and restart loop + djnz dinit8 ; loop till done with unit + ret dinit8a: ; d=unit, e=slice, l=dph#, b=slice cnt @@ -320,27 +304,6 @@ stpsiz equ $ - stpimg ; called CCP.COM on the system drive. ?ldccp: - - ;if zpm - ; - ;; Swap A: and system drive (make A: the system drive) - ;ld bc,(@dtbl) ; get drive A DPH - ;ld hl,@dtbl ; point to boot drive DPH - ;ld a,(@sysdr) - ;rlca - ;call addhla - ;ld e,(hl) ; set boot drive to drive A DPH - ;ld (hl),c ; ... and save boot drive DPH - ;inc hl - ;ld d,(hl) - ;ld (hl),b - ;ld (@dtbl),de ; set drive a DPH to boot drive - ; - ;xor a ; update @sysdr - ;ld (@sysdr),a - ; - ;endif - ; Force CCP to use system boot drive as initial default ld a,(@sysdr) ; get system boot drive ld (@ccpdr),a ; set CCP current drive @@ -369,22 +332,6 @@ stpsiz equ $ - stpimg if banked -; ; now, -; ; copy CCP to bank 0 for reloading -; lxi h,0100h ! lxi b,0C80h ; clone 3K, just in case -; lda @cbnk ! push psw ; save current bank -;ld$1: -; mvi a,tpa$bank ! call ?bnksl ; select TPA -; mov a,m ! push psw ; get a byte -; mvi a,2 ! call ?bnksl ; select extra bank -; pop psw ! mov m,a ; save the byte -; inx h ! dcx b ; bump pointer, drop count -; mov a,b ! ora c ; test for done -; jnz ld$1 -; pop psw ! call ?bnksl ; restore original bank - -; ; now, -; ; copy CCP to bank 0 for reloading ld hl,0100h ; clone 3K, just in case ld bc,0C80h ld a,(@cbnk) ; save current bank @@ -408,17 +355,9 @@ ld$1: endif - ;; Set first search path to system boot drive - ;inc a - ;ld (@srch1),a - - ;ld e,a - ;ld c,14 - ;call bdos - ret -no$CCP: ; here if we couldn't find the file +no$CCP: ; here if we couldn't find the file ld hl,ccp$msg call ?pmsg call ?conin @@ -429,17 +368,6 @@ no$CCP: ; here if we couldn't find the file if banked -; lxi h,0100h ! lxi b,0C00h ; clone 3K -;rl$1: -; mvi a,2 ! call ?bnksl ; select extra bank -; mov a,m ! push psw ; get a byte -; mvi a,tpa$bank ! call ?bnksl ; select TPA -; pop psw ! mov m,a ; save the byte -; inx h ! dcx b ; bump pointer, drop count -; mov a,b ! ora c ; test for done -; jnz rl$1 -; ret - ld hl,0100h ; clone 3K ld bc,0C80h rl$1: diff --git a/Source/CPM3/util.z80 b/Source/CPM3/util.z80 index affa7ade..28b39244 100644 --- a/Source/CPM3/util.z80 +++ b/Source/CPM3/util.z80 @@ -3,7 +3,7 @@ maclib options.lib public addhla, bcd2bin, bin2bcd - public phex16, phex8, cout + public phex16, phex8, cout, crlf, crlf2 cseg @@ -120,12 +120,28 @@ cout: pop bc pop af ret +; +; output 1 or 2 newlines +; +crlf2: + call crlf +crlf: + ; save all incoming registers + push af + ld a,13 + call cout + ld a,10 + call cout + pop af + ret else phex16: phex8: cout: +crlf2: +crlf: halt endif diff --git a/Source/Clean.cmd b/Source/Clean.cmd index a4420787..b097dc88 100644 --- a/Source/Clean.cmd +++ b/Source/Clean.cmd @@ -13,6 +13,5 @@ setlocal & cd Forth && call Clean.cmd & endlocal setlocal & cd Fonts && call Clean.cmd & endlocal setlocal & cd BPBIOS && call Clean.cmd & endlocal setlocal & cd HBIOS && call Clean.cmd & endlocal -setlocal & cd Doc && call Clean.cmd & endlocal setlocal & cd Images && call Clean & endlocal setlocal & cd Prop && call Clean & endlocal diff --git a/Source/Doc/Architecture.md b/Source/Doc/Architecture.md new file mode 100644 index 00000000..9a73a4cd --- /dev/null +++ b/Source/Doc/Architecture.md @@ -0,0 +1,1672 @@ +!include(Common.inc) +!def(document)(Architecture) +--- +title: | + | !product + | + | !document +author: !author (mailto:!authmail) +date: !date +institution: !orgname +documentclass: book +classoption: +- oneside +toc: true +toc-depth: 1 +numbersections: true +secnumdepth: 1 +papersize: letter +geometry: +- top=1in +- bottom=1in +- left=1in +- right=1in +# - showframe +# - pass +linestretch: 1.25 +colorlinks: true +fontfamily: helvet +fontsize: 12pt +header-includes: +- \setlength{\headheight}{15pt} +- | + ```{=latex} + \usepackage{fancyhdr} + \usepackage{xcolor} + \usepackage{xhfill} + \renewcommand*{\familydefault}{\sfdefault} + \renewcommand{\maketitle}{ + \begin{titlepage} + \centering + \par + \vspace*{0pt} + \includegraphics[width=\paperwidth]{Graphics/Logo.pdf} \par + \vfill + \raggedleft + {\scshape \bfseries \fontsize{48pt}{56pt} \selectfont !product \par} + {\bfseries \fontsize{32pt}{36pt} \selectfont !document \par} + \vspace{24pt} + {\huge Version !ver \\ !date \par} + \vspace{24pt} + {\large \itshape !orgname \\ \href{http://!orgurl}{!orgurl} \par} + \vspace{12pt} + {\large \itshape !author \\ \href{mailto:authmail}{!authmail} \par} + \end{titlepage} + } + \pagestyle{empty} + ``` +include-before: +- \renewcommand{\chaptername}{Section} +- | + ```{=latex} + \pagestyle{fancyplain} + \fancyhf{} + \lfoot{\small RetroBrew Computing Group ~~ {\xrfill[3pt]{1pt}[cyan]} ~~ \thepage} + \pagenumbering{roman} + ``` +--- + +```{=latex} +\clearpage +\pagenumbering{arabic} +\lhead{\fancyplain{}{\nouppercase{\footnotesize \bfseries \leftmark \hfill !product !document}}} +``` + +Overview +======== + +RomWBW provides a complete firmware package for all of the Z80 and Z180 +based systems that are available in the RetroBrew Computers Community +(see +[http://www.retrobrewcomputers.org](http://www.retrobrewcomputers.org/)) +as well as support for the RC2014 platform. Each of these systems +provides for a fairly large ROM memory (typically, 512KB or more). +RomWBW allows you to configure and build appropriate contents for such a +ROM. + +Typically, a computer will contain a small ROM that contains the BIOS +(Basic Input/Output System) functions as well as code to start the +system by booting an operating system from a disk. Since the RetroBrew +Computers Projects provide a large ROM space, RomWBW provides a much +more comprehensive software package. In fact, it is entirely possible to +run a fully functioning RetroBrew Computers System with nothing but the +ROM. + +RomWBW firmware includes: + +- System startup code (bootstrap) + +- A basic system/debug monitor + +- HBIOS (Hardware BIOS) providing support for the vast majority of + RetroBrew Computers I/O components + +- A complete operating system (either CP/M 2.2 or ZSDOS 1.1) + +- A built-in CP/M filesystem containing the basic applications and + utilities for the operating system and hardware being used + +It is appropriate to note that much of the code and components that make +up a complete RomWBW package are derived from pre-existing work. Most +notably, the imbedded operating system is simply a ROM-based copy of +generic CP/M or ZSDOS. Much of the hardware support code was originally +produced by other members of the RetroBrew Computers Community. + +The remainder of this document will focus on the HBIOS portion of the +ROM. HBIOS contains the vast majority of the custom-developed code for +the RetroBrew Computers hardware platforms. It provides a formal, +structured interface that allows the operating system to be hosted with +relative ease. + +Background +========== + +The Z80 CPU architecture has a limited, 64K address range. In general, +this address space must accommodate a running application, disk +operating system, and hardware support code. + +All RetroBrew Computers Z80 CPU platforms provide a physical address +space that is much larger than the CPU address space (typically 512K or +1MB physical RAM). This additional memory can be made available to the +CPU using a technique called bank switching. To achieve this, the +physical memory is divided up into chunks (banks) of 32K each. A +designated area of the CPU's 64K address space is then reserved to "map" +any of the physical memory chunks. You can think of this as a window +that can be adjusted to view portions of the physical memory in 32K +blocks. In the case of RetroBrew Computers platforms, the lower 32K of +the CPU address space is used for this purpose (the window). The upper +32K of CPU address space is assigned a fixed 32K area of physical memory +that never changes. The lower 32K can be "mapped" on the fly to any of +the 32K banks of physical memory at a time. The only constraint is that +the CPU cannot be executing code in the lower 32K of CPU address space +at the time that a bank switch is performed. + +By cleverly utilizing the pages of physical RAM for specific purposes +and swapping in the correct page when needed, it is possible to utilize +substantially more than 64K of RAM. Because the RetroBrew Computers +Project has now produced a very large variety of hardware, it has become +extremely important to implement a bank switched solution to accommodate +the maximum range of hardware devices and desired functionality. + +General Design Strategy +======================= + +The design goal is to locate as much of the hardware dependent code as +possible out of normal 64KB CP/M address space and into a bank switched +area of memory. A very small code shim (proxy) is located in the top 512 +bytes of CPU memory. This proxy is responsible for redirecting all +hardware BIOS (HBIOS) calls by swapping the "driver code" bank of +physical RAM into the lower 32K and completing the request. The +operating system is unaware this has occurred. As control is returned to +the operating system, the lower 32KB of memory is switched back to the +original memory bank. + +HBIOS is completely agnostic with respect to the operating system (it +does not know or care what operating system is using it). The operating +system makes simple calls to HBIOS to access any desired hardware +functions. Since the HBIOS proxy occupies only 512 bytes at the top of +memory, the vast majority of the CPU memory is available to the +operating system and the running application. As far as the operating +system is concerned, all of the hardware driver code has been magically +implemented inside of a small 512 byte area at the top of the CPU +address space. + +Unlike some other Z80 bank switching schemes, there is no attempt to +build bank switching into the operating system itself. This is +intentional so as to ensure that any operating system can easily be +adapted without requiring invasive modifications to the operating system +itself. This also keeps the complexity of memory management completely +away from the operating system and applications. + +There are some operating systems that have built-in support for bank +switching (e.g., CP/M 3). These operating systems are allowed to make +use of the bank switched memory and are compatible with HBIOS. However, +it is necessary that the customization of these operating systems take +into account the banks of memory used by HBIOS and not attempt to use +those specific banks. + +Note that all code and data are located in RAM memory during normal +execution. While it is possible to use ROM memory to run code, it would +require that more upper memory be reserved for data storage. It is +simpler and more memory efficient to keep everything in RAM. At startup +(boot) all required code is copied to RAM for subsequent execution. + +Runtime Memory Layout +===================== + +![Banked Switched Memory Layout](Graphics/Bank Switched Memory){ width=80% } + +System Boot Process +=================== + +A multi-phase boot strategy is employed. This is necessary because at +cold start, the CPU is executing code from ROM in lower memory which is +the same area that is bank switched. + +Boot Phase 1 copies the phase 2 code to upper memory and jumps to it to +continue the boot process. This is required because the CPU starts at +address \$0000 in low memory. However, low memory is used as the area +for switching ROM/RAM banks in and out. Therefore, it is necessary to +relocate execution to high memory in order to initialize the RAM memory +banks. + +Boot Phase 2 manages the setup of the RAM page banks for HBIOS +operation, performs hardware initialization, and then executes the boot +loader. + +Boot Phase 3 is the loading of the selecting operating system (or debug +monitor) by the Boot Loader. The Boot Loader is responsible for +prompting the user to select a target operating system to load, loading +it into RAM, then transferring control to it. The Boot Loader is capable +of loading a target operating system from a variety of locations +including disk drives and ROM. + +Note that the entire boot process is entirely operating system agnostic. +It is unaware of the operating system being loaded. The Boot Loader +prompts the user for the location of the binary image to load, but does +not know anything about what is being loaded (the image is usually an +operating system, but could be any executable code image). Once the Boot +Loader has loaded the image at the selected location, it will transfer +control to it. Assuming the typical situation where the image was an +operating system, the loaded operating system will then perform it's own +initialization and begin normal operation. + +There are actually two ways to perform a system boot. The first, and +most commonly used, method is a "ROM Boot". This refers to booting the +system directly from the startup code contained on the physical ROM +chip. A ROM Boot is always performed upon power up or when a hardware +reset is performed. + +Once the system is running (operating system loaded), it is possible to +reboot the system from a system image contained on the file system. This +is referred to as an "Application Boot". This mechanism allows a +temporary copy of the system to be uploaded and stored on the file +system of an already running system and then used to boot the system. +This boot technique is useful to: 1) test a new build of a system image +before programming it to the ROM; or 2) easily switch between system +images on the fly. + +A more detailed explanation of these two boot processes is presented +below. + +ROM Boot +-------- + +At power on (or hardware reset), ROM page 0 is automatically mapped to +lower memory by hardware level system initialization. Page Zero (first +256 bytes of the CPU address space) is reserved to contain dispatching +instructions for interrupt instructions. Address \$0000 performs a jump +to the start of the phase 1 code so that this first page can be +reserved. + +The phase 1 code now copies the phase 2 code from lower memory to upper +memory and jumps to it. The phase 2 code now initializes the HBIOS by +copying the ROM resident HBIOS from ROM to RAM. It subsequently calls +the HBIOS initialization routine. Finally, it starts the Boot Loader +which prompts the user for the location of the target system image to +execute. + +Once the boot loader transfers control to the target system image, all +of the Phase 1, Phase 2, and Boot Loader code is abandoned and the space +it occupied is normally overwritten by the operating system. + +Application Boot +---------------- + +When a new system image is built, one of the output files produced is an +actual CP/M application (an executable .COM program file). Once you have +a running CP/M (or compatible) system, you can upload/copy this +application file to the filesystem. By executing this file, you will +initiate an Application Boot using the system image contained in the +application file itself. + +Upon execution, the Application Boot program is loaded into memory by +the previously running operating system starting at \$0100. Note that +program image contains a copy of the HBIOS to be installed and run. Once +the Application Boot program is loaded by the previous operating system, +control is passed to it and it performs a system initialization similar +to the ROM Boot, but using the image loaded in RAM. + +Specifically, the code at \$0100 (in low memory) copies phase 2 boot +code to upper memory and transfers control to it. The phase 2 boot code +copies the HBIOS image from application RAM to RAM, then calls the HBIOS +initialization routine. At this point, the prior HBIOS code has been +discarded and overwritten. Finally, the Boot Loader is invoked just like +a ROM Boot. + +Notes +----- + +1. Size of ROM disk and RAM disk will be decreased as needed to + accommodate RAM and ROM memory bank usage for the banked BIOS. + +2. There is no support for interrupt driven drivers at this time. Such + support should be possible in a variety of ways, but none are yet + implemented. + +Driver Model +============ + +The framework code for bank switching also allows hardware drivers to be +implemented mostly without concern for memory management. Drivers are +coded to simply implement the HBIOS functions appropriate for the type +of hardware being supported. When the driver code gets control, it has +already been mapped to the CPU address space and simply performs the +requested function based on parameters passed in registers. Upon return, +the bank switching framework takes care of restoring the original memory +layout expected by the operating system and application. + +However, the one constraint of hardware drivers is that any data buffers +that are to be returned to the operating system or applications must be +allocated in high memory. Buffers inside of the driver's memory bank +will be swapped out of the CPU address space when control is returned to +the operating system. + +If the driver code must make calls to other code, drivers, or utilities +in the driver bank, it must make those calls directly (it must not use +RST 08). This is to avoid a nested bank switch which is not supported at +this time. + +Character / Emulation / Video Services +====================================== + +In addition to a generic set of routines to handle typical character +input/output, HBIOS also includes functionality for managing built-in +video display adapters. To start with there is a basic set of character +input/output functions, the CIOXXX functions, which allow for simple +character data streams. These functions fully encompass routing byte +stream data to/from serial ports. Note that there is a special character +pseudo-device called "CRT". When characters are read/written to/from the +CRT character device, the data is actually passed to a built-in terminal +emulator which, in turn, utilizes a set of VDA (Video Display Adapter) +functions (such as cursor positioning, scrolling, etc.). + +Figure 7.1 depicts the relationship between these components +of HBIOS video processing: + +![Character / Emulation / Video Services](Graphics/Character Emulation Video Services){ width=100% } + +Normally, the operating system will simply utilize the CIOXXX functions +to send and receive character data. The Character I/O Services will +route I/O requests to the specified physical device which is most +frequently a serial port (such as UART or ASCI). As shown above, if the +CRT device is targeted by a CIOXXX function, it will actually be routed +to the Emulation Services which implement TTY, ANSI, etc. escape +sequences. The Emulation Services subsequently rely on the Video Display +Adapter Services as an additional layer of abstraction. This allows the +emulation code to be completely unaware of the actual physical device +(device independent). Video Display Adapter (VDA) Services contains +drivers as needed to handle the available physical video adapters. + +Note that the Emulation and VDA Services API functions are available to +be called directly. Doing so must be done carefully so as to not corrupt +the "state" of the emulation logic. + +Before invoking CIOXXX functions targeting the CRT device, it is +necessary that the underlying layers (Emulation and VDA) be properly +initialized. The Emulation Services must be initialized to specify the +desired emulation and specific physical VDA device to target. Likewise, +the VDA Services may need to be initialized to put the specific video +hardware into the proper mode, etc. + +HBIOS Reference +=============== + +Invocation +---------- + +HBIOS functions are invoked by placing the required parameters in CPU registers and executing an RST 08 instruction. Note that HBIOS does not preserve register values that are unused. However, it will not modify the Z80 alternate registers or IX/IY (these registers may be used within HBIOS, but will be saved and restored internally). + +Normally, applications will not call HBIOS functions directly. It is intended that the operating system makes all HBIOS function calls. Applications that are considered system utilities may use HBIOS, but must be careful not to modify the operating environment in any way that the operating system does not expect. + +In general, the desired function is placed in the B register. Register C is frequently used to specify a subfunction or a target device unit number. Additional registers are used as defined by the specific function. Register A should be used to return function result information. A=0 should indicate success, other values are function specific. + +The character, disk, and video device functions all refer to target devices using a logical device unit number that is passed in the C register. Keep in mind that these unit numbers are assigned dynamically at HBIOS initialization during the device discovery process. The assigned unit numbers are displayed on the consoled at the conclusion of device initialization. The unit assignments will never change after HBIOS initialization. However, they can change at the next boot if there have been hardware or BIOS customization changes. Code using HBIOS functions should not assume fixed unit assignments. + +Some functions utilize pointers to memory buffers. Unless otherwise stated, such buffers can be located anywhere in the Z80 CPU 64K address space. However, performance sensitive buffers (primarily disk I/O buffers) will require double-buffering if the caller’s buffer is in the lower 32K of CPU address space. For optimal performance, such buffers should be placed in the upper 32K of CPU address space. + +\newpage + +Character Input/Output (CIO) +---------------------------- + +Character input/output functions require that a Character Unit be specified in the C register. This is the logical device unit number assigned during the boot process that identifies all character I/O devices uniquely. A special value of 0x80 can be used for Unit to refer to the current console device. + +Character devices can usually be configured with line characteristics +such as speed, framing, etc. A word value (16 bit) is used to describe +the line characteristics as indicated below: + +_Bits_ | _Function_ +------ | ---------- +15-14 | Reserved (set to 0) +13 | RTS +12-8 | Baud Rate (see below) +7 | DTR +6 | XON/XOFF Flow Control +5-3 | Parity (???) +2 | Stop Bits (???) +1-0 | Data Bits (???) + +The 5-bit baud rate value (V) is encoded as V = 75 \* 2\^X \* 3\^Y. The +bits are defined as YXXXX. + +### Function 0x00 -- Character Input (CIOIN) + +| _Entry Parameters_ +| B: 0x00 +| C: Serial Device Unit Number + +| _Exit Results_ +| A: Status (0=OK, else error) +| E: Character Received + +Read a character from the device unit specified in register C and return the character +value in E. If no character(s) are available, this function will wait indefinitely. + +### Function 0x01 -- Character Output (CIOOUT) + +| _Entry Parameters_ +| B: 0x01 +| C: Serial Device Unit Number +| E: Character to Send + +| _Exit Results_ +| A: Status (0=OK, else error) + +Send character value in register E to device specified in register C. If device is +not ready to send, function will wait indefinitely. + +### Function 0x02 -- Character Input Status (CIOIST) + +| _Entry Parameters_ +| B: 0x02 +| C: Serial Device Unit Number + +| _Exit Results_ +| A: Bytes Pending + +Return the number of characters available to read in the input buffer of the unit +specified. If the device has no input buffer, it is acceptable to return simply 0 or +1 where 0 means there is no character available to read and 1 means there is at +least one character available to read. + +### Function 0x03 -- Character Output Status (CIOOST) + +| _Entry Parameters_ +| B: 0x03 +| C: Serial Device Unit Number + +| _Exit Results_ +| A: Output Buffer Bytes Available + +Return the space available in the output buffer expressed as a character count. If a +16 byte output buffer contained 6 characters waiting to be sent, this function would +return 10, the number of positions available in the output buffer. If the port has +no output buffer, it is acceptable to return simply 0 or 1 where 0 means the port is +busy and 1 means the port is ready to output a character. + +### Function 0x04 -- Character IO Initialization (CIOINIT) + +| _Entry Parameters_ +| B: 0x04 +| C: Serial Device Unit Number +| DE: Line Characteristics + +| _Exit Results_ +| A: Status (0=OK, else error) + +Setup line characteristics (baudrate, framing, etc.) of the specified unit. Register +pair DE specifies line characteristics. If DE contains -1 (0xFFFF), then the device +will be reinitialized with the last line characteristics used. Result of function +is returned in A with zero indicating success. + +### Function 0x05 -- Character IO Query (CIOQUERY) + +| _Entry Parameters_ +| B: 0x05 +| C: Serial Device Unit Number + +| _Exit Results_ +| A: Status (0=OK, else error) +| DE: Line Characteristics + +Reports the line characteristics (baudrate, framing, etc.) of the specified unit. +Register pair DE contains the line characteristics upon return. + +### Function 0x06 -- Character IO Device (CIODEVICE) + +| _Entry Parameters_ +| B: 0x06 +| C: Serial Device Unit Number + +| _Exit Results_ +| A: Status (0=OK, else error) +| C: Serial Device Attributes +| D: Serial Device Type +| E: Serial Device Number + +Reports information about the character device unit specified. Register C indicates +the device attributes: 0=RS-232 and 1=Terminal. Register D indicates the device type +(driver) and register E indicates the physical device number assigned by the driver. + +Each character device is handled by an appropriate driver (UART, ASCI, etc.). The driver can be identified by the Device Type. The assigned Device Types are listed below. + +_Id_ | _Device Type / Driver_ +---- | ---------------------- +0x00 | UART +0x10 | ASCI +0x20 | Terminal +0x30 | PropIO VGA +0x40 | ParPortProp VGA +0x50 | SIO +0x60 | ACIA +0x70 | PIO +0x80 | UF + +\newpage + +Disk Input/Output (DIO) +----------------------- + +Character input/output functions require that a character unit be +specified in the C register. This is the logical disk unit number +assigned during the boot process that identifies all disk i/o devices +uniquely. + +A fixed set of media types are defined. The currently defined media types are listed below. Each driver will support a subset of the defined media types. + +**Media ID** | **Value** | **Format** +------------ | --------- | ---------- +MID\_NONE | 0 | No media installed +MID\_MDROM | 1 | ROM Drive +MID\_MDRAM | 2 | RAM Drive +MID\_RF | 3 | RAM Floppy (LBA) +MID\_HD | 4 | Hard Disk (LBA) +MID\_FD720 | 5 | 3.5" 720K Floppy +MID\_FD144 | 6 | 3.5" 1.44M Floppy +MID\_FD360 | 7 | 5.25" 360K Floppy +MID\_FD120 | 8 | 5.25" 1.2M Floppy +MID\_FD111 | 9 | 8" 1.11M Floppy + +### Function 0x10 -- Disk Status (DIOSTATUS) + +| _Entry Parameters_ +| B: 0x10 + +| _Exit Results_ +| A: Status (0=OK, else error) + +### Function 0x11 -- Disk Status (DIORESET) + +| _Entry Parameters_ +| B: 0x11 +| C: Disk Device Unit ID + +| _Exit Results_ +| A: Status (0=OK, else error) + +Reset the physical interface associated with the specified unit. Flag +all units associated with the interface for unit initialization at next +I/O call. Clear media identified unless locked. Reset result code of all +associated units of the physical interface. + +### Function 0x12 -- Disk Seek (DIOSEEK) + +| _Entry Parameters_ +| B: 0x12 +| C: Disk Device Unit ID +| D7: Address Type (0=CHS, 1=LBA) + +| if CHS: +| D6-0: Head +| E: Sector +| HL: Track + +| if LBA: +| DE:HL: Block Address + +| _Exit Results_ +| A: Status (0=OK, else error) + +Update target CHS or LBA for next I/O request on designated unit. +Physical seek is typically deferred until subsequent I/O +operation. + +Bit 7 of D indicates whether the disk seek address is specified as +cylinder/head/sector (CHS) or Logical Block Address (LBA). If D:7=1, then +the remaining bits of of the 32 bit register set DE:HL specify a linear, +zero offset, block number. If D:7=0, then the remaining bits of D specify +the head, E specifies sector, and HL specifies track. + +Note that not all devices will accept both types of addresses. +Specifically, floppy disk devices must have CHS addresses. All other +devices will accept either CHS or LBA. The DIOGEOM function can be used to +determine if the device supports LBA addressing. + +### Function 0x13 -- Disk Read (DIOREAD) + +| _Entry Parameters_ +| B: 0x13 +| C: Disk Device Unit ID +| E: Block Count +| HL: Buffer Address + +| _Exit Results_ +| A: Status (0=OK, else error) +| E: Blocks Reaad + +Read Block Count sectors to buffer address starting at current target +sector. Current sector must be established by prior seek function; +however, multiple read/write/verify function calls can be made after a +seek function. Current sector is incremented after each sector +successfully read. On error, current sector is sector is sector where +error occurred. Blocks read indicates number of sectors successfully read. + +Caller must ensure: 1) buffer address is large enough to contain data for all +sectors requested, and 2) entire buffer area resides in upper 32K of memory. + +### Function 0x14 -- Disk Write (DIOWRITE) + +| _Entry Parameters_ +| B: 0x14 +| C: Disk Device Unit ID +| E: Block Count +| HL: Buffer Address + +| _Exit Results_ +| A: Status (0=OK, else error) +| E: Blocks Written + +Write Block Count sectors to buffer address starting at current target +sector. Current sector must be established by prior seek function; +however, multiple read/write/verify function calls can be made after a +seek function. Current sector is incremented after each sector +successfully written. On error, current sector is sector is sector where +error occurred. Blocks written indicates number of sectors successfully +written. + +Caller must ensure: 1) buffer address is large enough to contain data for all +sectors being written, and 2) entire buffer area resides in upper 32K of memory. + +### Function 0x15 -- Disk Verify (DIOVERIFY) + +| _Entry Parameters_ +| B: 0x15 +| C: Disk Device Unit ID +| HL: Buffer Address +| E: Block Count + +| _Exit Results_ +| A: Status (0=OK, else error) +| E: Blocks Verified + +\*\*\*Not Implemented\*\*\* + +### Function 0x16 -- Disk Format (DIOFORMAT) + +| _Entry Parameters_ +| B: 0x16 +| C: Disk Device Unit ID +| D: Head +| E: Fill Byte +| HL: Cylinder + +| _Exit Results_ +| A: Status (0=OK, else error) + +\*\*\*Not Implemented\*\*\* + +### Function 0x17 -- Disk DEVICE (DIODEVICE) + +| _Entry Parameters_ +| B: 0x17 +| C: Disk Device Unit ID + +| _Exit Results_ +| A: Status (0=OK, else error) +| C: Attributes +| D: Device Type +| E: Device Number + +Reports information about the character device unit specified. Register D +indicates the device type (driver) and register E indicates the physical +device number assigned by the driver. + +Register C reports the following device attributes: + +Bit 7: 1=Floppy, 0=Hard Disk (or similar, e.g. CF, SD, RAM) + +| If Floppy: +| Bits 6-5: Form Factor (0=8", 1=5.25", 2=3.5", 3=Other) +| Bit 4: Sides (0=SS, 1=DS) +| Bits 3-2: Density (0=SD, 1=DD, 2=HD, 3=ED) +| Bits 1-0: Reserved + +| If Hard Disk: +| Bit 6: Removable\ +| Bits: 5-3: Type (0=Hard, 1=CF, 2=SD, 3=USB, +| 4=ROM, 5=RAM, 6=RAMF, 7=Reserved) +| Bits 2-0: Reserved + +Each disk device is handled by an appropriate driver (IDE, SD, +etc.) which is identified by a device type id from the table below. + +**Type ID** | **Disk Device Type** +----------- | -------------------- +0x00 | Memory Disk +0x10 | Floppy Disk +0x20 | RAM Floppy +0x30 | IDE Disk +0x40 | ATAPI Disk (not implemented) +0x50 | PPIDE Disk +0x60 | SD Card +0x70 | PropIO SD Card +0x80 | ParPortProp SD Card +0x90 | SIMH HDSK Disk + +### Function 0x18 -- Disk Media (DIOMEDIA) + +| _Entry Parameters_ +| B: 0x18 +| C: Disk Device Unit ID +| E0: Enable Media Discovery + +| _Exit Results_ +| A: Status (0=OK, else error) +| E: Media ID + +Report the media definition for media in specified unit. If bit 0 of E is +set, then perform media discovery or verification. If no media in device, +function will return an error status. + +### Function 0x19 -- Disk Define Media (DIODEFMED) + +| _Entry Parameters_ +| B: 0x19 +| C: Disk Device Unit ID +| E: Media ID + +| _Exit Results_ +| A: Status (0=OK, else error) + +\*\*\* Not implemented \*\*\* + +### Function 0x1A -- Disk Capacity (DIOCAPACITY) + +| _Entry Parameters_ +| B: 0x1A +| C: Disk Device Unit ID +| HL: Buffer Address + +| _Exit Results_ +| A: Status (0=OK, else error) +| DE:HL: Blocks on Device +| BC: Block Size + +Report current media capacity information. DE:HL is a 32 bit number +representing the total number of blocks on the device. BC contains the +block size. If media is unknown, an error will be returned. + +### Function 0x1B -- Disk Geometry (DIOGEOMETRY) + +| _Entry Parameters_ +| B: 0x1B +| C: Disk Device Unit ID + +| _Exit Results_ +| A: Status (0=OK, else error) +| HL: Cylinders +| D7: LBA Capability +| BC: Block Size + +Report current media geometry information. If media is unknown, return +error (no media). + +\newpage + +Real Time Clock (RTC) +--------------------- + +The Real Time Clock functions provide read/write access to the clock and +related Non-Volatile RAM. + +The time functions (RTCGTM and RTCSTM) require a 6 byte date/time buffer +of the following format. Each byte is BCD encoded. + +**Offset** | **Contents** +---------- | ------------ +0 | Year (00-99) +1 | Month (01-12) +2 | Date (01-31) +3 | Hours (00-24) +4 | Minutes (00-59) +5 | Seconds (00-59) + +### Function 0x20 -- RTC Get Time (RTCGETTIM) + +| _Entry Parameters_ +| B: 0x20 +| HL: Time Buffer Address + +| _Exit Results_ +| A: Status (0=OK, else error) + +Read the current value of the clock and store the date/time in the +buffer pointed to by HL. + +### Function 0x21 -- RTC Set Time (RTCSETTIM) + +| _Entry Parameters_ +| B: 0x21 +| HL: Time Buffer Address + +| _Exit Results_ +| A: Status (0=OK, else error) + +Set the current value of the clock based on the date/time in the buffer +pointed to by HL. + +### Function 0x22 -- RTC Get NVRAM Byte (RTCGETBYT) + +| _Entry Parameters_ +| B: 0x22 +| C: Index + +| _Exit Results_ +| A: Status (0=OK, else error) +| E: Value + +Read a single byte value from the Non-Volatile RAM at the index +specified by C. The value is returned in register E. + +### Function 0x23 -- RTC Set NVRAM Byte (RTCSETBYT) + +| _Entry Parameters_ +| B: 0x23 +| C: Index + +| _Exit Results_ +| A: Status (0=OK, else error) +| E: Value + +Write a single byte value into the Non-Volatile RAM at the index +specified by C. The value to be written is specified in E. + +### Function 0x24 -- RTC Get NVRAM Block (RTCGETBLK) + +| _Entry Parameters_ +| B: 0x24 +| HL: Buffer + +| _Exit Results_ +| A: Status (0=OK, else error) + +Read the entire contents of the Non-Volatile RAM into the buffer pointed +to by HL. HL must point to a location in the top 32K of CPU address space. + +### Function 0x25 -- RTC Set NVRAM Block (RTCSETBLK) + +| _Entry Parameters_ +| B: 0x25 +| HL: Buffer + +| _Exit Results_ +| A: Status (0=OK, else error) + +Write the entire contents of the Non-Volatile RAM from the buffer +pointed to by HL. HL must point to a location in the top 32K of CPU +address space. + +Video Display Adapter (VDA) +--------------------------- + +The VDA functions are provided as a common interface to Video Display +Adapters. Not all VDAs will include keyboard hardware. In this case, the +keyboard functions should return a failure status. + +Depending on the capabilities of the hardware, the use of colors and +attributes may or may not be supported. If the hardware does not support +these capabilities, they will be ignored. + +Color byte values are constructed using typical RGBI +(Red/Green/Blue/Intensity) bits. The high four bits of the value +determine the background color and the low four bits determine the +foreground color. This results in 16 unique color values for both +foreground and background. The following table illustrates the color +byte value construction: + +  | **Bit** | **Color** +---------- | ------- | --------- +Background | 7 | Intensity +  | 6 | Blue +  | 5 | Green +  | 4 | Red +Foreground | 3 | Intensity +  | 2 | Blue +  | 1 | Green +  | 0 | Red + +The following table illustrates the resultant color for each of the +possible 16 values for foreground or background: + +**Foreground** | **Background** | **Color** +------------------ | ------------------ | ---------------- +\_0 \_\_\_\_0000 | 0\_ 0000\_\_\_\_ | Black +\_1 \_\_\_\_0001 | 1\_ 0001\_\_\_\_ | Red +\_2 \_\_\_\_0010 | 2\_ 0010\_\_\_\_ | Green +\_3 \_\_\_\_0011 | 3\_ 0011\_\_\_\_ | Brown +\_4 \_\_\_\_0100 | 4\_ 0100\_\_\_\_ | Blue +\_5 \_\_\_\_0101 | 5\_ 0101\_\_\_\_ | Magenta +\_6 \_\_\_\_0110 | 6\_ 0110\_\_\_\_ | Cyan +\_7 \_\_\_\_0111 | 7\_ 0111\_\_\_\_ | White +\_8 \_\_\_\_1000 | 8\_ 1000\_\_\_\_ | Gray +\_9 \_\_\_\_1001 | 9\_ 1001\_\_\_\_ | Light Red +\_A \_\_\_\_1010 | A\_ 1010\_\_\_\_ | Light Green +\_B \_\_\_\_1011 | B\_ 1011\_\_\_\_ | Yellow +\_C \_\_\_\_1100 | C\_ 1100\_\_\_\_ | Light Blue +\_D \_\_\_\_1101 | D\_ 1101\_\_\_\_ | Light Magenta +\_E \_\_\_\_1110 | E\_ 1110\_\_\_\_ | Light Cyan +\_F \_\_\_\_1111 | F\_ 1111\_\_\_\_ | Bright White + +Attribute byte values are constructed using the following bit encoding: + +**Bit** | **Effect** +------- | ---------- +7 | n/a (0) +6 | n/a (0) +5 | n/a (0) +4 | n/a (0) +3 | n/a (0) +2 | Reverse +1 | Underline +0 | Blink + +The following codes are returned by a keyboard read to signify non-ASCII +keystrokes: + +**Value** | **Keystroke** | **Value** | **Keystroke** +--------- | ------------- | --------- | ------------- +0xE0 | F1 | 0xF0 | Insert +0xE1 | F2 | 0xF1 | Delete +0xE2 | F3 | 0xF2 | Home +0xE3 | F4 | 0xF3 | End +0xE4 | F5 | 0xF4 | PageUp +0xE5 | F6 | 0xF5 | PadeDown +0xE6 | F7 | 0xF6 | UpArrow +0xE7 | F8 | 0xF7 | DownArrow +0xE8 | F9 | 0xF8 | LeftArrow +0xE9 | F10 | 0xF9 | RightArrow +0xEA | F11 | 0xFA | Power +0xEB | F12 | 0xFB | Sleep +0xEC | SysReq | 0xFC | Wake +0xED | PrintScreen | 0xFD | Break +0xEE | Pause | 0xFE | +0xEF | App | 0xFF | + +### Function 0x40 -- Video Initialize (VDAINI) + +| _Entry Parameters_ +| B: 0x40 +| C: Video Device Unit ID +| E: Video Mode (device specific) +| HL: Font Bitmap Buffer Address (optional) + +| _Exit Results_ +| A: Status (0=OK, else error) + +Performs a full (re)initialization of the specified video device. The +screen is cleared and the keyboard buffer is flushed. If the specified +VDA supports multiple video modes, the requested mode can be specified +in E (set to 0 for default/not specified). Mode values are specific to +each VDA. + +HL may point to a location in memory with the character bitmap to be +loaded into the VDA video processor. The location MUST be in the top 32K +of the CPU memory space. HL must be set to zero if no character bitmap +is specified (the VDA video processor will utilize a default character +bitmap). + +### Function 0x41 -- Video Query (VDAQRY) + +| _Entry Parameters_ +| B: 0x41 +| C: Video Device Unit ID +| HL: Font Bitmap Buffer Address (optional) + +| _Exit Results_ +| A: Status (0=OK, else error) +| C: Video Mode +| D: Row Count +| E: Column Count +| HL: Font Bitmap Buffer Address (0 if N/A) + +Return information about the specified video device. C will be set to +the current video mode. DE will return the dimensions of the video +display as measured in rows and columns. Note that this is the **count** +of rows and columns, not the **last** row/column number. + +If HL is not zero, it must point to a suitably sized memory buffer in +the upper 32K of CPU address space that will be filled with the current +character bitmap data. It is critical that HL be set to zero if it does +not point to a proper buffer area or memory corruption will result. The +video device driver may not have the ability to provide character bitmap +data. In this case, on return, HL will be set to zero. + +### Function 0x42 -- Video Reset (VDARES) + +| _Entry Parameters_ +| B: 0x42 +| C: Video Device Unit ID + +| _Exit Results_ +| A: Status (0=OK, else error) + +Performs a soft reset of the Video Display Adapter. Should clear the +screen, home the cursor, restore active attribute and color to defaults. +Keyboard should be flushed. + +### Function 0x43 -- Video Device (VDADEV) + +| _Entry Parameters_ +| B: 0x43 +| C: Video Device Unit ID + +| _Exit Results_ +| A: Status (0=OK, else error) +| D=Device Type +| E=Device Number + +Reports information about the video device unit specified. + +Register D reports the video device type (see below). + +Register E reports the driver relative physical device number. + +The currently defined video device types are: + +VDA ID | Value | Device +---------- | ----- | ------ +VDA\_NONE | 0x00 | No VDA +VDA\_VDU | 0x10 | ECB VDU board +VDA\_CVDU | 0x20 | ECB Color VDU board +VDA\_7220 | 0x30 | ECB uPD7220 video display board +VDA\_N8 | 0x40 | TMS9918 video display built-in to N8 +VDA\_VGA | 0x50 | ECB VGA board + +### Function 0x44 -- Video Set Cursor Style (VDASCS) + +| _Entry Parameters_ +| B: 0x44 +| C: Video Device Unit ID +| D: Start/End Pixel Row +| E: Style + +| _Exit Results_ +| A: Status (0=OK, else error) + +If supported by the video hardware, adjust the format of the cursor such +that the cursor starts at the pixel specified in the top nibble of D and +end at the pixel specified in the bottom nibble of D. So, if D=\$08, a +block cursor would be used that starts at the top pixel of the character +cell and ends at the ninth pixel of the character cell. + +Register E is reserved to control the style of the cursor (blink, +visibility, etc.), but is not yet implemented. + +Adjustments to the cursor style may or may not be possible for any given +video hardware. + +### Function 0x45 -- Video Set Cursor Position (VDASCP) + +| _Entry Parameters_ +| B: 0x45 +| C: Video Device Unit ID +| D: Row (0 indexed) +| E: Column (0 indexed) + +| _Exit Results_ +| A: Status (0=OK, else error) + +Reposition the cursor to the specified row and column. Specifying a +row/column that exceeds the boundaries of the display results in +undefined behavior. Cursor coordinates are 0 based (0,0 is the upper +left corner of the display). + +### Function 0x46 -- Video Set Character Attribute (VDASAT) + +| _Entry Parameters_ +| B: 0x46 +| C: Video Device Unit ID +| E: Character Attribute Code + +| _Exit Results_ +| A: Status (0=OK, else error) + +Assign the specified character attribute code to be used for all +subsequent character writes/fills. This attribute is used to fill new +lines generated by scroll operations. Refer to the character attribute +for a list of the available attribute codes. Note that a given video +display may or may not support any/all attributes. + +### Function 0x47 -- Video Set Character Color (VDASCO) + +| _Entry Parameters_ +| B: 0x47 +| C: Video Device Unit ID +| E: Character Color Code + +| _Exit Results_ +| A: Status (0=OK, else error) + +Assign the specified color code to be used for all subsequent character +writes/fills. This color is also used to fill new lines generated by +scroll operations. Refer to color code table for a list of the available +color codes. Note that a given video display may or may not support +any/all colors. + +### Function 0x48 -- Video Set Write Character (VDAWRC) + +| _Entry Parameters_ +| B: 0x48 +| C: Video Device Unit ID +| E: Character + +| _Exit Results_ +| A: Status (0=OK, else error) + +Write the character specified in E. The character is written starting at +the current cursor position and the cursor is advanced. If the end of +the line is encountered, the cursor will be advanced to the start of the +next line. The display will **not** scroll if the end of the screen is +exceeded. + +### Function 0x49 -- Video Fill (VDAFIL) + +| _Entry Parameters_ +| B: 0x49 +| C: Video Device Unit ID +| E: Character +| HL: Count + +| _Exit Results_ +| A: Status (0=OK, else error) + +Write the character specified in E to the display the number of times +specified in HL. Characters are written starting at the current cursor +position and the cursor is advanced by the number of characters written. +If the end of the line is encountered, the characters will continue to +be written starting at the next line as needed. The display will **not** +scroll if the end of the screen is exceeded. + +### Function 0x4A -- Video Copy (VDACPY) + +| _Entry Parameters_ +| B: 0x4A +| C: Video Device Unit ID +| D: Source Row +| E: Source Column +| L: Count + +| _Exit Results_ +| A: Status (0=OK, else error) + +Copy count (L) bytes from the source row/column (DE) to current cursor +position. The cursor position is not updated. The maximum count is 255. +Copying to/from overlapping areas is not supported and will have an +undefined behavior. The display will **not** scroll if the end of the +screen is exceeded. Copying beyond the active screen buffer area is not +supported and results in undefined behavior. + +### Function 0x4B -- Video Scroll (VDASCR) + +| _Entry Parameters_ +| B: 0x4B +| C: Video Device Unit ID +| E: Scroll Distance (Line Count) + +| _Exit Results_ +| A: Status (0=OK, else error) + +Scroll the video display by the number of lines specified in E. If E +contains a negative number, then reverse scroll should be performed. + +### Function 0x4C -- Video Keyboard Status (VDAKST) + +| _Entry Parameters_ +| B: 0x4C +| C: Video Device Unit ID + +| _Exit Results_ +| A:Count of Key Codes in Keyboard Buffer + +Return a count of the number of key codes in the keyboard buffer. If it +is not possible to determine the actual number in the buffer, it is +acceptable to return 1 to indicate there are key codes available to read +and 0 if there are none available. + +### Function 0x4D -- Video Keyboard Flush (VDAKFL) + +| _Entry Parameters_ +| B: 0x4D +| C: Video Device Unit ID + +| _Exit Results_ +| A: Status (0=OK, else error) + +If a keyboard buffer is in use, it should be purged and all contents +discarded. + +### Function 0x4E -- Video Keyboard Read (VDAKRD) + +| _Entry Parameters_ +| B: 0x4E +| C: Video Device Unit ID + +| _Exit Results_ +| A: Status (0=OK, else error) +| C: Scancode +| D: Keystate +| E: Keycode + +Read next key code from keyboard. If a keyboard buffer is used, return +the next key code in the buffer. If no key codes are available, wait for +a keypress and return the keycode. + +The scancode value is the raw scancode from the keyboard for the +keypress. Scancodes are from scancode set 2 standard. + +The keystate is a bitmap representing the value of all modifier keys and +shift states as they existed at the time of the keystroke. The bitmap is +defined as: + +Bit | Keystate Indication +--- | -------------------------------- +7 | Key pressed was from the num pad +6 | Caps Lock was active +5 | Num Lock was active +4 | Scroll Lock was active +3 | Windows key was held down +2 | Alt key was held down +1 | Control key was held down +0 | Shift key was held down + +Keycodes are generally returned as appropriate ASCII values, if +possible. Special keys, like function keys, are returned as reserved +codes as described at the start of this section. + +System (SYS) +------------ + +### Function 0xF0 -- System Reset (SYSRESET) + +| _Entry Parameters_ +| B: 0xF0 + +| _Exit Results_ +| A: Status (0=OK, else error) + +Perform a soft reset of HBIOS. Releases all HBIOS memory allocated by +current OS. Does not reinitialize physical devices. + +### Function 0xF1 -- System Version (SYSVER) + +| _Entry Parameters_ +| B: 0xF1 +| C: Reserved (set to 0) + +| _Exit Results_ +| A: Status (0=OK, else error) +| DE: Version (Maj/Min/Upd/Pat) +| L: Platform ID + +This function will return the HBIOS version number. The version number +is returned in DE. High nibble of D is the major version, low nibble of +D is the minor version, high nibble of E is the patch number, and low +nibble of E is the build number. + +The hardware platform is identified in L: + +Id | Platform +-- | --------------------------------------------------- +1 | SBC V1 or V2 +2 | ZETA +3 | ZETA 2 +4 | N8 +5 | MK4 +6 | UNA +7 | RC2014 w/ Z80 +8 | RC2014 w/ Z180 + +### Function 0xF2 -- System Set Bank (SYSSETBNK) + +| _Entry Parameters_ +| B: 0xF2 +| C: Bank ID + +| _Exit Results_ +| A: Status (0=OK, else error) +| C: Previously Active Bank ID + +Activates the Bank ID specified in C and returns the previously active +Bank ID in C. The caller MUST be invoked from code located in the upper +32K and the stack **must** be in the upper 32K. + +### Function 0xF3 -- System Get Bank (SYSGETBNK) + +| _Entry Parameters_ +| B: 0xF3 + +| _Exit Results_ +| A: Status (0=OK, else error) +| C: Active Bank ID + +Returns the currently active Bank ID in C. + +### Function 0xF4 -- System Set Copy (SYSSETCPY) + +| _Entry Parameters_ +| B: 0xF4 +| D: Destination Bank ID +| E: Source Bank ID +| HL: Count of Bytes to Copy + +| _Exit Results_ +| A: Status (0=OK, else error) + +Prepare for a subsequent interbank memory copy (SYSBNKCPY) function by +setting the source bank, destination bank, and byte count for the copy. +The bank id's are not range checked and must be valid for the system in +use. + +No bytes are copied by this function. The SYSBNKCPY must be called to +actually perform the copy. The values setup by this function will remain +unchanged until another call is make to this function. So, after calling +SYSSETCPY, you may make multiple calls to SYSBNKCPY as long as you want +to continue to copy between the already established Source/Destination +Banks and the same size copy if being performed. + +### Function 0xF5 -- System Bank Copy (SYSBNKCPY) + +| _Entry Parameters_ +| B: 0xF5 +| DE: Destination Address +| HL: Source Address + +| _Exit Results_ +| A: Status (0=OK, else error) + +Copy memory between banks. The source bank, destination bank, and byte +count to copy MUST be established with a prior call to SYSSETCPY. +However, it is not necessary to call SYSSETCPY prior to subsequent calls +to SYSBNKCPY if the source/destination banks and copy length do not +change. + +WARNINGS: + +* This function is inherently dangerous and does not prevent you from + corrupting critical areas of memory. Use with **extreme** caution. + +* Overlapping source and destination memory ranges are not supported and + will result in undetermined behavior. + +* Copying of byte ranges that cross bank boundaries is undefined. + +### Function 0xF6 -- System Alloc (SYSALLOC) + +| _Entry Parameters_ +| B: 0xF6 +| HL: Size in Bytes + +| _Exit Results_ +| A: Status (0=OK, else error) +| HL: Address of Allocated Memory + +This function will attempt to allocate a block of memory of HL bytes +from the internal HBIOS heap. The HBIOS heap resides in the HBIOS bank +in the area of memory left unused by HBIOS. If the allocation is +successful, the address of the allocated memory block is returned in HL. +You will typically want to use the SYSBNKCPY function to read/write the +allocated memory. + +### Function 0xF7 -- System Free (SYSFREE) + +| _Entry Parameters_ +| B: 0xF7 +| HL: Address of Memory Block to Free + +| _Returned Values_ +| A: Status (0=OK, else error) + +\*\*\* This function is not yet implemented \*\*\* + +### Function 0xF8 -- System Get (SYSGET) + +| _Entry Parameters_ +| B: 0xF8 +| C: Subfunction (see below) + +| _Returned Values_ +| A: Status (0=OK, else error) + +This function will report various system information based on the +sub-function value. The following lists the subfunctions +available along with the registers/information returned. + +#### SYSGET Subfunction 0x00 -- Get Serial Device Unit Count (CIOCNT) + +| _Entry Parameters_ +| BC: 0xF800 + +| _Returned Values_ +| A: Status (0=OK, else error) +| E: Count of Serial Device Units + +#### SYSGET Subfunction 0x10 -- Get Disk Device Unit Count (DIOCNT) + +| _Entry Parameters_ +| BC: 0xF810 + +| _Returned Values_ +| A: Status (0=OK, else error) +| E: Count of Disk Device Units + +#### SYSGET Subfunction 0x40 -- Get Video Device Unit Count (VDACNT) + +| _Entry Parameters_ +| BC: 0xF840 + +| _Returned Values_ +| A: Status (0=OK, else error) +| E: Count of Video Device Units + +#### SYSGET Subfunction 0xD0 -- Get Timer Tick Count (TIMER) + +| _Entry Parameters_ +| BC: 0xF8D0 + +| _Returned Values_ +| A: Status (0=OK, else error) +| DE:HL: Current Timer Tick Count Value + +#### SYSGET Subfunction 0xD1 -- Get Seconds Count (SECONDS) + +| _Entry Parameters_ +| BC: 0xF8D1 + +| _Returned Values_ +| A: Status (0=OK, else error) +| DE:HL: Current Seconds Count Value +| C: Ticks within Second Value + +#### SYSGET Subfunction 0xE0 -- Get Boot Information (BOOTINFO) + +| _Entry Parameters_ +| BC: 0xF8E0 + +| _Returned Values_ +| A: Status (0=OK, else error) +| L: Boot Bank ID +| D: Boot Disk Device Unit ID +| E: Boot Disk Slice + +#### SYSGET Subfunction 0xF0 -- Get CPU Information (CPUINFO) + +| _Entry Parameters_ +| BC: 0xF8F0 + +| _Returned Values_ +| A: Status (0=OK, else error) +| H: Z80 CPU Variant +| L: CPU Speed in MHz +| DE: CPU Speed in KHz + +#### SYSGET Subfunction 0xF1 -- Get Memory Information (MEMINFO) + +| _Entry Parameters_ +| BC: 0xF8F1 + +| _Returned Values_ +| A: Status (0=OK, else error) +| D: Count of 32K ROM Banks +| E: Count of 32K RAM Banks + +#### SYSGET Subfunction 0xF2 -- Get Bank Information (BNKINFO) + +| _Entry Parameters_ +| BC: 0xF8F2 + +| _Returned Values_ +| A: Status (0=OK, else error) +| D: BIOS Bank ID +| E: User Bank ID + +### Function 0xF9 -- System Set (SYSSET) + +| _Entry Parameters_ +| B: 0xF9 +| C: Subfunction (see below) + +| _Returned Values_ +| A: Status (0=OK, else error) + +This function will set various system parameters based on the +sub-function value. The following lists the subfunctions +available along with the registers/information used as input. + +#### SYSSET Subfunction 0xD0 -- Set Timer Tick Count (TIMER) + +| _Entry Parameters_ +| BC: 0xF9D0 +| DE:HL: Timer Tick Count Value + +| _Returned Values_ +| A: Status (0=OK, else error) + + +#### SYSSET Subfunction 0xD1 -- Set Seconds Count (SECONDS) + +| _Entry Parameters_ +| BC: 0xF9D1 +| DE:HL: Seconds Count Value + +| _Returned Values_ +| A: Status (0=OK, else error) + + +#### SYSSET Subfunction 0xE0 -- Set Boot Information (BOOTINFO) + +| _Entry Parameters_ +| BC: 0xF9E0 +| L: Boot Bank ID +| D: Boot Disk Device Unit ID +| E: Boot Disk Slice + +| _Returned Values_ +| A: Status (0=OK, else error) + +### Function 0xFA -- System Peek (SYSPEEK) + +| _Entry Parameters_ +| B: 0xFA +| D: Bank ID +| HL: Memory Address + +| _Returned Values_ +| A: Status (0=OK, else error) +| E: Byte Value + +This function gets a single byte value at the specified bank/address. +The bank specified is not range checked. + +### Function 0xFB -- System Poke (SYSPOKE) + +| _Entry Parameters_ +| B: 0xFB +| D: Bank ID +| E: Value +| HL: Memory Address + +| _Returned Values_ +| A: Status (0=OK, else error) + +This function sets a single byte value at the specified bank/address. +The bank specified is not range checked. + +### Function 0xFC -- System Interrupt Management (SYSINT) + +| _Entry Parameters_ +| B: 0xFC +| C: Subfunction (see below) + +| _Returned Values_ +| A: Status (0=OK, else error) + +This function allows the caller to query information about the interrupt configuration of +the running system and allows adding or hooking interrupt handlers dynamically. Register C +is used to specify a subfunction. Additional input and output registers may be used as +defined by the sub-function. + +Note that during interrupt processing, the lower 32K of CPU address space will contain the +RomWBW HBIOS code bank, not the lower 32K of application TPA. As such, a dynamically +installed interrupt handler does not have access to the lower 32K of TPA and must be +careful to avoid modifying the contents of the lower 32K of memory. Invoking RomWBW HBIOS +functions within an interrupt handler is not supported. + +Interrupt handlers are different for IM1 or IM2. + +For IM1: + +> The new interrupt handler is responsible for chaining (JP) to the previous vector if the + interrupt is not handled. If the interrupt is handled, the new handler may simply return + (RET). When chaining to the previous interrupt handler, ZF must be set if interrupt is + handled and ZF cleared if not handled. The interrupt management framework takes care of + saving and restoring AF, BC, DE, HL, and IY. Any other registers modified must be saved + and restored by the interrupt handler. + +For IM2: + +> The new interrupt handler may either replace or hook the previous interrupt handler. To + replace the previous interrupt handler, the new handler just returns (RET) when done. To + hook the previous handler, the new handler can chain (JP) to the previous vector. Note + that initially all IM2 interrupt vectors are set to be handled as “BAD” meaning that the + interrupt is unexpected. In most cases, you do not want to chain to the previous vector + because it will cause the interrupt to display a “BAD INT” system panic message. + + The interrupt framework will take care of issuing an EI and RETI instruction. Do not put + these instructions in your new handler. Additionally, interrupt management framework takes care of saving and restoring AF, BC, DE, HL, and IY. Any other registers modified must be saved and restored by the interrupt handler. + + +If the caller is transient, then the caller must remove the new interrupt handler and +restore the original one prior to termination. This is accomplished by calling this +function with the Interrupt Vector set to the Previous Vector returned in the original call. + +The caller is responsible for disabling interrupts prior to making an INTSET call and +enabling them afterwards. The caller is responsible for ensuring that a valid interrupt +handler is installed prior to enabling any hardware interrupts associated with the handler. +Also, if the handler is transient, the caller must disable the hardware interrupt(s) +associated with the handler prior to uninstalling it. + +#### SYSINT Subfunction 0x00 -- Interrupt Info (INTINF) + +| _Entry Parameters_ +| BC: 0xFC00 + +| _Returned Values_ +| A: Status (0=OK, else error) +| D: Interrupt Mode +| E: Size (# entries) of Interrupt Vector Table + +Return interrupt mode in D and size of interrupt vector table in E. For +IM1, the size of the table is the number of vectors chained together. +For IM2, the size of the table is the number of slots in the vector +table. + +#### SYSINT Subfunction 0x10) -- Get Interrupt (INTGET) + +| _Entry Parameters_ +| BC: 0xFC10 +| E: Interrupt Vector Table Index + +| _Returned Values_ +| A: Status (0=OK, else error) +| HL: Current Interrupt Vector Address + +On entry, register E must contain an index into the interrupt vector +table. On return, HL will contain the address of the current interrupt +vector at the specified index. + +#### SYSINT Subfunction 0x20) -- Set Interrupt (INTSET) + +| _Entry Parameters_ +| BC: 0xFC20 +| E: Interrupt Vector Table Index +| HL: Interrupt Address to be Assigned + +| _Returned Values_ +| A: Status (0=OK, else error) +| HL: Previous Interrupt Vector Address +| DE: Interrupt Routing Engine Address (IM2) + +On entry, register E must contain an index into the interrupt vector table and register HL +must contain the address of the new interrupt vector to be inserted in the table at the +index. On return, HL will contain the previous address in the table at the index. diff --git a/Source/Doc/Build.cmd b/Source/Doc/Build.cmd deleted file mode 100644 index 5a595d65..00000000 --- a/Source/Doc/Build.cmd +++ /dev/null @@ -1,6 +0,0 @@ -@echo off -setlocal - -setlocal & cd "ZCPR Manual" && call Build.cmd || exit /b 1 & endlocal -rem setlocal & cd "RomWBW User Guide" && call Build.cmd || exit /b 1 & endlocal -rem setlocal & cd "RomWBW System Guide" && call Build.cmd || exit /b 1 & endlocal \ No newline at end of file diff --git a/Source/Doc/Build.docx b/Source/Doc/Build.docx deleted file mode 100644 index 31c11c39..00000000 Binary files a/Source/Doc/Build.docx and /dev/null differ diff --git a/Source/Doc/Clean.cmd b/Source/Doc/Clean.cmd deleted file mode 100644 index 1c04ba1b..00000000 --- a/Source/Doc/Clean.cmd +++ /dev/null @@ -1,6 +0,0 @@ -@echo off -setlocal - -setlocal & cd ZCPR Manual && call Clean.cmd & endlocal -setlocal & cd RomWBW User Guide && call Clean.cmd & endlocal -setlocal & cd RomWBW System Guide && call Clean.cmd & endlocal diff --git a/Source/Doc/Common.inc b/Source/Doc/Common.inc new file mode 100644 index 00000000..e5f87bed --- /dev/null +++ b/Source/Doc/Common.inc @@ -0,0 +1,7 @@ +!def(ver)(2.9.2) +!def(date)(!mdate) +!def(product)(RomWBW) +!def(author)(Wayne Warthen) +!def(authmail)(wwarthen@gmail.com) +!def(orgname)(RetroBrew Computers Group) +!def(orgurl)(www.retrobrewcomputers.org) \ No newline at end of file diff --git a/Source/Doc/GettingStarted.md b/Source/Doc/GettingStarted.md new file mode 100644 index 00000000..6815ea60 --- /dev/null +++ b/Source/Doc/GettingStarted.md @@ -0,0 +1,552 @@ +!include(Common.inc) +!def(document)(Getting Started) +--- +title: | + | !product + | + | !document +author: !author (mailto:!authmail) +date: !date +institution: !orgname +documentclass: article +classoption: + - oneside +toc: true +papersize: letter +geometry: + - top=1in + - bottom=1in + - left=1in + - right=1in +# - showframe +linestretch: 1.25 +colorlinks: true +fontfamily: helvet +fontsize: 12pt +header-includes: + - | + ```{=latex} + \renewcommand*{\familydefault}{\sfdefault} + \setstretch{1.25} % for TOC + ``` +--- + +`\clearpage % new page after TOC`{=latex} + +# RomWBW + +## Z80/Z180 System Software + +| Version !ver +| !date + +!author() [!authmail](mailto:!authmail) + +### Download + + * [RomWBW Distribution Package](https://github.com/wwarthen/RomWBW/releases) + +### Related Pages + + * [RomWBW Architecture Document](https://www.retrobrewcomputers.org/lib/exe/fetch.php?media=software:firmwareos:romwbw:romwbw_architecture.pdf) + * [RomWBW Applications](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps) + * [RomWBW Errata](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:errata) + +# Overview + +RomWBW provides a complete software system for a wide variety of hobbyist Z80/Z180 CPU-based systems produced by these developer communities: + + * [RetroBrew Computers](https://www.retrobrewcomputers.org) + * [RC2014](https://rc2014.co.uk) + * [retro-comp](https://groups.google.com/forum/#!forum/retro-comp) + +General features include: + + * Banked memory services for several banking designs + * Disk drivers for RAM, ROM, Floppy, IDE, CF, and SD + * Serial drivers including UART (16550-like), ASCI, ACIA, SIO + * Video drivers including TMS9918, SY6545, MOS8563, HD6445 + * Real time clock drivers including DS1322, BQ4845 + * Multiple OS support including CP/M 2.2, ZSDOS, CP/M 3, ZPM3 + * Built-in VT-100 terminal emulation support + +RomWBW is distributed as both source code and pre-built ROM and disk images. Some of the provided software can be launched directly from the ROM firmware itself: + + * System monitor + * Operating systems (CP/M 2.2, ZSDOS) + * ROM BASIC (Nascom BASIC and Tasty BASIC) + * ROM Forth + +A dynamic disk drive letter assignment mechanism allows mapping operating system drive letters to any available disk media. Additionally, mass media devices (IDE Disk, CF Card, SD Card) support the use of multiple slices (up to 256 per device). Each slice contains a complete CP/M filesystem and can be mapped independently to any drive letter. This overcomes the inherent size limitations in legacy OSes providing up to 2GB of accessible storage on a single device. + +The pre-built ROM firmware images are generally optimal for most users. However, it is also very easy to modify and build custom ROM images that fully tailor the firmware to your specific preferences. All tools required to build custom ROM firmware are included -- no need to install assemblers, etc. Any modern computer running Windows, Linux, or MacOS can be used. + +Multiple disk images are provided in the distribution. Most disk images contain a complete, bootable, ready-to-run implementation of a specific operating system. A "combo" disk image contains multiple slices, each with a full operating system implementation. If you use this disk image, you can easily pick whichever operating system you want to boot without changing media. + +# Installation + +The latest RomWBW distribution downloads are maintained on GitHub in the [RomWBW Repository](https://github.com/wwarthen/RomWBW). The fully-built distributions are found on the [releases page](https://github.com/wwarthen/RomWBW/releases) of the repository. On this page, you will probably see both pre-releases as well as normal releases. Unless you have a specific reason, I suggest you stick to the most recent normal release (not pre-release). Expand the "Assets" drop-down for the release you want to download, then select the asset named RomWBW-vX.X.X-Package.zip. The Package asset includes all pre-built ROM and Disk images as well as full source code. The other assets are Source Code only and do not have the pre-built ROM or disk images. + +The pre-built ROM images will automatically detect and support a reasonable range of devices including serial ports, video adapters, on-board disk interfaces, and PropIO/ParPortProp boards without building a custom ROM. The distribution is a .zip archive. After downloading it to a working directory on your modern computer (Windows/Linux/Mac) use any zip tool to extract the contents of the archive. + +In general, you will just program your system's ROM chip with the appropriate ROM image from the RomWBW distribution. Depending on how you got your system, you may have already been provided with a pre-programmed ROM chip. If so, use that initially. Otherwise, you will need to use a ROM programmer to initially program your ROM chip. Please refer to the documentation that came with your ROM programmer for more information. Once you have a running RomWBW system, you can generally update your ROM to a newer version in-situ with an included ROM Flashing tool (Will Sowerbutts' FLASH application) as described in the Upgrading section below. + +Looking at the extracted distribution archive, You will see that the distribution is broken up into a few sub-directories. The Binary directory contains the pre-built ROM and disk images. The ROM image files all end in ".rom". Based on the table below, **carefully** pick the appropriate ROM image: + +| Platform | ROM Image File | Baud | Description | +| --------------| --------------------- | --------: | ------------------------------------------------ | +| SBC V1/V2 | SBC_std.rom | 38400 | RetroBrew SBC v1 or v2 ECB Z80 | +| Zeta V1 | ZETA_std.rom | 38400 | RetroBrew Zeta V1 Z80, ParPortProp (optional) | +| Zeta V2 | ZETA2_std.rom | 38400 | RetroBrew Zeta V2 Z80, ParPortProp (optional) | +| N8 | N8_std.rom | 38400 | RetroBrew N8 Z180, date code >= 2312 | +| Mark IV | MK4_std.rom | 38400 | RetroBrew Mark IV ECB Z180 | +| RC2014 Z80 | RCZ80_std.rom | 115200 | RC2014 w/ Z80 CPU, requires 512K RAM/ROM module | +| RC2014 Z180\* | RCZ180_ext.rom | 115200 | RC2014 w/ Z180 CPU & 512K banked RAM/ROM module | +| RC2014 Z180\* | RCZ180_nat.rom | 115200 | RC2014 w/ Z180 CPU & 512K native RAM/ROM module | +| Easy Z80 | EZZ80_std.rom | 115200 | Sergey Kiselev's Easy Z80 | +| SC126 | SCZ180_126.rom | 115200 | Stephen Cousin's SC126 Z180 | +| SC130 | SCZ180_130.rom | 115200 | Stephen Cousin's SC130 Z180 | +| SC131 | SCZ180_131.rom | 115200 | Stephen Cousin's SC131 Z180 | +| Dyno | DYNO_std.rom | 38400 | Steve Garcia's Z180 Dyno Computer | + +\*The RC2014 Z180 requires a separate RAM/ROM memory module. There are two types of these modules and you must pick the ROM for your type of memory module. The "ext" ROM supports Spencer's official 512K RAM/ROM banked memory module. The "nat" ROM supports any of the third-party Z180 native memory modules. + +RomWBW will automatically attempt to detect and support typical add-on components for each of the systems supported. More information on the required system configuration and optional supported components for each ROM is found in the file called "RomList.txt" in the Binary directory. All pre-built ROM images are simple 512KB binary images. If your system utilizes a larger ROM chip, you can just program the image into the first 512KB of the ROM. + +Connect a serial terminal or computer with terminal emulation software to the primary serial port of your CPU board. You may need to refer to your hardware provider's documentation for details. A null-modem connection may be required. Set the baud rate as indicated in the table above. Set the line characteristics to 8 data bits, 1 stop bit, no parity, and no flow control. If possible, select VT-100 terminal emulation. + +Upon power-up, your terminal should display a sign-on banner within 2 seconds followed by hardware inventory and discovery information. When hardware initialization is completed, a boot loader prompt allows you to choose a ROM-based operating system, system monitor, application, or boot from a disk device. + +Initially, you should try the ROM boot options. By selecting either CP/M 2.2 or Z-System, the operating system will be loaded from ROM and you will see the a `B>` disk prompt. In this scenario, A: will be an empty RAM disk and B: will refer to your ROM disk containing some typical applications. This provides a simple environment for learning to use your system. Be aware that files saved to the RAM disk (A:) will disappear at the next power on (RAM is generally not persistent). Also note that attempts to save files to the ROM disk (B:) will fail because ROM is not writable. + +# Upgrading + +Upgrading to a newer release of RomWBW is essentially just a matter of updating the ROM chip in your system. If you have spare ROM chips for your system and a ROM programmer, it is always safest to keep your existing, working ROM chip and program a new one with the new firmware. If the new one fails to boot, you can easily return to the known working ROM. + +Prior to attempting to reprogram your actual ROM chip, you may wish to "try" the upgrade. With RomWBW, you can upload a new system image and load it from the command line. For each ROM image file (.rom) in the Binary directory, you will also find a corresponding application file (.com). For example, for SBC_std.rom, there is also an SBC_std.com file. You can upload the .com file to your system using XModem, then simply run the .com file. You will see your system go through the normal startup process just like it was started from ROM. However, your ROM has not been updated and the next time you boot your system, it will revert to the system image contained in ROM. You may find that you are unable to load the .com file because it is too large to fit in available application RAM (TPA). Unfortunately, in this case, you will not be able to use the .com file mechanism to start your system. + +If you do not have easy access to a ROM programmer, it is usually possible to reprogram your system ROM using the FLASH utility from Will Sowerbutts. This application called FLASH.COM can be found on the ROM drive of any running system. In this case, you would need to transfer the new ROM image (.rom) over to your system using XModem (or one of the other mechanisms described in the Transferring Files section below). The ROM image will be too large to fit on your RAM drive, so you will need to transfer it to a larger storage drive. Once the ROM image is on your system, you can use the FLASH application to update your ROM. The following is a typical example of transferring ROM image using XModem and flashing the chip in-situ. + +``` +E>xm r rom.img + +XMODEM v12.5 - 07/13/86 +RBC, 28-Aug-2019 [WBW], ASCI + +Receiving: E0:ROM.IMG +7312k available for uploads +File open - ready to receive +To cancel: Ctrl-X, pause, Ctrl-X + +Thanks for the upload + +E>flash write rom.img +FLASH4 by Will Sowerbutts version 1.2.3 + +Using RomWBW (v2.6+) bank switching. +Flash memory chip ID is 0xBFB7: 39F040 +Flash memory has 128 sectors of 4096 bytes, total 512KB +Write complete: Reprogrammed 2/128 sectors. +Verify (128 sectors) complete: OK! +``` + +Obviously, there is some risk to this approach since any issues with the programming or ROM image could result in a non-functional system. + +To confirm your ROM chip has been successfully updated, restart your system and boot an operating system from ROM. Do not boot from a disk device yet. Review the boot messages to see if any issues have occurred. + +Once you are satisfied that the ROM is working well, you will need to update the system images and RomWBW custom applications on your disk drives. The system images and custom applications are matched to the RomWBW ROM firmware in use. If you attempt to boot a disk or run applications that have not been updated to match the current ROM firmware, you are likely to have odd problems. + +The simplest way to update your disk media is to just use your modern computer to overwrite the entire media with the latest disk image of your choice. This process is described below in the Disk Images section. If you wish to update existing disk media in your system, you need to perform the following steps. + +If the disk is bootable, you need to update the system tracks of the disk. This is done using a SYSCOPY command such as `SYSCOPY C:=B:ZSYS.SYS`. For a ZSDOS boot disk, use ZSYS.SYS. For a CP/M 2.2 disk, use CPM.SYS. For a CP/M 3 or ZPM3 disk, use CPMLDR.SYS. CPMLDR.SYS is not provided on the ROM disk, so you would need to upload it from the distribution. + +Finally, if you have copies of any of the RomWBW custom applications on your hard disk, you need to update them with the latest copies. The following applications are found on your ROM disk. Use COPY to copy them over any older versions of the app on your disk: + + * ASSIGN.COM + * FORMAT.COM + * OSLDR.COM + * SYSCOPY.COM + * TALK.COM + * FDU.COM (was FDTST.COM) + * XM.COM + * MODE.COM + * RTC.COM + * TIMER.COM + * INTTEST.COM + +For example: `B>COPY ASSIGN.COM C:` + +# Using Disks + +While the RAM/ROM disks provide a functional system, they are not useful in the long term because you cannot save data across power cycles. They are also constrained by limited space. + +The systems supported by RomWBW all have the ability to use persistent disk media. I am referring to all kinds of disk devices including floppy drives, hard disks, CF Cards, and SD Cards. Some systems have disk interfaces built-in, while others will require add-in cards. You will need to refer to the documentation for your system for your specific options. + +In the RomWBW bootup messages, you will see hardware discovery messages. If you have a disk drive interface, you should see messages listing device types like FD:, IDE:, PPIDE:, SD:. Additionally, you will see messages indicating the media that has been found on the interfaces. As an example, here are the messages you might see if you have an IDE interface in your system with a single CF Card inserted in the primary side of the interface: + +``` +IDE: IO=0x80 MODE=MK4 +IDE0: 8-BIT LBA BLOCKS=0x00773800 SIZE=3815MB +IDE1: NO MEDIA +``` + +The messages you see will vary depending on your hardware and the media you have installed. But, they will all have the same general format as the example above. + +Once your your system has working disk devices, you can boot an operating system and the operating system will have access to the media. At the boot loader prompt, select either either CP/M 2.2 or Z-System to boot from ROM. As the operating system starts up, you should see a list of drive letters assigned to the disk media you have installed. Here is an example of this: + +``` +Configuring Drives... + + A:=MD1:0 + B:=MD0:0 + C:=IDE0:0 + D:=IDE0:1 +``` + +You will probably see more drive letters than this. The drive letter assignment process is described in more detail later in this document. Be aware that RomWBW will only assign drive letters to disk interfaces that actually have media in them. If you do not see drive letters assigned as expected, refer to the prior system boot messages to ensure media has been detected in the interface. Actually, there is one exception to this rule: floppy drives will be assigned a drive letter regardless of whether there is any media inserted at boot. + +Notice how each drive letter refers back to a specific disk hardware interface like IDE0. This is important as it is telling you what each drive letter refers to. Also notice that mass storage disks (like IDE) will normally have multiple drive letters assigned. The extra drive letters refer to additional "slices" on the disk. The concept of slices is also explained later in this document. + +Once you are seeing drive letters referring to your disk media, you can follow the instructions below to begin using the disk media with the operating system. Your disk media **must** be initialized prior to being used. There are two ways to initialize your media for use. + +You can initialize the media in-place using your RomWBW system. This process is described below under Disk Initialization. In this scenario, you will need to subsequently copy any files you want to use onto the newly initialized disk (see Transferring Files). + +Alternatively, you can use your modern Windows, Linux, or Mac computer to copy a disk image onto the disk media. RomWBW comes with a variety of disk images that are ready to use and have a much more complete set of files than you will find on the ROM disk. This process is covered below under Disk Images. + +## Disk Initialization + +To use a disk device, you will need to initialize the directory of the filesystem. On RomWBW, the initialization is done using the CLRDIR application. For example if your C: drive has been assigned to a storage device, you would use `CLRDIR C:` to initialize C: and prepare it hold files. Note that CLRDIR will prompt you for confirmation and you must respond with a **capital** 'Y' to confirm. Once `CLDIR` has completed, you can copy files onto the drive, for example `COPY *.* C:`. Be very careful to pay attention to your drive letter assignments prior to running `CLRDIR` to avoid accidentally wiping out a filesystem that has data on it. + +Running `CLRDIR` on a disk device is roughly equivalent to running FORMAT on MS-DOS. Note that unlike MS-DOS you do **not** partition your mass storage device. CP/M knows nothing about disk partitions. You may notice a partitioning application on your ROM disk (FDISK80), but this is strictly for an advanced technique of adding an MS-DOS FAT filesystem to your media in addition to the CP/M area. Do not use FDISK80 unless you are specifically attempting to add an MS-DOS FAT filesystem to your media. + +If you are using a floppy drive, you will need to physically format your floppy disk prior to use. This is only required for floppy disks, not hard disk, CF Cards, or SD Cards, etc. To format a floppy drive, you can use the interactive application `FDU`. FDU is not terribly user friendly, but is generally documented in the file "FDU.txt" found in the Doc directory of the distribution. It is not necessary to run `CLRDIR` on a floppy disk after physically formatting it -- the directory is cleared as part of the formatting. + +Once you have initialized a disk device and copied your desired files onto it, you may want to make the disk bootable. On CP/M filesystems, you must perform one additional step to make a disk bootable. Specifically, you need to place a copy of the operating system on the system tracks of the disk. This is done using the `SYSCOPY` command. Let's say you have prepared drive C: by initializing it with `CLRDIR` and copied some files onto it. You can now make C: bootable by running the following command: + +`B>SYSCOPY C:=B:ZSYS.SYS` + +This command means: copy the Z-System operating system onto the system tracks of drive C:. In this example, it is assumed that you have booted from ROM, so B: is the ROM disk drive. Additionally, this example assumes you want the Z-System operating system to be booted from C:. If you want CP/M 2.2 instead, you would replace `B:ZSYS.SYS` with `B:CPM.SYS`. Here is a full example of this process. + +``` +B>SYSCOPY C:=B:ZSYS.SYS + +SYSCOPY v2.0 for RomWBW CP/M, 17-Feb-2020 (CP/M 2 Mode) +Copyright 2020, Wayne Warthen, GNU GPL v3 + +Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y +Reading image... Writing image... Done +``` + +Once this process succeeds, you will be able to boot directly to the disk from the boot loader prompt. See the instructions in Booting Disks for details on this. + +## Disk Images + +As mentioned previously, RomWBW includes a variety of disk images that contain a full set of applications for the operating systems supported. It is generally easier to use these disk images instead of copying all the files over using XModem. You use your modern computer (Windows, Linux, MacOS) to place the disk image onto the disk media, then just move the media over to your system. In this scenario you **do not** run `CLRDIR` or `SYSCOPY` on the drive(s). The directory is prepared and the disk is already bootable, if it is an operating system boot disk image. + +To copy the disk image files onto your actual media (floppy disk, CF Card, SD Card, etc.), you need to use an image writing utility on your modern computer. Your modern computer will need to have an appropriate interface or slot that accepts the media. To actually copy the image, you can use the `dd` command on Linux or MacOS. On Windows, in the "Tools" directory of the distribution there are two tools you can use. For floppy media, you can use RawWriteWin and for hard disk media, you can use Win32DiskImager. In all cases, the image file should be written to the media starting at the very first block or sector of the media. This will **destroy** any other data on the media. + +The disk image files are found in the Binary directory of the distribution. Floppy disk images are prefixed with "fd_" and hard disk images are prefixed with "hd_". The floppy images are specifically for 1.44M floppy media only. Each disk image has the complete set of normal applications and tools distributed with the associated operating system or application suite. + +The following table shows the disk image files available. Note that the images in the "Hard" column are fine for use on CF Cards, SD Cards, as well as real spinning hard disks. + +| Floppy | Hard | Description | +| --------------- | --------------- | -------------------------------------- | +| fd_cpm22.img | hd_cpm22.img | DRI CP/M 2.2 boot disk | +| fd_zsdos.img | hd_zsdos.img | ZSDOS 1.1 boot disk | +| fd_nzcom.img | hd_nzcom.img | NZCOM boot disk | +| fd_cpm3 | hd_cpm3.img | DRI CP/M 3 boot disk | +| fd_zpm3 | hd_zpm3.img | ZPM3 boot disk | +| fd_ws4 | hd_ws4.img | WordStar v4 application disk | + +In addition to the disk images above, there is also a special hard disk image called hd_combo.img. This image contains all of the images above, but in a single image with 6 slices (see below for information on disk slices). At the boot loader prompt, you can choose a disk with the combo image, then select the specific slice you want. This allows a single disk to have all of the possible operating system options. + +This is the layout of the hd_combo disk image: + +| Slice | Description | +| ------- | ---------------------------------------------------------------- | +| Slice 0 | DRI CP/M 2.2 boot disk | +| Slice 1 | ZSDOS 1.1 boot disk | +| Slice 2 | NZCOM boot disk | +| Slice 3 | DRI CP/M 3 boot disk | +| Slice 4 | ZPM3 boot disk | +| Slice 5 | WordStar v4 application disk | + +Note that unlike the ROM firmware, you do **not** need to choose a disk image specific to your hardware. Because the RomWBW firmware provides a hardware abstraction layer, all hard disk images will work on all hardware variations. Yes, this means you can remove an SD Card from one system and put it in a different system. The only constraint is that the applications on the disk media must be up to date with the firmware on the system being used. + +All of the disk images that indicate they are bootable (boot disk) will boot from disk as is. You do not need to run `SYSCOPY` on them to make them bootable. However, if you upgrade your ROM, you should use `SYSCOPY` to update the system tracks. + +## Booting Disks + +When starting your system, following the hardware initialization, you will see the Boot Loader prompt. In addition, to the ROM boot options, you will see another line listing the Disk boot options. This line lists the disk devices that you can choose to boot directly. + +You will notice that you do not have an option to boot a drive letter here (like C:). This is because the operating system is not yet loaded. When you ran `SYSCOPY` previously, remember that C: was assigned to IDE0:0 which means device IDE0, slice 0. So, to boot the disk that you just setup with `SYSCOPY`, you would choose option 1. You will then be prompted for the slice on IDE0 that you want to boot. For now, just press enter to choose slice 0. Once you are familiar with slices, you can `SYSCOPY` and boot alternate slices. Here is what you would see when booting to a disk device: + +``` +MARK IV Boot Loader + +ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM +Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1 + +Boot Selection? 2 Slice(0-9)[0]? + +Booting Disk Unit 2, Slice 0... + +Reading disk information... +Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive + +Loading... +``` + +Following this, you would see the normal operating system startup messages. However, your operating system prompt will be `A>` and when you look at the drive letter assignments, you should see that A: has been assigned to the disk you selected to boot. + +If you receive the error message "Disk not bootable!", you have either failed to properly run `SYSCOPY` on the target disk or you have selected the wrong disk/slice. + +Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed in the Disk boot line, they are not "bootable" disks because they have no system tracks on them. Attempting to boot to one of them, will fail with a "Disk not bootable!" error message and return to the loader prompt. + +# General Usage + +Each of the operating systems and ROM applications included with RomWBW are sophisticated tools in their own right. It is not reasonable to document their usage here. However, you will find complete manuals in PDF format in the Doc directory of the distribution. The intention of this section is to document the RomWBW specific enhancements to these operating systems. + +## ROM Disk + +In addition to the ROM-based operating systems and applications, the ROM also contains a ROM disk with a small CP/M filesystem. The contents of the ROM disk have been chosen to provide a core set of tools and applications that are helpful for either CP/M 2.2 or ZSDOS. Since ZSDOS is CP/M 2.2 compatible, this works fairly well. However, you will find some files on the ROM disk that will work with ZSDOS, but will not work on CP/M 2.2. For example, `LDDS`, which loads the ZSDOS date/time stamper will only run on ZSDOS. + +## Drive Letter Assignment + +In legacy CP/M-type operating systems, drive letters were generally mapped to disk drives in a completely fixed way. For example, drive A: would **always** refer to the first floppy drive. Since RomWBW supports a wide variety of hardware configurations, it implements a much more flexible drive letter assignment mechanism so that any drive letter can be assigned to any disk device. + +At boot, you will notice that RomWBW automatically assigns drive letters to the available disk devices. These assignments are displayed during the startup of the selected operating system. Additionally, you can review the current drive assignments at any time using the `ASSIGN` command. CP/M 3 and ZPM3 do not automatically display the assignments at startup, but you can use `ASSIGN` do display them. + +The drive letter assignments **do not** change during an OS session unless you use the `ASSIGN` command yourself to do it. Additionally, the assignments at boot will stay the same on each boot as long as you do not make changes to your hardware configuration. Note that the assignments **are** dependent on the media currently inserted in hard disk drives. So, notice that if you insert or remove an SD Card or CF Card, the drive assignments will change. Since drive letter assignments can change, you must be careful when doing destructive things like using `CLRDIR` to make sure the drive letter you use is referring to the desired media. + +When performing a ROM boot of an operating system, note that A: will be your RAM disk and B: will be your ROM disk. When performing a disk boot, the disk you are booting from will be assigned to A: and the rest of the drive letters will be offset to accommodate this. This is done because most legacy operating systems expect that A: will be the boot drive. + +## Slices + +The vintage operating systems included with RomWBW were produced at a time when mass storage devices were quite small. CP/M 2.2 could only handle filesystems up to 8MB. In order to achieve compatibility across all of the operating systems supported by RomWBW, the hard disk filesystem format used is 8MB. This ensures any filesystem will be accessible to any of the operating systems. + +Since storage devices today are quite large, RomWBW implements a mechanism called slicing to allow up to 256 8MB filesystems on a single large storage device. This allows up to 2GB of useable space on a single media. You can think of slices as a way to refer to any of the first 256 8MB chunks of space on a single media. + +Of course, the problem is that CP/M-like operating systems have only 16 drive letters (A:-P:) available. Under the covers, RomWBW allows you to use any drive letter to refer to any slice of any media. The `ASSIGN` command is provided to allow you to view or change the drive letter mappings at any time. At startup, the operating system will automatically allocate a reasonable number of drive letters to the available storage devices. The allocation will depend on the number of large storage devices available at boot. For example, if you have only one hard disk type media, you will see that 8 drive letters are assigned to the first 8 slices of that media. If you have two large storage devices, you will see that each device is allocated four drive letters. + +Referring to slices within a storage device is done by appending a :n where n is the device relative slice number from 0-255. For example, if you have an IDE device, it will show up as IDE0: in the boot messages meaning the first IDE device. To refer to the fourth slice of IDE0, you would type "IDE0:3". So, if I wanted to use drive letter L: to refer to the fourth slice of IDE0, I could use the command `ASSIGN L:=IDE0:3`. + +There are a couple of rules to be aware of when assigning drive letters. First, you may only refer to a specific device/slice with one drive letter. Said another way, you cannot have multiple drive letters referring to a single device/slice at the same time. Second, there must always be a drive assigned to A:. Any attempt to violate these rules will be blocked by the `ASSIGN` command. + +Unlike MS-DOS partitions, slices are not allocated -- there is no partitioning of slices. Think of every hard disk type device as having a pre-allocated set of 256 8MB slices at the start of the media. You can refer to any of them simply by assigning a drive letter. RomWBW will not check to see if there is anything else on the hard disk in the slice you are referring to, nor will it verify that the hard disk media is large enough to have a slice at the location you refer to. If you attempt to write past the end of your media, you will get an I/O error displayed, so you will know if you make a mistake. There is no tracking of your use of slices -- you will need to keep track of your use of slices yourself. + +Nothing automatically initializes a slice as a file system. You must do that yourself using `CLRDIR`. Since `CLRDIR` works on drive letters, make absolutely sure you know what media and slice are assigned to that drive letter before using `CLRDIR`. + +While it is probably obvious, you cannot use slices on any media less than 8MB in size. Specifically, you cannot slice RAM disks, ROM disks, floppy disks, etc. + +# Inbuilt ROM Applications + +In addition to CP/M 2.2 and Z-System, there are several ROM applications that can be launched directly from ROM. These applications are not hosted by an operating system and so they are unable to save files to disk devices. + +The following ROM applications are available at the boot loader prompt: + +| Application | | +| ----------- | -------------------------------------------------------------- | +| Monitor | Z80 system debug monitor w/ Intel Hex loader | +| Forth | Brad Rodriguez's ANSI compatible Forth language | +| Basic | Nascom 8K BASIC language | +| Tasty BASIC | Dimitri Theuling's Tiny BASIC implementation | +| Play | A simple video game (requires ANSI terminal emulation) | + +In general, the command to exit these applications and restart the system is `BYE`. The exceptions are the Monitor which uses `B` and Play which uses `Q`. + +Space is available in the ROM image for the inclusion of other software. Any inbuilt application can be set up to launch automatically at startup. + +# RomWBW Custom Applications + +The operation of the RomWBW hosted operating systems is enhanced through several custom applications. These applications are functional on all of the OS variants included with RomWBW. + +The following custom applications are found on the ROM disk and are, therefore, globally available. + +| Application | Description | +| ----------- | -------------------------------------------------------------- | +| ASSIGN | Add, change, and delete drive letter assignments. Use ASSIGN /? for usage instructions. | +| SYSCOPY | Copy system image to a device to make it bootable. Use SYSCOPY with no parms for usage instructions. | +| FDU | Format and test floppy disks. Menu driven interface. | +| OSLDR | Load a new OS on the fly. For example, you can switch to Z-System when running CP/M. Use OSLDR with no parms for usage instructions. | +| FORMAT | Will someday be a command line tool to format floppy disks. Currently does nothing! | +| MODE | Reconfigures serial ports dynamically. | +| XM | XModem file transfer program adapted to hardware. Automatically uses primary serial port on system. | +| FDISK80 | John Coffman's Z80 hard disk partitioning tool. See documentation in Doc directory. | +| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). | +| FLASH | Will Sowerbutts' in-situ ROM programming utility. | +| CLRDIR | Initialize the directory area of a CP/M disk (Max Scane). | + +Some custom applications do not fit on the ROM disk. They are found on the disk image files or the individual files can be found in the Binary\\Apps directory of the distribution. + +| Application | Description | +| ----------- | -------------------------------------------------------------- | +| TUNE | Play .PT2, .PT3, .MYM audio files. | +| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). | + +There is additional documentation on some of these applications at the [RomWBW Applications Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps). + +# Operating Systems + +One of the primary goals of RomWBW is to expose a set of generic hardware functions that make it easy to adapt operating systems to any hardware supported by RomWBW. As a result, there are now 5 operating systems that have been adapted to run under RomWBW. The adaptations are identical for all hardware supported by RomWBW because RomWBW hides all hardware specifics from the operating system. + +Note that all of the operating systems included with RomWBW support the same basic filesystem format. As a result, a formatted filesystem will be accessible to any operating system. The only possible issue is that if you turn on date/time stamping using the newer OSes, the older OSes will not understand this. Files will not be corrupted, but the date/time stamps may be lost. + +The following sections briefly describe the operating system options currently available. + +## Digital Research CP/M 2.2 + +This is the most widely used variant of the Digital Research operating system. It has the most basic feature set, but is essentially the compatibility metric for all other CP/M-like operating systems including all of those listed below. The Doc directory contains a manual for CP/M usage ("CPM Manual.pdf"). If you are new to the CP/M world, I would recommend using this CP/M variant to start with simply because it is the most stable and you are less likely to encounter problems. + +## ZSDOS 1.1 + +ZSDOS is the most popular non-DRI CP/M "clone" which is generally referred to as Z-System. Z-System is intended to be an enhanced version of CP/M and should run all CP/M 2.2 applications. It is optimized for the Z80 CPU (as opposed to 8080 for CP/M) and has some significant improvements such as date/time stamping of files. For further information on the RomWBW implementation of Z-System, see the wiki page [Z-System Notes](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:zsystem). Additionally, the official documentation for Z-System is included in the RomWBW distribution Doc directory ("ZSDOS Manual.pdf" and "ZCPR Manual.pdf"). + +## NZCOM Automatic Z-System + +NZCOM is a much further refined version of Z-System (ZCPR 3.4). NZCOM was sold as an enhancement for existing users of CP/M 2.2 or ZSDOS. For this reason, (by design) NZCOM does not provide a way to boot directly from disk. Rather, it is loaded after the system boots into a host OS. On the RomWBW NZCOM disk images, the boot OS is ZSDOS 1.1. + +To use, NZCOM, you must run through a simple configuration process. This is well documented in the NZCOM manual in the "NZCOM Users Manual.pdf" file in the RomWBW Doc directory. Additionally, there are instructions for automatically launching NZCOM when the disk is booted under the host OS via an auto command submission process. + +## Digital Research CP/M 3 + +This is the Digital Research follow-up product to their very popular CP/M 2.2 operating system. While highly compatible with CP/M 2.2, it features many enhancements. It makes direct use of banked memory to increase the user program space (TPA). It also has a new suite of support tools and help system. + +Note that to make a CP/M 3 boot disk, you actually place CPMLDR.SYS on the system tracks of the disk. You do not place CPM3.SYS on the system tracks. + +## Simeon Cran's ZPM3 + +ZPM3 is an interesting combination of the features of both CP/M 3 and ZCPR 3. Essentially, it has the features of and compatibility with both. + +Like CP/M 3, to make ZPM3 boot disk, you put CPMLDR.SYS on the system tracks of the disk. + +## FreeRTOS + +Note that Phillip Stevens has also ported FreeRTOS to run under RomWBW. FreeRTOS is not provided in the RomWBW distribution. You can contact Phillip for availability. + +# Transferring Files + +Transferring files between your modern computer and your RomWBW system can be achieved in a variety of ways. The most common of these are described below. All of these have a certain degree of complexity and I encourage new users to use the available community forums to seek assistance as needed. + +## Serial Port Transfers + +RomWBW provides an serial file transfer program called XModem that has been adapted to run under RomWBW hardware. The program is called `XM` and is on your ROM disk as well as all of the pre-built disk images. + +You can type `XM` by itself to get usage information. In general, you will run `XM` with parameters to indicate you want to send or receive a file on your RomWBW system. Then, you will use your modern computers terminal program to complete the process. + +The `XM` application generally tries to detect the hardware you are using and adapt to it. However, you must ensure that you have a reliable serial connection. You must also ensure that the speed of the connection is not too fast for XModem to service. Alternatively, you can ensure that hardware flow control is working properly. + +There is an odd interaction between XModem and partner terminal programs that can occur. Essentially, after launching `XM`, you must start the protocol on your modern computer fairly quickly (usually in about 20 seconds or so). So, if you do not pick a file on your modern computer quickly enough, you will find that the transfer completes about 16K, then hangs. The interaction that causes this is beyond the scope of this document. + +## Disk Image Transfers + +It is possible to pass disk images between your RomWBW system and your modern computer. This assumes you have an appropriate media slot on your modern computer for the media you want to use (CF Card, SD Card, or floppy drive). + +The general process to get files from your modern computer to a RomWBW computer is: + +1. Use `cpmtools` on your modern computer to create a RomWBW CP/M filesystem image. +2. Insert your RomWBW media (CF Card, SD Card, or floppy disk) in your modern computer. +3. Use a disk imaging tool to copy the RomWBW filesystem image onto the media. +4. Move the media back to the RomWBW computer. + +This process is a little complicated, but it has the benefit of allowing you to get a lot of files over to your RomWBW system quickly and with little chance of corruption. + +The process can be run in reverse to get files from your RomWBW computer to a modern computer. + +The exact use of these tools is a bit too much for this document, but the tools are all included in the RomWBW distribution along with usage documents. + +Note that the build scripts for RomWBW create the default disk images supplied with RomWBW. It is relatively easy to customize the contents of the disk images that are part of RomWBW. This is described in more detail in the Source\\Images directory of the distribution. + +## FAT Filesystem Transfers + +RomWBW provides a mechanism that allows it to read and write files on a FAT formatted disk. This means that you can generally use your modern computer to make an SD Card or CF Card with a standard FAT32 filesystem on it, then place that media in your RomWBW computer and access the files. + +When formatting the media on your modern computer, but sure to pick the FAT filesystem. NTFS and other filesystems will not work. + +On your RomWBW computer you can use the `FAT` application to access the FAT media. The `FAT` application allows you to read files, write files, list a directory, and erase files on the FAT media. It can handle subdirectories as well. It will only see 8.3 character filenames however. Longer filenames will show up as a truncated version. + +The `FAT` application is not on your ROM disk because it is too large to fit. You will find it on all of the pre-built disk images as well as in the Binary\\Apps directory of the distribution. + +For advanced users, it is possible to create a hybrid disk that contains CP/M slices at the beginning and a FAT filesystem after. Such a hybrid disk can be used to boot an operating system and still have access to FAT files on the FAT portion of the disk. David Reese has prepared a document describing how to do this. It is called "SC126_How-To_No_2_Preparing_an_SD_Card_for_Use_with_SC126_Rev_1-5.pdf" and can be found in the Doc\\Contrib directory of the distribution. + +# Startup Command Processing + +Each of the operating systems supported by RomWBW provide a mechanism to run commands at boot. This is similar to the AUTOEXEC.BAT files from MS-DOS. + +With the exception of ZPM3, all operating systems will look for a file called `PROFILE.SUB` on the system drive at boot. If it is found, it will be processed as a standard CP/M submit file. You can read about the use of the SUBMIT facility in the CP/M manuals included in the RomWBW distribution. Note that the boot disk must also have a copy of `SUBMIT.EXE`. + +In the case of ZPM3, the file called `STARTZPM.COM` will be run at boot. To customize this file, you use the ZCPR ALIAS facility. You will need to refer to ZCPR documentation for more information on the ALIAS facility. + +Note that the automatic startup processing generally requires booting to a disk drive. Since the ROM disk is not writable, there is no simple way to add/edit a `PROFILE.SUB` file there. If you want to customize your ROM and add a `PROFILE.SUB` file to the ROM Disk, it will work, but is a lot harder than using a boot disk. + +# ROM Customization + +The pre-built ROM images are configured for the basic capabilities of each platform. Additionally, some of the typical add-on hardware for each platform will be automatically detected and used. If you want to go beyond this, RomWBW provides a very flexible configuration mechanism based on configuration files. Creating a customized ROM requires running a build script, but it is quite easy to do. + +Essentially, the creation of a custom ROM is accomplished by updating a small configuration file, then running a script to compile the software and generate the custom ROM and disk images. There are build scripts for Windows, Linux, and MacOS to accommodate virtually all users. All required build tools (compilers, assemblers, etc.) are included in the distribution, so it is not necessary to setup a build environment on your computer. + +The process for building a custom ROM is documented in the ReadMe.txt file in the Source directory of the distribution. + +For those who are interested in more than basic system customization, note that all source code is provided (including the operating systems). Modification of the source code is considered an expert level task and is left to the reader to pursue. + +Note that the ROM customization process does not apply to UNA. All UNA customization is performed within the ROM setup script. + +# UNA Hardware BIOS + +John Coffman has produced a new generation of hardware BIOS called UNA. The standard RomWBW distribution includes it's own hardware BIOS. However, RomWBW can alternatively be constructed with UNA as the hardware BIOS portion of the ROM. If you wish to use the UNA variant of RomWBW, then just program your ROM with the ROM image called "UNA_std.rom" in the Binary directory. This one image is suitable on **all** of the platforms and hardware UNA supports. + +UNA is customized dynamically using a ROM based setup routine and the setup is persisted in the system NVRAM of the RTC chip. This means that the single UNA-based ROM image can be used on most of the RetroBrew platforms and is easily customized. UNA also supports FAT file system access that can be used for in-situ ROM programming and loading system images. + +While John is likely to enhance UNA over time, there are currently a few things that UNA does not support: + + * Floppy Drives + * Terminal Emulation + * Zeta 1, N8, RC2014, Easy Z80, and Dyno Systems + * Some older support boards + +The UNA version embedded in RomWBW is the latest production release of UNA. RomWBW will be updated with John's upcoming UNA release with support for VGA3 as soon as it reaches production status. + +Please refer to the [UNA BIOS Firmware Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:una:start) for more information on UNA. + +# RomWBW Distribution + +All source code and distributions are maintained on GitHub. Code contributions are very welcome. + +[RomWBW GitHub Repository](https://github.com/wwarthen/RomWBW|https://github.com/wwarthen/RomWBW) + +## Distribution Directory Layout + +The RomWBW distribution is a compressed zip archive file organized in a set of directories. Each of these directories has it's own ReadMe.txt file describing the contents in detail. In summary, these directories are: + +| Application | Description | +| ----------- | -------------------------------------------------------------- | +| Binary | The final output files of the build process are placed here. Most importantly, are the ROM images with the file names ending in ".rom". | +| Doc | Contains various detailed documentation including the operating systems, RomWBW architecture, etc. | +| Source | Contains the source code files used to build the software and ROM images. | +| Tools | Contains the MS Windows programs that are used by the build process or that may be useful in setting up your system. | + +# Acknowledgements + +While I have heavily modified much of the code, I want to acknowledge that much of the work is derived from the work of others in the RetroBrew Computers Community including Andrew Lynch, Dan Werner, Max Scane, David Giles, John Coffman, and probably many others I am not clearly aware of (let me know if I omitted someone!). + +I especially want to credit Douglas Goodall for contributing code, time, testing, and advice. He created an entire suite of application programs to enhance the use of RomWBW. However, he is looking for someone to continue the maintenance of these applications and they have become unusable due to changes within RomWBW. As of RomWBW 2.6, these applications are no longer provided. + + * David Giles contributed support for the CSIO support in the SD Card driver. + * Ed Brindley contributed some of the code that supports the RC2014 platform. + * Phil Summers contributed Forth and BASIC in ROM as well as a long list of general code enhancements. + * Curt Mayer contributed the Linux / MacOS build process. + * UNA BIOS is a product of John Coffman. + +Contributions of all kinds to RomWBW are very welcome. + +# Getting Assistance + +The best way to get assistance with RomWBW or any aspect of the RetroBrew Computers projects is via the community forums: + + * [RetroBrew Computers Forum](https://www.retrobrewcomputers.org/forum/) + * [RC2014 Google Group](https://groups.google.com/forum/#!forum/rc2014-z80) + * [retro-comp Google Group](https://groups.google.com/forum/#!forum/retro-comp) + +Submission of issues and bugs are welcome at the [RomWBW GitHub Repository](https://github.com/wwarthen/RomWBW). + +Also feel free to email !author at [!authmail](mailto:!authmail). diff --git a/Source/Doc/Graphics/Bank Switched Memory.pdf b/Source/Doc/Graphics/Bank Switched Memory.pdf new file mode 100644 index 00000000..42db138c Binary files /dev/null and b/Source/Doc/Graphics/Bank Switched Memory.pdf differ diff --git a/Source/Doc/Graphics/Bank Switched Memory.png b/Source/Doc/Graphics/Bank Switched Memory.png new file mode 100644 index 00000000..f617cb0d Binary files /dev/null and b/Source/Doc/Graphics/Bank Switched Memory.png differ diff --git a/Source/Doc/Bank Switched Memory.vsd b/Source/Doc/Graphics/Bank Switched Memory.vsd similarity index 100% rename from Source/Doc/Bank Switched Memory.vsd rename to Source/Doc/Graphics/Bank Switched Memory.vsd diff --git a/Source/Doc/Character Emulation Video Services.vsd b/Source/Doc/Graphics/Character Emulation Video Services.vsd similarity index 100% rename from Source/Doc/Character Emulation Video Services.vsd rename to Source/Doc/Graphics/Character Emulation Video Services.vsd diff --git a/Source/Doc/Graphics/Character Emulation Video Services.pdf b/Source/Doc/Graphics/Character Emulation Video Services.pdf new file mode 100644 index 00000000..fadac746 Binary files /dev/null and b/Source/Doc/Graphics/Character Emulation Video Services.pdf differ diff --git a/Source/Doc/Graphics/Character Emulation Video Services.png b/Source/Doc/Graphics/Character Emulation Video Services.png new file mode 100644 index 00000000..4ccb3cc8 Binary files /dev/null and b/Source/Doc/Graphics/Character Emulation Video Services.png differ diff --git a/Source/Doc/Hard Disk Anatomy.vsd b/Source/Doc/Graphics/Hard Disk Anatomy.vsd similarity index 100% rename from Source/Doc/Hard Disk Anatomy.vsd rename to Source/Doc/Graphics/Hard Disk Anatomy.vsd diff --git a/Source/Doc/Graphics/Logo.pdf b/Source/Doc/Graphics/Logo.pdf new file mode 100644 index 00000000..0921f91a Binary files /dev/null and b/Source/Doc/Graphics/Logo.pdf differ diff --git a/Source/Doc/RomWBW System Guide/Logo.png b/Source/Doc/Graphics/Logo.png similarity index 100% rename from Source/Doc/RomWBW System Guide/Logo.png rename to Source/Doc/Graphics/Logo.png diff --git a/Source/Doc/Graphics/Logo.svg b/Source/Doc/Graphics/Logo.svg new file mode 100644 index 00000000..da51b423 --- /dev/null +++ b/Source/Doc/Graphics/Logo.svg @@ -0,0 +1,69 @@ + + + + + + + + + + + + + + Page-1 + + + Sheet.34 + + + + Sheet.35 + + + + Sheet.36 + + + + Sheet.38 + + + + Sheet.39 + + + + Sheet.44 + + + + Sheet.48 + + + + Sheet.49 + + + + Sheet.50 + + + + Sheet.52 + + + + Sheet.53 + + + + diff --git a/Source/Doc/WBW.vsdx b/Source/Doc/Graphics/WBW.vsdx similarity index 100% rename from Source/Doc/WBW.vsdx rename to Source/Doc/Graphics/WBW.vsdx diff --git a/Source/Doc/RomWBW Architecture.docx b/Source/Doc/RomWBW Architecture.docx deleted file mode 100644 index 89308a0a..00000000 Binary files a/Source/Doc/RomWBW Architecture.docx and /dev/null differ diff --git a/Source/Doc/RomWBW System Guide/Build.cmd b/Source/Doc/RomWBW System Guide/Build.cmd deleted file mode 100644 index 3413f3fc..00000000 --- a/Source/Doc/RomWBW System Guide/Build.cmd +++ /dev/null @@ -1,19 +0,0 @@ -@echo off -setlocal - -rem set MIKTEX_HOME=D:\miktex-portable\texmfs\install - -rem if "%MIKTEX_HOME%"=="" goto :eof - -rem set TEXSYSTEM=miktex -rem set MIKTEX_BINDIR=%MIKTEX_HOME%\miktex\bin -rem set MIKTEX_COMMONSTARTUPFILE=%MIKTEX_HOME%\miktex\config\miktexstartup.ini -rem set MIKTEX_GS_LIB=%MIKTEX_HOME%\ghostscript\base;%MIKTEX_HOME%\fonts -rem set MIKTEX_USERSTARTUPFILE=%MIKTEX_HOME%\miktex\config\miktexstartup.ini -rem set PATH=%MIKTEX_HOME%\miktex\bin;%PATH% - -call texify -p --clean Main.ltx - -if errorlevel 1 goto :eof - -move /Y Main.pdf "..\..\..\Doc\RomWBW System Guide.pdf" \ No newline at end of file diff --git a/Source/Doc/RomWBW System Guide/Clean.cmd b/Source/Doc/RomWBW System Guide/Clean.cmd deleted file mode 100644 index 66c5e249..00000000 --- a/Source/Doc/RomWBW System Guide/Clean.cmd +++ /dev/null @@ -1,9 +0,0 @@ -@echo off -setlocal - -if exist *.aux del *.aux -if exist *.log del *.log -if exist *.toc del *.toc -if exist *.lot del *.lot -if exist *.lof del *.lof -if exist *.pdf del *.pdf diff --git a/Source/Doc/RomWBW System Guide/Generate.cmd b/Source/Doc/RomWBW System Guide/Generate.cmd deleted file mode 100644 index f43109b8..00000000 --- a/Source/Doc/RomWBW System Guide/Generate.cmd +++ /dev/null @@ -1,4 +0,0 @@ -@echo off -setlocal - -texify -p -V --run-viewer Main.ltx diff --git a/Source/Doc/RomWBW System Guide/Main.ltx b/Source/Doc/RomWBW System Guide/Main.ltx deleted file mode 100644 index b6cb5a9c..00000000 --- a/Source/Doc/RomWBW System Guide/Main.ltx +++ /dev/null @@ -1,790 +0,0 @@ -\documentclass[letterpaper,12pt]{refrep} -\usepackage[T1]{fontenc} % Handle char values 128-255 -\usepackage[scaled]{helvet} % A nice sans serif font please -\usepackage{blindtext} % Enable \blindtext -\usepackage{scrextend} % ??? -\addtokomafont{labelinglabel}{\bfseries} % Make list labels bold -\usepackage[inline]{enumitem} % Prettier version of enumerate list -\usepackage{xcolor} % Enable colors? -\usepackage{framed} % Enable framing (used in examples) -\usepackage{graphicx} % ??? -\usepackage{fancyhdr} % More flexible header formatting -\usepackage{xhfill} % Enable \xrfill used in footer -%\usepackage{listings} % Handles source listings, improves on verbatim -\usepackage{fancyvrb} % Enhances \verbatim to allow internal formatting -\usepackage{hyperref} % More flexible hyperref formatting (\hypersetup) -\usepackage{bookmark} % Avoids "Package rerunfilecheck Warning" -\renewcommand*{\familydefault}{\sfdefault} -\title{RomWBW System Guide\\Version 2.8} -\author{Wayne Warthen\\wwarthen@gmail.com\\\\RetroBrew Computing Group\\http://www.retrobrewcomputers.org} -\date{\today} -\fullpage -\sloppy -\hypersetup{colorlinks=true} - -%\pdfobjcompresslevel=1 - -\begin{document} - -\pagenumbering{roman} - -\pagestyle{empty} - -%\maketitle -\begin{titlepage} - \centering - \par - \vspace*{72pt} - \includegraphics{Logo.png} \par - \vfill - \raggedleft - {\scshape \bfseries \fontsize{48pt}{56pt} \selectfont RomWBW \par} - {\bfseries \fontsize{32pt}{36pt} \selectfont System Guide \par} - \vspace{24pt} - {\huge Version 2.8 \\ \today \par} - \vspace{24pt} - {\large \itshape RetroBrew Computing Group \\ \href{http://www.retrobrewcomputers.org}{www.retrobrewcomputers.org} \par} - \vspace{12pt} - {\large \itshape Wayne Warthen \\ \href{mailto:wwarthen@gmail.com}{wwarthen@gmail.com} \par} -\end{titlepage} - -%\newpage - -\setcounter{page}{2} - -\begin{center} \Large COPYRIGHT \end{center} - -Copyright \copyright{} 2016 Wayne Warthen - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 -or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled "GNU -Free Documentation License". - -\bigskip -\begin{center} \Large DISCLAIMER \end{center} - -The author makes no representations or warranties with respect to the contents hereof and -specifically disclaims any implied warranties of merchantability or fitness for any particular -purpose. Further, the author reserves the right to revise this publication and to make -changes from time to time in the content hereof without obligation of the author to notify -any person of such revision or changes. - -\bigskip -\begin{center} \Large TRADEMARKS \end{center} - -CP/M is a registered trademark of Digital Research. ASM, DESPOOL, DDT, -LINK-80, MAC, MP/M, PL/1-80 and SID are trademarks of Digital Research. Intel is a -registered trademark of Intel Corporation. Zilog and Z80 are registered trademarks of Zilog, Inc. - -\bigskip -\bigskip -\begin{center} \rule{3cm}{2pt} \end{center} - -\bigskip -\bigskip -\begin{it} -This document was formatted using \LaTeX{} and produced using the MiKTeX implementation of pdfLaTeX, MakeIndex, and BibTeX running on Microsoft Windows. -\end{it} - -%\clearpage - -\fancyhf{} -\setlength{\headheight}{15.2pt} -\pagestyle{fancyplain} -\renewcommand{\chaptermark}[1]{ \markboth{#1}{} } -\renewcommand{\sectionmark}[1]{ \markright{#1}{} } -\lhead{ \fancyplain{}{\footnotesize \bfseries \rightmark \hfill RomWBW System Guide} } -\lfoot{ \fancyplain{}{\small RetroBrew Computing Group ~~ {\xrfill[3pt]{1pt}[cyan]} ~~ \thepage} } - -\renewcommand{\contentsname}{Table of Contents} -\tableofcontents -\listoftables -\listoffigures -\clearpage - -\lhead{ \fancyplain{}{\footnotesize \bfseries \thesection ~ \rightmark \hfill RomWBW System Guide} } -\pagenumbering{arabic} - -%\input{Overview.ltx} - -%\input{GettingStarted.ltx} - -\chapter{Introduction} - -\LaTeX{} is a document preparation system for -the \TeX{} typesetting program. It offers excellent -programmable desktop publishing features and -extensive facilities for automating most -aspects of typesetting and desktop publishing, -including numbering and cross-referencing, -tables and figures, page layout, -bibliographies, and much more. \LaTeX{} was -originally written in 1984 by Leslie Lamport -and has become the dominant method for using -\TeX; few people write in plain \TeX{} anymore. -The current version is \LaTeXe. - -\section{Acknowledgements} - -\section{System Requirements} - -\section{Getting Started} - -\newpage - -This is a second paragraph. - -This is a third paragraph. - -An itemized list: - -\begin{itemize} -\item First list item -\item Second list item -\item Third list item -\end{itemize} - - -An enumerated list: - -\begin{enumerate}[label=\textbf{\arabic*}.] -\item First list item -\item Second list item -\item Third list item -\end{enumerate} - -A description list: - -\begin{description} -\item [Ant] What is an ant? -\item [Elephant] \blindtext -\end{description} - -Labeling: - -\begin{labeling}{alligator} -\item [ant] really busy all the time -\item [chimp] likes bananas -\item [alligator] very dangerous animal, sharp teeth, long -muscular tail and a bit of text that is longer than one -line and shows the alignment of text quite nicely -\end{labeling} - -\section{Getting Started} - -\begin{framed} -\ttfamily -\footnotesize -%\small -\begin{verbatim} -C:> -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -\end{verbatim} -\end{framed} - -Now something else. - -Below is a table: - -\begin{tabular}{l ||| l | l | p{5cm}} -\hline -hello & goodbyte & hex & decimal \\ -\hline -\hline -hello & goodbyte & hex & decimal \\ -hello & goodbyte & hex & decimal \\ -\hline -\end{tabular} - -\chapter{Introduction} -\section{Getting Started} -\blindtext \par -\blindtext \par -\blindtext \par -\blindtext \par -\blindtext \par -\blindtext \par - -\chapter{Introduction} -\section{Getting Started} -\blindtext - -\chapter{Introduction} -\section{Getting Started} -\blindtext - -\chapter{Introduction} -\section{Getting Started} -\blindtext - -\chapter{Introduction} -\section{Getting Started} -\blindtext - -\chapter{Introduction} -\section{Getting Started} -\blindtext - -\chapter{Introduction} -\section{Getting Started} -\blindtext - -\chapter{Introduction} -\section{Getting Started} -\blindtext - -\chapter{Introduction} -\section{Getting Started} -\blindtext - -\chapter{Introduction} -\section{Getting Started} -\blindtext - -\appendix - -\chapter{Licensing} - -\section{GNU Free Documentation License} - -%\chapter*{\rlap{GNU Free Documentation License}} -%\addcontentsline{toc}{chapter}{GNU Free Documentation License} - - \begin{center} - - Version 1.3, 3 November 2008 - -\end{center} - -Copyright \copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. -\href{http://fsf.org/}{} - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - -{\large\bf 0. PREAMBLE \par} - -The purpose of this License is to make a manual, textbook, or other -functional and useful document ``free'' in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - - -{\large\bf 1. APPLICABILITY AND DEFINITIONS\par} -%\phantomsection -%\addcontentsline{toc}{section}{1. APPLICABILITY AND DEFINITIONS} - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``\textbf{Document}'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``\textbf{you}''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``\textbf{Modified Version}'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``\textbf{Secondary Section}'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``\textbf{Invariant Sections}'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``\textbf{Cover Texts}'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``\textbf{Transparent}'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``\textbf{Opaque}''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The ``\textbf{Title Page}'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``\textbf{publisher}'' means any person or entity that distributes -copies of the Document to the public. - -A section ``\textbf{Entitled XYZ}'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``\textbf{Acknowledgements}'', -``\textbf{Dedications}'', ``\textbf{Endorsements}'', or ``\textbf{History}''.) -To ``\textbf{Preserve the Title}'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - - -{\large\bf 2. VERBATIM COPYING\par} -%\phantomsection -%\addcontentsline{toc}{section}{2. VERBATIM COPYING} - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section~3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - - -{\large\bf 3. COPYING IN QUANTITY\par} -%\phantomsection -%\addcontentsline{toc}{section}{3. COPYING IN QUANTITY} - - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - - -{\large\bf 4. MODIFICATIONS\par} -%\phantomsection -%\addcontentsline{toc}{section}{4. MODIFICATIONS} - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -\begin{itemize} -\item[A.] - Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission. - -\item[B.] - List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has fewer than five), - unless they release you from this requirement. - -\item[C.] - State on the Title page the name of the publisher of the - Modified Version, as the publisher. - -\item[D.] - Preserve all the copyright notices of the Document. - -\item[E.] - Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - -\item[F.] - Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. - -\item[G.] - Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice. - -\item[H.] - Include an unaltered copy of this License. - -\item[I.] - Preserve the section Entitled ``History'', Preserve its Title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section Entitled ``History'' in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - -\item[J.] - Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the ``History'' section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - -\item[K.] - For any section Entitled ``Acknowledgements'' or ``Dedications'', - Preserve the Title of the section, and preserve in the section all - the substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - -\item[L.] - Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles. - -\item[M.] - Delete any section Entitled ``Endorsements''. Such a section - may not be included in the Modified Version. - -\item[N.] - Do not retitle any existing section to be Entitled ``Endorsements'' - or to conflict in title with any Invariant Section. - -\item[O.] - Preserve any Warranty Disclaimers. -\end{itemize} - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - - -{\large\bf 5. COMBINING DOCUMENTS\par} -%\phantomsection -%\addcontentsline{toc}{section}{5. COMBINING DOCUMENTS} - - -You may combine the Document with other documents released under this -License, under the terms defined in section~4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all sections -Entitled ``Endorsements''. - -{\large\bf 6. COLLECTIONS OF DOCUMENTS\par} -%\phantomsection -%\addcontentsline{toc}{section}{6. COLLECTIONS OF DOCUMENTS} - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - - -{\large\bf 7. AGGREGATION WITH INDEPENDENT WORKS\par} -%\phantomsection -%\addcontentsline{toc}{section}{7. AGGREGATION WITH INDEPENDENT WORKS} - - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section~3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - - -{\large\bf 8. TRANSLATION\par} -%\phantomsection -%\addcontentsline{toc}{section}{8. TRANSLATION} - - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section~4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section~4) to Preserve -its Title (section~1) will typically require changing the actual -title. - - -{\large\bf 9. TERMINATION\par} -%\phantomsection -%\addcontentsline{toc}{section}{9. TERMINATION} - - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - - -{\large\bf 10. FUTURE REVISIONS OF THIS LICENSE\par} -%\phantomsection -%\addcontentsline{toc}{section}{10. FUTURE REVISIONS OF THIS LICENSE} - - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -\texttt{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - - -{\large\bf 11. RELICENSING\par} -%\phantomsection -%\addcontentsline{toc}{section}{11. RELICENSING} - - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - - -{\large\bf ADDENDUM: How to use this License for your documents\par} -%\phantomsection -%\addcontentsline{toc}{section}{ADDENDUM: How to use this License for your documents} - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -\bigskip -\begin{quote} - Copyright \copyright{} YEAR YOUR NAME. - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -\end{quote} -\bigskip - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with \dots\ Texts.''\ line with this: - -\bigskip -\begin{quote} - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. -\end{quote} -\bigskip - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -\end{document} \ No newline at end of file diff --git a/Source/Doc/RomWBW User Guide/BoardNotes.ltx b/Source/Doc/RomWBW User Guide/BoardNotes.ltx deleted file mode 100644 index 6c6beaa1..00000000 --- a/Source/Doc/RomWBW User Guide/BoardNotes.ltx +++ /dev/null @@ -1,20 +0,0 @@ -\chapter{Board Notes} - -\blindtext - -\section{SBC} - -\blindtext - -\section{Zeta} - -\blindtext - -\section{N8} - -\blindtext - -\section{Mark IV} - -\blindtext - diff --git a/Source/Doc/RomWBW User Guide/Build.cmd b/Source/Doc/RomWBW User Guide/Build.cmd deleted file mode 100644 index 3218fc6c..00000000 --- a/Source/Doc/RomWBW User Guide/Build.cmd +++ /dev/null @@ -1,19 +0,0 @@ -@echo off -setlocal - -rem set MIKTEX_HOME=D:\miktex-portable\texmfs\install - -rem if "%MIKTEX_HOME%"=="" goto :eof - -rem set TEXSYSTEM=miktex -rem set MIKTEX_BINDIR=%MIKTEX_HOME%\miktex\bin -rem set MIKTEX_COMMONSTARTUPFILE=%MIKTEX_HOME%\miktex\config\miktexstartup.ini -rem set MIKTEX_GS_LIB=%MIKTEX_HOME%\ghostscript\base;%MIKTEX_HOME%\fonts -rem set MIKTEX_USERSTARTUPFILE=%MIKTEX_HOME%\miktex\config\miktexstartup.ini -rem set PATH=%MIKTEX_HOME%\miktex\bin;%PATH% - -call texify -p --clean Main.ltx - -if errorlevel 1 goto :eof - -move /Y Main.pdf "..\..\..\Doc\RomWBW User Guide.pdf" \ No newline at end of file diff --git a/Source/Doc/RomWBW User Guide/Clean.cmd b/Source/Doc/RomWBW User Guide/Clean.cmd deleted file mode 100644 index 66c5e249..00000000 --- a/Source/Doc/RomWBW User Guide/Clean.cmd +++ /dev/null @@ -1,9 +0,0 @@ -@echo off -setlocal - -if exist *.aux del *.aux -if exist *.log del *.log -if exist *.toc del *.toc -if exist *.lot del *.lot -if exist *.lof del *.lof -if exist *.pdf del *.pdf diff --git a/Source/Doc/RomWBW User Guide/Customization.ltx b/Source/Doc/RomWBW User Guide/Customization.ltx deleted file mode 100644 index a544dadf..00000000 --- a/Source/Doc/RomWBW User Guide/Customization.ltx +++ /dev/null @@ -1,12 +0,0 @@ -\chapter{Customization} - -\blindtext - -\section{Build Process} - -\blindtext - -\section{Configuration File} - -\blindtext - diff --git a/Source/Doc/RomWBW User Guide/DiskUsage.ltx b/Source/Doc/RomWBW User Guide/DiskUsage.ltx deleted file mode 100644 index 38dfe466..00000000 --- a/Source/Doc/RomWBW User Guide/DiskUsage.ltx +++ /dev/null @@ -1,15 +0,0 @@ -\chapter{Disk Usage} - -\blindtext - -\section{Preparing Disk Media} - -\blindtext - -\section{Disk Images} - -\blindtext - -\section{Placing Operating System on Disk} - -\blindtext \ No newline at end of file diff --git a/Source/Doc/RomWBW User Guide/Features.ltx b/Source/Doc/RomWBW User Guide/Features.ltx deleted file mode 100644 index 8c0a0500..00000000 --- a/Source/Doc/RomWBW User Guide/Features.ltx +++ /dev/null @@ -1,12 +0,0 @@ -\chapter{Features} - -\blindtext - -\section{Real Time Clock} - -\blindtext - -\section{Directory Time Stamping} - -\blindtext - diff --git a/Source/Doc/RomWBW User Guide/FormatSamples.ltx b/Source/Doc/RomWBW User Guide/FormatSamples.ltx deleted file mode 100644 index 4920b7df..00000000 --- a/Source/Doc/RomWBW User Guide/FormatSamples.ltx +++ /dev/null @@ -1,83 +0,0 @@ -\chapter{Formatting Samples} - -\blindtext - -An itemized list: - -\begin{itemize} -\item First list item -\item Second list item -\item Third list item -\end{itemize} - -An enumerated list: - -\begin{enumerate}[label=\textbf{\arabic*}.] -\item First list item -\item Second list item -\item Third list item -\end{enumerate} - -A description list: - -\begin{description}[style=multiline, leftmargin=1.25in, labelindent=0.25in, align=right] -\item [Ant] What is an ant? -\item [Elephant] \blindtext -\end{description} - -%Below is an example of labeling: - -%\begin{labeling}{alligator} -%\item [ant] really busy all the time -%\item [chimp] likes bananas -%\item [alligator] very dangerous animal, sharp teeth, long -%muscular tail and a bit of text that is longer than one -%line and shows the alignment of text quite nicely -%\end{labeling} - -\textrm{12345} - -Here is an output sample (Verbatim): - - -\begin{figure}[ht] -\setlength\abovecaptionskip{-0.5em} -\begin{Verbatim}[commandchars=\\\{\}, fontsize=\scriptsize, frame=single, rulecolor=\color{cyan}, numbers=left] -ROM Image: 'Output\textbackslash{}SBC_simh.rom' - -RetroBrew HBIOS v2.8.0-pre.5, 2016-06-22 - -SBC Z80 @ 20.000MHz ROM=512KB RAM=512KB -UART0: IO=0x68 8250 MODE=38400,8,N,1 -SIMRTC: Wed 2016-06-22 15:10:17 -MD: UNITS=2 ROMDISK=384KB RAMDISK=384KB -HDSK: UNITS=2 - -Below line is 80 characters: - -12345678901234567890123456789012345678901234567890123456789012345678901234567890 -\end{Verbatim} -\caption{Sample Output} -\label{fig:sampoutput} -\end{figure} - -Table \ref{tab:samptab} is an example of a floating table: - -\begin{table}[ht] -\center -\setlength{\arrayrulewidth}{2pt} -\begin{tabular}{l l} -\toprule -\bf CPU Board & \bf ROM Image File \\ -\midrule -SBC v1/v2 & SBC\_std.rom \\ -Zeta v1 & ZETA\_std.rom \\ -Zeta v2 & ZETA2\_std.rom \\ -N8 (2511) & N8\_2511.rom \\ -N8 (2312) & N8\_2312.rom \\ -Mark IV & MK4\_std.rom \\ -\bottomrule -\end{tabular} -\caption{Sample Table} -\label{tab:samptab} -\end{table} diff --git a/Source/Doc/RomWBW User Guide/GFDL.ltx b/Source/Doc/RomWBW User Guide/GFDL.ltx deleted file mode 100644 index 73bfeed4..00000000 --- a/Source/Doc/RomWBW User Guide/GFDL.ltx +++ /dev/null @@ -1,481 +0,0 @@ -\section{GNU Free Documentation License} - -\begin{center} Version 1.3, 3 November 2008 \end{center} - -\begin{multicols}{2} - -\tiny -\setlength{\parskip}{1em} -\setlength\columnseprule{.4pt} - -Copyright \copyright{} 2000, 2001, 2002, 2007, 2008 -Free Software Foundation, Inc. -\href{http://fsf.org/}{} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. - -\textbf{0. PREAMBLE} - -The purpose of this License is to make a manual, textbook, or other -functional and useful document ``free'' in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -\textbf{1. APPLICABILITY AND DEFINITIONS} - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes -copies of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) -To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -\textbf{2. VERBATIM COPYING} - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section~3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -\textbf{3. COPYING IN QUANTITY} - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -\textbf{4. MODIFICATIONS} - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -\begin{itemize}[leftmargin=*] - -\item[A.] Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -\item[B.] List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -\item[C.] State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -\item[D.] Preserve all the copyright notices of the Document. - -\item[E.] Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -\item[F.] Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -\item[G.] Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -\item[H.] Include an unaltered copy of this License. - -\item[I.] Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -\item[J.] Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -\item[K.] For any section Entitled ``Acknowledgements'' or ``Dedications'', -Preserve the Title of the section, and preserve in the section all -the substance and tone of each of the contributor acknowledgements -and/or dedications given therein. - -\item[L.] Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -\item[M.] Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -\item[N.] Do not retitle any existing section to be Entitled ``Endorsements'' -or to conflict in title with any Invariant Section. - -\item[O.] Preserve any Warranty Disclaimers. - -\end{itemize} - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -\textbf{5. COMBINING DOCUMENTS} - -You may combine the Document with other documents released under this -License, under the terms defined in section~4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all sections -Entitled ``Endorsements''. - -\textbf{6. COLLECTIONS OF DOCUMENTS} - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - - -\textbf{7. AGGREGATION WITH INDEPENDENT WORKS} - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section~3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -\textbf{8. TRANSLATION} - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section~4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section~4) to Preserve -its Title (section~1) will typically require changing the actual -title. - -\textbf{9. TERMINATION} - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -\textbf{10. FUTURE REVISIONS OF THIS LICENSE} - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -\href{http://www.gnu.org/copyleft/}{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -\textbf{11. RELICENSING} - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -\textbf{ADDENDUM: How to use this License for your documents} - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -\begingroup -\leftskip=2em -\slshape - -Copyright \copyright{} YEAR YOUR NAME. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 -or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled ``GNU -Free Documentation License''. - -\endgroup - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with \dots\ Texts.''\ line with this: - -\begingroup -\leftskip=2em -\slshape - -with the Invariant Sections being LIST THEIR TITLES, with the -Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - -\endgroup - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -\end{multicols} \ No newline at end of file diff --git a/Source/Doc/RomWBW User Guide/GPL.ltx b/Source/Doc/RomWBW User Guide/GPL.ltx deleted file mode 100644 index b95a8596..00000000 --- a/Source/Doc/RomWBW User Guide/GPL.ltx +++ /dev/null @@ -1,733 +0,0 @@ -\section{GNU General Public License} - -\begin{center} Version 3, 29 June 2007 \end{center} - -\begin{multicols}{2} - -\tiny -\setlength{\parskip}{1em} -\setlength\columnseprule{.4pt} - -Copyright \copyright{} 2007 Free Software Foundation, Inc. -\href{http://fsf.org/}{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -\bigskip -{\scriptsize \textbf{Preamble}} - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program--to make sure it -remains free software for all its users. We, the Free Software -Foundation, use the GNU General Public License for most of our -software; it applies also to any other work released this way by its -authors. You can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge -for them if you wish), that you receive source code or can get it if -you want it, that you can change the software or use pieces of it in -new free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the -freedom of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -\bigskip -{\scriptsize \textbf{TERMS AND CONDITIONS}} - -\textbf{0. Definitions.} - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other -kinds of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the -work in a fashion requiring copyright permission, other than the -making of an exact copy. The resulting work is called a ``modified -version'' of the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work -based on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' -to the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -\textbf{1. Source Code.} - -The ``source code'' for a work means the preferred form of the work -for making modifications to it. ``Object code'' means any non-source -form of a work. - -A ``Standard Interface'' means an interface that either is an -official standard defined by a recognized standards body, or, in the -case of interfaces specified for a particular programming language, -one that is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, -other than the work as a whole, that (a) is included in the normal -form of packaging a Major Component, but which is not part of that -Major Component, and (b) serves only to enable use of the work with -that Major Component, or to implement a Standard Interface for which -an implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential -component (kernel, window system, and so on) of the specific -operating system (if any) on which the executable work runs, or a -compiler used to produce the work, or an object code interpreter used -to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts -to control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available -free programs which are used unmodified in performing those -activities but which are not part of the work. For example, -Corresponding Source includes interface definition files associated -with source files for the work, and the source code for shared -libraries and dynamically linked subprograms that the work is -specifically designed to require, such as by intimate data -communication or control flow between those subprograms and other -parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -\textbf{2. Basic Permissions.} - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in -force. You may convey covered works to others for the sole purpose of -having them make modifications exclusively for you, or provide you -with facilities for running those works, provided that you comply -with the terms of this License in conveying all material for which -you do not control copyright. Those thus making or running the -covered works for you must do so exclusively on your behalf, under -your direction and control, on terms that prohibit them from making -any copies of your copyrighted material outside their relationship -with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -\textbf{3. Protecting Users' Legal Rights From Anti-Circumvention Law.} - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License -with respect to the covered work, and you disclaim any intention to -limit operation or modification of the work as a means of enforcing, -against the work's users, your or third parties' legal rights to -forbid circumvention of technological measures. - -\textbf{4. Conveying Verbatim Copies.} - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the -code; keep intact all notices of the absence of any warranty; and -give all recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -\textbf{5. Conveying Modified Source Versions.} - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -\begin{itemize}[leftmargin=*] - -\item[a)] The work must carry prominent notices stating that you -modified it, and giving a relevant date. - -\item[b)] The work must carry prominent notices stating that it is -released under this License and any conditions added under section 7. -This requirement modifies the requirement in section 4 to ``keep -intact all notices''. - -\item[c)] You must license the entire work, as a whole, under this -License to anyone who comes into possession of a copy. This License -will therefore apply, along with any applicable section 7 additional -terms, to the whole of the work, and all its parts, regardless of how -they are packaged. This License gives no permission to license the -work in any other way, but it does not invalidate such permission if -you have separately received it. - -\item[d)] If the work has interactive user interfaces, each must -display Appropriate Legal Notices; however, if the Program has -interactive interfaces that do not display Appropriate Legal Notices, -your work need not make them do so. - -\end{itemize} - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -\textbf{6. Conveying Non-Source Forms.} - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -\begin{itemize}[leftmargin=*] - -\item[a)] Convey the object code in, or embodied in, a physical -product (including a physical distribution medium), accompanied by -the Corresponding Source fixed on a durable physical medium -customarily used for software interchange. - -\item[b)] Convey the object code in, or embodied in, a physical -product (including a physical distribution medium), accompanied by a -written offer, valid for at least three years and valid for as long -as you offer spare parts or customer support for that product model, -to give anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily -used for software interchange, for a price no more than your -reasonable cost of physically performing this conveying of source, or -(2) access to copy the Corresponding Source from a network server at -no charge. - -\item[c)] Convey individual copies of the object code with a copy of -the written offer to provide the Corresponding Source. This -alternative is allowed only occasionally and noncommercially, and -only if you received the object code with such an offer, in accord -with subsection 6b. - -\item[d)] Convey the object code by offering access from a designated -place (gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that -supports equivalent copying facilities, provided you maintain clear -directions next to the object code saying where to find the -Corresponding Source. Regardless of what server hosts the -Corresponding Source, you remain obligated to ensure that it is -available for as long as needed to satisfy these requirements. - -\item[e)] Convey the object code using peer-to-peer transmission, -provided you inform other peers where the object code and -Corresponding Source of the work are being offered to the general -public at no charge under subsection 6d. - -\end{itemize} - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means -any tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the -way in which the particular user actually uses, or expects or is -expected to use, the product. A product is a consumer product -regardless of whether the product has substantial commercial, -industrial or non-consumer uses, unless such uses represent the only -significant mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include -a requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -\textbf{7. Additional Terms.} - -``Additional permissions'' are terms that supplement the terms of -this License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program -shall be treated as though they were included in this License, to the -extent that they are valid under applicable law. If additional -permissions apply only to part of the Program, that part may be used -separately under those permissions, but the entire Program remains -governed by this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright -holders of that material) supplement the terms of this License with -terms: - -\begin{itemize}[leftmargin=*] - -\item[a)] Disclaiming warranty or limiting liability differently from -the terms of sections 15 and 16 of this License; or - -\item[b)] Requiring preservation of specified reasonable legal -notices or author attributions in that material or in the Appropriate -Legal Notices displayed by works containing it; or - -\item[c)] Prohibiting misrepresentation of the origin of that -material, or requiring that modified versions of such material be -marked in reasonable ways as different from the original version; or - -\item[d)] Limiting the use for publicity purposes of names of -licensors or authors of the material; or - -\item[e)] Declining to grant rights under trademark law for use of -some trade names, trademarks, or service marks; or - -\item[f)] Requiring indemnification of licensors and authors of that -material by anyone who conveys the material (or modified versions of -it) with contractual assumptions of liability to the recipient, for -any liability that these contractual assumptions directly impose on -those licensors and authors. - -\end{itemize} - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as -you received it, or any part of it, contains a notice stating that it -is governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -\textbf{8. Termination.} - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your -license from a particular copyright holder is reinstated (a) -provisionally, unless and until the copyright holder explicitly and -finally terminates your license, and (b) permanently, if the -copyright holder fails to notify you of the violation by some -reasonable means prior to 60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -\textbf{9. Acceptance Not Required for Having Copies.} - -You are not required to accept this License in order to receive or -run a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -\textbf{10. Automatic Licensing of Downstream Recipients.} - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate -litigation (including a cross-claim or counterclaim in a lawsuit) -alleging that any patent claim is infringed by making, using, -selling, offering for sale, or importing the Program or any portion -of it. - -\textbf{11. Patents.} - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims -owned or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor -version, but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any -express agreement or commitment, however denominated, not to enforce -a patent (such as an express permission to practice a patent or -covenant not to sue for patent infringement). To ``grant'' such a -patent license to a party means to make such an agreement or -commitment not to enforce a patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through -a publicly available network server or other readily accessible -means, then you must either (1) cause the Corresponding Source to be -so available, or (2) arrange to deprive yourself of the benefit of -the patent license for this particular work, or (3) arrange, in a -manner consistent with the requirements of this License, to extend -the patent license to downstream recipients. ``Knowingly relying'' -means you have actual knowledge that, but for the patent license, -your conveying the covered work in a country, or your recipient's use -of the covered work in a country, would infringe one or more -identifiable patents in that country that you have reason to believe -are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent -license you grant is automatically extended to all recipients of the -covered work and works based on it. - -A patent license is ``discriminatory'' if it does not include within -the scope of its coverage, prohibits the exercise of, or is -conditioned on the non-exercise of one or more of the rights that are -specifically granted under this License. You may not convey a covered -work if you are a party to an arrangement with a third party that is -in the business of distributing software, under which you make -payment to the third party based on the extent of your activity of -conveying the work, and under which the third party grants, to any of -the parties who would receive the covered work from you, a -discriminatory patent license (a) in connection with copies of the -covered work conveyed by you (or copies made from those copies), or -(b) primarily for and in connection with specific products or -compilations that contain the covered work, unless you entered into -that arrangement, or that patent license was granted, prior to 28 -March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -\textbf{12. No Surrender of Others' Freedom.} - -If conditions are imposed on you (whether by court order, agreement -or otherwise) that contradict the conditions of this License, they do -not excuse you from the conditions of this License. If you cannot -convey a covered work so as to satisfy simultaneously your -obligations under this License and any other pertinent obligations, -then as a consequence you may not convey it at all. For example, if -you agree to terms that obligate you to collect a royalty for further -conveying from those to whom you convey the Program, the only way you -could satisfy both those terms and this License would be to refrain -entirely from conveying the Program. - -\textbf{13. Use with the GNU Affero General Public License.} - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a -single combined work, and to convey the resulting work. The terms of -this License will continue to apply to the part which is the covered -work, but the special requirements of the GNU Affero General Public -License, section 13, concerning interaction through a network will -apply to the combination as such. - -\textbf{14. Revised Versions of this License.} - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option -of following the terms and conditions either of that numbered version -or of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future -versions of the GNU General Public License can be used, that proxy's -public statement of acceptance of a version permanently authorizes -you to choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -\textbf{15. Disclaimer of Warranty.} - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -\textbf{16. Limitation of Liability.} - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -\textbf{17. Interpretation of Sections 15 and 16.} - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -END OF TERMS AND CONDITIONS - -\bigskip -{\scriptsize \textbf{How to Apply These Terms to Your New Programs}} - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make -it free software which everyone can redistribute and change under -these terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -\begingroup -\leftskip=2em -\slshape - -\\ -Copyright (C) - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see -\href{http://www.gnu.org/licenses/}{http://www.gnu.org/licenses/}. - -\endgroup - -Also add information on how to contact you by electronic and paper -mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -\begingroup -\leftskip=2em -\slshape - - Copyright (C) \\ -This program comes with ABSOLUTELY NO WARRANTY; for details type -`show w'. -This is free software, and you are welcome to redistribute it -under certain conditions; type `show c' for details. - -\endgroup - -The hypothetical commands `show w' and `show c' should show the -appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or -school, if any, to sign a ``copyright disclaimer'' for the program, -if necessary. For more information on this, and how to apply and -follow the GNU GPL, see -\href{http://www.gnu.org/licenses/}{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking -proprietary applications with the library. If this is what you want -to do, use the GNU Lesser General Public License instead of this -License. But first, please read -\href{http://www.gnu.org/philosophy/why-not-lgpl.html}{http://www.gnu.o -rg/philosophy/why-not-lgpl.html}. - -\end{multicols} \ No newline at end of file diff --git a/Source/Doc/RomWBW User Guide/Generate.cmd b/Source/Doc/RomWBW User Guide/Generate.cmd deleted file mode 100644 index f43109b8..00000000 --- a/Source/Doc/RomWBW User Guide/Generate.cmd +++ /dev/null @@ -1,4 +0,0 @@ -@echo off -setlocal - -texify -p -V --run-viewer Main.ltx diff --git a/Source/Doc/RomWBW User Guide/GettingStarted.ltx b/Source/Doc/RomWBW User Guide/GettingStarted.ltx deleted file mode 100644 index ccfba708..00000000 --- a/Source/Doc/RomWBW User Guide/GettingStarted.ltx +++ /dev/null @@ -1,251 +0,0 @@ -\chapter{Getting Started} - -Because of the wide variety of hardware combinations, there is no "one -case fits all" approach to getting started. The good news is that RomWBW -operates very consistently regardless of the specific hardware. The -operating systems, applications, and storage formats are all common. -However, building and testing your hardware is entirely outside the scope -of this document. The RetroBrew Computing Forum -(https://www.retrobrewcomputers.org/forum) is probably the best place to -get advice if you get stuck on hardware issues. - -\section{SIMH Simulator} - -It is not necessary, but I highly recommend running RomWBW under the SIMH -Simulator as a first step. This requires no hardware and will allow you -to see how it should look when you use it on real hardware. Since the -SIMH software is included in the distribution package, you can start it -with a single command. Using a command prompt window, navigate to the -high level directory of the distribution. Enter the command "sim" and -the simulator should start up. The first few lines of output should -look similar to Figure \ref{fig:simhboot}. You may see some benign -warning messages that can be ignored. - -\begin{figure}[ht] -\setlength\abovecaptionskip{-0.5em} -\begin{Verbatim}[commandchars=\\\{\}, fontsize=\scriptsize, frame=single, rulecolor=\color{cyan}, numbers=left] -ROM Image: 'Output\textbackslash{}SBC_simh.rom' - -RetroBrew HBIOS v2.8.0-pre.5, 2016-06-22 - -SBC Z80 @ 20.000MHz ROM=512KB RAM=512KB -UART0: IO=0x68 8250 MODE=38400,8,N,1 -SIMRTC: Wed 2016-06-22 15:10:17 -MD: UNITS=2 ROMDISK=384KB RAMDISK=384KB -HDSK: UNITS=2 - -\textsl{} -\end{Verbatim} -\caption{SIMH Boot Example} -\label{fig:simhboot} -\end{figure} - -\section{Board Setup} - -In all cases, you will want to start with a Z80/Z180 host board. Any of -the boards listed in System Requirements will work fine. I strongly -recommend that you initially work on getting just the single host board -running by itself -- don't even plug it into an ECB backplane. - -Given a host board that is assembled and passes any hardware checks -recommended by the boards designer, you need to make sure the board is -configured for RomWBW. Refer to the entry in Appendix A for your board -and confirm that all switches and jumpers on the board are set as -required by RomWBW. - -Your initial goal is to locate and program a ROM image for your host -board. The ROM images are located in the Output directory. You are -looking for the files that end in ".rom". Don't worry about all of the -other variations at this point. Refer to Table \ref{tab:basicromfiles} to -determine the ROM image that you want. - -\begin{table}[ht] -\center -%\renewcommand{\arraystretch}{1.5} -\setlength{\arrayrulewidth}{2pt} -\begin{tabular}{l l} -\toprule -\bf CPU Board & \bf ROM Image File \\ -\midrule -SBC v1/v2 & SBC\_std.rom \\ -Zeta v1 & ZETA\_std.rom \\ -Zeta v2 & ZETA2\_std.rom \\ -N8 (2511) & N8\_2511.rom \\ -N8 (2312) & N8\_2312.rom \\ -Mark IV & MK4\_std.rom \\ -\bottomrule -\end{tabular} -\caption{Basic ROM Files} -\label{tab:basicromfiles} -\end{table} - -Locate the appropriate ROM image file in the Output directory based on -Table \ref{tab:basicromfiles}. You should see that the file is exactly 512KB in size. -As indicated above in System Requirements, your system should have a ROM -capacity of 512KB or greater. You need to program the file to your ROM -using whatever tool you have. Programming a ROM chip is beyond the scope -of this document, but any feel free to ask for help at the RetroBrew -Computing Forum. The ROM image files are pure binary and should be -programmed into the ROM chip starting at address 0H thru address 7FFFH (8000H bytes). -Insert the programmed ROM chip in your system. - -Initially, you will need two external connections to your board. Power -and serial port. All of the CPU boards provide an onboard power -connection. Refer to the board designer's notes on the RBC Wiki for more -information on the power connection your board requires. - -Finally, you must connect the primary serial port of your host board to a -terminal using 38,400 baud, 8 data bits, 1 stop bit, and no parity. You can -use either a dedicated terminal or use terminal emulation software on -your PC\footnote{Under Windows, Tera Term is a good choice for terminal -emulation.}. -When connecting to a standard PC serial port, a null modem cable is required. -There is a good document on the Wiki that explains cabling of serial ports at -http://???????. \todo{Need to restore serial port cabling document on Wiki!} - -\section{Startup} - -System startup (booting) is accomplished simply by applying power. In some cases, -it may be necessary to press the reset button after applying power to get a -successful startup. - -If everything is working properly, you should see something like Figure \ref{fig:boot} -on your terminal screen. Your output will vary somewhat depending on your -specific hardware. The example shown comes from a Mark IV. - -\begin{figure}[ht] -\setlength\abovecaptionskip{-0.5em} -\begin{Verbatim}[commandchars=\\\{\}, fontsize=\scriptsize, frame=single, rulecolor=\color{cyan}, numbers=left] -RetroBrew HBIOS v2.8.0-pre.5, 2016-06-03 - -MARK IV Z180 @ 18.432MHz ROM=512KB RAM=512KB -ASCI0: IO=0x46,48 MODE=38400,8,N,1 -ASCI1: IO=0x47,49 MODE=38400,8,N,1 -DSRTC: MODE=STD Wed 2016-06-22 15:03:06 -MD: UNITS=2 ROMDISK=384KB RAMDISK=384KB -IDE: MODE=MK4 IO=0x80 UNITS=2 -IDE0: NO MEDIA -IDE1: NO MEDIA -SD: MODE=MK4 FAST OPR=0x89 CNTR=0x4A TRDR=0x4B UNITS=1 -SD0: NO MEDIA - -Unit Device Type Capacity/Mode ----------- ---------- ---------------- -------------------- -Disk 0 MD1: RAM Disk 384KB,LBA -Disk 1 MD0: ROM Disk 384KB,LBA -Disk 2 IDE0: Hard Disk -- -Disk 3 IDE1: Hard Disk -- -Disk 4 SD0: SD Card -- -Serial 0 ASCI0: RS-232 38400,8,N,1 -Serial 1 ASCI1: RS-232 38400,8,N,1 - -MARK IV Z180 Boot Loader - -Boot: (C)PM, (Z)System, (M)onitor, - (L)ist disks, or Disk Unit # ===> -\end{Verbatim} -\caption{Typical Boot Display} -\label{fig:boot} -\end{figure} - -If you see output on your terminal screen, but it is garbled/unreadable, then -check the serial port configuration settings on your terminal or terminal -emulation software. - -If you do not see any output of any kind on your terminal screen, the following -general areas should be checked: - -\begin{itemize} -\item Confirm power is being applied to the board and the the voltage is -in an acceptable range. -\item Confirm the ROM is programmed accurately by placing it back in the -programmer and using the verify function. -\item Verify the serial connection. When connecting to a PC, make sure -you have a null modem cable or adapter. -\item Review your board's construction carefully for chip orientation, bent -pins, missing or bridged solder joints, etc. -\end{itemize} - -You will find that the RetroBrew Computing Group is very helpful if you get -stuck. The best way to request assistance is to post a message on the -Forum. - -\section{Boot Display} - -As illustrated in Figure \ref{fig:boot}, RomWBW displays a lot of information -about the system and it's configuration. There are 4 basic sections to -the boot display. - -Line 1 is a banner that identifies the BIOS portion of the ROM including -version and build date. - -Lines 3-12 display the hardware inventory of the system as understood by -the ROM. Note that some of this information is \emph{not} discovered dynamically -- -it is built into the ROM. So, do not be alarmed if some parts of this -display do not match your hardware. For example, the RAM and ROM size -are configured into the ROM itself. You can refer to Appendix A for -more information on how to read the specific lines. - -Lines 14-22 contain a table that summarizes the devices in the system. This -information is used when the operating system is loaded/configured to -assign OS devices to system devices. - -Lines 24-27 is the display of the boot loader menu and prompt. The boot -loader allows you to choose the operating mode you want to initiate. These -options will be described the next section. - -\section{Loader} - -At the conclusion of a successful system startup, the loader menu/prompt will -be displayed on the console. The function of the loader is to load an -operating system or system monitor. - -\subsection{Monitor} - -Pressing 'M' at the boot loader prompt will launch a basic system monitor. -The system monitor provides very basic functions that are primarily useful -for testing components of your system. These functions include displaying -and modifying memory, reading and writing to I/O ports, etc. - -Refer to ??? for monitor operation. - -\subsection{CP/M} - -Pressing 'C' at the boot loader prompt will launch Digital Research CP/M-80 -Version 2.2. A complete copy of the CP/M operating system is imbedded in -the ROM and will be loaded directly from there, so no disk access is required. - -Initially, drive A will be a RAM drive (initialized with no files). Drive B -will be a ROM drive. The standard CP/M distribtion files are included on the -ROM drive (e.g., ASM, PIP, STAT). Drive B will initially be the logged drive. -At this point, you can execute the programs on drive B. Remember that drive B -is a ROM drive, so any attempt to write to that drive will result in an error. - -Refer to Chapter ?? for more information on using CP/M 2.2. - -\subsection{Z-System} - -Pressing 'Z' at the boot loader prompt will launch Z-System, a CP/M 2.2 -compatible operating system with many enhancements. As with CP/M, this -operating system will be loaded directly from ROM. - -The drive configuration for Z-System is identical to CP/M. - -Refer to Chapter ?? for more information on using Z-System. - -\subsection{Disk Boot} - -The boot loader also supports loading an operating system from a disk -device. In this case, you must press the number key corresponding to -the disk device containing the operating system to be loaded. The -disk device numbers are the ones listed in the device summary table. - -In order to boot from a disk device, it must be properly initialized -using the SYSCOPY application or equivalent. Attempting to boot a -disk that has no operating system will result in an error and the -boot loader prompt will be redisplayed. - -You can press 'L' at the boot loader prompt to display a list of -the disk devices available. The existence of a disk in this list -does \emph{not} mean that it has been initialized with an -operating system. diff --git a/Source/Doc/RomWBW User Guide/Licensing.ltx b/Source/Doc/RomWBW User Guide/Licensing.ltx deleted file mode 100644 index 434b4bb0..00000000 --- a/Source/Doc/RomWBW User Guide/Licensing.ltx +++ /dev/null @@ -1,5 +0,0 @@ -\chapter{Licensing} - -\input{GPL.ltx} - -\input{GFDL.ltx} diff --git a/Source/Doc/RomWBW User Guide/Logo.png b/Source/Doc/RomWBW User Guide/Logo.png deleted file mode 100644 index 3d43ff31..00000000 Binary files a/Source/Doc/RomWBW User Guide/Logo.png and /dev/null differ diff --git a/Source/Doc/RomWBW User Guide/Main.ltx b/Source/Doc/RomWBW User Guide/Main.ltx deleted file mode 100644 index 91652a84..00000000 --- a/Source/Doc/RomWBW User Guide/Main.ltx +++ /dev/null @@ -1,192 +0,0 @@ -\documentclass[letterpaper,12pt,oneside]{book} -%\documentclass[letterpaper,12pt,oneside,draft]{book} -%\usepackage[utf8]{inputenc} % Handle UTF8 input files -\usepackage[T1]{fontenc} % Allows use of fonts with char codes 128-255 -\usepackage{bookman} % Nice rm font -\usepackage{ascii} % Nice tt font -\usepackage[scaled]{helvet} % Nice sf font -\usepackage{geometry} % Page layout commands -\usepackage{multicol} % Easy use of multiple columns -\usepackage{hyperref} % More flexible hyperref formatting (\hypersetup) -\usepackage{blindtext} % Enable \blindtext -%\usepackage{scrextend} % A bundle of useful stuff... -\usepackage[inline]{enumitem} % Prettier version of enumerate list -%\usepackage{color} % Enable colors? -\usepackage{framed} % Enable framing (used in examples) -\usepackage{graphicx} % Add support for imbedding graphics -\usepackage{fancyhdr} % More flexible header formatting -\usepackage{xhfill} % Enable \xrfill used in footer -\usepackage{booktabs} % Improved table formattting -\usepackage{fancyvrb} % Enhances \verbatim to allow internal formatting -\usepackage{tocloft} % More versatile toc/lof/lot formatting -\usepackage{bookmark} % Avoids "Package rerunfilecheck Warning" -%\usepackage{showframe} % Diagnostic - -\title{RomWBW User Guide\\Version 2.8} -\author{Wayne Warthen\\wwarthen@gmail.com\\\\RetroBrew Computing Group\\http://www.retrobrewcomputers.org} -\date{\today} - -% -% PDF construction options -% - -%\pdfminorversion=5 -%%\pdfobjcompresslevel=1 -%\pdfobjcompresslevel=3 -%\pdfcompresslevel=9 - -% -% Global page layout and formatting -% - -%\renewcommand*\ttdefault{ascii} -%\renewcommand*\rmdefault{bookman} -%\renewcommand*\sfdefault{ascii} -\renewcommand*{\familydefault}{\sfdefault} -\geometry{letterpaper, margin=1.5in} -\setlength{\headheight}{14pt} -%\setlength\papermarginwidth{1.5in} -%\settextfraction{1.0} -%\setlength\textheight{5in} -%\renewcommand{\baselinestretch}{1.1} -\setlength\parskip{1.2em} -\setlength\parindent{0pt} -\setlist{topsep=0pt} -\sloppy - -\newcommand\todo[1]{\textcolor{red}{[TODO: #1]}} -\hypersetup{colorlinks=true} -%\addtokomafont{labelinglabel}{\bfseries} % Make list labels bold - -\renewcommand{\chaptername}{Section} - -\begin{document} - -% -% Start of frontmatter -% - -\frontmatter -\pagestyle{plain} - -%\maketitle -\begin{titlepage} - \centering - \par - \vspace*{72pt} - \includegraphics{Logo.png} \par - \vfill - \raggedleft - {\scshape \bfseries \fontsize{48pt}{56pt} \selectfont RomWBW \par} - {\bfseries \fontsize{32pt}{36pt} \selectfont User Guide \par} - \vspace{24pt} - {\huge Version 2.8 \\ \today \par} - \vspace{24pt} - {\large \itshape RetroBrew Computing Group \\ \href{http://www.retrobrewcomputers.org}{www.retrobrewcomputers.org} \par} - \vspace{12pt} - {\large \itshape Wayne Warthen \\ \href{mailto:wwarthen@gmail.com}{wwarthen@gmail.com} \par} -\end{titlepage} - -\setcounter{page}{2} - -\begin{center} \Large \uppercase{Copyright} \end{center} - -Copyright \copyright{} 2016 Wayne Warthen - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 -or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled "GNU -Free Documentation License". - -\bigskip -\begin{center} \Large \uppercase{Disclaimer} \end{center} - -The author makes no representations or warranties with respect to the contents hereof and -specifically disclaims any implied warranties of merchantability or fitness for any particular -purpose. Further, the author reserves the right to revise this publication and to make -changes from time to time in the content hereof without obligation of the author to notify -any person of such revision or changes. - -\bigskip -\begin{center} \Large \uppercase{Trademarks} \end{center} - -CP/M is a registered trademark of Digital Research. ASM, DESPOOL, DDT, -LINK-80, MAC, MP/M, PL/1-80 and SID are trademarks of Digital Research. Intel is a -registered trademark of Intel Corporation. Zilog and Z80 are registered trademarks of Zilog, Inc. - -\bigskip -\bigskip -\begin{center} \rule{3cm}{2pt} \end{center} - -\bigskip -\bigskip -\begin{it} -This document was formatted using \LaTeX{} and produced using the MiKTeX implementation of pdfLaTeX and BibTeX. -\end{it} - -\newpage -\renewcommand{\contentsname}{Table of Contents} -\cftpagenumbersoff{chapter} -\tableofcontents -\clearpage -\listoftables -\clearpage -\listoffigures -\clearpage - -\renewcommand*\ttdefault{pcr} - -% -% Start of main document content -% - -\mainmatter -\pagestyle{fancy} - -\fancyhf{} -\renewcommand{\chaptermark}[1]{ \markboth{#1}{} } -\renewcommand{\sectionmark}[1]{ \markright{#1}{} } -\fancyfoot{\small RetroBrew Computing Group ~~ {\xrfill[3pt]{1pt}[cyan]} ~~ \thepage} -\renewcommand{\headrulewidth}{0pt} -\renewcommand{\footrulewidth}{0pt} - -\fancypagestyle{plain}{ - \fancyhf{} - \fancyfoot{\small RetroBrew Computing Group ~~ {\xrfill[3pt]{1pt}[cyan]} ~~ \thepage} - \renewcommand{\headrulewidth}{0pt} - \renewcommand{\footrulewidth}{0pt} -} - -%\fancyhead{\footnotesize \bfseries \thesection ~ \rightmark \hfill RomWBW User Guide} -\fancyhead{\small \thesection ~ \rightmark \hfill RomWBW User Guide} -\renewcommand{\headrulewidth}{1pt} - -\input{Overview.ltx} - -\input{GettingStarted.ltx} - -\input{DiskUsage.ltx} - -\input{SystemMonitor.ltx} - -\input{OperatingSystems.ltx} - -\input{Features.ltx} - -\input{Customization.ltx} - -\input{FormatSamples.ltx} - -\appendix - -\addtocontents{toc}{ {\bigskip \bigskip \Large Appendixes \bigskip \par} } - -\input{BoardNotes.ltx} - -\input{Licensing.ltx} - -\backmatter - -\end{document} \ No newline at end of file diff --git a/Source/Doc/RomWBW User Guide/OperatingSystems.ltx b/Source/Doc/RomWBW User Guide/OperatingSystems.ltx deleted file mode 100644 index b0fa7ab0..00000000 --- a/Source/Doc/RomWBW User Guide/OperatingSystems.ltx +++ /dev/null @@ -1,15 +0,0 @@ -\chapter{Operating Systems} - -\blindtext - -\section{CP/M-80} - -\blindtext - -\section{Z-System} - -\blindtext - -\section{NZ-COM} - -\blindtext diff --git a/Source/Doc/RomWBW User Guide/Overview.ltx b/Source/Doc/RomWBW User Guide/Overview.ltx deleted file mode 100644 index 15012aea..00000000 --- a/Source/Doc/RomWBW User Guide/Overview.ltx +++ /dev/null @@ -1,272 +0,0 @@ -\chapter{Overview} - -RomWBW is system software that supports the Z80/Z180 based computing -platforms produced by the RetroBrew -Computing Group which is found at http://www.retrobrewcomputers.org. The goal of the -project is to provide all firmware -and software needed to make a fully functional computing platform. This -includes both firmware (ROM) and -software (disk images). The source code is provided and is licensed under -GPL v3. A GitHub repository is -used to maintain all source code and can be found at -http://www.github.com/RomWBW. - -Essentially all Z80/Z180 based hardware produced by RetroBrew Computing is -fully supported by RomWBW. Much of the software was adapted from software -produced by others in the community (see Acknowledgements) and is packaged -within RomWBW to provide an integrated solution. A companion document -(RomWBW System Guide) provides substantial detail on the architecture and -internal operation of this software. - -It is worth noting that this software is a perpetual work-in-progress. -While it has become fairly stable and robust over time, it is undergoing -constant updates to support new and revised hardware produced by the -community. Backward compatibility between releases should not be assumed. -In order to provide a complete solution, the RomWBW package incorporates a -hardware BIOS (hardware drivers) and selected operating systems and -application software. All software is derived from the CP/M era of 8-bit -computing. The operating systems included have been adapted to run under -the RomWBW architecture. In general, application software has simply been -included as originally distributed by the vendors and required no adaptation. - -The RomWBW distribution package includes all the tools required to easily -build the software from the source that is included in the package. The -package includes a range of pre-built ROM and disk images. These are -usually sufficient to get your hardware up and running simply by -programming a ROM and optionally copying disk image(s) to a floppy disk, CF -Card, or SD Card. If you wish to highly customize your system software, it -is straightforward to modify the source code and build your own. At -present, this requires Microsoft Windows XP or greater. All of the tools -have counterparts for Linux, so building the software under Linux should be -possible with a little effort. - -\section{System Requirements} - -RomWBW is purely a software project. It assumes you have a fully -functional hardware platform on which to host the software. A great deal -of information on procuring and building the appropriate hardware is found -on the RetroBrew Computing Wiki at http://www.retrobrewcomputing.org. -Additionally, the RetroBrew Computing Group has a very active forum found at -http://www.retrobrewcomputing.org/forum. This forum is the ideal place to -ask questions and get guidance for hardware and software. It is the -primary forum for supporting RomWBW. - -The starting point for a hardware platform that will appropriately host -RomWBW software is one of the following CPU boards: - -\begin{description}[style=multiline, leftmargin=1.25in, labelindent=0.25in, align=right] - -\item [SBC] -This is the original Z80 CPU board produced by the community. It remains a -very functional platform and is relatively easy to build. Note that v1 has -a design deficiency that may or may not prevent the proper operation of -RomWBW (bank switching does not always function reliably). The SBC CPU -board features an ECB bus connector which allows it to be expanded with a -backplane and peripheral boards. - -\item [Zeta] -The Zeta is very similar to the SBC board and is generally compatible with -it. However, the Zeta platform is optimized to be a compact, standalone -system. In addition to the features of the SBC, it includes an onboard -floppy disk controller and the form factor of the board allows it to be -mounted directly to a 3.5" floppy disk for a complete computing solution. -It optionally supports a single daughter board that provides SD Card -storage, VGA Monitor interface, and PS/2 keyboard interface. Although it -does not have a bus interface, Zeta is powerful, compact, and fully -featured. The Zeta v2 primarily adds enhanced bank switching and an -interrupt controller which is not required by RomWBW. - -\item [N8] -The N8 is a very robust SBC. It is significantly larger than the SBC and -incorporates a wide range of peripherals right on the one board (although -it also supports expansion via ECB bus). The N8 is based on the Z180 CPU -and incorporates interfaces for 2 serial ports, 2 parallel ports, IDE Hard -Disk / CF Card, SD Card, sound synthesizer, video display, PS/2 keyboard -and mouse interface, and floppy disk controller. This board is very -powerful, but more challenging to build. It is not compatible with the -SBC/Zeta -- it implements a different bank switching mechanism. - -\item [Mark IV] -The Mark IV by John Coffman is similar to the SBC in that it shares the -same form factor and ECB for expansion. However, it is substantially more -powerful featuring a Z180 CPU and onboard CF Card and SD Card interfaces. - -\end{description} - -RomWBW fully supports all of the above boards as a starting point. For -Zeta, the ParPortProp is supported as an option. The other platforms all -support the ECB bus for adding optional peripheral support boards. - -In addition to the hardware listed above, RomWBW also runs well on the -Microsoft Windows based SIMH Altair Z80 simulator which allows you to try -all of the RomWBW features without any actual hardware. The distribution -package contains a copy of the simulator software for MS Windows, so it is -very easy to use it (see Getting Started). - -Note that RomWBW assumes specific board configuration settings. You must -ensure that you set the jumpers/switches of each board as required by -RomWBW (unless you modify RomWBW and produce a custom version that supports -your specific board configurations). The standard board configuration -settings are documented in Appendix A. - -Note that RomWBW assumes there is 512KB of ROM and 512KB of RAM for all -systems. It is fine if your system has more RAM or ROM than this, but it -is problematic if you have less. It would be very rare for a system to -have less that these amounts, but be aware of this constraint. These -assumptions can be modified via customization later, but the pre-built -software must have these minimums. - -All of the host boards include a serial port. RomWBW will use this serial -port for output when you start your system. By default, RomWBW uses 38,400 -baud, 8 data bits, 1 stop bit, and no parity. You will need to connect the -primary serial port of the host board to a terminal (or PC running terminal -emulation software) to see the system output when you start RomWBW. - -The use of the ECB bus signals is standardized such that any ECB add-on -board can generally be combined with any of the ECB host boards to provide -enhanced functionality. Appendix A provides an inventory of the boards -supported by RomWBW along with relevant notes and required board -configuration settings. Appendix A also includes a compatibility/support -matrix between the host boards and the peripheral support boards. - -\section{Acknowledgements} - -First, I want to be clear that RomWBW is not the only option available for -system software on RetroBrew Computing Z80/Z180 hardware. While many -similar projects are no longer active, they are very useful and may contain -functionality that has not been incorporated in RomWBW. All of the -software projects (including RomWBW) are listed in the RetroBrew Computing -Wiki. - -The UNA Project from John Coffman is the other currently active software -project for the Z80/Z180 projects. It is far more advanced than RomWBW in -that it can support all 4 host boards with a single ROM image and allows -dynamic system configuration via onboard setup. It does not yet support -the full range of hardware or video capabilities of RomWBW. Note that -RomWBW supports an UNA "hybrid" configuration in which the UNA BIOS is -combined with the RomWBW OS and application layers. - -The RetroBrew Computing Group has existed in various forms since about 2010 -(?). Many individuals have contributed to the community. The original -founder of the community has moved on and requested anonymity going -forward. However, his initiative is greatly appreciated. While there is -no formal structure to the community, Andrew Bingham has taken the mantle -of responsibility for the wiki and discussion group. This is a critical -function and he deserves substantial credit for this effort. - -Earlier in the community's history, there were multiple branches of -software development. Frequently, when a new board was produced, someone -would create an independent code branch to support it. This started to -lead to a very fragmented set of software that made it very difficult to -create an integrated system with selected boards. RomWBW came about as an -effort to create a framework that would allow arbitrary hardware to be -easily added without creating entirely separate branches of code. - -RomWBW essentially became a semi-structured place to incorporate all of the -many software efforts of the community. Initially, most of the RomWBW -codebase was simply a "cut and paste" of the software produced by others. -Over time, much of this software has been repeatedly revised such that it -is no longer similar to the original, but RomWBW owes its existence to the -contributions of many other individuals. A few of those people are listed -below and I apologize for anyone that I may have inadvertently omitted. I -have intentionally omitted the original founder of the community based on -my understanding of his desire to be anonymous going forward. - -Douglas Goodall worked in very close collaboration with me during the first -year of the RomWBW Project. He produced an excellent set of supporting -utility programs and provided a great deal of design input. Regrettably, -his utilities no longer have a caretaker and have become unusable as RomWBW -has evolved, but their legacy continues within the current codebase. The -source for all of these utilities is still available if anyone wants to -take responsibility for bringing them back to current status. - -John Coffman has personally produced a great deal of the hardware designs -within the community. RomWBW contains many portions of code that John -contributed over time. Additionally, he has been instrumental in providing -advice and guidance to me for many years now. - -Dan Werner has been one of the most prolific coders within the community. -A great deal of his code was incorporated in the early RomWBW releases. -David Giles produced some code that also provided a more integrated set of -software for each host board. Over time, much of his code was incorporated -in RomWBW. Likewise, Max Scane has produced code that ultimately wound up -in RomWBW -- specifically, he contributed the CLRDIR application. - -It is my belief that all code incorporated into RomWBW has been done so -with the express or implied permission of the original authors. I realize -there have been many other individuals that have contributed to RomWBW and -apologize for not naming all of them. - -\section{RomWBW Distribution Package} - -RomWBW is distributed as a complete package (a .zip file) that contains -everything appropriate for the different hardware variations. In other -words, don't look for a specific distribution for your hardware, you just -want the current package. Within the package, you will find documentation, -source code, build tools, and pre-built ROM and disk images. - -The distribution package is usually hosted at the following locations: - - -\begin{itemize} -\item {\bf RetroBrew Computing Wiki} - -Navigate to https://www.retrobrewcomputers.org. Then, using the navigation -menu on the left, choose software $\rightarrow$ firmwareos -$\rightarrow$ romwbw to reach the RomWBW -Project Page. At the bottom of the page you will find the distribution -files listed for download. - -\item {\bf GitHub} - -Navigate to https://github.com/wwarthen/RomWBW for the RomWBW Project -on GitHub. Select "releases" to reach the list of distribution files. -Note that you will see both Prereleases and Releases listed. Unless you -specifically want to test work-in-progress, please download only a Release -version. -\end{itemize} - -The package should be named something like RomWBW-2.8-Package.zip. Using -any standard personal computer (Windows, Linux, Mac, etc.), download and -extract the contents of the zip file using any of the standard zip tools. -You will see that there are several directories that are used to organize -the contents. Don't get overwhelmed. Initially, all you really care about -is the Output directory (and possibly the Doc directory): - -\begin{description}[style=multiline, leftmargin=1.25in, labelindent=0.25in, align=right] - -\item [Doc] -Contains documentation files for many components of the RomWBW distribution -including operating systems, applications, and other aspects of RomWBW -itself. In most cases, the name of the file should identify the component -being documented. - -\item[Hardware] -Files that are specific to certain hardware components. For example, it -has the font ROM images for the video display boards. You do not need any -of these files for the host boards used initially. Appendix A describes -the contents of this directory for relevant boards. - -\item[Images] -Files that are used to create disk images. Since the disk images are all -pre-built, you do not need to worry about this directory until you want to -create custom disk images (documented later). - -\item[Output] -The ROM and Disk Images that you need to get started as documented below in -Getting Started. - -\item[Source] -The source code files that are compiled or assembled to create RomWBW. -Again, the output is pre-built, so you don't need to worry about this -directory until you want to customize your system. - -\item[Tools] -Windows-based applications that are used to build RomWBW. It also contains -applications that you can use to copy disk images to floppy disks, CF -Cards, SD Cards, etc. It also has the SIMH simulation software. - -\end{description} - -In most cases, you will find a ReadMe.txt file in the directory which -describes the contents of the directory in more detail. diff --git a/Source/Doc/RomWBW User Guide/SystemMonitor.ltx b/Source/Doc/RomWBW User Guide/SystemMonitor.ltx deleted file mode 100644 index eff0bf16..00000000 --- a/Source/Doc/RomWBW User Guide/SystemMonitor.ltx +++ /dev/null @@ -1,7 +0,0 @@ -\chapter{System Monitor} - -\blindtext - -\section{Monitor Commands} - -\blindtext \ No newline at end of file diff --git a/Source/Doc/RomWBW User Guide/x - Copy (8).ltx b/Source/Doc/RomWBW User Guide/x - Copy (8).ltx deleted file mode 100644 index 9b8e1807..00000000 --- a/Source/Doc/RomWBW User Guide/x - Copy (8).ltx +++ /dev/null @@ -1,7 +0,0 @@ -\chapter{x} - -\blindtext - -\section{x} - -\blindtext \ No newline at end of file diff --git a/Source/Doc/RomWBW User Guide/x - Copy.ltx b/Source/Doc/RomWBW User Guide/x - Copy.ltx deleted file mode 100644 index 9b8e1807..00000000 --- a/Source/Doc/RomWBW User Guide/x - Copy.ltx +++ /dev/null @@ -1,7 +0,0 @@ -\chapter{x} - -\blindtext - -\section{x} - -\blindtext \ No newline at end of file diff --git a/Source/Doc/RomWBW User Guide/x.ltx b/Source/Doc/RomWBW User Guide/x.ltx deleted file mode 100644 index 9b8e1807..00000000 --- a/Source/Doc/RomWBW User Guide/x.ltx +++ /dev/null @@ -1,7 +0,0 @@ -\chapter{x} - -\blindtext - -\section{x} - -\blindtext \ No newline at end of file diff --git a/Source/Doc/WBW.png b/Source/Doc/WBW.png deleted file mode 100644 index 3d43ff31..00000000 Binary files a/Source/Doc/WBW.png and /dev/null differ diff --git a/Source/Doc/ZCPR Manual/Build.cmd b/Source/Doc/ZCPR Manual/Build.cmd deleted file mode 100644 index 84086e9b..00000000 --- a/Source/Doc/ZCPR Manual/Build.cmd +++ /dev/null @@ -1,19 +0,0 @@ -@echo off -setlocal - -rem set MIKTEX_HOME=D:\miktex-portable\texmfs\install - -rem if "%MIKTEX_HOME%"=="" goto :eof - -rem set TEXSYSTEM=miktex -rem set MIKTEX_BINDIR=%MIKTEX_HOME%\miktex\bin -rem set MIKTEX_COMMONSTARTUPFILE=%MIKTEX_HOME%\miktex\config\miktexstartup.ini -rem set MIKTEX_GS_LIB=%MIKTEX_HOME%\ghostscript\base;%MIKTEX_HOME%\fonts -rem set MIKTEX_USERSTARTUPFILE=%MIKTEX_HOME%\miktex\config\miktexstartup.ini -rem set PATH=%MIKTEX_HOME%\miktex\bin;%PATH% - -call texify -p --clean "Main.ltx" - -if errorlevel 1 goto :eof - -move /Y Main.pdf "..\..\..\Doc\ZCPR Manual.pdf" \ No newline at end of file diff --git a/Source/Doc/ZCPR Manual/Clean.cmd b/Source/Doc/ZCPR Manual/Clean.cmd deleted file mode 100644 index 42d81d19..00000000 --- a/Source/Doc/ZCPR Manual/Clean.cmd +++ /dev/null @@ -1,9 +0,0 @@ -@echo off -setlocal - -if exist *.pdf del *.pdf -if exist *.prn del *.prn -if exist *.ix del *.ix -if exist *.log del *.log -if exist part?.txt del part?.txt -if exist *.synctex.gz del *.synctex.gz diff --git a/Source/Doc/ZCPR Manual/Main.ltx b/Source/Doc/ZCPR Manual/Main.ltx deleted file mode 100644 index 2cc18498..00000000 --- a/Source/Doc/ZCPR Manual/Main.ltx +++ /dev/null @@ -1,25 +0,0 @@ -\documentclass[letterpaper,10pt,oneside]{book} -\usepackage[T1]{fontenc} -%\usepackage[defaultmono]{droidmono} -\usepackage[scaled]{beramono} -\usepackage{fancyvrb} -\usepackage{geometry} -\usepackage{pdflscape} -%\usepackage{showframe} % Diagnostic - -% Suppress headers and footers completely -\pagestyle{empty} - -% 66 lines per page, portrait -\geometry{top=0.0in, bottom=0.0in, left=1.5in, right=1.5in} - -\RecustomVerbatimCommand{\VerbatimInput}{VerbatimInput} -{ - commandchars=\\\{\} -} - -\begin{document} - -\VerbatimInput{zcpr.ltx} - -\end{document} \ No newline at end of file diff --git a/Source/Doc/ZCPR Manual/zcpr.ltx b/Source/Doc/ZCPR Manual/zcpr.ltx deleted file mode 100644 index 732f43a7..00000000 --- a/Source/Doc/ZCPR Manual/zcpr.ltx +++ /dev/null @@ -1,1384 +0,0 @@ - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - - - \textbf{Documentation on ZCPR - A Z80 Replacement for the CP/M CCP} - - - - - ZCPR is a Group Project By the CCP-GROUP: - RLC - Richard Conn FJW - Frank Wancho - KBP - Keith Peterson RGF - Ron Fowler - - - ZCPR Documentation By RLC - - - - - - - - Table of Contents - ----- -- -------- - - Introduction 2 - - Part A: Installation Instructions 4 - ZCPR Integration Example 5 - Setting the ZCPR Inline Options 8 - REL, BASE, CPRLOC, RAS, SUBA, CLEVEL3 8 - Customization Symbols 8 - NLINES, WIDE, PGDFLT 8 - PGDFLG, MAXUSR, SYSFLG, SOFLG, SUPRES, - DEFUSR, SPRMPT, CPRMPT, NUMBASE, 9 - SECTFLG, FENCE 10 - Patching SUBMIT.COM 10 - - Part B: Usage Instructions and Explanation of - Commands 11 - The ZCPR Command Hierarchy Search 11 - The ZCPR-Resident Commands 14 - DIR, ERA 14 - LIST, TYPE, SAVE 15 - REN, USER, DFU 16 - JUMP, GO, GET 17 - ZCPR Error Messages 18 - - Part C: ZCPR Command Levels and How to Use Them 19 - - - - - - - - - Page 1 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - \textbf{Documentation on ZCPR - A Z80 Replacement for the CP/M CCP} - - - - - ZCPR is a replacement for the CP/M Console Command Processor - (CCP) which is designed to run as part of CP/M on Z80-based - microcomputers. In most cases it is upward-compatible with the - original CP/M Version 2.2 CCP. - - ZCPR, however, provides many extensions to the CP/M CCP. - Included in these extensions are the following features: - - . The TYPE function can be made to page or not page its - output at the user's discretion - - . A LIST function is available which sends its output - to the CP/M LST: Device and does NOT page - - . The DIR command has been extended to allow the dis- - play of the system files or all files - - . The ERA command now prints out the names of the files - it is erasing - - . The current user number may be included as part of - the command prompt; if the user is under a number other than 0, - the prompt is of the form 'du>' (like 'A2>' or 'B10>'), and, if - the user is under 0, the prompt may be 'd>' or 'd0>' as per his - choice - - . The SUBMIT facility has been changed in two basic - ways: - - the prompt changes to 'du$' or 'd$' when the - SUBMIT command is printed - - the $$$.SUB is executed from drive A: (note that - the original SUBMIT problem now exists, but the new SUB.COM - facility corrects it); the CCP-GROUP definition of an Indirect - Command File now applies, and this definition is that any - sequence of commands which may be issued from the console is also - a valid sequence of commands for execution from an Indirect - Command File; hence, the sequence: - - DIR - B: - DIR - A: - - may be issued from either the console or an Indirect Command - File, and the results of the execution of this sequence are the - same. Basically, this says that Indirect Command Files are - upward-compatible to the console input (but not necessarily that - the contents of an Indirect Command File may be issued at the - console without modification). - - - Page 2 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - . A command-search hierarchy is now implemented which - is executed roughly as follows: - - the user's command is checked against the CPR- - resident commands and executed immediately if a match is found - - failing that, the current user number on the - current disk is scanned for the COM file; the COM file is loaded - and executed if found - - failing that, a default user number (initially 0 - but can be reset with the DFU CPR-resident command) on the cur- - rent disk is scanned for the COM file; the COM file is loaded and - executed if found - - finally, failing that, the default user number - on disk A: is scanned for the COM file; the COM file is loaded - and executed if found or an error message (COMMAND?, when COMMAND - was the user's command name) is printed - - . The numeric argument for the SAVE command can be - specified in hexadecimal so that the user may employ the values - presented by tools such as DDT exactly as they are given - - . A GET command which loads a file at a specified - memory address and a JUMP command which "calls" the subroutine at - a specified memory address have been added; a GO command which - "calls" the subroutine at 100H (subset of the JUMP capability) - has also been added - - - This document provides the user of ZCPR with the following - information: - - Part A: Installation Instructions - Part B: Usage Instructions and Explanation of Commands - Part C: ZCPR Command Levels and How to Use Them - - - - - - - - - - - - - - - - - - - - - - - - Page 3 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Part A - Installation Instructions - - In order to install ZCPR on a target microcomputer (must be - currently running CP/M 2.2), the user must know two basic things: - - 1) Where his CCP is currently running in memory - 2) Where his CCP is located in the SYSGEN image, or, - for systems which don't support SYSGEN (such as P&T CP/M 2.2 for - the TRS-80 Model II), where his CCP is located on disk and how to - place the new ZCPR on top of it - - The first question is answered relatively easily. A pro- - gram, known as either BDOSLOC or BDLOC (for BDOS Locator), is - provided with ZCPR. You should assemble this program for your - particular computer (change the base ORG if you are running non- - ORG-0 CP/M) and execute it. Upon execution, it will provide you - with the base address of (1) the BDOS and (2) the CCP for your - particular system. BDOSLOC has worked correctly for all systems - tested so far, but there is always a chance that it may NOT work - for some non-tested system. For the time being, assume that it - works correctly and record the starting base page address of your - CCP. - - The second question is not answered nearly so easily. If - you have the ability to SYSGEN your system, it is much easier - (commonly) than if you do not. You must, after assembling the - ZCPR properly, integrate it into the sysgen (or disk) image of - CP/M. This can be done by obtaining a SYSGEN image of your - system, scanning it via a debugger such as DDT to find the offset - for the CCP, reading the new CPR in on top of the old one, and - finally running SYSGEN again to place the resultant system on - disk. If you DO NOT have SYSGEN capability, a Disk Utility - program is required to locate the CCP on disk and then write the - new ZCPR on top of the old one. The net result of this - integration is the placement of the new ZCPR onto disk in the - proper place so that it will be loaded with the rest of CP/M on - cold boot and executed properly. - - To find the original CCP, you typically have to locate it by - its appearance. It is probably stored contiguously on disk, so, - once it is found, a sequential overwrite is all that is required. - Probability is extremely high that it is stored contiguously in - the SYSGEN image. The CCP starts with two (2) and ONLY TWO jump - instructions followed by a buffer area (possibly containing an - initial command and/or the Digital Research copyright notice). - The Digital Research manuals show the CCP to reside at address - 980H in the SYSGEN image, but this may vary with system. To - find this image, use DDT or some other such debugger, load the - SYSGEN image you can get via SYSGEN, and examine memory starting - at around 900H for the two (and ONLY two) jumps described above. - If you find an area with more than two jumps (a group of them), - you are probably looking at the BIOS and should go lower for the - CCP. The CCP will probably start on an even page or half-page - address (like 900H, 980H, 1100H, etc). - - Page 4 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Now that the location of the CCP has been found, record this - address for later. You are now ready for the integration of ZCPR - into your system. To do this, perform the following steps using - the information of the page address of the CCP (obtained from - BDOSLOC and called CPRLOC within ZCPR) and the SYSGEN image - address of the CCP (called IMAGE for reference in this document). - - 1. Edit ZCPR and set the CPRLOC equate to the value - obtained from above. Also set any flags and values as you desire - (see the section on ZCPR Customization below). When satisfied, - end the edit session. - - 2. Assemble ZCPR with MAC (or equivalent). This - assembler is required because of the MACROs used. Only the - resultant HEX file is required. - - 3. Assuming that you can use SYSGEN, obtain a SYSGEN - image of your current CP/M system and save it on disk. - - 4. Load the SYSGEN image into memory with DDT (or - equivalent). Once loaded, verify that the original CCP is at the - IMAGE address found above and compute the integration offset - using the DDT H command: - H, - The second number displayed gives you the OFFSET value required - for step 5. - - 5. Integrate ZCPR into your SYSGEN image via DDT's I - and ROFFSET commands. Use IZCPR.HEX (or the name of your version - of ZCPR) to load the FCB and ROFFSET (where OFFSET was computed - in step 4) to load the ZCPR.HEX file into memory at the proper - location. Check to see that ZCPR is indeed properly loaded by - examining the SYSGEN IMAGE area. - - 6. Place the new system on disk by running SYSGEN and - NOT loading the system from disk (use the memory image). - - For further clarification of the above process, the - following is a sample terminal session which outlines the steps - taken. - - ZCPR Integration Example - - - B>; Sample terminal session for integrating ZCPR - B>sysgen - SYSGEN VER 2.2 - SOURCE DRIVE NAME (OR RETURN TO SKIP)b - SOURCE ON B, THEN TYPE RETURN <-- I hit the RETURN key here - FUNCTION COMPLETE / - DESTINATION DRIVE NAME (OR RETURN TO REBOOT) <-- and here - B>save 44 cpm56.com <-- We now have a SYSGEN image of CP/M - to work with - - - - Page 5 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - B>xdir - XDIR Version 2.6 User Number: 0, Double Density - File Attributes: Non-System - - Filename.Typ Size K Filename.Typ Size K Filename.Typ Size K - -------- --- ------ -------- --- ------ -------- --- ------ - !TEXTWRK.-12 0 CPR .DOC 8 EE687 .TXT 4 - CPR .AQM 34 TFS .HLP 6 EE687PRE.TXT 4 - CPR .ASM 50 CONTENTS.T01 6 SW1 .TXT 10 - CPR .BAK 4 CONTENTS.T02 4 SW2 .TXT 2 - CPM56 .COM 12 CONTENTS.T03 4 - B: 30 Entries & 22 Files -- 338K Bytes Remaining - File Data: 14 Files -- 154K Bytes Displayed - B>bdosloc <-- Now to locate the CCP's address - The Base Page Address of this system's BDOS is C5 - The Base Page Address of this system's CCP is BD <-- This is it - B>ddt cpm56.com <-- Now to find the CCP in the SYSGEN image - DDT VERS 2.0 - NEXT PC - 2D00 0100 - -d900,90f <-- Start looking around here - 0900 31 80 E7 3E 06 3C 3C FE 1B CA 00 C2 DA 11 E7 D6 1..>.<<......... - -da00,a0f - 0A00 31 00 01 01 01 0C C5 CD 0F E4 21 00 BE 11 00 04 1.........!..... - -db00,b0f - 0B00 31 00 01 01 01 11 C5 CD 0F E4 21 00 C0 11 00 02 1.........!..... - -db80,b8f - 0B80 31 00 01 01 09 01 CD A8 00 21 00 D2 11 00 C2 0E 1........!...... - -- Detail Left Out -- - -d1100 <-- I found it at 1100H; note the 2 JMP's - 1100 C3 FF BD C3 FB BD 50 10 20 20 20 20 20 20 20 20 ......P. - 1110 20 20 20 20 20 20 20 20 00 00 00 00 00 00 00 00 ........ - 1120 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ - -- Detail Left Out -- - -^C <-- Return to CP/M; I know that CPRLOC will be - BD00H and the IMAGE offset is 1100H - - B>ed cpr.asm \{edit ZCPR here and place CPRLOC=BD00H\}# - -- Detail Left Out -- - - B>mac cpr $pz sz <-- Now to assemble the CPR - CP/M MACRO ASSEM 2.0 - C4F0 <-- Note that CPR MUST end before BDOS - begins! - 014H USE FACTOR - END OF ASSEMBLY - - - - - - - - - - - - Page 6 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - B>ddt cpm56.com <-- Now to integrate! - DDT VERS 2.0 - NEXT PC - 2D00 0100 - -h1100,bd00 <-- Compute offset for new CPR - CE00 5400 <-- Offset is 5400H - -icpr.hex <-- Init FCB - -r5400 <-- Read in new CPR with offset - NEXT PC - 2D00 0000 - -^C <-- Done! - B>sysgen <-- Now to SYSGEN onto disk - SYSGEN VER 2.2 - SOURCE DRIVE NAME (OR RETURN TO SKIP) <-- Use memory image - DESTINATION DRIVE NAME (OR RETURN TO REBOOT)b <-- onto B: - DESTINATION ON B, THEN TYPE RETURN - FUNCTION COMPLETE - DESTINATION DRIVE NAME (OR RETURN TO REBOOT) <-- Done for now - - B> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Page 7 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Setting the ZCPR Inline Options - - The following are the four basic options available to the - user under ZCPR for customization of his package. - - Option Name Function - - REL Configures CPRLOC (CPRLOC equ 0) for integration - via MOVCPM rather than the DDT/SYSGEN technique - outlined above; set to TRUE for MOVCPM integra- - tion or FALSE for DDT/SYSGEN integration - - BASE Base address of your CP/M system; standard CP/M - has a base of 0, but some CP/M systems (such as - for the TRS-80 Model I and Heath/Zenith H89/Z89) - start physical RAM memory at a higher address; - equate BASE to the starting RAM memory address of - your system - - CPRLOC This is the starting address of ZCPR; set the - second CPRLOC equate to the address you obtain - from BDOSLOC - - RAS This is an equate which masks out selected ZCPR - command functions for security purposes on - Remote Access Systems such as Bulletin Boards; - the masked out functions currently include - SAVE, ERA, REN, JUMP, GO, and GET; set RAS to TRUE - to mask these out or FALSE to leave them in - - SUBA This is an equate which determines the drive - onto which ZCPR will look for an executing - Indirect Command File. If the basic philosophy - of the Indirect Command File described above is - to be maintained, this symbol should be set to - TRUE (look on drive A: for the $$$.SUB file); if - not, this symbol should be set to FALSE (look on - the default drive from the $$$.SUB file). To - review, the basic philosophy of the Indirect - Command File is that any sequence of commands - which may be issued from the console (within - reason, which means NOT to erase a $$$.SUB file) - may also be issued from within an Indirect - Command File, and the resultant execution should - be identical (same functions performed). - - CLEVEL3 This equate enables or disables extended Command - Level 3 Processing. If set to TRUE, extended - Command Level 3 Processing is enabled and the user - command line is automatically capitalized, the - terminating zero is placed at the end of the - buffer, and the internal CIBPTR is set correctly - (see later for more information). - - - - Page 8 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - Customization Symbols - - The following symbols are provided for further customization - of ZCPR to a user's particular tastes and hardware facilities. - - Option Name Function - - NLINES Number of lines on the user's CRT for paging - - WIDE This equate is used to select a narrow or wide - display under the DIR command; if WIDE is equated - to TRUE, each file name is separated by two - spaces, a FENCE, and two more spaces; if WIDE is - equated to FALSE, each file name is separated by - one space, a FENCE, and one more space - - PGDFLT This is the Paging Default flag for the TYPE - command; if PGDFLT is set to TRUE, the TYPE - command will page its output by default and - the P option on the TYPE command (see below) - will prohibit paging; if PGDFLT is set to FALSE, - the TYPE command will NOT page its output by - default and the P option will enable paging - - PGDFLG This sets the option character in the command - line for the TYPE command (the 'P' mentioned - above); if the user wishes to change this option - character, he need only change this equate - - MAXUSR This is the largest user number recognized by - the USER command; if the user wishes to protect - the higher user areas, he may set this symbol - to the highest area normally accessable; 15 is - the largest permitted value for MAXUSR - - SYSFLG This is the option character for the DIR command - line which is used to specify that DIR search - All Files (both $SYS and $DIR) for its display; - the distributed default for this is 'A' - - SOFLG This is the option character for the DIR command - line which is used to specify that DIR search - ONLY the $SYS files for its display; the distri- - buted default for this is 'S' - - SUPRES Set SUPRES to TRUE to suppress printing the user - number when the user is under User Number 0 or - set SUPRES to FALSE to ALWAYS display the User - Number with the CPR prompt; with SUPRES set to - TRUE, a user on B: in user 0 sees 'B>' as the - prompt, but with SUPRES set to FALSE, a user on - B: in user 0 sees 'B0>' as the prompt - - - - Page 9 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - DEFUSR This is the CPR-default user number which is - searched in the command hierarchy for the COM - files (distributed as 0); the DFU changes this - temporarily until a Warm Boot or Cold Boot is - done, at which time the search reverts to this - value - - SPRMPT This is the CPR prompt character which indicates - that a SUBMIT file is in execution; by default - it is set to '$', so prompts like 'A$' appear - during SUBMIT file execution - - CPRMPT This is the CPR prompt character which indicates - that the CPR is awaiting a user console command; - by default it is set to '>', so prompts like - 'A>' appear during user input to the CPR - - NUMBASE This is the escape character used by those - commands which require a DECIMAL number as - an argument; placing this character after - the number argument switches the base to - HEXADECIMAL; for example, 'SAVE 15 MYFILE' can be - expressed as 'SAVE FH MYFILE' if NUMBASE is - set to 'H' (the default) - - SECTFLG This character constant is the suffix option for - the SAVE command which specifies that sectors, - as opposed to pages, are to be saved; the default - value is 'S' - - FENCE This is the character printed to separate entries - in a directory listing; it's default value is '|' - - - Patching SUBMIT.COM - - SUBMIT.COM may be patched to run with ZCPR by the following - procedure (this is recommended if the user does not have - SUB.COM). This patch simply makes it always place the $$$.SUB - file on Drive A:. Illustrative terminal session follows: - - A>ddt b:submit.com - DDT VERS 2.0 - NEXT PC - 0600 0100 - -s5bb <-- Patch is at 5BB Hex - 05BB 00 1 <-- Change 0 (default drive) to 1 (drive A:) - 05BC 24 . <-- That's it! - -d5b0 5cf <-- See change - 05B0 00 00 00 00 00 00 30 30 31 20 24 01 24 24 24 20 ......001 $.$$$ - 05C0 20 20 20 20 53 55 42 00 00 00 1A 1A 1A 1A 1A 1A SUB......... - -^C <-- Done - A>save 5 newsubmt.com <-- Save new SUBMIT.COM file - - - - Page 10 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Part B - Usage Instructions and Explanation of Commands - - - The following instructions are written with the assumption - that the reader is quite familiar with how to use CP/M 2.2 and - its CCP. ZCPR is written as a logical extension of the CP/M 2.2 - CCP philosophy and should be addressed as such. - - - - The ZCPR Command Hierarchy Search - - The first, and most basic thing, to learn about ZCPR is the - order in which is searches for a COM file for execution or a file - specified by the GET command. Under the CP/M 2.2 CCP, if the - specified COM file command was not found on the current drive in - the current user area, the CCP aborted with an error message. - ZCPR, however, continues searching from this point a maximum of - two more levels. This command hierarchy search was outlined - above and is described here in further detail. - - 1. If the command is of the form 'COMMAND' and NOT - 'd:COMMAND', the CPR-resident command list is searched for a - match. If the match is found, the CPR-resident command is - immediately processed. If the match is not found or the command - is of the form 'd:COMMAND', the next step is taken. Note that - the 'd:COMMAND' form is good for executing a command COM file - which has the same name as a CPR-resident command (such as SAVE - or DIR). - - 2. If the command is of the form 'd:COMMAND', disk - drive 'd:' is temporarily logged in for the purpose of the - command search. Otherwise, the currently logged-in drive is - used. - - 3. Now the file named COMMAND.COM is searched for. If - found, it is loaded into memory starting at 100H and executed. - If not, proceed to step 4. - - 4. Now that the first search for COMMAND.COM has - failed, the CPR checks to see if the user is under the current - Default User Number. The Default User Number may be that set by - the DEFUSR equate in the CPR or that set by the user via the DFU - command. DEFUSR is in effect if DFU has not been issued since - the last Warm or Cold Boot, and DFU is in effect if it was issued - since the last Warm or Cold Boot. If the user is NOT under the - current Default User Number, ZCPR temporarily logs him into it - and searches the directory. If COMMAND.COM is found, it is - loaded as described above and executed. If not, ZCPR proceeds to - the next step. - - - - - - Page 11 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - 5. The user is now in the Default User Number, and at - this point, ZCPR checks to see if the user is on disk drive A:. - If not, it temporarily logs into A: and searches the default user - number of A: for COMMAND.COM. If found, it is loaded as - described above and executed. If not, ZCPR prints the command - name as an error message and returns to command input mode, - aborting the SUBMIT file if COMMAND came from it. - - In all cases of the search above, if COMMAND.COM is found, - after it is loaded into memory, ZCPR resets the user to his - original disk drive and user number. Hence, the files referenced - by the user by default are obtained from this environment. - - To illustrate this command hierarchy search, consider the - following examples: - - Example 1: DEFUSR equ 0 \{default user number is 0\} - - B10> <-- User is on Drive B:, User Number 10 - B10>ASM TEST.BBZ <-- User wishes to assemble TEST.ASM in - Drive B:, User 10 - <-- At this point, ZCPR looks on B:/10 for ASM.COM, fails, - looks on B:/0, fails, and finally looks on A:/0; it - finds ASM.COM here and goes back to B:/10 for the file - - - Example 2: DEFUSR equ 0 and DFU issued - - B10> <-- User is on Drive B:, User Number 10 - B10>DFU 5 <-- User Selects User 5 as default - B10>ASM TEST.BBZ <-- As above - <-- At this point, ZCPR looks on B:/10 for ASM.COM, fails, - look on B:/5, fails, and finally looks on A:/5; it - fails here also and prints ASM? as an error message - - Example 3: DEFUSR equ 0 - - B> <-- User is on Drive B:, User Number 0 - B>ASM TEST.BBZ <-- As above - <-- At this point, ZCPR looks on B:/0 for ASM.COM, fails, - looks on A:/0, fails, and prints error message - - Example 4: DEFUSR equ 0 - - A10> <-- User is on Drive A:, User Number 10 - A10>ASM TEST.AAZ <-- As above, but file on A: - <-- At this point, ZCPR looks on A:/10 for ASM.COM, fails, - looks on A:/0, fails, and prints error message - - - - - - - - - Page 12 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Another Example: - - For example, if the user is logged into Drive B: in - User Area 10, the Default User Number is 0, and the following COM - files are present as indicated -- - - WM.COM on Drive A: in User 0 - MBASIC.COM on Drive A: in User 0 and on - Drive B: in User 0 - TEST.COM on Drive B: in User 10 and Drive B: - in User 0 - - then the following happens when the following commands are - issued from the console (or Indirect Command File): - - B10>WM TEST2.TXT - ^ ^ ^-------- File to be edited - | +----------- Invoke the WM.COM file (Word Master editor) - +--------------- User is on Drive B: in User Area 10 - - Results: - ZCPR searches B: User 10, B: User 0, and A: User 0 for - WM.COM; it finds WM.COM in A: User 0, loads it, logs the user - back into B: User 10, and executes it. - - B10>MBASIC - ^ ^----- Invoke the MBASIC.COM file (MBASIC Interpreter) - +--------- User is on Drive B: in User Area 10 - - Results: - ZCPR searches B: User 10 and B: User 0 for MBASIC.COM; - it finds MBASIC.COM in B: User 0, so it doesn't bother to look on - A: User 0. MBASIC.COM is then loaded and executed as described - in the previous example. - - B10>TEST - ^ ^--- Invoke the TEST.COM file (TEST program) - +------- User is on Drive B: in User Area 10 - - Results: - ZCPR searches B: User 10 for TEST.COM; it finds - TEST.COM in B: User 0, so it doesn't bother to look further (if - it had, it would have found TEST.COM in B: User 0). TEST.COM is - then loaded and executed as described above. - - B10>TEST2 - | +--- Invoke the TEST2.COM file (TEST2 program) - +------- User is on Drive B: in User Area 10 - - Results: - ZCPR searches B: User 10, B: User 0, and A: User 0 for - TEST2.COM; it doesn't find it, so it issues the error message - 'TEST2?', which says it couldn't find TEST2.COM. - - - - Page 13 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - - The ZCPR-Resident Commands - - The following pages describe the ZCPR-Resident Commands. - These are commands located within ZCPR itself which are executed - from within ZCPR. The phrases and refer to ambiguous - file name and unambigous file name as per the CP/M convention. - - Command: DIR - Function: To Display a listing of the names of the files on disk - Forms: - DIR <-- Displays $DIR files - DIR S <-- Displays $SYS files - DIR A <-- Displays both $DIR and $SYS files - Customization Variables: - WIDE SYSFLG SOFLG FENCE - Examples: - DIR *.ASM <-- All $DIR .ASM files - DIR *.COM S <-- All $SYS .COM files - DIR *.COM A <-- All .COM files - Notes: - If a file is scanned for and no such name exists on disk, - the 'No Files' message will appear. However, if a file is - scanned for and the name exists as a $SYS file and $DIR files are - being scanned for, no file name is displayed but the 'No Files' - message does NOT appear. For example, if TEST.COM is a $SYS file - and 'DIR TEST.COM' is issued, no message appears. If 'DIR - TEXT.COM' is issued and TEXT.COM does not exist on disk, the 'No - Files' message is displayed. - - - Command: ERA - Function: To Erase the specified $R/W files from disk - Forms: - ERA <-- Erase both $DIR and $SYS files - Customization Variables: - WIDE FENCE - Examples: - ERA *.ASM <-- Erase all .ASM files - ERA *.* <-- Erase all files - Notes: - If a $R/O file is encountered, a BDOS error message will be - displayed and the procedure is stopped. The user is unsure at - this time as to which files have been erased and which have not - and should check. Sorry for this problem! The ERASE command (to - be given to SIG/M by RLC in the near future) is a solution to - this problem. - - - - - - - - - Page 14 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - Command: LIST - Function: To Print the specified file on the CP/M LST: device - Forms: - LIST <-- Print the file (no paging) - Customization Variables: - -None- - Examples: - LIST TEST.TXT <-- Print TEST.TXT on LST: - Notes: - If the file has a $SYS attribute, it will be found as well - as those with $DIR attributes. - - - Command: TYPE - Function: To Print the specified file on the CP/M CON: device - Forms: - TYPE <-- Print the file with the paging deflt - TYPE P <-- Print the file with the paging deflt - negated - Customization Variables: - NLINES PGDFLT PGDFLG - Examples: - TYPE TEST.TXT - TYPE TEST.TXT P - Notes: - When the display pauses during paging, type any char to - continue or ^C to abort. ^S also works. - - - Command: SAVE - Function: To Copy the TPA starting at 100H to disk - Forms: - SAVE <-- in DEC - SAVE H <-- in HEX - SAVE S <-- Number of sectors - SAVE H S <-- Number of sectors - Customization Variables: - NUMBASE RAS - Examples: - SAVE 15 MYFILE.TXT <-- 15 pages saved - SAVE FH MYFILE.TXT <-- 15 pages saved - SAVE 10H MYFILE.TXT S <-- 16 sectors (8 pages) saved - Notes: - If the file name to be saved already exists, then SAVE will - exit with the message 'Delete File?'; if the user REALLY wants to - save under this name, he may then type Y or y and the current - file will be deleted and then recreated containing the specified - part of the TPA. - - - - - - - - Page 15 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - - Command: REN - Function: To Change the name of a disk file - Forms: - REN = - Customization Variables: - RAS - Examples: - REN NEWFILE.TXT=OLDFILE.TXT - Notes: - If already exists, the message 'Delete File?' will - be printed and the user may respond with Y or y to delete the - current and then rename to . - - Command: USER - Function: To Change the current user number - Forms: - USER <-- in DEC - USER H <-- in HEX - Customization Variables: - -None- - Examples: - USER 15 USER FH USER 0 - USER <-- Same as USER 0 - Notes: - -None- - - - Command: DFU - Function: To Temporarily Change the default user number for the - command hierarchy search - Forms: - DFU <-- in DEC - DFU H <-- in HEX - Customization Variables: - -None- - Examples: - DFU 15 DFU FH DFU 0 - DFU <-- Same as DFU 0 - Notes: - See above for explanation. - - - - - - - - - - - - - - - Page 16 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - - Command: JUMP - Function: To "call" the subroutine at the specified page address - Forms: - JUMP
<--
in HEX - Customization Variables: - NUMBASE RAS - Examples: - JUMP E000 or JUMP E000H <-- Jump to E000H - JUMP <-- Jump to 000H - JUMP 0 <-- Jump to 000H - Notes: - JUMP performs a subroutine "call", so the called routine may - return to the ZCPR by either a RET or a Warm Boot. - - - Command: GO - Function: To "call" the subroutine starting at 100H - Forms: - GO <-- Execute reentrant at 100H - Customization Variables: - RAS - Examples: - GO *.ASM <-- Assuming XDIR is loaded, - gives directory of *.ASM - Notes: - This command is identical in function to JUMP 100H; JUMP, - however, leaves the address as the first entry in CP/M BASE + 80H - (the input line buffer), while GO has no such address. - - - Command: GET - Function: To load a file from disk into memory starting at the - specified page - Forms: - GET
<--
in HEX - Customization Variables: - NUMBASE RAS - Examples: - GET 8000 TEST.80 <-- Load TEST.80 starting at 8000H - GET 100 TEST.80 or GET 100H TEST.80 <-- Load TEST.80 - starting at 100H - GET 0 TEST.80 <-- Load TEST.80 starting at 000H - Notes: - GET searches for the specified file according to the same - command hierarchy search employed by the ZCPR command scanner. - Hence, if the user is on B:/10 and the file is on A:/0 with the - current default user number at 0, GET will search from B:/10 to - B:/0 to A:/0 in looking for the file. - - - - - - - Page 17 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - ZCPR Error Messages - - The following are the error messages issued by ZCPR and - their meanings. - - Message Meaning - - ? Printed after a command or an argument means that such - was invalid - - No File From DIR, this means that DIR did not locate any files - Also from ERA with the same meaning - - All? Issued in response ERA *.*, asks the user is he really - wants to erase all the files. Unlike under the - original CP/M 2.2 CCP, single character input is - required (Y or y for yes and anything else for no) - with NO to end the line - - Full From SAVE, means that there is not enough space on - disk - From GET or command load by CPR, means that there - is not enough space in memory - - Delete File? - From REN or SAVE, means that the file specified already - exists on disk and the user may type Y or y to delete - it and proceed with the REN or SAVE function - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Page 18 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - Part C - ZCPR Command Levels and How to Use Them - - - ZCPR Version 1.0 and beyond supports three distinct command - levels in its implementation. Each level constitutes a different - way to issue a command for ZCPR to process. - - Command Levels 1 and 2 are common to all implementations of - CP/M and CP/ZM from CP/M Version 1.4. Command Level 1 is that - command level in which the command is issued by the user from his - console terminal. The prompt 'd>' or 'du>' appears on the - terminal, and the user is allowed to enter the command with - editing from the terminal. Command Level 2 is that command level - in which the command is entered from an executing $$$.SUB file. - - In both cases, the command is stored in the internal ZCPR - buffer called CIBUFF (Command Input BUFFer). Under both Command - Levels 1 and 2, the command is placed into this buffer, the - characters of the command line are capitalized, a character count - which indicates the number of characters in the command line is - stored in CBUFF (the byte before CIBUFF), an ending binary 0 is - placed after the last character in the command line, and the - internal pointer CIBPTR (Command Input Buffer PoinTeR) is set to - point to CIBUFF (the first character of the command line). - - Command Level 3 is an extended concept to Command Levels 1 - and 2 which is specifically supported by ZCPR Version 1.0 and - beyond. This command level allows a transient program to place a - command line into CIBUFF and the character count into CBUFF and - have this command line executed by ZCPR. Once control is trans- - ferred to ZCPR to execute the command line, the transient program - which placed the command line loses control and the command is - executed exactly as though it had been typed by the user at his - console terminal. - - In order for a transient program to utilize the Command - Level 3 facility, this program MUST do the following: - - 1. Locate the ZCPR. Since the ZCPR is ALWAYS 2K bytes - in size and located directly under the BDOS, the transient can - locate the ZCPR by examining the BDOS entry page address at - location 7 and subtracting 8 from this number (8 pages = 2K - bytes). The resulting number is the base page address of ZCPR. - - 2. Store the command line in CIBUFF and the character - count in CBUFF. Knowing the base page address of ZCPR, the - following information is useful in doing this: - - - - - - - - Page 19 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - ORG CPRLOC ;Base Address of ZCPR - JMP CPR ;Enter ZCPR and Execute Default Cmd - JMP CPR1 ;Enter ZCPR and Don't Execute - MBUFF: DB BUFLEN ;Size of CIBUFF in bytes - CBUFF: DS 1 ;Number of Bytes in Command Line - CIBUFF: DS BUFLEN ;Buffer for Command Line - DS 1 ;Buffer for Ending 0 (set by ZCPR) - CIBPTR: DS 2 ;Address of CIBUFF (set by ZCPR) - - - 3. Obtain the User/Disk Flag. Location 4 contains - this number, but the user may select a flag of his choice. This - flag is one byte long, and the high-order nybble (4 bits) - contains the user number and the low-order nybble contains the - disk number to process the command from. The User/Disk Flag is - to be passed to ZCPR in the C Register. - - 4. When ready, transfer control to ZCPR to process the - command by JMPing to the base address of ZCPR. The first JMP in - the JMP Table given above is at this address. At this time, ZCPR - will log in the user and disk in the User/Disk Flag and process - the Command Level 3 Command Line. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Page 20 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - The following is a sample program which illustrates the - steps outlined above: - - ; - ; Demonstration of Command Level 3 Facility by RLC - ; - udflag equ 4 ;Address of User/Disk Flag - bdos equ 5 ;Address of BDOS Entry Point - - org 100h - - lxi d,prmpt ;Print User Prompt - mvi c,9 ;PRINT function - call bdos - - lhld bdos+1 ;Get address of BDOS - mov a,h ;High-Order Address in A - sui 8 ;A=High-Order Address of CPR - mov h,a ;HL=Address of CPR - mvi l,0 - shld cpr ;Save address in buffer - - lxi d,6 ;Point to command line buffer - dad d ;HL points to command line buffer - xchg ;DE points to command line buffer - mvi c,10 ;READLN into this buffer - call bdos - - lhld cpr ;Get Address of CPR - lda udflag ;Get User/Disk Flag - mov c,a ; ... in C - pchl ;Run Command Line - - cpr: ds 2 ;CPR Address buffer - prmpt: db 'User Command? $' - - - - - - - Enjoy using ZCPR! - -- RLC - - - - - - - - - - - - - Page 21 \ No newline at end of file diff --git a/Source/HBIOS/Build.ps1 b/Source/HBIOS/Build.ps1 index 32f97ded..b84902e9 100644 --- a/Source/HBIOS/Build.ps1 +++ b/Source/HBIOS/Build.ps1 @@ -201,8 +201,8 @@ if ($Platform -ne "UNA") "Building ${RomSize}KB ${RomName} ROM disk data file..." -# Use the blank ROM disk image to create a working ROM disk image -Copy-Item $BlankROM $RomDiskFile +# Create a blank ROM disk image to create a working ROM disk image +Set-Content -Value ([byte[]](0xE5) * (([int]${RomSize} * 1KB) - 128KB)) -Encoding byte -Path $RomDiskFile # Copy all files from the appropriate directory to the working ROM disk image cpmcp -f $RomFmt $RomDiskFile ../RomDsk/ROM_${RomSize}KB/*.* 0: diff --git a/Source/HBIOS/Config/RCZ80_kio.asm b/Source/HBIOS/Config/RCZ80_kio.asm index eeede184..8526fa8e 100644 --- a/Source/HBIOS/Config/RCZ80_kio.asm +++ b/Source/HBIOS/Config/RCZ80_kio.asm @@ -26,7 +26,6 @@ ; CPUOSC .SET 7372800 ; CPU OSC FREQ IN MHZ INTMODE .SET 2 ; INTERRUPTS: 0=NONE, 1=MODE 1, 2=MODE 2 -DEFSERCFG .SET SER_115200_8N1 ; DEFAULT SERIAL LINE CONFIG (SEE STD.ASM) ; KIOENABLE .SET TRUE ; ENABLE ZILOG KIO SUPPORT ; diff --git a/Source/HBIOS/Config/RCZ80_mt.asm b/Source/HBIOS/Config/RCZ80_mt.asm index 7006d750..bdd72e8d 100644 --- a/Source/HBIOS/Config/RCZ80_mt.asm +++ b/Source/HBIOS/Config/RCZ80_mt.asm @@ -28,4 +28,3 @@ ; SDENABLE .SET TRUE ; SD: ENABLE SD CARD DISK DRIVER (SD.ASM) SDMODE .SET SDMODE_MT ; SD: DRIVER MODE: SDMODE_[JUHA|N8|CSIO|PPI|UART|DSD|MK4|SC|MT] - diff --git a/Source/HBIOS/Config/RCZ80_wiz.asm b/Source/HBIOS/Config/RCZ80_wiz.asm deleted file mode 100644 index b61b2d0f..00000000 --- a/Source/HBIOS/Config/RCZ80_wiz.asm +++ /dev/null @@ -1,30 +0,0 @@ -; -;================================================================================================== -; RC2014 Z80 CONFIGURATION W/ WIZNET -;================================================================================================== -; -; THE COMPLETE SET OF DEFAULT CONFIGURATION SETTINGS FOR THIS PLATFORM ARE FOUND IN THE -; CFG_.ASM INCLUDED FILE WHICH IS FOUND IN THE PARENT DIRECTORY. THIS FILE CONTAINS -; COMMON CONFIGURATION SETTINGS THAT OVERRIDE THE DEFAULTS. IT IS INTENDED THAT YOU MAKE -; YOUR CUSTOMIZATIONS IN THIS FILE AND JUST INHERIT ALL OTHER SETTINGS FROM THE DEFAULTS. -; EVEN BETTER, YOU CAN MAKE A COPY OF THIS FILE WITH A NAME LIKE _XXX.ASM AND SPECIFY -; YOUR FILE IN THE BUILD PROCESS. -; -; THE SETTINGS BELOW ARE THE SETTINGS THAT ARE MOST COMMONLY MODIFIED FOR THIS PLATFORM. -; MANY OF THEM ARE EQUAL TO THE SETTINGS IN THE INCLUDED FILE, SO THEY DON'T REALLY DO -; ANYTHING AS IS. THEY ARE LISTED HERE TO MAKE IT EASY FOR YOU TO ADJUST THE MOST COMMON -; SETTINGS. -; -; N.B., SINCE THE SETTINGS BELOW ARE REDEFINING VALUES ALREADY SET IN THE INCLUDED FILE, -; TASM INSISTS THAT YOU USE THE .SET OPERATOR AND NOT THE .EQU OPERATOR BELOW. ATTEMPTING -; TO REDEFINE A VALUE WITH .EQU BELOW WILL CAUSE TASM ERRORS! -; -; PLEASE REFER TO THE CUSTOM BUILD INSTRUCTIONS (README.TXT) IN THE SOURCE DIRECTORY (TWO -; DIRECTORIES ABOVE THIS ONE). -; -#DEFINE PLATFORM_NAME "RC2014 (wiz)" -; -#include "Config/RCZ80_std.asm" -; -SDENABLE .SET TRUE -SDMODE .SET SDMODE_MT diff --git a/Source/HBIOS/Config/SBC_simh.asm b/Source/HBIOS/Config/SBC_simh.asm index dd7fad54..85600427 100644 --- a/Source/HBIOS/Config/SBC_simh.asm +++ b/Source/HBIOS/Config/SBC_simh.asm @@ -31,7 +31,6 @@ INTMODE .SET 1 ; INTERRUPTS: 0=NONE, 1=MODE 1, 2=MODE 2 HTIMENABLE .SET TRUE ; ENABLE SIMH TIMER SUPPORT ; SIMRTCENABLE .SET TRUE ; ENABLE SIMH CLOCK DRIVER (SIMRTC.ASM) -; DSRTCENABLE .SET FALSE ; DSRTC: ENABLE DS-1302 CLOCK DRIVER (DSRTC.ASM) ; HDSKENABLE .SET TRUE ; HDSK: ENABLE SIMH HDSK DISK DRIVER (HDSK.ASM) diff --git a/Source/HBIOS/Config/SCZ180_126.asm b/Source/HBIOS/Config/SCZ180_126.asm index 9bb78400..851f3476 100644 --- a/Source/HBIOS/Config/SCZ180_126.asm +++ b/Source/HBIOS/Config/SCZ180_126.asm @@ -37,6 +37,7 @@ HBIOS_MUTEX .SET FALSE ; ENABLE REENTRANT CALLS TO HBIOS (ADDS OVERHEAD) ASCIENABLE .SET TRUE ; ASCI: ENABLE Z180 ASCI SERIAL DRIVER (ASCI.ASM) ; ACIAENABLE .SET FALSE ; ACIA: ENABLE MOTOROLA 6850 ACIA DRIVER (ACIA.ASM) +; SIOENABLE .SET FALSE ; SIO: ENABLE ZILOG SIO SERIAL DRIVER (SIO.ASM) ; FDENABLE .SET FALSE ; FD: ENABLE FLOPPY DISK DRIVER (FD.ASM) diff --git a/Source/HBIOS/Config/SCZ180_130.asm b/Source/HBIOS/Config/SCZ180_130.asm index 7ee6370d..b3f22265 100644 --- a/Source/HBIOS/Config/SCZ180_130.asm +++ b/Source/HBIOS/Config/SCZ180_130.asm @@ -36,9 +36,14 @@ HBIOS_MUTEX .SET FALSE ; ENABLE REENTRANT CALLS TO HBIOS (ADDS OVERHEAD) ; LEDENABLE .SET TRUE ; ENABLE STATUS LED (SINGLE LED) ; +DIAGENABLE .SET FALSE ; ENABLES OUTPUT TO 8 BIT LED DIAGNOSTIC PORT +; +DSRTCENABLE .SET FALSE ; DSRTC: ENABLE DS-1302 CLOCK DRIVER (DSRTC.ASM) +; ASCIENABLE .SET TRUE ; ASCI: ENABLE Z180 ASCI SERIAL DRIVER (ASCI.ASM) ; ACIAENABLE .SET FALSE ; ACIA: ENABLE MOTOROLA 6850 ACIA DRIVER (ACIA.ASM) +; SIOENABLE .SET FALSE ; SIO: ENABLE ZILOG SIO SERIAL DRIVER (SIO.ASM) ; FDENABLE .SET FALSE ; FD: ENABLE FLOPPY DISK DRIVER (FD.ASM) diff --git a/Source/HBIOS/Config/ZETA2_std.asm b/Source/HBIOS/Config/ZETA2_std.asm index 5eeab428..7128d885 100644 --- a/Source/HBIOS/Config/ZETA2_std.asm +++ b/Source/HBIOS/Config/ZETA2_std.asm @@ -24,7 +24,7 @@ ; #include "cfg_zeta2.asm" ; -DEFSERCFG .SET DEFSERCFG | SER_RTS +UARTCFG .SET UARTCFG | SER_RTS ; CRTACT .SET TRUE ; ACTIVATE CRT (VDU,CVDU,PROPIO,ETC) AT STARTUP ; diff --git a/Source/HBIOS/MakeBlankROM.ps1 b/Source/HBIOS/MakeBlankROM.ps1 deleted file mode 100644 index 8f9e9d27..00000000 --- a/Source/HBIOS/MakeBlankROM.ps1 +++ /dev/null @@ -1,4 +0,0 @@ -# Create a "blank" rom disk image, filled with hex E5 -# -Set-Content -Value ([byte[]](0xE5) * (512KB - 128KB)) -Encoding byte -Path 'Blank512KB.dat' -Set-Content -Value ([byte[]](0xE5) * (1MB - 128KB)) -Encoding byte -Path 'Blank1024KB.dat' diff --git a/Source/HBIOS/Makefile b/Source/HBIOS/Makefile index c28edb77..6ee90216 100644 --- a/Source/HBIOS/Makefile +++ b/Source/HBIOS/Makefile @@ -10,7 +10,6 @@ OBJECTS += RCZ180_nat.rom RCZ180_nat.com OBJECTS += RCZ80_kio.rom RCZ80_kio.com OBJECTS += RCZ80_mt.rom RCZ80_mt.com OBJECTS += RCZ80_std.rom RCZ80_std.com -OBJECTS += RCZ80_wiz.rom RCZ80_wiz.com OBJECTS += SBC_simh.rom SBC_simh.com OBJECTS += SBC_std.rom SBC_std.com OBJECTS += SCZ180_126.rom SCZ180_126.com @@ -31,7 +30,7 @@ MOREDIFF = camel80.bin game.bin hbios_rom.bin nascom.bin prefix.bin usrrom.bin \ SUBDIRS = DEST = ../../Binary TOOLS =../../Tools -OTHERS = *.img *.rom *.com *.bin *.z80 cpm.sys zsys.sys Build.inc RomDisk.tmp font*.asm +OTHERS = *.img *.rom *.com *.bin *.z80 cpm.sys zsys.sys Build.inc RomDisk.tmp font*.asm *.dat include $(TOOLS)/Makefile.inc ifeq ($(DIFFMAKE),1) @@ -48,9 +47,6 @@ N8_std.rom: ROMSIZE=512 %.rom: bash Build.sh $(DIFFBUILD) $(shell echo $* | sed 's/_/ /') $(ROMSIZE) -#ZETA2_std.rom: -# bash Build.sh ZETA2 std 512 - hbios_rom.bin: hbios.asm build.inc $(TASM) -dROMBOOT hbios.asm hbios_rom.bin hbios_rom.lst diff --git a/Source/HBIOS/blank1024KB.dat b/Source/HBIOS/blank1024KB.dat deleted file mode 100644 index ac034386..00000000 --- a/Source/HBIOS/blank1024KB.dat +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/Source/HBIOS/blank512KB.dat b/Source/HBIOS/blank512KB.dat deleted file mode 100644 index 9f83fa94..00000000 --- a/Source/HBIOS/blank512KB.dat +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/Source/HBIOS/cfg_dyno.asm b/Source/HBIOS/cfg_dyno.asm index 8a9f251b..03e7aaa0 100644 --- a/Source/HBIOS/cfg_dyno.asm +++ b/Source/HBIOS/cfg_dyno.asm @@ -1,6 +1,6 @@ ; ;================================================================================================== -; ROMWBW 2.X CONFIGURATION DEFAULTS FOR RC2014 +; ROMWBW 2.X CONFIGURATION DEFAULTS FOR DYNO ;================================================================================================== ; ; THIS FILE CONTAINS THE FULL SET OF DEFAULT CONFIGURATION SETTINGS FOR THE PLATFORM @@ -82,6 +82,8 @@ ACIAENABLE .EQU FALSE ; ACIA: ENABLE MOTOROLA 6850 ACIA DRIVER (ACIA.ASM) ; SIOENABLE .EQU FALSE ; SIO: ENABLE ZILOG SIO SERIAL DRIVER (SIO.ASM) ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) NECENABLE .EQU FALSE ; NEC: ENABLE NEC UPD7220 VIDEO/KBD DRIVER (NEC.ASM) diff --git a/Source/HBIOS/cfg_ezz80.asm b/Source/HBIOS/cfg_ezz80.asm index 08a777d6..a4d7a083 100644 --- a/Source/HBIOS/cfg_ezz80.asm +++ b/Source/HBIOS/cfg_ezz80.asm @@ -97,6 +97,8 @@ SIO1BCLK .EQU 7372800 ; SIO 1B: OSC FREQ IN HZ, ZP=2457600/4915200, RC/SMB=7372 SIO1BDIV .EQU 1 ; SIO 1B: SERIAL CLOCK DIVIDER, RC2014/SMB=1, ZP=2/4/8/16/32/64/128/256 (X5) SIO1BCFG .EQU DEFSERCFG ; SIO 1B: SERIAL LINE CONFIG ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) NECENABLE .EQU FALSE ; NEC: ENABLE NEC UPD7220 VIDEO/KBD DRIVER (NEC.ASM) diff --git a/Source/HBIOS/cfg_master.asm b/Source/HBIOS/cfg_master.asm index ea5d2680..d2fd3eb6 100644 --- a/Source/HBIOS/cfg_master.asm +++ b/Source/HBIOS/cfg_master.asm @@ -93,11 +93,12 @@ BQRTC_BASE .EQU $50 ; BQRTC: I/O BASE ADDRESS ; UARTENABLE .EQU FALSE ; UART: ENABLE 8250/16550-LIKE SERIAL DRIVER (UART.ASM) UARTOSC .EQU 1843200 ; UART: OSC FREQUENCY IN MHZ +UARTCFG .EQU DEFSERCFG ; UART: LINE CONFIG FOR UART PORTS +UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED UARTSBC .EQU FALSE ; UART: AUTO-DETECT SBC/ZETA ONBOARD UART UARTCAS .EQU FALSE ; UART: AUTO-DETECT ECB CASSETTE UART UARTMFP .EQU FALSE ; UART: AUTO-DETECT MF/PIC UART UART4 .EQU FALSE ; UART: AUTO-DETECT 4UART UART -UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED ; ASCIENABLE .EQU FALSE ; ASCI: ENABLE Z180 ASCI SERIAL DRIVER (ASCI.ASM) ASCI0CFG .EQU DEFSERCFG ; ASCI 0: SERIAL LINE CONFIG @@ -137,6 +138,8 @@ SIO1BCLK .EQU CPUOSC ; SIO 1B: OSC FREQ IN HZ, ZP=2457600/4915200, RC/SMB=73728 SIO1BDIV .EQU 1 ; SIO 1B: SERIAL CLOCK DIVIDER, RC2014/SMB=1, ZP=2/4/8/16/32/64/128/256 (X5) SIO1BCFG .EQU DEFSERCFG ; SIO 1B: SERIAL LINE CONFIG ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) VDUSIZ .EQU V80X25 ; VDU: DISPLAY FORMAT [V80X24|V80X25|V80X30] CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) diff --git a/Source/HBIOS/cfg_mk4.asm b/Source/HBIOS/cfg_mk4.asm index 46f5301f..cd00fe1d 100644 --- a/Source/HBIOS/cfg_mk4.asm +++ b/Source/HBIOS/cfg_mk4.asm @@ -78,11 +78,12 @@ BQRTC_BASE .EQU $50 ; BQRTC: I/O BASE ADDRESS ; UARTENABLE .EQU TRUE ; UART: ENABLE 8250/16550-LIKE SERIAL DRIVER (UART.ASM) UARTOSC .EQU 1843200 ; UART: OSC FREQUENCY IN MHZ +UARTCFG .EQU DEFSERCFG ; UART: LINE CONFIG FOR UART PORTS +UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED UARTSBC .EQU FALSE ; UART: AUTO-DETECT SBC/ZETA ONBOARD UART UARTCAS .EQU TRUE ; UART: AUTO-DETECT ECB CASSETTE UART UARTMFP .EQU FALSE ; UART: AUTO-DETECT MF/PIC UART UART4 .EQU TRUE ; UART: AUTO-DETECT 4UART UART -UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED ; ASCIENABLE .EQU TRUE ; ASCI: ENABLE Z180 ASCI SERIAL DRIVER (ASCI.ASM) ASCI0CFG .EQU DEFSERCFG ; ASCI 0: SERIAL LINE CONFIG @@ -92,6 +93,8 @@ ACIAENABLE .EQU FALSE ; ACIA: ENABLE MOTOROLA 6850 ACIA DRIVER (ACIA.ASM) ; SIOENABLE .EQU FALSE ; SIO: ENABLE ZILOG SIO SERIAL DRIVER (SIO.ASM) ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) VDUSIZ .EQU V80X25 ; VDU: DISPLAY FORMAT [V80X24|V80X25|V80X30] CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) diff --git a/Source/HBIOS/cfg_n8.asm b/Source/HBIOS/cfg_n8.asm index 29ce4a5c..ae84317f 100644 --- a/Source/HBIOS/cfg_n8.asm +++ b/Source/HBIOS/cfg_n8.asm @@ -81,11 +81,12 @@ BQRTC_BASE .EQU $50 ; BQRTC: I/O BASE ADDRESS ; UARTENABLE .EQU TRUE ; UART: ENABLE 8250/16550-LIKE SERIAL DRIVER (UART.ASM) UARTOSC .EQU 1843200 ; UART: OSC FREQUENCY IN MHZ +UARTCFG .EQU DEFSERCFG ; UART: LINE CONFIG FOR UART PORTS +UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED UARTSBC .EQU FALSE ; UART: AUTO-DETECT SBC/ZETA ONBOARD UART UARTCAS .EQU TRUE ; UART: AUTO-DETECT ECB CASSETTE UART UARTMFP .EQU FALSE ; UART: AUTO-DETECT MF/PIC UART UART4 .EQU TRUE ; UART: AUTO-DETECT 4UART UART -UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED ; ASCIENABLE .EQU TRUE ; ASCI: ENABLE Z180 ASCI SERIAL DRIVER (ASCI.ASM) ASCI0CFG .EQU DEFSERCFG ; ASCI 0: SERIAL LINE CONFIG @@ -95,6 +96,8 @@ ACIAENABLE .EQU FALSE ; ACIA: ENABLE MOTOROLA 6850 ACIA DRIVER (ACIA.ASM) ; SIOENABLE .EQU FALSE ; SIO: ENABLE ZILOG SIO SERIAL DRIVER (SIO.ASM) ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) VDUSIZ .EQU V80X25 ; VDU: DISPLAY FORMAT [V80X24|V80X25|V80X30] CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) diff --git a/Source/HBIOS/cfg_rcz180.asm b/Source/HBIOS/cfg_rcz180.asm index d430084c..f09dc1d7 100644 --- a/Source/HBIOS/cfg_rcz180.asm +++ b/Source/HBIOS/cfg_rcz180.asm @@ -102,6 +102,8 @@ SIO1BCLK .EQU 7372800 ; SIO 1B: OSC FREQ IN HZ, ZP=2457600/4915200, RC/SMB=7372 SIO1BDIV .EQU 1 ; SIO 1B: SERIAL CLOCK DIVIDER, RC2014/SMB=1, ZP=2/4/8/16/32/64/128/256 (X5) SIO1BCFG .EQU SER_115200_8N1 ; SIO 1B: SERIAL LINE CONFIG ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) NECENABLE .EQU FALSE ; NEC: ENABLE NEC UPD7220 VIDEO/KBD DRIVER (NEC.ASM) diff --git a/Source/HBIOS/cfg_rcz80.asm b/Source/HBIOS/cfg_rcz80.asm index 59f86821..8087c810 100644 --- a/Source/HBIOS/cfg_rcz80.asm +++ b/Source/HBIOS/cfg_rcz80.asm @@ -106,6 +106,8 @@ SIO1BCLK .EQU CPUOSC ; SIO 1B: OSC FREQ IN HZ, ZP=2457600/4915200, RC/SMB=73728 SIO1BDIV .EQU 1 ; SIO 1B: SERIAL CLOCK DIVIDER, RC2014/SMB=1, ZP=2/4/8/16/32/64/128/256 (X5) SIO1BCFG .EQU DEFSERCFG ; SIO 1B: SERIAL LINE CONFIG ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) NECENABLE .EQU FALSE ; NEC: ENABLE NEC UPD7220 VIDEO/KBD DRIVER (NEC.ASM) diff --git a/Source/HBIOS/cfg_sbc.asm b/Source/HBIOS/cfg_sbc.asm index ab54d396..353b4796 100644 --- a/Source/HBIOS/cfg_sbc.asm +++ b/Source/HBIOS/cfg_sbc.asm @@ -72,11 +72,12 @@ BQRTC_BASE .EQU $50 ; BQRTC: I/O BASE ADDRESS ; UARTENABLE .EQU TRUE ; UART: ENABLE 8250/16550-LIKE SERIAL DRIVER (UART.ASM) UARTOSC .EQU 1843200 ; UART: OSC FREQUENCY IN MHZ +UARTCFG .EQU DEFSERCFG ; UART: LINE CONFIG FOR UART PORTS +UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED UARTSBC .EQU TRUE ; UART: AUTO-DETECT SBC/ZETA ONBOARD UART UARTCAS .EQU TRUE ; UART: AUTO-DETECT ECB CASSETTE UART UARTMFP .EQU TRUE ; UART: AUTO-DETECT MF/PIC UART UART4 .EQU TRUE ; UART: AUTO-DETECT 4UART UART -UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED ; ASCIENABLE .EQU FALSE ; ASCI: ENABLE Z180 ASCI SERIAL DRIVER (ASCI.ASM) ; @@ -95,6 +96,8 @@ SIO0BCLK .EQU 4915200 ; SIO 0B: OSC FREQ IN HZ, ZP=2457600/4915200, RC/SMB=7372 SIO0BDIV .EQU 8 ; SIO 0B: SERIAL CLOCK DIVIDER, RC2014/SMB=1, ZP=2/4/8/16/32/64/128/256 (X5) SIO0BCFG .EQU DEFSERCFG ; SIO 0B: SERIAL LINE CONFIG ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) VDUSIZ .EQU V80X25 ; VDU: DISPLAY FORMAT [V80X24|V80X25|V80X30] CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) diff --git a/Source/HBIOS/cfg_scz180.asm b/Source/HBIOS/cfg_scz180.asm index c37cc2d6..f1646cee 100644 --- a/Source/HBIOS/cfg_scz180.asm +++ b/Source/HBIOS/cfg_scz180.asm @@ -97,6 +97,8 @@ SIO1BCLK .EQU 7372800 ; SIO 1B: OSC FREQ IN HZ, ZP=2457600/4915200, RC/SMB=7372 SIO1BDIV .EQU 1 ; SIO 1B: SERIAL CLOCK DIVIDER, RC2014/SMB=1, ZP=2/4/8/16/32/64/128/256 (X5) SIO1BCFG .EQU SER_115200_8N1 ; SIO 1B: SERIAL LINE CONFIG ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) NECENABLE .EQU FALSE ; NEC: ENABLE NEC UPD7220 VIDEO/KBD DRIVER (NEC.ASM) diff --git a/Source/HBIOS/cfg_zeta.asm b/Source/HBIOS/cfg_zeta.asm index 85e7f731..087a251b 100644 --- a/Source/HBIOS/cfg_zeta.asm +++ b/Source/HBIOS/cfg_zeta.asm @@ -66,6 +66,8 @@ BQRTC_BASE .EQU $50 ; BQRTC: I/O BASE ADDRESS ; UARTENABLE .EQU TRUE ; UART: ENABLE 8250/16550-LIKE SERIAL DRIVER (UART.ASM) UARTOSC .EQU 1843200 ; UART: OSC FREQUENCY IN MHZ +UARTCFG .EQU DEFSERCFG ; UART: LINE CONFIG FOR UART PORTS +UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED UARTSBC .EQU TRUE ; UART: AUTO-DETECT SBC/ZETA ONBOARD UART UARTCAS .EQU FALSE ; UART: AUTO-DETECT ECB CASSETTE UART UARTMFP .EQU FALSE ; UART: AUTO-DETECT MF/PIC UART @@ -77,6 +79,8 @@ ACIAENABLE .EQU FALSE ; ACIA: ENABLE MOTOROLA 6850 ACIA DRIVER (ACIA.ASM) ; SIOENABLE .EQU FALSE ; SIO: ENABLE ZILOG SIO SERIAL DRIVER (SIO.ASM) ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) NECENABLE .EQU FALSE ; NEC: ENABLE NEC UPD7220 VIDEO/KBD DRIVER (NEC.ASM) diff --git a/Source/HBIOS/cfg_zeta2.asm b/Source/HBIOS/cfg_zeta2.asm index 19c48c62..0ea6c0eb 100644 --- a/Source/HBIOS/cfg_zeta2.asm +++ b/Source/HBIOS/cfg_zeta2.asm @@ -71,6 +71,8 @@ BQRTC_BASE .EQU $50 ; BQRTC: I/O BASE ADDRESS ; UARTENABLE .EQU TRUE ; UART: ENABLE 8250/16550-LIKE SERIAL DRIVER (UART.ASM) UARTOSC .EQU 1843200 ; UART: OSC FREQUENCY IN MHZ +UARTCFG .EQU DEFSERCFG ; UART: LINE CONFIG FOR UART PORTS +UARTCASSPD .EQU SER_300_8N1 ; UART: ECB CASSETTE UART DEFAULT SPEED UARTSBC .EQU TRUE ; UART: AUTO-DETECT SBC/ZETA ONBOARD UART UARTCAS .EQU FALSE ; UART: AUTO-DETECT ECB CASSETTE UART UARTMFP .EQU FALSE ; UART: AUTO-DETECT MF/PIC UART @@ -82,6 +84,8 @@ ACIAENABLE .EQU FALSE ; ACIA: ENABLE MOTOROLA 6850 ACIA DRIVER (ACIA.ASM) ; SIOENABLE .EQU FALSE ; SIO: ENABLE ZILOG SIO SERIAL DRIVER (SIO.ASM) ; +XIOCFG .EQU DEFSERCFG ; XIO: SERIAL LINE CONFIG +; VDUENABLE .EQU FALSE ; VDU: ENABLE VDU VIDEO/KBD DRIVER (VDU.ASM) CVDUENABLE .EQU FALSE ; CVDU: ENABLE CVDU VIDEO/KBD DRIVER (CVDU.ASM) NECENABLE .EQU FALSE ; NEC: ENABLE NEC UPD7220 VIDEO/KBD DRIVER (NEC.ASM) diff --git a/Source/HBIOS/dbgmon.asm b/Source/HBIOS/dbgmon.asm index d9b94dda..ddfe411e 100644 --- a/Source/HBIOS/dbgmon.asm +++ b/Source/HBIOS/dbgmon.asm @@ -819,7 +819,7 @@ COUT: ; ; OUTPUT CHARACTER TO CONSOLE VIA HBIOS LD E,A ; OUTPUT CHAR TO E - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOOUT ; HBIOS FUNC: OUTPUT CHAR RST 08 ; HBIOS OUTPUTS CHARACTER ; @@ -842,7 +842,7 @@ CIN: PUSH HL ; ; INPUT CHARACTER FROM CONSOLE VIA HBIOS - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOIN ; HBIOS FUNC: INPUT CHAR RST 08 ; HBIOS READS CHARACTER LD A,E ; MOVE CHARACTER TO A FOR RETURN @@ -865,7 +865,7 @@ CST: PUSH HL ; ; GET CONSOLE INPUT STATUS VIA HBIOS - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOIST ; HBIOS FUNC: INPUT STATUS RST 08 ; HBIOS RETURNS STATUS IN A ; diff --git a/Source/HBIOS/eastaegg.asm b/Source/HBIOS/eastaegg.asm index 66982bee..35c4c982 100644 --- a/Source/HBIOS/eastaegg.asm +++ b/Source/HBIOS/eastaegg.asm @@ -175,7 +175,7 @@ mandel_end ld hl, finished ; Print finished-message ; GET CONSOLE INPUT STATUS VIA HBIOS waitch #IF (BIOS == BIOS_WBW) - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOIN ; HBIOS FUNC: INPUT CHAR RST 08 ; DO IT @@ -215,7 +215,7 @@ _putc PUSH DE PUSH HL LD E,A ; OUTPUT CHAR TO E - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOOUT ; HBIOS FUNC: OUTPUT CHAR RST 08 ; HBIOS OUTPUTS CHARACTDR POP HL diff --git a/Source/HBIOS/hbios.asm b/Source/HBIOS/hbios.asm index 2fb9e56b..6e696cb6 100644 --- a/Source/HBIOS/hbios.asm +++ b/Source/HBIOS/hbios.asm @@ -3423,8 +3423,10 @@ PS_DISK: ; UNIT COLUMN PRTS("Disk $") LD A,C ; MOVE UNIT NUM TO A - CALL PRTDECB ; PRINT IT, ASSUME SINGLE DIGIT - PRTS(" $") ; PAD TO NEXT COLUMN + CALL PRTDECB ; PRINT IT + CP 10 ; CHECK FOR MULTIPLE DIGITS + CALL C,PC_SPACE ; EXTRA SPACE IF NEEDED + PRTS(" $") ; PAD TO NEXT COLUMN ; ; DEVICE COLUMN LD B,BF_DIODEVICE ; FUNC=GET DEVICE INFO, UNIT NUM STILL IN C diff --git a/Source/HBIOS/hbios.inc b/Source/HBIOS/hbios.inc index d47d53f9..97dc9d14 100644 --- a/Source/HBIOS/hbios.inc +++ b/Source/HBIOS/hbios.inc @@ -85,6 +85,8 @@ BF_SYSINT_INFO .EQU $00 ; GET INTERRUPT SYSTEM INFO BF_SYSINT_GET .EQU $10 ; GET INT VECTOR ADDRESS BF_SYSINT_SET .EQU $20 ; SET INT VECTOR ADDRESS ; +CIO_CONSOLE .EQU $80 ; CIO UNIT NUM FOR CUR CON +; ; CHAR DEVICE IDS ; CIODEV_UART .EQU $00 @@ -96,7 +98,6 @@ CIODEV_SIO .EQU $50 CIODEV_ACIA .EQU $60 CIODEV_PIO .EQU $70 CIODEV_UF .EQU $80 -CIODEV_CONSOLE .EQU $D0 ; ; SUB TYPES OF CHAR DEVICES ; diff --git a/Source/HBIOS/nascom.asm b/Source/HBIOS/nascom.asm index 28bbee1b..1449c741 100644 --- a/Source/HBIOS/nascom.asm +++ b/Source/HBIOS/nascom.asm @@ -1349,7 +1349,7 @@ TSTBRK: PUSH DE PUSH HL - LD C,CIODEV_CONSOLE; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOIST ; HBIOS FUNC: INPUT STATUS RST 08 ; HBIOS RETURNS STATUS IN A @@ -1363,7 +1363,7 @@ TSTBRK: ; INPUT CHARACTER FROM CONSOLE VIA HBIOS - LD C,CIODEV_CONSOLE; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOIN ; HBIOS FUNC: INPUT CHAR RST 08 ; HBIOS READS CHARACTDR LD A,E ; MOVE CHARACTER TO A FOR RETURN @@ -1387,7 +1387,7 @@ STALL: ; Wait for key ; ; INPUT CHARACTER FROM CONSOLE VIA HBIOS ; - LD C,CIODEV_CONSOLE; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOIN ; HBIOS FUNC: INPUT CHAR RST 08 ; HBIOS READS CHARACTDR LD A,E ; MOVE CHARACTER TO A FOR RETURN @@ -4463,7 +4463,7 @@ GETINP: PUSH BC PUSH DE PUSH HL - LD C,CIODEV_CONSOLE; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOIN ; HBIOS FUNC: INPUT CHAR RST 08 ; HBIOS READS CHARACTDR LD A,E ; MOVE CHARACTER TO A FOR RETURN @@ -4706,7 +4706,7 @@ MONOUT: PUSH DE PUSH HL LD E,A ; OUTPUT CHAR TO E - LD C,CIODEV_CONSOLE; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOOUT ; HBIOS FUNC: OUTPUT CHAR RST 08 ; HBIOS OUTPUTS CHARACTDR POP HL ; RESTORE ALL REGISTERS diff --git a/Source/HBIOS/ppp.asm b/Source/HBIOS/ppp.asm index 2f0cbf1d..0b45b1eb 100644 --- a/Source/HBIOS/ppp.asm +++ b/Source/HBIOS/ppp.asm @@ -691,7 +691,7 @@ PPPSD_DEVICE: PPPSD_MEDIA: ; REINITIALIZE THE CARD HERE TO DETERMINE PRESENCE CALL PPPSD_INITCARD -#IF (PPPSDTRACE == 1) +#IF (PPPSDTRACE >= 3) CALL PPPSD_PRTERR ; PRINT ANY ERRORS #ENDIF LD E,MID_HD ; ASSUME WE ARE OK diff --git a/Source/HBIOS/prp.asm b/Source/HBIOS/prp.asm index 9bd1de1b..bb95606f 100644 --- a/Source/HBIOS/prp.asm +++ b/Source/HBIOS/prp.asm @@ -126,7 +126,7 @@ PRPCON_COLS .EQU 80 ; PROPELLER VGA DISPLAY COLS PRPCON_INIT: ; CALL NEWLINE - PRTS("PRPCON: $") + PRTS("PRPCON:$") ; ; DISPLAY CONSOLE DIMENSIONS CALL PC_SPACE @@ -547,7 +547,7 @@ PRPSD_DEVICE: PRPSD_MEDIA: ; REINITIALIZE THE CARD HERE CALL PRPSD_INITCARD -#IF (PRPSDTRACE == 1) +#IF (PRPSDTRACE >= 3) CALL PRPSD_PRTERR ; PRINT ANY ERRORS #ENDIF LD E,MID_HD ; ASSUME WE ARE OK diff --git a/Source/HBIOS/romldr.asm b/Source/HBIOS/romldr.asm index 844a1de4..6ce3ce6c 100644 --- a/Source/HBIOS/romldr.asm +++ b/Source/HBIOS/romldr.asm @@ -1050,7 +1050,7 @@ COUT: ; ; OUTPUT CHARACTER TO CONSOLE VIA HBIOS LD E,A ; OUTPUT CHAR TO E - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOOUT ; HBIOS FUNC: OUTPUT CHAR RST 08 ; HBIOS OUTPUTS CHARACTDR ; @@ -1070,7 +1070,7 @@ CIN: PUSH HL ; ; INPUT CHARACTER FROM CONSOLE VIA HBIOS - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOIN ; HBIOS FUNC: INPUT CHAR RST 08 ; HBIOS READS CHARACTDR LD A,E ; MOVE CHARACTER TO A FOR RETURN @@ -1090,7 +1090,7 @@ CST: PUSH HL ; ; GET CONSOLE INPUT STATUS VIA HBIOS - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C LD B,BF_CIOIST ; HBIOS FUNC: INPUT STATUS RST 08 ; HBIOS RETURNS STATUS IN A ; diff --git a/Source/HBIOS/tastybasic.asm b/Source/HBIOS/tastybasic.asm index 7d009815..243cce39 100644 --- a/Source/HBIOS/tastybasic.asm +++ b/Source/HBIOS/tastybasic.asm @@ -11,7 +11,7 @@ ; ; Tasty Basic is distributed in the hope that it will be useful, ; but WITHOUT ANY WARRANTY; without even the implied warranty of -; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ; GNU General Public License for more details. ; ; You should have received a copy of the GNU General Public License @@ -24,70 +24,70 @@ #define dwa(addr) .db (addr >> 8) + 080h\ .db addr & 0ffh -ctrlc .equ 03h -bs .equ 08h -lf .equ 0ah -cr .equ 0dh -ctrlo .equ 0fh -ctrlu .equ 15h +ctrlc .equ 03h +bs .equ 08h +lf .equ 0ah +cr .equ 0dh +ctrlo .equ 0fh +ctrlu .equ 15h -#ifdef ZEMU ; Z80 Emulator -tty_data .equ 7ch -tty_status .equ 7dh -rx_full .equ 1 -tx_empty .equ 0 -TBC_LOC .equ 0 -#else ; RomWBW -#include "std.asm" +#ifdef ZEMU ; Z80 Emulator +tty_data .equ 7ch +tty_status .equ 7dh +rx_full .equ 1 +tx_empty .equ 0 +TBC_LOC .equ 0 +#else ; RomWBW +#include "std.asm" #endif - .org TBC_LOC + .org TBC_LOC start: - ld sp,stack ; ** Cold Start ** - ld a,0ffh - jp init + ld sp,stack ; ** Cold Start ** + ld a,0ffh + jp init testc: - ex (sp),hl ; ** TestC ** - call skipspace ; ignore spaces - cp (hl) ; test character - inc hl ; compare the byte that follows the - jr z,tc1 ; call instruction with the text pointer - push bc - ld c,(hl) ; if not equal, ad the seond byte - ld b, 0h ; that follows the call to the old pc - add hl,bc - pop bc - dec de + ex (sp),hl ; ** TestC ** + call skipspace ; ignore spaces + cp (hl) ; test character + inc hl ; compare the byte that follows the + jr z,tc1 ; call instruction with the text pointer + push bc + ld c,(hl) ; if not equal, ad the seond byte + ld b, 0h ; that follows the call to the old pc + add hl,bc + pop bc + dec de tc1: - inc de ; if equal, skip those bytes - inc hl ; and continue - ex (sp),hl - ret + inc de ; if equal, skip those bytes + inc hl ; and continue + ex (sp),hl + ret skipspace: - ld a,(de) ; ** SkipSpace ** - cp ' ' ; ignore spaces - ret nz ; in text (where de points) - inc de ; and return the first non-blank - jp skipspace ; character in A + ld a,(de) ; ** SkipSpace ** + cp ' ' ; ignore spaces + ret nz ; in text (where de points) + inc de ; and return the first non-blank + jp skipspace ; character in A expr: - call expr2 ; ** Expr ** - push hl ; evaluate expression - jp expr1 + call expr2 ; ** Expr ** + push hl ; evaluate expression + jp expr1 comp: - ld a,h ; ** Compare ** - cp d ; compare hl with de - ret nz ; return c and z flags - ld a,l ; old a is lost - cp e - ret + ld a,h ; ** Compare ** + cp d ; compare hl with de + ret nz ; return c and z flags + ld a,l ; old a is lost + cp e + ret finish: - pop af ; ** Finish ** - call fin ; check end of command - jp qwhat + pop af ; ** Finish ** + call fin ; check end of command + jp qwhat ;************************************************************* ; @@ -99,7 +99,7 @@ finish: ; 'IF' IS FOLLOWED BY AN EXPR. AS A CONDITION AND ONE OR MORE ; COMMANDS (INCLUDING OTHER 'IF'S) SEPERATED BY SEMI-COLONS. ; NOTE THAT THE WORD 'THEN' IS NOT USED. TBI EVALUATES THE -; EXPR. IF IT IS NON-ZERO, EXECUTION CONTINUES. IF THE +; EXPR. IF IT IS NON-ZERO, EXECUTION CONTINUES. IF THE ; EXPR. IS ZERO, THE COMMANDS THAT FOLLOWS ARE IGNORED AND ; EXECUTION CONTINUES AT THE NEXT LINE. ; @@ -108,10 +108,10 @@ finish: ; DOUBLE QUOTES, OR IS A BACK-ARROW, IT HAS THE SAME EFFECT AS ; IN 'PRINT'. IF AN ITEM IS A VARIABLE, THIS VARIABLE NAME IS ; PRINTED OUT FOLLOWED BY A COLON. THEN TBI WAITS FOR AN -; EXPR. TO BE TYPED IN. THE VARIABLE IS THEN SET TO THE +; EXPR. TO BE TYPED IN. THE VARIABLE IS THEN SET TO THE ; VALUE OF THIS EXPR. IF THE VARIABLE IS PROCEDED BY A STRING ; (AGAIN IN SINGLE OR DOUBLE QUOTES), THE STRING WILL BE -; PRINTED FOLLOWED BY A COLON. TBI THEN WAITS FOR INPUT EXPR. +; PRINTED FOLLOWED BY A COLON. TBI THEN WAITS FOR INPUT EXPR. ; AND SET THE VARIABLE TO THE VALUE OF THE EXPR. ; ; IF THE INPUT EXPR. IS INVALID, TBI WILL PRINT "WHAT?", @@ -126,90 +126,90 @@ finish: ; THIS IS DONE BY 'DEFLT'. ;************************************************************* rem: - ld hl,0000h ; ** Rem ** - jr if1 ; this is like 'IF 0' + ld hl,0000h ; ** Rem ** + jr if1 ; this is like 'IF 0' iff: - call expr ; ** If ** + call expr ; ** If ** if1: - ld a,h ; is the expr = 0? - or l - jp nz,runsml ; no, continue - call findskip ; yes, skip rest of line - jp nc,runtsl ; and run the next line - jp rstart ; if no, restart + ld a,h ; is the expr = 0? + or l + jp nz,runsml ; no, continue + call findskip ; yes, skip rest of line + jp nc,runtsl ; and run the next line + jp rstart ; if no, restart inputerror: - ld hl,(stkinp) ; ** InputError ** - ld sp,hl ; restore old sp and old current - pop hl - ld (current),hl - pop de ; and old text pointer - pop de ; redo current + ld hl,(stkinp) ; ** InputError ** + ld sp,hl ; restore old sp and old current + pop hl + ld (current),hl + pop de ; and old text pointer + pop de ; redo current input: - push de ; ** Input ** - call qtstg ; is next item a string? - jp ip2 ; no - call testvar ; yes and followed by a variable? - jp c,ip4 ; no - jp ip3 ; yes, input variable + push de ; ** Input ** + call qtstg ; is next item a string? + jp ip2 ; no + call testvar ; yes and followed by a variable? + jp c,ip4 ; no + jp ip3 ; yes, input variable ip2: - push de ; save for printstr - call testvar ; must be variable - jp c,qwhat ; no, what? - ld a,(de) ; prepare for printstr - ld c,a - sub a - ld (de),a - pop de - call printstr ; print string as prompt - ld a,c ; restore text - dec de - ld (de),a + push de ; save for printstr + call testvar ; must be variable + jp c,qwhat ; no, what? + ld a,(de) ; prepare for printstr + ld c,a + sub a + ld (de),a + pop de + call printstr ; print string as prompt + ld a,c ; restore text + dec de + ld (de),a ip3: - push de ; save text pointer - ex de,hl - ld hl,(current) ; also save current - push hl - ld hl,input - ld (current),hl - ld hl,0000h - add hl,sp - ld (stkinp),hl - push de - ld a,':' - call getline - ld de,buffer - call expr - nop - nop - nop - pop de - ex de,hl - ld (hl),e - inc hl - ld (hl),d - pop hl - ld (current),hl - pop de + push de ; save text pointer + ex de,hl + ld hl,(current) ; also save current + push hl + ld hl,input + ld (current),hl + ld hl,0000h + add hl,sp + ld (stkinp),hl + push de + ld a,':' + call getline + ld de,buffer + call expr + nop + nop + nop + pop de + ex de,hl + ld (hl),e + inc hl + ld (hl),d + pop hl + ld (current),hl + pop de ip4: - pop af ; purge stack - call testc ; is next character ','? - .db ',' - .db ip5-$-1 - jr input ; yes, more items + pop af ; purge stack + call testc ; is next character ','? + .db ',' + .db ip5-$-1 + jr input ; yes, more items ip5: - call finish + call finish deflt: - ld a,(de) ; ** DEFLT ** - cp cr ; empty line is fine - jr z,lt1 ; else it's 'LET' + ld a,(de) ; ** DEFLT ** + cp cr ; empty line is fine + jr z,lt1 ; else it's 'LET' let: - call setval ; ** Let ** - call testc ; set value to var - .db ',' - .db lt1-$-1 - jr let ; item by item + call setval ; ** Let ** + call testc ; set value to var + .db ',' + .db lt1-$-1 + jr let ; item by item lt1: - call finish + call finish ;************************************************************* ; @@ -222,310 +222,310 @@ lt1: ; ;************************************************************* peek: - call parn ; ** Peek(expr) ** - ld a,h ; expression must be positive - or a - jp m,qhow - ld a,(hl) - ld h,0 - ld l,a - ret + call parn ; ** Peek(expr) ** + ld a,h ; expression must be positive + or a + jp m,qhow + ld a,(hl) + ld h,0 + ld l,a + ret poke: - call expr ; ** Poke ** - ld a,h ; address must be positive - or a - jp m,qhow - push hl - call testc ; is next char a comma? - .db ',' - .db pk1-$-1 ; what, no? - call expr ; get value to store - ld a,0 ; is it > 255? - cp h - jp z,pk2 ; no, all good - pop hl - jp m,qhow + call expr ; ** Poke ** + ld a,h ; address must be positive + or a + jp m,qhow + push hl + call testc ; is next char a comma? + .db ',' + .db pk1-$-1 ; what, no? + call expr ; get value to store + ld a,0 ; is it > 255? + cp h + jp z,pk2 ; no, all good + pop hl + jp m,qhow pk2: - ld a,l ; save value - pop hl - ld (hl),a - call finish + ld a,l ; save value + pop hl + ld (hl),a + call finish pk1: - pop hl - jp qwhat + pop hl + jp qwhat usrexec: - call parn ; ** Usr(expr) ** - push de - ex de,hl - ld hl,ue1 - push hl - ld ix,(usrptr) - jp (ix) + call parn ; ** Usr(expr) ** + push de + ex de,hl + ld hl,ue1 + push hl + ld ix,(usrptr) + jp (ix) ue1: - ex de,hl - pop de - ret + ex de,hl + pop de + ret ;************************************************************* ; ; *** EXPR *** ; ; 'EXPR' EVALUATES ARITHMETICAL OR LOGICAL EXPRESSIONS. ; :: -; +; ; WHERE IS ONE OF THE OPERATORS IN TAB8 AND THE ; RESULT OF THESE OPERATIONS IS 1 IF TRUE AND 0 IF FALSE. ; ::=(+ OR -)(+ OR -)(....) ; WHERE () ARE OPTIONAL AND (....) ARE OPTIONAL REPEATS. ; ::=(* OR />)(....) ; ::= -; -; () +; +; () ; IS RECURSIVE SO THAT VARIABLE '@' CAN HAVE AN ; AS INDEX, FUNCTIONS CAN HAVE AN AS ARGUMENTS, AND ; CAN BE AN IN PARANTHESE. ;************************************************************* expr1: - ld hl,tab8-1 ; look up rel.op - jp exec ; go do it + ld hl,tab8-1 ; look up rel.op + jp exec ; go do it xp11: - call xp18 ; rel.op.'>=' - ret c ; no, return hl=0 - ld l,a ; yes, return hl=1 - ret + call xp18 ; rel.op.'>=' + ret c ; no, return hl=0 + ld l,a ; yes, return hl=1 + ret xp12: - call xp18 ; rel.op.'#' - ret z ; no, return hl=0 - ld l,a ; yes, return hl=1 - ret + call xp18 ; rel.op.'#' + ret z ; no, return hl=0 + ld l,a ; yes, return hl=1 + ret xp13: - call xp18 ; rel.op.'>' - ret z ; no - ret c ; also, no - ld l,a ; yes, return hl=1 - ret + call xp18 ; rel.op.'>' + ret z ; no + ret c ; also, no + ld l,a ; yes, return hl=1 + ret xp14: - call xp18 ; rel.op.'<=' - ld l,a ; set hl=1 - ret z ; yes, return hl=1 - ret c - ld l,h ; else set hl=0 - ret + call xp18 ; rel.op.'<=' + ld l,a ; set hl=1 + ret z ; yes, return hl=1 + ret c + ld l,h ; else set hl=0 + ret xp15: - call xp18 ; rel.op.'=' - ret nz ; no, return hl=0 - ld l,a ; else hl=1 - ret + call xp18 ; rel.op.'=' + ret nz ; no, return hl=0 + ld l,a ; else hl=1 + ret xp16: - call xp18 ; rel.op.'<' - ret nc ; no, return hl=0 - ld l,a ; else hl=1 - ret + call xp18 ; rel.op.'<' + ret nc ; no, return hl=0 + ld l,a ; else hl=1 + ret xp17: - pop hl ; not rel.op - ret ; return hl= + pop hl ; not rel.op + ret ; return hl= xp18: - ld a,c ; routine for all rel.ops - pop hl - pop bc - push hl - push bc ; reverse top of stack - ld c,a - call expr2 ; get second - ex de,hl ; value now in de - ex (sp),hl ; first in hl - call ckhlde ; compare them - pop de ; restore text pointer - ld hl,0000h ; set hl=0, a=1 - ld a,1 - ret + ld a,c ; routine for all rel.ops + pop hl + pop bc + push hl + push bc ; reverse top of stack + ld c,a + call expr2 ; get second + ex de,hl ; value now in de + ex (sp),hl ; first in hl + call ckhlde ; compare them + pop de ; restore text pointer + ld hl,0000h ; set hl=0, a=1 + ld a,1 + ret expr2: - call testc ; is it minus sign? - .db '-' - .db xp21-$-1 - ld hl,0000h ; yes, fake 0 - - jr xp26 ; treat like subtract + call testc ; is it minus sign? + .db '-' + .db xp21-$-1 + ld hl,0000h ; yes, fake 0 - + jr xp26 ; treat like subtract xp21: - call testc ; is it plus sign? - .db '+' - .db xp22-$-1 + call testc ; is it plus sign? + .db '+' + .db xp22-$-1 xp22: - call expr3 ; first + call expr3 ; first xp23: - call testc ; addition? - .db '+' - .db xp25-$-1 - push hl ; yes, save value - call expr3 ; get second + call testc ; addition? + .db '+' + .db xp25-$-1 + push hl ; yes, save value + call expr3 ; get second xp24: - ex de,hl ; 2nd in de - ex (sp),hl ; 1st in hl - ld a,h ; compare sign - xor d - ld a,d - add hl,de - pop de ; restore text pointer - jp m,xp23 ; first and second sign differ - xor h ; first and second sign are equal - jp p,xp23 ; so is the result - jp qhow ; else we have overflow + ex de,hl ; 2nd in de + ex (sp),hl ; 1st in hl + ld a,h ; compare sign + xor d + ld a,d + add hl,de + pop de ; restore text pointer + jp m,xp23 ; first and second sign differ + xor h ; first and second sign are equal + jp p,xp23 ; so is the result + jp qhow ; else we have overflow xp25: - call testc ; subtract? - .db '-' - .db xp42-$-1 + call testc ; subtract? + .db '-' + .db xp42-$-1 xp26: - push hl ; yes, save first - call expr3 ; get second - call changesign ; negate - jr xp24 ; and add them + push hl ; yes, save first + call expr3 ; get second + call changesign ; negate + jr xp24 ; and add them expr3: - call expr4 ; get first expr4 + call expr4 ; get first expr4 xp31: - call testc ; multiply? - .db '*' - .db xp34-$-1 - push hl ; yes, save first and get second - call expr4 ; - ld b,0 ; clear b for sign - call checksign - ex (sp),hl ; first in hl - call checksign ; check sign of first - ex de,hl - ex (sp),hl - ld a,h ; is hl > 255? - or a - jr z,xp32 ; no - ld a,d ; yes, what about de - or d - ex de,hl - jp nz,ahow + call testc ; multiply? + .db '*' + .db xp34-$-1 + push hl ; yes, save first and get second + call expr4 ; + ld b,0 ; clear b for sign + call checksign + ex (sp),hl ; first in hl + call checksign ; check sign of first + ex de,hl + ex (sp),hl + ld a,h ; is hl > 255? + or a + jr z,xp32 ; no + ld a,d ; yes, what about de + or d + ex de,hl + jp nz,ahow xp32: - ld a,l - ld hl,0000h - or a - jr z,xp35 + ld a,l + ld hl,0000h + or a + jr z,xp35 xp33: - add hl,de - jp c,ahow - dec a - jr nz,xp33 - jr xp35 + add hl,de + jp c,ahow + dec a + jr nz,xp33 + jr xp35 xp34: - call testc ; divide - .db '/' - .db xp42-$-1 - push hl ; yes, save first - call expr4 ; and get the second one - ld b,0h ; clear b for sign - call checksign ; check sign of the second - ex (sp),hl ; get the first in hl - call checksign ; check sign of first - ex de,hl - ex (sp),hl - ex de,hl - ld a,d ; divide by 0? - or e - jp z,ahow ; err...how? - push bc ; else save sign - call divide - ld h,b - ld l,c - pop bc ; retrieve sign + call testc ; divide + .db '/' + .db xp42-$-1 + push hl ; yes, save first + call expr4 ; and get the second one + ld b,0h ; clear b for sign + call checksign ; check sign of the second + ex (sp),hl ; get the first in hl + call checksign ; check sign of first + ex de,hl + ex (sp),hl + ex de,hl + ld a,d ; divide by 0? + or e + jp z,ahow ; err...how? + push bc ; else save sign + call divide + ld h,b + ld l,c + pop bc ; retrieve sign xp35: - pop de ; and text pointer - ld a,h ; hl must be positive - or a - jp m,qhow ; else it's overflow - ld a,b - or a - call m,changesign ; change sign if needed - jp xp31 ; look for more terms + pop de ; and text pointer + ld a,h ; hl must be positive + or a + jp m,qhow ; else it's overflow + ld a,b + or a + call m,changesign ; change sign if needed + jp xp31 ; look for more terms expr4: - ld hl,tab4-1 ; find function in tab4 - jp exec ; and execute it + ld hl,tab4-1 ; find function in tab4 + jp exec ; and execute it xp40: - call testvar - jr c,xp41 ; nor a variable - ld a,(hl) - inc hl - ld h,(hl) ; value in hl - ld l,a - ret + call testvar + jr c,xp41 ; nor a variable + ld a,(hl) + inc hl + ld h,(hl) ; value in hl + ld l,a + ret xp41: - call testnum ; or is it a number - ld a,b ; number of digits - or a - ret nz ; ok + call testnum ; or is it a number + ld a,b ; number of digits + or a + ret nz ; ok parn: - call testc - .db '(' - .db xp43-$-1 - call expr ; "(expr)" - call testc - .db ')' - .db xp43-$-1 + call testc + .db '(' + .db xp43-$-1 + call expr ; "(expr)" + call testc + .db ')' + .db xp43-$-1 xp42: - ret + ret xp43: - jp qwhat ; what? + jp qwhat ; what? rnd: - call parn ; ** Rnd(expr) ** - ld a,h ; expression must be positive - or a - jp m,qhow - or l ; and non-zero - jp z,qhow - push de ; save de and hl - push hl - ld hl,(rndptr) ; get memory as random number - ld de,LST_ROM - call comp - jr c,ra1 ; wrap around if last - ld hl,start + call parn ; ** Rnd(expr) ** + ld a,h ; expression must be positive + or a + jp m,qhow + or l ; and non-zero + jp z,qhow + push de ; save de and hl + push hl + ld hl,(rndptr) ; get memory as random number + ld de,LST_ROM + call comp + jr c,ra1 ; wrap around if last + ld hl,start ra1: - ld e,(hl) - inc hl - ld d,(hl) - ld (rndptr),hl - pop hl - ex de,hl - push bc - call divide ; rnd(n)=mod(m,n)+1 - pop bc - pop de - inc hl - ret + ld e,(hl) + inc hl + ld d,(hl) + ld (rndptr),hl + pop hl + ex de,hl + push bc + call divide ; rnd(n)=mod(m,n)+1 + pop bc + pop de + inc hl + ret abs: - call parn ; ** Abs (expr) ** - dec de - call checksign - inc de - ret + call parn ; ** Abs (expr) ** + dec de + call checksign + inc de + ret size: - ld hl,(textunfilled) ; ** Size ** - push de ; get the number of free bytes between - ex de,hl ; and varbegin - ld hl,varbegin - call subde - pop de - ret + ld hl,(textunfilled) ; ** Size ** + push de ; get the number of free bytes between + ex de,hl ; and varbegin + ld hl,varbegin + call subde + pop de + ret clrvars: - ld hl,(textunfilled) ; ** ClearVars** - push de ; get the number of bytes available - ex de,hl ; for variable storge - ld hl,varend - call subde - ld b,h ; and save in bc - ld c,l - ld hl,(textunfilled) ; clear the first byte - ld d,h - ld e,l - inc de - ld (hl),0h - ldir ; and repeat for all the others - pop de - ret + ld hl,(textunfilled) ; ** ClearVars** + push de ; get the number of bytes available + ex de,hl ; for variable storge + ld hl,varend + call subde + ld b,h ; and save in bc + ld c,l + ld hl,(textunfilled) ; clear the first byte + ld d,h + ld e,l + inc de + ld (hl),0h + ldir ; and repeat for all the others + pop de + ret ;************************************************************* ; @@ -535,7 +535,7 @@ clrvars: ; ; 'SUBDE' SUBSTRACTS DE FROM HL ; -; 'CHKSGN' CHECKS SIGN OF HL. IF +, NO CHANGE. IF -, CHANGE +; 'CHKSGN' CHECKS SIGN OF HL. IF +, NO CHANGE. IF -, CHANGE ; SIGN AND FLIP SIGN OF B. ; ; 'CHGSGN' CHECKS SIGN N OF HL AND B UNCONDITIONALLY. @@ -545,85 +545,85 @@ clrvars: ; CASE, HL DE ARE THEN COMPARED TO SET THE FLAGS. ;************************************************************* divide: - push hl ; ** Divide ** - ld l,h ; divide h by de - ld h,0h - call dv1 - ld b,c ; save result in b - ld a,l ; (remainder + l) / de - pop hl - ld h,a + push hl ; ** Divide ** + ld l,h ; divide h by de + ld h,0h + call dv1 + ld b,c ; save result in b + ld a,l ; (remainder + l) / de + pop hl + ld h,a dv1: - ld c,0ffh ; result in c + ld c,0ffh ; result in c dv2: - inc c ; dumb routine - call subde ; divide using subtract and count - jr nc,dv2 - add hl,de - ret + inc c ; dumb routine + call subde ; divide using subtract and count + jr nc,dv2 + add hl,de + ret subde: - ld a,l ; ** subde ** - sub e ; subtract de from hl - ld l,a - ld a,h - sbc a,d - ld h,a - ret + ld a,l ; ** subde ** + sub e ; subtract de from hl + ld l,a + ld a,h + sbc a,d + ld h,a + ret checksign: - ld a,h ; ** CheckSign ** - or a ; check sign of hl - ret p + ld a,h ; ** CheckSign ** + or a ; check sign of hl + ret p changesign: - ld a,h ; ** ChangeSign ** - or l ; check if hl is zero - jp nz,cs1 ; no, try to change sign - ret ; yes, return + ld a,h ; ** ChangeSign ** + or l ; check if hl is zero + jp nz,cs1 ; no, try to change sign + ret ; yes, return cs1: - ld a,h ; change sign of hl - push af - cpl - ld h,a - ld a,l - cpl - ld l,a - inc hl - pop af - xor h - jp p,qhow - ld a,b ; and also flip b - xor 80h - ld b,a - ret + ld a,h ; change sign of hl + push af + cpl + ld h,a + ld a,l + cpl + ld l,a + inc hl + pop af + xor h + jp p,qhow + ld a,b ; and also flip b + xor 80h + ld b,a + ret ckhlde: - ld a,h ; same sign? - xor d ; yes, compare - jp p,ck1 ; no, exchange and compare - ex de,hl + ld a,h ; same sign? + xor d ; yes, compare + jp p,ck1 ; no, exchange and compare + ex de,hl ck1: - call comp - ret + call comp + ret ;************************************************************* ; ; *** SETVAL *** FIN *** ENDCHK *** & ERROR (& FRIENDS) *** ; ; "SETVAL" EXPECTS A VARIABLE, FOLLOWED BY AN EQUAL SIGN AND -; THEN AN EXPR. IT EVALUATES THE EXPR. AND SET THE VARIABLE +; THEN AN EXPR. IT EVALUATES THE EXPR. AND SET THE VARIABLE ; TO THAT VALUE. ; ; "FIN" CHECKS THE END OF A COMMAND. IF IT ENDED WITH ":", -; EXECUTION CONTINUES. IF IT ENDED WITH A CR, IT FINDS THE +; EXECUTION CONTINUES. IF IT ENDED WITH A CR, IT FINDS THE ; NEXT LINE AND CONTINUE FROM THERE. ; ; "ENDCHK" CHECKS IF A COMMAND IS ENDED WITH CR. THIS IS -; REQUIRED IN CERTAIN COMMANDS. (GOTO, RETURN, AND STOP ETC.) +; REQUIRED IN CERTAIN COMMANDS. (GOTO, RETURN, AND STOP ETC.) ; ; "ERROR" PRINTS THE STRING POINTED BY DE (AND ENDS WITH CR). ; IT THEN PRINTS THE LINE POINTED BY 'CURRNT' WITH A "?" ; INSERTED AT WHERE THE OLD TEXT POINTER (SHOULD BE ON TOP ; OF THE STACK) POINTS TO. EXECUTION OF TB IS STOPPED -; AND TBI IS RESTARTED. HOWEVER, IF 'CURRNT' -> ZERO +; AND TBI IS RESTARTED. HOWEVER, IF 'CURRNT' -> ZERO ; (INDICATING A DIRECT COMMAND), THE DIRECT COMMAND IS NOT ; PRINTED. AND IF 'CURRNT' -> NEGATIVE # (INDICATING 'INPUT' ; COMMAND), THE INPUT LINE IS NOT PRINTED AND EXECUTION IS @@ -636,76 +636,76 @@ ck1: ; 'AHOW' AND 'AHOW' IN THE ZERO PAGE SECTION ALSO DO THIS. ;************************************************************* setval: - call testvar ; ** SetVal ** - jp c,qwhat ; no variable - push hl ; save address of var - call testc ; do we have =? - .db '=' - .db sv1-$-1 - call expr ; evaluate expression - ld b,h ; value is in bc now - ld c,l - pop hl ; get address - ld (hl),c ; save value - inc hl - ld (hl),b - ret + call testvar ; ** SetVal ** + jp c,qwhat ; no variable + push hl ; save address of var + call testc ; do we have =? + .db '=' + .db sv1-$-1 + call expr ; evaluate expression + ld b,h ; value is in bc now + ld c,l + pop hl ; get address + ld (hl),c ; save value + inc hl + ld (hl),b + ret sv1: - jp qwhat + jp qwhat fin: - call testc ; test for ':' - .db ':' - .db fi1 - $ - 1 - pop af ; yes, purge return address - jp runsml ; continue on same line + call testc ; test for ':' + .db ':' + .db fi1 - $ - 1 + pop af ; yes, purge return address + jp runsml ; continue on same line fi1: - call testc ; not ':', is it cr - .db cr - .db fi2 - $ - 1 - pop af ; yes, purge return address - jp runnxl ; run next line + call testc ; not ':', is it cr + .db cr + .db fi2 - $ - 1 + pop af ; yes, purge return address + jp runnxl ; run next line fi2: - ret ; else return to caller + ret ; else return to caller endchk: - call skipspace ; ** EndChk ** - cp cr ; ends with cr? - ret z ; ok, otherwise say 'what?' + call skipspace ; ** EndChk ** + cp cr ; ends with cr? + ret z ; ok, otherwise say 'what?' qwhat: - push de ; ** QWhat ** + push de ; ** QWhat ** awhat: - ld de,what ; ** AWhat ** + ld de,what ; ** AWhat ** handleerror: - sub a ; ** Error ** - call printstr ; print error message - pop de - ld a,(de) ; save the character - push af ; at where old de points - sub a ; and put a 0 (zero) there - ld (de),a - ld hl,(current) ; get the current line number - push hl - ld a,(hl) ; check the value - inc hl - or (hl) - pop de - jp z,rstart ; if zero, just rerstart - ld a,(hl) ; if negative - or a - jp m,inputerror ; then redo input - call printline ; else print the line - dec de ; up to where the 0 is - pop af ; restore the character - ld (de),a - ld a,'?' ; print a ? - call outc - sub a ; and the rest of the line - call printstr - jp rstart + sub a ; ** Error ** + call printstr ; print error message + pop de + ld a,(de) ; save the character + push af ; at where old de points + sub a ; and put a 0 (zero) there + ld (de),a + ld hl,(current) ; get the current line number + push hl + ld a,(hl) ; check the value + inc hl + or (hl) + pop de + jp z,rstart ; if zero, just rerstart + ld a,(hl) ; if negative + or a + jp m,inputerror ; then redo input + call printline ; else print the line + dec de ; up to where the 0 is + pop af ; restore the character + ld (de),a + ld a,'?' ; print a ? + call outc + sub a ; and the rest of the line + call printstr + jp rstart qsorry: - push de ; ** Sorry ** + push de ; ** Sorry ** asorry: - ld de,sorry - jr handleerror + ld de,sorry + jr handleerror ;************************************************************* ; @@ -713,7 +713,7 @@ asorry: ; ; 'GETLN' READS A INPUT LINE INTO 'BUFFER'. IT FIRST PROMPT ; THE CHARACTER IN A (GIVEN BY THE CALLER), THEN IT FILLS -; THE BUFFER AND ECHOS. IT IGNORES LF'S AND NULLS, BUT STILL +; THE BUFFER AND ECHOS. IT IGNORES LF'S AND NULLS, BUT STILL ; ECHOS THEM BACK. RUB-OUT IS USED TO CAUSE IT TO DELETE ; THE LAST CHARACTER (IF THERE IS ONE), AND ALT-MOD IS USED TO ; CAUSE IT TO DELETE THE WHOLE LINE AND START IT ALL OVER. @@ -735,72 +735,72 @@ asorry: ; 'FNDSKP' USE DE TO FIND A CR, AND THEN START SEARCH. ;************************************************************* getline: - call outc ; ** GetLine ** - ld de,buffer ; prompt and initalise pointer + call outc ; ** GetLine ** + ld de,buffer ; prompt and initalise pointer gl1: - call chkio ; check keyboard - jr z,gl1 ; no input, so wait - cp bs ; erase last character? - jr z,gl3 ; yes - call outc ; echo character - cp lf ; ignore lf - jr z,gl1 - or a ; ignore null - jr z,gl1 - cp ctrlu ; erase the whole line? - jr z,gl4 ; yes - ld (de),a ; save the input - inc de ; and increment pointer - cp cr ; was it cr? - ret z ; yes, end of line - ld a,e ; any free space left? - cp bufend & 0ffh - jr nz,gl1 ; yes, get next char + call chkio ; check keyboard + jr z,gl1 ; no input, so wait + cp bs ; erase last character? + jr z,gl3 ; yes + call outc ; echo character + cp lf ; ignore lf + jr z,gl1 + or a ; ignore null + jr z,gl1 + cp ctrlu ; erase the whole line? + jr z,gl4 ; yes + ld (de),a ; save the input + inc de ; and increment pointer + cp cr ; was it cr? + ret z ; yes, end of line + ld a,e ; any free space left? + cp bufend & 0ffh + jr nz,gl1 ; yes, get next char gl3: - ld a,e ; delete last character - cp buffer & 0ffh ; if there are any? - jr z,gl4 ; no, redo whole line - dec de ; yes, back pointer - ld a,08h ; and echo a backspace - call outc - jr gl1 ; and get next character + ld a,e ; delete last character + cp buffer & 0ffh ; if there are any? + jr z,gl4 ; no, redo whole line + dec de ; yes, back pointer + ld a,08h ; and echo a backspace + call outc + jr gl1 ; and get next character gl4: - call crlf ; redo entire line - ld a,'>' - jr getline + call crlf ; redo entire line + ld a,'>' + jr getline findline: - ld a,h ; ** FindLine ** - or a ; check the sign of hl - jp m,qhow ; it cannot be negative - ld de,textbegin ; initialise the text pointer + ld a,h ; ** FindLine ** + or a ; check the sign of hl + jp m,qhow ; it cannot be negative + ld de,textbegin ; initialise the text pointer findlineptr: fl1: - push hl ; save line number - ld hl,(textunfilled) ; check if we passed end - dec hl - call comp - pop hl ; retrieve line number - ret c ; c,nz passed end - ld a,(de) ; we didn't; get first byte - sub l ; is this the line? - ld b,a ; compare low order - inc de - ld a,(de) ; get second byte - sbc a,h ; compare high order - jr c,fl2 ; no, not there yet - dec de ; else we either found it - or b ; or it's not there - ret ; nc,z:found; nc,nz:no + push hl ; save line number + ld hl,(textunfilled) ; check if we passed end + dec hl + call comp + pop hl ; retrieve line number + ret c ; c,nz passed end + ld a,(de) ; we didn't; get first byte + sub l ; is this the line? + ld b,a ; compare low order + inc de + ld a,(de) ; get second byte + sbc a,h ; compare high order + jr c,fl2 ; no, not there yet + dec de ; else we either found it + or b ; or it's not there + ret ; nc,z:found; nc,nz:no findnext: - inc de ; find next line + inc de ; find next line fl2: - inc de ; just passed first and second byte + inc de ; just passed first and second byte findskip: - ld a,(de) ; ** FindSkip ** - cp cr ; try to find cr - jr nz,fl2 ; keep looking - inc de ; found cr, skip over - jr fl1 ; check if end of text + ld a,(de) ; ** FindSkip ** + cp cr ; try to find cr + jr nz,fl2 ; keep looking + inc de ; found cr, skip over + jr fl1 ; check if end of text ;************************************************************* ; @@ -827,130 +827,130 @@ findskip: ; 'PRTLN' PRINTS A SAVED TEXT LINE WITH LINE # AND ALL. ;************************************************************* printstr: - ld b,a + ld b,a ps1: - ld a,(de) ; get a character - inc de ; bump pointer - cp b ; same as old A? - ret z ; yes, return - call outc ; no, show character - cp cr ; was it a cr? - jr nz,ps1 ; no, next character - ret ; yes, returns + ld a,(de) ; get a character + inc de ; bump pointer + cp b ; same as old A? + ret z ; yes, return + call outc ; no, show character + cp cr ; was it a cr? + jr nz,ps1 ; no, next character + ret ; yes, returns qtstg: - call testc ; ** Qtstg ** - .db 22h ; is it a double quote - .db qt3-$-1 - ld a,22h + call testc ; ** Qtstg ** + .db 22h ; is it a double quote + .db qt3-$-1 + ld a,22h qt1: - call printstr ; print until another - cp cr - pop hl - jp z,runnxl + call printstr ; print until another + cp cr + pop hl + jp z,runnxl qt2: - inc hl ; skip 3 bytes on return - inc hl - inc hl - jp (hl) ; return + inc hl ; skip 3 bytes on return + inc hl + inc hl + jp (hl) ; return qt3: - call testc ; is it a single quote - .db 27h - .db qt4-$-1 - ld a,27h - jr qt1 + call testc ; is it a single quote + .db 27h + .db qt4-$-1 + ld a,27h + jr qt1 qt4: - call testc ; is it back-arrow - .db '_' - .db qt5-$-1 - ld a,8dh ; yes, cr without lf - call outc - call outc - pop hl ; return address - jr qt2 + call testc ; is it back-arrow + .db '_' + .db qt5-$-1 + ld a,8dh ; yes, cr without lf + call outc + call outc + pop hl ; return address + jr qt2 qt5: - ret ; none of the above + ret ; none of the above printnum: - ld b,0h ; ** PrintNum ** - call checksign ; check sign - jp p,pn1 ; no sign - ld b,'-' - dec c + ld b,0h ; ** PrintNum ** + call checksign ; check sign + jp p,pn1 ; no sign + ld b,'-' + dec c pn1: - push de ; save - ld de, 000ah ; decimal - push de ; save as flag - dec c ; c=spaces - push bc ; save sign & space + push de ; save + ld de, 000ah ; decimal + push de ; save as flag + dec c ; c=spaces + push bc ; save sign & space pn2: - call divide ; divide hl by 10 - ld a,b ; result 0? - or c - jr z,pn3 ; yes, we got all - ex (sp),hl ; no, save remainder - dec l ; and count space - push hl ; hl is old bc - ld h,b ; moved result to bc - ld l,c - jr pn2 ; and divide by 10 + call divide ; divide hl by 10 + ld a,b ; result 0? + or c + jr z,pn3 ; yes, we got all + ex (sp),hl ; no, save remainder + dec l ; and count space + push hl ; hl is old bc + ld h,b ; moved result to bc + ld l,c + jr pn2 ; and divide by 10 pn3: - pop bc ; we got all digits + pop bc ; we got all digits pn4: - dec c - ld a,c ; look at space count - or a - jp m,pn5 ; no leading spaces - ld a,' ' ; print a leading space - call outc - jr pn4 ; any more? + dec c + ld a,c ; look at space count + or a + jp m,pn5 ; no leading spaces + ld a,' ' ; print a leading space + call outc + jr pn4 ; any more? pn5: - ld a,b ; print sign - or a - call nz,outc - ld e,l ; last remainder in e + ld a,b ; print sign + or a + call nz,outc + ld e,l ; last remainder in e pn6: - ld a,e ; check digit in e - cp lf ; lf is flag for no more - pop de - ret z ; if yes, return - add a,30h ; else convert to ascii - call outc ; and print the digit - jr pn6 ; next digit + ld a,e ; check digit in e + cp lf ; lf is flag for no more + pop de + ret z ; if yes, return + add a,30h ; else convert to ascii + call outc ; and print the digit + jr pn6 ; next digit printhex: - ld c,h ; ** PrintHex ** - call ph1 ; first hex byte + ld c,h ; ** PrintHex ** + call ph1 ; first hex byte printhex8: - ld c,l ; then second + ld c,l ; then second ph1: - ld a,c ; get left nibble into position - rra - rra - rra - rra - call ph2 ; and turn into hex digit - ld a,c ; then convert right nibble + ld a,c ; get left nibble into position + rra + rra + rra + rra + call ph2 ; and turn into hex digit + ld a,c ; then convert right nibble ph2: - and 0fh ; mask right nibble - add a,90h ; and convert to ascii character - daa - adc a,40h - daa - call outc ; print character - ret + and 0fh ; mask right nibble + add a,90h ; and convert to ascii character + daa + adc a,40h + daa + call outc ; print character + ret printline: - ld a,(de) ; ** PrintLine ** - ld l,a ; low order line number - inc de - ld a,(de) ; high order - ld h,a - inc de - ld c,04h ; print 4 digit line number - call printnum - ld a,' ' ; followed by a space - call outc - sub a ; and the the rest - call printstr - ret + ld a,(de) ; ** PrintLine ** + ld l,a ; low order line number + inc de + ld a,(de) ; high order + ld h,a + inc de + ld c,04h ; print 4 digit line number + call printnum + ld a,' ' ; followed by a space + call outc + sub a ; and the the rest + call printstr + ret ;************************************************************* ; @@ -969,143 +969,143 @@ printline: ; STACK ;************************************************************* mvup: - call comp ; ** mvup ** - ret z ; de = hl, return - ld a,(de) ; get one byte - ld (bc),a ; then copy it - inc de ; increase both pointers - inc bc - jr mvup ; until done + call comp ; ** mvup ** + ret z ; de = hl, return + ld a,(de) ; get one byte + ld (bc),a ; then copy it + inc de ; increase both pointers + inc bc + jr mvup ; until done mvdown: - ld a,b ; ** mvdown ** - sub d ; check if de = bc - jp nz,md1 ; no, go move - ld a,c ; maybe, other byte - sub e - ret z ; yes, return + ld a,b ; ** mvdown ** + sub d ; check if de = bc + jp nz,md1 ; no, go move + ld a,c ; maybe, other byte + sub e + ret z ; yes, return md1: - dec de ; else move a byte - dec hl ; but first decrease both pointers - ld a,(de) ; and then do it - ld (hl),a - jr mvdown ; loop back + dec de ; else move a byte + dec hl ; but first decrease both pointers + ld a,(de) ; and then do it + ld (hl),a + jr mvdown ; loop back popa: - pop bc ; bc = return address - pop hl ; restore loopvar - ld (loopvar),hl - ld a,h - or l - jr z,pp1 ; all done, so return - pop hl - ld (loopinc),hl - pop hl - ld (looplmt),hl - pop hl - ld (loopln),hl - pop hl - ld (loopptr),hl + pop bc ; bc = return address + pop hl ; restore loopvar + ld (loopvar),hl + ld a,h + or l + jr z,pp1 ; all done, so return + pop hl + ld (loopinc),hl + pop hl + ld (looplmt),hl + pop hl + ld (loopln),hl + pop hl + ld (loopptr),hl pp1: - push bc ; bc = return address - ret + push bc ; bc = return address + ret pusha: - ld hl,stacklimit ; ** PushA ** - call changesign - pop bc ; bc = return address - add hl,sp ; is stack near the top? - jp nc,qsorry ; yes, sorry - ld hl,(loopvar) ; else save loop variables - ld a,h - or l - jr z,pu1 ; only when loopvar not 0 - ld hl,(loopptr) - push hl - ld hl,(loopln) - push hl - ld hl,(looplmt) - push hl - ld hl,(loopinc) - push hl - ld hl,(loopvar) + ld hl,stacklimit ; ** PushA ** + call changesign + pop bc ; bc = return address + add hl,sp ; is stack near the top? + jp nc,qsorry ; yes, sorry + ld hl,(loopvar) ; else save loop variables + ld a,h + or l + jr z,pu1 ; only when loopvar not 0 + ld hl,(loopptr) + push hl + ld hl,(loopln) + push hl + ld hl,(looplmt) + push hl + ld hl,(loopinc) + push hl + ld hl,(loopvar) pu1: - push hl - push bc ; bc = return address - ret + push hl + push bc ; bc = return address + ret testvar: - call skipspace ; ** testvar ** - sub '@' ; test variables - ret c ; not a variable - jr nz,tv1 ; not @ array - inc de ; is is the @ array - call parn ; @ should be followed by (expr) - add hl,hl ; as its index - jr c,qhow ; is index too big? - push de ; will it override text? - ex de,hl - call size ; find the size of free - call comp - jp c,asorry ; yes, sorry - ld hl,varbegin ; no, get address of @(expr) and - call subde ; put it in hl - pop de - ret + call skipspace ; ** testvar ** + sub '@' ; test variables + ret c ; not a variable + jr nz,tv1 ; not @ array + inc de ; is is the @ array + call parn ; @ should be followed by (expr) + add hl,hl ; as its index + jr c,qhow ; is index too big? + push de ; will it override text? + ex de,hl + call size ; find the size of free + call comp + jp c,asorry ; yes, sorry + ld hl,varbegin ; no, get address of @(expr) and + call subde ; put it in hl + pop de + ret tv1: - cp 1bh ; not @, is it A to Z - ccf - ret c - inc de ; if A trhough Z - ld hl,varbegin ; calculate address of that variable - rlca ; and return it in hl - add a,l ; with the c flag cleared - ld l,a - ld a,0 - adc a,h - ld h,a - ret + cp 1bh ; not @, is it A to Z + ccf + ret c + inc de ; if A trhough Z + ld hl,varbegin ; calculate address of that variable + rlca ; and return it in hl + add a,l ; with the c flag cleared + ld l,a + ld a,0 + adc a,h + ld h,a + ret testnum: - ld hl,0000h ; ** TestNum ** - ld b,h ; test if the text is a number - call skipspace + ld hl,0000h ; ** TestNum ** + ld b,h ; test if the text is a number + call skipspace tn1: - cp '0' ; if not,return 0 in b and hl - ret c - cp ':' ; if a digit, convert to binary in - ret nc ; b and hl - ld a,0f0h ; set b to number of digits - and h ; if h>255, there is no room for - jr nz,qhow ; next digit - inc b ; b counts number of digits - push bc - ld b,h ; hl=10*hl+(new digit) - ld c,l - add hl,hl ; where 10* is done by shift and add - add hl,hl - add hl,bc - add hl,hl - ld a,(de) ; and (digit) is by stripping the - inc de ; ascii code - and 0fh - add a,l - ld l,a - ld a,0 - adc a,h - ld h,a - pop bc - ld a,(de) - jp p,tn1 + cp '0' ; if not,return 0 in b and hl + ret c + cp ':' ; if a digit, convert to binary in + ret nc ; b and hl + ld a,0f0h ; set b to number of digits + and h ; if h>255, there is no room for + jr nz,qhow ; next digit + inc b ; b counts number of digits + push bc + ld b,h ; hl=10*hl+(new digit) + ld c,l + add hl,hl ; where 10* is done by shift and add + add hl,hl + add hl,bc + add hl,hl + ld a,(de) ; and (digit) is by stripping the + inc de ; ascii code + and 0fh + add a,l + ld l,a + ld a,0 + adc a,h + ld h,a + pop bc + ld a,(de) + jp p,tn1 qhow: - push de ; ** Error How? ** + push de ; ** Error How? ** ahow: - ld de,how - jp handleerror + ld de,how + jp handleerror -msg1 .db "TASTY BASIC",cr -msg2 .db " BYTES FREE",cr -how .db "HOW?",cr -ok .db "OK",cr -what .db "WHAT?",cr -sorry .db "SORRY",cr +msg1 .db "TASTY BASIC",cr +msg2 .db " BYTES FREE",cr +how .db "HOW?",cr +ok .db "OK",cr +what .db "WHAT?",cr +sorry .db "SORRY",cr ;************************************************************* ; @@ -1116,7 +1116,7 @@ sorry .db "SORRY",cr ; ; AT START, IT PRINTS OUT "(CR)OK(CR)", AND INITIALIZES THE ; STACK AND SOME OTHER INTERNAL VARIABLES. THEN IT PROMPTS -; ">" AND READS A LINE. IF THE LINE STARTS WITH A NON-ZERO +; ">" AND READS A LINE. IF THE LINE STARTS WITH A NON-ZERO ; NUMBER, THIS NUMBER IS THE LINE NUMBER. THE LINE NUMBER ; (IN 16 BIT BINARY) AND THE REST OF THE LINE (INCLUDING CR) ; IS STORED IN THE MEMORY. IF A LINE WITH THE SAME LINE @@ -1125,7 +1125,7 @@ sorry .db "SORRY",cr ; AND ANY EXISTING LINE WITH THE SAME LINE NUMBER IS DELETED. ; ; AFTER A LINE IS INSERTED, REPLACED, OR DELETED, THE PROGRAM -; LOOPS BACK AND ASKS FOR ANOTHER LINE. THIS LOOP WILL BE +; LOOPS BACK AND ASKS FOR ANOTHER LINE. THIS LOOP WILL BE ; TERMINATED WHEN IT READS A LINE WITH ZERO OR NO LINE ; NUMBER; AND CONTROL IS TRANSFERED TO "DIRECT". ; @@ -1135,80 +1135,80 @@ sorry .db "SORRY",cr ; BY THE CONTENT OF A MEMORY LOCATION LABELED "TXTUNF". ; ; THE MEMORY LOCATION "CURRNT" POINTS TO THE LINE NUMBER -; THAT IS CURRENTLY BEING INTERPRETED. WHILE WE ARE IN +; THAT IS CURRENTLY BEING INTERPRETED. WHILE WE ARE IN ; THIS LOOP OR WHILE WE ARE INTERPRETING A DIRECT COMMAND ; (SEE NEXT SECTION). "CURRNT" SHOULD POINT TO A 0. ;************************************************************* rstart: - ld sp,stack + ld sp,stack st1: - call crlf - sub a ; a=0 - ld de,ok ; print ok - call printstr - ld hl,st2 + 1 ; literal zero - ld (current),hl ; reset current line pointer + call crlf + sub a ; a=0 + ld de,ok ; print ok + call printstr + ld hl,st2 + 1 ; literal zero + ld (current),hl ; reset current line pointer st2: - ld hl,0000h - ld (loopvar),hl - ld (stkgos),hl + ld hl,0000h + ld (loopvar),hl + ld (stkgos),hl st3: - ld a,'>' ; initialise prompt - call getline - push de ; de points to end of line - ld de,buffer ; point de to beginning of line - call testnum ; check if it is a number - call skipspace - ld a,h ; hl = value of the number, or - or l ; 0 if no number was found - pop bc ; bc points to end of line - jp z,direct - dec de ; back up de and save the value of - ld a,h ; the value of the line number there - ld (de),a - dec de - ld a,l - ld (de),a - push bc ; bc,de point to begin,end - push de - ld a,c - sub e + ld a,'>' ; initialise prompt + call getline + push de ; de points to end of line + ld de,buffer ; point de to beginning of line + call testnum ; check if it is a number + call skipspace + ld a,h ; hl = value of the number, or + or l ; 0 if no number was found + pop bc ; bc points to end of line + jp z,direct + dec de ; back up de and save the value of + ld a,h ; the value of the line number there + ld (de),a + dec de + ld a,l + ld (de),a + push bc ; bc,de point to begin,end + push de + ld a,c + sub e - push af ; a = number of bytes in line - call findline ; find this line in save area - push de ; de points to save area - jr nz,st4 ; nz: line not found - push de ; z: found, delete it - call findnext ; find next line - ; de -> next line - pop bc ; bc -> line to be deleted - ld hl,(textunfilled) ; hl -> unfilled text area - call mvup ; move up to delete - ld h,b ; txtunf -> unfilled area - ld l,c - ld (textunfilled),hl + push af ; a = number of bytes in line + call findline ; find this line in save area + push de ; de points to save area + jr nz,st4 ; nz: line not found + push de ; z: found, delete it + call findnext ; find next line + ; de -> next line + pop bc ; bc -> line to be deleted + ld hl,(textunfilled) ; hl -> unfilled text area + call mvup ; move up to delete + ld h,b ; txtunf -> unfilled area + ld l,c + ld (textunfilled),hl st4: - pop bc ; get ready to insert - ld hl,(textunfilled) ; but first check if the length - pop af ; of new line is 3 (line# and cr) - push hl - cp 3h ; if so, do not insert - jr z,rstart ; must clear the stack - add a,l ; calculate new txtunf - ld l,a - ld a,0 - adc a,h - ld h,a ; hl -> new unfilled area - ld de,textend ; check to see if there is space - call comp - jp nc,qsorry ; no, sorry - ld (textunfilled),hl ; ok, update textunfilled - pop de ; de -> old unfilled area - call mvdown - pop de ; de,hl -> begin,end - pop hl - call mvup ; copy new line to save area - jr st3 + pop bc ; get ready to insert + ld hl,(textunfilled) ; but first check if the length + pop af ; of new line is 3 (line# and cr) + push hl + cp 3h ; if so, do not insert + jr z,rstart ; must clear the stack + add a,l ; calculate new txtunf + ld l,a + ld a,0 + adc a,h + ld h,a ; hl -> new unfilled area + ld de,textend ; check to see if there is space + call comp + jp nc,qsorry ; no, sorry + ld (textunfilled),hl ; ok, update textunfilled + pop de ; de -> old unfilled area + call mvdown + pop de ; de,hl -> begin,end + pop hl + call mvup ; copy new line to save area + jr st3 ;************************************************************* ; @@ -1249,47 +1249,47 @@ st4: ;************************************************************* #ifndef ZEMU bye: - call endchk ; ** Reboot ** - LD A,BID_BOOT ; BOOT BANK - LD HL,0 ; ADDRESS ZERO - CALL HB_BNKCALL ; DOES NOT RETURN - HALT + call endchk ; ** Reboot ** + LD A,BID_BOOT ; BOOT BANK + LD HL,0 ; ADDRESS ZERO + CALL HB_BNKCALL ; DOES NOT RETURN + HALT #endif new: - call endchk ; ** New ** - ld hl,textbegin - ld (textunfilled),hl + call endchk ; ** New ** + ld hl,textbegin + ld (textunfilled),hl clear: - call clrvars ; ** Clear ** - jp rstart + call clrvars ; ** Clear ** + jp rstart endd: - call endchk ; ** End ** - jp rstart + call endchk ; ** End ** + jp rstart run: - call endchk ; ** Run ** - ld de,textbegin + call endchk ; ** Run ** + ld de,textbegin runnxl: - ld hl,0h ; ** Run Next Line ** - call findlineptr - jp c,rstart + ld hl,0h ; ** Run Next Line ** + call findlineptr + jp c,rstart runtsl: - ex de,hl ; ** Run Tsl - ld (current),hl ; set current -> line # - ex de,hl - inc de - inc de + ex de,hl ; ** Run Tsl + ld (current),hl ; set current -> line # + ex de,hl + inc de + inc de runsml: - call chkio ; ** Run Same Line ** - ld hl, tab2-1 ; find the command in table 2 - jp exec ; and execute it + call chkio ; ** Run Same Line ** + ld hl, tab2-1 ; find the command in table 2 + jp exec ; and execute it goto: - call expr - push de ; save for error routine - call endchk ; must find a cr - call findline ; find the target line - jp nz, ahow ; no such line # - pop af ; clear the pushed de - jr runtsl ; go do it + call expr + push de ; save for error routine + call endchk ; must find a cr + call findline ; find the target line + jp nz, ahow ; no such line # + pop af ; clear the pushed de + jr runtsl ; go do it ;************************************************************* ; @@ -1302,7 +1302,7 @@ goto: ; ; PRINT COMMAND IS 'PRINT ....;' OR 'PRINT ....(CR)' ; WHERE '....' IS A LIST OF EXPRESIONS, FORMATS, BACK- -; ARROWS, AND STRINGS. THESE ITEMS ARE SEPERATED BY COMMAS. +; ARROWS, AND STRINGS. THESE ITEMS ARE SEPERATED BY COMMAS. ; ; A FORMAT IS A POUND SIGN FOLLOWED BY A NUMBER. IT CONTROLS ; THE NUMBER OF SPACES THE VALUE OF A EXPRESION IS GOING TO @@ -1320,77 +1320,77 @@ goto: ; ENDED WITH A COMMA, NO (CRLF) IS GENERATED. ;************************************************************* list: - call testnum ; check if there is a number - call endchk ; if no number we get a 0 - call findline ; find this or next line + call testnum ; check if there is a number + call endchk ; if no number we get a 0 + call findline ; find this or next line ls1: - jp c,rstart - call printline ; print the line - call chkio ; stop on ctrl-c - call findlineptr ; find the next line - jr ls1 ; and loop back + jp c,rstart + call printline ; print the line + call chkio ; stop on ctrl-c + call findlineptr ; find the next line + jr ls1 ; and loop back print: - ld c,6 ; c = number of spaces - call testc ; is it a semicolon? - .db ':' - .db pr2-$-1 - call crlf - jr runsml + ld c,6 ; c = number of spaces + call testc ; is it a semicolon? + .db ':' + .db pr2-$-1 + call crlf + jr runsml pr2: - call testc ; is it a cr? - .db cr - .db pr0-$-1 - call crlf - jr runnxl + call testc ; is it a cr? + .db cr + .db pr0-$-1 + call crlf + jr runnxl pr0: - call testc ; is it format? - .db '#' - .db pr1-$-1 - call expr - ld c,l - jr pr3 + call testc ; is it format? + .db '#' + .db pr1-$-1 + call expr + ld c,l + jr pr3 pr1: - call testc ; is it a dollar? - .db '$' - .db pr4-$-1 - call expr - ld c,l - call testc ; do we have a comma? - .db ',' - .db pr6-$-1 - push bc - call expr - pop bc - ld a,8 ; 8 bits? - cp c - jp nz,pr9 ; no, try 16 - call printhex8 ; yes, print a single hex byte - jp pr3 + call testc ; is it a dollar? + .db '$' + .db pr4-$-1 + call expr + ld c,l + call testc ; do we have a comma? + .db ',' + .db pr6-$-1 + push bc + call expr + pop bc + ld a,8 ; 8 bits? + cp c + jp nz,pr9 ; no, try 16 + call printhex8 ; yes, print a single hex byte + jp pr3 pr9: - ld a,10h ; 16 bits? - cp c - jp nz,qhow ; no, show error message - call printhex ; yes, print two hex bytes - jp pr3 + ld a,10h ; 16 bits? + cp c + jp nz,qhow ; no, show error message + call printhex ; yes, print two hex bytes + jp pr3 pr4: - call qtstg ; is it a string? - jr pr8 + call qtstg ; is it a string? + jr pr8 pr3: - call testc ; is it a comma? - .db ',' - .db pr6-$-1 - call fin - jr pr0 + call testc ; is it a comma? + .db ',' + .db pr6-$-1 + call fin + jr pr0 pr6: - call crlf ; list ends - call finish + call crlf ; list ends + call finish pr8: - call expr ; evaluate the expression - push bc - call printnum - pop bc - jr pr3 + call expr ; evaluate the expression + push bc + call printnum + pop bc + jr pr3 ;************************************************************* ; @@ -1399,7 +1399,7 @@ pr8: ; 'GOSUB EXPR;' OR 'GOSUB EXPR (CR)' IS LIKE THE 'GOTO' ; COMMAND, EXCEPT THAT THE CURRENT TEXT POINTER, STACK POINTER ; ETC. ARE SAVE SO THAT EXECUTION CAN BE CONTINUED AFTER THE -; SUBROUTINE 'RETURN'. IN ORDER THAT 'GOSUB' CAN BE NESTED +; SUBROUTINE 'RETURN'. IN ORDER THAT 'GOSUB' CAN BE NESTED ; (AND EVEN RECURSIVE), THE SAVE AREA MUST BE STACKED. ; THE STACK POINTER IS SAVED IN 'STKGOS', THE OLD 'STKGOS' IS ; SAVED IN THE STACK. IF WE ARE IN THE MAIN ROUTINE, 'STKGOS' @@ -1412,34 +1412,34 @@ pr8: ; NEVER HAD A 'GOSUB' AND IS THUS AN ERROR. ;************************************************************* gosub: - call pusha ; ** Gosub ** - call expr ; save the current "FOR" params - push de ; and text pointer - call findline ; find the target line - jp nz,ahow ; how? because it doesn't exist - ld hl,(current) ; found it, save old 'current' - push hl - ld hl,(stkgos) ; and 'stkgos' - push hl - ld hl,0000h ; and load new ones - ld (loopvar),hl - add hl,sp - ld (stkgos),hl - jp runtsl ; and run the line + call pusha ; ** Gosub ** + call expr ; save the current "FOR" params + push de ; and text pointer + call findline ; find the target line + jp nz,ahow ; how? because it doesn't exist + ld hl,(current) ; found it, save old 'current' + push hl + ld hl,(stkgos) ; and 'stkgos' + push hl + ld hl,0000h ; and load new ones + ld (loopvar),hl + add hl,sp + ld (stkgos),hl + jp runtsl ; and run the line return: - call endchk ; there must be a cr - ld hl,(stkgos) ; check old stack pointer - ld a,h ; - or l - jp z,what ; what? not found - ld sp,hl ; otherwise restore it - pop hl - ld (stkgos),hl - pop hl - ld (current),hl ; and old 'current' - pop de ; and old text pointer - call popa ; and old 'FOR' params - call finish ; and we're back + call endchk ; there must be a cr + ld hl,(stkgos) ; check old stack pointer + ld a,h ; + or l + jp z,what ; what? not found + ld sp,hl ; otherwise restore it + pop hl + ld (stkgos),hl + pop hl + ld (current),hl ; and old 'current' + pop de ; and old text pointer + call popa ; and old 'FOR' params + call finish ; and we're back ;************************************************************* ; @@ -1469,258 +1469,258 @@ return: ; DID NOT MATCH. EITHER WAY, TBI THEN ADDS THE 'STEP' TO ; THAT VARIABLE AND CHECK THE RESULT WITH THE LIMIT. IF IT ; IS WITHIN THE LIMIT, CONTROL LOOPS BACK TO THE COMMAND -; FOLLOWING THE 'FOR'. IF OUTSIDE THE LIMIT, THE SAVE AREA +; FOLLOWING THE 'FOR'. IF OUTSIDE THE LIMIT, THE SAVE AREA ; IS PURGED AND EXECUTION CONTINUES. ;************************************************************* for: - call pusha ; save old save area - call setval ; set the control variable - dec hl ; its address is hl - ld (loopvar),hl ; save that - ld hl,tab5-1 ; use 'exec' to find 'TO' - jp exec + call pusha ; save old save area + call setval ; set the control variable + dec hl ; its address is hl + ld (loopvar),hl ; save that + ld hl,tab5-1 ; use 'exec' to find 'TO' + jp exec fr1: - call expr ; evaluate the limit - ld (looplmt),hl ; and save it - ld hl,tab6-1 ; use 'exec' to find 'STEP' - jp exec + call expr ; evaluate the limit + ld (looplmt),hl ; and save it + ld hl,tab6-1 ; use 'exec' to find 'STEP' + jp exec fr2: - call expr ; found 'STEP' - jr fr4 + call expr ; found 'STEP' + jr fr4 fr3: - ld hl,0001h ; no 'STEP' so set to 1 + ld hl,0001h ; no 'STEP' so set to 1 fr4: - ld (loopinc),hl ; and save that too + ld (loopinc),hl ; and save that too fr5: - ld hl,(current) ; save current line number - ld (loopln),hl - ex de,hl ; and text pointer - ld (loopptr),hl - ld bc,0ah ; dig into stack to find loopvar - ld hl,(loopvar) - ex de,hl - ld h,b - ld l,b - add hl,sp - .db 3eh + ld hl,(current) ; save current line number + ld (loopln),hl + ex de,hl ; and text pointer + ld (loopptr),hl + ld bc,0ah ; dig into stack to find loopvar + ld hl,(loopvar) + ex de,hl + ld h,b + ld l,b + add hl,sp + .db 3eh fr7: - add hl,bc - ld a,(hl) - inc hl - or (hl) - jr z,fr8 - ld a,(hl) - dec hl - cp d - jr nz,fr7 - ld a,(hl) - cp e - jr nz,fr7 - ex de,hl - ld hl,0000h - add hl,sp - ld b,h - ld c,l - ld hl,000ah - add hl,de - call mvdown - ld sp,hl + add hl,bc + ld a,(hl) + inc hl + or (hl) + jr z,fr8 + ld a,(hl) + dec hl + cp d + jr nz,fr7 + ld a,(hl) + cp e + jr nz,fr7 + ex de,hl + ld hl,0000h + add hl,sp + ld b,h + ld c,l + ld hl,000ah + add hl,de + call mvdown + ld sp,hl fr8: - ld hl,(loopptr) ; all done - ex de,hl - call finish + ld hl,(loopptr) ; all done + ex de,hl + call finish next: - call testvar ; get address of variable - jp c,qwhat ; what, no variable - ld (varnext),hl ; yes, save it + call testvar ; get address of variable + jp c,qwhat ; what, no variable + ld (varnext),hl ; yes, save it nx0: - push de ; save the text pointer - ex de,hl - ld hl,(loopvar) ; get the variable in 'FOR' - ld a,h - or l ; if 0, there never was one - jp z,awhat - call comp ; else check them - jr z,nx3 ; yes, they agree - pop de ; no, complete current loop - call popa - ld hl,(varnext) ; and pop one level - jr nx0 ; go check again + push de ; save the text pointer + ex de,hl + ld hl,(loopvar) ; get the variable in 'FOR' + ld a,h + or l ; if 0, there never was one + jp z,awhat + call comp ; else check them + jr z,nx3 ; yes, they agree + pop de ; no, complete current loop + call popa + ld hl,(varnext) ; and pop one level + jr nx0 ; go check again nx3: - ld e,(hl) - inc hl - ld d,(hl) ; de = value of variable - ld hl,(loopinc) - push hl - ld a,h - xor d - ld a,d - add hl,de - jp m,nx4 - xor h - jp m,nx5 + ld e,(hl) + inc hl + ld d,(hl) ; de = value of variable + ld hl,(loopinc) + push hl + ld a,h + xor d + ld a,d + add hl,de + jp m,nx4 + xor h + jp m,nx5 nx4: - ex de,hl - ld hl,(loopvar) - ld (hl),e - inc hl - ld (hl),d - ld hl,(looplmt) - pop af - or a - jp p,nx1 ; step > 0 - ex de,hl ; step < 0 + ex de,hl + ld hl,(loopvar) + ld (hl),e + inc hl + ld (hl),d + ld hl,(looplmt) + pop af + or a + jp p,nx1 ; step > 0 + ex de,hl ; step < 0 nx1: - call ckhlde ; compare with limit - pop de ; restore the text pointer - jr c,nx2 ; over the limit - ld hl,(loopln) ; within the limit - ld (current),hl - ld hl,(loopptr) - ex de,hl - call finish + call ckhlde ; compare with limit + pop de ; restore the text pointer + jr c,nx2 ; over the limit + ld hl,(loopln) ; within the limit + ld (current),hl + ld hl,(loopptr) + ex de,hl + call finish nx5: - pop hl - pop de + pop hl + pop de nx2: - call popa ; purge this loop - call finish ; + call popa ; purge this loop + call finish ; init: - ld hl,start ; initialise random pointer - ld (rndptr),hl - ld hl,usrfunc ; initialise user defined function - ld (usrptr),hl - ld a,0c3h - ld (usrfunc),a ; initiase default USR() behaviour - ld hl,qhow ; (i.e. HOW? error) - ld (usrfunc+1),hl - ld hl,textbegin ; initialise text area pointers - ld (textunfilled),hl - ld (ocsw),a ; enable output control switch - call clrvars ; clear variables - call crlf - ld de,msg1 ; output welcome message - call printstr - call crlf - call size ; output free size message - call printnum - ld de,msg2 - call printstr - jp rstart + ld hl,start ; initialise random pointer + ld (rndptr),hl + ld hl,usrfunc ; initialise user defined function + ld (usrptr),hl + ld a,0c3h + ld (usrfunc),a ; initiase default USR() behaviour + ld hl,qhow ; (i.e. HOW? error) + ld (usrfunc+1),hl + ld hl,textbegin ; initialise text area pointers + ld (textunfilled),hl + ld (ocsw),a ; enable output control switch + call clrvars ; clear variables + call crlf + ld de,msg1 ; output welcome message + call printstr + call crlf + call size ; output free size message + call printnum + ld de,msg2 + call printstr + jp rstart chkio: - call haschar ; check if character available - ret z ; no, return - call getchar ; get the character - push bc ; is it a lf? - ld b,a - sub lf - jr z,io1 ; yes, ignore an return - ld a,b ; no, restore a and bc - pop bc - cp ctrlo ; is it ctrl-o? - jr nz,io2 ; no, done - ld a,(ocsw) ; toggle output control switch - cpl - ld (ocsw),a - jr chkio ; get next character + call haschar ; check if character available + ret z ; no, return + call getchar ; get the character + push bc ; is it a lf? + ld b,a + sub lf + jr z,io1 ; yes, ignore an return + ld a,b ; no, restore a and bc + pop bc + cp ctrlo ; is it ctrl-o? + jr nz,io2 ; no, done + ld a,(ocsw) ; toggle output control switch + cpl + ld (ocsw),a + jr chkio ; get next character io1: - ld a,0h ; clear - or a ; set the z-flag - pop bc ; restore bc - ret ; return with z set + ld a,0h ; clear + or a ; set the z-flag + pop bc ; restore bc + ret ; return with z set io2: - cp 60h ; is it lower case? - jp c,io3 ; no - and 0dfh ; yes, make upper case + cp 60h ; is it lower case? + jp c,io3 ; no + and 0dfh ; yes, make upper case io3: - cp ctrlc ; is it ctrl-c? - ret nz ; no - jp rstart ; yes, restart tasty basic + cp ctrlc ; is it ctrl-c? + ret nz ; no + jp rstart ; yes, restart tasty basic crlf: - ld a,cr + ld a,cr outc: - push af - ld a,(ocsw) ; check output control switch - or a - jr nz,oc1 ; output is enabled - pop af ; output is disabled - ret ; so return + push af + ld a,(ocsw) ; check output control switch + or a + jr nz,oc1 ; output is enabled + pop af ; output is disabled + ret ; so return oc1: - pop af - call putchar - cp cr ; was it a cr? - ret nz ; no, return - ld a,lf ; send a lf - call outc - ld a,cr ; restore register - ret ; and return + pop af + call putchar + cp cr ; was it a cr? + ret nz ; no, return + ld a,lf ; send a lf + call outc + ld a,cr ; restore register + ret ; and return putchar: #ifdef ZEMU - call uart_tx_ready ; see if transmit is available - out (tty_data),a ; and send it - ret + call uart_tx_ready ; see if transmit is available + out (tty_data),a ; and send it + ret uart_tx_ready: - push af + push af uart_tx_ready_loop: - in a,(tty_status) - bit tx_empty,a - jp z,uart_tx_ready_loop - pop af + in a,(tty_status) + bit tx_empty,a + jp z,uart_tx_ready_loop + pop af #else - PUSH AF - PUSH BC - PUSH DE - PUSH HL - ; OUTPUT CHARACTER TO CONSOLE VIA HBIOS - LD E,A ; OUTPUT CHAR TO E - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C - LD B,BF_CIOOUT ; HBIOS FUNC: OUTPUT CHAR - RST 08 ; HBIOS OUTPUTS CHARACTER - POP HL - POP DE - POP BC - POP AF + PUSH AF + PUSH BC + PUSH DE + PUSH HL + ; OUTPUT CHARACTER TO CONSOLE VIA HBIOS + LD E,A ; OUTPUT CHAR TO E + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C + LD B,BF_CIOOUT ; HBIOS FUNC: OUTPUT CHAR + RST 08 ; HBIOS OUTPUTS CHARACTER + POP HL + POP DE + POP BC + POP AF #endif - ret + ret haschar: #ifdef ZEMU - in a,(tty_status) ; check if character available - bit rx_full,a + in a,(tty_status) ; check if character available + bit rx_full,a #else - PUSH BC - PUSH DE - PUSH HL - ; GET CONSOLE INPUT STATUS VIA HBIOS - LD C,CIODEV_CONSOLE; CONSOLE UNIT TO C - LD B,BF_CIOIST ; HBIOS FUNC: INPUT STATUS - RST 08 ; HBIOS RETURNS STATUS IN A - POP HL - POP DE - POP BC + PUSH BC + PUSH DE + PUSH HL + ; GET CONSOLE INPUT STATUS VIA HBIOS + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C + LD B,BF_CIOIST ; HBIOS FUNC: INPUT STATUS + RST 08 ; HBIOS RETURNS STATUS IN A + POP HL + POP DE + POP BC #endif - ret + ret getchar: #ifdef ZEMU - in a,(tty_data) ; get the character + in a,(tty_data) ; get the character #else - PUSH BC - PUSH DE - PUSH HL - ; INPUT CHARACTER FROM CONSOLE VIA HBIOS - LD C,CIODEV_CONSOLE ; CONSOLE UNIT TO C - LD B,BF_CIOIN ; HBIOS FUNC: INPUT CHAR - RST 08 ; HBIOS READS CHARACTDR - LD A,E ; MOVE CHARACTER TO A FOR RETURN - ; RESTORE REGISTERS (AF IS OUTPUT) - POP HL - POP DE - POP BC + PUSH BC + PUSH DE + PUSH HL + ; INPUT CHARACTER FROM CONSOLE VIA HBIOS + LD C,CIO_CONSOLE ; CONSOLE UNIT TO C + LD B,BF_CIOIN ; HBIOS FUNC: INPUT CHAR + RST 08 ; HBIOS READS CHARACTDR + LD A,E ; MOVE CHARACTER TO A FOR RETURN + ; RESTORE REGISTERS (AF IS OUTPUT) + POP HL + POP DE + POP BC #endif - ret + ret ;************************************************************* ; @@ -1736,7 +1736,7 @@ getchar: ; ALL DIRECT AND STATEMENT COMMANDS. ; ; A '.' IN THE STRING WILL TERMINATE THE TEST AND THE PARTIAL -; MATCH WILL BE CONSIDERED AS A MATCH. E.G., 'P.', 'PR.', +; MATCH WILL BE CONSIDERED AS A MATCH. E.G., 'P.', 'PR.', ; 'PRI.', 'PRIN.', OR 'PRINT' WILL ALL MATCH 'PRINT'. ; ; THE TABLE CONSISTS OF ANY NUMBER OF ITEMS. EACH ITEM @@ -1748,155 +1748,155 @@ getchar: ; STRING DOES NOT MATCH ANY OF THE OTHER ITEMS, IT WILL ; MATCH THIS NULL ITEM AS DEFAULT. ;************************************************************* -tab1: ; direct commands - .db "LIST" - dwa(list) - .db "RUN" - dwa(run) - .db "NEW" - dwa(new) - .db "CLEAR" - dwa(clear) +tab1: ; direct commands + .db "LIST" + dwa(list) + .db "RUN" + dwa(run) + .db "NEW" + dwa(new) + .db "CLEAR" + dwa(clear) #ifndef ZEMU - .db "BYE" - dwa(bye) + .db "BYE" + dwa(bye) #endif -tab2: ; direct/statement - .db "NEXT" - dwa(next) - .db "LET" - dwa(let) - .db "IF" - dwa(iff) - .db "GOTO" - dwa(goto) - .db "GOSUB" - dwa(gosub) - .db "RETURN" - dwa(return) - .db "REM" - dwa(rem) - .db "FOR" - dwa(for) - .db "INPUT" - dwa(input) - .db "PRINT" - dwa(print) - .db "POKE" - dwa(poke) - .db "END" - dwa(endd) - dwa(deflt) -tab4: ; functions - .db "PEEK" - dwa(peek) - .db "RND" - dwa(rnd) - .db "ABS" - dwa(abs) - .db "USR" - dwa(usrexec) - .db "SIZE" - dwa(size) - dwa(xp40) -tab5: ; 'TO' in 'FOR' - .db "TO" - dwa(fr1) -tab6: ; 'STEP' in 'FOR' - .db "STEP" - dwa(fr2) - dwa(fr3) -tab8: ; relational operators - .db ">=" - dwa(xp11) - .db "#" - dwa(xp12) - .db ">" - dwa(xp13) - .db "=" - dwa(xp15) - .db "<=" - dwa(xp14) - .db "<" - dwa(xp16) - dwa(xp17) +tab2: ; direct/statement + .db "NEXT" + dwa(next) + .db "LET" + dwa(let) + .db "IF" + dwa(iff) + .db "GOTO" + dwa(goto) + .db "GOSUB" + dwa(gosub) + .db "RETURN" + dwa(return) + .db "REM" + dwa(rem) + .db "FOR" + dwa(for) + .db "INPUT" + dwa(input) + .db "PRINT" + dwa(print) + .db "POKE" + dwa(poke) + .db "END" + dwa(endd) + dwa(deflt) +tab4: ; functions + .db "PEEK" + dwa(peek) + .db "RND" + dwa(rnd) + .db "ABS" + dwa(abs) + .db "USR" + dwa(usrexec) + .db "SIZE" + dwa(size) + dwa(xp40) +tab5: ; 'TO' in 'FOR' + .db "TO" + dwa(fr1) +tab6: ; 'STEP' in 'FOR' + .db "STEP" + dwa(fr2) + dwa(fr3) +tab8: ; relational operators + .db ">=" + dwa(xp11) + .db "#" + dwa(xp12) + .db ">" + dwa(xp13) + .db "=" + dwa(xp15) + .db "<=" + dwa(xp14) + .db "<" + dwa(xp16) + dwa(xp17) direct: - ld hl,tab1-1 ; ** Direct ** + ld hl,tab1-1 ; ** Direct ** exec: - call skipspace ; ** Exec ** - push de + call skipspace ; ** Exec ** + push de ex1: - ld a,(de) - inc de - cp '.' - jr z,ex3 - inc hl - cp (hl) - jr z,ex1 - ld a,7fh - dec de - cp (hl) - jr c,ex5 + ld a,(de) + inc de + cp '.' + jr z,ex3 + inc hl + cp (hl) + jr z,ex1 + ld a,7fh + dec de + cp (hl) + jr c,ex5 ex2: - inc hl - cp (hl) - jr nc,ex2 - inc hl - pop de - jr exec + inc hl + cp (hl) + jr nc,ex2 + inc hl + pop de + jr exec ex3: - ld a,7fh + ld a,7fh ex4: - inc hl - cp (hl) - jr nc,ex4 + inc hl + cp (hl) + jr nc,ex4 ex5: - ld a,(hl) - inc hl - ld l,(hl) - and 7fh - ld h,a - pop af - jp (hl) + ld a,(hl) + inc hl + ld l,(hl) + and 7fh + ld h,a + pop af + jp (hl) ;------------------------------------------------------------------------------- -LST_ROM: ; all the above _can_ be in rom - ; all following *must* be in ram - .org (TBC_LOC + 09feh) -usrptr: .ds 2 ; -> user defined function area - .org (TBC_LOC + 0a00h) -usrfunc .ds 2 ; start of user defined function area - .org (TBC_LOC + 0c00h) ; start of state -ocsw .ds 1 ; output control switch -current .ds 2 ; points to current line -stkgos .ds 2 ; saves sp in 'GOSUB' -varnext .ds 2 ; temp storage -stkinp .ds 2 ; save sp in 'INPUT' -loopvar .ds 2 ; 'FOR' loop save area -loopinc .ds 2 ; loop increment -looplmt .ds 2 ; loop limit -loopln .ds 2 ; loop line number -loopptr .ds 2 ; loop text pointer -rndptr .ds 2 ; random number pointer -textunfilled .ds 2 ; -> unfilled text area -textbegin .ds 2 ; start of text save area - .org (TBC_LOC + 07dffh) -textend .ds 0 ; end of text area -varbegin .ds 55 ; variable @(0) -varend .ds 0 ; end of variable area -buffer .ds 72 ; input buffer -bufend .ds 1 -stacklimit .ds 1 - .org (TBC_LOC + 07fffh) -stack .equ $ +LST_ROM: ; all the above _can_ be in rom + ; all following *must* be in ram + .org (TBC_LOC + 09feh) +usrptr: .ds 2 ; -> user defined function area + .org (TBC_LOC + 0a00h) +usrfunc .ds 2 ; start of user defined function area + .org (TBC_LOC + 0c00h) ; start of state +ocsw .ds 1 ; output control switch +current .ds 2 ; points to current line +stkgos .ds 2 ; saves sp in 'GOSUB' +varnext .ds 2 ; temp storage +stkinp .ds 2 ; save sp in 'INPUT' +loopvar .ds 2 ; 'FOR' loop save area +loopinc .ds 2 ; loop increment +looplmt .ds 2 ; loop limit +loopln .ds 2 ; loop line number +loopptr .ds 2 ; loop text pointer +rndptr .ds 2 ; random number pointer +textunfilled .ds 2 ; -> unfilled text area +textbegin .ds 2 ; start of text save area + .org (TBC_LOC + 07dffh) +textend .ds 0 ; end of text area +varbegin .ds 55 ; variable @(0) +varend .ds 0 ; end of variable area +buffer .ds 72 ; input buffer +bufend .ds 1 +stacklimit .ds 1 + .org (TBC_LOC + 07fffh) +stack .equ $ #ifndef ZEMU -SLACK .EQU (TBC_END - LST_ROM) - .FILL SLACK,'t' +SLACK .EQU (TBC_END - LST_ROM) + .FILL SLACK,'t' - .ECHO "TASTYBASIC space remaining: " - .ECHO SLACK - .ECHO " bytes.\n" + .ECHO "TASTYBASIC space remaining: " + .ECHO SLACK + .ECHO " bytes.\n" #endif - .end + .end diff --git a/Source/HBIOS/uart.asm b/Source/HBIOS/uart.asm index d29ccc46..220749d6 100644 --- a/Source/HBIOS/uart.asm +++ b/Source/HBIOS/uart.asm @@ -575,7 +575,7 @@ UART_CFG: .DB 0 ; UART TYPE .DB $68 ; IO PORT BASE (RBR, THR) .DB $68 + UART_LSR ; LINE STATUS PORT (LSR) - .DW DEFSERCFG ; LINE CONFIGURATION + .DW UARTCFG ; LINE CONFIGURATION .FILL 2,$FF ; FILLER #ENDIF #IF (UARTCAS) @@ -593,7 +593,7 @@ UART_CFG: .DB 0 ; UART TYPE .DB $48 ; IO PORT BASE (RBR, THR) .DB $48 + UART_LSR ; LINE STATUS PORT (LSR) - .DW DEFSERCFG ; LINE CONFIGURATION + .DW UARTCFG ; LINE CONFIGURATION .FILL 2,$FF ; FILLER #ENDIF #IF (UART4) @@ -602,28 +602,28 @@ UART_CFG: .DB 0 ; UART TYPE .DB $C0 ; IO PORT BASE (RBR, THR) .DB $C0 + UART_LSR ; LINE STATUS PORT (LSR) - .DW DEFSERCFG ; LINE CONFIGURATION + .DW UARTCFG ; LINE CONFIGURATION .FILL 2,$FF ; FILLER ; 4UART SERIAL PORT B .DB 0 ; DEVICE NUMBER (UPDATED DURING INIT) .DB 0 ; UART TYPE .DB $C8 ; IO PORT BASE (RBR, THR) .DB $C8 + UART_LSR ; LINE STATUS PORT (LSR) - .DW DEFSERCFG ; LINE CONFIGURATION + .DW UARTCFG ; LINE CONFIGURATION .FILL 2,$FF ; FILLER ; 4UART SERIAL PORT C .DB 0 ; DEVICE NUMBER (UPDATED DURING INIT) .DB 0 ; UART TYPE .DB $D0 ; IO PORT BASE (RBR, THR) .DB $D0 + UART_LSR ; LINE STATUS PORT (LSR) - .DW DEFSERCFG ; LINE CONFIGURATION + .DW UARTCFG ; LINE CONFIGURATION .FILL 2,$FF ; FILLER ; 4UART SERIAL PORT D .DB 0 ; DEVICE NUMBER (UPDATED DURING INIT) .DB 0 ; UART TYPE .DB $D8 ; IO PORT BASE (RBR, THR) .DB $D8 + UART_LSR ; LINE STATUS PORT (LSR) - .DW DEFSERCFG ; LINE CONFIGURATION + .DW UARTCFG ; LINE CONFIGURATION .FILL 2,$FF ; FILLER #ENDIF ; diff --git a/Source/HBIOS/vdu.asm b/Source/HBIOS/vdu.asm index e1b220d6..bc888aa5 100644 --- a/Source/HBIOS/vdu.asm +++ b/Source/HBIOS/vdu.asm @@ -461,21 +461,13 @@ VDU_BLKCPY: LD A,31 ; PREP VDU FOR DATA R/W OUT (VDU_REG),A ; DO IT LD HL,VDU_BUF ; HL POINTS TO WORK BUFFER -; LD C,VDU_RAMWR ; LOAD C WITH VDU WRITE REGISTER + LD C,VDU_RAMRD ; LOAD C WITH VDU READ REGISTER VDU_BLKCPY1: ; VIDEO RAM -> BUFFER COPY LOOP CALL VDU_WAITRDY ; WAIT FOR VDU -;;;;;;;;;;;;;;;;; -; INI IS NOT WORKING FOR ME, GARBAGE DATA READS, NO IDEA WHY -; INI ; READ BYTE, DEC B, INC HL -; IN A,(VDU_DATA) ; BOGUS READ TO INCREMENT VDU RAM ADDRESS!!! -; JR NZ,VDU_BLKCPY1 ; LOOP TILL DONE -;;;;;;;;;;;;;;;;; - IN A,(VDU_RAMRD) ; READ DATA BYTE - LD (HL),A ; SAVE IN BUFFER - INC HL ; BUMP SOURCE ADDRESS + INI ; READ BYTE, DEC B, INC HL IN A,(VDU_DATA) ; BOGUS READ TO INCREMENT VDU RAM ADDRESS!!! - DJNZ VDU_BLKCPY1 ; LOOP TILL DONE + JR NZ,VDU_BLKCPY1 ; LOOP TILL DONE ; SETUP TO COPY FROM WORK BUFFER TO VDU DEST POP BC ; RECOVER THE COPY LENGTH diff --git a/Source/HBIOS/xio.asm b/Source/HBIOS/xio.asm index 31a7d986..b1c15c3e 100644 --- a/Source/HBIOS/xio.asm +++ b/Source/HBIOS/xio.asm @@ -49,7 +49,7 @@ XIO_INIT: ; MINIMAL UART INIT ;OUT0 (Z180_CNTLB0),A ; -> CNTLB0 ; TRY TO IMPLEMENT CONFIGURED BAUD RATE - LD HL,DEFSERCFG ; SERIAL CONFIG WORD + LD HL,XIOCFG ; SERIAL CONFIG WORD LD A,H ; BYTE W/ ENCODED BAUD RATE AND $1F ; ISOLATE BITS LD L,A ; MOVE TO L @@ -65,7 +65,7 @@ XIO_INIT1: #IF ((PLATFORM == PLT_SBC) | (PLATFORM == PLT_ZETA) | (PLATFORM == PLT_ZETA2)) - LD DE,DEFSERCFG ; SERIAL CONFIG WORD + LD DE,XIOCFG ; SERIAL CONFIG WORD CALL XIO_COMPDIV ; COMPUTE DIVISOR TO BC LD A,$80 ; LCR := DLAB ON diff --git a/Source/Images/Makefile b/Source/Images/Makefile index 277ee494..4832dc37 100644 --- a/Source/Images/Makefile +++ b/Source/Images/Makefile @@ -73,9 +73,7 @@ blankhd: if [ -f d_$$d.txt ] ; then \ echo " " copying files from d_$$d.txt ; \ grep -v ^# d_$$d.txt | tr -d '\r' | while read file user ; do \ - hack= ; \ - if [ "$$file" = "../../Binary/Apps/Tunes/*.*" ] ; then hack=../../Binary/Apps/Tunes/Makefile ; fi ; \ - rf=$$($(CASEFN) $$hack $$file | sort -V) ; \ + rf=$$($(CASEFN) $$file | sort -V) ; \ echo " " $$rf ; \ if [ -z "$$rf" ] ; then \ echo " " $$file missing ; \ diff --git a/Source/Makefile b/Source/Makefile index 1204b022..166bb4c1 100644 --- a/Source/Makefile +++ b/Source/Makefile @@ -1,7 +1,6 @@ # # order is actually important, because of build dependencies # -NOTDONE = Doc SUBDIRS = Prop SUBDIRS += Apps SUBDIRS += CBIOS diff --git a/Source/ReadMe.txt b/Source/ReadMe.txt index 7f3895b2..fd6b5ae0 100644 --- a/Source/ReadMe.txt +++ b/Source/ReadMe.txt @@ -329,11 +329,6 @@ BuildBP: This command builds another OS variant called BPBIOS. It is a work in progress and should not be used at this time without contacting Wayne Warthen. -BuildDoc: This command is used to build a new generation of RomWBW - documentation based on LaTeX. This is also a work in - progress and requires LaTeX be installed on your Windows - computer. It is not intended for use at this time. - Example BuildShared Run ----------------------- diff --git a/Source/ver.inc b/Source/ver.inc index dda78577..02742296 100644 --- a/Source/ver.inc +++ b/Source/ver.inc @@ -2,4 +2,4 @@ #DEFINE RMN 9 #DEFINE RUP 2 #DEFINE RTP 0 -#DEFINE BIOSVER "2.9.2-pre.35" +#DEFINE BIOSVER "2.9.2-pre.37" diff --git a/Source/ver.lib b/Source/ver.lib index 870f44ee..a1c3667c 100644 --- a/Source/ver.lib +++ b/Source/ver.lib @@ -3,5 +3,5 @@ rmn equ 9 rup equ 2 rtp equ 0 biosver macro - db "2.9.2-pre.35" + db "2.9.2-pre.37" endm