Consolidated /docs into /pubs
This commit is contained in:
Jeff Parsons
Jeff Parsons
parent
9d356c582b
commit
71d117fa02
106 changed files with 350 additions and 317 deletions
163
pubs/c1pjs/README.md
Normal file
163
pubs/c1pjs/README.md
Normal file
|
|
@ -0,0 +1,163 @@
|
|||
---
|
||||
layout: page
|
||||
title: C1Pjs Documentation
|
||||
permalink: /pubs/c1pjs/
|
||||
machines:
|
||||
- id: c1p8kb
|
||||
type: c1p-dbg
|
||||
config: /devices/c1p/machine/8kb/large/debugger/machine.xml
|
||||
redirect_from:
|
||||
- /c1p/
|
||||
- /c1pjs/
|
||||
---
|
||||
|
||||
C1Pjs Documentation
|
||||
---
|
||||
|
||||
C1Pjs is a JavaScript simulation of the Challenger 1P, an 8-bit 6502-based microcomputer
|
||||
manufactured by Ohio Scientific in 1978. The base configuration included an 8Kb BASIC-in-ROM from Microsoft
|
||||
and 4Kb of RAM (user-expandable to 8Kb). Below is a simulation of the 8Kb RAM configuration.
|
||||
|
||||
After you've read the Documentation, check out our other [C1P Machine Configurations](/devices/c1p/machine/),
|
||||
learn how [Customize and Embed](embed/) your own machines, read the [Source Code](/modules/c1pjs/), and
|
||||
experiment!
|
||||
|
||||
{% include machine.html id="c1p8kb" %}
|
||||
|
||||
### Using C1Pjs
|
||||
|
||||
**NOTE:** For those of you who never used a *real* Challenger 1P machine, if any of the operational
|
||||
details of the machine seem bizarre, that's not the simulator's fault. It's how the machine
|
||||
actually operated.
|
||||
|
||||
Some of those details are artifacts of teletype-based interfaces, which were more common
|
||||
than a video monitor interface in the 1970's. On a teletype, there was no way to physically
|
||||
erase printed characters, so you had to count underscores to know how many characters had been
|
||||
erased internally.
|
||||
|
||||
Also, the wide margins on either side of the screen were a side-effect of how the machine
|
||||
displayed video on a conventional television set; they helped ensure that no characters would be
|
||||
displayed off-screen and therefore unreadable. As a result, even though the machine contained
|
||||
enough video memory for 32 rows of characters, each with 32 columns, the usable portion was much
|
||||
smaller.
|
||||
|
||||
The original C1P, with its more modern keyboard and video monitor interface, obviously could
|
||||
have done a better job processing and displaying user input (and in fact, I wrote some
|
||||
machine-language extensions back in the day that did exactly that). And Ohio Scientific did improve
|
||||
later models, but the original C1P functioned exactly as shown, with all its teletype-like
|
||||
idiosyncrasies and television-related limitations.
|
||||
|
||||
#### Starting the Simulator
|
||||
|
||||
* Press the **RUN** or **BREAK** button to start the C1Pjs Simulator.
|
||||
* Press **C** to select a COLD START.
|
||||
* At the MEMORY SIZE prompt, press **Return** to use all available memory.
|
||||
* At the TERMINAL WIDTH prompt, press **Return** to select the default screen width.
|
||||
|
||||
Wait for the BASIC "OK" prompt before using the **Load File** button;
|
||||
this will allow the Simulator to automatically "LOAD" and "RUN" the selected program.
|
||||
|
||||
NOTE: The wide margins on the left and right sides of the screen are normal.
|
||||
The Challenger 1P's display was organized as 32 rows x 32 columns of text,
|
||||
but its video circuitry lacked a "guard band" feature, which meant that only
|
||||
about 24 characters per line, and 24 total lines, in the center of the screen
|
||||
could be seen on a typical television monitor. As a result, the ROMs avoided
|
||||
drawing outside a 24x24 area. In the window above, the top 4 and bottom 4 rows
|
||||
are automatically cropped, but the left and right sides are not, because I
|
||||
eventually want to patch the ROMs to enable 32 characters per row.
|
||||
|
||||
#### Typing in the Simulator
|
||||
|
||||
The C1P normally uses only upper-case characters and expects its SHIFT-LOCK key to be locked,
|
||||
so the Simulator initially locks it, independent of your CAPS-LOCK key.
|
||||
|
||||
The C1P keyboard lacks characters found on modern keyboards such as ~ and \_.
|
||||
Unsupported keys are simply ignored.
|
||||
|
||||
Characters can be erased using the **DELETE** key instead of the documented **SHIFT-O**.
|
||||
For each character that's erased internally, an underscore is displayed.
|
||||
|
||||
Lines can be erased using the **@** key instead of the documented **SHIFT-P**.
|
||||
|
||||
The BASIC power operator can be typed using the **^** key instead of the documented **SHIFT-N**;
|
||||
for example, typing "PRINT 5^2" should display "25".
|
||||
|
||||
RUN and LIST commands can be aborted by pressing **CTRL-C**, unless the current program has
|
||||
disabled BASIC keyboard polling. Use the BASIC command "POKE 530,0" to re-enable BASIC keyboard polling,
|
||||
or press **BREAK** and then **W** for a WARM START.
|
||||
|
||||
Pressing **CTRL-O** disables input echo until it is pressed again;
|
||||
presumably this feature was added to prevent the display of passwords or other sensitive information.
|
||||
|
||||
If the Simulator is not responding to any keys, try clicking on the black display area to restore focus;
|
||||
if all else fails, press **BREAK** and then **W** for a WARM START.
|
||||
|
||||
#### Using The Control Panel
|
||||
|
||||
Press the **Run** button to start the Simulator; it will change to **Halt** while running.
|
||||
|
||||
Press the **Step** button while the simulated CPU is halted to execute a single instruction;
|
||||
hold the **Step** button to step through multiple instructions.
|
||||
|
||||
Press the **Reset** button to halt and reset the simulated CPU; screen memory will be erased,
|
||||
but all other memory will be preserved, permitting a WARM START.
|
||||
|
||||
Press the **Load File** button to load the selected BASIC program into the simulated cassette device;
|
||||
the Simulator will attempt to automatically "LOAD" and "RUN" the selected program.
|
||||
|
||||
Alternatively, use the BASIC "LOAD" command to begin loading a program from the simulated cassette device.
|
||||
Press the spacebar at the end of the "LOAD" operation to restore keyboard control.
|
||||
|
||||
Press the **Load Disk** button to mount the selected disk image into the simulated floppy disk drive;
|
||||
press **BREAK** and then **D** to boot from the image and load the OS-65D operating system.
|
||||
|
||||
#### Using The Debugger
|
||||
|
||||
A built-in Debugger is provided as part of the Control Panel.
|
||||
|
||||
Type **?** and then **Enter** to display the list of Debugger commands.
|
||||
|
||||
The instruction frequency ("f") and history ("p") commands collect data only while the CPU is
|
||||
running (not stepping) and one or more breakpoints have been set; set a dummy execution breakpoint
|
||||
(eg, "bp 0") to enable collection.
|
||||
|
||||
#### Controlling The Speed
|
||||
|
||||
The default speed of the simulated CPU is roughly 1Mhz, or one million simulated CPU cycles per second.
|
||||
|
||||
Press the **FAST** button to allow the Simulator to run as fast as possible; press **SLOW** to return to
|
||||
the default speed of 1Mhz.
|
||||
|
||||
Slow computers, as well as browsers with slow JavaScript interpreters, may not be able to achieve 1Mhz operation;
|
||||
in those situations, the speed controls will have no effect.
|
||||
|
||||
---
|
||||
|
||||
### Embedding
|
||||
|
||||
Want to embed the C1Pjs Simulator on your own web page? Everything you need to know is explained [here](embed/).
|
||||
You can even launch multiple simulations on a single page; check out the C1P "Server Array"
|
||||
[demo](/devices/c1p/machine/8kb/array/).
|
||||
|
||||
---
|
||||
|
||||
### Implementation
|
||||
|
||||
This computer simulation was written in JavaScript, in part to test the performance limits of web-based applications.
|
||||
The result was one of the **fastest** JavaScript implementations of a 6502-based computer simulation on the web.
|
||||
|
||||
This application uses XML to define the machine architecture, XSLT to transform the XML into HTML, and JavaScript
|
||||
to implement the simulation and bind it to the various HTML elements. The C1Pjs screen is implemented using the HTML5
|
||||
<canvas> element, so the application requires a browser that supports HTML5.
|
||||
|
||||
This application was tested with current versions of Safari, Firefox, Chrome and Internet Explorer. Somewhat less
|
||||
current versions will probably work as well, with the exception of Internet Explorer, which did not add support for
|
||||
the <canvas> tag until IE9.
|
||||
|
||||
---
|
||||
|
||||
### Challenger 1P Reference Manuals
|
||||
|
||||
[<img src="https://s3-us-west-2.amazonaws.com/archive.pcjs.org/pubs/c1p/techref/thumbs/OSI_BASIC-IN-ROM_Reference_Manual-thumb.jpg" width="200" height="260" alt="OSI BASIC-IN-ROM Manual"/>](https://s3-us-west-2.amazonaws.com/archive.pcjs.org/pubs/c1p/techref/pdfs/OSI_BASIC-IN-ROM_Reference_Manual.pdf)
|
||||
[<img src="https://s3-us-west-2.amazonaws.com/archive.pcjs.org/pubs/c1p/techref/thumbs/OSI_C1P_Character_Graphics_Reference_Manual-thumb.jpg" width="200" height="260" alt="OSI C1P Graphics Manual"/>](https://s3-us-west-2.amazonaws.com/archive.pcjs.org/pubs/c1p/techref/pdfs/OSI_C1P_Character_Graphics_Reference_Manual.pdf)
|
||||
[<img src="https://s3-us-west-2.amazonaws.com/archive.pcjs.org/pubs/c1p/techref/thumbs/OSI_C1P_Users_Manual-thumb.jpg" width="200" height="260" alt="OSI C1P Users Manual"/>](https://s3-us-west-2.amazonaws.com/archive.pcjs.org/pubs/c1p/techref/pdfs/OSI_C1P_Users_Manual.pdf)
|
||||
197
pubs/c1pjs/embed/README.md
Normal file
197
pubs/c1pjs/embed/README.md
Normal file
|
|
@ -0,0 +1,197 @@
|
|||
---
|
||||
layout: page
|
||||
title: Embedding The C1Pjs Simulator
|
||||
permalink: /pubs/c1pjs/embed/
|
||||
machines:
|
||||
- id: c1p8kb
|
||||
type: c1p
|
||||
config: /devices/c1p/machine/8kb/embed/machine.xml
|
||||
redirect_from:
|
||||
- /configs/c1p/embed/
|
||||
- /demos/c1p/embed.html
|
||||
---
|
||||
|
||||
Embedding The C1Pjs Simulator
|
||||
---
|
||||
|
||||
{% include machine.html id="c1p8kb" %}
|
||||
|
||||
If you want to read as little as possible, then just paste the following code onto a web page:
|
||||
|
||||
```html
|
||||
<div id="myC1P"/></div><div style="clear:both"></div>
|
||||
<script type="text/javascript"
|
||||
src="http://www.pcjs.org/versions/c1pjs/1.34.0/c1p.js">
|
||||
</script>
|
||||
<script type="text/javascript">
|
||||
window.embedC1P(
|
||||
"myC1P",
|
||||
"http://www.pcjs.org/devices/c1p/machine/8kb/embed/machine.xml",
|
||||
"http://www.pcjs.org/versions/c1pjs/1.34.0/components.xsl"
|
||||
);
|
||||
</script>
|
||||
```
|
||||
|
||||
Otherwise, read on to learn how embedding works, and how you can create your own machine configuration and customize
|
||||
its appearance.
|
||||
|
||||
Step 1: Create a machine definition XML file
|
||||
---
|
||||
You need an XML file that defines a Challenger configuration, listing all the components it will contain and where
|
||||
they will be mapped into the address space.
|
||||
|
||||
The order of the XML elements also determines the layout of the associated HTML elements; for example, if the
|
||||
**<keyboard>** element appears before the **<video>** element, then the keyboard controls will be
|
||||
displayed *above* the video display instead of *below*. There's an extensive set of attributes that you can add
|
||||
to any of the elements below to style and position them, including the usual *style* attribute, but at present,
|
||||
there's no documentation beyond the sample XML files and the default [XML stylesheet](/versions/c1pjs/1.34.0/components.xsl).
|
||||
|
||||
The example at the top of this page uses an [XML file](/devices/c1p/machine/8kb/embed/machine.xml) that looks like:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<machine id="OSI" class="c1pjs" border="1" width="272px" pos="right" padleft="16px" padright="16px" padbottom="16px">
|
||||
<computer id="c1p" name="Challenger 1P">
|
||||
<module type="cpu" refid="cpu6502" start="0x0000" end="0xffff"/>
|
||||
<module type="ram" refid="ram8K" start="0x0000" end="0x1fff"/>
|
||||
<module type="rom" refid="romNull" start="0x2000" end="0x9fff"/>
|
||||
<module type="rom" refid="romBasic" start="0xa000" end="0xbfff"/>
|
||||
<module type="video" refid="video" start="0xd000" end="0xd3ff"/>
|
||||
<module type="keyboard" refid="keyboard" start="0xdf00" end="0xdfff"/>
|
||||
<module type="serial" refid="serialPort" start="0xf000" end="0xf0ff"/>
|
||||
<module type="rom" refid="romSystem" start="0xf800" end="0xffff"/>
|
||||
</computer>
|
||||
<cpu id="cpu6502"/>
|
||||
<ram id="ram8K" size="0x2000"/>
|
||||
<rom id="romNull" size="0x8000"/>
|
||||
<rom id="romBasic" size="0x2000" image="http://www.pcjs.org/devices/c1p/rom/basic-gcpatch.hex"/>
|
||||
<rom id="romSystem" size="0x0800" image="http://www.pcjs.org/devices/c1p/rom/system.hex"/>
|
||||
<video id="video" screenwidth="256" screenheight="192" cols="32" rows="32"
|
||||
charset="http://www.pcjs.org/devices/c1p/video/chargen1x.png" padtop="8px" padleft="8px" padbottom="8px"/>
|
||||
<keyboard id="keyboard" pos="center">
|
||||
<control type="button" class="input" binding="ctrl-c">CTRL-C</control>
|
||||
<control type="button" class="input" binding="ctrl-o">CTRL-O</control>
|
||||
<control type="button" class="input" binding="break">BREAK</control>
|
||||
</keyboard>
|
||||
<serial id="serialPort" demo="true"/>
|
||||
</machine>
|
||||
```
|
||||
|
||||
Machine configuration files can also be "self-starting" if they contain the following XML stylesheet reference at the
|
||||
top of the file:
|
||||
|
||||
```xml
|
||||
<?xml-stylesheet type="text/xsl" href="http://www.pcjs.org/versions/c1pjs/1.34.0/machine.xsl"?>
|
||||
```
|
||||
|
||||
For example, here's a self-starting [machine.xml](/devices/c1p/machine/8kb/large/machine.xml) configuration.
|
||||
After it loads, use your browser's "View Source" command and you'll see that it's very similar to the
|
||||
[XML example](/devices/c1p/machine/8kb/embed/machine.xml) above.
|
||||
|
||||
Want to embed *multiple* simulators on a single page? No problem. Each **<machine>** element simply needs
|
||||
a unique *id* attribute. Take a look at [array.xml](/devices/c1p/machine/8kb/array/) for an example.
|
||||
|
||||
Step 2: Make sure you have all the necessary resource files
|
||||
---
|
||||
In the above XML file, the ROM and Video components refer to additional resources:
|
||||
|
||||
- 8K BASIC ROM image @ http://www.pcjs.org/devices/c1p/rom/basic-gcpatch.hex
|
||||
- 2K SYSTEM ROM image @ http://www.pcjs.org/devices/c1p/rom/system.hex
|
||||
- 256-Character Generator image @ http://www.pcjs.org/devices/c1p/video/chargen1x.png
|
||||
|
||||
The URLs for those resource files can omit the server name if they're on the same server as the web page.
|
||||
The simulator will not start running until all the above resources have been loaded. Other resources, such as files
|
||||
or disk images listed by the <serial> or <disk> components, are not loaded until/unless they are selected.
|
||||
|
||||
NOTE: For larger simulator windows (eg, screenwidth of 512 and screenheight of 384), use a larger image file for the charset attribute; the smaller image file will work as well, but in the process of being enlarged, it won't look as sharp.
|
||||
|
||||
If you decide to include the <disk> component, you can simply link to an existing component definition XML file,
|
||||
such as samples.xml:
|
||||
|
||||
```xml
|
||||
<machine id="OSI" border="1" width="272px">
|
||||
<computer id="c1p" name="Challenger 1P">
|
||||
...
|
||||
<module type="ram" refid="ram32K" start="0x0000" end="0x7fff"/>
|
||||
<module type="rom" refid="romNull" start="0x8000" end="0x9fff"/>
|
||||
<module type="rom" refid="romBasic" start="0xa000" end="0xbfff"/>
|
||||
<module type="disk" refid="disk" start="0xc000" end="0xc0ff"/>
|
||||
<module type="video" refid="video" start="0xd000" end="0xd7ff"/>
|
||||
...
|
||||
</computer>
|
||||
...
|
||||
<disk ref="http://www.pcjs.org/apps/c1p/samples.xml"/>
|
||||
...
|
||||
</machine>
|
||||
```
|
||||
|
||||
Step 3: Add the C1Pjs Simulator to your web page
|
||||
---
|
||||
Somewhere on your page, you need to add the following **<script>** element:
|
||||
|
||||
```html
|
||||
<script type="text/javascript" src="http://www.pcjs.org/versions/c1pjs/1.34.0/c1p.js"></script>
|
||||
```
|
||||
|
||||
To include the C1Pjs Debugger, use [c1p-dbg.js](/versions/c1pjs/1.34.0/c1p-dbg.js) instead of
|
||||
[c1p.js](/versions/c1pjs/1.34.0/c1p.js), and include some additional definitions in your machine
|
||||
definition XML file:
|
||||
|
||||
```xml
|
||||
<machine id="OSI" border="1" width="272px">
|
||||
<computer id="c1p" name="Challenger 1P">
|
||||
...
|
||||
</computer>
|
||||
...
|
||||
<debugger id="debugger"/>
|
||||
<panel ref="http://www.pcjs.org/devices/c1p/panel/default.xml"/>
|
||||
...
|
||||
</machine>
|
||||
```
|
||||
|
||||
The [Panel](/devices/c1p/panel/default.xml) XML file included above defines a variety of buttons and
|
||||
input/output controls that are bound to the CPU and Debugger components according to their *binding*
|
||||
attributes.
|
||||
|
||||
You can also create your own XML file that defines a completely different Control Panel layout, and either
|
||||
paste it into your machine definition file, inside a pair of **<panel *id*="panel"...>** ... **</panel>**
|
||||
elements, or link to it using a single **<panel/>** element with the *ref* attribute.
|
||||
|
||||
Step 4: Activate the C1Pjs Simulator
|
||||
---
|
||||
Add the following to your page's **<body>** element:
|
||||
|
||||
```html
|
||||
<body onload="window.embedC1P('myC1P','embed.xml')">
|
||||
```
|
||||
|
||||
and insert a **<div id="myC1P"></div>** where you want the simulator to appear.
|
||||
|
||||
The **embedC1P()** function accepts three parameters:
|
||||
- the *id* attribute of the HTML element that will contain the simulator (eg, 'myC1P');
|
||||
- the URL of your machine definition XML file (eg, 'embed.xml', since it's on the same server);
|
||||
- the URL of an XML stylesheet; unless you've created your own stylesheet, it's recommended you omit this
|
||||
parameter and use the default [XML stylesheet](/versions/c1pjs/1.34.0/components.xsl).
|
||||
|
||||
Step 5: Enjoy!
|
||||
---
|
||||
All I ask is that any page that embeds the simulator also includes attribution, such as:
|
||||
|
||||
> [PCjs](http://pcjs.org) © 2012-2017 by [Jeff Parsons](mailto:Jeff@pcjs.org) ([@jeffpar](http://twitter.com/jeffpar))
|
||||
|
||||
If you use the default [XML stylesheet](/versions/c1pjs/1.34.0/components.xsl), attribution is automatically inserted,
|
||||
which relieves you from including it yourself.
|
||||
|
||||
Feel free to copy any or all of the files listed above to your own server (it's probably better to share the server
|
||||
load, after all). Just be aware that none of these files have been frozen -- there are more features to add and
|
||||
probably still a few bugs waiting to be fixed. The advantage of copying them is that you might avoid regressions down
|
||||
the road, but the disadvantage is that you'll miss out on any changes, unless you check back periodically.
|
||||
|
||||
Problems? Something I neglected to explain? Features you'd like to see added, or better yet, add yourself? You can
|
||||
reach me at either [@jeffpar](http://twitter.com/jeffpar) or [Jeff@pcjs.org](mailto:Jeff@pcjs.org).
|
||||
|
||||
Thanks!
|
||||
|
||||
*Jeff Parsons<br/>August 28, 2012*
|
||||
|
||||
[Return to [C1Pjs Documentation](../)]
|
||||
Loading…
Reference in a new issue