Pegasys-RomWBW/Source/ReadMe.txt

***********************************************************************
***                                                                 ***
***                          R o m W B W                            ***
***                                                                 ***
***                    Z80/Z180 System Software                     ***
***                                                                 ***
***********************************************************************

This directory is the root directory for the source tree for RomWBW.

This document describes the process to build a customized version 
of the RomWBW firmware.  RomWBW was explicitly organized in a way 
that makes it very easy to rebuild the firmware.

Significant customization can be achieved with a custom built 
firmware using simple option configuration files.  You can 
customize your firmware to:

    - Include support for add-on support boards such as
      the DiskIO, Dual-IDE, etc.
    - Modify operational parameters such as serial port
      speed or wait state insertion.
    - Add or remove programs or files contained on the ROM disk.
    
Thought not necessary, advanced users can easily modify any of
the software including the operating systems.

A cross-platform approach is used to build the RomWBW firmware. 
The software is built using a modern Windows, Linux, or Mac
computer, then the resulting firmware image is programmed into
the ROM of your RetroBrew Computer CPU board.

Build System Requirements
-------------------------

For Linux/Mac computers, refer to the ReadMe.unix file in the
top directory of the distribution.

For Microsoft Windows computers, All that is required to build the
firmware is the RomWBW distribution zip archive file.  The zip
archive package includes all of the required source code 
(including the operating systems) and the programs required to run 
the build.

The build process is run via some simple scripts that automate the 
process.  These scripts utilize both batch command files as well as 
Windows PowerShell.  All versions of Microsoft Windows starting with 
Vista include PowerShell and will run the build process with no 
addtional programs required.  Either 32 or 64 bit versions of 
Microsoft Windows are fine.

Process Overview
----------------

The basic steps to create a custom ROM are:

  1) Create/update configuration file

  2) Update/Add/Delete any files you want incorporated in the
     ROM Disk

  3) Run the build scripts and confirm there are no errors.

  4) Program the resultant ROM image and try it.

Note that steps 1 and 2 are performed to customize your ROM as 
desired.  If you want to simply build a standard configuration, it is 
*not* necessary to perform steps 1 or 2 before running a build.  In 
fact, I strongly recommend that you skip steps 1 and 2 initially and 
just perform perform steps 3 and 4 using the standard configuration to 
make sure that you have no issues building and programming a ROM that 
works the same as a pre-built ROM.

Each of the 4 steps above is described in more detail below.

1. Create/Update Configuration File
-----------------------------------

The options for a build are primarily controlled by a configuration 
file that is included in the build process.  In order to customize 
your settings, it is easiest to make a copy of an existing 
configuration file and make your changes there.

Configuration files are found in the Source\HBIOS\Config 
directory.  If you look in the this directory, you will see a 
series of files named <plt>_<cfg>.asm where <plt> refers to the 
CPU board in your system and <cfg> is used to name the specific 
configuration so you can maintain multiple configurations.

You will notice that there is generally one configuration file for 
each CPU platform with a name of "std".  For example, you there is 
a file called MK4_std.asm.  This is the standard ("std") 
configuration for a Mark IV CPU board.

The platform names are predefined.  Refer to the following table 
to determine the <plt> component of the configuration filename:

	SBC V1/V2	SBC_std.rom
	SBC SimH	SBC_simh.rom
	Zeta V1		ZETA_std.rom
	Zeta V2		ZETA2_std.rom
	N8		N8_std.rom
	Mark IV		MK4_std.rom
	RC2014 w/ Z80	RCZ80_std.rom
	RC2014 w/ Z180	RCZ180_nat.rom	(native Z180 memory addressing)
	RC2014 w/ Z180	RCZ180_ext.rom	(external 512K RAM/ROM module)
	SCZ180		SC126, SC130, SC131
	Easy Z80	EZZ180_std.rom
	Dyno		DYNO_std.rom

You can use any name you choose for the <cfg> component of the 
configuration filename.  So, let's say you want to create a custom 
ROM for the Mark IV.  You would simply copy "MK4_std.asm" to 
something like "MK4_cust.asm".  Now, just edit the new file 
("MK4_cust.asm" in this example) as desired.

