added hdl folder

8 files changed, 237 insertions, 0 deletions

diff --git a/doc/src/01-About.md b/doc/src/01-About.md
new file mode 100644
index 0000000..0468708
--- /dev/null
+++ b/doc/src/01-About.md
@@ -0,0 +1,73 @@
+# About this Manual
+
+This manual describes the architecture and programming environment of a Vertex
+Mark I microprocessor. This manual applies to application programmers, operating
+system programmers and BIOS designers.
+
+## Notational Conventions
+
+This manual uses specific notation for data-structure formats, for symbolic
+representation and for hexadecimal and binary numbers. A review of this notation
+makes the manual easier to read.
+
+### Bit and Byte Order
+
+In illustrations of data structures in memory, smaller addresses appear toward
+the bottom of the figure; addresses increase toward the top. Bit positions are
+numbered from right to left. The numerical value of a set bit is two raised to
+the power of the bit position. Vertex processors are "little endian" machines;
+this means the bytes of a word are numbered starting from the least significant
+byte. Figure 1.1 illustrates these conventions.
+
+### Reserved Bits
+
+In many register and memory layout descriptions, certain bits are marked as
+**reserved**. When bits are marked as reserved, it is essential for
+compatibility with future processors that software treat these bits as having
+a future, but unknown, use. These bits should be treated as, not only undefined,
+but unpredictable.
+
+### Instruction Operands
+
+When instructions are represented symbolically, a subset of the Vertex-32
+assembly language is used. In this subset, an instruction has the following
+format:
+
+```
+label: mnemonic argument1, argument2, argument3
+```
+
+where:
+
+* A **label** is an identifier which is followed by a colon
+* A **mnemonic** is a reserved name for an instruction opcode
+* The operands *argument1*, *argument2* and *argument3* are optional. There may
+  be from zero to three operands, depending on the opcode.
+
+When three operands are present in an arithmetic or logical operation, the first
+operand is the destination register and the remaining two are either source
+registers or immediate values. For example:
+
+```
+load: ADDI AX, BX, subtotal
+```
+
+In this example, `ADDI` is the mnemonic identifier of an opcode, `AX` is the
+destination operand, and `BX` and `subtotal` are the source operands.
+
+### Hexadecimal and Binary Numbers
+
+Base 16 (hexadecimal) numbers are represented by a '0x' followed by a string of
+hexadecimal digits. A hexadecimal digit is a character from '0' to '9' and 'A'
+to 'F'. Base 2 (binary) numbers are represented by a string of 1s and 0s,
+sometimes preceded by '0b' (for example, 0b1010). The '0b' designation is only
+used in situations in which confusion about a number's base may arise.
+
+### Exceptions
+
+An exception is an event that typically occurs when an instruction causes an
+error. For example, an attempt to divide by zero generates a divide-by-zero
+exception. All exceptions provide either an error code or 0, indicating no
+error. An error code reports additional information about the error. For
+example, a page fault would provide a fault code indicating what caused the page
+fault.
diff --git a/doc/src/02-Instruction-Format.md b/doc/src/02-Instruction-Format.md
new file mode 100644
index 0000000..e08f110
--- /dev/null
+++ b/doc/src/02-Instruction-Format.md
@@ -0,0 +1,5 @@
+# Instruction Format
+
+## Instruction Format for V32 Mode
+
+WIP
diff --git a/doc/src/03-Instruction-Set-Reference.md b/doc/src/03-Instruction-Set-Reference.md
new file mode 100644
index 0000000..e258393
--- /dev/null
+++ b/doc/src/03-Instruction-Set-Reference.md
@@ -0,0 +1,92 @@
+# Instruction Set Reference
+
+This chapter describes the instruction set for the Vertex-32 and Vertex-64
+architectures in V32 and V64 modes of operation. For each instruction, each
+operand combination is described, a description of the effect upon the FLG
+register and a summary of possible exceptions are also provided.
+
+## Registers
+
+Figure 3.1 shows the initial state of the registers in the ISA. For V32, the
+16 registers are each 32 bits wide. Register `0X` is hardwired with all bits
+equal to 0. General purpose registers `AX` to `GX` hold values that various
+instructions interpret as a collection of Boolean values, or as two's
+complement signed binary integers or unsigned binary integers. The registers
+`PTR`, `IDTR` and `CRX` are considered privileged and writing to them in the
+unprivileged state will generate a general protection fault.
+
+## Base Instruction Formats
+
+In the core V32 ISA, there are four instruction formats (C/I/R/J), as shown in
+Figure 3.3. All are a fixed 32 bits in length and must be aligned on a four-byte
+boundary in memory. An instruction alignment exception is generated if a branch
+or jump instruction is called on an address that is not four-byte aligned. No
+exception is generated on a branch or jump not taken.
+
+## Integer Instructions
+
+Most integer computational instructions operate on 32 or 64 bit values held in
+a register or memory location. Integer instructions are encoded as
+register-immediate operations using the I-type format or as register-register
+operations using the R-type format. The destination is `RD` for both
+register-immediate and register-register operations. If any of the following
+instructions cause an overflow or underflow, the overflow flag is set.
+
+### Integer-Register Instructions
+
+The instructions that follow are operations between registers; an attempt to use
+a non-register operand will result in an invalid opcode exception. The format
+for these exceptions follow Figure 3.4.
+
+#### ADD
+
+`ADD` adds the second and third operands and stores the result in the first
+operand.
+
+#### SUB
+
+`SUB` subtracts the third operand from the second operand and stores the result
+in the first operand.
+
+#### MUL/MULU
+
+`MUL` multiplies the second operand by the third operand and stores the result
+in the first operand. `MULU` performs the same operation on unsigned integers.
+
+#### DIV/DIVU
+
+`DIV` divides the second operand by the third operand. The dividend is stored in
+the upper 16 bits of the first operand, and the remainder is stored in the lower
+16 bits. `DIVU` performs the same operation on unsigned integers.
+
+#### XOR
+
+`XOR` performs a bitwise 'exclusive or' operation between the second and third
+operands and stores the result in the first operand.
+
+#### OR
+
+`OR` performs a bitwise 'or' operation between the second and third operands and
+stores the result in the first operand.
+
+#### AND
+
+`AND` performs a bitwise 'and' operation between the second and third operands
+and stores the result in the first operand.
+
+#### LSL
+
+`LSL` performs a logical shift left. The second operand is shifted left by `n`
+bits, where `n` is the third operand. The result is stored in the first operand.
+
+#### LSR
+
+`LSR` performs a logical shift right. The second operand is shifted right by
+'n' bits, where 'n' is the third operand. The result is stored in the first
+operand.
+
+#### ASR
+
+`ASR` performs an arithmetic shift right. The second operand is shifted right by
+'n' bits, where 'n' is the third operand. The result is stored in the first
+operand.
diff --git a/doc/src/04-System-Architecture-Overview.md b/doc/src/04-System-Architecture-Overview.md
new file mode 100644
index 0000000..2aa76d3
--- /dev/null
+++ b/doc/src/04-System-Architecture-Overview.md
@@ -0,0 +1,14 @@
+# System Architecture Overview
+
+## Overview of the System-level Architecture
+
+The system-level architecture consists of a set of registers, data structures
+and instructions designed to support basic system management operations such as
+memory management, interrupt handling, task management and control of multiple
+processors. Figure 4.1 describes the registers and data structures relevant to
+V32 mode.
+
+## Memory Management Overview
+
+The Vertex-32 architecture provides several instructions that create and
+manipulate pages and page tables.
diff --git a/doc/src/05-Interrupt-Handling.md b/doc/src/05-Interrupt-Handling.md
new file mode 100644
index 0000000..0c549e1
--- /dev/null
+++ b/doc/src/05-Interrupt-Handling.md
@@ -0,0 +1,30 @@
+# Interrupt and Exception Handling
+
+This chapter describes the interrupt and exception-handling mechanism on a
+Vertex-32 or Vertex-64 processor.
+
+## Interrupts Overview
+
+Interrupts and exceptions are events that get triggered either upon a special
+condition or when the instruction `INT interrupt_number` is executed. Typically,
+an interrupt forces a transfer of execution from the currently executing task to
+a special routine called an interrupt handler or an exception handler. The
+action taken by a processor in response to an interrupt is referred to as
+servicing or handling the interrupt or exception.
+
+Interrupts can occur at regular intervals or randomly during the execution of a
+task or software routine in response to signals from hardware, such as requests
+from peripheral devices. Interrupts can also be generated by software by calling
+the `INT` instruction.
+
+Exceptions occur when the processor detects an error condition while executing
+an instruction. For instance, the processor could detect that a program is
+requesting a page that is currently not mapped, generating a page fault.
+
+When an interrupt is received, the currently running task is suspended while the
+processor services the interrupt or exception. Upon completion of the interrupt
+handler, execution is returned to the suspended task without loss of continuity.
+If the exception cannot be handled or the exception handler does not return, a
+double fault is generated. If a further exception is encountered while servicing
+the double fault, it is considered an unrecoverable error and the processor is
+reset.
diff --git a/doc/src/06-Memory-Management.md b/doc/src/06-Memory-Management.md
new file mode 100644
index 0000000..0813c6a
--- /dev/null
+++ b/doc/src/06-Memory-Management.md
@@ -0,0 +1,11 @@
+# Memory Management
+
+This chapter describes the Vertex-32 and Vertex-64 architecture's memory
+management facilities, including physical memory requirements and paging.
+
+## Memory Management Overview
+
+The Vertex family of processors provide facilities to perform demand-paged
+paging algorithms. Although recommended for most applications, the paging
+mechanism can be disabled and memory can then be access directly. Segmentation,
+such as what is found on Intel's x86 architecture, is not supported.
diff --git a/doc/src/figs/registers.svg b/doc/src/figs/registers.svg
new file mode 100644
index 0000000..1522f2a
--- /dev/null
+++ b/doc/src/figs/registers.svg
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Do not edit this file with editors other than diagrams.net -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="141px" height="451px" viewBox="-0.5 -0.5 141 451" content="&lt;mxfile host=&quot;Electron&quot; modified=&quot;2022-05-06T03:17:17.485Z&quot; agent=&quot;5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/17.4.2 Chrome/100.0.4896.60 Electron/18.0.1 Safari/537.36&quot; etag=&quot;LDFEIayXnVHNOMXlRYny&quot; version=&quot;17.4.2&quot; type=&quot;device&quot;&gt;&lt;diagram id=&quot;aj0NjsLKcaomzQoa0Eas&quot; name=&quot;Page-1&quot;&gt;7ZpNb6MwEIZ/DcddAQ5teiykya6USlVSaffqggNWjSc1TpP01+8QTAhxPw9dOBChCL+e8cfM4wAODony3UzRdXYLCROO7yY7h0wc3x9fjPG7FPaVEFz6lZAqnlSS1whL/sKM6Bp1wxNWtAw1gNB83RZjkJLFuqVRpWDbNluBaPe6pimzhGVMha3+4YnOzLQCt9F/MZ5mdc+ea2pyWhsbochoAtsTidw4JFIAujrLdxETZezquFR+0zdqjwNTTOrPOED0tFvwZx3T+ez+cb5/Yhv1w7usmnmmYmNmvGApLzRThRm23texKLY8F1RiKVyB1EtT42I5zrhI5nQPm3IshabxY10KM1D8Be2pwCoPBaxW2qSauC2LZelp2lSsQJu7eoLemXRLdy3DOS10PRoQgq4L/nAYX+mYU5VyGYLWkBujcgpTmnNRkjmjiuYgMVThM1OaIwDXgqcSq3KeJGU7oYkUVrPdmznwjpnFFcEgZ1rt0cQ4kCCoXMxq8K4MHNuGLW9ktOyEq1ENHDU8p8e2j90tkH8qUxzrm/35l3Z/wSvdkbPeqEAgJNUshI1MilPO8ORkpo10oO8rJI4tEt2/FoIYen0gSMEji0CAQl1CxSQX4kyiJocx5oep95JbrGnMZTpnqzIEo0ZZmKiUEqD7ShwWcYaODFsI18ClPoQpCPHAwEXuz8AJcLQRlr2mjEdprnQEEidA+YEZhthuWYluqEBTTR+Oi6pF6FQxdgsSjF5P1MFcHT6fBfSdnwEb230bh48oPcfmFNIWL1+Fg1xYcFwPcPQDjouu4fCuLDjCAY5+wPHZ69u3wVHffZ3AEQ1w9AMOz++cDvu6Mhno6AkdQed02A9HNwMdPaFj3Dkd9gPLdKCjH3Qct4+6o8O+KZ0NdPSEjlHXdBD7rnQ6nw149AOPVzbJ/jMenoXH77uBjl7QQdzO6fAtOpYDHT2ho/utUmLREQ509ISOzvdKycii426yGPDoBx6d75aSwL7xmNwPfPSDj9E37pdisXkVofpPt3mfg9z8Aw==&lt;/diagram&gt;&lt;/mxfile&gt;" style="background-color: rgb(42, 42, 42);"><defs><clipPath id="mx-clip-4-30-132-30-0"><rect x="4" y="30" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-60-132-30-0"><rect x="4" y="60" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-90-132-30-0"><rect x="4" y="90" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-120-132-30-0"><rect x="4" y="120" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-150-132-30-0"><rect x="4" y="150" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-180-132-30-0"><rect x="4" y="180" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-210-132-30-0"><rect x="4" y="210" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-240-132-30-0"><rect x="4" y="240" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-270-132-30-0"><rect x="4" y="270" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-300-132-30-0"><rect x="4" y="300" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-330-132-30-0"><rect x="4" y="330" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-360-132-30-0"><rect x="4" y="360" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-390-132-30-0"><rect x="4" y="390" width="132" height="30"/></clipPath><clipPath id="mx-clip-4-420-132-30-0"><rect x="4" y="420" width="132" height="30"/></clipPath></defs><g><path d="M 0 30 L 0 0 L 140 0 L 140 30" fill="rgb(42, 42, 42)" stroke="rgb(240, 240, 240)" stroke-miterlimit="10" pointer-events="all"/><path d="M 0 30 L 0 450 L 140 450 L 140 30" fill="none" stroke="rgb(240, 240, 240)" stroke-miterlimit="10" pointer-events="none"/><path d="M 0 30 L 140 30" fill="none" stroke="rgb(240, 240, 240)" stroke-miterlimit="10" pointer-events="none"/><g fill="rgb(240, 240, 240)" font-family="Garamond" pointer-events="none" text-anchor="middle" font-size="12px"><text x="69.5" y="19.5">Registers</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-30-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="49.5">0X</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-60-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="79.5">AX</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-90-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="109.5">BX</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-120-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="139.5">CX</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-150-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="169.5">DX</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-180-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="199.5">EX</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-210-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="229.5">FX</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-240-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="259.5">GX</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-270-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="289.5">FLG</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-300-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="319.5">IP</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-330-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="349.5">SP</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-360-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="379.5">BP</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-390-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="409.5">PDR</text></g><g fill="#000000" font-family="FreeMono" pointer-events="none" clip-path="url(#mx-clip-4-420-132-30-0)" text-anchor="middle" font-size="12px"><text x="69.5" y="439.5">IDTR</text></g></g></svg>
\ No newline at end of file
diff --git a/doc/src/title.txt b/doc/src/title.txt
new file mode 100644
index 0000000..8ff72f6
--- /dev/null
+++ b/doc/src/title.txt
@@ -0,0 +1,8 @@
+---
+title: Vertex Architecture Manual
+subtitle: A KISS Architecture
+author:
+        - Danny Holman
+        - Jon Sanderson
+date: June 14, 2022
+---