| layout | title | permalink | redirect_from | machines | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
page |
PCx86 Documentation |
/docs/pcx86/ |
|
|
PCx86 is a full-featured IBM PC and PC-compatible emulator written entirely in JavaScript. It supports a variety of XT and AT class machines, with processors ranging from the 8088 through the 80386. The PCjs website provides a variety of "stock" configurations, featuring classic machines running at their original clock speed, or you can create your own, by mixing, matching, and reconfiguring any of the PCx86 components listed below.
After you've read the Documentation, check out the Examples, browse the Source Code, and experiment!
{% include machine.html id="ibm5150" %}
The simulation above features an Intel 8088 running at 4.77Mhz, with 64Kb of RAM and an IBM Monochrome Display Adapter. To create your own simulation, all you need is the PCx86 script and a machine XML file, along with a couple of XSL and CSS support files (included in the ZIP file below).
A PCx86 machine XML file defines all a machine's components, including:
- ChipSet
- Computer
- Control Panel
- CPU
- Debugger
- Floppy Drive Controller
- Hard Drive Controller
- Keyboard
- Mouse
- RAM
- ROM
- Parallel Port
- Serial Port
- Video
Here's a simple machine XML file that includes an 8088 CPU and 16Kb of RAM:
<machine id="ibm">
<computer id="pc" name="IBM PC"/>
<cpu id="cpu8088" model="8088"/>
<ram id="ramLow" addr="0x00000" size="0x04000"/>
</machine>However, that machine isn't really usable, since it lacks a keyboard, screen, or any code (ROMs) to execute.
Here's a simple machine XML definition that's more useful:
<machine id="ibm" class="pc" width="720px">
<computer id="pc" name="IBM PC"/>
<cpu id="cpu8088" model="8088"/>
<ram id="ramLow" addr="0x00000" size="0x04000"/>
<rom id="romBASIC" addr="0xf6000" size="0x8000" file="ibm-basic-1.00.json"/>
<rom id="romBIOS" addr="0xfe000" size="0x2000" file="1981-04-24.json"/>
<keyboard id="keyboard"/>
<video id="videoMDA" model="mda" screenwidth="720" screenheight="350" charset="ibm-mda-cga.json">
<name>Monochrome Display</name>
</video>
<chipset id="chipset" model="5150" sw1="01000001" sw2="11110000"/>
</machine>Example 1 shows the XML in action.
Machine definitions can also include visual elements. For example, we can include a Run button with the CPU component. Note that as soon as the machine is ready and the CPU starts running, the Run button will change to Halt.
<machine id="ibm" class="pc" width="720px">
<computer id="pc" name="IBM PC"/>
<cpu id="cpu8088" model="8088">
<control type="button" class="input" binding="run">Run</control>
</cpu>
...
</machine>Next, we can add a Floppy Drive Controller (FDC) component. And since we want to be able to "load" and "unload" floppy disks at will, we'll include some UI controls.
<machine id="ibm" class="pc" width="720px">
<fdc id="fdcNEC" autoMount="{A: {name: 'PC DOS 1.0', path: 'pcdos-1.00.json'}}">
<control type="container">
<control type="list" class="input" binding="listDrives"/>
<control type="list" class="input" binding="listDisks">
<disk path="">None</disk>
<disk path="pcdos-1.00.json">PC DOS 1.0</disk>
</control>
<control type="button" class="input" binding="loadDisk">Load</control>
</control>
</fdc>
...
</machine>Example 2 shows the updated XML in action.
Inside a web page, add a <div> to contain the machine, load the pcx86.js script (pcx86-dbg.js if you need the PCx86 Debugger), and then call embedPCx86():
<div id="example2"/>
<script type="text/javascript" src="pcx86.js"/>
<script type="text/javascript">
embedPCx86("example2", "example2.xml", "components.xsl");
</script>In fact, this is exactly what we did in Example 2.
embedPCx86() accepts 4 parameters:
- The id of the machine <div> (e.g., "example2");
- The url of the machine XML file (e.g., "example2.xml");
- The url of the components XSL file (e.g., "components.xsl")
- Any parms that should be passed to the machine components during initialization
The first 3 parameters are required; the parms parameter is optional. If parms is specified, it should contain a single-quoted JSON object definition, with properties intended to override those specified in the machine XML file; eg:
'{messages:"warn",autoMount:{"A":{"path":"/disks/pcx86/dos/ibm/1.00/PCDOS100.json"}}}'
components.xsl (and the corresponding components.css) are included with the PCx86 scripts in the Examples download. Every version of components.xsl has a corresponding components.css, which your web page should also load, usually with a <link> tag inside the <head> element; eg:
<link rel="stylesheet" type="text/css" href="components.css">To create a configuration that includes the PCx86 Debugger, you need to:
- Add Debugger and Control Panel components to the machine XML file;
- Add debugger controls to the Control Panel, such as Run, Step, Reset, etc;
- Change your web page to load pcx86-dbg.js instead of pcx86.js.
Take a look at Example 3A (XML).
The debugger gives you access to more capabilities than mere debugging. For example, you can use the load command to load diskette sectors into memory ("l [addr] [drive #] ...") or the dump command to dump an entire diskette as JSON ("d disk [drive #]"). You can also halt a machine ("h") and dump its entire state as JSON ("d state"). You can save that state in a .json file, and then use that state to initialize a new machine (as long as it uses the same machine id).
In fact, Example 3B (XML) does just that, using JSON dumps created from Example 3A after starting VisiCalc. See the state property on the Computer component for more information on state files.
All of the examples described above can be downloaded onto your own web server.
If you don't have your own web server and want to try the PCjs Node web server, setup instructions can be found in the PCjs Repository.
See PCjs Disk Formats for information on PCjs disk images and how to create them.