You will see that the file already has lines for all of the common 
options and there is a comment after each option indicating the 
possible values.

In our example, let's say you have added a Dual-IDE board to your 
Mark IV system and want to include floppy support. You will see a 
couple lines similar to these in the config file:

FDENABLE  .SET	FALSE		; TRUE FOR FLOPPY DEVICE SUPPORT
FDMODE    .SET	FDMODE_DIDE	; FDMODE_DIO, FDMODE_DIDE, FDMODE_DIO3

To enable floppy support, you would just change FDENABLE to TRUE:

FDENABLE  .SET	TRUE		; TRUE FOR FLOPPY DEVICE SUPPORT

Since FDMODE is already set to FDMODE_DIDE, it is correct as is.  
If instead, you had added a DiskIO V3 board and wanted to use it 
for floppy support, you would also change FDMODE to 
FDMODE_FDMODE_DIO3:

FDMODE    .SET	FDMODE_DIO3	; FDMODE_DIO, FDMODE_DIDE, FDMODE_DIO3

2. Update/Add/Delete ROM Disk Files
-----------------------------------

The files that are included on the ROM Disk of your ROM are copied 
from a set of directories during the build process.  This allows 
you to have complete flexibility over the files you want included 
in your ROM.

These directories are already populated in the distribution.  You do 
not need to do anything unless you want to change the files that are 
included in the ROM Disk.

In summary, the ROM Disk embedded in the ROM firmware you build, 
will include the files from the ROM_512KB directory (or the 
ROM_1024KB directory if building a 1024KB firmware).  
Additionally, files will be added from the directory associated 
with the platform specified in the ROM Build.

There is a ReadMe.txt document in the \Source\RomDsk directory 
with a more detailed description of this process.

Note that the standard 512K ROM disk is absolutely full.  So, if
you want to add files to it, you will need to delete other files
to free up some space.

3. Run the Build Process
------------------------

This section describes the build process for Microsoft Windows
computers.  The build process for Linux/Mac computers is described
in the ReadMe.unix file in the top level directory of the
distribution.

The build involves running commands at the command prompt.  Open a 
command prompt window for the Source directory.  If you unzipped 
the distribution to "C:\", then your command prompt should look 
like this:

    C:\RomWBW\Source>

Now run the first of two commands, the BuildShared command:

    C:\RomWBW\Source> BuildShared

This command will run a series of commands that generate the 
software which is "shared" by all ROM builds.  It is normal to 
have some lines indicating a warning like the following.  This is 
normal and expected.

    ++ Warning: program origin NOT at 100H ++
    
A sample run of the BuildShared command is provided later in this 
document.

Now run the second command, the BuildROM command:

    C:\RomWBW\Source> BuildROM

This command will prompt you twice as it runs.  These prompts 
determine the platform and configuration to be built.  The first 
prompt is for the platform, as shown below:

    Platform [SBC|ZETA|ZETA2|RCZ80|EZZ80|UNA|N8|MK4|RCZ180|SCZ180|DYNO]:

Enter the option corresponding to the platform of the ROM firmware 
you are building.  If you enter something other than one of the 
possible options, the prompt will be repeated until you provide an 
acceptable response.

Next, you will be prompted for the specific configuration of the 
platform to be built.  The options presented will be based on the 
configuration files in the Config directory.  So, if you have made 
a copy of the MK4_std.asm config and called it MK4_cust.asm, you 
would see a prompt like this:

    Configurations available:
     > std
     > cust
    Configuration:

Enter one of the configuration options to build a ROM with the 
associated config file.

At this point, the build should run and you will see output 
related to the assembler runs and some utility invocations.  Just 
review the output for any obvioius errors.  Normally, all errors 
will cause the build to stop immediately and display an error 
message in red.

A sample run of the BuildROM command is provided later in this 
document.

