PC-SERIAL-LOADER -- README.TXT ============================== == Table of contents == 1. Overview 2. Package contents 3. Hardware setup 4. About the initial loader 5. About the toolbox 6. About the toolbox client 6.1 Overview 6.2 Main menu bar 6.3 Connecting to the target 6.4 Disk drive information 6.5 Drive editor 6.6 Read image 6.7 Write image 6.8 Explore 6.9 Receive file 6.10 Send file 6.11 Delays and timeouts 6.12 Flow control 7. About the fat12-resize tool 8. Advanced topics 8.1 Changing the baud rate 8.2 Changing the port 8.3 Changing the second stage address 9. Miscellaneous hints 9.1 Creating bootable media 10. Contact == 1. Overview == The PC serial loader package is meant to be used with "old" PCs that are cut off from the modern world, e.g. because of using removable media that isn't supported anymore (like 5.25 inch floppy disks), or not having access to removable media in the first place (e.g. because of a broken floppy drive). It does so by transferring data via a RS232 port using a null modem cable. The only software that needs to be present on the target PC is the initial loader, which has a size of about 50 bytes which can be keyed in on the MS-DOS prompt using standard tools present in every MS-DOS installation. After the initial loader is started, the host PC (running Windows 95/98/NT or later) transfers a "toolbox" image to the target, which is stored in RAM and executed. The toolbox contains code for more advanced features like reading and writing files or disk images. These features are controlled using the toolbox client program which runs on the host PC and thereby should have access to any modern media including the internet. == 2. Package contents == pc-serial-loader +-- readme.txt Documentation (this file) +-- target | +-- initld.com Initial loader program | +-- initld.txt Assembly listing of loader program for keying in | +-- toolbox.bin Toolbox image to be transferred to target +-- client | +-- toolbox-client.exe Toolbox client program (GUI) +-- tools +-- fat12-resize.exe Tool for resizing FAT12 disk images (console) == 3. Hardware setup == For communicating with the target a null modem cable is needed. This is a serial cable with two female connectors and crossed lines for RxD/TxD, RTS/CTS and DSR/DTR. Such cables are available as finished products for about 5 to 10 EUR, but can also easily be made from two regular serial cables by cutting each of them into two pieces and reconnecting the two pieces with the female connectors, crossing the lines as required (Frankenstein cable). Target PC Host PC Line | DE-9 | DB-25 Line | DE-9 | DB-25 -----|------|------ -----|------|------ RxD | 2 | 3 <---------------------- TxD | 3 | 2 TxD | 3 | 2 ----------------------> RxD | 2 | 3 DTR | 4 | 20 ----------------------> DSR | 6 | 6 DSR | 6 | 6 <---------------------- DTR | 4 | 20 RTS | 7 | 4 ----------------------> CTS | 8 | 5 CTS | 8 | 5 <---------------------- RTS | 7 | 4 Note: the lines for hardware flow control are not actually used, but must have specific levels for the initial loader and toolbox to work (to be more precise: to use the int 14h BIOS functions). If you feel adventurous, you can tie the target's pins for DSR and CTS to +12V and omit the lines in the cable. In case the host PC doesn't have a RS232 port, an additional USB-to-RS232 converter is needed, which costs about 10 EUR as well. From my personal experience I recommend using the adapters from LogiLink, but be careful to buy one supported by your operating system. The model AU0002B is older and works fine with Windows 7, while the newer model AU0034 seems to work with Windows 8 and later only. == 4. About the initial loader == The initial loader (initld.com) is the program which is started on the target, allowing the host PC to send more data. It consists of about 25 assembler instructions and takes up about 50 bytes. The initial loader takes the data it receives on the serial port, writes it into a memory location and calls it as a function, thereby executing the newly received program which I call a "second stage program". This second stage program could be the toolbox image which is part of this package, but could be anything else as well. The initial loader passes the index of the COM port which was used as a word on the stack to the second stage program for further communication. After the second stage has returned, the register AL is checked. If it contains a zero the initial loader starts over, waiting for the next second stage program. If it contains any other value, the initial loader returns to the DOS prompt with that value as an exit code. To get this initial loader onto a PC with nothing else but a DOS installation (or even boot disk), you can use the built-in "echo" command with redirecting the output into a file: | | C:\>echo 12345678 > file.com | To create all characters from the 8-bit ASCII alphabet, press and hold the ALT key, enter the decimal code of the character using the numeric key pad, then release the ALT key. Don't be scared by the awkward look of the characters, they do work (unless a very few special characters which I avoided to use). The decimal values can be found in the last column of the listing file (initld.txt), which is part of this package. Do not use quote characters around the character string; at least MS-DOS 3.3 takes them literally and thereby alters the code of the initial loader! Note: you might notice that the binary is 2 bytes longer than the amount of characters you keyed in. That is the CRLF line terminator that is appended automatically. This isn't a problem, because it is located after the exit command of the initial loader and thus is never reached. == 5. About the toolbox == The toolbox image contains another assembler program which provides functions for manipulating the target. Beside some administrative commands, there are means to read/write floppy disk images and to read/write/list files. The toolbox and the toolbox client communicate via the null modem connection and use a simple request/response based protocol. Beside downloading the toolbox image to the target in the beginning of the session, you shouldn't have to worry about this component at all. However, there are a few quirks concerning the download you should know: - The initial loader doesn't know about the toolbox protocol, if you start sending toolbox commands before the toolbox is started, bad things might happen (e.g. taking the commands, treating the data as program code and executing it with hard to predict consequences). - The toolbox client by now has no reliable way to check if there is a toolbox present, except for sending commands and waiting for reply. So you as a user need to keep track of whether a toolbox is running or not. - The toolbox protocol and its implementation aims for simplicity, not robustness. When leaving the predefined path by suddenly disrupting the communication or injecting unexpected data, the toolbox might hang up or do stupid things. - You should not cancel the toolbox download. The initial loader interprets a stop of incoming data as end of transmission and will start execution of the incomplete program image. Again, when just using the toolbox client and not fiddling around with the cable while communicating, everything should be okay and you will probably never take notice of the thing called toolbox. == 6. About the toolbox client == 6.1 Overview The toolbox client is the main user interface and contains most of the logic. It is a Win32 GUI application that provides convenient access to all functions the toolbox provides. The basic functions for setting up the session are available via the main menu bar. All other functions are accessed via the controls of the main dialog window. Controls with an ellipsis ("...") indicate that a sub dialog will open to query further information. Settings are stored in the Windows registry under the following key: HKEY_CURRENT_USER\SOFTWARE\Zotteljedi\toolbox-client 6.2 Main menu bar The File menu is used to manage the connection to the target. File +-- Connect... Connects to the target +-- Disconnect Closes an existing connection +-- Exit Exits the program The Toolbox menu is used to download and manage the toolbox on the target. Toolbox +-- Download to target... Downloads a toolbox image to the target +-- Query version number Shows the version number of the target's toolbox +-- Exit to loader Lets the toolbox return to the initial loader +-- Exit to system Lets the toobbox return to the DOS prompt The Tweaks menu contains functions for fine-tuning and working around issues. Tweaks +-- Drive editor... Editor to manually modify detected disk drives +-- Delays and timeouts... Settings for artifical delays (for slow targets) +-- Flow control... Settings for serial port hardware flow control The Help menu provides basic information about the application. Help +-- About Shows information about the toolbox client 6.3 Connecting to the target Connecting to the target opens a sub dialog which asks for the following connection parameters: - Port - Baud rate - Data bits - Parity - Stop bits The port can be selected from a list. This list is updated each time the connect sub dialog opens, e.g. it won't show new hardware that becomes available while the dialog is already open. The baud rate is limited to the baud rates supported by the int 14h functions the toolbox uses and ranges from 110 to 9600 baud. Note: to change the baud rate on the target, you have to manipulate the initial loader. See section 8.1 Changing the baud rate for details. For data bits, parity and stop bits you should use the defaults, which are 8 data bits, no parity and 1 stop bit. 6.4 Disk drive information When pressing the "Detect drives" button, the toolbox client queries information about the first 4 drives on the target and updates the dropdown combobox accordingly. For each drive there is information displayed about: - Type - Number of tracks - Number of sides - Number of sectors per track This information is obtained using an int 13h BIOS function. Note: for drives which are not present in the target the values are random. It seems that there is no reliable way to tell if the result is valid or not. In case your BIOS does not return proper values, consider using the drive editor as a workaround. 6.5 Drive editor The drive editor allows manual modification of the disk drive list. This allows using the toolbox client even in cases where the target's BIOS does not enumerate the disk drives properly. The information entered via the drive editor is not saved persistently and must be re-entered every time the toolbox client is started again. The editor allows three basic operations: - Adding a new drive (up to 4 drives in total) - Editing an existing drive entry - Removing an existing drive entry Changes are applied to the main drive list only when leaving the editor by pressing the "OK" button. For each drive the following parameters can be entered: - Index 0 = A:, 1 = B: - Type Selected from dropdown combobox - Number of tracks 0 to 255, see table below - Number of sides 0 to 255, see table below - Number of sectors per track 0 to 255, see table below The number of tracks, sides and sectors per track must match the target drive's geometry. For the regular drive types the values are: Type | Tracks | Sides | Sectors ------|--------|-------|-------- 360K | 40 | 2 | 9 1.2M | 80 | 2 | 15 720K | 80 | 2 | 9 1.44M | 80 | 2 | 18 Note: the disk drive type has an effect on the media descriptor value being used when resizing a disk image using FAT12 header modification. In all other cases the selected type does not matter. 6.6 Read image When pressing the "Read image..." button, a save file dialog opens and prompts you to select a file. Then the currently selected drive is read sector by sector and the image is stored in the previously selected file. During this process a progress dialog is shown. The image format is: | | for (track = 0; track < track_count; track++) | for (side = 0; side < side_count; side++) | for (sector = 0; sector < sector_count; sector++) | read_sector(track, side, sector); | Each sector has 512 bytes and is written to the image file as raw data. Such images can be read by DOSBox and also match the typical "raw" format used by other imagers. 6.7 Write image When pressing the "Write image..." button, an open file dialog opens and prompts you to select a file. Then the file is written sector by sector to the currently selected drive. During this process a progress dialog is shown. If the selected image file does not match the target drive's capacity, a dialog asking for resizing options is shown. You can decide to proceed by writing as much data to the target drive as possible, or to cancel. There is an option to modify an existing FAT12 header to match the target drive's characteristics. It is strongly recommended to use this option if the file contains a FAT12 image (e.g. for "normal" disks used with MS-DOS). If the file does not contain a FAT12 image, this option should not be used. Notes: - When writing images which are smaller than the disk in the target drive, the sectors which are not overwritten retain their original data. If data privacy is a concern, the disk should for wiped/formatted first. - Some drives don't show the new content until the disk is either removed and re-inserted, or the PC is rebooted. This has been observed in a PS/2 55 SX. - Special care must be taken if the created disk should be bootable. Please consider the hints in section 9.1 Creating bootable media. 6.8 Explore When pressing the "Explore..." button, the target explorer dialog opens. It contains two controls: the location bar (text field below the title bar) and the file view (list view below the location bar). The location bar is used to specify the initial path to browse, e.g. "C:\*.*". When pressing the enter key the target browser lists the files and sub directories found using the path specification (e.g. with "C:\TEMP\*.TXT" only text files inside C:\TEMP will be listed). The file view is used to display the files and directories, together with their size, date and time of last modification and attributes. You can interact with the elements by double-clicking them: Item | Action ---------------|--------------------------------------------------- Directory "." | The view of the current directory is refreshed Directory ".." | The parent directory is entered again Sub directory | The specified sub directory is entered File | A download dialog for the specified file is opened In addition to that, you can also send files to the directory that is currently listed by dropping them via drag & drop. A dialog opens that allows to adjust the target file name to match the DOS conventions (max. 8 characters for the file name plus 3 characters for the file extension). 6.9 Receive file When pressing the "Receive..." button, a dialog opens which prompts you to select a remote and a local file, where the local file can be selected using a save file dialog. When the dialog is left using the OK button, the file transfer starts and a progress dialog is shown. The file specification can be an absolute path (including drive letters), or a path relative to the working directory the initial loader was started in. 6.10 Send file When pressing the "Send..." button, a dialog opens which prompts you to select a local and a remote file, where the local file can be selected using a open file dialog. When the dialog is left using the OK button, the file transfer starts and a progress dialog is shown. The file specification can be an absolute path (including drive letters), or a path relative to the working directory the initial loader was started in. Note: files can have arbitrary sizes (up to 4 GB, if you are willing to wait long enough). There is no checking of remaining disk space on the target. 6.11 Delays and timeouts The dialog "Delays and timeouts" allows configuration of artificial delays that can be introduced into the communication with the target. Usually this is not required, but might be useful when working with extraordinary slow targets. Note: all delays and timeouts are specified in milliseconds. Although the resolution is 1 millisecond, this doesn't mean that the precision also is. Delay before write Description: Delay introduced right before writing a byte Value range: 0 to 65535 milliseconds Default value: 0 (Off) Delay after write Description: Delay introduced right after a byte was written successfully Value range: 0 to 65535 milliseconds Default value: 0 (Off) Delay before read Description: Delay introduced right before attempting to read a byte Value range: 0 to 65535 milliseconds Default value: 0 (Off) Delay after read Description: Delay introduced right after a byte was read successfully Value range: 0 to 65535 milliseconds Default value: 0 (Off) Delay before read after write Description: Delay introduced before reading the first byte after writing Value range: 0 to 65535 milliseconds Default value: 0 (Off) Delay before write after read Description: Delay introduced before writing the first byte after reading Value range: 0 to 65535 milliseconds Default value: 0 (Off) Read timeout Description: Timeout until a read returns if no data is available Value range: 0 to 65535 milliseconds Default value: 0 6.12 Flow control The dialog "Flow control" allows configuration of the serial port's hardware flow control behavior. Usually all settings different to the default ones do not work properly together with the int 14h BIOS functions of the PC XT/AT. They are provided to support future toolbox implementations using different ways to access the serial port, and to cope with non-standard BIOS behavior. Use CTS output flow control Description: Suspend sending until RTS (ready-to-send) is signaled Value range: Off/On Default value: Off Use DSR output flow control Description: Suspend sending until DTR (data-terminal-ready) is signaled Value range: Off/On Default value: Off DTR flow control Description: Use DTR flow control Value range: Disable/Enable/Handshake Default value: Enable RTS flow control Description: Use RTS flow control Value range: Disable/Enable/Handshake Default value: Enable == 7. About the fat12-resize tool == The fat12-resize tool is a command line program that allows resizing of disk images that use the FAT12 file system. You can specify a source image, a target image and the target drive type to adjust the image for: | | fat12-resize | The supported target drive types are: - 1 = 360K - 2 = 1.2M - 3 = 720K - 4 = 1.44M Internally the very same mechanism is used as for writing disk images using the toolbox client. However, the fat12-resize tool sets all unused bytes in the target image to zero, while writing an actual disk image to the target leaves all unused sectors in its original state. == 8. Advanced topics == 8.1 Changing the baud rate The baud rate is hard-coded into the initial loader binary, together with the number of data bits, stop bits and the parity mode. It can be changed when keying in the initial loader code on the target, or afterwards using a hex editor or the DEBUG utility which is part of a regular MS-DOS installation. The instruction to change is "mov al, 0xe3", where the bits have the following meaning: +-----+-----+-----+-----+-----+-----+-----+-----+ | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +-----+-----+-----+-----+-----+-----+-----+-----+ | Baud rate | Parity | St. | Data bits | +-----------------+-----------+-----+-----------+ Bit 7 | Bit 6 | Bit 5 | Value | Baud rate ------|-------|-------|-------|---------- 0 | 0 | 0 | 0x00 | 110 baud 0 | 0 | 1 | 0x20 | 150 baud 0 | 1 | 0 | 0x40 | 300 baud 0 | 1 | 1 | 0x60 | 600 baud 1 | 0 | 0 | 0x80 | 1200 baud 1 | 0 | 1 | 0xa0 | 2400 baud 1 | 1 | 0 | 0xc0 | 4800 baud 1 | 1 | 1 | 0xe0 | 9600 baud 8.2 Changing the port The port is also hard-coded into the initial loader binary, but easier to spot: it is the value of DX. In the default configuration this is 0 for COM1, coded as "xor dx, dx", which is semantically the same as "mov dx, 0", but has the advantage of not generating binary zeros into the machine code (which are a problem for keying in via ALT+nnn). A way out is to either add "inc" instructions or setting DX to e.g. 0x9999 and then subtracting 0x9998 to get a difference of 0x0001 for COM2. 8.3 Changing the second stage address The initial loader writes received data to a specific memory address and then executes it by performing a CALL. The address is specified in the Makefile by the symbol LOAD_ADDR. When using the ALT+nnn method for keying in the loader code to the target, the address must be chosen carefully to avoid byte values in the resulting machine code that encode certain problematic special characters like 0x00 (NUL), 0x09 (TAB), 0x1b (ESC), etc. The address also has impact on the maximum size of the initial loader and the toolbox image: +---------------------+ <--- 0xffff | Toolbox image | +---------------------+ <--- LOAD_ADDR | Initial loader | +---------------------+ <--- 0x0100 | Administrative data | +---------------------+ <--- 0x0000 == 9. Miscellaneous hints == 9.1 Creating bootable media The write image function takes all sectors from the source image and writes each of them to the next free sector of the target drive. If the drive geometry is different, this causes the written sector to be located at a different "disk address" (track/side/sector). Example: - Input = 180K image (5,25", double density, 1 side) - Output = 360K drive (5,25", double density, 2 sides) Writing this image results in distributing the sectors over 2 sides: - Input track 0, side 0 => output track 0, side 0 - Input track 1, side 0 => output track 0, side 1 - Input track 2, side 0 => output track 1, side 0 - Input track 3, side 0 => output track 1, side 1 - ... Similar effects occur when writing an image with 9 sectors per track to a drive with 15 sectors per track. For using the disk with a FAT12 file system, this doesn't matter, because FAT12 knows about the disk geometry and where the sectors are located. However, simple boot loaders know their next piece of code to be executed by its track/side/sector, which changes during this process, causing the boot loader to pick something different, causing random behavior. You can keep the sectors from being rearranged by patching the target drive's geometry using the disk editor. Going with the example mentioned above, make the target drive to have only 1 side instead of 2 sides; when now writing the 180K image, all sectors will go to the first side, preserving the "addresses". This should work for a difference in number of sectors per track as well, but has not been tested yet. (Please give feedback if you did try this!) == 10. Contact == If you have found a bug or have an idea for new features or other improvements, please contact me via E-Mail at felix@zotteljedi.de. When reporting bugs, please include a detailed description of - Systems used (host, target) - Operating systems involved - Your observation and the behavior you expected - If possible: steps for reproducing the issue For updates, please visit http://www.zotteljedi.de/pc-serial-loader/.