Initial commit (a clone of the jsmachines project as of v1.15.3)
This commit is contained in:
jeffpar
commit
a5e3e6a59d
714 changed files with 130602 additions and 0 deletions
157
docs/pcjs/README.md
Normal file
157
docs/pcjs/README.md
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
PCjs Documentation
|
||||
---
|
||||
|
||||
[PCjs](/docs/about/pcjs/) is a full-featured IBM PC and PC XT simulator written entirely in JavaScript.
|
||||
|
||||
[IBM PC Model 5150](/configs/pc/machines/5150/mda/64kb/ "PCjs:ibm5150")
|
||||
|
||||
The [simulation](/configs/pc/machines/5150/mda/64kb/) 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 PCjs script and a machine XML file, along with a couple
|
||||
of XSL and CSS support files (included in the ZIP file below).
|
||||
|
||||
### Creating Machine XML Files
|
||||
|
||||
A PCjs machine XML file defines all a machine's components. Components include:
|
||||
|
||||
* [Chipset](/docs/pcjs/chipset/)
|
||||
* [Computer](/docs/pcjs/computer/)
|
||||
* [Control Panel](/docs/pcjs/panel/)
|
||||
* [CPU](/docs/pcjs/cpu/)
|
||||
* [Debugger](/docs/pcjs/debugger/)
|
||||
* [Floppy Disk Controller](/docs/pcjs/fdc/)
|
||||
* [Hard Disk Controller](/docs/pcjs/hdc/)
|
||||
* [Keyboard](/docs/pcjs/keyboard/)
|
||||
* [Mouse](/docs/pcjs/mouse/)
|
||||
* [RAM](/docs/pcjs/ram/)
|
||||
* [ROM](/docs/pcjs/rom/)
|
||||
* [Serial Port](/docs/pcjs/serial/)
|
||||
* [Video Adapter](/docs/pcjs/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 usable, since it lacks a keyboard, screen, or any code (ROMs) to execute.
|
||||
|
||||
A simple machine definition that's actually usable might look like:
|
||||
|
||||
<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>
|
||||
|
||||
Here is a [demo](/docs/pcjs/demos/sample1.html) of this machine's [XML](/docs/pcjs/demos/sample1.xml) file.
|
||||
|
||||
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 Disk 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="loadDrive">Load</control>
|
||||
</control>
|
||||
</fdc>
|
||||
...
|
||||
</machine>
|
||||
|
||||
Here is a [demo](/docs/pcjs/demos/sample2.html) of the updated machine's [XML](/docs/pcjs/demos/sample2.xml) file.
|
||||
|
||||
### Loading Machine XML Files
|
||||
|
||||
Inside a web page, add a <div> to contain the machine, load the **pc.js** script
|
||||
(**pc-dbg.js** if you need the PCjs [Debugger](/docs/pcjs/debugger/)), and then call *window.embedPC()*:
|
||||
|
||||
<div id="sample2"/>
|
||||
<script type="text/javascript" src="pc.js"/>
|
||||
<script type="text/javascript">
|
||||
window.embedPC("sample2", "sample2.xml", "components.xsl");
|
||||
</script>
|
||||
|
||||
In fact, this is exactly what we did in the previous [demo](/docs/pcjs/demos/sample2.html).
|
||||
|
||||
*window.embedPC()* requires 3 parameters:
|
||||
|
||||
- The *id* of the machine <div> (e.g., "sample2");
|
||||
- The *url* of the machine XML file (e.g., "sample2.xml");
|
||||
- The *url* of the components XSL file (e.g., "components.xsl")
|
||||
|
||||
**components.xsl** (and the corresponding **components.css**) are included with the PCjs scripts in the samples download below.
|
||||
|
||||
### Using the PCjs Debugger
|
||||
|
||||
To create a configuration that includes the PCjs Debugger, you need to:
|
||||
|
||||
- Add [Debugger](/docs/pcjs/debugger/) and [Control Panel](/docs/pcjs/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 **pc-dbg.js** instead of **pc.js**.
|
||||
|
||||
Take a look at the [sample3a](/docs/pcjs/demos/sample3a.html) demo (with [XML file](/docs/pcjs/demos/sample3a.xml)) for an example.
|
||||
|
||||
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 dump an entire diskette as JSON ("l json <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, the [sample3b](/docs/pcjs/demos/sample3b.html) demo (with [XML file](/docs/pcjs/demos/sample3b.xml))
|
||||
does just that, using JSON dumps created from [sample3a](/docs/pcjs/demos/sample3a.html) after starting VisiCalc.
|
||||
See the *state* attribute on the [Computer](/docs/pcjs/computer/) component for more information on state files.
|
||||
|
||||
### Running PCjs On Your Own Website
|
||||
|
||||
All of the demos described above are available for [download](/docs/pcjs/demos/).
|
||||
|
||||
### Creating PCjs-Compatible Disk Images
|
||||
|
||||
If you have (or find) an IMG disk image file on a server, [pcjs.org](http://www.pcjs.org/) provides a
|
||||
[DiskDump API](/api/v1/dump) that creates PCjs-compatible disks in JSON:
|
||||
|
||||
http://www.pcjs.org/api/v1/dump?disk=(file|url)&format=json
|
||||
|
||||
For example, let's say you found a disk image online:
|
||||
|
||||
http://www.pcjs.org/disks/pc/dos/ibm/1.00/PCDOS100.img
|
||||
|
||||
To convert it to a PCjs-compatible JSON format, use the following command:
|
||||
|
||||
http://www.pcjs.org/api/v1/dump?disk=http://www.pcjs.org/disks/pc/dos/ibm/1.00/PCDOS100.img&format=json
|
||||
|
||||
Save the resulting JSON file to a folder on your server, and then update your machine XML file(s) to use that file.
|
||||
|
||||
Although PCjs will accept IMG disk image files, it must call the [DiskDump API](/api/v1/dump)
|
||||
to convert the image every time it's loaded, so it's *much* faster and more efficient to use pre-converted
|
||||
JSON-encoded disk images.
|
||||
|
||||
Remember that PC and PC XT machines supported only 160Kb diskettes (on any version of PC-DOS),
|
||||
320Kb diskettes (on PC-DOS 1.1 and higher), and 180Kb and 360Kb diskettes (on PC-DOS 2.0 and higher).
|
||||
The 1.2Mb diskette format was introduced with the PC AT, and 720Kb and 1.44Mb diskette formats were
|
||||
introduced with the PS/2; those formats will be supported in a future release of PCjs, when the necessary
|
||||
hardware support has been added.
|
||||
Loading…
Reference in a new issue