You will see some lines in the output indicating the amount of 
space various components have taken.  You should check these to 
make sure you do not see any negative numbers which would indicate 
that you have included too many features/drivers for the available 
memory space.  Here are examples of the lines showing the space 
used:

    HBIOS PROXY STACK space: 38 bytes.
    HBIOS INT space remaining: 82 bytes.
    DSRTC occupies 423 bytes.
    UART occupies 716 bytes.
    ASCI occupies 580 bytes.
    MD occupies 451 bytes.
    IDE occupies 1276 bytes.
    SD occupies 2191 bytes.
    HBIOS space remaining: 21434 bytes.

Optionally, you can run one more command that will create the
RomWBW disk images that can be subsequently written to actual
disk media.

    C:\RomWBW\Source> BuildImages

After running this command, you will find the resultant
disk image file in the Binary directory with names in the
format fd_xxx.img for floppy media or hd_xxx.img for
hard disk media.  Refer to the DiskList.txt file in the
Binary directory for more information on using the disk
image files.

4. Deploy the ROM
-----------------

Upon completion of a successful build, you should find the 
resulting firmware in the Binary directory.  These output files 
will have names that match the config filename, but with different 
extensions.

Three output files will be created for a single BuildROM run:

     <plt>_<cfg>.rom - binary ROM image to burn to EEPROM
     <plt>_<cfg>.com - executable version of the system image
                       that can be copied via X-Modem to a
		       running system to test the build.

The actual ROM image is the file ending in .rom.  It should be 
exactly 512KB.  Simply burn the .rom image to your ROM and install 
it in your hardware.  The process for programming your ROM depends 
on your hardware, but the .rom file is in a pure binary format (it 
is not hex encoded).

Refer to the document ReadMe.txt in the Binary directory for more 
information on the other two file extensions created.

Specifying Build Options on Command Line
----------------------------------------

If you don't want to be prompted for the options to the "BuildROM" 
command, you can specify the options right on the command line.

For example:

    C:\RomWBW\Source> BuildROM MK4 cust

In this case, you will not be prompted.  This is useful if you wish 
to automate your build process.

There is a third parameter that you can specify to the BuildROM 
command via a command line.  If you want to build a 1024K (1MB) ROM, 
you can add "1024" to the end of the line, like this:

    C:\RomWBW\Source> BuildROM MK4 cust 1024

You must ensure that your system actually supports a 1024K ROM.

Special Build Commands
----------------------

You may notice there are a few additional Build*.cmd files in the 
Source directory.  They are not used or required for building ROM 
firmware.  Their purpose is described below:

BuildProp: Some RetroBrew Computer peripheral boards are based
           on the Parallax Propeller.  The Propeller requires
           custom onboard EEPROM firmware to operate.  This
           command file builds the firmware images for each
           of the Propeller-based boards.

BuildImages: RomWBW has the ability to create floppy disk and hard
             disk images for use on systems running the RomWBW
	     firmware.  This script allows you to place the files
	     you want on a CP/M floppy or hard disk in a directory
	     and will turn them into a writable disk image.  Refer
	     to the ReadMe.txt document in the Source\Images
	     directory for a detailed description of this process.
	     N.B., BuildShared must be run prior to BuildImages.

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.

Example BuildShared Run
-----------------------

C:\RomWBW\Source> BuildShared

Building SysCopy...
TASM Z80 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
tasm: pass 2 complete.
tasm: Number of errors = 0

Building Assign...
TASM Z80 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
tasm: pass 2 complete.
tasm: Number of errors = 0

Building Format...
TASM Z80 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
tasm: pass 2 complete.
tasm: Number of errors = 0

Building Talk...
TASM Z80 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
tasm: pass 2 complete.
tasm: Number of errors = 0

Building OSLdr...
TASM Z80 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
tasm: pass 2 complete.
tasm: Number of errors = 0

Z80ASM Copyright (C) 1983-86 by SLR Systems Rel. 1.32 #AB1234

 SYSGEN/F
End of file Pass 1
End of file Pass 2
 0 Error(s) Detected.
 1132 Absolute Bytes. 80 Symbols Detected.



Building ccpb03...
TASM Z80 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
tasm: pass 2 complete.
tasm: Number of errors = 0

Building bdosb01...
TASM Z80 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
tasm: pass 2 complete.
tasm: Number of errors = 0
CP/M MACRO ASSEM 2.0
D7F2
00BH USE FACTOR
END OF ASSEMBLY

