                         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.

