From c8f5357689fd55ec9a8235923202eb2110e760e8 Mon Sep 17 00:00:00 2001
From: Jeff Parsons <jeff@pcjs.org>
Date: Wed, 27 Jul 2016 12:03:12 -0700
Subject: [PATCH] More VT100 groundwork

---
 devices/pc8080/machine/README.md         |  3 +-
 devices/pc8080/machine/vt100/README.md   | 59 ++++++++++++++++++++++++
 devices/pc8080/machine/vt100/machine.xml | 20 ++++++++
 devices/pc8080/rom/README.md             |  2 +-
 devices/pc8080/rom/vt100/README.md       |  2 +-
 modules/pc8080/lib/video.js              | 28 +++++++----
 modules/shared/templates/components.xsl  | 14 +++++-
 pubs/README.md                           |  8 +++-
 pubs/c1p/README.md                       | 11 +++++
 pubs/dec/README.md                       | 10 ++++
 pubs/dec/vt100/README.md                 | 19 ++++++++
 11 files changed, 162 insertions(+), 14 deletions(-)
 create mode 100644 devices/pc8080/machine/vt100/README.md
 create mode 100644 devices/pc8080/machine/vt100/machine.xml
 create mode 100644 pubs/c1p/README.md
 create mode 100644 pubs/dec/README.md
 create mode 100644 pubs/dec/vt100/README.md

diff --git a/devices/pc8080/machine/README.md b/devices/pc8080/machine/README.md
index f7e9a1079..1ad417684 100644
--- a/devices/pc8080/machine/README.md
+++ b/devices/pc8080/machine/README.md
@@ -9,5 +9,6 @@ PC8080 Machine Configurations
 
 The following 8080-based machines are currently available:
 
+* [8080 Exerciser](exerciser/)
 * [Space Invaders (1978)](invaders/)
