From e1d2eb1ecdb229b9ecf62e42a07e537db459fb51 Mon Sep 17 00:00:00 2001 From: Wayne Warthen Date: Wed, 2 May 2018 15:04:47 -0700 Subject: [PATCH] Comments in PowerShell Build Script --- Source/HBIOS/Build.ps1 | 114 ++++++++++++++++++++++++++++++++++------- 1 file changed, 96 insertions(+), 18 deletions(-) diff --git a/Source/HBIOS/Build.ps1 b/Source/HBIOS/Build.ps1 index 8f1af1bc..d56b4066 100644 --- a/Source/HBIOS/Build.ps1 +++ b/Source/HBIOS/Build.ps1 @@ -1,5 +1,30 @@ param([string]$Platform = "", [string]$Config = "", [string]$RomSize = "512", [string]$RomName = "") +# +# This PowerShell script performs the heavy lifting in the build of RomWBW. It handles the assembly +# of the HBIOS and then creates the final ROM image imbedding the other components such as the OS +# images, boot loader, and ROM disk image. +# +# The RomWBW build is heavily dependent on the concept of a hardware "platform" and the associated +# "configuration". The build process selects a pair of files that are included in the HBIOS assembly +# to create the hardware-specific ROM image. First, a platform file called cfg_.asm is +# included to establish the required assembly equates for the main hardware platform. Second, a +# file from the Config subdirectory is included to tune the build for the specific setup of the +# desired hardware platform. The platform file establishes all of the default equate values for +# the platform being built. The config file is used to override the values in the platform file +# as desired. +# +# Note that there is a special platform called UNA. UNA is John Coffman's hardware BIOS which is an +# alternative to HBIOS. UNA is a single image that will run on all platforms and has a built-in +# setup mechanism so that multiple configuration are not needed. When building for UNA, the pre-built +# UNA BIOS is simply imbedded, it is not built here. +# + +# +# Establish the build platform. It may have been passed in on the command line. Validate +# $Platform and loop requesting a new value as long as it is not valid. The valid platform +# names are just hard-coded for now. +# $Platform = $Platform.ToUpper() while ($true) { @@ -7,9 +32,15 @@ while ($true) $Platform = (Read-Host -prompt "Platform [SBC|ZETA|ZETA2|RC|N8|MK4|UNA]").Trim().ToUpper() } +# +# Establish the platform configuration to build. It may have been passed in on the commandline. Validate +# $Config and loop requesting a new value as long as it is not valid. The file system is scanned to determine +# if the requested ConfigFile exists. Config files must be named _.asm where is +# the platform name established above and is the value of $Config determined here. +# while ($true) { -; $PlatformConfigFile = "Config/plt_${Platform}.asm" + $PlatformConfigFile = "Config/plt_${Platform}.asm" $ConfigFile = "Config/${Platform}_${Config}.asm" if (Test-Path $ConfigFile) {break} if ($Config -ne "") {Write-Host "${ConfigFile} does not exist!"} @@ -19,14 +50,29 @@ while ($true) $Config = (Read-Host -prompt "Configuration").Trim() } +# +# Establish the ROM size (in KB). It may have been passed in on the command line. Validate +# $RomSize and loop requesting a new value as long as it is not valid. The valid ROM sizes +# are just hard-coded for now. The ROM size does nothing more than determine the size of the +# ROM disk portion of the ROM image. +# while ($true) { if (($RomSize -eq "512") -or ($RomSize -eq "1024")) {break} $RomSize = (Read-Host -prompt "ROM Size [512|1024]").Trim() } +# +# TASM should be invoked with the proper CPU type. Below, the CPU type is inferred +# from the platform. +# if (($Platform -eq "N8") -or ($Platform -eq "MK4")) {$CPUType = "180"} else {$CPUType = "80"} +# +# The $RomName variable determines the name of the image created by the script. By default, +# this will be _.rom. Unless the script was invoked with a specified +# ROM filename, the name is established below. +# if ($RomName -eq "") {$RomName = "${Platform}_${Config}"} while ($RomName -eq "") { @@ -34,32 +80,40 @@ while ($RomName -eq "") if ($RomName -eq "") {$RomName = $Config} } +# If a PowerShell exception occurs, just stop the script immediately. $ErrorAction = 'Stop' +# Directories of required build tools (TASM & cpmtools) $TasmPath = '..\..\tools\tasm32' $CpmToolsPath = '..\..\tools\cpmtools' +# Add tool directories to PATH and setup TASM's TABS directory path $env:TASMTABS = $TasmPath $env:PATH = $TasmPath + ';' + $CpmToolsPath + ';' + $env:PATH -$OutDir = "../../Binary" -$RomFmt = "wbw_rom${RomSize}" -$BlankROM = "Blank${RomSize}KB.dat" -$RomDiskFile = "RomDisk.tmp" -$RomFile = "${OutDir}/${RomName}.rom" -$ComFile = "${OutDir}/${RomName}.com" -$ImgFile = "${OutDir}/${RomName}.img" +# Initialize working variables +$OutDir = "../../Binary" # Output directory for final image file +$RomFmt = "wbw_rom${RomSize}" # Location of files to imbed in ROM disk +$BlankROM = "Blank${RomSize}KB.dat" # An initial "empty" image for the ROM disk of propoer size +$RomDiskFile = "RomDisk.tmp" # Temporary filename used to create ROM disk image +$RomFile = "${OutDir}/${RomName}.rom" # Final name of ROM image +$ComFile = "${OutDir}/${RomName}.com" # Final name of COM image (command line loadable HBIOS/CBIOS) +$ImgFile = "${OutDir}/${RomName}.img" # Final name of IMG image (memory loadable HBIOS/CBIOS image) + +# Select the proper CBIOS to include in the ROM. UNA is special. if ($Platform -eq "UNA") {$CBiosFile = '../CBIOS/cbios_una.bin'} else {$CBiosFile = '../CBIOS/cbios_wbw.bin'} +# List of RomWBW proprietary apps to imbed in ROM disk. $RomApps = "assign","fdu","format","mode","osldr","rtc","survey","syscopy","sysgen","talk","timer","xm" "" "Building ${RomName}: ${ROMSize}KB ROM configuration ${Config} for Z${CPUType}..." "" -# $TimeStamp = '"' + (Get-Date -Format 'dd-MMM-yyyy') + '"' +# Current date/time is queried here to be subsequently imbedded in image $TimeStamp = '"' + (Get-Date -Format 'yyyy-MM-dd') + '"' +# Function to run TASM and throw an exception if an error occurs. Function Asm($Component, $Opt, $Architecture=$CPUType, $Output="${Component}.bin", $List="${Component}.lst") { $Cmd = "tasm -t${Architecture} -g3 ${Opt} ${Component}.asm ${Output} ${List}" @@ -68,6 +122,7 @@ Function Asm($Component, $Opt, $Architecture=$CPUType, $Output="${Component}.bin if ($LASTEXITCODE -gt 0) {throw "TASM returned exit code $LASTEXITCODE"} } +# Function to concatenate two binary files. Function Concat($InputFileList, $OutputFile) { Set-Content $OutputFile -Value $null @@ -77,7 +132,11 @@ Function Concat($InputFileList, $OutputFile) } } -# Generate the build settings include file +# +# Since TASM has no mechanism to include files dynamically based on variables, a file +# if built on-the-fly here for imbedding in the build process. This file is basically +# just used to include the platform and config files. It also passes in some values +# from the build to include in the build. @" ; RomWBW Configured for ${Platform} ${Config}, $(Get-Date -Format "s") @@ -92,12 +151,15 @@ ROMSIZE .EQU ${ROMSize} ; SIZE OF ROM IN KB ; "@ | Out-File "build.inc" -Encoding ASCII +# Create a local copy of the CP/M CCP and BDOS images for later use. Copy-Item '..\cpm22\os2ccp.bin' 'ccp.bin' Copy-Item '..\cpm22\os3bdos.bin' 'bdos.bin' +# Create a local copy of the ZSystem CCP and BDOS images for later use. Copy-Item '..\zcpr-dj\zcpr.bin' 'zcpr.bin' Copy-Item '..\zsdos\zsdos.bin' 'zsdos.bin' +# Assemble individual components. Note in the case of UNA, there is less to build. Asm 'dbgmon' Asm 'prefix' Asm 'romldr' @@ -108,39 +170,56 @@ if ($Platform -ne "UNA") Asm 'hbios' '-dIMGBOOT' -Output 'hbios_img.bin' -List 'hbios_img.lst' } -# Generate result files using components above - +# +# Once all of the individual binary components have been created above, the final +# ROM image is created by simply concatenating the pieces together as needed. +# "Building ${RomName} output files..." +# Combine the CCP and BDOS portions of CP/M and ZSystem to create OS images Concat 'ccp.bin','bdos.bin',$CBiosFile 'cpm.bin' Concat 'zcpr.bin','zsdos.bin',$CBiosFile 'zsys.bin' +# Prepend a bit of boot code required to bootstrap the OS images Concat 'prefix.bin','cpm.bin' 'cpm.sys' Concat 'prefix.bin','zsys.bin' 'zsys.sys' +# Build 32K OS chunk containing the loader, debug monitor, and OS images Concat 'romldr.bin', 'dbgmon.bin','cpm.bin','zsys.bin' osimg.bin -# Create the RomDisk image +# +# Now the ROM disk image is created. This is done by starting with a +# blank ROM disk image of the correct size, then cpmtools is used to +# add the desired files. +# "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 + +# Copy all files from the appropriate directory to the working ROM disk image cpmcp -f $RomFmt $RomDiskFile ../RomDsk/ROM_${RomSize}KB/*.* 0: -#cpmcp -f $RomFmt $RomDiskFile ../RomDsk/${Platform}_${Config}/*.* 0: + +# Add any platform specific files to the working ROM disk image if (Test-Path "../RomDsk/${Platform}/*.*") { cpmcp -f $RomFmt $RomDiskFile ../RomDsk/${Platform}/*.* 0: } +# Add the proprietary RomWBW applications to the working ROM disk image foreach ($App in $RomApps) { cpmcp -f $RomFmt $RomDiskFile ../../Binary/Apps/$App.com 0: } - -# cpmcp -f $RomFmt $RomDiskFile ../Apps/*.com 0: +# Add the CP/M and ZSystem system images to the ROM disk (used by SYSCOPY) cpmcp -f $RomFmt $RomDiskFile *.sys 0: +# +# Finally, the individual binary components are concatenated together to produce +# the final images. +# if ($Platform -eq "UNA") { Copy-Item 'osimg.bin' ${OutDir}\UNA_WBW_SYS.bin @@ -155,6 +234,5 @@ else Concat 'hbios_img.bin','osimg.bin' $ImgFile } -# Cleanup - +# Remove the temprary working ROM disk file Remove-Item $RomDiskFile \ No newline at end of file