Commit 5a64ec0d authored by Karsten Lehmann's avatar Karsten Lehmann

doc: Documentated new setup and tests of the bootloader

parent dce4e213
......@@ -8,37 +8,65 @@ More information about the project is [available on my blog](https://blog.kalehm
## Usage
### Building
### Build process
First the binaries of the bootloader and its installer must be build. To do so
**gcc** and **nasm** have to be installed.
To build the bootloader [The Netwide Assembler (nasm)]( has to
be installed.
The build process is started with the include _Makefile_ by simply running
The bootloader binary (`bootloader.bin`) can be built with
### Creating a floppy image
### Configuring the bootloader
The bootloader needs to know the
[8.3 or short filename](
of the file it should boot. The filename needs to be written to the offset 498
of the bootloader.
This can be done with the following command:
echo "TEST BIN" | dd of=<bootloader binary> conv=notrunc bs=1 count=11 seek=498
### Write the bootloader to an image
The bootloader can be written to an image with **dd**:
Creating a floppy image can be done using the _mkfs.fat_ utility. The image can
be mounted afterwards and the second stage copied onto it:
dd if=<bootloader binary> of=<image file> conv=notrunc bs=1512 count=1
## Development
### Debugging
The bootloader can be debugged with qemu and gdb.
``` bash
mkfs.msdos -C -v floppy.flp 1440
LOOP=$(losetup -f)
losetup ${LOOP} floppy.flp
mkdir -p loop_mount
mount /dev/loop0 loop_mount/
cp MYCOOLOS.BIN loop_mount/
umount loop_mount
rm -Rf loop_mount
losetup -D
In one terminal window execute
make debug
After that, the bootloader can be written on the image with the included
installer and configured to load *MYCOOLOS.BIN*
and in another terminal window connect with gdb using:
``` bash
./sibolo-install bootloader.bin floppy.flp MYCOOLOS.BIN
gdb \
-ex "target remote :1234" \
-ex "set tdesc filename target.xml" \
-ex "break *0x7c00" \
-ex "layout asm" \
-ex "set disassembly-flavor intel" \
-ex "continue"
### Testing
The project has build processes for three floppy images and testcode to verify
that the bootloader works.
**Note** that the name of the file that the bootloader loads needs to comply with the 8.3 format. The length of the base name must not exceed 8 bytes and the length of the file extension must not exceed 3 bytes. All letters must be upper case.
The test process is documented in the [`tests` directory](tests/
## Testing the Simple Bootloader
The tests for the bootloader can be executed with
make check
Unfortunately this command has to be executed with superuser priviledges as it
assignes images to loop devices and mounts them.
The test process starts three different qemu instances and the user
must visually verify that the test succeeded.
### First test case: Successfully booting
The first qemu instance (with the title _Test working_) should show
a short text with the value for the boot drive and the contents of all
![A screenshot of qemu showing a success message](screenshots/test_success.png)
## Second test case: File not found
The second qemu instance (with the title _Test file not found_) should display
a message, that the file **TEST.BIN** could not be found.
![A screenshot of qemu showing the message Not found: TEST BIN](screenshots/test_file_not_found.png)
## Third test case: IO error
In the third test case, a hard drive is simulated for the bootloader, that is
too small to hold a fat12 file system.
The bootloader tries to read data from an address not on the drive and shows
the message _"IO error"_
![A screenshot of qemu showing the message Not found: IO error](screenshots/test_io_error.png)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment