FreeDOS Boot Disks

The FreeDOS Boot Disks repository contains minimal bootable FreeDOS diskette images and boot sectors from those diskettes. The diskette images can be used to boot a simple DOS shell in a virtual machine such as VirtualBox or QEMU, or in a browser with Fabian Hemmer's v86 x86 emulator.

This project also contains various bash scripts that help create/edit FreeDOS boot disk/sector image files. Details on those are provided below.

Demo

A demo of one of the stripped down diskette images from this project running on v86 is hosted here.

Additionally, Fabian Hemmer hosts an excellent v86 Demo that demonstrates a number of OS installations such as versions of Windows, different Linux installations, and various DOS versions here.

Boot Diskette Image Files

FreeDOS Boot Diskette image files are available in the bootdisks folder of this project.

The provided boot disk images are minimal. They only contain the following: KERNEL.SYS, CONFIG.SYS, AUTOEXEC.BAT, COMMAND.COM, and a small README.TXT file with a link to this project.

The boot disk images come in differing sizes (160K, 180K, 320K, 360K, 640K, 720K, 1200K, 1.4M) in case you need to fill the image with a few more programs or have a strange expected target disk size.

Note: This project generates a 640K boot disk image. v86 does not support the 640K size.

The provided images boot well in v86. I have not taken the time to see if they boot well on other virtualized platforms or on real vintage hardware.

Customizing Boot Disks

To customize any of the provided boot disk images on MacOS, simply double click one of the boot diskette .img files in the Finder application to mount the disk, then use Finder (or the terminal, the disk will be mounted in /Volumes/FREEDOS) to customize the contents of the .img file. Be sure to eject the image file using Finder (or 'hditutil eject /Volumes/FREEDOS') when you've finished customizing it.

Advanced Boot Disk Customization

The FreeDOS boot disks provided by this project were built with the eddosboot.sh script, like so:

./eddosboot.sh CREATE_ALL_BOOT_DISKS

When eddosboot.sh creates boot disk images, the files from this project's scripts/lib/boot_disk_contents directory are copied to the diskette.

If needed, you can customize the contents of the scripts/lib/boot_disk_contents directory and rebuild the boot disks again using the CREATE_ALL_BOOT_DISKS command shown above.

The following resources will be helpful in customizing your installation:

FreeDOS Reference
FreeDOS CONFIG.SYS Reference
FreeDOS COMMAND.COM Reference
FreeDOS AUTOEXEC.BAT Reference
FreeDOS HIMEM.EXE Reference
FreeDOS NANSI.SYS Reference
FreeDOS chkdsk Reference - Alternative to MS ScanDisk.
FreeDOS fdisk Reference
FreeDOS format Reference
FeeeDOS zip Reference
FreeDOS unzip Reference
FreeDos md5sum Reference
WinWorld's Dos Application Library - Contains useful retro software such as WordPerfect, compilers, pkzip, etc.
v86 FreeDOS boot diskette image - Contains several additional utilities, drivers, and games that aren't found in boot disks provided by this project.

If you don't feel comfortable customizing a FreeDOS boot disk's configuration by hand, then you can create FreeDOS boot diskettes by running through a virtualized FreeDOS installation using QEMU or VirtualBox. Once you have the resulting FreeDOS boot disk image in hand, you can copy the disk's contents to the scripts/lib/boot_disk_contents directory and create the minimally sized disks again.

Boot Sectors

Boot Sectors for each of the FreeDOS .img files mentioned above have been extracted and placed are available in the bootsectors folder of this project.

Booting in v86

If you're unfamiliar with v86, it's a x86 javascript emulator that emulates a vintage PC in a browser. v86 provides hardware emulation of floppy disk drives, IDE hard disk drives, sound blaster 16, VGA, PCI and more.

The author has various Linux, Windows, and DOS demo operating systems running on v86 on his personal host here:

https://copy.sh/v86/

It took a while for me to figure out how to run just his FreeDOS demo image locally without the big demo that requires downloading multiple OS images, here's my source for that:

<!doctype html>
<script>
	//if you want v86 to log debug information, uncomment this line below
	//var DEBUG = true;
</script>
<script src="libv86.js"></script>
<script>
	"use strict";

	window.onload = function() {
    	var emulator = window.emulator = new v86Starter({
        	memory_size: 32 * 1024 * 1024,
        	vga_memory_size: 2 * 1024 * 1024,
        	screen_container: document.getElementById("screen_container"),
        	bios: { url: "seabios.bin", },
        	vga_bios: { url: "vgabios.bin", },
        	fda: { "url": "freedos.boot.disk.160K.img", },
        	autostart: true,
	    });
	}
