# RxDOS version 7.20N notes

This document (2008-2011 by C. Masloch) is in the Public Domain.

This document has been sloppily compiled on 2018-05-22, release 2011-01-14.

## 1: RxDOS license

This product is distributed AS IS and contains no warranty whatsoever, including warranty of merchantability or fitness for a particular purpose.

Copyright (C) 1990-1999 Mike Podanoffsky

This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, see the file LICENSE.TXT.

### 1.1 Contributions

C. Masloch ported the provided source code to NASM, and packed these files up for the RxDOS 7.20N release. The associated work is released as-is, without any warranty whatsoever, and is in the public domain. This does not affect other copyrights as noted above.

## 2: Contact

BTTR Software
  http://www.bttr-software.de/
C. Masloch
  cm -AT- bttr-software.de

## 3: Advise on usage of RxDOS version 7.20N

Do not use RxDOS version 7.20N. It tries to re-produce every bug of RxDOS 7.1.5 (as found on the FreeDOS mirrors). It is not usable currently. The release of version 7.20N is only intended for developers.

### 3.1 Developing RxDOS

1. Do not take anything for granted.
2. Read and understand all the source code that you use from this release before claiming it works.
3. You can read the book ‘Dissecting DOS’ for some advise on RxDOS's internal structure, although it describes an older version. You will need a deeper understanding for development though.
4. As described in section 6 the build process currently uses tools that run and build on DOS, are considered non-free, or require non-free programs to build. Modifying the kernel and RxCMD to build using nothing but NASM should be trivial for developers.

## 4: Introduction

### 4.1 Where are all the programs?

RxDOS does only consist of the DOS system core (kernel), the command line interpreter and a few supplemental programs.

It's recommended to use the programs from the FreeDOS project: Most of these run on RxDOS as well and they're all free like RxDOS as well.

### 4.2 How do I install RxDOS?

If you're running some DOS (possible RxDOS from an installation disk) locate the batch script file named MAKEBOOT.BAT. Change the current directory and drive to the directory in which you found MAKEBOOT.BAT. Make sure the program files RXD_BOOT.COM and RXCMD.EXE and the system files RXBIO.SYS and RXDOS.SYS are also in the same directory. Then type ‘`MAKEBOOT A:`’ (without the quotes), substituting ‘`A:`’ by the drive you want to install RxDOS on. In general you'll have to type ‘`MAKEBOOT A:`’ or ‘`MAKEBOOT B:`’ to install RxDOS on a floppy drive or ‘`MAKEBOOT C:`’ to install RxDOS on a hard drive.

If you want to install the supplemental programs locate them on a disk and copy them to a directory on the target drive you've just installed RxDOS on, using (for example) ‘`COPY A:\RXVDISK.SYS C:\RXDOS\RXVDISK.SYS`’. (This examples assumes that there's already a directory RXDOS on drive C:. Create one with ‘`MD C:\RXDOS`’ if you want it.)

### 4.3 What are the files RxDOS is made up of?

`RXBIO.SYS`
  The RxBIO (Basic Input/Output) core. Required to boot RxDOS.
`RXDOS.SYS`
  The RxDOS (Disk Operating System) core. Required to boot RxDOS.
`RXCMD.EXE`
  The RxCMD (Command line interpreter) program. This is the program that RxDOS will start by default after it booted. You can however use RXCMD.EXE like any other program. You can also instruct RxDOS to start another program after it booted. Type ‘`RXCMD.EXE /?`’ at the command prompt to get help on the usage of RxCMD.
`RXD_BOOT.COM`
  This program installs RXBOOT.SYS to a DOS drive. Type in ‘`RXD_BOOT.COM /?`’ at the command prompt to get help on the usage of RxD_BOOT. A copy of RXBOOT.SYS is contained inside RXD_BOOT.COM, you don't need RXBOOT.SYS to use RXD_BOOT.COM.
`RXVDISK.SYS`
  This system driver creates a virtual drive inside the low memory area. It is used inside RXCONFIG.SYS with a line like ‘`DEVICE=RXVDISK.SYS`’ (see RXCONFIG.TXT for a description of the RXCONFIG.SYS file).
