How to boot FreeDOS-32

This document explains how to start the FreeDOS-32 kernel either with GNU GRUB or with the X.exe eXtender.

Using GNU GRUB and the eXtender

The FreeDOS-32 kernel is a MultiBoot compliant executable (see the MultiBoot specification on the GRUB web site for details); as a result, it can be booted using a MultiBoot compliant boot loader, such as GNU GRUB, or it can be run from a DOS system through a custom DOS eXtender (x.exe).

In order to run FreeDOS-32 through the eXtender, boot a DOS (either MS-DOS or FreeDOS) and type:

x -m <module1> -m <module2> ... -m <modulen> <kernel>

For example, from the fd32 directory (referring to the source tree) type:

x -m drivers\dpmi\dpmi.o -m ..\tests\empty.exe fd32.bin

(note: x.exe should be in your path, or in the fd32 directory)

In order to boot the kernel using GRUB, create a GRUB floppy (look at GRUB documentation), copy the kernel and the modules on it and boot it. Then, enter the GRUB command line (by pressing the 'c' key), and type:

kernel (fd0)/<kernel>
module (fd0)/<module1>
module (fd0)/<module2>
...
module (fd0)/<modulen>
boot

For example, use:

kernel (fd0)/fd32.bin
module (fd0)/dpmi.o
module (fd0)/empty.out
boot

Boot modules

Now, before seeing which modules you can load, let's have a look at what a module is. A module can either be an object file (that will be dynamically linked with the kernel) implementing a driver or a native application, or an executable file (COFF, ELF, or DJGPP stubbed EXE) that will be executed by the kernel on boot. Some programs to be run as modules are in the tests CVS module, whereas some objects implementing drivers can be found in the drivers CVS moudle. The DPMI driver is special, because it is not intended to be portable, thus it is located in the drivers directory of the fd32 CVS module.

For example, tests/empty.exe (or, that is the same, its unstubbed version, empty.out) is a very simple program using the DPMI driver, that is fd32/drivers/dpmi/dpmi.o.

Now, let's see which modules to load. First of all, if you want to test the kernel without running any program you do not need to load any module. Simply use:

x fd32.bin

or GRUB with:

kernel (fd0)/fd32.bin
boot

Using the DPMI driver

If you want to run a DPMI program, you have to load the DPMI driver in order to provide it the standard DOS and DPMI APIs (summarizing, INT 21h and INT 31h). By default these APIs are not provided by the FD32 kernel. You will have to load the DPMI driver first and the program after.

This explains why I said that in order to run the empty.exe test we have to do (supposing all files in the current directory):

x -m dpmi.o -m empty.exe fd32.bin

or, using GRUB (supposing all files in the root directory of the floppy):

kernel (fd0)/fd32.bin
module (fd0)/dpmi.o
module (fd0)/empty.exe
boot

Keyboard and console drivers

If you want to run a program which requires input from the keyboard, you have two more drivers to load. The keyboard driver provides low level keyboard access, while the console driver provides "cooked" access to the keyboard input, thus implementing the stdin functionality. Actually, the console driver provides also console output, implementing the stdout stream, but you can get off without it: the kernel provides failsafe stdout functionality if no console driver is installed.

To run a test program using the keyboard, such as get.exe, try this:

kernel (fd0)/fd32.bin
module (fd0)/dpmi.o
module (fd0)/keybdrv.o
module (fd0)/consdrv.o
module (fd0)/get.exe
boot

Note 1: I did not show the syntax to be used if you want to use x.exe, but you can easily argue it.
Note 2: the keyboard driver has to be loaded before the console driver, because the latter requires services from the former.
Note 3: the order in which you load dpmi.o and keybdrv.o or consdrv.o is not important: just load them all before the test program.

You will notice that some keys don't work properly. This is simply because the console driver is mainly incomplete... Have a look at the source, and you will understand what I mean :)

Using the FAT driver

Now, let's increase the complexity: let's use the FAT file system. The filetest.exe test program performs a fopen/fread/fclose sequence on a file.

kernel (fd0)/fd32.bin
module (fd0)/biosdisk.o
module (fd0)/clockdrv.o
module (fd0)/fat.o
module (fd0)/dpmi.o
module (fd0)/filetest.exe
boot

BIOSDisk (biosdisk.o) is the disk driver, which provides low level (sector) access to disk devices. The FAT driver (fat.o) has to be loaded after BIOSDisk, because it relies on the low level services the latter provides. Actually, you have to load the file system driver after the disk driver because registering a file system driver to the FD32 kernel causes it to trigger drive letters assignment. This may change in the future.

Note that the CMOS Clock driver (clockdrv.o) is loaded before the FAT driver in order to provide it system date and time for files time stamps. Loading clockdrv.o is not required, but if you don't load it the FAT driver will save empty time stamps.

And again, load dpmi.o whenever you want, but before filetest.exe.

Ok, now you got the point... Now, you can start to be creative, and to try some new combination of drivers and programs (note that after executing a program you can execute a new one...).