diff --git a/Binary/Apps/Test/inttest.doc b/Binary/Apps/Test/inttest.doc new file mode 100644 index 00000000..686c140a --- /dev/null +++ b/Binary/Apps/Test/inttest.doc @@ -0,0 +1,44 @@ +INTTEST +======= + +RomWBW includes an API allowing applications to "hook" interrupts. +The `INTTEST` utility allows you to test this functionality. + + +** Syntax ** + +`INTTEST` + + +** Usage ** + +`INTTEST` is an interactive application. At startup, it will display +a list of the interrupt vector slots in your system along with the +current vector address for each of them. + +It then prompts you to enter the slot number (in hex) of a vector to +hook. After entering this, the application will watch the hooked +vector and countdown from 0xFF to 0x00 as interrupts are noted. + +When the counter reaches 0x00, the interrupt is unhooked and the +application terminates. The application can also be terminated by +pressing . + + +** Notes ** + +If your system is running without interrupts active, the application +will terminate immediately. + +All slots have vectors even if the corresponding interrupt is not +doing anything. In this case, the vector is pointing to the "bad +interrupt" handler. + +If you hook a vector that is not receiving any interrupts, the +down-counter will not do anything. + + +** Etymology* * + +The `INTTEST` command is an original product and the source code is +provided in the RomWBW distribution. diff --git a/Doc/ChangeLog.txt b/Doc/ChangeLog.txt index a887c670..5292d99f 100644 --- a/Doc/ChangeLog.txt +++ b/Doc/ChangeLog.txt @@ -22,6 +22,8 @@ Version 3.5 - WBW: Preliminary support for S100 FPGA Z80 platform - WBW: Added simple serial (SSER) driver - WBW: Added preliminary support for S100 FPGA Z80 SD Cards +- M?R: Consolidated ROM Applications document into the Applications document +- M?R: Reviewed and substantially improved the Applications document Version 3.4 ----------- diff --git a/Doc/RomWBW Applications.pdf b/Doc/RomWBW Applications.pdf index 7bc642f0..9742b515 100644 Binary files a/Doc/RomWBW Applications.pdf and b/Doc/RomWBW Applications.pdf differ diff --git a/Doc/RomWBW Disk Catalog.pdf b/Doc/RomWBW Disk Catalog.pdf index 290acc31..da9ef38d 100644 Binary files a/Doc/RomWBW Disk Catalog.pdf and b/Doc/RomWBW Disk Catalog.pdf differ diff --git a/Doc/RomWBW Errata.pdf b/Doc/RomWBW Errata.pdf index af843051..23e45d77 100644 Binary files a/Doc/RomWBW Errata.pdf and b/Doc/RomWBW Errata.pdf differ diff --git a/Doc/RomWBW System Guide.pdf b/Doc/RomWBW System Guide.pdf index 81406708..eba96722 100644 Binary files a/Doc/RomWBW System Guide.pdf and b/Doc/RomWBW System Guide.pdf differ diff --git a/Doc/RomWBW User Guide.pdf b/Doc/RomWBW User Guide.pdf index 5b0512b2..0e74b158 100644 Binary files a/Doc/RomWBW User Guide.pdf and b/Doc/RomWBW User Guide.pdf differ diff --git a/ReadMe.md b/ReadMe.md index 7e341dba..1486cd32 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -3,7 +3,7 @@ **RomWBW ReadMe** \ Version 3.5 \ Wayne Warthen ([wwarthen@gmail.com](mailto:wwarthen@gmail.com)) \ -30 Jun 2024 +03 Jul 2024 # Overview @@ -124,8 +124,6 @@ Documentation for RomWBW includes: Guide](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20System%20Guide.pdf) - [RomWBW Applications](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20Applications.pdf) -- [RomWBW ROM - Applications](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20ROM%20Applications.pdf) - [RomWBW Errata](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20Errata.pdf) diff --git a/ReadMe.txt b/ReadMe.txt index 2d5ea376..e55dd417 100644 --- a/ReadMe.txt +++ b/ReadMe.txt @@ -1,6 +1,6 @@ RomWBW ReadMe Wayne Warthen (wwarthen@gmail.com) -30 Jun 2024 +03 Jul 2024 @@ -122,7 +122,6 @@ Documentation for RomWBW includes: - RomWBW User Guide - RomWBW System Guide - RomWBW Applications -- RomWBW ROM Applications - RomWBW Errata diff --git a/Source/Apps/Test/inttest/Build.cmd b/Source/Apps/Test/inttest/Build.cmd index e26d9b73..0d05f824 100644 --- a/Source/Apps/Test/inttest/Build.cmd +++ b/Source/Apps/Test/inttest/Build.cmd @@ -8,4 +8,5 @@ set TASMTABS=%TOOLS%\tasm32 tasm -t180 -g3 -fFF inttest.asm inttest.com inttest.lst || exit /b copy /Y inttest.com ..\..\..\..\Binary\Apps\Test\ || exit /b +copy /Y inttest.doc ..\..\..\..\Binary\Apps\Test\ || exit /b diff --git a/Source/Apps/Test/inttest/Makefile b/Source/Apps/Test/inttest/Makefile index 04222fbd..25570390 100644 --- a/Source/Apps/Test/inttest/Makefile +++ b/Source/Apps/Test/inttest/Makefile @@ -1,5 +1,7 @@ OBJECTS = inttest.com +DOCS = inttest.doc DEST = ../../../../Binary/Apps/Test +DOCDEST = ../../../../Binary/Apps/Test TOOLS =../../../../Tools USETASM=1 diff --git a/Source/Apps/Test/inttest/inttest.doc b/Source/Apps/Test/inttest/inttest.doc new file mode 100644 index 00000000..686c140a --- /dev/null +++ b/Source/Apps/Test/inttest/inttest.doc @@ -0,0 +1,44 @@ +INTTEST +======= + +RomWBW includes an API allowing applications to "hook" interrupts. +The `INTTEST` utility allows you to test this functionality. + + +** Syntax ** + +`INTTEST` + + +** Usage ** + +`INTTEST` is an interactive application. At startup, it will display +a list of the interrupt vector slots in your system along with the +current vector address for each of them. + +It then prompts you to enter the slot number (in hex) of a vector to +hook. After entering this, the application will watch the hooked +vector and countdown from 0xFF to 0x00 as interrupts are noted. + +When the counter reaches 0x00, the interrupt is unhooked and the +application terminates. The application can also be terminated by +pressing . + + +** Notes ** + +If your system is running without interrupts active, the application +will terminate immediately. + +All slots have vectors even if the corresponding interrupt is not +doing anything. In this case, the vector is pointing to the "bad +interrupt" handler. + +If you hook a vector that is not receiving any interrupts, the +down-counter will not do anything. + + +** Etymology* * + +The `INTTEST` command is an original product and the source code is +provided in the RomWBW distribution. diff --git a/Source/Doc/Applications.md b/Source/Doc/Applications.md index a972b53e..cb4e4370 100644 --- a/Source/Doc/Applications.md +++ b/Source/Doc/Applications.md @@ -1,17 +1,873 @@ -$define{doc_title}{Applications}$ +$define{doc_title}{Applications Guide}$ +$define{doc_author}{MartinR \& Phillip Summers}$ +$define{doc_authmail}{}$ $include{"Book.h"}$ # Summary -RomWBW includes a small suite of custom applications to maximize the -features available. In general, these applications are operating -system agnostic -- they run under any of the included operating +RomWBW is supplied with a suite of software applications that enhance +the use of the system. Some of these applications have been written +entirely from scratch for RomWBW. Others are pre-existing software +that has been customized for the RomWBW environment. This document +serves as a reference for these RomWBW-specific applications. + +The primary usage documentation for RomWBW is the $doc_user$. It is assumed +that the reader is generally familiar with this document. + +RomWBW also includes many generic software applications that have not +been modified for RomWBW (e.g., MSBASIC). These generic applications +are not documented here. Please refer to the application specific +documentation for these generic applications. The documentation for +some of these generic applications is included in the Doc folder of +the RomWBW distribution. + +The applications described in this document fall into two general +categories. + +1. **ROM Applications** are software applications that are loaded + from the the ROM memory of your RomWBW system. + +2. **CP/M Applications** are software applications that are loaded + from disk using a previously loaded CP/M (or CP/M like) operating + system using its command line. + +Note that some applications are available in both forms. For example, +Microsoft BASIC is available as a ROM application and as an application +that runs under CP/M. Only the ROM variant is documented here because +the CP/M variant is not RomWBW-specific. + +You will see that two of the RomWBW operating systems are included +here as ROM Applications. Although operating systems are normally +loaded from disk, RomWBW does include a way to launch CP/M 2.2 and +Z-System directly from ROM. + +Most RomWBW systems include a ROM disk. A running operating system +can load applications from the ROM disk just like a floppy or hard +disk. Applications loaded from the ROM disk by CP/M are considered +to be CP/M applications, **not** ROM applications. + +`\clearpage`{=latex} + +# Boot Menu + +The system start-up process is described in some detail in the RomWBW +User Guide, and for the sake of completeness there is some overlap here. + +When a RomWBW system is started the user is presented with a sign-on +message at the default console detailing the RomWBW version and build +date. The system follows this with the list of hardware that it has +discovered, a list of devices and the system units assigned to them, +before finally inviting the to select a boot device with the prompt: + +``` +Boot [H=Help]: +``` + +At this point, the user may specify a unit, optionally with a slice, +to boot from. Note that it is not possible to boot from from the serial (ASCI) +or memory disk (MD) devices. + +Alternatively the user may select one of the built-in Boot Loader commands. +A menu of which may be displayed by pressing the H or ? keys (for Help). +Furthermore, a ROM application may also be started from this prompt. + +This start-up process is described in some detailed in the RomWBW User Guide, +and there is some overlap here. + +## Help + +After pressing H or ? at the boot prompt the user will be presented with +the following list of available commands: + +``` +L - List ROM Applications +D - Device Inventory +R - Reboot System +I [] - Set Console Interface/Baud code +V [] - View/Set HBIOS Diagnostic Verbosity +[.] - Boot Disk Unit/Slice +``` + +The function performed by each command is described below: + +L: + +: Lists the applications and operating systems that are built into the + RomWBW ROM - e.g., low-level monitor utility, CP/M, or BASIC. + + +D: + +: Displays the list of system devices that was first displayed when the + system was started. + + +R: + +: Will restart the system. Note that this does not reset hardware devices + in the same way that power-on or pressing the reset button would. + + +I: + +: Allows the user to select the interface connected to the console, and + optionally the Baud rate. This could be used to allow the system to be + operated from a second console. + +V: + +: Enables the display of invalid RomWBW HBIOS API calls. This option + is very unlikely to be used by a user and is used for development + purposes. + +And, finally, the system may be booted by specifying the unit number, +and optional slice, separated by a period('.'), of where the disk operating +system software is located - eg 2, 4.1, 5.3 + +Alternatively, a RomWBW ROM application may be started by pressing the appropriate +key from the applications menu, shown in the following section. + +## List ROM Applications + +If the user presses the L key at the Boot Loader prompt then the system will +display the list of ROM applications that are built into RomWBW. If a command +letter is known, then it may be entered directly at the prompt rather than +first displaying the menu. + +The ROM applications available from the boot prompt are: + +``` +M: Monitor +C: CP/M 2.2 +Z: Z-System +B: BASIC +T: Tasty BASIC +F: Forth +P: Play a Game +N: Network Boot +X: XModem Flash Updater +U: User App +``` + +Each of these will now be described in greater detail. + +# ROM Applications + +## Monitor + +The Monitor program is a low-level utility that can be used +for testing and programming. It allows programs to be entered, +memory to be examined and modified, and input/output devices to +be read or written to. + +It's key advantage is that is available at boot up. + +Its key disadvantages are that code cannot be entered in assembly +language and there is no ability to save to persistent storage (disks). + +The available memory area for programming is `0100h-EDFFh`. +The following areas are reserved: + +Memory Area | Function +------------|----------------------------------- +`0000-00FFh`| Jump and restart (RST) vectors +`EE00-FDFFh`| Monitor +`FE00-FFFFh`| HBIOS proxy + +The monitor uses a prompt in the format of `xx>` where xx is the +RomWBW bank id number. For example, the prompt may look like this +and means that Bank Id 0x8E is currently mapped into the low 32K +of processor memory. + +`8E>` + +Please refer to Section 4 of the $doc_sys# for a description of the +RomWBW Bank Id and how it relates to the physical bank of memory being +mapped to the lower 32K of the processor. The method of assigning +banks for specific RomWBW functions is also described. + +Commands can be entered at the command prompt. +Automatic case conversion takes place on command entry and all +numeric arguments are expected to be in hex format. + +The Monitor allows access to all memory locations but ROM and +Flash memory cannot be written to. At startup, the Monitor will +select the default "User" bank. The `S` command is provided to +allow selecting alternate banks. + +There now follows a more detailed guide to using the RomWBW +Monitor program: + +### Command Summary + +**`?`** - Will display a summary of the available commands. + +``` +Monitor Commands (all values in hex): +B - Boot system +D xxxx [yyyy] - Dump memory from xxxx to yyyy +F xxxx yyyy zz - Fill memory from xxxx to yyyy with zz +H - Halt system +I xxxx - Input from port xxxx +K - Keyboard echo +L - Load Intel hex data +M xxxx yyyy zzzz - Move memory block xxxx-yyyy to zzzz +O xxxx yy - Output value yy to port xxxx +P xxxx - Program RAM at address xxxx +R xxxx [[yy] [zzzz]] - Run code at address xxxx + Pass yy and zzzz to register A and BC +S xx - Set bank to xx +U - Set bank to previous bank +T xxxx - X-modem transfer to memory location xxxx +X - Exit monitor +``` + +### Cold Boot + +**`B`** - Performs a cold boot of the RomWBW system. A complete +re-initialization of the system is performed and the system +returns to the Boot Loader prompt. + +### Dump Memory + +**`D xxxx [yyyy]`** - Dump memory from hex location xxxx to yyyy +on the screen as lines of 16 hexadecimal bytes with their +ASCII equivalents (if within a set range, else a '.' is +printed). If the end address is omitted then 256 bytes are +displayed. + +A good tool to see where code is located, check +for version id, obtain details for chip configurations and +execution paths. + +Example: `D 100 1FF` + +``` +0100: 10 0B 01 5A 33 45 4E 56 01 00 00 2A 06 00 F9 11 ...Z3ENV...*..ù. +0110: DE 38 37 ED 52 4D 44 0B 6B 62 13 36 00 ED B0 21 Þ87íRMD.kb.6.í°! +0120: 7D 32 E5 21 80 00 4E 23 06 00 09 36 00 21 81 00 }2å!..N#...6.!.. +0130: E5 CD 6C 1F C1 C1 E5 2A C9 8C E5 CD 45 05 E5 CD åÍl.ÁÁå*É.åÍE.åÍ +0140: 59 1F C3 00 00 C3 AE 01 C3 51 04 C3 4C 02 C3 57 Y.Ã..î.ÃQ.ÃL.ÃW +0150: 02 C3 64 02 C3 75 02 C3 88 02 C3 B2 03 C3 0D 04 .Ãd.Ãu.Ã..ò.Ã.. +0160: C3 19 04 C3 22 04 C3 2A 04 C3 35 04 C3 40 04 C3 Ã..Ã".Ã*.Ã5.Ã@.à +0170: 48 04 C3 50 04 C3 50 04 C3 50 04 C3 8F 02 C3 93 H.ÃP.ÃP.ÃP.Ã..Ã. +0180: 02 C3 94 02 C3 95 02 C3 85 04 C3 C7 04 C3 D1 01 .Ã..Ã..Ã..ÃÇ.ÃÑ. +0190: C3 48 02 C3 E7 04 C3 56 03 C3 D0 01 C3 D0 01 C3 ÃH.Ãç.ÃV.ÃÐ.ÃÐ.à +01A0: D0 01 C3 D0 01 C3 D0 01 C3 D0 01 01 02 01 CD 6B Ð.ÃÐ.ÃÐ.ÃÐ....Ík +01B0: 04 54 68 69 73 20 66 75 6E 63 74 69 6F 6E 20 6E .This function n +01C0: 6F 74 20 73 75 70 70 6F 72 74 65 64 2E 0D 0A 00 ot supported.... +01D0: C9 3E FF 32 3C 00 3A 5D 00 FE 20 28 14 D6 30 32 É>ÿ2<.:].þ (.Ö02 +01E0: AB 01 32 AD 01 3A 5E 00 FE 20 28 05 D6 30 32 AC «.2­.:^.þ (.Ö02¬ +01F0: 01 C5 01 F0 F8 CF E5 26 00 0E 0A CD 39 02 7D 3C .Å.ðøÏå&...Í9.}< +``` + +### Fill Memory + +**`F xxxx yyyy zz`** - Fill memory from hex xxxx to yyyy with +a single value of zz over the full range. The Dump command +can be used to confirm that the fill completed as expected. A +good way to zero out memory areas before writing machine data +for debug purposes. + +### Halt System + +**`H`** - Halt system. A Z80 HALT instruction is executed. The +system remains in the halt state until the system is +physically rebooted. Interrupts will not restart the +system. On systems that support a HALT status LED, the +LED will be illuminated. + +### Input from Port + +**`I xxxx`** - Input data from port xxxx and display to the screen. +This command is used to read values from hardware I/O ports +and display the contents in hexadecimal. + +### Keyboard Echo + +**`K`** - Echo any key-presses from the terminal. Press 'ESC' key +to quit. This facility provides that any key stroke sent to +the computer will be echoed back to the terminal. File down +loads will be echoed as well while this facility is ‘on’. + +### Load Hex + +**`L`** - Load a Intel Hex data via the terminal program. +The load address is defined in the hex file of the +assembled code. + +The terminal emulator program should be configured to +give a delay at the end of each line to allow the monitor +enough time to parse the line and move the data to memory. + +Keep in mind that this will be transient unless the +system supports battery backed memory. Saving to memory drive +is not supported. + +### Move Memory + +**`M xxxx yyyy zzzz`** - Move hex memory block xxxx to yyyy to +memory starting at hex location zzzz. Care should be taken +to insure that there is enough memory at the destination so +that code does not get over-written or memory wrapped around. + +### Output to Port + +**`O xxxx yy`** - Output data byte xx to port xxxx. This command is +used to send hexadecimal values to hardware I/O ports to +verify their operation and is the companion to the I operation. +Use clip leaded LEDs to confirm the data written. + +### Program Memory + +**`P xxxx`** - Program memory location xxxx. This routine will +allow you to program a hexadecimal value 'into memory starting +at location xxxx. Press 'Enter' on a blank line to +return to the Monitor prompt. + +The limitation around programming memory is that it must be +entered in hexadecimal. An alternative is to use the L command +to load a program that has been assembled to a hex file on the +remote computer. + +An excellent online resource for looking up opcodes for entry +can be found here: . + +### Run Program + +**`R xxxx [[yy] [zzzz]]`** - Run program at location xxxx. If optional +arguments yy and zzzz are entered they are loaded into the +A and BC register respectively. The return address of the +Monitor is saved on the stack so the program can return +to the monitor. On return to the monitor, the contents of +the A, HL, DE and BC registers are displayed. + +### Set Bank + +**`S xx`** - Set the physical memory bank to the RomWBW Bank Id +indicated by xx. Memory addresses +0x0000-0x7FFF (i.e. bottom 32k) are affected. Because the +interrupt vectors are stored in the bottom page of this +range, this function is disabled when interrupt mode 1 is +being used (IM1). Interrupt mode 2 is not affected as the +associated jump vectors are stored in high memory. + +Changing the bank also impacts the restart vectors (RST), +so executing code that calls the HBIOS using the `RST 08` +assembly code will not work. + +The monitor stack resides in high memory and is not affected +but any code that changes the stack to low memory will be +affected. + +The U command may be used to undo the change and return the +selected memory bank back to the previously selected one. + +Section 4 of the $doc_sys$ provides detail on how Bank Ids map to the +physical memory of the system and also how specific banks are utilized +by RomWBW. + +### Undo Bank + +**`U`** - Change the bank in memory back to the previously selected bank. +This command should be used in conjunction with the S command. + +### X-Modem Transfer + +**`T xxxx`** - Receive an X-modem file transfer and load it into +memory starting at location xxxx. + +128 byte blocks and checksum mode is the only supported +protocol. + +### Exit Monitor + +**`X`** - Exit the monitor program back to the main boot menu. + +## CP/M 2.2 + +This option will boot the CP/M 2.2 disk operating system +from an image contained within the ROM. Please refer to the +CPM User Manual in the Doc/CPM folder of the distribution for +CP/M usage. There are also many online resources. + +During the build process the system will create a ROM disk +containing a number of curated CP/M applications, and also a +RAM drive. The capacity of each will depend upon the size +of the ROM and RAM available to the system. A more complete +set of utilities are provided within the disk image files +provided as part of RomWBW. + +A number of the applications provided are generic to +CP/M, while others rely on particular hardware or +aspects of RomWBW itself. + +Those that are written specific to RomWBW include: ASSIGN, +CPUSPD, FDU, FORMAT, FLASH, FDISK80, MODE, RTC, SYSCOPY, +TALK, TIMER, and XM. + +The CP/M utilities supplied with RomWBW warrant more detailed descriptions, +and so are described in some detail in their own section +of this user guide. In summary they provide the initial capability +to manage and update your RomWBW system, to create other +bootable media (hardware dependent) and to write/debug +code using assembler and BASIC. + +## Z-System + +Z-System is a complete alternative, but entirely compatible, disk +operating system to CP/M. + +Z-System is comprised of ZSDOS 1.1 which is a +replacement for CP/M's Basic Disk Operating System (BDOS), and ZCPR which +is a replacement for the Console Command Processor (CCP). Either or both +may be used, although using both together will allow ZCPR to make use of +specific ZSDOS features. + +Documentation for Z-System may be found in the Doc/CPM folder of the +RomWBW distribution and the reader is referred to those. + +## BASIC + +For those who are not familiar with BASIC, it stands for Beginners All Purpose Symbolic +Instruction Code. + +RomWBW contains two versions of ROM BASIC, a full implementation and a "tiny" BASIC. + +The full implementation is a version of Microsoft BASIC from the NASCOM Computer. + +A comprehensive instruction manual is available in the Doc/Contrib directory. + +### RomWBW specific features + +- Sound +- Graphics +- Terminal Support + +### RomWBW unsupported features + +- Cassette loading +- Cassette saving + +## TastyBASIC + +TastyBASIC offers a minimal implementation of BASIC that is only 2304 +bytes in size. It originates from Li-Chen Wang's Palo Alto Tiny BASIC +from around 1976. It's small size is suited the tiny memory capacities of +the time. This implementation is by Dimitri Theulings and his original +source can be found at . + +### Features / Limitations + +- Integer arithmetic, numbers -32767 to 32767 +- Singles letter variables A-Z +- 1-dimensional array support +- Strings are not supported + +### Direct Commands + +- `LIST`,`RUN`, `NEW`, `CLEAR`, `BYE` + +### Statements + +- `LET`, `IF`, `GOTO`, `GOSUB RETURN`, `REM`, `FOR TO NEXT STEP`, `INPUT`, `PRINT`, `POKE`, `END` + +### Functions + +- `PEEK`, `RND`, `ABS`, `USR`, `SIZE` + +### Operators + +- `>=`, `#`, `>`, `=`, `<=`, `<` + +- Operator precedence is supported. + +Type ***BYE*** to return to the boot menu. + +## FORTH + +CamelForth is the version of Forth included as part of the boot ROM in +RomWBW. It has been converted from the Z80 CP/M version published at +. The +author is Brad Rodriguez who is a prolific Forth enthusiast, whose work +can be found here: . + +For those are who are not familiar with Forth, I recommend the +wikipedia article +and the Forth Interest Group website . + +### Important things to know + +Forth is case sensitive. + +To exit back to the boot loader type ***bye*** + +To get a list of available words type ***WORDS*** + +To reset Forth to its initial state type ***COLD*** + +Most of the code you find on the internet will not run unless modified or additional Forth +words are added to the dictionary. + +This implementation does not support loading or saving of programs. All programs +need to be typed in. Additionally, screen editing and code blocks are not supported. + +### Structure of Forth source files + +File | Description +--------------|----------------------------- +camel80.azm | Code Primitives + camel80d.azm | CPU Dependencies + camel80h.azm | High Level words + camel80r.azm | RomWBW additions +glosshi.txt | Glossary of high level words +glosslo.txt | Glossary of low level words +glossr.txt | Glossary of RomWBW additions + +### RomWBW Additions + +Extensions and changes to this implementation compared to the original distribution are: + +- The source code has been converted from Z80mr assembler to Hector Peraza's zsm. + +- An additional file camel80r.azm has been added for including additional words to + the dictionary at build time. However, as currently configured there is very little space + allocated for addition words. Exceeding the allocated ROM space will generate an error + message when building. + +- James Bowman's double precision words have been added from his RC2014 version: + . + +Word | Syntax | Description +--------|----------------------------|--------------------------------- +D+ | d1 d2 -- d1+d2 | Add double numbers +2>R | d -- | 2 to R +2R> | d -- | fetch 2 from R +M*/ | d1 n2 u3 -- d=(d1*n2)/u3 | double precision mult. div +SVC | hl de bc n -- hl de bc af | Execute a RomWBW function +P! | n p -- | Write a byte to a I/O port +P@ | p -- n | Read a byte from and I/O port + +## Play a Game + +### 2048 + +2048 is a puzzle game that can be both mindless and challenging. It +appears deceptively simple but failure can creep up on you suddenly. + +It requires an ANSI/VT-100 compatible colour terminal to play. + +2048 is like a sliding puzzle game except the puzzle tiles are +numbers instead of pictures. Instead of moving a single tile all +tiles are moved simultaneously in the same direction. Where two +tiles of the same number collide, they are reduced to one tile with +the combined value. After every move a new tile is added with +a starting value of 2. + +The goal is to create a tile of 2048 before all tile locations are +occupied. Reaching the highest points score, which is the sum of all +the tiles is a secondary goal. The game will automatically end when +there are no more possible moves. + +Play consists of entering a direction to move. Directions can be entered +using any of three different keyboard direction sets. + +``` +Direction | Keys +----------|---------- +Up | w ^E 8 +Down | s ^X 2 +Left | a ^S 4 +Right | d ^D 6 +``` + +The puzzle board is a 4x4 grid. At start, the grid will be populated +with two 2 tiles. An example game sequence is shown below with new +tiles to the game shown in brackets. + +``` +Start Move 1 - Up Move 2 - Left Move 3 - Left ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +| | | |(2)| | | | | 4 | | 4 | | | | | 4 | | | | ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +| | | | | | | | | | | | | |(4)| | 4 | | | | ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +| | | |(2)| | | | | | | | | | | | | | | | ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +| | | | | | | |(2)| | | 2 | | | | | 2 | |(2)| | ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ + +Move 4 - Left Move 5 - Up Move 6 - Right Move 7 - Up ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +| 4 | | | | | 8 | | | 4 | | | | 8 | 4 | | | | 8 | 8 | ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +| 4 | | |(4)| | 4 | | | | | | | | 4 | | | | | 2 | ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +| | | | | | | | | | | | | | | | | | | | ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +| 4 | | | | |(2)| | | | |(2)| | | 2 | |(2)| | | | ++---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +``` + +This is how I lost this game: + +``` ++---+---+---+---+ +| 4 | 2 | 16| 4 | ++---+---+---+---+ +| 32| 64| 8 | 2 | ++---+---+---+---+ +| 4 | 8 |128| 32| ++---+---+---+---+ +|(2)| 16| 8 | 4 | ++---+---+---+---+ +``` + +Press Q at any time to bring up the option to Quit or Restart the game. + +## Network Boot + +If your RomWBW system is equipped with an RCBus MT011 module, it is +possible to boot into CP/M 2.2 directly from a CP/NET network server. +This means that the operating system will be loaded directly from the +network server and all of your drive letters will be provided by the +network server. + +This function requires substantial knowledge of CP/NET and it's +implementation within RomWBW. Section 10 of the $doc_user$ provides +complete instructions for setting up a CP/NET based network under RomWBW +including a section on network booting. + +## Xmodem Flash Updater + +The RomWBW Xmodem flash updater provides the capability to update RomWBW from the boot loader using an x-modem file transfer. It offers similar capabilities to Will Sowerbutts FLASH4 utility except that the flashing process occurs during the file transfer. + +These are the key differences between the two methods are: + +Xmodem Flash Updater | FLASH.COM (aka FLASH4) +--------------------------------|----------------- +Available from the boot loader | Well proven and tested +Xmodem transfer is integrated | Wider range of supported chips and hardware +Integrated checksum utilities | Wider range of supported platforms +Capability to copy a ROM image | Only reprograms sectors that have changed +More convenient one step process | Ability save and verify ROM images +No intermediate storage required | Progress display while flashing +. | Displays chip identification information +. | Faster file transfer + +The major disadvantages of the Updater is that it is new and relatively untested. There is the risk that a failed transfer will result in a partially flashed and unbootable ROM. There are some limitations on serial transfer speeds. + +The updater utility was initially intended to support the Retrobrew SBC-V2-005 platform using Atmel 39SF040 flash chips but has now been extended to be more generic in operation. + +Supported flash chips are +39SF040, 29F040, AT49F040, AT29C040, M29F040 , MX29F040, A29010B, A29040B + +The Atmel 39SF040 chip is recommended as it can erase and write 4Kb sectors. Other chips require the whole chip to be erased. + +### Usage + +In most cases, completing a ROM update is a simple as: + +1. Booting to the boot loader prompt +2. Selecting option X - Xmodem Flash Updater +3. Selecting option U - Update +4. Initiating an X-modem transfer of your ROM image on your console device +5. Selecting option R - Reboot + +If your console device is not able to transfer a ROM image i.e. your console is a VDU then you will have to use the console options to identify which character-input/output device is to be used as the serial device for transfer. + +When your console is the serial device used for the transfer, no progress information is displayed as this would disrupt the x-modem file transfer. If you use an alternate character-input/output devices as the serial device for the transfer then progress information will be displayed on the console device. + +Due to different platform processor speeds, serials speeds and flow control capabilities the default console or serial device speed may need to be reduced for a successful transfer and flash to occur. The **Set Console Interface/Baud code** option at the Boot Loader can be used to change the speed if required. Additionally, the Updater has options to set to and revert from a recommended speed. + +See the RomWBW Applications guide for additional information on performing upgrades. + +### Console Options +Option ( C ) - Set Console Device + +Option ( S ) - Set Serial Device + +By default the updater assumes that the current console is a serial device and that the ROM file to be flashed will also be transferred across this device, so the Console and Serial device are both the same. + +Either device can be can be change to another character-input/output device but the updater will always expect to receive the x-modem transfer on the **Serial Device** + +The advantage of transferring on a different device to the console is that progress information can be displayed during the transfer. + +Option ( > ) - Set Recommended Baud Rate + +Option ( < ) - Revert to Original Baud Rate + +### Programming options + +Option ( U ) - Begin Update + +The will begin the update process. The updater will expect to start receiving +an x-modem file on the serial device unit. + +X-modem sends the file in packets of 128 bytes. The updater will cache 32 +packets which is 1 flash sector and then write that sector to the +flash device. + +If using separate console, bank and sector progress information will shown + +``` +BANK 00 s00 s01 s02 s03 s04 s05 s06 s06 s07 +BANK 01 s00 s01 s02 s03 s04 s05 s06 s06 s07 +BANK 02 s00 s01 s02 s03 s04 s05 s06 s06 s07 etc +``` + +The x-modem file transfer protocol does not provide any filename or size +information for the transfer so the updater does not perform any checks +on the file suitability. + +The updater expects the file size to be a multiple of 4 kilobytes and +will write all data received to the flash device. A system update +file (128kb .img) or complete ROM can be received and written (512kb or +1024kb .rom) + +If the update fails it is recommended that you retry before rebooting or +exiting to the Boot loader as your machine may not be bootable. + +Option ( D ) - Duplicate flash #1 to flash #2 + +This option will make a copy of flash #1 onto flash #2. The purpose of this is to enable + making a backup copy of the current flash. Intended for systems using 2x512Kb Flash devices. + +Option ( V ) - Toggle Write Verify + +By default each flash sector will be verified after being written. Slight +performance improvements can be gained if turned off and could be used if +you are experiencing reliable transfers and flashing. + +### Exit options + +Option ( R ) - Reboot + +Execute a cold reboot. This should be done after a successful update. If +you perform a cold reboot after a failed update then it is likely that +your system will be unusable and removing and reprogramming the flash +will be required. + +Option ( Q ) - Quit to boot loader. + +The SBC Boot Loader is reloaded from ROM and +executed. After a successful update a Reboot should be performed. However, +in the case of a failed update this option could be used to attempt to +load CP/M and perform the normal x-modem / flash process to recover. + +### CRC Utility options + +Option ( 1 ) and ( 2 ) - Calculate and display CRC32 of 1st or 2nd 512k ROM. +Option ( 3 ) - Calculate and display CRC32 of a 1024k (2x512Kb) ROM. + +Can be used to verify if a ROM image has been transferred and flashed correctly. Refer to the Tera Term section below for details on configuring the automatic display of a files CRC after it has been transferred. + +In Windows, right clicking on a file should also give you a context menu option CRC SHA which will allow you to select a CRC32 calculation to be done on the selected file. + +### Tera Term macro configuration + +Macros are a useful tool for automatic common tasks. There are a number of instances where using macros to facilitate the update process could be worthwhile if you are: + +* Following the RomWBW development builds. +* Doing lots of configuration changes. +* Doing development on RomWBW drivers + +Macros can be used to automate sending ROM updates or images and for my own purposed I have set up a separate macro for transferring each of the standard build ROM, my own custom configuration ROM and update ROM. + +An example macro file to send an *.upd file, using checksum mode and display the crc32 value of the transmitted file: + +``` +Xmodem send, checksum, display crc32 +xmodemsend '\\desktop\users\phillip\documents\github\romwbw\binary\sbc_std_cust.upd' 1 +crc32file crc '\\desktop\users\phillip\documents\github\romwbw\binary\sbc_std_cust.rom' +sprintf '0x%08x' crc +messagebox inputstr 'crc32' +``` + +### Serial speed guidelines + +As identified in the introduction, there are limitations on serial speed depending on processor speed and flow control settings. Listed below are some of the results identified during testing. + +Configuration | Processor Speed | Maximum Serial Speed +-----------------------|-----------------|--------------------- +UART no flow control | 2MHz | 9600 +UART no flow control | 4MHz | 19200 +UART no flow control | 5MHz | 19200 +UART no flow control | 8MHz | 38400 +UART no flow control | 10MHz | 38400 +USB-fifo 2MHz+ | | n/a +ASCI no flow control | 18.432MHz | 9600 +ASCI with flow control | 18.432MHz | 38400 + +The **Set Recommend Baud Rate** option in the Updater menu follows the following guidelines. + +Processor Speed | Baud Rate +----------------|---------- +1MHz | 4800 +2-3MHz | 9600 +4-7MHz | 19200 +8-20MHz | 38400 + +These can be customized in the updater.asm source code in the CLKTBL table if desired. +Feedback to the RomWBW developers on these guidelines would be appreciated. + +### Notes + +All testing was done with Tera Term x-modem, Forcing checksum mode using macros was found to give the most reliable transfer. +Partial writes can be completed with 39SF040 chips. Other chips require entire flash to be erased before being written. +An SBC V2-005 MegaFlash or Z80 MBC required for 1mb flash support. The Updater assumes both chips are same type +Failure handling has not been tested. +Timing broadly calibrated on a Z80 SBC-v2 +Unabios not supported + +## User Application + +RomWBW provides the facility for a user to build, include and execute their +own custom application directly from the applications menu at boot-up. All that's +needed is for the user to create their custom code ready for inclusion, +recognising that there are certain constraints in doing this. + +In order to build properly, the build process requires that the file +`usrrom.asm` be found in the /Source/HBIOS folder of the RomWBW tree. + +This source file needs to assemble using TASM and it must start at +(ORG) address 00100H as the RomWBW HBIOS reserves locations 00000H +to 000FFH for internal use. Further, the user application must assemble to +a maximum of `USR-SIZ` bytes. + +During execution, the user application may make use of HBIOS calls as necessary, +and at exit it should return to the RomWBW boot loader +using the HBIOS warm reset. Note that no disk operating system (eg CP/M) +functions will be available as no disk operating system will have been loaded. + +There is a sample `usrrom.asm` supplied in Source/HBIOS and it is recommended +that, at least initially, users create their own application based on this as +a template because it already creates the necessary variables, starts at +(ORG) 00100H, and ensures that the assembled file is padded to create a +file `USR-SIZ` in length. Equally, should the the user's application prove +too large for the space available then assembly will be terminated with an error. +Users should not remove this check from the templated code. + +If required, the user application may make use of the Z80 interrupt system +but if the user application wishes to rely on HBIOS functionality then it +must adhere to the HBIOS framework for managing interupts. Alternatively, +if the user appliction has no need for the HBIOS then it may use its own +custom code for handling interrupts. In that case, a hard reset, rather +than an HBIOS warm start, would be necessary to return control to RomWBW. + +`\clearpage`{=latex} + +# CP/M Applications - ROM-Based & Disk-Based + +There now follows a more detailed guide to using the small suite of custom +applications included with RomWBW. In general, these applications are +operating system agnostic -- they run under any of the included operating systems. However, they all require RomWBW -- they are not generic CP/M applications. Most of the applications are custom written for RomWBW. However, some are standard CP/M applications that have been adapted to run under -RomWBW (e.g., XModem). The applications are generally matched to the +RomWBW (e.g. XM/XModem). The applications are generally matched to the version of RomWBW they are distributed with. So, if you upgrade the version of RomWBW in your system ROM, you will want to copy the corresponding applications to any storage devices you are using. @@ -27,37 +883,81 @@ data on your disk media, so don't do this if you are saving any data on the media. Most of the applications are included as source code in the RomWBW -distribution and are built in the normal build process. The source -code is found in the Source\\Apps directory of the distribution. The -binary executable applications are found in the Binary\\Apps directory. - -The following table clarifies where each of the applications can be -found: - -| Application | ROM Disk | Boot Disks | Apps Dir | -| ----------- | -------- | ---------- | -------- | -| ASSIGN | Yes | Yes | Yes | -| SYSCOPY | Yes | Yes | Yes | -| MODE | Yes | Yes | Yes | -| FDU | Yes | Yes | Yes | -| FORMAT | Yes | Yes | Yes | -| XM | Yes | Yes | Yes | -| FLASH | Yes | Yes | Yes | -| FDISK80 | Yes | Yes | Yes | -| TALK | Yes | Yes | Yes | -| RTC | Yes | Yes | Yes | -| TIMER | Yes | Yes | Yes | -| CPUSPD | Yes | Yes | Yes | -| FAT | Yes | Yes | Yes | -| CLRDIR | Yes | Yes | Yes | -| INTTEST | No | Yes | Yes | -| TUNE | No | Yes | Yes | -| WDATE | No | Yes | Yes | -| HTALK | No | Yes | Yes | +distribution and are built during the normal build process. The source +code is found in the Source/Apps directory of the distribution. The +binary executable applications are found in the Binary/Apps directory. + +The table below clarifies where each of the applications may be +found. It is not an exhaustive list, with further applications existing +on both the ROM-based and disk-based versions of CP/M. All of the Applications +incuded within RomWBW may be found with in the Binary/Apps directory. + +| Application | ROM Disk | Boot Disks | +| ----------- | :------: | :--------: | +| ASSIGN | Yes | Yes | +| CLRDIR | Yes | Yes | +| CPUSPD | Yes | Yes | +| FAT | No | Yes | +| FDISK80 | Yes | Yes | +| FDU | Yes | Yes | +| FLASH | Yes | Yes | +| FORMAT | Yes | Yes | +| HTALK | Yes | Yes | +| MODE | Yes | Yes | +| RTC | Yes | Yes | +| SURVEY | Yes | Yes | +| SYSCOPY | Yes | Yes | +| TALK | Yes | Yes | +| TIMER | Yes | Yes | +| TUNE | No | Yes | +| VGMPLAY | No | Yes | +| WDATE | No | Yes | +| XM | Yes | Yes | + +All of the CP/M applications may be found in the RomWBW Binary/Apps directory +and a user may copy those they need to their own customised disk/slice. + +Independantly of whether the CP/M system was started from ROM or a boot disk, +such as a floppy disk or a slice on a CF or uSD memory card, applications +may be located on and executed from either the ROM-disk itself or from other media. +There are multiple disk images available for CP/M (eg floppy, legacy hard-disk and new +hard-disk formats) and they all contain essentially the same set of applications. + +There are particular advantages for each method of booting into CP/M. + +ROM-based CP/M: + +- A clean and reliable copy of CP/M with no possibility of corruption +- No additional hardware required +- Fast to boot +- Rolled forward with new releases of RomWBW + +Disk-based CP/M: + +- Greater capacity allows for a larger number of applications +- Allows for user-customisation of applications available +- Allows individual disks to be tailored to a particular purpose, eg word processor + +For systems starting CP/M from a disk created from an image file, there are a small number +of additional applications stored in the ```USER 2``` area of the disk. These applications +do not form part of CP/M, but rather are small utilities used for test purposes during develpment work. +They may, or may not, fuction correctly with any given hardware or software configuration. +Documentation for these untilities is very limited, though the source files maybe found +in the /Source folder. Note that these utiltites are not available when starting CP/M +from the ROM image or from a floppy disk. + +A number of the CP/M applications available are described in more detail in +the following sections, each with an indication as to whether that application +may be found on the ROM-disk, a boot-disk, or both. `\clearpage`{=latex} -# ASSIGN +## ASSIGN + +| ASSIGN | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| RomWBW includes a flexible mechanism for associating the operating system drive letters (A: - P:) to the physical devices in the system. @@ -65,7 +965,7 @@ Drive letter assignments can be changed on a running operating system without rebooting. The ASSIGN command facilitates this by allowing you to display, assign, reassign, or remove the drive letter assignments. -## Syntax +#### Syntax | `ASSIGN /?` | `ASSIGN /L` @@ -73,7 +973,7 @@ to display, assign, reassign, or remove the drive letter assignments. | `ASSIGN `*``*`=[`*``*`:[`*``*`]],...` | `ASSIGN `*``*`=`*``*`,...` -## Usage +#### Usage `ASSIGN /?` will display brief command usage and version information. @@ -110,7 +1010,7 @@ When the command runs it will echo the resultant assignments to the console to confirm its actions. It will also display the remaining space available in disk buffers. -## Notes +#### Notes If the `ASSIGN` command encounters any rule violations or errors, it will abort with an error and **none** of the drive assignments will be @@ -183,314 +1083,374 @@ vs. CP/M 3. If you utilize an RSX that modifies the BDOS version returned, you are likely to have serious problems. In this case, be sure to use `ASSIGN` prior to loading the RSX or after it is unloaded. -## Etymology +#### Etymology The `ASSIGN` command is an original product and the source code is provided in the RomWBW distribution. `\clearpage`{=latex} -# SYSCOPY +## CLRDIR -To make disk media bootable, you must write a system boot image onto -the system tracks of the of the media. The `SYSCOPY` allows you to -read or write the system boot image of disk media. +| CLRDIR | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -## Syntax +The `CLRDIR` command is used to initialise the directory area of a drive. -| `SYSCOPY `*``*`=`*``* +#### Syntax -*``* is the drive to receive the operating system image or -alternatively a filename to save the operating system image +| `CLRDIR `*``* -*``* is the drive containing an operating system image or -alternatively a filename containing the system image to be placed on -the destination +#### Usage -## Usage +`CLRDIR `*``* will initialise the directory area of the specified drive. The +drive may take any form - eg floppy disk, hard-disk, CF, uSD etc. -Both *``* and *``* can refer to either a drive letter or a -file. If a drive letter is specified, the system boot image will be -read or written to the system tracks of the drive. If a filename is -specified, the system boot image will be read or written to the -specified filename. +The use of FDISK80 to reserve space, or slices, for CP/M use as drives will not +initialise the directory areas of those slices. The resultant directory areas will +contain garbage left over from a previous use of the disk (or media) and using +them in this state with CP/M will very likely lead to failed or corrupted data +storage. Use `CLRDIR` to initialise the directory properly. -`SYSCOPY C:=ZSYS.SYS` will read a system boot image from the file -ZSYS.SYS and write it onto the system tracks of drive C:. +FDU will initialise the directory of a floppy disk as part of the formatting process +and so `CLRDIR` is unnecessary for a floppy disk. `CLRDIR` is, therefore, primarily used +with other types such as hard-disk, CF and uSD. -`SYSCOPY A:OS.SYS=C:` will capture the system boot image from the -system tracks of drive C: and store it in the file A:OS.SYS. +The `CLRDIR` command may also be used to effectively 'reformat' a used disk +by reinitialising its directory area and effectively making it blank again. -`SYSCOPY D:=C:` will copy the system tracks from drive C: onto the -system tracks of drive D:. +Use `CLRDIR` with caution as changes made to disks by `CLRDIR` cannot be undone. -## Notes +#### Notes -The RomWBW ROM disk contains files with the system boot image for -Z-System and CP/M 2.2. These files are called CPM.SYS and ZSYS.SYS -respectively. These files can be used as the source of a `SYSCOPY` -command to make a disk bootable with the corresponding operating -system. +If `CLRDIR` is used on disk containing data then the directory area will be +reinitialised and the data previously stored will be lost. -CP/M 3 uses a two phase boot process. To make a CP/M 3 drive bootable, -you need to put "CPMLDR.SYS" on the boot tracks of the disk and be -sure that the drive also contains the "CPM.SYS" file. The "CPMLDR.SYS" -file is not included on the ROM disk, but is found on the CP/M 3 disk -image. +`\clearpage`{=latex} -ZPM3 is similar to CP/M 3. You also put "CPMLDR.SYS" on the system -tracks of the drive to make it bootable. The ZPM3 operating system is -in the file called "CPM3.SYS" on the ZPM3 disk image. It may seem -confusing that ZPM3 is in the file called CPM3.SYS, but it is normal -for ZPM3. +## CPUSPD -For the purposes of booting an operating system, each disk slice is -considered its own operating system. Each slice can be made bootable -with its own system tracks. +| CPUSPD | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -`SYSCOPY` uses drive letters to specify where to read/write the system -boot images. However, at startup, the boot loaded will require you to -enter the actual disk device and slice to boot from. So, you need to -be careful to pay attention to the device and slice that is assigned -to a drive letter so you will know what to enter at the boot loader -prompt. By way of explanation, the boot loader does not know about -drive letters because the operating system is not loaded yet. +The `CPUSPD` application is used to change the running speed and wait +states of a RomWBW system. -If you want to put a boot system image on a device and slice that is -not currently assigned to a drive letter, you will need to assign a -drive letter first. +The functionality is highly dependent on the capabilities of your system. -Not all disk formats include space for system tracks. Such disk -formats cannot contains a system boot image and, therefore, cannot be -made bootable. The best example of such disk formats are the ROM and -RAM disks. To maximize usable file space on these drives, they do not -have system tracks. Obviously, ROM operating system is supported by -choosing a ROM operating system at the boot loader prompt. Any attempt -to write a system boot image to disk media with no system tracks will -cause SYSCOPY to fail with an error message. +At present, all Z180 systems can change their CPU speed and their +wait states. SBC and MBC systems may be able to change their CPU +speed if the hardware supports it and it is enabled in the HBIOS +configuration. -The system boot images are paired with the ROM version in your system. -So, you must take care to update the system tracks of any bootable -disk when you upgrade your ROM firmware. +#### Syntax -The system boot images are **not** tied to specific hardware -configurations. System boot images and operating systems provided with -RomWBW will work with any supported RomWBW platform or hardware as -long as they are the same version as the RomWBW firmware. +| `CPUSPD [`*``*`[,[`*``*`][,[`*``*`]]]` -## Etymology +*``* is one of HALF, FULL, or DOUBLE. +*``* is a number specifying the desired memory wait states. +*``* is a number specifying the desired I/O wait states. -The `SYSCOPY` command is an original product and the source code is -provided in the RomWBW distribution. +#### Usage -`\clearpage`{=latex} +Entering `CPUSPD` with no parameters will display the current CPU speed +and wait state information of the running system. Wait state +information is not available for all systems. -# MODE +To modify the running speed of a system, you can specify the +`*``*` parameter. To modify either or both of the wait +states, you can enter the desired number. Either or both of the wait +state parameters may be omitted and the current wait state settings +will remain in effect. -The MODE command allows you to adjust the operating characteristics -such as baud rate, data bits, stop bits, and parity bits of serial -ports dynamically. +#### Notes -## Syntax +The ability to modify the running speed and wait states of a system +varies widely depending on the hardware capabilities and the HBIOS +configuration settings. -`MODE /?` -`MODE COM`*``*`: [`*``*`[,`*``*`[,`*``*`[,`*``*`]]]] [/P]` +Note that it is frequently impossible to tell if a system is capable +of dynamic speed changes. This function makes the changes blindly. +If an attempt is made to change the speed of a system +that is definitely incapable of doing so, then an error result is +returned. -`/?` displays command usage and version information +The `CPUSPD` command makes no attempt to ensure that the new CPU +speed will actually work on the current hardware. Setting a CPU +speed that exceeds the capabilities of the system will result in +unstable operation or a system stall. -*``* is the character device unit number +Some peripherals are dependent on the CPU speed. For example, the Z180 +ASCI baud rate and system timer are derived from the CPU speed. The +CPUSPD application will attempt to adjust these peripherals for +correct operation after modifying the CPU speed. However, in some +cases this may not be possible. The baud rate of ASCI ports have a +limited set of divisors. If there is no satisfactory divisor to +retain the existing baud rate under the new CPU speed, then the baud +rate of the ASCI port(s) will be affected. -*``* is numerical baudrate +#### Etymology -*``* is (N)one, (O)dd, (E)ven, (M)ark, or (S)pace +The `CPUSPD` application was custom written for RomWBW. All of the +hardware interface code is specific to RomWBW and the application will +not operate correctly on non-RomWBW systems. -*``* is number of data bits, typically 7 or 8 +The source code is provided in the RomWBW distribution. -*``* is number of stop bits, typically 1 or 2 +`\clearpage`{=latex} -`/P` prompts user prior to setting new configuration +## FAT -## Usage +| FAT | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -`MODE /?` will display basic command usage and version information. +The operating systems included with RomWBW do not have any native +ability to access MS-DOS FAT filesystems. The FAT application can be +used overcome this. It will allow you to transfer files between CP/M +and FAT filesystems (wildcards supported). It can also erase files, +format, and list directories of FAT filesystems. -`MODE` with no parameters will list all devices and their current -configuration. +#### Syntax -`MODE <`*n*`>` will display the current configuration of the specified -character device unit. +| `FAT DIR `*``* +| `FAT COPY `*` `* +| `FAT REN `*` `* +| `FAT DEL `*`[|]`* +| `FAT MD `*``* +| `FAT FORMAT `*``* -`MODE COM`*``*`: [`*``*`[,`*``*`[,`*``*`[,` -*``*`]]]] [/P]` requests that the specified configuration -be set on the character device unit. You can use commas with no values -to leave some values unchanged. As an example, `MODE COM0: 9600,,,2` -will setup character device unit 0 for 9600 baud and 2 stop bits while -leaving data bits and stop bits as is. +| *``* is a FAT path +| *``*, *``* are FAT or CP/M filenames +| *``*, *``* are FAT filenames +| *``* is a FAT filename +| *``* is a FAT directory name +| *``* is a RomWBW disk unit number -Appending `/P` in a command specifying a new configuration will cause -the terminal output to pause and wait for the user to press a key. -This allows the user to change the local terminal setup before -continuing. +| CP/M filespec: *``*`:FILENAME.EXT` (*``* is CP/M drive letter A-P) +| FAT filespec: *``*`:/DIR/FILENAME.EXT` (*``* is RomWBW disk unit #) -## Notes +#### Usage -Specified baud rate and line characteristics must be supported by the -serial unit. Any parameters not specified will remain unchanged. +The `FAT` application determines whether you are referring to a CP/M +filesystem or a FAT filesystem based on the way you specify the file +or path. If the file or path is prefixed with a number (n:), then it +is assumed this is a FAT filesystem reference and is referring to the +FAT filesystem on RomWBW disk unit 'n'. Otherwise, the file +specification is assumed to be a normal CP/M file specification. -Changes are not persisted and will revert to system defaults at next -system boot. +If you wanted to list the directory of the FAT filesystem on RomWBW +disk unit 2, you would use `FAT DIR 2:`. If you only wanted to see the +".TXT" files, you would use `FAT DIR 2:*.TXT`. -Not all character devices support all `MODE` options. Some devices -(notably ASCI devices) have limited baud rate divisors. An attempt to -set a baud rate that the device cannot support will fail with an error -message. +If you wanted to copy all of the files on CP/M drive B: to the FAT +filesystem on RomWBW disk unit 4, you would use the command `FAT COPY +B:*.* 4:` If you wanted to copy the files to the "FOO" directory, then +you would use `FAT COPY B:*.* 4:\FOO`. To copy files in the opposite +direction, you just reverse the parameters. -## Etymology +To rename the file "XXX.DAT" to "YYY.DAT" on a FAT filesystem, you +could use a command like "FAT REN 2:XXX.DAT 2:YYY.DAT". -The `MODE` command is an original product and the source code is -provided in the RomWBW distribution. +To delete a file "XXX.DAT" on a FAT filesystem in directory "FOO", you +would use a command like `FAT DEL 2:\FOO\XXX.DAT`. -`\clearpage`{=latex} +To make a directory called "FOO2" on a FAT filesystem, you would use a +command line `FAT MD 2:\FOO2`. -# FDU +To format the filesystem on a FAT partition, you would use a command +like `FAT FORMAT 2:`. Use this with caution because it will destroy +all data on any pre-existing FAT filesystem on disk unit 2. -The FDU application is a Floppy Disk Utility that provides functions -to format and test floppy disk media. +#### Notes -## Syntax +Partitioned or non-partitioned media is handled automatically. A +floppy drive is a good example of a non-partitioned FAT filesystem and +will be recognized. Larger media will typically have a partition +table which will be recognized by the application to find the FAT +filesystem. -`FDU` +Although RomWBW-style CP/M media does not know anything about +partition tables, it is entirely possible to have media that +has both CP/M and FAT file systems on it. This is accomplished +by creating a FAT filesystem on the media that starts on a track +beyond the last track used by CP/M. Each CP/M slice can occupy +up to 8MB. So, make sure to start your FAT partition beyond +(slice count) * 9MB. -## Usage +The application infers whether you are attempting to reference a FAT +or CP/M filesystem via the drive specifier (char before ':'). A +numeric drive character specifies the HBIOS disk unit number for FAT +access. An alpha (A-P) character indicates a CP/M file system access +targeting the specified drive letter. If there is no drive character +specified, the current CP/M filesystem and current CP/M drive is +assumed. For example: -This application has an interactive user interface. At startup, you -will be prompted to select the floppy interface hardware in your -system. Following this, you will see the main menu of the program with -many functions to manage floppy disk drives. +| `2:README.TXT` refers to FAT file "README.TXT" on disk unit #2 +| `C:README.TXT` refers to CP/M file "README.TXT" on CP/M drive C +| `README.TXT` refers to CP/M file "README.TXT" on the current CP/M drive -The primary documentation for this application is in a file called -"FDU.txt" in the Doc directory of the RomWBW distribution. Please -consult this file for usage information. +Files with SYS, HIDDEN, or R/O only attributes are not given any +special treatment. Such files are found and processed like any other +file. However, any attempt to write to a read-only file will fail and +the application will abort. -## Notes +It is not currently possible to reference CP/M user areas other than +the current user. To copy files to alternate user areas, you must +switch to the desired user number first or use an additional step to +copy the file to the desired user area. -This application interfaces directly to the floppy hardware in your -system. It does not use the RomWBW HBIOS. This means that even if your -system is not configured for floppy drives, you can still use `FDU` -to test your floppy drives and format floppy media. This also means it -is critical that you choose the correct hardware interface from the -initial selection when starting the application. +Accessing FAT filesystems on a floppy requires the use of RomWBW HBIOS +v2.9.1-pre.13 or greater. -## Etymology +Only the first 8 RomWBW disk units (0-7) can be referenced. -The `FDU` command is an original product and the source code is -provided in the RomWBW distribution. +Files written are not verified. -`\clearpage`{=latex} +Wildcard matching in FAT filesystems is a bit unusual as implemented by +FatFs. See FatFs documentation. -# FORMAT +#### Etymology -This application is just a placeholder for a future version that will -make it simpler to format media including floppy disks. +The `FAT` application is an original RomWBW work, but utilizes the +FsFat library for all of the FAT filesystem work. This application is +written in C and requires SDCC to compile. As such it is not part of +the RomWBW build process. However, the full project and source code is +found in the [FAT GitHub Repository](https://github.com/wwarthen/FAT). -## Syntax +#### Known Issues -`FORMAT` +CP/M (and workalike) OSes have significant restrictions on filename +characters. The FAT application will block any attempt to create a +file on the CP/M filesystem containing any of these prohibited +characters: -## Notes +| `< > . , ; : ? * [ ] |/ \` -This application currently just displays a few lines of information -briefly instructing a user how to format media. It performs no actual -function beyond this display currently. +The operation will be aborted with "`Error: Invalid Path Name`" if such +a filename character is encountered. -## Etymology +Since MS-DOS does allow some of these characters, you can have +issues when copying files from MS-DOS to CP/M if the MS-DOS filenames +use these characters. Unfortunately, FAT is not yet smart enough to +substitute illegal characters with legal ones. So, you will need to +clean the filenames before trying to copy them to CP/M. -The `FORMAT` command is an original product and the source code is -provided in the RomWBW distribution. +The FAT application does try to detect the scenario where you are +copying a file to itself. However, this detection is not perfect and +can corrupt a file if it occurs. Be careful to avoid this. `\clearpage`{=latex} -# XM +## FDISK80 -An adaptation of Ward Christensen's X-Modem protocol for transferring -files between systems using a serial port. +| FDISK80 | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -## Syntax +`FDISK80` allows you to create and manage traditional partitions on +your hard disk media. Depending on the hard disk format and features +you are using, RomWBW may need hard disk partitions defined. -| `XM S `*``* -| `XM SK `*``* -| `XM L `*` `* -| `XM LK `*` `* -| `XM R `*``* +Please refer to the $doc_user$ for more information on the use of +partitions within RomWBW. It is very important to understand that +RomWBW slices are completely different from disk partitions. -`S`: Send a file -`L`: Send a file from a library -`R`: Receive a file -`K`: Use 1K blocksize for transfer +This application is provided by John Coffman. The primary +documentation is in the file "FDisk Manual.pdf" found in the +Doc directory of the RomWBW distribution. -*``* is the name of a file to send or receive +#### Usage -*``* is the name of a library (.lbr) to extract a file to send +`FDISK80` is an interactive application. At startup it will ask you +for the disk unit that you want to partition. When your RomWBW system +boots, it will display a table with the disk unit numbers. Use the +disk unit numbers from that table to enter the desired disk unit to +partition. -## Usage +`FDISK80` operates very much like other FDISK disk partitioning +applications. Please refer to the file called "FDisk Manual.pdf" in +the Doc directory of the RomWBW distribution for further instructions. -To transfer a file from your host computer to your RomWBW computer, do -the following: +If 'slices' for CP/M have been created using `FDISK80`, then these will +need to have their directory areas initialised properly using `CLRDIR`. +Failure to do this will likely result in corrupted data. -1. Enter one of the `XM` receive commands specifying the name you want -to give to the received file. +There is also more information on using FAT partitions with RomWBW in +the $doc_user$ document in the Doc directory of the distribution. -2. On your host computer select a file to send and initiate the XModem -send operation. +#### Notes -To transfer a file from your RomWBW computer to your host computer, do -the following: +Hard disk partition tables allow a maximum of 1024 cylinders when +defining partitions. However, RomWBW uses exclusively Logical Block +Addressing (LBA) which does not have this limitation. When defining +partitions is usually best to define the start and size of of the +partition using bytes or sectors. -1. Enter one of the `XM` send commands specifying the name of the file -to be sent. +#### Etymology -2. On your host computer, specify the name to assign to the received -file and initiate and XModem receive operation. +The source for this application was provided directly by John Coffman. +It is a C program and requires a build environment that includes the +SDCC compiler. As such, it is not included in the RomWBW build +process, only the binary executable is included. -Please refer to the documentation of your host computer's terminal -emulation software for specific instructions on how to use XModem. +Please contact John Coffman if you would like a copy of the source. -## Notes +`\clearpage`{=latex} -The XModem adaptation that comes with RomWBW will automatically use -the primary character device unit (character device unit 0) for the -file transfer. +## FDU -`XM` attempts to determine the best way to drive the serial port based -on your hardware configuration. When possible, it will bypass the -HBIOS for faster operation. However, in many cases, it will use HBIOS -so that flow control can be used. +| FDU | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -`XM` is dependent on a reliable communications channel. You must -ensure that the serial port can be serviced fast enough by either -using a baud rate that is low enough or ensuring that hardware flow -control is fully functional (end to end). +The FDU application is a Floppy Disk Utility that provides functions +to format and test floppy disk media. -## Etymology +#### Syntax -The `XM` application provided in RomWBW is an adaptation of a -pre-existing XModem application. Based on the source code comments, it -was originally adapted from Ward Christensen's MODEM2 by Keith -Petersen and is labelled version 12.5. +`FDU` -The original source of the application was found in the Walnut Creek -CD-ROM and is called XMDM125.ARK dated 7/15/86. +#### Usage -The actual application is virtually untouched in the RomWBW -adaptation. The majority of the work was in the modem driver which was -enhanced to detect the hardware being used and dynamically choose the -appropriate driver. +This application has an interactive user interface. At startup, you +will be prompted to select the floppy interface hardware in your +system. Following this, you will see the main menu of the program with +many functions to manage floppy disk drives. + +The primary documentation for this application is in a file called +"FDU.txt" in the Doc directory of the RomWBW distribution. Please +consult this file for usage information. + +#### Notes + +This application interfaces directly to the floppy hardware in your +system. It does not use the RomWBW HBIOS. This means that even if your +system is not configured for floppy drives, you can still use `FDU` +to test your floppy drives and format floppy media. This also means it +is critical that you choose the correct hardware interface from the +initial selection when starting the application. -The source code is provided in the RomWBW distribution. +#### Etymology + +The `FDU` command is an original product and the source code is +provided in the RomWBW distribution. `\clearpage`{=latex} -# FLASH +## FLASH + +| FLASH | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| Most of the hardware platforms that run RomWBW support the use of EEPROMs -- Electronically Erasable Programmable ROMs. The `FLASH` @@ -500,7 +1460,7 @@ removing the ROM from your system. This application is provided by Will Sowerbutts. -## Syntax +#### Syntax | `FLASH READ `*``*` [options]` | `FLASH VERIFY `*``*` [options]` @@ -523,7 +1483,7 @@ Options: | `/P112`: Force P112 bank switching | `/N8VEMSBC`: Force N8VEM SBC (v1, v2), Zeta (v1) SBC bank switching -## Usage +#### Usage To program your EEPROM ROM chip, first transfer the file to your RomWBW system. Then use the command `FLASH WRITE *``*. The @@ -541,12 +1501,12 @@ of the command. The author's documentation for the application is found in the RomWBW distribution in the Doc/Contrib directory. -## Notes +#### Notes The application supports a significant number of EEPROM parts. It should automatically detect your part. If it does not recognize your chip, make sure that you do not have a write protect jumper set -- -this jumper will prevent the ROM chip from being recognized. +this jumper can prevent the ROM chip from being recognized. Reprogramming a ROM chip in-place is inherently dangerous. If anything goes wrong, you will be left with a non-functional system and no @@ -554,7 +1514,7 @@ ability to run the `FLASH` application again. Use this application with caution and be prepared to use a hardware ROM programmer to restore your system if needed. -## Etymology +#### Etymology This application was written and provided by Will Sowerbutts. He provides it in binary format and is included in the RomWBW @@ -565,130 +1525,156 @@ GitHub repository](https://github.com/willsowerbutts/flash4). `\clearpage`{=latex} -# FDISK80 - -`FDISK80` allows you to create and manage traditional partitions on -your hard disk media. Depending on the hard disk format and features -you are using, RomWBW may need hard disk partitions defined. - -Please refer to the $doc_user$ for more information on the use of -partitions within RomWBW. It is very important to understand that -RomWBW slices are completely different from disk partitions. - -This application is provided by John Coffman. The primary -documentation is in the file "FDisk Manual.pdf" found in the -Doc directory of the RomWBW distribution. - -## Usage +## FORMAT -`FDISK80` is an interactive application. At startup it will ask you -for the disk unit that you want to partition. When your RomWBW system -boots, it will display a table with the disk unit numbers. Use the -disk unit numbers from that table to enter the desired disk unit to -partition. +| FORMAT | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -`FDISK80` operates very much like other FDISK disk partitioning -applications. Please refer to the file called "FDisk Manual.pdf" in -the Doc directory of the RomWBW distribution for further instructions. +This application is just a placeholder for a future version that will +make it simpler to format media including floppy disks. -There is also more information on using FAT partitions with RomWBW in -the $doc_user$ document in the Doc directory of the distribution. +#### Syntax -## Notes +`FORMAT` -Hard disk partition tables allow a maximum of 1024 cylinders when -defining partitions. However, RomWBW uses exclusively Logical Block -Addressing (LBA) which does not have this limitation. When defining -partitions is usually best to define the start and size of of the -partition using bytes or sectors. +#### Notes -## Etymology +This application currently just displays a few lines of information +briefly instructing a user how to format media. It performs no actual +function beyond this display currently. -The source for this application was provided directly by John Coffman. -It is a C program and requires a build environment that includes the -SDCC compiler. As such, it is not included in the RomWBW build -process, only the binary executable is included. +#### Etymology -Please contact John Coffman if you would like a copy of the source. +The `FORMAT` command is an original product and the source code is +provided in the RomWBW distribution. `\clearpage`{=latex} -# TALK +## HTALK -It is sometimes useful to direct your console input/output to a -designated serial port. For example, if you were to connect a modem -to your second serial port, you might want to connect directly to it -and have everything you type sent to it and everything it sends be -shown on your console. The `TALK` application does this. +| HTALK | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -## Syntax +`HTALK` is a variation of the `TALK` utility, but it works directly +against HBIOS Character Units. -`TALK [TTY:|CRT:|BAT:UC1:]` +#### Syntax + +`HTALK COMn:` -## Usage +#### Usage -`TALK` operates at the operating system level (not HBIOS). +`HTALK` operates at the HBIOS level. -The parameter to `TALK` refers to logical CP/M serial devices. Upon +The parameter to `TALK` refers to a HBIOS character unit. Upon execution all characters typed at the console will be sent to the device specified and all characters received by the specified device will be echoed on the console. Press Control+Z on the console to terminate the application. -## Notes +#### Notes -This application is designed for CP/M 2.2 or Z-System. Use on later -operating systems such as CP/M 3 is not supported. -## Etymology +#### Etymology -The `TALK` command is an original product and the source code is -provided in the RomWBW distribution. +The `TALK` command was created and donated to RomWBW by Tom Plano. It +is an original product designed specifically for RomWBW. `\clearpage`{=latex} -# HTALK +## MODE -`HTALK` is a variation of the `TALK` utility, but it works directly -against HBIOS Character Units. +| MODE | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -## Syntax +The MODE command allows you to adjust the operating characteristics +such as baud rate, data bits, stop bits, and parity bits of serial +ports dynamically. -`HTALK COMn:` +#### Syntax -## Usage +`MODE /?` +`MODE COM`*``*`: [`*``*`[,`*``*`[,`*``*`[,`*``*`]]]] [/P]` -`HTALK` operates at the HBIOS level. +`/?` displays command usage and version information -The parameter to `TALK` refers to a HBIOS character unit. Upon -execution all characters typed at the console will be sent to the -device specified and all characters received by the specified device -will be echoed on the console. +*``* is the character device unit number -Press Control+Z on the console to terminate the application. +*``* is numerical baudrate -## Notes +*``* is (N)one, (O)dd, (E)ven, (M)ark, or (S)pace +*``* is number of data bits, typically 7 or 8 -## Etymology +*``* is number of stop bits, typically 1 or 2 -The `TALK` command was created and donated to RomWBW by Tom Plano. It -is an original product designed specifically for RomWBW. +`/P` prompts user prior to setting new configuration + +#### Usage + +`MODE /?` will display basic command usage and version information. + +`MODE` with no parameters will list all devices and their current +configuration. + +`MODE <`*n*`>` will display the current configuration of the specified +character device unit. + +`MODE COM`*``*`: [`*``*`[,`*``*`[,`*``*`[,` +*``*`]]]] [/P]` requests that the specified configuration +be set on the character device unit. You can use commas with no values +to leave some values unchanged. As an example, `MODE COM0: 9600,,,2` +will setup character device unit 0 for 9600 baud and 2 stop bits while +leaving data bits and stop bits as is. + +Appending `/P` in a command specifying a new configuration will cause +the terminal output to pause and wait for the user to press a key. +This allows the user to change the local terminal setup before +continuing. + +#### Notes + +Specified baud rate and line characteristics must be supported by the +serial unit. Any parameters not specified will remain unchanged. + +Changes are not persisted and will revert to system defaults at next +system boot. + +Not all character devices support all `MODE` options. Some devices +(notably ASCI devices) have limited baud rate divisors. An attempt to +set a baud rate that the device cannot support will fail with an error +message. + +#### Etymology + +The `MODE` command is an original product and the source code is +provided in the RomWBW distribution. `\clearpage`{=latex} -# RTC +## RTC + +| RTC | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |yes| Many RomWBW systems provide real time clock hardware. The RTC application is a simple, interactive program allowing you to display and set the time and registers of the RTC. -## Syntax +#### Syntax `RTC` -## Usage +#### Usage After startup, the application provides the following options: @@ -709,7 +1695,7 @@ After startup, the application provides the following options: | `B)oot` | will reboot your system. | | `H)elp` | displays brief help. | -## Notes +#### Notes When using Get and Put options, the register number to read/write is entered in hex. The non-volatile ram register numbers are 0x20-0x3F. @@ -721,7 +1707,7 @@ the two hex characters. Yes, this should be improved. The `RTC` application interacts directly with the RTC hardware bypassing HBIOS. -## Etymology +#### Etymology The `RTC` application was originally written by Andrew Lynch as part of the original ECB SBC board development. It has since been modified to @@ -729,308 +1715,254 @@ support most of the hardware variations included with RomWBW. `\clearpage`{=latex} -# TIMER +## SURVEY -Most RomWBW systems have a 50Hz periodic system timer. A counter is -incremented every time a timer tick occurs. The `TIMER` application -displays the value of the counter. - -## Syntax - -`TIMER` -`TIMER /?` -`TIMER /C` - -## Usage - -Use `TIMER` to display the current value of the counter. - -Use `TIMER /C` to display the value of the counter continuously. - -The display of the counter will be something like this: - -`00045444 Ticks, 0000162A.10 Seconds` - -The first number is the total number of ticks since system startup. -The second number is the total number of seconds since system startup. - -## Notes - -The seconds value is displayed with a fractional value which is not a -an actual fraction, but rather the number of ticks past the seconds -rollover. All values are in hex. - -The primary use of the `TIMER` application is to test the system -timer functionality of your system. - -In theory, you could capture the value before and after some process -you want to time. - -## Etymology - -The `TIMER` command is an original product and the source code is -provided in the RomWBW distribution. +| SURVEY | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -`\clearpage`{=latex} - -# INTTEST - -RomWBW includes an API allowing applications to "hook" interrupts. -The `INTTEST` application allows you to test this functionality. - -## Syntax +The `SURVEY` command interrogates the system for information on disk +usage, memory usage and I/O ports used, and reports it to the user. -`INTTEST` +#### Syntax -## Usage +The `SURVEY` command takes no arguments. -`INTTEST` is an interactive application. At startup, it will display -a list of the interrupt vector slots in your system along with the -current vector address for each of them. +| `SURVEY` -It then prompts you to enter the slot number (in hex) of a vector to -hook. After entering this, the application will watch the hooked -vector and countdown from 0xFF to 0x00 as interrupts are noted. +#### Usage -When the counter reaches 0x00, the interrupt is unhooked and the -application terminates. The application can also be terminated by -pressing . +The results presented by `SURVEY` include: -## Notes +1. Information about any drives, within the first eight (ie A: to H:), +which have been logged by the system. This includes: the total number +of files; the storage capacity occupied by those files; and the capacity +remaining on that drive. -If your system is running without interrupts active, the application -will terminate immediately. +1. Information about the the 64KByte CP/M memory map, which is shown +diagramatically, and includes: locations and sizes of the TPA (Transient Program Area), +CP/M's CCP (Console Command Processor),and BDOS (Basic Disk Operating System). -All slots have vectors even if the corresponding interrupt is not -doing anything. In this case, the vector is pointing to the "bad -interrupt" handler. +1. The addresses of active CPU I/O ports. -If you hook a vector that is not receiving any interrupts, the -downcounter will not do anything. +#### Notes -## Etymology - -The `INTTEST` command is an original product and the source code is -provided in the RomWBW distribution. +The mechanism by which `SURVEY` discovers I/O ports is very conservative and +therefore the list returned may not be exhaustive. In particular, it may fail to +discover ports that are 'write-only'. `\clearpage`{=latex} -# FAT +## SYSCOPY -The operating systems included with RomWBW do not have any native -ability to access MS-DOS FAT filesystems. The FAT application can be -used overcome this. It will allow you to transfer files between CP/M -and FAT filesystems (wildcards supported). It can also erase files, -format, and list directories of FAT filesystems. +| SYSCOPY | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -## Syntax +To make disk media bootable, you must write a system boot image onto +the system tracks of the of the media. The `SYSCOPY` allows you to +read or write the system boot image of disk media. -| `FAT DIR `*``* -| `FAT COPY `*` `* -| `FAT REN `*` `* -| `FAT DEL `*`[|]`* -| `FAT MD `*``* -| `FAT FORMAT `*``* +#### Syntax -| *``* is a FAT path -| *``*, *``* are FAT or CP/M filenames -| *``*, *``* are FAT filenames -| *``* is a FAT filename -| *``* is a FAT directory name -| *``* is a RomWBW disk unit number +| `SYSCOPY `*``*`=`*``* -| CP/M filespec: *``*`:FILENAME.EXT` (*``* is CP/M drive letter A-P) -| FAT filespec: *``*`:/DIR/FILENAME.EXT` (*``* is RomWBW disk unit #) +*``* is the drive to receive the operating system image or +alternatively a filename to save the operating system image -## Usage +*``* is the drive containing an operating system image or +alternatively a filename containing the system image to be placed on +the destination -The `FAT` application determines whether you are referring to a CP/M -filesystem or a FAT filesystem based on the way you specify the file -or path. If the file or path is prefixed with a number (n:), then it -is assumed this is a FAT filesystem reference and is referring to the -FAT filesystem on RomWBW disk unit 'n'. Otherwise, the file -specification is assumed to be a normal CP/M file specification. +#### Usage -If you wanted to list the directory of the FAT filesystem on RomWBW -disk unit 2, you would use `FAT DIR 2:`. If you only wanted to see the -".TXT" files, you would use `FAT DIR 2:*.TXT`. +Both *``* and *``* can refer to either a drive letter or a +file. If a drive letter is specified, the system boot image will be +read or written to the system tracks of the drive. If a filename is +specified, the system boot image will be read or written to the +specified filename. -If you wanted to copy all of the files on CP/M drive B: to the FAT -filesystem on RomWBW disk unit 4, you would use the command `FAT COPY -B:*.* 4:` If you wanted to copy the files to the "FOO" directory, then -you would use `FAT COPY B:*.* 4:\FOO`. To copy files in the opposite -direction, you just reverse the parameters. +`SYSCOPY C:=ZSYS.SYS` will read a system boot image from the file +ZSYS.SYS and write it onto the system tracks of drive C:. -To rename the file "XXX.DAT" to "YYY.DAT" on a FAT filesystem, you -could use a command like "FAT REN 2:XXX.DAT 2:YYY.DAT". +`SYSCOPY A:OS.SYS=C:` will capture the system boot image from the +system tracks of drive C: and store it in the file A:OS.SYS. -To delete a file "XXX.DAT" on a FAT filesystem in directory "FOO", you -would use a command like `FAT DEL 2:\FOO\XXX.DAT`. +`SYSCOPY D:=C:` will copy the system tracks from drive C: onto the +system tracks of drive D:. -To make a directory called "FOO2" on a FAT filesystem, you would use a -command line `FAT MD 2:\FOO2`. +#### Notes -To format the filesystem on a FAT partition, you would use a command -like `FAT FORMAT 2:`. Use this with caution because it will destroy -all data on any pre-existing FAT filesystem on disk unit 2. +The RomWBW ROM disk contains files with the system boot image for +Z-System and CP/M 2.2. These files are called CPM.SYS and ZSYS.SYS +respectively. These files can be used as the source of a `SYSCOPY` +command to make a disk bootable with the corresponding operating +system. -## Notes +CP/M 3 uses a two phase boot process. To make a CP/M 3 drive bootable, +you need to put "CPMLDR.SYS" on the boot tracks of the disk and be +sure that the drive also contains the "CPM.SYS" file. The "CPMLDR.SYS" +file is not included on the ROM disk, but is found on the CP/M 3 disk +image. -Partitioned or non-partitioned media is handled automatically. A -floppy drive is a good example of a non-partitioned FAT filesystem and -will be recognized. Larger media will typically have a partition -table which will be recognized by the application to find the FAT -filesystem. +ZPM3 is similar to CP/M 3. You also put "CPMLDR.SYS" on the system +tracks of the drive to make it bootable. The ZPM3 operating system is +in the file called "CPM3.SYS" on the ZPM3 disk image. It may seem +confusing that ZPM3 is in the file called CPM3.SYS, but it is normal +for ZPM3. -Although RomWBW-style CP/M media does not know anything about -partition tables, it is entirely possible to have media that -has both CP/M and FAT file systems on it. This is accomplished -by creating a FAT filesystem on the media that starts on a track -beyond the last track used by CP/M. Each CP/M slice can occupy -up to 8MB. So, make sure to start your FAT partition beyond -(slice count) * 9MB. +For the purposes of booting an operating system, each disk slice is +considered its own operating system. Each slice can be made bootable +with its own system tracks. -The application infers whether you are attempting to reference a FAT -or CP/M filesystem via the drive specifier (char before ':'). A -numeric drive character specifies the HBIOS disk unit number for FAT -access. An alpha (A-P) character indicates a CP/M file system access -targeting the specified drive letter. If there is no drive character -specified, the current CP/M filesystem and current CP/M drive is -assumed. For example: +`SYSCOPY` uses drive letters to specify where to read/write the system +boot images. However, at startup, the boot loaded will require you to +enter the actual disk device and slice to boot from. So, you need to +be careful to pay attention to the device and slice that is assigned +to a drive letter so you will know what to enter at the boot loader +prompt. By way of explanation, the boot loader does not know about +drive letters because the operating system is not loaded yet. -| `2:README.TXT` refers to FAT file "README.TXT" on disk unit #2 -| `C:README.TXT` refers to CP/M file "README.TXT" on CP/M drive C -| `README.TXT` refers to CP/M file "README.TXT" on the current CP/M drive +If you want to put a boot system image on a device and slice that is +not currently assigned to a drive letter, you will need to assign a +drive letter first. -Files with SYS, HIDDEN, or R/O only attributes are not given any -special treatment. Such files are found and processed like any other -file. However, any attempt to write to a read-only file will fail and -the application will abort. +Not all disk formats include space for system tracks. Such disk +formats cannot contains a system boot image and, therefore, cannot be +made bootable. The best example of such disk formats are the ROM and +RAM disks. To maximize usable file space on these drives, they do not +have system tracks. Obviously, ROM operating system is supported by +choosing a ROM operating system at the boot loader prompt. Any attempt +to write a system boot image to disk media with no system tracks will +cause SYSCOPY to fail with an error message. -It is not currently possible to reference CP/M user areas other than -the current user. To copy files to alternate user areas, you must -switch to the desired user number first or use an additional step to -copy the file to the desired user area. +The system boot images are paired with the ROM version in your system. +So, you must take care to update the system tracks of any bootable +disk when you upgrade your ROM firmware. -Accessing FAT filesystems on a floppy requires the use of RomWBW HBIOS -v2.9.1-pre.13 or greater. +The system boot images are **not** tied to specific hardware +configurations. System boot images and operating systems provided with +RomWBW will work with any supported RomWBW platform or hardware as +long as they are the same version as the RomWBW firmware. -Only the first 8 RomWBW disk units (0-7) can be referenced. +#### Etymology -Files written are not verified. +The `SYSCOPY` command is an original product and the source code is +provided in the RomWBW distribution. -Wildcard matching in FAT filesystems is a bit unusual as implemented by -FatFs. See FatFs documentation. +`\clearpage`{=latex} -The `FAT FORMAT` command will not perform a physical format on floppy -disks. You must use FDU to do this prior to using `FAT FORMAT`. +## TALK -Formatting (`FAT FORMAT`) of floppies does not work well. The -underlying FatFs library uses some non-standard fields. The resulting -floppy may or may not be useable on other systems. It is best to format -a FAT floppy on a Windows or DOS system. You should have no problems -copying files to/from such a floppy using `FAT`. +| TALK | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -## Etymology +It is sometimes useful to direct your console input/output to a +designated serial port. For example, if you were to connect a modem +to your second serial port, you might want to connect directly to it +and have everything you type sent to it and everything it sends be +shown on your console. The `TALK` application does this. -The `FAT` application is an original RomWBW work, but utilizes the -FsFat library for all of the FAT filesystem work. This application is -written in C and requires SDCC to compile. As such it is not part of -the RomWBW build process. However, the full project and source code is -found in the [FAT GitHub Repository](https://github.com/wwarthen/FAT). +#### Syntax -## Known Issues +`TALK [TTY:|CRT:|BAT:UC1:]` -CP/M (and workalike) OSes have significant restrictions on filename -characters. The FAT application will block any attempt to create a -file on the CP/M filesystem containing any of these prohibited -characters: +#### Usage -| `< > . , ; : ? * [ ] |/ \` +`TALK` operates at the operating system level (not HBIOS). -The operation will be aborted with "`Error: Invalid Path Name`" if such -a filename character is encountered. +The parameter to `TALK` refers to logical CP/M serial devices. Upon +execution all characters typed at the console will be sent to the +device specified and all characters received by the specified device +will be echoed on the console. -Since MS-DOS does allow some of these characters, you can have -issues when copying files from MS-DOS to CP/M if the MS-DOS filenames -use these characters. Unfortunately, FAT is not yet smart enough to -substitute illegal characters with legal ones. So, you will need to -clean the filenames before trying to copy them to CP/M. +Press Control+Z on the console to terminate the application. -The FAT application does try to detect the scenario where you are -copying a file to itself. However, this detection is not perfect and -can corrupt a file if it occurs. Be careful to avoid this. +#### Notes -`\clearpage`{=latex} +This application is designed for CP/M 2.2 or Z-System. Use on later +operating systems such as CP/M 3 is not supported. + +#### Etymology -# CLRDIR +The `TALK` command is an original product and the source code is +provided in the RomWBW distribution. -`CLRDIR` is used to initialize a CP/M filesystem. This is frequently -used to prepare RomWBW disk slices for use. If there is any data -on the filesystem, it will be destroyed. `CLRDIR` works on CP/M -drive letters. To initialize a RomWBW slice, the slice must first be -assigned to a CP/M drive letter. +`\clearpage`{=latex} +## TIMER -This application is provided by Max Scane. +| TIMER | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| -## Syntax +Most RomWBW systems have a 50Hz periodic system timer. A counter is +incremented every time a timer tick occurs. The `TIMER` application +displays the value of the counter. -| `CLRDIR `*``*` [options]` +#### Syntax -*``* is the CP/M drive letter to be cleared (e.g., "A:") +`TIMER` +`TIMER /?` +`TIMER /C` +#### Usage -Options: +Use `TIMER` to display the current value of the counter. -| `-D`: Enable debug output -| `-Y`: Do not ask for confirmation +Use `TIMER /C` to display the value of the counter continuously. -## Usage +The display of the counter will be something like this: -This application has a command line interface only. Type an -appropriately formatted command at the command prompt at any of the -RomWBW CP/M operatings systems (CP/M 2.2, ZSDOS, CP/M 3, etc.). +`13426 Ticks 268.52 Seconds` -You will be prompted for confirmation to continue. You must type a -**capital** 'Y' to proceed. The application will confirm that the -drive has been cleared. +The first number is the total number of ticks since system startup, where +there are 50 ticks per second. The second number is the total number of +seconds since system startup. Numbers are displayed in decimal format. -If used under ZSDOS, you should issue a `RELOG` command after using -`CLRDIR` to ensure that CP/M relogs the cleared drive. +#### Notes -## Notes +The seconds value is displayed with a fractional value which is not a +an actual fraction, but rather the number of ticks past the seconds +rollover. All values are in hex. -This command is inherently dangerous. It will completely destroy the -directory area of the target drive. Be very careful to ensure you do -not target a drive that contains useful data. +The primary use of the `TIMER` application is to test the system +timer functionality of your system. -`CLRDIR` understands the directory formats of all of the RomWBW -CPM-like operating systems and devices including floppy disks, CF/SD -Cards, etc. +In theory, you could capture the value before and after some process +you want to time. -## Etymology +#### Etymology -This application was written and provided by Max Scane. He -provides it in binary format and is included in the RomWBW -distribution as a binary file. +The `TIMER` command is an original product and the source code is +provided in the RomWBW distribution. `\clearpage`{=latex} -# TUNE +## TUNE + +| TUNE | | +| --------------------|---| +| ROM-based |No | +| Disk-based |Yes| If your RomWBW system has a sound card based on either an AY-3-8190 or YM2149F sound chip, you can use the `TUNE` application to play PT or MYM sound files. -## Syntax +#### Syntax `TUNE `*``* *``* is the name of a sound file ending in .PT2, .PT3, or .MYM -## Usage +#### Usage The TUNE application supports PT and YM sound file formats. It determines the format of the file from the extension of the file, so @@ -1040,7 +1972,7 @@ To play a sound file, just use the command and specify the file to play after the command. So, for example, `TUNE ATTACK.PT2` will immediately begin playing the PT sound file "ATTACK.PT2". -## Notes +#### Notes The `TUNE` application automatically probes for compatible hardware at well known port addresses at startup. It will auto-configure itself @@ -1078,7 +2010,7 @@ The HBIOS mode also support other switch as described below. All RomWBW operating system boot disks include a selection of sound files in user area 3. -## Etymology +#### Etymology The `TUNE` application was custom written for RomWBW. All of the hardware interface code is specific to RomWBW. The sound file decoding @@ -1088,77 +2020,14 @@ is (c)2004-2007 S.V.Bulba . The source code is provided in the RomWBW distribution. -# CPUSPD - -The `CPUSPD` application is used to change the running speed and wait -states of a RomWBW system. - - The functionality is highly dependent on -the capabilities of your system. - -At present, all Z180 systems can change their CPU speed and their -wait states. SBC and MBC systems may be able to change their CPU -speed if the hardware supports it and it is enabled in the HBIOS -configuration. - -## Syntax - -| `CPUSPD [`*``*`[,[`*``*`][,[`*``*`]]]` - -*``* is one of HALF, FULL, or DOUBLE. -*``* is a number specifying the desired memory wait states. -*``* is a number specifying the desired I/O wait states. - -## Usage - -Entering `CPUSPD` with no parameters will display the current CPU speed -and wait state information of the running system. Wait state -information is not available for all systems. - -To modify the running speed of a system, you can specify the -`*``*` parameter. To modify either or both of the wait -states, you can enter the desired number. Either or both of the wait -state parameters may be omitted and the current wait state settings -will remain in effect. - -## Notes - -The ability to modify the running speed and wait states of a system -varies widely depending on the hardware capabilities and the HBIOS -configuration settings. - -Note that it is frequently impossible to tell if a system is capable -of dynamic speed changes. This function makes the changes blindly. -If an attempt is made to change the speed of a system -that is definitely incapable of doing so, then an error result is -returned. - -The `CPUSPD` command makes no attempt to ensure that the new CPU -speed will actually work on the current hardware. Setting a CPU -speed that exceeds the capabilities of the system will result in -unstable operation or a system stall. - -Some peripherals are dependent on the CPU speed. For example, the Z180 -ASCI baud rate and system timer are derived from the CPU speed. The -CPUSPD application will attempt to adjust these peripherals for -correct operation after modifying the CPU speed. However, in some -cases this may not be possible. The baud rate of ASCI ports have a -limited set of divisors. If there is no satisfactory divisor to -retain the existing baud rate under the new CPU speed, then the baud -rate of the ASCI port(s) will be affected. - -## Etymology - -The `CPUSPD` application was custom written for RomWBW. All of the -hardware interface code is specific to RomWBW and the application will -not operate correctly on non-RomWBW systems. - -The source code is provided in the RomWBW distribution. - - `\clearpage`{=latex} -# VGMPLAY +## VGMPLAY + +| VGMPLAY | | +| --------------------|---| +| ROM-based |No | +| Disk-based |Yes| This application will allow you to play Video Game Music files. VGM files contain music samples from a range of different sound chips @@ -1189,17 +2058,18 @@ Sound chips currently supported are: VGMPLAY supports playback of files with multiple combinations of these chips. -## Syntax +#### Syntax `VGMPLAY `*``* *``* is the name of a sound file ending in .VGM -## Usage +#### Usage VGMPLAY does not automatically detect the hardware platform or sound hardware that you are using. This means a version customized for your -system must be assembled before use. +system must be assembled before use. However, the version as distributed +will work with ECB bus SBC systems. To play a sound file, just use the VGMPLAY command and specify the file to play after the command. So, for example, `VGMPLAY TEDDY` will load @@ -1208,7 +2078,7 @@ the TEDDY.VGM sound file into memory and begin playing it. Playback can be stopped by pressing a key. There may be a delay before playback stops. -## Notes +#### Notes The default build configuration for VGMPLAY is: @@ -1235,16 +2105,21 @@ RomWBW distribution. `\clearpage`{=latex} -# WDATE +## WDATE + +| WDATE | | +| --------------------|---| +| ROM-based |No | +| Disk-based |Yes| `wdate` is a utility for CP/M systems that have Wayne Warthen's -ROMWBW firmware. It reads or sets the real-time clock, using function +RomWBW firmware. It reads or sets the real-time clock, using function calls in the BIOS. It should work on any RTC device that is supported by -ROMWBW, including the internal interrupt-driven timer that is is available +RomWBW, including the internal interrupt-driven timer that is is available on some systems. `wdate` differs from the `rtc.com` utility that is provided with the -ROMWBW version of CP/M in that it only gets and sets the date/time. +RomWBW version of CP/M in that it only gets and sets the date/time. `rtc.com` can also manipulate the nonvolatile RAM in certain clock devices, and modify the charge controller. However, `wdate` is (I would argue) easier to use, as it takes its input from the command line, which @@ -1259,14 +2134,14 @@ application for two reasons: first, the BIOS does not expose it. Second, there is no universally-accepted way to interpret it (which day does the week start on? Is '0' a valid day of the week?) -## Syntax +#### Syntax | `WDATE` | `WDATE ` *`
`* | `WDATE ` *`
`* | `WDATE ` *`
`* -## Usage +#### Usage A> wdate Saturday 27 May 13:14:39 2023 @@ -1292,25 +2167,112 @@ two-digit year starts at 2000. Show a summary of the command-line usage. -## Notes +#### Notes I've tested this utility with the DS1302 clock board designed by Ed Brindly, and on the interrupt-driven timer built into my Z180 board. However, it does not interact with hardware, only BIOS; I would expect it to work with other hardware. -wdate checks for the non-existence of ROMWBW, and also for failing +wdate checks for the non-existence of RomWBW, and also for failing operations on the RTC. It will display the terse "No RTC" message in both cases. -The ROMWBW functions that manipulate the date and time operate on BCD +The RomWBW functions that manipulate the date and time operate on BCD numbers, as RTC chips themselves usually do. wdate works in decimal, so that it can check that the user input makes sense. A substantial part of the program's code is taken up by number format conversion and range checking. -## Etymology +#### Etymology The `WDATE` application was written and contributed by Kevin Boone. The source code is available on GitHub at -[https://github.com/kevinboone/wdate-cpm/blob/main/README.md](https://github.com/kevinboone/wdate-cpm/blob/main/README.md). +. + +`\clearpage`{=latex} + +## XM + +| XM | | +| --------------------|---| +| ROM-based |Yes| +| Disk-based |Yes| + +An adaptation of Ward Christensen's X-Modem protocol for transferring +files between systems using a serial port. + +#### Syntax + +| `XM S `*``* +| `XM SK `*``* +| `XM L `*` `* +| `XM LK `*` `* +| `XM R `*``* + +`S`: Send a file +`L`: Send a file from a library +`R`: Receive a file +`K`: Use 1K blocksize for transfer + +*``* is the name of a file to send or receive + +*``* is the name of a library (.lbr) to extract a file to send + +#### Usage + +To transfer a file from your host computer to your RomWBW computer, do +the following: + +1. Enter one of the `XM` receive commands specifying the name you want +to give to the received file. + +2. On your host computer select a file to send and initiate the XModem +send operation. + +To transfer a file from your RomWBW computer to your host computer, do +the following: + +1. Enter one of the `XM` send commands specifying the name of the file +to be sent. + +2. On your host computer, specify the name to assign to the received +file and initiate and XModem receive operation. + +Please refer to the documentation of your host computer's terminal +emulation software for specific instructions on how to use XModem. + +#### Notes + +The XModem adaptation that comes with RomWBW will automatically use +the primary character device unit (character device unit 0) for the +file transfer. + +`XM` attempts to determine the best way to drive the serial port based +on your hardware configuration. When possible, it will bypass the +HBIOS for faster operation. However, in many cases, it will use HBIOS +so that flow control can be used. + +`XM` is dependent on a reliable communications channel. You must +ensure that the serial port can be serviced fast enough by either +using a baud rate that is low enough or ensuring that hardware flow +control is fully functional (end to end). + +#### Etymology + +The `XM` application provided in RomWBW is an adaptation of a +pre-existing XModem application. Based on the source code comments, it +was originally adapted from Ward Christensen's MODEM2 by Keith +Petersen and is labelled version 12.5. + +The original source of the application was found in the Walnut Creek +CD-ROM and is called XMDM125.ARK dated 7/15/86. + +The actual application is virtually untouched in the RomWBW +adaptation. The majority of the work was in the modem driver which was +enhanced to detect the hardware being used and dynamically choose the +appropriate driver. + +The source code is provided in the RomWBW distribution. + +`\clearpage`{=latex} diff --git a/Source/Doc/Basic.h b/Source/Doc/Basic.h index 4ab5106c..def9b838 100644 --- a/Source/Doc/Basic.h +++ b/Source/Doc/Basic.h @@ -11,7 +11,6 @@ $define{doc_orgurl}{www.retrobrewcomputers.org}$ $define{doc_user}{[RomWBW User Guide]($doc_root$/RomWBW User Guide.pdf)}$ $define{doc_sys}{[RomWBW System Guide]($doc_root$/RomWBW System Guide.pdf)}$ $define{doc_apps}{[RomWBW Applications]($doc_root$/RomWBW Applications.pdf)}$ -$define{doc_romapps}{[RomWBW ROM Applications]($doc_root$/RomWBW ROM Applications.pdf)}$ $define{doc_catalog}{[RomWBW Disk Catalog]($doc_root$/RomWBW Disk Catalog.pdf)}$ $define{doc_errata}{[RomWBW Errata]($doc_root$/RomWBW Errata.pdf)}$ diff --git a/Source/Doc/Build.cmd b/Source/Doc/Build.cmd index 14ac1187..d96277dd 100644 --- a/Source/Doc/Build.cmd +++ b/Source/Doc/Build.cmd @@ -15,7 +15,6 @@ call :GenDoc ReadMe call :GenDoc UserGuide call :GenDoc SystemGuide call :GenDoc Applications -call :GenDoc ROM_Applications call :GenDoc Catalog call :GenDoc Errata @@ -24,7 +23,6 @@ if exist ReadMe.txt copy ReadMe.txt ..\..\ReadMe.txt || exit /b if exist UserGuide.pdf copy UserGuide.pdf "..\..\Doc\RomWBW User Guide.pdf" || exit /b if exist SystemGuide.pdf copy SystemGuide.pdf "..\..\Doc\RomWBW System Guide.pdf" || exit /b if exist Applications.pdf copy Applications.pdf "..\..\Doc\RomWBW Applications.pdf" || exit /b -if exist ROM_Applications.pdf copy ROM_Applications.pdf "..\..\Doc\RomWBW ROM Applications.pdf" || exit /b if exist Catalog.pdf copy Catalog.pdf "..\..\Doc\RomWBW Disk Catalog.pdf" || exit /b if exist Errata.pdf copy Errata.pdf "..\..\Doc\RomWBW Errata.pdf" || exit /b diff --git a/Source/Doc/Makefile b/Source/Doc/Makefile index 11e4c600..05c624f7 100644 --- a/Source/Doc/Makefile +++ b/Source/Doc/Makefile @@ -3,7 +3,7 @@ # and available on commandline for this build to work!!! # Typically "sudo apt install gpp pandoc texlive-latex-extra texlive-luatex texlive-fonts-extra fonts-roboto" # -OBJECTS = ReadMe.gfm ReadMe.txt UserGuide.pdf SystemGuide.pdf Applications.pdf ROM_Applications.pdf Catalog.pdf Errata.pdf +OBJECTS = ReadMe.gfm ReadMe.txt UserGuide.pdf SystemGuide.pdf Applications.pdf Catalog.pdf Errata.pdf # DEST = ../../Doc TOOLS = ../../Tools OTHERS = *.tmp @@ -36,6 +36,5 @@ deploy : cp UserGuide.pdf "../../Doc/RomWBW User Guide.pdf" cp SystemGuide.pdf "../../Doc/RomWBW System Guide.pdf" cp Applications.pdf "../../Doc/RomWBW Applications.pdf" - cp ROM_Applications.pdf "../../Doc/RomWBW ROM Applications.pdf" cp Catalog.pdf "../../Doc/RomWBW Disk Catalog.pdf" cp Errata.pdf "../../Doc/RomWBW Errata.pdf" diff --git a/Source/Doc/ROM_Applications.md b/Source/Doc/ROM_Applications.md deleted file mode 100644 index cfb8ae5f..00000000 --- a/Source/Doc/ROM_Applications.md +++ /dev/null @@ -1,635 +0,0 @@ -$define{doc_title}{ROM Applications}$ -$define{doc_author}{Phillip Summers}$ -$define{doc_authmail}{}$ -$include{"Book.h"}$ - -# Summary - -RomWBW includes a small selection of built in utilities and -programming languages. - -`\clearpage`{=latex} - -# RomWBW Monitor - -The Monitor program is a low level utility that can be used -for testing and programming. It allows programs to be entered, -memory to be examined, and input/output devices to be read or -written to. - -It's key advantage is that is available at boot up. - -Its key disadvantages are that code cannot be entered in assembly -language and there is no ability to save to memory devices. - -The available memory area for programming is `0200-EDFFh`. -The following areas are reserved: - -Memory Area | Function -------------|----------------------------------- -`0000-00FFh`| Jump and restart (RST) vectors -`0100-01FFh`| HBIOS configuration block -`EE00-FDFFh`| MONITOR -`FE00-FFFFh`| HBIOS proxy - -Commands can be entered at the command prompt `>` -Automatic case conversion takes place on command entry and all -arguments are expected to be in hex format. - -The current memory bank in low memory is displayed before the prompt i.e.: - -`8E>` - -The Monitor allows access to all memory locations but ROM and -Flash memory cannot be written to. Memory outside the normal -address range can be accessed using the B command. The first -256 bytes `0000-01FF` is critical for the HBIOS operation. -Changing banks may make this information inaccessible. - -Refer to the RomWBW Architecture manual for details memory banking. - -A quick guide to using the Monitor program follows: - -## ? - Displays a summary of available commands. - -``` -Monitor Commands (all values in hex): -B - Boot system -D xxxx [yyyy] - Dump memory from xxxx to yyyy -F xxxx yyyy zz - Fill memory from xxxx to yyyy with zz -H - Halt system -I xxxx - Input from port xxxx -K - Keyboard echo -L - Load Intel hex data -M xxxx yyyy zzzz - Move memory block xxxx-yyyy to zzzz -O xxxx yy - Output value yy to port xxxx -P xxxx - Program RAM at address xxxx -R xxxx [[yy] [zzzz]] - Run code at address xxxx - Pass yy and zzzz to register A and BC -T xxxx - X-modem transfer to memory location xxxx -S xx - Set bank to xx -X - Exit monitor -``` - -## Cold Boot - -B - Performs a cold boot of the ROMWBW system. A complete -re-initialization of the system is performed and the system -returns to the Boot Loader prompt. - -## Dump Memory - -D xxxx [yyyy] - Dump memory from hex location xxxx to yyyy -on the screen as lines of 16 hexadecimal bytes with their -ASCII equivalents (if within a set range, else a '.' is -printed). If the end address is omitted then 256 bytes is -displayed. - -A good tool to see where code is located, check -for version id, obtain details for chip configurations and -execution paths. - -Examples: `D 100 1FF` - -``` -0100: 10 0B 01 5A 33 45 4E 56 01 00 00 2A 06 00 F9 11 ...Z3ENV...*..ù. -0110: DE 38 37 ED 52 4D 44 0B 6B 62 13 36 00 ED B0 21 Þ87íRMD.kb.6.í°! -0120: 7D 32 E5 21 80 00 4E 23 06 00 09 36 00 21 81 00 }2å!..N#...6.!.. -0130: E5 CD 6C 1F C1 C1 E5 2A C9 8C E5 CD 45 05 E5 CD åÍl.ÁÁå*É.åÍE.åÍ -0140: 59 1F C3 00 00 C3 AE 01 C3 51 04 C3 4C 02 C3 57 Y.Ã..î.ÃQ.ÃL.ÃW -0150: 02 C3 64 02 C3 75 02 C3 88 02 C3 B2 03 C3 0D 04 .Ãd.Ãu.Ã..ò.Ã.. -0160: C3 19 04 C3 22 04 C3 2A 04 C3 35 04 C3 40 04 C3 Ã..Ã".Ã*.Ã5.Ã@.à -0170: 48 04 C3 50 04 C3 50 04 C3 50 04 C3 8F 02 C3 93 H.ÃP.ÃP.ÃP.Ã..Ã. -0180: 02 C3 94 02 C3 95 02 C3 85 04 C3 C7 04 C3 D1 01 .Ã..Ã..Ã..ÃÇ.ÃÑ. -0190: C3 48 02 C3 E7 04 C3 56 03 C3 D0 01 C3 D0 01 C3 ÃH.Ãç.ÃV.ÃÐ.ÃÐ.à -01A0: D0 01 C3 D0 01 C3 D0 01 C3 D0 01 01 02 01 CD 6B Ð.ÃÐ.ÃÐ.ÃÐ....Ík -01B0: 04 54 68 69 73 20 66 75 6E 63 74 69 6F 6E 20 6E .This function n -01C0: 6F 74 20 73 75 70 70 6F 72 74 65 64 2E 0D 0A 00 ot supported.... -01D0: C9 3E FF 32 3C 00 3A 5D 00 FE 20 28 14 D6 30 32 É>ÿ2<.:].þ (.Ö02 -01E0: AB 01 32 AD 01 3A 5E 00 FE 20 28 05 D6 30 32 AC «.2­.:^.þ (.Ö02¬ -01F0: 01 C5 01 F0 F8 CF E5 26 00 0E 0A CD 39 02 7D 3C .Å.ðøÏå&...Í9.}< -``` - -## Fill Memory - -F xxxx yyyy zz - Fill memory from hex xxxx to yyyy with -a single value of zz over the full range. The Dump command -can be used to confirm that the fill completed as expected. A -good way to zero out memory areas before writing machine data -for debug purposes. - -## Halt System - -H - Halt system. A Z80 HALT instruction is executed. The -system remains in the halt state until the system is -physically rebooted. Interrupts will not restart the -system. On systems that support a HALT status LED, the -LED will be illuminated. - -## Input from port - -I xxxx - Input data from port xxxx and display to the screen. -This command is used to read values from hardware I/O ports -and display the contents in hexadecimal. - -## Keyboard Echo - -K - Echo any key-presses from the terminal. Press 'ESC' key -to quit. This facility provides that any key stroke sent to -the computer will be echoed back to the terminal. File down -loads will be echoed as well while this facility is ‘on’. - -## Load Hex format file into memory - -L - Load a Intel Hex format file via the terminal program. -The load address is defined in the hex file of the -assembled code. - -The terminal emulator program should be configured to -give a delay at the end of each line to allow the monitor -enough time to parse the line and move the data to memory. - -Keep in mind that this will be a transient unless the -system support battery backed memory. Saving to memory drive -is not supported. - -## Move memory - -M xxxx yyyy zzzz - Move hex memory block xxxx to yyyy to -memory starting at hex location zzzz. Care should be taken -to insure that there is enough memory at the destination so -that code does not get over-written or memory wrapped around. - -## Output to port - -O xxxx yy - Output data byte xx to port xxxx. This command is -used to send hexadecimal values to hardware I/O ports to -verify their operation and is the companion to the I operation. -Use clip leaded LEDs to confirm the data written. - -## Program memory location - -P xxxx - Program memory location xxxx. This routine will -allow you to program a hexadecimal value 'into memory starting -at location xxxx. Press 'Enter' on a blank line to -return to the Monitor prompt. - -The limitation around programming memory is that it must be -entered in hexadecimal. An alternative is to use the L command -to load a program that has been assembled to a hex file on the -remote computer. - -An excellent online resource for looking up opcodes for entry -can be found here: [https://clrhome.org/table](https://clrhome.org/table) - -## Run program - -R xxxx [[yy] [zzzz]] - Run program at location xxxx. If optional -arguments yy and zzzz are entered they are loaded into the -A and BC register respectively. The return address of the -Monitor is saved on the stack so the program can return -to the monitor. On return to the monitor, the contents of -the A, HL, DE and BC registers are displayed. - -## Set bank - -S xx - Change the bank in memory to xx. Memory addresses -0000-7FFF (i.e. bottom 32k) are affected. Because the -interrupt vectors are stored in the bottom page of this -range, this function is disable when interrupt mode 1 is -being used (IM1). Interrupt mode 2 is not affected as the -associated jump vectors are stored in high memory. - -Changing the bank also impacts the restart vectors (RST), -so executing code that call the HBIOS using the RST 08 -assembly code will not work. - -The monitor stack resides in high memory and is not affected -but any code that changes the stack to low memory will be -affected. - -### Bank codes and descriptions - -TYPE | DESCRIPTION |BANK| DETAILS ------|--------------------|----|--------------------- -RAM | COMMON BANK | 9F | 1024K RAM SYSTEM -RAM | USER BANK | 9E | 1024K RAM SYSTEM -RAM | BIOS BANK | 9D | 1024K RAM SYSTEM -RAM | AUX BANK | 9C | 1024K RAM SYSTEM -RAM | OS BUFFERS END | 9B | 1024K RAM SYSTEM -RAM | OS BUFFERS START | 98 | 1024K RAM SYSTEM -RAM | RAM DRIVE END | 97 | 1024K RAM SYSTEM -RAM | COMMON BANK | 8F | 512K RAM SYSTEM -RAM | USER BANK | 8E | 512K RAM SYSTEM -RAM | BIOS BANK | 8D | 512K RAM SYSTEM -RAM | AUX BANK | 8C | 512K RAM SYSTEM -RAM | OS BUFFERS | 8B | 512K RAM SYSTEM -RAM | OS BUFFERS | 8A | 512K RAM SYSTEM -RAM | OS BUFFERS | 89 | 512K RAM SYSTEM -RAM | OS BUFFERS | 88 | 512K RAM SYSTEM -RAM | RAM DRIVE END | 87 | 512K RAM SYSTEM -RAM | RAM DRIVE START | 80 | -ROM | BOOT BANK | 00 | COLD START & HBIOS -ROM | LOADER & IMAGES | 01 | MONITOR, FORTH -ROM | ROM IMAGES CONTD. | 02 | BASIC, ETC -ROM | FAT FILESYSTEM | 03 | UNA ONLY, ELSE UNUSED -ROM | ROM DRIVE START | 04 | -ROM | ROM DRIVE END | 0F | 512K ROM SYSTEM -ROM | ROM DRIVE END | 1F | 1024K ROM SYSTEM - -## X-modem transfer - -T xxxx - Receive an X-modem file transfer and load it into -memory starting at location xxxx. - -128 byte blocks and checksum mode is the only supported -protocol. - -If the monitor is assembled with the DSKY functionality, -this feature will be exclude due to space limitations. - - -## NOTES: - -The RTC utility on the CP/M ROM disk provides facilities -to manipulate the Real Time Clock non-volatile Memory. -Use the C or Z option from the Boot Loader to load CP/M -and then run RTC to see the options list. - -# FORTH - -CamelForth is the version of Forth included as part of the boot -ROM in ROMWBW. It has been converted from the Z80 CP/M version -published here [www.camelforth.com/page.php?5](www.camelforth.com/page.php?5). The author is Brad -Rodriguez who is a prolific Forth enthusiast, whose work can be -found here: [www.bradrodriguez/papers/index.html](www.bradrodriguez/papers/index.html) - -For those are who are not familiar with Forth, I recommend the -wikipedia article [en.wikipedia.org/wiki/Forth_(programming_language](en.wikipedia.org/wiki/Forth_(programming_language)) -and the Forth Interest Group website [www.forth.org](www.forth.org) - -## Important things to know - -Forth is case sensitive. - -To exit back to the boot loader type ***bye*** - -To get a list of available words type ***WORDS*** - -To reset Forth to its initial state type ***COLD*** - -Most of the code you find on the internet will not run unless modified or additional Forth -words are added to the dictionary. - -This implementation does not support loading or saving of programs. All programs -need to be typed in. Additionally, screen editing and code blocks are not supported. - -## Structure of Forth source files - -File | Description ---------------|----------------------------- -camel80.azm | Code Primitives - camel80d.azm | CPU Dependencies - camel80h.azm | High Level words - camel80r.azm | ROMWBW additions -glosshi.txt | Glossary of high level words -glosslo.txt | Glossary of low level words -glossr.txt | Glossary of ROMWBW additions - -## ROMWBW Additions - -Extensions and changes to this implementation compared to the original distribution are: - -The source code has been converted from Z80mr assembler to Hector Peraza's zsm. - -An additional file camel80r.azm has been added for including additional words to -the dictionary at build time. However, as currently configured there is very little space -allocated for addition words. Exceeding the allocated ROM space will generate an error -message when building. - -James Bowman's double precision words have been added from his RC2014 version: -[https://github.com/jamesbowman/camelforth-z80](https://github.com/jamesbowman/camelforth-z80) - -Word | Syntax | Description ---------|----------------------------|--------------------------------- -D+ | d1 d2 -- d1+d2 | Add double numbers -2>R | d -- | 2 to R -2R> | d -- | fetch 2 from R -M*/ | d1 n2 u3 -- d=(d1*n2)/u3 | double precision mult. div -SVC | hl de bc n -- hl de bc af | Execute a ROMWBW function -P! | n p -- | Write a byte to a I/O port -P@ | p -- n | Read a byte from and I/O port - -# BASIC - -For those who are not familiar with BASIC, it stands for Beginners All purpose Symbolic -Instruction Code. - -ROMWBW contains two versions of ROM BASIC, a full implementation and a "tiny" BASIC. - -The full implementation is a version of Microsoft BASIC from the NASCOM Computer. - -A comprehensive instruction manual is available in the Doc\\Contrib directory. - -## ROMWBW specific features - -- Sound -- Graphics -- Terminal Support - -## ROMWBW unsupported features - -- This ROM-hosted implementation does not support cassette or disk - access for loading and saving programs. - -# TastyBASIC - -TastyBASIC offers a minimal implementation of BASIC that is only 2304 bytes in size. -It originates from Li-Chen Wang's Palo Alto Tiny BASIC from around 1976. It's small size suited the tiny memory capacities of the time. This implementation is by Dimitri Theulings and his -original source can be found here [https://github.com/dimitrit/tastybasic](https://github.com/dimitrit/tastybasic) - -## Features / Limitations - -- This ROM-hosted implementation does not support disk access for - loading and saving programs. -- Integer arithmetic, numbers -32767 to 32767 -- Singles letter variables A-Z -- 1-dimensional array support -- Strings are not supported - -## Direct Commands - -- `LIST`,`RUN`, `NEW`, `CLEAR`, `BYE` - -## Statements - -- `LET`, `IF`, `GOTO`, `GOSUB RETURN`, `REM`, `FOR TO NEXT STEP`, `INPUT`, `PRINT`, `POKE`, `END` - -## Functions - -- `PEEK`, `RND`, `ABS`, `USR`, `SIZE` - -## Operators - -- `>=`, `#`, `>`, `=`, `<=`, `<` - -- Operator precedence is supported. - -Type ***BYE*** to return to the monitor. - -# Play a Game - -## 2048 - -2048 is a puzzle game that can be both mindless and challenging. It -appears deceptively simple but failure can creep up on you suddenly. - -It requires an ANSI/VT-100 compatible colour terminal to play. - -2048 is like a sliding puzzle game except the puzzle tiles are -numbers instead of pictures. Instead of moving a single tile all -tiles are moved simultaneously in the same direction. Where two -tiles of the same number collide, they are reduced to one tile with -the combined value. After every move a new tile is added with -a starting value of 2. - -The goal is to create a tile of 2048 before all tile locations are -occupied. Reaching the highest points score, which is the sum of all -the tiles is a secondary goal. The game will automatically end when -there are no more possible moves. - -Play consists of entering a direction to move. Directions can be entered -using any of three different keyboard direction sets. - -``` -Direction | Keys -----------|---------- -Up | w ^E 8 -Down | s ^X 2 -Left | a ^S 4 -Right | d ^D 6 -``` -The puzzle board is a 4x4 grid. At start, the grid will be populated -with two 2 tiles. An example game sequence is shown below with new -tiles to the game shown in brackets. - -``` -Start Move 1 - Up Move 2 - Left Move 3 - Left -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ -| | | |(2)| | | | | 4 | | 4 | | | | | 4 | | | | -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ -| | | | | | | | | | | | | |(4)| | 4 | | | | -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ -| | | |(2)| | | | | | | | | | | | | | | | -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ -| | | | | | | |(2)| | | 2 | | | | | 2 | |(2)| | -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ - -Move 4 - Left Move 5 - Up Move 6 - Right Move 7 - Up -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ -| 4 | | | | | 8 | | | 4 | | | | 8 | 4 | | | | 8 | 8 | -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ -| 4 | | |(4)| | 4 | | | | | | | | 4 | | | | | 2 | -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ -| | | | | | | | | | | | | | | | | | | | -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ -| 4 | | | | |(2)| | | | |(2)| | | 2 | |(2)| | | | -+---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ -``` -This is how I lost this game: -``` -+---+---+---+---+ -| 4 | 2 | 16| 4 | -+---+---+---+---+ -| 32| 64| 8 | 2 | -+---+---+---+---+ -| 4 | 8 |128| 32| -+---+---+---+---+ -|(2)| 16| 8 | 4 | -+---+---+---+---+ -``` -Press Q at any time to bring up the option to Quit or Restart the game. - -# Network Boot - -# Xmodem Flash Updater - -The ROMWBW Xmodem flash updater provides the capability to update ROMWBW from the boot loader using an x-modem file transfer. It offers similar capabilities to Will Sowerbutts FLASH4 utility except that the flashing process occurs during the file transfer. - -These are the key differences between the two methods are: - -Xmodem Flash Updater | FLASH4 ---------------------------------|----------------- -Available from the boot loader | Well proven and tested -Xmodem transfer is integrated | Wider range of supported chips and hardware -Integrated checksum utilities | Wider range of supported platforms -Capability to copy a ROM image | Only reprograms sectors that have changed -More convenient one step process | Ability save and verify ROM images -No intermediate storage required | Progress display while flashing -. | Displays chip identification information -. | Faster file transfer - -The major disadvantages of the Updater is that it is new and relatively untested. There is the risk that a failed transfer will result in a partially flashed and unbootable ROM. There are some limitations on serial transfer speeds. - -The updater utility was initially intended to support the Retrobrew SBC-V2-005 platform using Atmel 39SF040 flash chips but has now been extended to be more generic in operation. - -Supported flash chips are -39SF040, 29F040, AT49F040, AT29C040, M29F040 , MX29F040, A29010B, A29040B - -The Atmel 39SF040 chip is recommended as it can erase and write 4Kb sectors. Other chips require the whole chip to be erased. - -## Usage - -In most cases, completing a ROM update is a simple as: - -1. Booting to the boot loader prompt -2. Selecting option X - Xmodem Flash Updater -3. Selecting option U - Update -4. Initiating an X-modem transfer of your ROM image on your console device -5. Selecting option R - Reboot - -If your console device is not able to transfer a ROM image i.e. your console is a VDU then you will have to use the console options to identify which character-input/output device is to be used as the serial device for transfer. - -When your console is the serial device used for the transfer, no progress information is displayed as this would disrupt the x-modem file transfer. If you use an alternate character-input/output devices as the serial device for the transfer then progress information will be displayed on the console device. - -Due to different platform processor speeds, serials speeds and flow control capabilities the default console or serial device speed may need to be reduced for a successful transfer and flash to occur. The **Set Console Interface/Baud code** option at the Boot Loader can be used to change the speed if required. Additionally, the Updater has options to set to and revert from a recommended speed. - -See the ROMWBW Applications guide for additional information on performing upgrades. - -## Console Options - -Option ( C ) - Set Console Device - -Option ( S ) - Set Serial Device - -By default the updater assumes that the current console is a serial device and that the ROM file to be flashed will also be transferred across this device, so the Console and Serial device are both the same. - -Either device can be can be change to another character-input/output device but the updater will always expect to receive the x-modem transfer on the **Serial Device** - -The advantage of transferring on a different device to the console is that progress information can be displayed during the transfer. - -Option ( > ) - Set Recommended Baud Rate - -Option ( < ) - Revert to Original Baud Rate - -## Programming options - -Option ( U ) - Begin Update - -The will begin the update process. The updater will expect to start receiving -an x-modem file on the serial device unit. - -X-modem sends the file in packets of 128 bytes. The updater will cache 32 -packets which is 1 flash sector and then write that sector to the -flash device. - -If using separate console, bank and sector progress information will shown - -``` -BANK 00 s00 s01 s02 s03 s04 s05 s06 s06 s07 -BANK 01 s00 s01 s02 s03 s04 s05 s06 s06 s07 -BANK 02 s00 s01 s02 s03 s04 s05 s06 s06 s07 etc -``` - -The x-modem file transfer protocol does not provide any filename or size -information for the transfer so the updater does not perform any checks -on the file suitability. - -The updater expects the file size to be a multiple of 4 kilobytes and -will write all data received to the flash device. A system update -file (128kb .img) or complete ROM can be received and written (512kb or -1024kb .rom) - -If the update fails it is recommended that you retry before rebooting or -exiting to the Boot loader as your machine may not be bootable. - -Option ( D ) - Duplicate flash #1 to flash #2 - -This option will make a copy of flash #1 onto flash #2. The purpose of this is to enable - making a backup copy of the current flash. Intended for systems using 2x512Kb Flash devices. - -Option ( V ) - Toggle Write Verify - -By default each flash sector will be verified after being written. Slight -performance improvements can be gained if turned off and could be used if -you are experiencing reliable transfers and flashing. - -## Exit options - -Option ( R ) - Reboot - -Execute a cold reboot. This should be done after a successful update. If -you perform a cold reboot after a failed update then it is likely that -your system will be unusable and removing and reprogramming the flash -will be required. - -Option ( Q ) - Quit to boot loader. - -The SBC Boot Loader is reloaded from ROM and -executed. After a successful update a Reboot should be performed. However, -in the case of a failed update this option could be used to attempt to -load CP/M and perform the normal x-modem / flash process to recover. - -## CRC Utility options - -Option ( 1 ) and ( 2 ) - Calculate and display CRC32 of 1st or 2nd 512k ROM. -Option ( 3 ) - Calculate and display CRC32 of a 1024k (2x512Kb) ROM. - -Can be used to verify if a ROM image has been transferred and flashed correctly. Refer to the Teraterm section below for details on configuring the automatic display of a files CRC after it has been transferred. - -In Windows, right clicking on a file should also give you a context menu option CRC SHA which will allow you to select a CRC32 calculation to be done on the selected file. - -## Tera Term macro configuration - -Macros are a useful tool for automatic common tasks. There are a number of instances where using macros to facilitate the update process could be worthwhile if you are: - -* Following the ROMWBW development builds. -* Doing lots of configuration changes. -* Doing development on ROMWBW drivers - -Macros can be used to automate sending ROM updates or images and for my own purposed I have set up a separate macro for transferring each of the standard build ROM, my own custom configuration ROM and update ROM. - -An example macro file to send an *.upd file, using checksum mode and display the crc32 value of the transmitted file: - -``` -Xmodem send, checksum, display crc32 -xmodemsend '\\desktop\users\phillip\documents\github\romwbw\binary\sbc_std_cust.upd' 1 -crc32file crc '\\desktop\users\phillip\documents\github\romwbw\binary\sbc_std_cust.rom' -sprintf '0x%08x' crc -messagebox inputstr 'crc32' -``` - -## Serial speed guidelines - -As identified in the introduction, there are limitations on serial speed depending on processor speed and flow control settings. Listed below are some of the results identified during testing. - -Platform / Configuration | Processor Speed | Maximum Serial Speed --------------------------------|-----------------|--------------------- -SBC-V2 UART no flow control | 2mhz | 9600 -SBC-V2 UART no flow control | 4mhz | 19200 -SBC-V2 UART no flow control | 5mhz | 19200 -SBC-V2 UART no flow control | 8mhz | 38400 -SBC-V2 UART no flow control | 10mhz | 38400 -SBC-V2 USB-FIFO 2mhz+ | | n/a -SBC-MK4 ASCI no flow control | 18.432mhz | 9600 -SBC-MK4 ASCI with flow control | 18.432mhz | 38400 - -The **Set Recommend Baud Rate** option in the Updater menu follows the following guidelines. - -Processor Speed | Baud Rate -----------------|---------- -1Mhz | 4800 -2-3Mhz | 9600 -4-7Mhz | 19200 -8-20Mhz | 38400 - -These can be customized in the updater.asm source code in the CLKTBL table if desired. -Feedback to the ROMWBW developers on these guidelines would be appreciated. - -## Notes: -- All testing was done with Teraterm x-modem, Forcing checksum mode using macros was found to give the most reliable transfer. -- Partial writes can be completed with 39SF040 chips. Other chips require entire flash to be erased before being written. -- An SBC V2-005 MegaFlash or Z80 MBC required for 1mb flash support. The Updater assumes both chips are same type -- Failure handling has not been tested. -- Timing broadly calibrated on a Z80 SBC-v2 -- UNA BIOS not supported diff --git a/Source/Doc/ReadMe.md b/Source/Doc/ReadMe.md index 61783118..4207fd78 100644 --- a/Source/Doc/ReadMe.md +++ b/Source/Doc/ReadMe.md @@ -114,7 +114,6 @@ Documentation for $doc_product$ includes: * $doc_user$ * $doc_sys$ * $doc_apps$ -* $doc_romapps$ * $doc_errata$ # Acknowledgments diff --git a/Source/Doc/UserGuide.md b/Source/Doc/UserGuide.md index 7ee5d871..9021c0b4 100644 --- a/Source/Doc/UserGuide.md +++ b/Source/Doc/UserGuide.md @@ -11,11 +11,8 @@ companion documents you should refer to as appropriate: of RomWBW. It includes a reference for the RomWBW HBIOS API functions. -* $doc_romapps$ is a reference for the ROM-hosted applications provided - with RomWBW including the monitor, programming languages, etc. - -* $doc_apps$ is a reference for the OS-hosted proprietary command - line applications that were created to enhance RomWBW. +* $doc_apps$ is a reference for the ROM-hosted and OS-hosted applications + created or customized to enhance the operation of RomWBW. * $doc_catalog$ is a reference for the contents of the disk images provided with RomWBW. It is somewhat out of date at this time. @@ -391,7 +388,7 @@ At the Boot Loader prompt, you can type `H ` for help. You can type `L ` to list the available built-in ROM applications. If your terminal supports ANSI escape sequences, you can try the 'P' command to play a simple on-screen game. Instructions for the -game are found in $doc_romapps$. +game are found in $doc_apps$. If all of this seems fine, your ROM has been successfully programmed. See the [Boot Loader Operation] section of this document for further @@ -645,7 +642,7 @@ return to the Boot Loader menu. If you are interested in creating a custom application to run here, review the "usrrom.asm" file in the Source/HBIOS folder of the distribution. -Each of the ROM Applications is documented in $doc_romapps$. Some +Each of the ROM Applications is documented in $doc_apps$. Some of the applications (such as BASIC) also have their own independent manual in the Doc directory of the distribution. The OSes included in the ROM (CP/M 2.2 & Z-System) are described in the Operating Systems diff --git a/Source/Images/hd_bp.txt b/Source/Images/hd_bp.txt index 58f88d7e..789683f9 100644 --- a/Source/Images/hd_bp.txt +++ b/Source/Images/hd_bp.txt @@ -40,6 +40,7 @@ ../../Binary/Apps/vgmplay.com 15: # ../../Binary/Apps/Test/*.com 2: +../../Binary/Apps/Test/*.doc 2: Test/*.* 2: # # Add Tune sample files diff --git a/Source/Images/hd_cpm22.txt b/Source/Images/hd_cpm22.txt index a2f7f94e..8d60965b 100644 --- a/Source/Images/hd_cpm22.txt +++ b/Source/Images/hd_cpm22.txt @@ -36,6 +36,7 @@ d_cpm22/ReadMe.txt 0: ../../Binary/Apps/vgmplay.com 0: # ../../Binary/Apps/Test/*.com 2: +../../Binary/Apps/Test/*.doc 2: Test/*.* 2: # # Add Tune sample files diff --git a/Source/Images/hd_cpm3.txt b/Source/Images/hd_cpm3.txt index ba8383bd..1772d2fa 100644 --- a/Source/Images/hd_cpm3.txt +++ b/Source/Images/hd_cpm3.txt @@ -52,6 +52,7 @@ ../../Binary/Apps/vgmplay.com 0: # ../../Binary/Apps/Test/*.com 2: +../../Binary/Apps/Test/*.doc 2: Test/*.* 2: # # Add Tune sample files diff --git a/Source/Images/hd_nzcom.txt b/Source/Images/hd_nzcom.txt index bdcdad1c..356a5fe7 100644 --- a/Source/Images/hd_nzcom.txt +++ b/Source/Images/hd_nzcom.txt @@ -53,6 +53,7 @@ d_zsdos/u0/*.* 0: ../../Binary/Apps/vgmplay.com 0: # ../../Binary/Apps/Test/*.com 2: +../../Binary/Apps/Test/*.doc 2: Test/*.* 2: # # Add Tune sample files diff --git a/Source/Images/hd_qpm.txt b/Source/Images/hd_qpm.txt index f8fc8e85..98434857 100644 --- a/Source/Images/hd_qpm.txt +++ b/Source/Images/hd_qpm.txt @@ -40,6 +40,7 @@ d_cpm22/u0/*.* 0: ../../Binary/Apps/vgmplay.com 0: # ../../Binary/Apps/Test/*.com 2: +../../Binary/Apps/Test/*.doc 2: Test/*.* 2: # # Add Tune sample files diff --git a/Source/Images/hd_zpm3.txt b/Source/Images/hd_zpm3.txt index 1532cb55..5f5c0615 100644 --- a/Source/Images/hd_zpm3.txt +++ b/Source/Images/hd_zpm3.txt @@ -51,6 +51,7 @@ ../../Binary/Apps/vgmplay.com 15: # ../../Binary/Apps/Test/*.com 2: +../../Binary/Apps/Test/*.doc 2: Test/*.* 2: # # Add Tune sample files diff --git a/Source/Images/hd_zsdos.txt b/Source/Images/hd_zsdos.txt index 9dc1dcda..1c7fe895 100644 --- a/Source/Images/hd_zsdos.txt +++ b/Source/Images/hd_zsdos.txt @@ -49,6 +49,7 @@ d_cpm22/u0/XSUB.COM 0: ../../Binary/Apps/vgmplay.com 0: # ../../Binary/Apps/Test/*.com 2: +../../Binary/Apps/Test/*.doc 2: Test/*.* 2: # # Add Tune sample files diff --git a/Source/ver.inc b/Source/ver.inc index 15761e84..b18648e3 100644 --- a/Source/ver.inc +++ b/Source/ver.inc @@ -2,7 +2,7 @@ #DEFINE RMN 5 #DEFINE RUP 0 #DEFINE RTP 0 -#DEFINE BIOSVER "3.5.0-dev.51" +#DEFINE BIOSVER "3.5.0-dev.52" #define rmj RMJ #define rmn RMN #define rup RUP diff --git a/Source/ver.lib b/Source/ver.lib index 592b3bb4..69fc0e06 100644 --- a/Source/ver.lib +++ b/Source/ver.lib @@ -3,5 +3,5 @@ rmn equ 5 rup equ 0 rtp equ 0 biosver macro - db "3.5.0-dev.51" + db "3.5.0-dev.52" endm