MLOAD v25  Copyright (c) 1983, 1984, 1985, 1988
by NightOwl Software, Inc.
Loaded 1887 bytes (075FH) to file P0:CCP.BIN
Start address: D000H  Ending address: D7BAH  Bias: 0000H
Saved image size: 2048 bytes (0800H, - 16 records)

++ Warning: program origin NOT at 100H ++

CP/M MACRO ASSEM 2.0
E5EE
017H USE FACTOR
END OF ASSEMBLY

MLOAD v25  Copyright (c) 1983, 1984, 1985, 1988
by NightOwl Software, Inc.
Loaded 3453 bytes (0D7DH) to file P0:BDOS.BIN
Start address: D800H  Ending address: E5B2H  Bias: 0000H
Saved image size: 3584 bytes (0E00H, - 28 records)

++ Warning: program origin NOT at 100H ++

CP/M MACRO ASSEM 2.0
D7F2
008H USE FACTOR
END OF ASSEMBLY

MLOAD v25  Copyright (c) 1983, 1984, 1985, 1988
by NightOwl Software, Inc.
Loaded 1906 bytes (0772H) to file P0:CCP22.BIN
Start address: D000H  Ending address: D7CCH  Bias: 0000H
Saved image size: 2048 bytes (0800H, - 16 records)

++ Warning: program origin NOT at 100H ++

CP/M MACRO ASSEM 2.0
E633
012H USE FACTOR
END OF ASSEMBLY

MLOAD v25  Copyright (c) 1983, 1984, 1985, 1988
by NightOwl Software, Inc.
Loaded 3518 bytes (0DBEH) to file P0:BDOS22.BIN
Start address: D800H  Ending address: E5EDH  Bias: 0000H
Saved image size: 3584 bytes (0E00H, - 28 records)

++ Warning: program origin NOT at 100H ++

CP/M MACRO ASSEM 2.0
D7F2
00BH USE FACTOR
END OF ASSEMBLY

MLOAD v25  Copyright (c) 1983, 1984, 1985, 1988
by NightOwl Software, Inc.
Loaded 1887 bytes (075FH) to file P0:OS2CCP.BIN
Start address: D000H  Ending address: D7BAH  Bias: 0000H
Saved image size: 2048 bytes (0800H, - 16 records)

++ Warning: program origin NOT at 100H ++

CP/M MACRO ASSEM 2.0
E5EE
017H USE FACTOR
END OF ASSEMBLY

MLOAD v25  Copyright (c) 1983, 1984, 1985, 1988
by NightOwl Software, Inc.
Loaded 3453 bytes (0D7DH) to file P0:OS3BDOS.BIN
Start address: D800H  Ending address: E5B2H  Bias: 0000H
Saved image size: 3584 bytes (0E00H, - 28 records)

++ Warning: program origin NOT at 100H ++

CP/M MACRO ASSEM 2.0
D7EF
00EH USE FACTOR
END OF ASSEMBLY

MLOAD v25  Copyright (c) 1983, 1984, 1985, 1988
by NightOwl Software, Inc.
Loaded 1888 bytes (0760H) to file P0:ZCPR.BIN
Start address: D000H  Ending address: D7EEH  Bias: 0000H
Saved image size: 2048 bytes (0800H, - 16 records)

++ Warning: program origin NOT at 100H ++

CP/M MACRO ASSEM 2.0
01B3
000H USE FACTOR
END OF ASSEMBLY

MLOAD v25  Copyright (c) 1983, 1984, 1985, 1988
by NightOwl Software, Inc.
Loaded 179 bytes (00B3H) to file P0:BDLOC.COM
Start address: 0100H  Ending address: 01B2H  Bias: 0000H
Saved image size: 256 bytes (0100H, - 2 records)


No Fatal error(s)


Link-80  3.44  09-Dec-81  Copyright (c) 1981 Microsoft

Data    0100    08F7    < 2039>

51779 Bytes Free
[0000   08F7        8]



ZMAC Relocating Macro Assembler v 1.7, 04/09/93
  Copyright 1988,1989 by A.E. Hawley


      P0:ZSDOS.Z80      assembled with   NO ERRORS

