How to set up your hardware specifications

📅 2025-05-12  · ✍️ Bas v.d. Wiel  ·  🏷 design , documentation

Hardware specifications are one key part of a complete DOSContainer configuration. Manifests are the other, but we’ll get to that. Hardware specifications, or HwSpec for short declares to DOSContainer what your retro PC hardware looks like. In it, you specify exactly what devices you have in your real or emulated system so that DOSContainer can take this into account when configuring applications and games to run on your system. It means DOSContainer will configure your game to use CGA graphics if that’s all you have, even if the game itself can do better. This article explains the first draft of the HwSpec TOML file format and shows a couple of complete examples that define a real IBM PC and a 1983 IBM XT.

Let’s start with what TOML is. TOML is short for Tom’s Obvious Minimal Language. It’s got its own website and a tagline as well: A config file format for humans. Being geared at humans is a big plus for it over other formats like JSON or even YAML. TOML is easy to read and easy to write as well. DOSContainer aims to make its configuration as easy as possible, so TOML it is!

Hardware specifications

PC’s from the age of DOS came in all shapes and sizes. If you look at it from a modern perspective you’d be surprised at how much you could really tweak the hardware and how much of a jarring difference there was between graphics, sound and processors back then. Nowadays you’ll see GPU’s being faster than others, sometimes by a lot, but the contrast between CGA and VGA must be seen to be believed.

So in order for your DOS retro experience to be as good as it gets, your software should be configured to use the hardware in your retro PC as well as it can. That’s why we have a configuration format for it, and this is how it works.

ram = "1MiB"
video = "vga"

[floppy]
floppy_type = "1.2M"

[cpu]
family = "386sx"
clock = 20

[[audio]]
device = "bleeper"

DOSContainer interprets the above as follows:

DOSContainer hardware specification
-----------------------------------
 CPU    : Intel 80386SX at 20Mhz.
 RAM    : 1048576 bytes
 Video  : IBM VGA or compatible
 Audio  : PC Speaker
 Floppy : 5.25" double-sided 1.2MB

This snipped of TOML describes what the first PC that I owned was like. It was quite a nice build in 1990 and it would run many of the contemporary games and applications of its day. Let’s go over the format for a bit.

The top two lines specify ram and video, which are simple fields for now because I’m not (yet) making any distinctions in the type of RAM available or specifics regarding video hardware. Nor do I intend to support multi-monitor setups, or systems with multiple video cards (yet). So for now you specify how much RAM you have, an the general type of video card you have in your machine.

The CPU is a slightly more complicated animal. It comes in families that can have different clock rates within them. So in this case it’s not enough to say that we’re using a 386SX. We should also specify that it runs at 20MHz. DOSContainer exposes this information later on to manifests that support it, so that games or applications can be configured to fit the system constraints by either choosing conservative graphics settings if your CPU is slow, or purposefully slowing it down -and by how much- in case it’s (much) too fast.

You’ll see that the audio device has two square brackets around it. That’s because, unlike CPU’s, you can have any number of different audio devices in your PC. Sure, it’s hell to configure an actual system with three or more sound cards, but for DOSContainer it’s just an inventory list of what the game or application software should take advantage of.

IBM PC and XT

At the current state of development, DOSContainer will support only the original IBM PC and XT systems at the first release. The HwSpec for those looks like this for a PC with a lot of RAM:

ram = "256KiB"
video = "cga"

[floppy]
floppy_type = "160k"

[cpu]
family = "8088"
clock = 4

[[audio]]
device = "bleeper"

The XT, from a DOSContainer perspective, is hardly different. Just up the RAM and it’ll work. So for now this is the only HwSpec that you’re going to need once DOSContainer 1.00 gets release. When that will be, I don’t know yet.