Documentation updates

_posts/2016-02-06-tidying-the-project.md

@@ -0,0 +1,39 @@
+---
+layout: post
+title: Tidying The Project
+date: 2016-02-06 10:00:00
+permalink: /blog/2016/02/06/
+---
+
+The next release of PCjs (v1.20.8) is another fairly minor update.  It includes basic parallel port emulation, in the
+form of a **ParallelPort** component that you include in a machine XML file with the <parallel> element, in much
+the same way you include the **SerialPort** component with the <serial> element.
+
+I've also tidied a few things in the [Devices](/devices/) folder.  ROM images used to be stored under
+`/devices/pc/basic/` and `/devices/pc/bios/`, but BASIC and BIOS ROM images aren't actually devices; they are the
+*contents* of ROM devices.  So, with that in mind, I've made the following rearrangements:
+
+* `/devices/pc/basic/ibm-basic-1.00.json` => `/devices/pc/rom/5150/basic/BASIC100.json`
+* `/devices/pc/basic/ibm-basic-1.10.json` => `/devices/pc/rom/5160/basic/BASIC110.json`
+* `/devices/pc/bios/5150/*` => `/devices/pc/rom/5150/bios/*`
+* `/devices/pc/bios/5160/*` => `/devices/pc/rom/5160/bios/*`
+* `/devices/pc/bios/5170/*` => `/devices/pc/rom/5170/bios/*`
+* `/devices/pc/bios/compaq/*` => `/devices/pc/rom/compaq/bios/*`
+
+This structure mirrors what was done with **Machine** and **Video** devices, where the devices are organized
+first by manufacturer (IBM or COMPAQ) and then by type (MDA, CGA, EGA, etc).
+
+Here, the first **ROM** subdivision is either a manufacturer or a machine model.  A model implies a manufacturer;
+for example, models 5150 through 5170 refer to IBM PC models.
+
+---
+
+The IBM BASIC ROMs require a bit more research.  I'm unclear on the exact history of those ROMs, how many variations
+there were, or whether any of them were machine-dependent.
+
+The project currently includes only two BASIC ROM versions, 1.00 and 1.10, which were initially released with the
+first model 5150 and 5160 machines, respectively.  However, I've also read reports that later revisions of the model
+5150 included BASIC ROM 1.10.
+
+I believe there was also a version 1.20 released for IBM PCjr, but since PCjs does not yet emulate the PCjr, it has
+not been added to the project.

_sass/_base.scss

