PCx86 configuration options

[jeffpar]

The PCx86 machine emulator is a collection of device components, and each device looks for its own set of configuration properties, which in turn affect how the device will be initialized.

The Video component, for example, supports lots of configuration properties; here are just a few:

• model (eg, "mda" for Monochrome Display Adapter)
• mode: initial video mode
• screenWidth: width of the screen canvas, in pixels
• screenHeight: height of the screen canvas, in pixels
• screenColor: background color of the screen canvas (default is black)

For a machine defined using an XML file, those properties are passed as attributes in a <video> element.

For a machine defined using a JSON file, those properties are specified in a JSON object with a class of "video".

Regardless of whether you use XML or JSON files to define a machine, they both get transformed into HTML before the machine is initialized. For each component, a <div> element is created with a data-value attribute containing values for all the configuration properties that component supports; eg:

<div class="pcx86-video-object pcjs-screen" data-value="{ id:'ibm-5150-cga.videoCGA',name:'',model:'',memory:'',screenWidth:1280,screenHeight:800,screenColor:'black',fontROM:'/machines/pcx86/ibm/video/cga/IBM-CGA.json',fontColor:'',charCols:80,charRows:25,touchScreen:'mouse',scale:false,switches:'',autoLock:true,aspectRatio:0,smoothing:null,flicker:0.5 }">

XML files are transformed as the page is loaded by your web browser, based on rules defined by an XSL file on the web server, whereas JSON files are preprocessed by the web server and the HTML is delivered with all the <div> elements and data-value attributes preset.

There is also a special device component (Computer) which manages the entire machine, and it supports a subset of properties that can override individual device properties. For example, the following Video properties can be overridden, either by passing them as machine properties (via the 4th parameter of the embedPCx86() function) or as URL parameters:

• fontColor
• flicker

While it might seem like a nice idea to allow every device property to be modified with a machine override, it becomes too easy to completely break a machine. Think about the ROM component: most machines have multiple ROMs, and most ROMs are designed to run at a specific address, so allowing the user to override the ROM component's addr property would break all the ROMs and make the machine non-functional.

Since there are no mechanisms for catching invalid property combinations, it's best to limit the set of machine overrides to those that are unlikely to break something.