</script>

<div id="screen_container">
    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
    <canvas style="display: none"></canvas>
</div>

A few notes on the sample shown above:

An expanded version of this sample.html file, complete with the seabios.img, vgabios.img, libv86.js, and freedos.boot.disk.160K.img are provided in the sample directory of this project.
You won't be able to run the sample by simply opening the html file from disk in your browser. Instead, you will need to run a http webserver on your machine. The easiest way to run a server on your machine is to run the following python command in the directory you want to server the html and img files from:

python -m SimpleHTTPServer 8070
The above example will host a web server on your machine on port 8070. If you start the webserver in the sample folder of this project, the url to fetch the sample.html will be:

http://localhost:8070/sample.html
Other popular web server options to consider are Apache, NGINX, a LAMP stack (which includes apache as the webserver portion of the stack), Tomcat, or Geronimo. More webserver options are listed here.
The seabios.bin and vgabios.bin images came from the v86 github project here.
If you prefer, you can build the libv86.js file yourself by cloning the v86 project from github. And building it yourself.
You can run a non-minimized js version of the v86 library locally if you clone the v86 repo and reference the v86 debug loader.js file from source like the v86 source sample html does.
You can easily provide more images for emulated hard drives and cdroms using the v86 api with params such as "hda" and "cdrom". The cd-rom images can be (or must be?) in .iso format.
The v86 API has a bunch of other options, those are documented here and here.

Scripts

A few scripts were written to automate boot disk creation, boot sector extraction/importing, and sector size/count editing. The scripts are in the scripts directory of this project.

All scripts are bash scripts intended to run on MacOS.

The primary script is eddosboot.sh. It provides the following operations:

Create minimal FreeDOS boot disk image files in the following sizes: 160K, 320K, 720K, 1.44M
Create FreeDOS boot sector image files for supported boot disk sizes.
Display boot disk / boot sector sector sizes and sector counts.
Change boot disk / boot sector sector sizes and sector counts.
Copy boot sectors from one image file to another.
Bulk mode to generate all supported boot disk sizes.
Bulk mode to generate all supported boot sectors.

The script provides usage instructions when it's run without any arguments like so:

./eddosboot.sh

The testeddosboot.sh script provides some unit tests that exercise eddosboot.sh functionality.

The project also includes a small library of hex conversion and read/write bash functions in hexlib.sh. A test script testhexlib.sh is also provided.

Bugs / Possible Problems

I'm not a vintage hardware guru, so I would not be surprised if the images I've hacked together have issues in the boot sectors such as:

Sector sizes might be unrealistic for real diskettes. For example, all of the images and boot sectors here specify a sector size of 512 bytes. I have not done the research to figure out if a 160KB diskette had a different sector size than a 1.4MB diskette typically had.
Sectors Per Track / Sectors Per Cylinder specifications may be unrealistic for real diskettes. The provided boot sectors and images have left these values in the original state from the source image provided by the v86 project.

If you want to edit sector sizes, sector counts, volume names, cylinder counts, or track counts, I recommend the following resources:

Resources

Boot process resources:

Open-source / Free DOS distributions:

Tools:

FreeDOS
VirtualBox - Free OS virtualization platform.
QEMU - Another free OS virtualization platform.
Win World - Old OS (Windows 3.1, 9x, Dos, and more) installation files and old software (Turbo Pascal, WordStar, etc)
Old Version - Archive of many old versions for various retro and current software such as WinAmp, FireFox, and more.

Javascript x86 Emulation:

v86
js-dos - x86 javascript emulator tailored for converting and running dos games in browser.
em-dosbox
asm.js
WebAssembly
emscripten - LLVM (C/C++) to JS compiler

Further Resources:

Trivia

While building this project, I learned a lot about bootable diskettes. It was not trivial to piece together how a vintage bootable diskette image can be created on modern hardware, or how the boot process works in general. I'm providing these bits of trivia and details in hopes that it will help others looking for understanding:

A bootable hard drive has several parts to it. The very first sector on the disk is called a boot sector. The boot sector is 512 bytes long and contains the Master Boot Record (aka MBR). The drive itself contains one or more partitions, which is a section of the drive that is mapped to a logical drive on your computer. A drive can have multiple partitions on it, but there's usually just one partition.

When you create a file system on a disk by formatting a partition on the drive with tools such as MacOs' Disk Utility, the tools will ask you how large you want a partition to be. For example, you could create a 50GB partition and a 150GB partition on a 200GB drive.