`RXBOOT.SYS`
  This binary file is an image for the RxDOS boot loader for FAT12 or FAT16 drives. You don't need this file unless you've some special program capable of installing it to a drive.
`RXMBR.SYS`
  This binary file is an image for the RxDOS boot loader for hard disks. You don't need this file unless you've some special program capable of installing it to a disk.
`MAKEBOOT.BAT`
  This text file contains a batch script to install the RxDOS boot loader (using RXD_BOOT.COM), both RxDOS system cores and the command line interpreter to a drive. This is no real program and it's only distributed with RxDOS to make installing RxDOS easier.

## 5: Changes of RxDOS version 7.20N since 7.1.5

1. Only Netwide Assembler (NASM) 2.04+ used for assembling.
2. Changed names of these programs:

       RxDOSBIO   to RxBIO
       RxDOSCMD   to RxCMD
       RxD_BOOT   to RxD_BOOT and RxBOOT (see also below)
       RxDOSMBR   to RxMBR

3. RxD_BOOT slightly modified:
   1. Splitted into RxBOOT (the actual boot sector) and RxD_BOOT (the boot sector write program).
   2. RxD_BOOT is now assembled into a .COM program file. Removed unused padding which made the file's size about 32 KiB.
   3. RxD_BOOT can use Int25/26 instead of direct DOS device driver calls which makes it work in NTVDM and possible other environments that don't support direct DOS device driver calls.
4. Format of the source files modified:
   1. The source files now use tab characters to make editing them easier. The tab characters should be expanded to up to 8 spaces for displaying.
   2. Removed the funny boxes drawn with ; ' - . characters. Use the MASM source if you really need them.
5. Replaced COPYING and gpl.txt by LICENSE.TXT which is an up-to-date plain-text GNU GPL Version 2 from http://www.gnu.org/
6. Directory structure changed.

   Former:

       \         Binaries, documentation, license,
                  makefile, link files
       \sources  Actual source, include/macro files, license
       \objs     Object files
       \errors   Assembler and linker error messages

   New:

       \         Make scripts
       \RxBIO    RxBIO source
       \RxDOS    RxDOS source
       \RxCMD    RxCMD source
       \RxAPP    Sources of RxMBR, RxBOOT, RxD_BOOT, RxVDISK
       \MACRO    Macro files
       \doc      Documentation, license
       \lst      Listings
       \map      Map files
       \obj      Object files
       \bin      Binaries

7. Some new or corrected code for RxDOS 7.30 added to source files. This code is deactivated using NASM conditional assembly and it'll get actived in the first release after RxDOS 7.20N (planned as RxDOS 7.30).

## 6: Building RxDOS 7.20N from the source code

### 6.1 Required tools

1. NASM 2.04 .. 2.10, other versions might work
2. One of these linkers:
   1. WarpLink 2.70
   2. ALink, possibly
   3. Other 16-bit OMF linkers, with trivial adjustments
   4. NASM's internal linker (output format `bin`), requiring some adjustments to the source code and scripts
3. exe2bin (tested with OpenWatcom 1.6 .. 1.9 program)

Note that usage of NASM's internal linker would make exe2bin unnecessary too. Some other linkers will output a flat binary instead of an .EXE file too.

### 6.2 Warnings to expect

Recent attempts to assemble the provided source code (with NASM 2.10rc1-20101106) caused several warnings in RxCMD.ASM, mostly by re-using variable names without manually undefining these pre-processor variables. The reason that this was not yet fixed might have been that RxCMD wasn't finished yet. Some (but probably not all) of these cases warn with "trailing garbage after expression ignored" because the %[i]assign directives get passed something like "`_-2 -2`" (as %1 is already expanded). A simple solution to these problems (in the macros) requires the %# feature that is not yet implemented in NASM.

The "word data exceeds bounds" warnings that are displayed for RxCMD.ASM too can probably be ignored.

The erroneous relocation in the RxDOS.EXE file as reported by exe2bin is, though non-sensical, indeed in the source.

### 6.3 Script

The mak.cmd script should be sufficient to create a makefile or simple script for your particular platform. It was created for a Windows NT environment.

To achieve mostly binary-compatible files to RxDOS 7.1.5 the automatic optimization of recent NASM versions needs to be turned off using the command line switch "`-O0`".

