PCjs documentation updates
This commit is contained in:
Jeff Parsons
parent
f9ef6c9f1b
commit
68929ac77f
29 changed files with 150 additions and 133 deletions
|
|
@ -12,7 +12,7 @@ PCjs Documentation
|
|||
---
|
||||
|
||||
[PCjs](/docs/about/pcjs/) is a full-featured IBM PC, PC XT and PC AT emulator written entirely in JavaScript.
|
||||
After you've read the Documentation, play with the [Demos](demos/).
|
||||
After you've read the Documentation, play with the [Examples](examples/).
|
||||
|
||||
{% include machine.html id="ibm5150" %}
|
||||
|
||||
|
|
@ -23,29 +23,29 @@ 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:
|
||||
A PCjs machine XML file defines all a machine's components, including:
|
||||
|
||||
* [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/)
|
||||
* [Parallel Port](/docs/pcjs/parallel/)
|
||||
* [Serial Port](/docs/pcjs/serial/)
|
||||
* [Video Adapter](/docs/pcjs/video/)
|
||||
* [Chipset](chipset/)
|
||||
* [Computer](computer/)
|
||||
* [Control Panel](panel/)
|
||||
* [CPU](cpu/)
|
||||
* [Debugger](debugger/)
|
||||
* [Floppy Disk Controller](fdc/)
|
||||
* [Hard Disk Controller](hdc/)
|
||||
* [Keyboard](keyboard/)
|
||||
* [Mouse](mouse/)
|
||||
* [RAM](ram/)
|
||||
* [ROM](rom/)
|
||||
* [Parallel Port](parallel/)
|
||||
* [Serial Port](serial/)
|
||||
* [Video Adapter](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"/>
|
||||
<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.
|
||||
|
|
@ -53,93 +53,108 @@ However, that machine isn't usable, since it lacks a keyboard, screen, or any co
|
|||
A simple machine definition that actually works 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"/>
|
||||
<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.
|
||||
Here is an [example](examples/example1.html) of this machine's [XML](examples/example1.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>
|
||||
...
|
||||
<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>
|
||||
...
|
||||
<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.
|
||||
Here is an [example](examples/example2.html) of the updated machine's [XML](examples/example2.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()*:
|
||||
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](debugger/)), and then call *embedPC()*:
|
||||
|
||||
<div id="sample2"/>
|
||||
<div id="example2"/>
|
||||
<script type="text/javascript" src="pc.js"/>
|
||||
<script type="text/javascript">
|
||||
window.embedPC("sample2", "sample2.xml", "components.xsl");
|
||||
embedPC("example2", "example2.xml", "components.xsl");
|
||||
</script>
|
||||
|
||||
In fact, this is exactly what we did in the previous [demo](/docs/pcjs/demos/sample2.html).
|
||||
In fact, this is exactly what we did in the previous [example](examples/example2.html).
|
||||
|
||||
*window.embedPC()* requires 3 parameters:
|
||||
*embedPC()* accepts 4 parameters:
|
||||
|
||||
- The *id* of the machine <div> (e.g., "sample2");
|
||||
- The *url* of the machine XML file (e.g., "sample2.xml");
|
||||
- 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
|
||||
|
||||
**components.xsl** (and the corresponding **components.css**) are included with the PCjs scripts in the samples download below.
|
||||
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/pc/dos/ibm/1.00/PCDOS100.json"}}}'
|
||||
|
||||
*components.xsl* (and the corresponding *components.css*) are included with the PCjs scripts in the
|
||||
[Examples](#running-pcjs-on-your-own-server) 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">
|
||||
|
||||
### 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](debugger/) and [Control Panel](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**.
|
||||
- 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.
|
||||
Take a look at the [example3a](examples/example3a.html) example
|
||||
(with [XML file](examples/example3a.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 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*).
|
||||
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, 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.
|
||||
In fact, the [example3b](examples/example3b.html) example (with [XML file](examples/example3b.xml))
|
||||
does just that, using JSON dumps created from [example3a](examples/example3a.html) after starting VisiCalc.
|
||||
See the *state* attribute on the [Computer](computer/) component for more information on state files.
|
||||
|
||||
### Running PCjs On Your Own Server
|
||||
|
||||
All of the demos described above are available for [download](/docs/pcjs/demos/).
|
||||
All of the examples described above are available for [download](examples/).
|
||||
|
||||
### Creating PCjs-Compatible Disk Images
|
||||
|
||||
|
|
|
|||
|
|
@ -1,34 +0,0 @@
|
|||
---
|
||||
layout: page
|
||||
title: PCjs Documentation Demos
|
||||
permalink: /docs/pcjs/demos/
|
||||
machines:
|
||||
- type: pc
|
||||
id: sample3
|
||||
config: /docs/pcjs/demos/sample3b.xml
|
||||
---
|
||||
|
||||
PCjs Documentation Demos
|
||||
---
|
||||
|
||||
This folder provides all the self-contained [PCjs](/docs/about/pcjs/) demos described in the [Documentation](/docs/pcjs/).
|
||||
|
||||
To use them, download [samples.zip](samples.zip), unzip it into a folder on your desktop computer or web server,
|
||||
and experiment with them in your web browser. Since all these samples are self-contained, they should work with either
|
||||
the "file:" or "http:" protocol.
|
||||
|
||||
+ Check out the sample HTML and XML files:
|
||||
- [sample1.html](sample1.html) and [sample1.xml](sample1.xml)
|
||||
- [sample2.html](sample2.html) and [sample2.xml](sample2.xml)
|
||||
- [sample3a.html](sample3a.html) and [sample3a.xml](sample3a.xml)
|
||||
- [sample3b.html](sample3b.html) and [sample3b.xml](sample3b.xml)
|
||||
+ Feel free to copy/paste additional components from other machine XML files on [pcjs.org](http://www.pcjs.org/).
|
||||
+ Remember to display the appropriate attribution on anything you share publicly; e.g.:
|
||||
[PCjs](http://pcjs.org) © 2012-2016 by [Jeff Parsons](mailto:Jeff@pcjs.org) ([@jeffpar](http://twitter.com/jeffpar))
|
||||
+ Stay in sync with the [PCjs repository](https://github.com/jeffpar/pcjs), to keep your copy of PCjs up-to-date.
|
||||
|
||||
Have fun!
|
||||
|
||||
{% include machine.html id="sample3" %}
|
||||
|
||||
[Return to [PCjs Documentation](..)]
|
||||
File diff suppressed because one or more lines are too long
Binary file not shown.
|
|
@ -1,4 +0,0 @@
|
|||
#!/bin/sh
|
||||
if [ ! -d zips ]; then mkdir zips; fi
|
||||
zip -q zips/$1 * -x samples*.zip zip.sh
|
||||
cp zips/$1 samples.zip
|
||||
36
docs/pcjs/examples/README.md
Normal file
36
docs/pcjs/examples/README.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
layout: page
|
||||
title: PCjs Documentation Examples
|
||||
permalink: /docs/pcjs/examples/
|
||||
machines:
|
||||
- type: pc
|
||||
id: example3
|
||||
config: /docs/pcjs/examples/example3b.xml
|
||||
redirect_from:
|
||||
- /docs/pcjs/demos/
|
||||
---
|
||||
|
||||
PCjs Documentation Examples
|
||||
---
|
||||
|
||||
This folder provides all the self-contained [PCjs](/docs/about/pcjs/) examples described in the [Documentation](/docs/pcjs/).
|
||||
|
||||
To use them, download [examples.zip](examples.zip), unzip it into a folder on your desktop computer or web server,
|
||||
and experiment with them in your web browser. Since all these examples are self-contained, they should work with either
|
||||
the "file:" or "http:" protocol.
|
||||
|
||||
+ Check out the example HTML and XML files:
|
||||
- [example1.html](example1.html) and [example1.xml](example1.xml)
|
||||
- [example2.html](example2.html) and [example2.xml](example2.xml)
|
||||
- [example3a.html](example3a.html) and [example3a.xml](example3a.xml)
|
||||
- [example3b.html](example3b.html) and [example3b.xml](example3b.xml)
|
||||
+ Feel free to copy/paste additional components from other machine XML files on [pcjs.org](http://www.pcjs.org/).
|
||||
+ Remember to display the appropriate attribution on anything you share publicly; e.g.:
|
||||
[PCjs](http://pcjs.org) © 2012-2016 by [Jeff Parsons](mailto:Jeff@pcjs.org) ([@jeffpar](http://twitter.com/jeffpar))
|
||||
+ Stay in sync with the [PCjs repository](https://github.com/jeffpar/pcjs), to keep your copy of PCjs up-to-date.
|
||||
|
||||
Have fun!
|
||||
|
||||
{% include machine.html id="example3" %}
|
||||
|
||||
[Return to [PCjs Documentation](..)]
|
||||
|
|
@ -2,15 +2,15 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||||
<title>pcjs.org | /docs/pcjs/demos/sample1.html</title>
|
||||
<title>pcjs.org | /docs/pcjs/demos/example1.html</title>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" type="text/css" href="components.css">
|
||||
<script type="text/javascript" src="pc.js"></script>
|
||||
</head>
|
||||
<body style="font-family: Helvetica, Arial, sans-serif;">
|
||||
<div id="sample1"></div>
|
||||
<div id="example1"></div>
|
||||
<script type="text/javascript">
|
||||
window.embedPC("sample1", "sample1.xml", "components.xsl");
|
||||
embedPC("example1", "example1.xml", "components.xsl");
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<machine id="sample1" class="pc" width="720px">
|
||||
<machine id="example1" class="pc" width="720px">
|
||||
<computer id="pc" name="IBM PC"/>
|
||||
<cpu id="cpu8088" model="8088" autostart="true"/>
|
||||
<ram id="ramLow" addr="0x00000" size="0x10000"/>
|
||||
|
|
@ -2,15 +2,15 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||||
<title>pcjs.org | /docs/pcjs/demos/sample2.html</title>
|
||||
<title>pcjs.org | /docs/pcjs/demos/example2.html</title>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" type="text/css" href="components.css">
|
||||
<script type="text/javascript" src="pc.js"></script>
|
||||
</head>
|
||||
<body style="font-family: Helvetica, Arial, sans-serif;">
|
||||
<div id="sample2"></div>
|
||||
<div id="example2"></div>
|
||||
<script type="text/javascript">
|
||||
window.embedPC("sample2", "sample2.xml", "components.xsl");
|
||||
embedPC("example2", "example2.xml", "components.xsl");
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<machine id="sample2" class="pc" width="720px">
|
||||
<machine id="example2" class="pc" width="720px">
|
||||
<computer id="pc" name="IBM PC"/>
|
||||
<ram id="ramLow" addr="0x00000" size="0x10000"/>
|
||||
<rom id="romBASIC" addr="0xf6000" size="0x8000" file="ibm-basic-1.00.json"/>
|
||||
1
docs/pcjs/examples/example3.json
Normal file
1
docs/pcjs/examples/example3.json
Normal file
File diff suppressed because one or more lines are too long
|
|
@ -2,15 +2,15 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||||
<title>pcjs.org | /docs/pcjs/demos/sample3a.html</title>
|
||||
<title>pcjs.org | /docs/pcjs/demos/example3a.html</title>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" type="text/css" href="components.css">
|
||||
<script type="text/javascript" src="pc-dbg.js"></script>
|
||||
</head>
|
||||
<body style="font-family: Helvetica, Arial, sans-serif;">
|
||||
<div id="sample3"></div>
|
||||
<div id="example3"></div>
|
||||
<script type="text/javascript">
|
||||
window.embedPC("sample3", "sample3a.xml", "components.xsl");
|
||||
embedPC("example3", "example3a.xml", "components.xsl");
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<machine id="sample3" class="pc" border="0" width="900px">
|
||||
<machine id="example3" class="pc" border="0" width="900px">
|
||||
<computer id="pc" name="IBM PC"/>
|
||||
<cpu id="cpu8088" model="8088" autostart="true"/>
|
||||
<debugger id="debugger"/>
|
||||
|
|
@ -2,15 +2,15 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||||
<title>pcjs.org | /docs/pcjs/demos/sample3b.html</title>
|
||||
<title>pcjs.org | /docs/pcjs/demos/example3b.html</title>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" type="text/css" href="components.css">
|
||||
<script type="text/javascript" src="pc.js"></script>
|
||||
</head>
|
||||
<body style="font-family: Helvetica, Arial, sans-serif;">
|
||||
<div id="sample3"></div>
|
||||
<div id="example3"></div>
|
||||
<script type="text/javascript">
|
||||
window.embedPC("sample3", "sample3b.xml", "components.xsl");
|
||||
embedPC("example3", "example3b.xml", "components.xsl");
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<machine id="sample3" class="pc" width="720px">
|
||||
<computer id="pc" name="IBM PC" state="sample3.json"/>
|
||||
<machine id="example3" class="pc" width="720px">
|
||||
<computer id="pc" name="IBM PC" state="example3.json"/>
|
||||
<cpu id="cpu8088" model="8088" autostart="true"/>
|
||||
<ram id="ramLow" addr="0x00000" size="0x10000"/>
|
||||
<rom id="romBASIC" addr="0xf6000" size="0x8000" file="ibm-basic-1.00.json"/>
|
||||
4
docs/pcjs/examples/zip.sh
Executable file
4
docs/pcjs/examples/zip.sh
Executable file
|
|
@ -0,0 +1,4 @@
|
|||
#!/bin/sh
|
||||
if [ ! -d zips ]; then mkdir zips; fi
|
||||
zip -q zips/$1 * -x examples*.zip zip.sh
|
||||
cp zips/$1 examples.zip
|
||||
Loading…
Reference in a new issue