Consumer laptops often ship with a drive that has multiple partitions on it, the first being a read-only "recovery partition" that's used to reinstall the OS, and the second being the main partition used to house the OS and your files.

When a machine is dual-bootable, there can either be two (or more) physical hard disks in the system with one partition per drive, or two partitions on a single drive. [Boot Camp](https://en.wikipedia.org/wiki/Boot_Camp_(software) for MacOS does just this, it creates a second partition on your hard drive and formats with a filesystem format that Windows understands (such as ExFAT), while keeping the primary partition on the drive formatted in APFS or some other format that MacOS recognizes and boots from.

When a machine starts, one of the partitions on the primary drive is marked as 'active', meaning that's the partition for the BIOS to jump to and start loading the OS from. Boot managers that help with dual booting a machine into multiple operating systems simply switch which partition is marked as active, then boots the machine to that partition (I think.. maybe the boot manager is actually on a third partition and the third partition is always marked as active, with the boot manager program tricking the OS into booting from another partition when the user selects which OS they want to boot).

When the computer boots, or a new drive is attached to the computer, partitions are mapped to logical drives, such as a "C:" or "D:" drive on a Windows Machine. On linux/MacOS systems the drive's partitions will be mapped to filesystem abstractions such as /dev/disk1s1 and /dev/disk1s2. For MacOS terminal fans, the logical volume versions of the the partitions will also be mounted under the /Volumes directory, for example: /Volumes/MYDRIVE.

When an external drive, cdrom, usb stick, or sd card is plugged into a machine, the drive will popup in Finder (on Macos) or Explorer (on Windows) with the volume labels such as MYDRIVE mentioned above. Under the covers on a linux or MacOS system, the OS is automatically doing two operations to make the volume available: attaching and mounting the drive.

When a drive is attached but not mounted, the drive can be fully erased, reformatted, or byte-for-byte copied to another disk or an image file using the unix dd command. The dd program differs from cp in that it copies every single byte from the disk, meaning it will copy or erase every sector from the disk, including boot sectors, partition information, FAT information, empty space, every file and folder in their current state (including their exact fragmentation across different sectors on disk, and even 'deleted' file data on the disk where the file has merely been removed from the FAT but the bytes of the file are not securely erased by writing zeros or random data over the file's contents on disk). The dd command is often used when attempting to recover a faulty or failing disk that's mounting incorrectly or has a corrupted FAT.

The df command on Linux and MacOS machines can be used to view information about the attached and mounted disks in your system. In this example below, I provide the -h switch to the df command, so the command prints out the drive capacity and free space in a human-legible summarized format such as 1GB rather than 1073741824 bytes:

jbmbpro2014:dist jason$ df -h

Filesystem      Size   Used  Avail Capacity iused               ifree %iused  Mounted on
/dev/disk1s1   234Gi  192Gi   39Gi    84% 1633783 9223372036853142024    0%   /
/dev/disk1s4   234Gi  2.0Gi   39Gi     5%       2 9223372036854775805    0%   /private/var/vm
/dev/disk1s3   234Gi  495Mi   39Gi     2%      14 9223372036854775793    0%   /Volumes/Recovery

The dd command can also be used to create an empty zeroed-out .img file like so:

dd if=/dev/zero of=myimage.img bs=512 count=1440

With the example above, we're specify that the .img file is filled with zeroes (copied from /dev/zero, which when read will always return zeros). The created .img file has sectors that are 512 bytes in size, and it has 1440 sectors. A kilobyte is 1024 bytes, so two sectors form a kilobyte. When we divide 1440 by 2, we get 720 - so a 1440 sector 512 byte per sector disk is 720KB, which is one common disk size for floppy disks.

Early floppy disks came in sizes of 160KB and later disks regularly came in a 1.44MB size. v86 supports a few common floppy disk sizes, those are found in the floppy.js file:

var floppy_types = {
	160  : { type: 1, tracks: 40, sectors: 8 , heads: 1 },
	180  : { type: 1, tracks: 40, sectors: 9 , heads: 1 },
	200  : { type: 1, tracks: 40, sectors: 10, heads: 1 },
	320  : { type: 1, tracks: 40, sectors: 8 , heads: 2 },
	360  : { type: 1, tracks: 40, sectors: 9 , heads: 2 },
	400  : { type: 1, tracks: 40, sectors: 10, heads: 2 },
	720  : { type: 3, tracks: 80, sectors: 9 , heads: 2 },
	1200 : { type: 2, tracks: 80, sectors: 15, heads: 2 },
	1440 : { type: 4, tracks: 80, sectors: 18, heads: 2 },
	1722 : { type: 5, tracks: 82, sectors: 21, heads: 2 },
	2880 : { type: 5, tracks: 80, sectors: 36, heads: 2 },
};

Note: This project generates a 640K boot disk image. v86 does not support the 640K size.

More details on floppy disk formats are listed on Wikipedia's List Of Floppy Disk Formats.

A floppy diskette does not have a MBR, but instead has a Volume Boot Record (VBR). I'm a little confused on the difference between a MBR and a VBR, but my basic understanding is that a MBR is used on devices like hard disks that support partitions or multiple partitions, and a VBR is used on storage mediums without partitions (such as floppy diskettes).

The bootable FreeDOS diskettes provided in this project are FAT12 format, because that's what the original v86 floppy image was formatted in. I think later boot disk formats for Windows, Linux, and other operating systems were not necessarily FAT12, as the MBR/VBR generally has a jump command that points to some x86 instructions to first run a disk driver, which is a program that reads FAT information from a drive and controls organizing, reading, and writing files and folders. After the disk driver is started up, it transfers command to a boot file on the disk such as CONFIG.SYS in FreeDOS, which then continues booting the OS.

There are a number of other useful commands for image creation, partitioning, and formatting in Linux/MacOS that can be used in a terminal:

Managing Linux Partitions With fdisk
Another fdisk Reference
newfs_msdos
dd
Using dd to save/restore a boot sector
df
hdiutil - MacOS only
Disk Utility and the terminal version diskutil - MacOS only

This is all my very high-level novice understanding of how MBRs, VBRs, boot sectors, partitions, and file system formats work. There are a number of resources listed above that go into much greater detail, with much greater authority than I possess. In particular, be sure to check out Boot Records Revealed with extremely detailed information about the byte-level breakdown of various boot sector formats.

Note that there's more trivia and gotchas document inside the script files contained within this project.

Purpose

These images were created while working on a book about vintage computing and the insanity associated with a software engineering career. While writing the book, emulated operating systems in a browser were in vogue, and I wanted to create a nostalgic browser-based DOS experience to advertise the book. I found the v86 library. The sample FreeDOS image provided with v86 is a 720KB diskette that includes a few programs and tools that I was not interested in providing on my book's site, so I went on a quest to strip the diskette image file down in size. In that quest, I sought a way to recreate a bootable diskette with an arbitrary size via a script that would not require manually clicking through a FreeDOS installation wizard or changing the original source diskette image, and I realized there weren't any incredibly straight forward resources for creating a minimal bootable FreeDOS diskette image, so here we are.

Credit

Thanks to Fabian Hemmer for v86 and his original FreeDOS diskette image that I used to seed this project's images.
Thanks to David Anderson for helping me understand the difference between MBR and VBR, and providing example code to extract the boot sector from one image and stick it into another in this Stack Overflow thread.
MS Dos 5.0 Boot Sector Reference
FreeDOS
The Hex Fiend hex editor for MacOS was used to verify and troubleshoot this project's boot sectors.

Contributing

If you'd like to contribute to the project, feel free to send me PRs, I'll credit you for your additions.

Some suggested future improvements:

More boot sector display/edit property support for properties such as the boot sector volume label, head count, cylinder count, etc.
Make the scripts cross-portable, rather than MacOS specific.
Improve the baseline CONFIG.SYS file.
Documentation improvements.
Productize hexlib.sh to be a nice standalone script rather than just bash functions.
Add more supported boot disk image sizes (all possible variations are listed in 'man newfs_msdos'). In particular, I could use help figuring out the newfs_msdos incantation for a 2.88MB image.
Add error handling when a disk is being created and the user's boot_disk_contents files overflow the disk size.
Add more error checking in general, checking for exit codes from various commands.

License

All V86 assets, including the copied FreeDOS image file, the vgabios.img, the seabios.img, and the compiled libv86.js file in this repository are copyrighted by Fabian Hemmer or other respective owners. License information for those assets is available on the v86 licensing terms page.

All FreeDOS assets, including the KERNEL.SYS and COMMAND.COM FreeDOS files are licensed as described here.

All scripts are licensed with the Apache license, which is a great license because, essentially it:

a) covers liability - my code should work, but I'm not liable if you do something stupid with it
b) allows you to copy, fork, and use the code, even commercially
c) is non-viral, that is, your derivative code doesn't have to be open source to use it

Other great licensing options for your own code: BSD License, MIT License, or Creative Commons.

Here's the license:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied.

codercowboy / freedosbootdisks Goto Github PK