-* [8080 Exerciser Test Machine](exerciser/)
+* [DEC VT100 Terminal](vt100/)
diff --git a/devices/pc8080/machine/vt100/README.md b/devices/pc8080/machine/vt100/README.md
new file mode 100644
index 000000000..4da50c242
--- /dev/null
+++ b/devices/pc8080/machine/vt100/README.md
@@ -0,0 +1,59 @@
+---
+layout: page
+title: VT100 Terminal
+permalink: /devices/pc8080/machine/vt100/
+machines:
+  - type: pc8080
+    id: vt100
+    debugger: true
+---
+
+VT100 Terminal
+--------------
+
+This is where we'll be testing another 8080-based machine: a VT100 Terminal. Unlike other VT100 emulations,
+this will simulate a VT100 by running the terminal's original firmware inside the [PC8080](/modules/pc8080/) CPU emulator.
+
+As described in the [Technical Manual (July 1982)](http://bitsavers.informatik.uni-stuttgart.de/pdf/dec/terminal/vt100/EK-VT100-TM-003_VT100_Technical_Manual_Jul82.pdf),
+p. 4-15, 8Kb (0x2000) of ROM is located at 0x0000, and 3Kb (0x0C00) of RAM immediately follows it at 0x2000.  
+
+[vt100romhax](http://vt100romhax.tumblr.com/post/90697428973/the-vt100-memory-map-and-8080-disassembly)
+(aka [phooky](https://github.com/phooky)) further explains VT100 memory usage:
+
+	Start   End     Size    Description
+	0x0000  0x1fff  8K      Basic ROM
+	0x2000  0x2012  18B     Blank lines for refresh (6 x 3B)
+	0x2012  0x204f  61B     Stack area (grows down from 0x204e)
+	0x204f  0x22d0  641B    Scratch Pad/Setup Area(?)
+	0x22d0  0x2c00  2352B   Screen RAM
+
+Normally, the PC8080 Video component allocates its own video buffer, based on the specified buffer address
+(*bufferAddr*) and other dimensions (eg, *bufferCols* and *bufferRows*), but the VT100 is a little unusual:
+it has a custom video processor that uses DMA to request character data from any region of RAM, one line at a time.
+It always defaults to address 0x2000 for the first line of character data, but each line terminates with 3 bytes
+containing line attributes and the address of the next line, so the location of subsequent lines will vary,
+depending on the following line attributes:
+
+* Single-width characters (80 or 132 columns)
+* Double-width characters (40 or 66 columns)
+
+In addition to single vs. double width, line attributes can also specify double height (along with whether the
+top half or bottom half of the character should be displayed).
+
+The VT100 screen displays 800 dots per horizontal scan, and a total of 240 horizontal scans,
+so for optimum scaling, we define our own screen using multiples of those dimensions (currently 1600x480),
+and by default, it uses a 10x10 character cell, so the default display dimensions are 80 columns by 24 rows.
+
+In light of the above, the [machine XML file](machine.xml) must set the Video component's *bufferRAM* property
+to "true", indicating that existing RAM should be used, and a new property, *bufferFormat* must be set to "vt100",
+enabling support for the VT100's line data format; eg:
+
+	<ram id="ram" addr="0x2000" size="0x0C00"/>
+	<video id="video" screenWidth="1600" screenHeight="480" bufferAddr="0x2000" bufferRAM="true" bufferFormat="vt100" bufferCols="80" bufferRows="24" ...>
+
+{% include machine.html id="vt100" %}
+
+VT100 Resources
+---------------
+
+[VT100 Publications](/pubs/dec/vt100/)
diff --git a/devices/pc8080/machine/vt100/machine.xml b/devices/pc8080/machine/vt100/machine.xml
new file mode 100644
index 000000000..4ee48b4a1
--- /dev/null
+++ b/devices/pc8080/machine/vt100/machine.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-stylesheet type="text/xsl" href="/versions/pc8080/1.23.2/machine.xsl"?>
+<machine id="vt100" class="pc8080" border="1" pos="center" background="#FAEBD7">
+	<name pos="center">VT100 Terminal</name>
+	<computer id="computer" busWidth="16"/>
+	<cpu id="cpu8080" model="8080" cycles="2000000" autoStart="true"/>
+	<rom id="rom" addr="0x0000" size="0x2000" file="/devices/pc8080/rom/vt100/VT100.json"/>
+	<ram id="ram" addr="0x2000" size="0x02D0"/>
+	<video id="video" screenWidth="1600" screenHeight="480" smoothing="false" bufferAddr="0x22D0" bufferRAM="true" bufferFormat="vt100" width="40%" pos="left" padding="8px">
+		<menu>
+			<title>VT100 Screen</title>
+			<control type="container" pos="right">
+				<control type="button" binding="fullScreen" padleft="8px;line-height:1em">Full Screen</control>
+			</control>
+		</menu>
+	</video>
+	<keyboard id="keyboard"/>
+	<panel ref="/devices/pc8080/panel/left.xml"/>
+	<debugger id="debugger" commands="s 8086"/>
+</machine>
diff --git a/devices/pc8080/rom/README.md b/devices/pc8080/rom/README.md
index 6c8cf17af..0288823ff 100644
--- a/devices/pc8080/rom/README.md
+++ b/devices/pc8080/rom/README.md
@@ -17,5 +17,5 @@ for each ROM in the machine; eg:
 The project currently contains the following 8080-based ROMs:
 
 * [8080 Exerciser Tests](exerciser/)
-* [DEC VT100](vt100/)
 * [Space Invaders (1978)](invaders/)
+* [DEC VT100 Terminal](vt100/)
diff --git a/devices/pc8080/rom/vt100/README.md b/devices/pc8080/rom/vt100/README.md
index d010d0b14..781d1972f 100644
--- a/devices/pc8080/rom/vt100/README.md
+++ b/devices/pc8080/rom/vt100/README.md
@@ -31,7 +31,7 @@ The above PCB chip locations correspond to the following [DEC ROM](/devices/roms
 * E45: [23-033E2.bin](https://web.archive.org/web/20140723115846/http://www.dunnington.u-net.com/public/DECROMs/23-033E2.bin)
 * E40: [23-034E2.bin](https://web.archive.org/web/20140723115846/http://www.dunnington.u-net.com/public/DECROMs/23-034E2.bin)
 
-And sure enough, concatenating those DEC ROM four dumps produces a perfect match for Trammell Hudson's
+And sure enough, concatenating those four DEC ROM dumps produces a perfect match for Trammell Hudson's
 [VT100.bin](http://trmm.net/images/2/20/VT100.bin).
 
 The VT100 also used one 2Kb character generator ROM, which is stored in [23-018E2.json](23-018E2.json).
diff --git a/modules/pc8080/lib/video.js b/modules/pc8080/lib/video.js
index 0bbda415e..7f7826621 100644
--- a/modules/pc8080/lib/video.js
+++ b/modules/pc8080/lib/video.js
@@ -52,6 +52,8 @@ if (NODE) {
  *      screenRotate: the amount of counter-clockwise screen rotation required (eg, -90 or 270)
  *      aspectRatio (eg, 1.33)
  *      bufferAddr: the starting address of the frame buffer (eg, 0x2400)
+ *      bufferRAM: true to use existing RAM (default is false)
+ *      bufferFormat: can be set to anything, but the only recognized format is currently "vt100"
  *      bufferCols: the width of a single frame buffer row, in pixels (eg, 256)
  *      bufferRows: the number of frame buffer rows (eg, 224)
  *      bufferBits: the number of bits per column (default is 1)
@@ -96,6 +98,8 @@ function Video(parmsVideo, canvas, context, textarea, container)
     this.cyScreen = parmsVideo['screenHeight'];
 
     this.addrBuffer = parmsVideo['bufferAddr'];
+    this.fUseRAM = parmsVideo['bufferRAM'];
+    this.sFormat = parmsVideo['bufferFormat'];
     this.cxBuffer = parmsVideo['bufferCols'];
     this.cyBuffer = parmsVideo['bufferRows'];
     this.nBitsPerPixel = parmsVideo['bufferBits'] || 1;
@@ -212,6 +216,10 @@ function Video(parmsVideo, canvas, context, textarea, container)
 
 Component.subclass(Video);
 
+/*
+ * TODO: Use of these overlay colors should be limited to machine's that require/request them (ie, Space Invaders),
+ * using an additional parmsVideo property.
+ */
 Video.COLORS = {
     OVERLAY_TOP:    0,
     OVERLAY_BOTTOM: 1,
@@ -237,14 +245,18 @@ Video.prototype.initBus = function(cmp, bus, cpu, dbg)
     /*
      * Compute the size of the frame buffer and allocate.
      */
-    this.sizeBuffer = ((this.cxBuffer * this.nBitsPerPixel) >> 3) * this.cyBuffer;
-    if (this.bus.addMemory(this.addrBuffer, this.sizeBuffer, Memory.TYPE.VIDEO)) {
-        /*
-         * Compute the number of cells and initialize the cell cache.
-         */
-        this.nCellCache = this.sizeBuffer >> 1;
-        this.nPixelsPerCell = (16 / this.nBitsPerPixel)|0;
-        this.initCache();
+    if (!this.fUseRAM) {
+        this.sizeBuffer = ((this.cxBuffer * this.nBitsPerPixel) >> 3) * this.cyBuffer;
+        if (this.bus.addMemory(this.addrBuffer, this.sizeBuffer, Memory.TYPE.VIDEO)) {
+            /*
+             * Compute the number of cells and initialize the cell cache; note that sizeBuffer is a number of
+             * bytes, whereas nCellCache is a number of 16-bit words (aka shorts) because we fetch memory 16 bits
+             * at a time during screen updates.
+             */
+            this.nCellCache = this.sizeBuffer >> 1;
+            this.nPixelsPerCell = (16 / this.nBitsPerPixel)|0;
+            this.initCache();
+        }
     }
 
     /*
diff --git a/modules/shared/templates/components.xsl b/modules/shared/templates/components.xsl
index 22420a87d..5d6c4d0d2 100644
--- a/modules/shared/templates/components.xsl
+++ b/modules/shared/templates/components.xsl
@@ -1003,6 +1003,18 @@
 				<xsl:otherwise>0</xsl:otherwise>
 			</xsl:choose>
 		</xsl:variable>
+		<xsl:variable name="bufferRAM">
+			<xsl:choose>
+				<xsl:when test="@bufferRAM"><xsl:value-of select="@bufferRAM"/></xsl:when>
+				<xsl:otherwise>false</xsl:otherwise>
+			</xsl:choose>
+		</xsl:variable>
+		<xsl:variable name="bufferFormat">
+			<xsl:choose>
+				<xsl:when test="@bufferFormat"><xsl:value-of select="@bufferFormat"/></xsl:when>
+				<xsl:otherwise>1bpp</xsl:otherwise>
+			</xsl:choose>
+		</xsl:variable>
 		<xsl:variable name="bufferCols">
 			<xsl:choose>
 				<xsl:when test="@bufferCols"><xsl:value-of select="@bufferCols"/></xsl:when>
@@ -1120,7 +1132,7 @@
 		<xsl:call-template name="component">
 			<xsl:with-param name="machine" select="$machine"/>
 			<xsl:with-param name="class">video</xsl:with-param>
-			<xsl:with-param name="parms">,model:'<xsl:value-of select="$model"/>',mode:<xsl:value-of select="$mode"/>,screenWidth:<xsl:value-of select="$screenWidth"/>,screenHeight:<xsl:value-of select="$screenHeight"/>,screenColor:'<xsl:value-of select="$screenColor"/>',screenRotate:<xsl:value-of select="$screenRotate"/>,bufferAddr:<xsl:value-of select="$bufferAddr"/>,bufferCols:<xsl:value-of select="$bufferCols"/>,bufferRows:<xsl:value-of select="$bufferRows"/>,bufferBits:<xsl:value-of select="$bufferBits"/>,bufferLeft:<xsl:value-of select="$bufferLeft"/>,bufferRotate:<xsl:value-of select="$bufferRotate"/>,memory:<xsl:value-of select="$memory"/>,switches:'<xsl:value-of select="$switches"/>',scale:<xsl:value-of select="$scale"/>,charCols:<xsl:value-of select="$charCols"/>,charRows:<xsl:value-of select="$charRows"/>,fontROM:'<xsl:value-of select="$fontROM"/>',touchScreen:'<xsl:value-of select="$touchScreen"/>',autoLock:<xsl:value-of select="$autoLock"/>,aspectRatio:<xsl:value-of select="$aspectRatio"/>,smoothing:<xsl:value-of select="$smoothing"/>,interruptRate:<xsl:value-of select="$interruptRate"/>,refreshRate:<xsl:value-of select="$refreshRate"/></xsl:with-param>
+			<xsl:with-param name="parms">,model:'<xsl:value-of select="$model"/>',mode:<xsl:value-of select="$mode"/>,screenWidth:<xsl:value-of select="$screenWidth"/>,screenHeight:<xsl:value-of select="$screenHeight"/>,screenColor:'<xsl:value-of select="$screenColor"/>',screenRotate:<xsl:value-of select="$screenRotate"/>,bufferAddr:<xsl:value-of select="$bufferAddr"/>,bufferRAM:<xsl:value-of select="$bufferRAM"/>,bufferFormat:'<xsl:value-of select="$bufferFormat"/>',bufferCols:<xsl:value-of select="$bufferCols"/>,bufferRows:<xsl:value-of select="$bufferRows"/>,bufferBits:<xsl:value-of select="$bufferBits"/>,bufferLeft:<xsl:value-of select="$bufferLeft"/>,bufferRotate:<xsl:value-of select="$bufferRotate"/>,memory:<xsl:value-of select="$memory"/>,switches:'<xsl:value-of select="$switches"/>',scale:<xsl:value-of select="$scale"/>,charCols:<xsl:value-of select="$charCols"/>,charRows:<xsl:value-of select="$charRows"/>,fontROM:'<xsl:value-of select="$fontROM"/>',touchScreen:'<xsl:value-of select="$touchScreen"/>',autoLock:<xsl:value-of select="$autoLock"/>,aspectRatio:<xsl:value-of select="$aspectRatio"/>,smoothing:<xsl:value-of select="$smoothing"/>,interruptRate:<xsl:value-of select="$interruptRate"/>,refreshRate:<xsl:value-of select="$refreshRate"/></xsl:with-param>
 		</xsl:call-template>
 	</xsl:template>
 
diff --git a/pubs/README.md b/pubs/README.md
index 13333d425..90bbcf3fe 100644
--- a/pubs/README.md
+++ b/pubs/README.md
@@ -7,7 +7,7 @@ permalink: /pubs/
 Publication Archive
 ---
 
-[PC Publications](pc/):
+[PC Publications](/pubs/pc/):
 
 * [CPU Documents](/pubs/pc/reference/intel/)
 * [Datasheets](/pubs/pc/datasheets/)
@@ -16,12 +16,16 @@ Publication Archive
 * [Reference Manuals](/pubs/pc/reference/)
 * [Software User and Development Guides](/pubs/pc/software/) (eg, [DOS](/pubs/pc/software/dos/), [OS/2](/pubs/pc/software/os2/), [Windows](/pubs/pc/software/windows/))
 
-Ohio Scientific's 6502-based [Challenger 1P Publications](c1p/):
+Ohio Scientific's 6502-based [Challenger 1P Publications](/pubs/c1p/):
 
 * [Datasheets](/pubs/c1p/datasheets/)
 * [Programming Guides/Samples](/pubs/c1p/programming/)
 * [Reference Manuals](/pubs/c1p/techref/)
 
+[Digital Equipment Corporation (DEC) Publications](/pubs/dec/):
+
+* [VT100](/pubs/dec/vt100/)
+
 [<img src="http://archive.pcjs.org/pubs/pc/datasheets/thumbs/8088-CPU.jpg" width="200" height="260" alt= "8088 CPU"/>](pc/datasheets/)
 [<img src="http://archive.pcjs.org/pubs/pc/magazines/byte/BYTE-1975-11/thumbs/BYTE-1975-11 1.jpeg" width="200" height="260" alt= "Byte Magazine"/>](pc/magazines/byte/)
 [<img src="http://archive.pcjs.org/pubs/pc/magazines/msj/MSJ-1986-10/thumbs/MSJ-1986-10 1.jpeg" width="200" height="260" alt= "Microsoft Systems Journal"/>](pc/magazines/msj/)
diff --git a/pubs/c1p/README.md b/pubs/c1p/README.md
new file mode 100644
index 000000000..c66a9b240
--- /dev/null
+++ b/pubs/c1p/README.md
@@ -0,0 +1,11 @@
+---
+layout: page
+title: Challenger 1P Publications
+permalink: /pubs/c1p/
+---
+
+Challenger 1P Publications
+--------------------------
+
+* [Data Sheets](datasheets/)
+* [Technical Reference Manuals](techref/)
diff --git a/pubs/dec/README.md b/pubs/dec/README.md
new file mode 100644
index 000000000..bb655c69f
--- /dev/null
+++ b/pubs/dec/README.md
@@ -0,0 +1,10 @@
+---
+layout: page
+title: Digital Equipment Corporation (DEC) Publications
+permalink: /pubs/dec/
+---
+
+Digital Equipment Corporation (DEC) Publications
+------------------------------------------------
+
+* [VT100](vt100/)
diff --git a/pubs/dec/vt100/README.md b/pubs/dec/vt100/README.md
new file mode 100644
index 000000000..454792882
--- /dev/null
+++ b/pubs/dec/vt100/README.md
@@ -0,0 +1,19 @@
+---
+layout: page
+title: VT100 Publications
+permalink: /pubs/dec/vt100/
+---
+
+VT100 Publications
+------------------
+
+* Technical Manuals ([September 1980](http://www.vt100.net/docs/vt100-tm/ek-vt100-tm-002.pdf), [July 1982](http://bitsavers.informatik.uni-stuttgart.de/pdf/dec/terminal/vt100/EK-VT100-TM-003_VT100_Technical_Manual_Jul82.pdf))
+* User Guides ([August 1978](http://bitsavers.informatik.uni-stuttgart.de/pdf/dec/terminal/vt100/EK-VT100-UG-001_VT100_User_Guide_Aug78.pdf), [January 1979](http://bitsavers.informatik.uni-stuttgart.de/pdf/dec/terminal/vt100/EK-VT100-UG-002_VT100_User_Guide_Jan79.pdf))
+* Field Maintenance Guides ([March 1980](http://bitsavers.informatik.uni-stuttgart.de/pdf/dec/terminal/vt100/MP00633_VT100_Mar80.pdf), [February 1982](http://bitsavers.informatik.uni-stuttgart.de/pdf/dec/terminal/vt100/MP00633_VT100_Schematic_Feb82.pdf))
+
+Additional Resources
+--------------------
+
+* [Wikipedia](https://en.wikipedia.org/wiki/VT100)
+* [vt100.net](http://www.vt100.net/docs/)
+* [Retrochallenge 2014](http://vt100romhax.tumblr.com/) by [Adam Mayer](https://github.com/phooky)