@@ -140,6 +140,7 @@ code {
 pre {
     padding: 8px 12px;
     overflow-x: scroll;
+    white-space: pre-wrap;
     
     > code {
         border: 0;

devices/pc/rom/README.md

@@ -28,4 +28,5 @@ The project contains the following IBM PC BIOS ROMs:
 As well as BIOS ROMs, with more detailed information, for the following machines:
 
 * [Model 5170](5170/bios/)
-* [Compaq DeskPro 386](compaq/deskpro386/)
+* [Compaq DeskPro 386](compaq/bios/deskpro386/)
+* [Compaq Portable III](compaq/bios/portable3/)

docs/pcjs/parallel/README.md

@@ -0,0 +1,52 @@
+---
+layout: page
+title: PCjs <parallel> Element
+permalink: /docs/pcjs/parallel/
+---
+
+PCjs ParallelPort Component
+---
+
+Format
+---
+	<parallel>...</parallel>
+
+Purpose
+---
+Creates an instance of the ParallelPort component, which simulates an IBM PC Parallel Printer Adapter.
+
+Attributes
+---
+ * *adapter* (required)
+
+	A number (1, 2, or 3) indicating whether this adapter uses port 0x3BC, 0x378, or 0x278.  Adapters 1 and 2
+	default to IRQ 7, and adapter 3 defaults to IRQ 5.
+	
+ * *binding* (optional)
+ 
+	The name of an existing control binding (typically a &lt;textarea&gt;) to optionally redirect port I/O to.
+	For example, if you've defined a Control Panel with a &lt;textarea&gt; control bound to "print", specifying a
+	binding of "print" for the Parallel Port component will bind its port to the same control.
+	
+Also supports the attributes of *[Component](/docs/pcjs/component/)*.
+
+Bindings
+---
+ * *buffer*
+ 
+	For use with a control of type "textarea", to send/receive data to/from the port. If you would rather
+	bind the port to an existing control, then use *binding* attribute instead (see above).
+
+Example
+---
+	<parallel id="lpt1" adapter="1" binding="print"/>
+
+Output
+---
+	<div id="..." class="pc-parallel pc-component">
+		<div class="pc-container">
+			<div class="pcjs-parallel" data-value="id:'...',name:'...',adapter:'...',binding:'...'"></div>
+		</div>
+	</div>
+
+[Return to [PCjs Documentation](..)]

modules/pcjs/lib/serialport.js

@@ -46,16 +46,19 @@ if (NODE) {
  *
  * The SerialPort component has the following component-specific (parmsSerial) properties:
  *
- *      adapter: 1 (for port 0x3F8) or 2 (for port 0x2F8); 0 if not defined
+ *      adapter: 1 (port 0x3F8) or 2 (port 0x2F8); 0 if not defined
  *
  *      binding: name of a control (based on its "binding" attribute) to bind to this port's I/O
  *
  *      tabSize: set to a non-zero number to convert tabs to spaces (applies only to output to
  *      the above binding); default is 0 (no conversion)
  *
- * WARNING: Since the XSL file defines 'adapter' as a number, not a string, there's no need to
+ * In the future, we may support 'port' and 'irq' properties that allow the machine to define a
- * use parseInt(), and as an added benefit, we don't need to worry about whether a hex or decimal
+ * non-standard serial port configuration, instead of only our pre-defined 'adapter' configurations.
- * format was used.
+ *
+ * NOTE: Since the XSL file defines 'adapter' as a number, not a string, there's no need to use
+ * parseInt(), and as an added benefit, we don't need to worry about whether a hex or decimal format
+ * was used.
  *
  * This hard-coded approach mimics the original IBM PC Asynchronous Adapter configuration, which
  * contained a pair of "shunt modules" that allowed the user to select a port address of either

modules/pcjs/templates/components.xsl

@@ -697,6 +697,33 @@
 		</xsl:call-template>
 	</xsl:template>
 
+	<xsl:template match="parallel[@ref]">
+		<xsl:param name="machine" select="''"/>
+		<xsl:variable name="componentFile"><xsl:value-of select="$rootDir"/><xsl:value-of select="@ref"/></xsl:variable>
+		<xsl:apply-templates select="document($componentFile)/parallel"><xsl:with-param name="machine" select="$machine"/></xsl:apply-templates>
+	</xsl:template>
+
+	<xsl:template match="parallel[not(@ref)]">
+		<xsl:param name="machine" select="''"/>
+		<xsl:variable name="adapter">
+			<xsl:choose>
+				<xsl:when test="@adapter"><xsl:value-of select="@adapter"/></xsl:when>
+				<xsl:otherwise>0</xsl:otherwise>
+			</xsl:choose>
+		</xsl:variable>
+		<xsl:variable name="binding">
+			<xsl:choose>
+				<xsl:when test="@binding"><xsl:value-of select="@binding"/></xsl:when>
+				<xsl:otherwise/>
+			</xsl:choose>
+		</xsl:variable>
+		<xsl:call-template name="component">
+			<xsl:with-param name="machine" select="$machine"/>
+			<xsl:with-param name="class">parallel</xsl:with-param>
+			<xsl:with-param name="parms">,adapter:<xsl:value-of select="$adapter"/>,binding:'<xsl:value-of select="$binding"/>'</xsl:with-param>
+		</xsl:call-template>
+	</xsl:template>
+
 	<xsl:template match="serial[@ref]">
 		<xsl:param name="machine" select="''"/>
 		<xsl:variable name="componentFile"><xsl:value-of select="$rootDir"/><xsl:value-of select="@ref"/></xsl:variable>

pubs/pc/reference/intel/80186/README.md

@@ -0,0 +1,23 @@
+---
+layout: page
+title: Intel 80186/80188 CPU Information
+permalink: /pubs/pc/reference/intel/80186/
+---
+
+Intel 80186/80188 CPU Information
+---
+
+80186 Errata
+---
+
+* TBD
+
+80186 Undocumented Instructions
+---
+
+* TBD
+
+Assorted Publications
+---
+
+* TBD

pubs/pc/reference/intel/80286/README.md

@@ -7,7 +7,8 @@ permalink: /pubs/pc/reference/intel/80286/
 Intel 80286 CPU Information
 ---
 
-### 80286 Errata
+80286 Errata
+---
 
 * [Early Errata: A1 and B1 Steppings](early_errata/)
 * [ARPL Behavior](arpl/)
@@ -18,11 +19,13 @@ Intel 80286 CPU Information
 * [POPF Behavior](b2_b3_info/#popf-behavior)
 * [REP MOVS and REP INS Restartability](rep_restart/)
 
-### 80286 Undocumented Instructions
+80286 Undocumented Instructions
+---
 
 * [LOADALL](loadall/)
 
-### 80286 Real-Mode Emulation Notes
+80286 Real-Mode Emulation Notes
+---
 
 * [Executing Real Mode Programs in Protected Mode](real_mode/)
 * [Discrepancies from an iAPX 86/88 Using Emulation](real_mode/#discrepancies-from-an-iapx-86-88-using-emulation)
@@ -30,7 +33,8 @@ Intel 80286 CPU Information
 * [Mixing Real Mode and Protected Mode](real_mode/#mixing-real-mode-and-protected-mode)
 * [Exceptions from Undefined Opcodes and String Instructions](exceptions/)
 
-### Assorted Publications
+Assorted Publications
+---
 
 [<img src="http://archive.pcjs.org/pubs/pc/reference/intel/iAPX_286_Hardware_Reference--1983/thumbs/iAPX_286_Hardware_Reference--1983.jpg" width="200" height="260" alt="iAPX 286 Hardware Reference (1983)"/>](http://bitsavers.trailing-edge.com/pdf/intel/_dataBooks/1983_iAPX_286_Hardware_Reference.pdf)
 [<img src="http://archive.pcjs.org/pubs/pc/reference/intel/iAPX_286_Operating_System_Writers_Guide--1983/thumbs/iAPX_286_Operating_System_Writers_Guide--1983.jpg" width="200" height="260" alt="iAPX 286 OS Writer's Guide (1983)"/>](http://bitsavers.trailing-edge.com/pdf/intel/_dataBooks/1983_iAPX_286_Operating_System_Writers_Guide.pdf)

pubs/pc/reference/intel/80386/README.md

@@ -20,12 +20,6 @@ Intel 80386 CPU Information
 * [D1 Stepping](#d1-stepping)
 * [D2 Stepping](#d2-stepping)
 
-80386 Undocumented Instructions
----
-
-* [LOADALL](loadall/)
-* [IBTS and XBTS](ibts_xbts/)
-
 80386 Steppings
 ---
 
@@ -818,3 +812,9 @@ Revision identifier: 0x08.
 ### D2 Stepping
 
 Revision identifier: 0x08 (same as the D1 stepping).
+
+80386 Undocumented Instructions
+---
+
+* [LOADALL](loadall/)
+* [IBTS and XBTS](ibts_xbts/)

pubs/pc/reference/intel/80386/ibts_xbts/README.md

@@ -4,11 +4,12 @@ title: "Obsolete 80386 Instructions: IBTS and XBTS"
 permalink: /pubs/pc/reference/intel/80386/ibts_xbts/
 ---
 
-### Obsolete 80386 Instructions
+Obsolete 80386 Instructions
+---
 
 Here's more information on the 80386 opcodes (IBTS and XBTS) that were removed from the 80386 as of the B1 stepping.
 
-[IBTS (0x0F 0xA7)](http://asm.inightmare.org/opcodelst/index.php?op=IBTS)
+### [IBTS (0x0F 0xA7)](http://asm.inightmare.org/opcodelst/index.php?op=IBTS)
 
 	Opcode IBTS
 	
@@ -28,7 +29,7 @@ Here's more information on the 80386 opcodes (IBTS and XBTS) that were removed f
 	Clocks:	IBTS 
 	80386:	12/19
 
-[XBTS (0x0F 0xA6)](http://asm.inightmare.org/opcodelst/index.php?op=XBTS):
+### [XBTS (0x0F 0xA6)](http://asm.inightmare.org/opcodelst/index.php?op=XBTS)
 
     Opcode XBTS
 

pubs/pc/reference/intel/8086/README.md

@@ -0,0 +1,23 @@
+---
+layout: page
+title: Intel 8086/8088 CPU Information
+permalink: /pubs/pc/reference/intel/8086/
+---
+
+Intel 8086/8088 CPU Information
+---
+
+8086 Errata
+---
+
+* TBD
+
+8086 Undocumented Instructions
+---
+
+* TBD
+
+Assorted Publications
+---
+
+* TBD

pubs/pc/reference/intel/8087/README.md

@@ -165,23 +165,23 @@ operands, enabling convenient processing of numeric arrays, structures, based va
 
 	                       Table S-3. Principal Instructions
 	
-		Class                   Instructions
+	    Class                   Instructions
 	
-		Data Transfer           Load (all data types), Store (all data types), Exchange
+	    Data Transfer           Load (all data types), Store (all data types), Exchange
 	
-		Arithmetic              Add, Subtract, Multiply, Divide, Subtract Reversed, Divide Reversed,
+	    Arithmetic              Add, Subtract, Multiply, Divide, Subtract Reversed, Divide Reversed,
-								Square Root, Scale, Remainder, Integer Part, Change Sign,
+	                            Square Root, Scale, Remainder, Integer Part, Change Sign,
-								Absolute Value, Extract
+	                            Absolute Value, Extract
 	
-		Comparison              Compare, Examine, Test
+	    Comparison              Compare, Examine, Test
 	
-		Transcendental          Tangent, Arctangent, 2^x-1, Y*Log2(X + 1), Y*Log2(X)
+	    Transcendental          Tangent, Arctangent, 2^x-1, Y*Log2(X + 1), Y*Log2(X)
 	
-		Constants               0, 1, π, Log10(2), Loge(2), Log2(10), Log2(e)
+	    Constants               0, 1, π, Log10(2), Loge(2), Log2(10), Log2(e)
 	
-		Processor Control       Load Control Word, Store Control Word, Store Status Word,
+	    Processor Control       Load Control Word, Store Control Word, Store Status Word,
-								Load Environment, Store Environment, Save, Restore, Enable Interrupts,
+	                            Load Environment, Store Environment, Save, Restore, Enable Interrupts,
-								Disable Interrupts, Clear Exceptions, Initialize
+	                            Disable Interrupts, Clear Exceptions, Initialize
 
 > NDP routines may also be written in PL/M-86, Intel's high-level language for the 8086 and 8088 CPUs. PL/M-86
 provides the programmer with access to many 8087 facilities while reducing the programmer's need to understand the

pubs/pc/reference/intel/README.md

@@ -7,10 +7,26 @@ permalink: /pubs/pc/reference/intel/
 Intel CPU Documentation
 ---
 
-Processor-specific information:
+### [8086 CPU](8086/)
  
- * [80286 CPU](80286/)
+### [8087 FPU](8087/)
- * [80386 CPU](80386/)
+ 
+### [80186 CPU](80186/)
+ 
+### [80286 CPU](80286/)
+ 
+ * [80286 Errata](80286/#errata)
+ * [80286 Undocumented Instructions](80286/#undocumented-instructions)
+	 * [LOADALL](80286/loadall/)
+ * [80286 Real-Mode Emulation Notes](80286/#real-mode-emulation-notes)
+
+### [80386 CPU](80386/)
+ 
+ * [80386 Errata](80386/#errata)
+ * [80386 Steppings](80386/#steppings)
+ * [80386 Undocumented Instructions](80386/#undocumented-instructions)
+	 * [LOADALL](80386/loadall/)
+	 * [IBTS](80386/ibts_xbts/), [XBTS](80386/ibts_xbts/)
 
 ### Assorted Publications