#### 6.3.1 Building RxBIO, RxVDISK, RxBOOT, RxMBR

The associated .SYS file has to be build from the .ASM source code file using NASM's output format `bin`. As for all NASM command lines, `-i..\MACRO\` or `-i../MACRO/` has to be specified to pass the macro include path to NASM. Minimal example:

    nasm -i..\MACRO\ -o..\bin\RxBIO.SYS RxBIO.ASM
    nasm -i..\MACRO\ -o..\bin\RxVDISK.SYS RxVDISK.ASM
     .
     .
     .

#### 6.3.2 Building RxD_BOOT

First, the intermediate file RxD_BOOT.SYS has to build like the other files described in section 6.3.1:

    nasm -i..\MACRO\ -o..\bin\RxD_BOOT.SYS RxD_BOOT.ASM

Then, the file RxBOOT.SYS has to be appended to RxD_BOOT.SYS to form RxD_BOOT.COM. A `copy` command might require a `/b` switch to specify that it should open the files in binary mode. The `/y` is used here to specify overwriting the destination if it exists.

    copy /y /b RXD_BOOT.SYS + RXBOOT.SYS RXD_BOOT.COM

#### 6.3.3 Building RxDOS

Each of the RxDOS modules RxDOS, RxDOSCCB, RxDOSDEV, RxDOSEXE, RxDOSFAT, RxDOSFCB, RxDOSFIL, RxDOSLFN, RxDOSF32, RxDOSIFS, RxDOSMEM, RxDOSSFT, RxDOSSTR, RxDOSCTB, RxDOSERR and RxDOSINI need to be assembled into intermediate objects file first. For example:

    nasm -i..\MACRO\ -fobj -o..\obj\RxDOS.OBJ RxDOS.ASM
    nasm -i..\MACRO\ -fobj -o..\obj\RxDOSCCB.OBJ RxDOSCCB.ASM
     .
     .
     .

Then, all the object files have to be linked together with a linker. This is the command line that works with WarpLink:

    warplink @warplink.lin

The file warplink.lin contains the list of files and command line options. The order in which these files are linked is important. RxDOS.OBJ must be the first, while RxDOSINI.OBJ must be the last. The order of the other files probably doesn't matter.

     /s /mx /xt +
    RxDOS.OBJ +
    RxDOSCCB.OBJ +
    RxDOSDEV.OBJ +
    RxDOSEXE.OBJ +
    RxDOSFAT.OBJ +
    RxDOSFCB.OBJ +
    RxDOSFIL.OBJ +
    RxDOSLFN.OBJ +
    RxDOSF32.OBJ +
    RxDOSIFS.OBJ +
    RxDOSMEM.OBJ +
    RxDOSSFT.OBJ +
    RxDOSSTR.OBJ +
    RxDOSCTB.OBJ +
    RxDOSERR.OBJ +
    RxDOSINI.OBJ +
     ,RxDOS.EXE,RxDOS.MAP,;

(The plus sign specifies line continuation to WarpLink.)

The RxDOS.EXE file that is created by the linker (in the obj subdirectory) now needs to be converted to a flat .COM file. This command line works with OpenWatcom's exe2bin:

    exe2bin -x -r -l=0 RxDOS.EXE ..\bin\RXDOS.SYS

#### 6.3.4 Building RxCMD

Similar to RxDOS's build process described in section 6.3.3, each of the RxCMD modules RxCMDCPY, RxCMDDIR, RxCMDFOR, RxCMDPRM, RxCMDREN and RxCMD need to be assembled into object files first. The files have to be linked similarly to the RxDOS link process then, too. The order of the RxCMD objects probably is important too, the module RxCMD quite certainly must be specified last. exe2bin is not to be used for RxCMD.

#### 6.3.5 Building the documentation

The provided documentation is partly written for Halibut, a program that compiles its input to various other formats. To compile the documentation into one text file and one HTML file, use this command:

    halibut --text --html readme.but intro.but changes.but build.but

This writes the readme.txt and readme.htm files. The order of the input files matters, as the output will reflect this order. Note that readme.but contains some configuration for the text and HTML output formats of Halibut, but not for any other formats. You may wish to configure other output formats if you want to use them.