..To produce:

P0:ZSDOS.REL, P0:ZSDOS.PRN

Source Lines    3345          Unused Memory   7995H
Labels           429          Total Code Size 0DF6H
Macros  -Read   none
    -Expanded   none

               ===  SEGMENT SIZES  ===

ASEG    =empty   CSEG    =0DF6H   DSEG    =empty   BLANK   =empty

 Named COMMON segments

_BIOS_
LINK 1.31

/_BIOS_/ E600

ABSOLUTE     0000
CODE SIZE    0E00 (D800-E5FF)
DATA SIZE    0000
COMMON SIZE  0000
USE FACTOR     1C


Building CBIOS for RomWBW...

TASM Z80 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
CBIOS extension info occupies 6 bytes.
UTIL occupies 485 bytes.
INIT code slack space: 2924 bytes.
HEAP space: 4450 bytes.
CBIOS total space used: 6144 bytes.
tasm: pass 2 complete.
tasm: Number of errors = 0

Building CBIOS for UNA...

TASM Z80 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
CBIOS extension info occupies 6 bytes.
UTIL occupies 485 bytes.
INIT code slack space: 2909 bytes.
HEAP space: 4263 bytes.
CBIOS total space used: 6400 bytes.
tasm: pass 2 complete.
tasm: Number of errors = 0

Example BuildROM Run
-----------------------

C:\RomWBW\Source> BuildROM
Platform [SBC|ZETA|ZETA2|N8|MK4|UNA]: MK4
Configurations available:
 > std
 > cust
Configuration: cust

Building MK4_cust: 512KB ROM configuration cust for Z180...

tasm -t180 -g3  dbgmon.asm dbgmon.bin dbgmon.lst
TASM Z180 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
DBGMON space remaining: 1533 bytes.
tasm: pass 2 complete.
tasm: Number of errors = 0
tasm -t180 -g3  prefix.asm prefix.bin prefix.lst
TASM Z180 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
tasm: pass 2 complete.
tasm: Number of errors = 0
tasm -t180 -g3  romldr.asm romldr.bin romldr.lst
TASM Z180 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
LOADER space remaining: 1217 bytes.
tasm: pass 2 complete.
tasm: Number of errors = 0
tasm -t180 -g3 -dROMBOOT hbios.asm hbios_rom.bin hbios_rom.lst
TASM Z180 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
HBIOS PROXY STACK space: 38 bytes.
HBIOS INT space remaining: 82 bytes.
DSRTC occupies 423 bytes.
UART occupies 716 bytes.
ASCI occupies 580 bytes.
MD occupies 451 bytes.
IDE occupies 1276 bytes.
SD occupies 2191 bytes.
HBIOS space remaining: 21454 bytes.
tasm: pass 2 complete.
tasm: Number of errors = 0
tasm -t180 -g3 -dAPPBOOT hbios.asm hbios_app.bin hbios_app.lst
TASM Z180 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
HBIOS PROXY STACK space: 38 bytes.
HBIOS INT space remaining: 82 bytes.
DSRTC occupies 423 bytes.
UART occupies 716 bytes.
ASCI occupies 580 bytes.
MD occupies 451 bytes.
IDE occupies 1276 bytes.
SD occupies 2191 bytes.
HBIOS space remaining: 21434 bytes.
tasm: pass 2 complete.
tasm: Number of errors = 0
tasm -t180 -g3 -dIMGBOOT hbios.asm hbios_img.bin hbios_img.lst
TASM Z180 Assembler.       Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: pass 1 complete.
HBIOS PROXY STACK space: 38 bytes.
HBIOS INT space remaining: 82 bytes.
DSRTC occupies 423 bytes.
UART occupies 716 bytes.
ASCI occupies 580 bytes.
MD occupies 451 bytes.
IDE occupies 1276 bytes.
SD occupies 2191 bytes.
HBIOS space remaining: 21434 bytes.
tasm: pass 2 complete.
tasm: Number of errors = 0
Building MK4_cust output files...
Building 512KB MK4_cust ROM disk data file...