by Richard F. Drushel (drushel@apk.net)
Per Dale Wick's request from ADAMcon 0Ch almost a month ago, I have finished collecting all of the various sources for my ADAMserve serially- linked device driver software. This includes the x86 assembler source for the PC-side server, and the Z80 assembler source for ADAMserve boot, EOS, HARDDISK, and File Manager. The purposes for this collection are (1) to make sure it doesn't get lost, and (2) to put it on an ADAM software CD that Dale's brother Neil is reportedly working on.
As of last Sunday, I had located almost everything I needed, and put it all into various ZIP files. One item that I couldn't seem to find, however, was the source for the HARDDISK boot block. I remembered that it had been modified from an old, pre-ADAMserve version , so I figured that I could just regenerate it and compare the new binary against the old, to be sure that I hadn't made any mistakes. A few hours I thought it would take...
Well, I didn't get a few free hours until this evening, a week later. And after finally making a stand-alone .ASM file, I remembered that the "source" for the HARDDISK boot was present in the HARDDISK binary all along! Original HARDDISK author Tony Morhen liked to write programs which could create their own boot disk images, boot block, directory, and all. Since the ADAMserve version of HARDDISK was descended from Tony's original source, it still had this feature...so, sheepishly I must admit that my new boot .ASM program was superfluous...and so all the source code ought to be ready to send off to Dale.
*Ought*...but I realized that there were no "help" texts to go along with the source code...and some of it is a little hairy, because it prompts for configuration options. So, I started to write the README files...and it took me 5 hours to do it :-(
This isn't what I wanted to talk about in TWWMCA this week, but it's now very late, I need to get this out, and here is a pile of ADAM-related text. So, here it is :-) It is, of course, most useful if you are sitting with the various sources mentioned in front of you; but there is lots of useful by-the- way info about usage and program design, so I guess it will be of enough general interest. If not, oh well...
README72.TXT help file for ADAMserve 72 READMESV.TXT information about SERVE72x.ASM source code for PC server READMEBO.TXT information about ADAMserve boot disk images READMESB.TXT help file for sources to the ADAMserve boot block READMEOS.TXT information about the source code for ADAMserve EOS READMEHD.TXT information about the sources for ADAMserve HARDDISK 4.203 READMEFM.TXT help file for sources for ADAMserve File Manager 4.1
by Richard F. Drushel
drushel@apk.net
13 August 2000
ADAMserve requires (minimum) an XT-class PC with 256K RAM, two 180K floppy disk drives, a serial port, a 20MB hard disk, and MS-DOS 2.0. A parallel port is required if you wish to bypass printing to the ADAM printer.
ADAMserve is known to run perfectly under Windows 95, Windows 98, OS/2 2.1 and 3.0 Warp. ADAMserve runs in a limited fashion under Windows NT 4.0: the ADAMserve hard disk can be accessed over the serial link, but PC floppy disk I/O is completely blocked. As of this writing, ADAMserve has not been tested under Windows ME or Windows 2000.
Connect the PC serial port to the ADAM serial port using a null modem cable. An RS-232 line tester with status LEDs is a good item to put in-line, because it can help you debug cabling problems. It is probably best to test the null modem connection using PC and ADAM telecommunications programs (e.g., ProComm, Telix, IMP, ADAMlink) *first*, before trying to run ADAMserve. If you can type at one keyboard and see characters on the other screen, and vice versa, then the serial link is working; if not, ADAMserve won't work.
Start the PC side of ADAMserve before booting the ADAM. The PC file is called SERVE72x.EXE, where x specifies the PC floppy mapping and PC serial port to be used:
x date A: B: serial A 9609.02 1440K 1200K COM1: B 9609.02 1440K 1200K COM2: C 9609.02 320K 320K COM2: D 9609.02 1200K 1200K COM2: E 9609.02 320K 720K COM2: F 9609.02 1200K 1440K COM2: G 9609.08 720K 320K COM2:
You can use the startup command line option /B to run in monochrome mode; default is color (black and cyan).
You should put ADAMserve into its own directory, e.g., C:\ADAMSERVE. Make sure that the two EOS hard disk image files EOSHD0.DSK and EOSHD1.DSK are present in this directory.
You must have the following line in your CONFIG.SYS file when you boot your PC:
DEVICE=C:\DOS\ANSI.SYS (or whatever path leads to ANSI.SYS)
Ignore the "File not found" error message at startup; it is from an as-yet- unimplemented configuration file feature.
ADAMserve requires (minimum) a stock ADAM with one tape drive and a third- party serial board (Eve, Orphanware, or Micro Innovations). A full printer/ power supply is necessary if you wish to print to the ADAM printer; otherwise, you may use a bare power supply and redirect printing to a PC parallel printer.
After the PC side of the server is running, put the ADAMserve boot tape/disk into any drive and pull the reset switch.
ADAMserve has built-in drivers for all third-party serial boards. However, you must configure your boot tape/disk to specify which serial port you are using for ADAMserve.
Block 0 boot of the ADAMserve boot disk has a reserved byte to specify the server serial baseport. Offset 2 (0-based) has one of following values:
44h Orphanware port 68 4Ch Orphanware port 76 54h Orphanware port 84 5Ch Orphanware port 92 18h MIB2 port 1 10h MIB2 port 2
Boot disk images are provided for all 6 serial baseports. However, you can use a block-editing utility like File Manager to change the baseport byte if you wish.
The ADAMserve boot will load HARDDISK from the boot tape/disk. Once HARDDISK is running, you can use it to launch programs from the hard disk or from tapes or (PC) floppy disks. For example, to run a program stored on Volume 5, change the Logical Drive to 5, then select "Boot From Hard Disk". From the menu of boot blocks, select the appropriate boot block. Your application will then run. To boot from an external drive, insert the tape/disk, then select "Boot Software" and select the appropriate drive.
From application programs, you can change the current Logical Drive of the hard disk by typing Shift-Tab (hold down both keys at once). You will hear a beep, then the current Logical Drive will be advanced by one (9 wraps back to 0).
To return to HARDDISK from any application, type Shift-Undo (hold down both keys at once). This reboots HARDDISK from the server hard drive.
The ADAMserve server program accepts the following function keys:
<escape>
flushes the server receive buffer (may be useful after an I/O error). C/c ADAMcalc 'fudge'. Performs proper page eject when printing with either serial printer or "other" printer (parallel printer) in ADAMcalc. P/p PowerPaint 'fudge'. Ignores the hiword of block number (necessary for PowerPaint disk I/O). Q/q quits to DOS.
The two 'fudges' are toggles: repeated typing turns them on and off. You should use the appropriate toggle before launching either ADAMcalc or PowerPaint from HARDDISK.
Note that status information is displayed: blocks being read or written, and any error messages.
Instructions for assembling both the PC and ADAM source code for ADAMserve are given in the respective ZIP archives containing the source.
A small wrinkle seems to exist in the 1200K server floppy disk I/O: sometimes it can't read a 1200K disk correctly if it's the very first disk ADAMserve reads after it's started. If you read from a 160K or 320K floppy disk *first*, all subsequent attempts to read any 1200K disks are successful, regardless of whether you mix/match 160K/320K/1200K disks subsequently.
The ADAM printer emulator to parallel printer does not support underline printing from SmartWriter.
ADAM software which attempts to do raw ADAMnet I/O (by directly manipulating device control blocks), or does block I/O at levels below _READ_1_BLOCK, will not work with ADAMserve, due to incomplete ADAMnet emulation. Such software can often be patched, however, to be "better behaved". If you find such software, please let me know, and maybe I can patch it.
by Richard F. Drushel
drushel@apk.net
13 August 2000
The following x86 code files are necessary to build the PC server for ADAMserve, using Borland's Turbo Assembler, TASM.EXE (or equivalent):
SERVE72x.ASM x=A,B,C,D,E,F,G (different floppy/serial port mixes) DATA_31x.ASM x=A,B,C,D,E,F,G CON_IO.ASM keyboard/screen FILE_IO.ASM DOS filesystem SER_IO4.ASM low-level serial port BLK_IO61.ASM block devices FDD_IO2.ASM low-level floppy disk CHAR_IO.ASM character devices TOGGLE_1.ASM ADAMcalc and PowerPaint toggle handlers SETUP_2.ASM configuration module (skeleton only)
To assemble the server, type
TASM SERVE72X SERVE72X SERVE72X
at the MS-DOS prompt. Unlike Z80ASM+, TASM.EXE creates only object files; a separate linker program, TLINK.EXE, must be run to create the final SERVE72x.EXE application. Thus, after running TASM.EXE, type
TLINK SERVE72X
It is unknown whether SERV72x can assemble correctly under the MASM assembler. The source currently doesn't use any TASM-specific tricks that I know of.
The various low-level hardware I/O routines, while perfectly acceptable in MS-DOS, may become increasingly useless as later Windows operating systems restrict direct hardware access, or imperfectly emulate it. For instance, while SERVE72x works perfectly well under Windows 98, the floppy disk I/O code does not work under Windows NT 4.0. Windows-specific development tools will be necessary at some point.
The most annoying feature of ADAMserve is that the PC side is not runtime- configurable by the user, rather relying upon special separately-assembled code bases to change serial port or combination of disk drives. This is mostly due to not wanting to write a menu interface in assembler, and not having given enough thought to how to write one in a higher-level language (e.g., C or QuickBASIC) and linking it in with the nuts-and-bolts assembly code.
by Richard F. Drushel
drushel@apk.net
13 August 2000
The following 160K disk images are provided for booting ADAMserve:
ASBOOT16.IMG Micro Innovations port 2 ASBOOT24.IMG Micro Innovations port 1 ASBOOT68.IMG Eve/Orphanware port 44H ASBOOT76.IMG Orphanware port 4CH ASBOOT84.IMG Orphanware port 54H ASBOOT92.IMG Orphanware port 5CH
These images are identical except for the serial baseport byte at offset 2 (0-based). They contain:
the ADAMserve boot block
the ADAMserve HARDDISK boot block
ADAMserve HARDDISK 4.203
EOS4.0
EOS4.X
File Manager 4.1
These images may be cloned to actual 160K disks using the appropriate TDOS program, CLONE.COM. They could also be block-copied onto disks starting from block 0, using File Manager and a source medium which is bigger than 160K. Only the first 47 blocks (blocks 0-46) actually have data on them, however, so it is possible to transfer less than the full 160 blocks. Though disk images, they may also be copied to tape for boot purposes; ADAMserve won't care.
For complete instructions, see README72.TXT.
by Richard F. Drushel
drushel@apk.net
13 August 2000
The following source code files are necessary to build the ADAMserve block 0 boot program:
SBOOT20.ASM main boot code SBOOT20A.ASM special version for inclusion in HARDDISK SIOINI32.ASM code to initialize serial ports
To assemble the ADAMserve boot block, type
Z80ASM+ SBOOT20.ASM
(Note: if you are using a CP/M emulator under MS-DOS, you will have to change the name of the assembler to Z80ASMP, because '+' is an invalid filename character in MS-DOS.)
The resulting 1K binary file must be block-copied to block 0 of the boot tape/ disk.
The ADAMserve boot block has built-in drivers for all third-party serial boards. However, you must configure your boot tape/disk to specify which serial port you are using for ADAMserve.
Block 0 boot of the ADAMserve boot disk has a reserved byte to specify the server serial baseport. Offset 2 (0-based) has one of following values:
44h Orphanware port 68 4Ch Orphanware port 76 54h Orphanware port 84 5Ch Orphanware port 92 18h MIB2 port 1 10h MIB2 port 2
Boot disk images are provided for all 6 serial baseports. However, you can use a block-editing utility like File Manager to change the baseport byte if you wish. You may also reassemble from source, changing the default value of the baseport.
The ADAMserve boot block loads the HARDDISK boot block and passes control to it. See the documentation for the ADAMserve HARDDISK source for information on how to construct an entire ADAMserve boot disk.
by Richard F. Drushel
drushel@apk.net
13 August 2000
ADAMserve EOS is based largely upon the EOS-7 codebase (rather than the EOS-6 version present in ROM of every production ADAM I've ever seen), because EOS-7 is much smaller than EOS-6, and code space is at a premium: EOS cannot extend below 0E000H in RAM. The source for EOS-7 is the original .LST which was derived from the SmartBASIC 2.0 distribution. While this code is the original code, with the original symbols, it was stripped of comments. Any comments now found in the code are my own addition; but I have only commented those places where it was relevant to ADAMserve.
The following source code files are necessary to build the two ADAMserve EOS binaries:
EOS551.ASM most of EOS EOSIO453.ASM ADAMserve protocol handshaking module
To assemble ADAMserve EOS, type
Z80ASM+ EOS551.ASM
(Note: if you are using a CP/M emulator under MS-DOS, you will have to change the name of the assembler to Z80ASMP, because '+' is an invalid filename character in MS-DOS.)
The binary file known as EOS4.0(^B), where (^B) is Control-B, CHR$(2), is the "standard" ADAMserve EOS. The binary file known as EOS4.X(^B) is a "special" version with some bugfixing code to allow ADAMcalc and SmartLOGO to function correctly with ADAMserve. ADAMserve HARDDISK has code to detect if either ADAMcalc or SmartLOGO is being launched, and will load in the special EOS4.X version before running them. A soft reboot with Shift-Undo causes the normal EOS4.0 version to loaded before returning to HARDDISK.
In the .LST files provided, EOS551.LST corresponds to EOS4.0, and EOS551A.LST corresponds to EOS4.X.
There are a number of assembly-time prompts for user input. Some are to enable debugging code; some are to enable functions that there is not enough RAM available for; and some are to select between 2 different final versions of the EOS binary. Here are the prompts and the required responses:
RAMdisk code? FALSE (no room for code) Shift-Wildcard 64K RAM dump? FALSE (debugging) Enter amount of pre-pad: 0 for both 4.0 and 4.X (may be needed to pad code forward so that current hard disk volume and volume offset table are at the required reserved RAM addresses) Assemble for EOS? TRUE (FALSE creates a BLOAD file for SmartBASIC) Check for overrun/framing/parity errors? FALSE (no room for code) Assemble special ADAMcalc/SmartLOGO EOS? FALSE for 4.0, TRUE for 4.X Enter amount of post-pad: 0 for 4.0, 5 for 4.X (may be required to pad code forward so that EOS jump table is at the required reserved RAM address)
The files EOS4.0 and EOS4.X must be copied to both the ADAMserve boot disk and Volume 0 of the ADAMserve hard disk.
by Richard F. Drushel
drushel@apk.net
13 August 2000
The following files are needed to build ADAMserve HARDDISK 4.203 (using the Z80ASM+ assembler from SLR, or equivalent):
HD4203.ASM S-SPEC2.Z80 DATA5.Z80 SPATCH.Z80 1ST2BLK5.ASM SBOOT20A.ASM SIOINI32.ASM
To assemble HARDDISK, type
Z80ASM+ HD4203.ASM
(Note: if you are using a CP/M emulator under MS-DOS, you will have to change the name of the assembler to Z80ASMP, because '+' is an invalid filename character in MS-DOS.)
There are macro prompts for input parameters (leftovers from the original ability to build all possible versions of HARDDISK for different hard disk controllers from a single source). You should type FALSE for everything except the SERVER? prompt, at which you should type TRUE.
NOTE: the output is an 11-block binary image of a 160K disk, HD4203.BIN. (This also is a leftover from Tony Morehen's original code, which spit out an entire boot disk image.) Block 0 is the HARDDISK BOOT block; block 1 is a DIRECTORY, and blocks 2-10 are the actual HARDDISK program.
To make an ADAMserve boot disk, you must
copy the ADAMserve boot code to block 0 of the disk
copy the HARDDISK BOOT code to a file named SERVBOOT2(^B), where (^B) is Control-B, CHR$(2)
copy the HARDDISK program code to a file named HARDDISK(^B)
copy the 2 special versions of EOS to files named EOS4.0(^B) and EOS4.X(^B).
If you are wise, you will also
copy ADAMserve File Manager (FILEMAN(^B)) to the boot disk; you may need it some day for disaster recovery!
The easiest way to do this is to get all the pieces onto EOS media as separate files, and then use File Manager to do the block and file copying. Getting the pieces onto EOS media can be a job in itself, especially if you are using an MS-DOS development environment. XMODEM transfer from PC to ADAM using your favorite terminal programs will work adequately.
Other README files describe how to assemble the ADAMserve boot block and the 2 versions of EOS.
Volume 0 block 0 of the ADAMserve hard drive must contain the contents of the SERVBOOT2 file. Additionally, volume 0 must also contain the files HARDDISK, EOS4.0, and EOS4.X. Since Volume 0 of all EOS hard disks is in a very fragile state (with many programs which are at specific blocks and which must remain at those specific blocks in order to function correctly), it is not wise to use file copying methods to install these files from binary images. Assuming that you already have a working ADAMserve hard drive, just block copy onto the necessary pre-occupied blocks. HARDDISK on Volume 0 is set to occupy 12 blocks (despite having only 9K of code currently); *do not change this*.
For development purposes in an MS-DOS environment, I have used QuickBASIC programs to copy binaries from files to the proper positions in the 10 MB EOS hard disk image. These are not "intelligent" programs, as they don't read the directory to find out where to copy the files to; for simplicity they just assume that the files are at certain locations and block copy to the appropriate offsets. If someone wants to write these general-purpose utility programs, please go ahead :-)
You can't yet write an ADAMserve BOOT disk/tape from the menu.
'Krunch' works, but *don't* use it on Volume 0, for the reasons described above. (This caveat applies to *all* versions of HARDDISK, for *any* hardware.)
Similarly, *don't* 'Init' Volume 0!
The logical-to-physical device table can't be edited yet, except for toggling between a genuine ADAM printer and emulating it on a PC-connected parallel printer. Thus, both disk drives are mapped to the PC; ADAMserve can't see a real ADAMnet disk drive. Implementing the remapping menu would be my first project for additional work on ADAMserve HARDDISK.
by Richard F. Drushel
drushel@apk.net
13 August 2000
ADAMserve File Manager was completely reverse-engineered from the File Manager 4.0 binary. All hard-coded device dependencies were removed; all devices are accessed at the EOS level, not at the ADAMnet device control block level. Thus, ADAMserve File Manager should work perfectly well with all Coleco and third-party disks, including Mini Wini and IDE hard disks.
The following source files are required to assemble ADAMserve File Manager 4.1:
FM023.ASM application FM4BOOT.ASM block 0 boot, for making a stand-alone disk
TO assemble File Manager, type
Z80ASM+ FM023.ASM
(Note: if you are using a CP/M emulator under MS-DOS, you will have to change the name of the assembler to Z80ASMP, because '+' is an invalid filename character in MS-DOS.) To assemble the boot block, type
Z80ASM+ FM4BOOT.ASM
The resulting binaries must be copied to tape/disk for use. FILEMAN(^B), where (^B) is Control-B, CHR$(2), is the accepted name for File Manager. It may be file-copied to any desired destination. The boot block image, however, must be block-copied to block 0 of the desired tape/disk.
NOTE: On the ADAMserve hard drive, the Volume 0 copy of FILEMAN should *only* be updated by block-copying onto the existing image. There is a bug in the file launcher of HARDDISK which limits the display of launchable programs to only one screen's worth. If there are too many entries, you cannot page down to another screen. FILEMAN is *always* something you want to be able to launch, so it occupies a top position in the directory listing. If you move it to the end, you may not be able to see it some day, if your Volume 0 fills up with too many application software boot blocks.
A long-standing bug in File Manager was that the entire number of blocks of a tape/disk could not be copied in one pass, because of an off-by-one error in the block counter. This has been fixed in ADAMserve File Manager.
The FORMAT menu merely gives the MS-DOS FORMAT command switches necessary to create disks of the desired size. Since the disk formatting protocol of ADAMserve has not been specified implemented, there is no way currently to format disks from within ADAMserve.
See you again next week!
*Rich*
Next Article
Previous Article
TWWMCA Archive Main Page