docs(reference): 07-hardware — SIBO/Workabout MX programming reference

docs/reference/07-hardware.md

@@ -0,0 +1,581 @@
+# Psion SIBO / Workabout — Hardware Reference for Programmers
+
+Scope and sources. This reference is compiled **only** from two Psion manuals:
+
+- **HDK** — *The Psion SIBO Hardware Development Kit*, Psion PLC, Rev 1.00, May 1995.
+- **WPG** — *Workabout Programming Guide* (Workabout Programmers Reference), hardware
+  appendices / introduction.
+
+Citations are given as `[HDK p.N]` or `[WPG §/p]`. Where a fact is asserted by the manuals it is
+cited; nothing here is invented. The manuals themselves note that both refer onward to a separate
+*Hardware Reference manual* and *SIBO Computers Programmers Reference* for the full physical
+memory map — those documents are **not** in scope, so the memory-map section below is limited to
+what the two supplied manuals actually state, and gaps are marked explicitly.
+
+> **MX note.** The two supplied manuals describe the **V30H**-based Workabout (NEC V30H at
+> 7.68 MHz) and the ASIC1/ASIC2/ASIC4/ASIC5/ASIC9 family. **They do not mention the V30MX or
+> ASIC9MX.** Every statement about the **V30MX / ASIC9MX / Workabout MX** in this document is
+> therefore flagged as **[MX — not in supplied manuals]** and is presented only as an orientation
+> note, not as a sourced fact. Treat all MX specifics as *uncertain / to be confirmed against the
+> MX hardware reference.*
+
+---
+
+## 1. SIBO architecture overview
+
+All Psion machines in this family are built on the proprietary **SIBO** ("SIxteen Bit Organiser")
+architecture: a battery-powered, 8086-class computer system designed for size, weight and power
+[HDK p.2; WPG §basic hardware].
+
+Key components of the architecture [HDK p.2; WPG p.1-x]:
+
+- An **8086-class processor**.
+- A **power-management system** that selectively powers subsystems under software control.
+- An **asynchronous high-speed serial protocol** (the *Psion SIBO serial interface*) between the
+  machine and its peripherals.
+- **Solid State Disks (SSDs)** — fast, low-power, silicon mass storage, no moving parts.
+- **Hardware protection** from aberrant software: trapping of out-of-range addressing, plus a
+  **watch-dog timer** that fires if interrupts are left disabled too long.
+- **Real-time clock**, **ROM-resident system software**, **graphics LCD**.
+- On some models: touch digitiser pad; ISDN-8-bit combo sound.
+
+The digital logic of a SIBO machine is implemented in custom **ASICs** (Application Specific
+Integrated Circuits). At the time of the HDK there were **ten** SIBO ASICs; all are static-CMOS
+surface-mount parts [HDK p.2].
+
+### 1.1 Processor (NEC V-series)
+
+- The MC/HC/Series 3 and the Workabout use the **NEC V30H**, "an enhanced 16-bit CMOS version of
+  the 8088 found in the original IBM PC … software compatible with the 8088" [HDK p.2].
+- **Workabout:** NEC V30H, clocked at **7.68 MHz** [WPG p.1-x, Tech Spec: "NEC V30 running at
+  7.68 MHz"].
+- The V30H is a **fully static** design: all internal storage (registers) is static, so there is
+  **no minimum clock speed** and the clock can be stopped at any instant with **no loss of state**.
+  SIBO exploits this to stop the clock while the CPU is idle, saving power [HDK p.2].
+
+> **[MX — not in supplied manuals]** Later Workabout variants are marketed as the **Workabout MX**,
+> based on the **NEC V30MX** core integrated in the **ASIC9MX**. Neither the V30MX nor ASIC9MX
+> appears in the HDK or WPG supplied here; their clock rate, memory reach and register differences
+> are **not documented in these sources** and must be confirmed elsewhere. Software written to the
+> V30H/8086 programming model and the ASIC register interfaces below is the documented baseline.
+
+### 1.2 Chip integration levels
+
+- **Discrete generation** (MC, HC, Series 3): three principal chips — **V30H + ASIC1 + ASIC2**
+  [HDK p.2].
+- **Integrated generation** (Series 3a, Workabout): V30H, ASIC1 and ASIC2 collapsed into a single
+  custom chip, **ASIC9** (plus general I/O and PSU-control logic). ASIC9 "integrates all the
+  digital logic required to produce a SIBO architecture computer less the memory onto one chip",
+  and adds a free-running clock (FRC) and a codec interface for sound [HDK p.4].
+
+So on the Workabout, the functions attributed below to "ASIC1" (system/interrupt/LCD) and "ASIC2"
+(peripheral/serial-protocol/power) are physically inside **ASIC9** [HDK p.4].
+
+> **[MX — not in supplied manuals]** On the MX, the equivalent single-chip part is **ASIC9MX** with
+> the **V30MX** core. Same architectural role as ASIC9 is assumed; specifics unconfirmed here.
+
+---
+
+## 2. The ASICs and their roles
+
+| ASIC | Role (from HDK p.4) |
+|------|---------------------|
+| **ASIC1** | Main **system controller**. Connects directly to the V30H, controlling all CPU bus cycles (forming a micro-controller-like unit executing 8086 code). Blocks: bus controller, programmable timer, **eight-input interrupt controller**, **LCD controller**, memory-decode circuitry. |
+| **ASIC2** | **Peripheral controller**. Contains the system clock oscillator; controls standby↔operating switching; interfaces to PSU, keyboard, buzzer and SSDs; contains the **eight-channel SIBO serial-protocol controller**; drives the reduced-external and extended-internal expansion ports. |
+| **ASIC4** | Serial-protocol **slave** for addressing memory / memory-mapped peripherals. Used in SSDs. A cut-down ASIC5. See §5. |
+| **ASIC5** | General-purpose I/O **slave** with an on-board **UART**; several modes (RS232 / parallel / barcode / card-reader / memory pack). See §6. |
+| **ASIC9** | Composite: **V30H + ASIC1 + ASIC2** + general I/O + PSU control on one die; adds FRC and codec interface. Used in S3a and Workabout. |
+
+On the **host** side of the SIBO serial link the controller (SPC) is in **ASIC2** (HC/MC/S3) or
+**ASIC9** (S3a/Workabout). On the **peripheral** side the slave (SPS) is **ASIC4** or **ASIC5**
+[HDK p.4, p.6].
+
+> **[MX — not in supplied manuals]** **ASIC9MX** — the composite CPU/LCD/system chip on the MX — is
+> not described in these sources. Assume it plays the ASIC9 role (V30MX core + ASIC1/ASIC2
+> functions). No register-level MX detail is available here.
+
+---
+
+## 3. Memory: ROM / RAM / SSD and segments
+
+What the supplied manuals state:
+
+- **ROM:** all Workabout models have **1 MB internal masked ROM** holding the OS (EPOC), the
+  MS-DOS-like Command Processor, OPL editor and other utilities [WPG p.1-9, Tech Spec].
+- **RAM:** Workabout ships with either **256 KB** or **1 MB** internal RAM (Tech Spec lists memory
+  build codes A=256 KB, B=512 KB, C=1 MB, D=2 MB) [WPG p.1-x, Tech Spec, serial-number table].
+- **SSD:** two SSD drives, exposed as **drive A:** (top) and **drive B:** (bottom); RAM or Flash
+  SSDs, "up to 8 MB" of extra storage [WPG p.1-3, Tech Spec]. SSDs retain data independently of the
+  main power source [WPG p.1-4]. Contents of the internal RAM are preserved across power-off (the
+  machine resumes previous state on power-on) [WPG p.1-x].
+- **Internal drive M:** internal RAM is also exposed as a filing volume **M:** (with
+  `M:RAMDRIVE`), formattable like an SSD volume [WPG §FORMAT, §MEM].
+
+### 3.1 The programmer's memory model (segments, protection)
+
+- The CPU is 8086-class, so software sees the standard **16-bit segmented** address model
+  (segment:offset, 16-byte "paragraphs") [HDK, WPG passim]. `LSEG` reports each segment's **segment
+  address**, **size in paragraphs** (1 paragraph = 16 bytes) and **access count** [WPG §LSEG].
+- **Memory protection:** any attempt by an application to write **outside its own data segment**
+  causes the OS to terminate it (a **"panic"**); likewise leaving interrupts disabled too long
+  (watch-dog) [WPG §Resetting; HDK p.2].
+- **`MEM`** reports free RAM in KB; this exceeds free bytes on `M:` because "some parts of internal
+  memory are reserved for code and data segments" [WPG §MEM].
+- The OS **moves memory segments** at runtime (e.g. when a driver is installed/removed). Drivers
+  must cope: FAR return addresses into the OS stay valid, but a driver's own absolute segment
+  address may change, so ISR/PDD addresses must be re-established on **resume** (see §7.4)
+  [HDK p.40–42].
+
+### 3.2 Banking / paging — status in these sources
+
+The physical **memory map and paging/banking scheme of the host CPU are not laid out in the
+supplied manuals**; both defer to the separate *SIBO Computers Programmers Reference* / *Hardware
+Reference* [WPG p.1-3: "See the SIBO Computers Programmers Reference manual for further details
+regarding SSDs"; HDK p.2]. What the HDK *does* document is the **address decode inside ASIC4/ASIC5
+slaves**, i.e. how a peripheral or SSD's own address space is banked via **chip-select blocks**:
+
+- **ASIC4:** 8 chip-selects forming selectable **addressing blocks**, size software-defined,
+  **default 32 KB/block**; the filing system re-sizes the block when reaching the top of the
+  address space [HDK p.24]. Up to **28 address bits (256 MB)** in Extended mode; **21 bits + 4
+  chip-selects (4 × 2 MB)** in SSD/compatibility mode [HDK p.25]. See §5.
+- **ASIC5 (pack mode):** address lines A0–A20 generated across ports B/D/C, with **CS0–CS3**
+  selected by SEL0/SEL1; **counter mode** on port B auto-increments the low address so 256
+  consecutive locations can be read without re-addressing [HDK p.30, p.57].
+
+> **Gap flagged:** the host-side ROM/RAM/SSD address ranges, and any V30-level bank registers, are
+> **not in these two manuals**. Do not infer them from the peripheral-side decode above.
+
+---
+
+## 4. SIBO serial protocol (host ↔ peripheral bus)
+
+Everything a program does to an ASIC4/ASIC5 peripheral goes over the **two-wire synchronous SIBO
+serial link** [HDK p.6]:
+
+- **CLK** — clock, always **output from the controller** (ASIC2/ASIC9). Nominal **3.84 MHz** for
+  memory interfaces; **1.536 MHz continuous** for peripherals. Tri-stated low when idle
+  [HDK p.6].
+- **DATA** — bi-directional, synchronous. Direction is set by the transport layer, not the
+  physical layer. Changed on falling CLK edge by the transmitter, latched on rising edge by the
+  receiver; pulled low when idle [HDK p.6].
+
+**Framing (physical layer).** 12-bit frames, 8 data bits each → theoretical max ≈ **312 KB/s**
+[HDK p.6]. Frame = `ST` (start, goes high) · `CTL` (0 = control frame, 1 = data frame) · `I1`
+(idle/turn-around) · `D0–D7` · `I2` (idle) [HDK p.7]. Four frame types: **Null** (sync all slaves —
+12 clocks with DATA held low), **Control**, **Data-out** (controller→slave), **Data-in**
+(slave→controller; controller drives cycles 1–2 then tri-states, slave drives D0–D7) [HDK p.7].
+
+**Transport layer.** The controller has two registers: a write-only **Control register** and a
+read/write **Data register** (byte or word) [HDK p.8]. Control bytes are classified by **bit 7,
+the Select (S) bit**:
+
+- **S = 0 — Slave-select mode.** Byte = `R` (reset bit) + **6-bit slave ID**. ID 0 is illegal, so
+  up to **63 slaves** per controller. `R=0` resets, `R=1` selects. Selecting a slave with `R=1`
+  makes it return a **non-zero 8-bit info byte**; a reply of **0 means no slave of that ID present**
+  [HDK p.8–9].
+- **S = 1 — Slave-control mode.** Byte = `R/W` (0=write,1=read) · `B/W` (0=byte,1=word) · `S/M`
+  (0=single,1=multi) · 4 slave-specific data bits. Byte-pair (word) transfers are **listed as not
+  implemented** [HDK p.9].
+
+**Timing rules (clock cycles, ≈260 ns each at 3.84 MHz)** [HDK p.10–11]:
+control-byte process = 12 cycles; byte transfer = 12 cycles; byte-pair = 24 cycles. After writing
+the control register, wait ≥12 cycles before touching the data register or writing another control
+word.
+
+Assembler helper macros the HDK uses for all of this [HDK p.52]:
+
+| Macro | Action |
+|-------|--------|
+| `SCONTOUT` | Output control byte in AL |
+| `SDATAOUT` | Output data byte in AL |
+| `SDATAIN`  | Input a data byte into AL |
+| `SBUSY`    | Wait while the link is busy |
+| `XNOP`     | Short wait |
+| `HwNullFrame` | Emit a null frame to sync slaves |
+
+Serial-protocol control defines (`SerialSelect`, `SerialReadSingle`, `SerialWriteSingle`, slave
+IDs) live in `ospack.inc` / `ossibo.inc` [HDK p.59].
+
+---
+
+## 5. ASIC4 — memory / peripheral slave
+
+Purpose: convert SIBO serial frames into the address/data/control signals needed to drive memory
+and memory-mapped peripherals; used in SSDs and in ASIC4-based expansion boards [HDK p.24].
+
+**Bus:** 8-bit data, **28-bit address**, **8 chip-selects** (CS0–CS7) [HDK p.24].
+
+### 5.1 Modes (selected by slave ID)
+
+Select ASIC4 with the appropriate ID, then read the info byte [HDK p.25]:
+
+- **SSD / ASIC5-compatibility mode — ID 2.** Mimics an ASIC5 in pack mode; compatible with all
+  existing SSD software. Max **21 address bits + 4 CS (4 × 2 MB)**.
+- **ASIC4 Extended mode — ID 6.** Up to **28 address bits (256 MB)**. On reset, four extra config
+  bits come from A27–A24; **A27 = M** selects standard-SSD (M=0) or **mixed mode (M=1)** —
+  memory + peripherals. Mixed mode is the one of interest for peripheral developers.
+
+**Mixed mode split:** address space halves — lower half = memory-mapped peripherals (any use),
+upper half = pure memory (typically a control ROM the filing system can mount). Chip-selects split:
+**CS0–CS3 = peripheral blocks, CS4–CS7 = memory devices 1–4** [HDK p.25–26].
+
+**Reset config** is read from the data bus (**Info Byte**, D0–D7) and A24–A27 (extended nibble),
+set with pull-up/pull-down resistors (~100 k so the bus can still drive the lines in normal
+operation) [HDK p.26].
+
+### 5.2 ASIC4 registers (mixed/peripheral mode) [HDK p.53–55]
+
+| Reg | Name | R/W | Notes |
+|-----|------|-----|-------|
+| **0** | **Data Register** | R/W | Drives/reads D0–D7 (tri-state when idle). **On reset holds the Info Byte** (see below). |
+| **1** | **Input Register** (read) / **Device-Size Register** (write) | R/W | Read: extended-info bits + live state of general inputs **In0–In2** and X2. Write: bits S3–S0 set the address-decoder block size (32 KB … 256 MB); defaults to `0x0F` (unused) on reset. |
+| **2** | **Address-Increment Register** | W | A write increments address lines A0–A3. |
+| **3** | **Address Register** | W (multi-byte, LSB first) | Loads all 28 address lines. Bytes: **ATO = A0–A7, AT1 = A8–A15, AT2 = A16–A23, AT3 = A24–A27**. Writing the first byte resets A8–A27 to 0. AT3 bits 4–6 can steer CS0–CS3. Cleared on reset. |
+| **4,5,6** | — | — | **Not implemented.** |
+| **7** | **Control Register** | W | Bits: `7 LBO · 6 TSTA · 5 LTM · 4 VPS · 3 EDA · 2 CSS · 1 WRS · 0 OES`. Setting **LBO** / **VPS** drives those pins high (usable as GP outputs). **OES/WRS** control read/write accesses. |
+
+**Info Byte** (Reg 0 at reset) [HDK p.53]: bits encode **device type** (RAM / Intel Flash type 1 /
+type 2 / read-only SSD / hardware write-protected SSD), **number of devices** (1–4), and **device
+size** (000 = no SSD present, then 32 KB → 2 MB). In Extended mode a further **Extended Info Byte**
+(M, De, Ne, Se) identifies the peripheral type — e.g. `1 0 0 1` = Turbo RS232 (16550), `1 0 1 0` =
+3Fax, `1 1 1 1` = extended info held in ROM [HDK p.54].
+
+**Access sequence** (bottom 256 addresses) [HDK p.58–59]: control-write to the **Address** register
+→ data-write the address → control-frame read/write to the **Data** register → transfer the byte.
+The HDK gives `Input`/`Output` assembler routines doing exactly this; **interrupts must be off**
+during them so the host does not multitask mid-transfer.
+
+**Other pins** [HDK p.27, p.55]: `In0–In2` GP inputs; `LBO` (open-drain low-battery driver), `VPS`
+(VPP control) GP outputs; `OE`/`WR` bus control; `SCLK`/`SDAT` the serial link; `SDIR` protocol
+direction bit; `POR` reset; `ATST` test (pull high = address test mode); `MCSD`/`X2D2` tie to GND
+via 100 k. A PSRAM mode reuses some pins for refresh/oscillator.
+
+---
+
+## 6. ASIC5 — UART / parallel / barcode / card-reader slave
+
+Three primary functions: a **UART** (up to **48000 baud**), **general-purpose I/O**, and
+**address/data lines** for memory / memory-mapped peripherals [HDK p.29].
+
+### 6.1 Modes
+
+- **Pack mode:** generates full address/data/control to access memory; **no peripheral functions**.
+- **Peripheral mode:** limited memory addressing (lines reused for I/O). Entered by setting the
+  **peripheral bit (bit 0) in the Port-B mode register** [HDK p.29].
+
+**Port re-use** [HDK p.30]:
+
+- **PA0–PA7** — 8-bit non-latched GP I/O; in peripheral mode **PA0–PA3 = UART RX, CTS, DSR, DCD**;
+  **PA4** is a change-of-state interrupt source (e.g. Centronics **BUSY**, or **RI** on the VIC —
+  see below). In pack mode PA0–PA7 is the memory data bus.
+- **PB0–PB7** — latched output / **counter** mode; in pack mode = address **A0–A7**.
+- **PD0–PD7** — GP outputs; in pack mode = address **A8–A15**; in peripheral mode **PD0/PD1/PD2 =
+  UART TX, RTS, DTR**.
+- **PC0–PC4** — in pack mode = address **A16–A20**; in peripheral mode **PC4/PC7** = inverted
+  edge-triggered interrupt inputs, **PC5** = interrupt output, **PC6** = GP latched output +
+  pack/peripheral select at reset, **PC0–PC3** = a **dual synchronous serial port** for magnetic
+  card readers.
+
+**UART details** [HDK p.29–30, p.61]: needs the host link in **continuous-clocking** mode (baud
+clocks are derived from the 1.536 MHz link clock). No internal buffering — the **Transmitter
+Holding Register must be empty** before writing. One shared **active-high interrupt line**; software
+reads the status/interrupt registers to find the cause. Reading the UART Status register clears the
+Tx interrupt.
+
+**Barcode:** the UART receives data from a dedicated barcode-scanner IC [HDK p.30].
+**Card readers:** two synchronous serial ports (PC0–PC3) take clocked serial data [HDK p.30].
+
+**Reset config** read from **PA0–PA7** (device type/size, like ASIC4); **PC6** selects pack vs
+peripheral; in peripheral mode PA0–PA7 indicate the peripheral type (RS232 port / Centronics port,
+combinable) [HDK p.31].
+
+### 6.2 ASIC5 register set — the sixteen registers
+
+Reading/writing a register is two steps: send a control byte selecting the register, then
+read/write the data [HDK p.56]. Register list [HDK p.56–57, cross-checked against the
+`SYS$AS5.ASM` defines at HDK p.102]:
+
+| Reg | Name | R/W | Function |
+|-----|------|-----|----------|
+| **0** | **Port A data** | R/W | Read/write Port A; a read/write triggers a memory access cycle (pack mode) or one-cycle CS0 strobe (peripheral mode). |
+| **~2** | **Port B data** | R/W | Latches PB0–PB7 (= A0–A7 in pack mode); read returns last value. |
+| **~4** | **Port B mode / Inc** | R/W | **bit 0 = 0 memory / 1 peripheral (enables UART)**; also selects **counter** vs **latch** mode and "baud rate out on Port B". Counter increments on Port A access. |
+| **~5** | **Port C/D write** | W | First write latches PD0–PD7; subsequent (multiwrite) writes latch Port C, incl. **SEL0/SEL1** choosing CS0–CS3. In peripheral mode PD0 = UART TX (bit 0 has no effect). |
+| **6** | **Interrupt Mask** | R/W | 1 = enable that event's interrupt; 0 = disable. All disabled on reset. |
+| **~7** | **Interrupt Status / Type-Ctrl** | R | Reading indicates interrupt source; bit meanings mirror the mask. |
+| **8** | **UART Status / UART Control** | R/W | Format (stop/data bits, parity), break, and status (Tx empty, Rx/parity/framing/overrun errors). |
+| **9** | **UART Receive / Transmit holding register** | R/W | Read = received char; write = char to transmit. |
+| **10** | **UART Baud rate LSB** | W | Low byte of baud divisor. |
+| **11** | **UART Baud rate MSB** | W | High byte of baud divisor. |
+| **12** | **MCR shift register** | — | Magnetic-card-reader shift register. |
+| **13** | **Barcode read data** | R | Returns states of the barcode lines / general interrupt bits. |
+| **14** | **Synchronous Port 2 read** | R | Second synchronous serial port (card reader). |
+| **(15)** | (sync port 1 / reserved) | — | Synchronous-port-1 data; documented in prose (sync port 1 & 2 char-received are distinct interrupt sources). |
+
+> The HDK's printed register table is OCR-garbled for some indices; the register **names, R/W
+> attributes and functions** above are taken verbatim from the HDK prose (p.56–57) and the
+> assembler comment block in `SYS$AS5.ASM` (p.102): *Port A R/W · Port B R/W · Inc/Mode · Port CD
+> write-only · Interrupt mask R/W · IntType/Ctrl · UART Status/Ctrl · Receive/Transmit · Baud Rate
+> (×2, write-only) · MCR shift register · Barcode data & ints.* Exact numeric slots for the
+> mid-range registers should be confirmed against the include files (`ospack.inc`, `ossibo.inc`).
+
+**Interrupt-mask bits** [HDK p.56, and `S_*` defines p.102]: UART character received; UART
+transmitter awaiting character; modem/handshake change of state; **synchronous port 1 char
+received**; **synchronous port 2 char received**; **barcode data / general interrupt**. Reading the
+**Interrupt Status** register (same bit layout, high = active) identifies the source [HDK p.56].
+
+**UART Status/Control bits** (`SYS$AS5.ASM`, HDK p.102):
+
+| Define | Value | Meaning |
+|--------|-------|---------|
+| `S_RXENB` | `0000_0001b` | Receive interrupt enable |
+| `S_TXENB` | `0000_0010b` | Transmit interrupt enable |
+| `S_TXEMPTY` | `0001_0000b` | Transmit buffer empty (status) |
+| `S_RXINT` | `0000_0001b` | Receive interrupt pending |
+| `S_TXINT` | `0000_0010b` | Transmit interrupt pending |
+| `S_MDINT` | `0000_0100b` | Modem-status interrupt |
+| `S_CTS`/`S_RTS`/`S_DCD`/`S_DSR`/`S_DTR` | `01b`/`02b`/`04b`/`02b`/`04b` | Handshake-line states |
+| `OVERRUN_ERROR` | `0100_0000b` | Character overrun |
+| `PARITY_ERROR` | `1000_0000b` | Parity error |
+| `S_PERIPHERALMODE` | `0000_0011b` | ASIC5 RS232 (peripheral) mode |
+| `S_UART_OFF` | `0000_0010b` | ASIC5 peripheral mode, UART off |
+
+**Baud rate.** `Divisor = 1 − (96000 / desired_baud)`, written as a 16-bit word: LSB → reg 10,
+MSB → reg 11 [HDK p.61]. The driver's `BaudRateTable` (HDK p.102) holds the two's-complement
+divisors, e.g. `-0x077F, -0x04FF, -0x0368, -0x02CC, -0x027F, -0x013F, -0x009F, -0x004F, -0x0035,
+-0x0030, -0x0027, -0x0019, -0x0013, -0x000C, -0x0009, -0x0004` for the standard rates.
+
+### 6.3 Selecting / configuring ASIC5
+
+Before use, select the chip (and re-select after every hold/resume from power-down, pack-door, or
+insert/remove) [HDK p.56]. Selection differs by mode:
+
+- Peripheral: `mov al,(SerialSelect or Asic5NormalId)` → `SCONTOUT` → `SDATAIN`; a **zero reply
+  means no ASIC5 present** [HDK p.56].
+- Pack: same with `Asic5PackId` [HDK p.56]. An **ASIC4 will answer a pack-mode select** (it
+  impersonates an ASIC5 in pack mode) [HDK p.56].
+
+---
+
+## 7. I/O ports, interrupts and the channel model
+
+### 7.1 Eight hardware interrupts
+
+SIBO supports **8 level-triggered hardware interrupts**, IRQ0 (highest) … IRQ7 (lowest), handled by
+the interrupt controller in **ASIC1 (or ASIC9)**. Expansion ports carry an interrupt line into this
+controller [HDK p.3]:
+
+- **Extended internal** expansion ports: **active-low** interrupt input.
+- **Reduced external** expansion ports (S3a 6-pin, Workabout LIF): **active-high** interrupt input.
+
+Servicing order [HDK p.3]:
+
+1. Device asserts its IRQ line.
+2. The controller (ASIC2/ASIC9) places the **vector of the highest-priority pending device** on the
+   data bus; the CPU jumps to that ISR.
+3. The ISR clears the interrupt at the device (device-specific action).
+4. The ISR writes the **non-specific end-of-interrupt (NSEOI/NSEOD)** location to tell the
+   controller the interrupt is cleared.
+5. Repeat if another is pending.
+
+**Nested interrupts are not possible** on these 8086-class processors [HDK p.3].
+
+### 7.2 The four channel variables
+
+To be portable across host machines, a driver parameterises four values per expansion channel
+[HDK p.52]:
+
+- **Channel interrupt mask** — an 8-bit value OR'd into the mask register (`A1InterruptMask` or
+  `A9BInterruptMask`, depending on whether the controller is ASIC1 or ASIC9) to enable interrupts on
+  that channel; also passed to `HwGetChannel` / `HwFreeChannel`.
+- **Channel interrupt number** — 16-bit, used with `GenSetRevector` / `GenResetRevector` to say
+  which default ISR the driver replaces.
+- **Channel interrupt vector** — 16-bit pointer to the driver's ISR.
+- **Hardware SIBO channel** — used by `HwSelectChannel` to route serial frames to that channel.
+
+### 7.3 Per-platform channel map [HDK p.52]
+
+| Host | Controller | Ports and channels |
+|------|-----------|--------------------|
+| **Series 3** | ASIC2 | Expansion port C = serial **channel 7**, interrupt `Asic2Int` (IRQ4), select `SelectChannel7`. |
+| **Series 3a** | ASIC9 | Expansion port C = serial **channel 5**, mask `A9MSlave`, revector `IHwIrq2Revector` (IRQ2), select `SelectChannel5`. |
+| **Workabout / HC (3-channel)** | ASIC9 / ASIC2 | Port **A** (top) and port **B** (bottom) internal + port **C** (side/cradle); masks `ExpIntLeftA` / `A9MExpIntA`, `ExpIntRightB` / `A9MExpIntB`, plus the slave/`Asic2Int` channel; selects `ExpChannelLeftA`, `ExpChannelRightB`, `SelectChannel5/7`. |
+
+Build flags select the machine so one driver source compiles for all: **Consumer (S3a)** = 1 SIBO
+channel; **HC/S3C** = 3 channels; S3 = single-channel [HDK p.51–52; `SYS$AS5.ASM` p.102].
+
+### 7.4 Owning and selecting a channel
+
+The S3/S3a/HC have **three** Psion serial links: two are the SSD slots, the third is the expansion
+port [HDK p.60]. Only **one link is selected at a time**.
+
+- **`HwGetChannel`** (AL = channel interrupt mask): reserve a channel; **carry clear = success**.
+  Normally called from the driver's **open** vector; open should fail if the channel is unavailable
+  [HDK p.60].
+- **`HwFreeChannel`** (AL = mask): release it (on close) [HDK p.60].
+- **`HwSelectChannel`** (AL = select code): make a channel current; **returns the previously
+  selected channel in AL** so it can be restored on exit [HDK p.60].
+
+Discipline [HDK p.60]: select the correct channel on entry to any vector/ISR that talks down it, and
+restore the previous one on exit. **Disable interrupts (multitasking) between select and restore** —
+but only briefly, because the **watch-dog** forbids leaving interrupts off indefinitely; hence
+comms happen in short bursts. Idiom:
+
+```asm
+    pushf
+    cli
+    mov  al, SelectChannel5
+    HwSelectChannel        ; old channel returned in AL
+    push ax
+    ; ... Input / Output to the peripheral ...
+    pop  ax
+    HwSelectChannel        ; restore previous channel
+    popf
+```
+
+### 7.5 Channel unit letters (open qualifiers)
+
+A driver can support several channels distinguished by a **single-letter qualifier** appended to
+the device name, allocated from `'A'` [HDK p.38]. Convention: **A = top port, B = bottom port,
+C = side/cradle port** [HDK p.38]. Example: `p_open(&pcb,"PAR:A",-1)`. On the S3a only **one** SIBO
+channel (port C) can be opened; on Workabout/HC up to **three** (A, B, C) [HDK p.38]. The VIC's
+extra serial connectors appear to the Workabout as standard serial devices **ports I and F**, and
+the extended 15-way port is addressed as **port C** [WPG Appendix A, VIC].
+
+### 7.6 Direct I/O (HC extended internal ports)
+
+On the HC's 25-way extended internal ports, expansion devices also get **direct processor I/O**:
+`AD0–AD7` (multiplexed addr/data, low half only → up to 128 I/O addresses, even addresses only),
+`ALE`, `IOWR`, `IORD`, `EES` (External Expansion Select — high during I/O to that device), `INTR`
+(active-high IRQ to ASIC1). Port 1 decodes I/O `100–1FF`, port 2 `200–2FF`; A0 is always low for
+valid writes so A1 is the lowest usable address line [HDK p.19]. Each HC port also carries one SIBO
+serial channel (port 1 = channel 5, port 2 = channel 6) [HDK p.20]. (The Workabout uses a 26-way
+Torson connector for its internal expansion — see §8.)
+
+---
+
+## 8. Expansion slots, ports and connectors
+
+### 8.1 Overview by machine [HDK p.2]
+
+| Machine | SSD ports | Expansion |
+|---------|-----------|-----------|
+| MC / HC | 2 | Two independent single-row **25-way extended internal** ports (SIBO channel + direct parallel I/O + 7.2 V battery). |
+| Series 3 / 3a | 2 | One **6-pin reduced external** port (port C): SIBO serial channel + limited power (**< 25 mA**). |
+| **Workabout** | 2 (A: top, B: bottom) | Two internal expansion points + one **11-pin LIF** external port. Each internal port = single-row **26-way** carrying two high-speed serial ports. |
+
+### 8.2 Workabout internal 26-way (Torson) connector [HDK p.13]
+
+Signals: **Vcc1** = 3.0 V nominal, **≤ 100 mA**; **Vcc2** = 5 V nominal, **≤ 200 mA**; **RUN**
+(low = powered down, high = powered up — used to power-down/reset the module); **SCK2/SCK3** serial
+clocks (run continuously at **1.536 MHz** when the port is in use; clock the ASIC5 UART in the
+RS232-AT/TTL and AT/Barcode modules); **SD2/SD3** bi-directional serial data; **EINT1/EINT2**
+active-low interrupt inputs; **EXON** active-high turn-on. All logic at **3.0/3.3 V** (per Vcc1).
+Unused lines are reserved for a codec interface.
+
+The Workabout expansion module (RS232/TTL or RS232/Barcode) connects the main board to the module
+via this 26-way Torson connector + flexi cable; modules are **factory-fitted** [WPG p.1-3,
+Appendix A]. The RS232/TTL module runs up to **19,200 baud**; the RS232/Barcode module uses an HP
+HBCR-1612 micro to decode and transmit barcode data at up to **9,600 baud** [WPG Appendix A].
+
+### 8.3 Workabout external 11-pin LIF connector [HDK p.14–16]
+
+The reduced external port for connecting to the Cradle system. Standard pin functions (Polarisation
+Type B, cradle perspective) [HDK p.16]:
+
+| Pin | Name | Function |
+|-----|------|----------|
+| 1 | LCA | Local Computer Active — high when the computer is on. Workabout can **source 100 mA** from this pin (HC/HCDOS: 5 mA). |
+| 2 | EXON | External switch-ON, active-high (+5 V) — asserted by a remote/cradle device to switch the computer on. |
+| 3 | THERM | Battery thermistor terminal. |
+| 4 | DLA | Disconnect Local ASIC (does not apply to Workabout). |
+| 7 | VIN | Power supply to computer (+10 V). |
+| 8 | SCLK | Serial-channel clock. |
+| 9 | GND | Power / signal ground / −ve battery (1 A). |
+| 10 | SDATA | Serial-channel data. |
+| 11 | STATUS | Cradle status; pulled-up for open-collector sensing (low = remote device present). |
+
+Type-A polarisation repurposes several pins for RS232 signals. The LIF cover can be moulded with a
+polarising pin in up to four positions to differentiate variants [HDK p.14].
+
+### 8.4 S3/S3a 6-pin reduced external port (port C) [HDK p.12]
+
+Six wires: **MSD/MCLK** (a master SIBO serial channel — **channel 7 on S3, channel 5 on S3a**),
+**SDS/INT** and **SCK/EXON** (dual-function: form a slave serial channel, or SDS/INT is an
+active-high interrupt, and a rising edge on SCK/EXON wakes the machine from standby), **VCC** (+5 V,
+switched off in standby, **max 25 mA**). Opening the pack doors on an S3a or Workabout **cuts power
+to external peripherals** [HDK p.12].
+
+---
+
+## 9. Power
+
+- **Workabout power sources** [WPG p.1-4, Appendix A]: NiCd rechargeable pack **or** 2 × AA
+  alkaline (main), plus a **3 V lithium CR1620 backup** battery that preserves internal RAM when the
+  main source is absent (recommend yearly replacement; alone it preserves memory for a limited
+  period). External: a Series 3 mains adaptor via the **LIF Converter** (also trickle-charges), and
+  (from Jan/Feb 1997) a **vehicle power adaptor** / Docking Station.
+- Power management is **software-controlled** and selective; the machine auto-switches-off after
+  ~5 minutes idle by default [WPG p.1-4, §basic hardware].
+- Under **low battery** the Workabout may run the screen/keyboard but refuse to write Flash SSD or
+  access expansion devices; it turns off if such an operation is attempted [WPG p.1-4].
+- **States:** standby vs operating/idle. In standby, switched supplies (VCC/Vcc2) are **off**;
+  peripheral designs must not drive lines high in standby (pull-down inputs cause excessive standby
+  current) [HDK p.12, p.19].
+- **Peripheral power budgets** (from the connector tables): S3a port C **< 25 mA**; HC 25-way Vcc2
+  **50 mA** (or use unregulated **Vsup** 5.5–12 V with a low-dropout regulator for higher loads);
+  Workabout Torson **Vcc1 100 mA / Vcc2 200 mA**; LIF **LCA 100 mA** [HDK p.12, p.19–20, p.13,
+  p.16].
+- **Power-fail handling for drivers** [HDK p.41]: on power loss there is ~**2 ms** to power
+  everything down; the hold vector must be fast or the RAM-hold voltage drops and the machine
+  cold-reboots, losing internal RAM (including any loaded driver). On a power-fail hold the OS has
+  already reset the SIBO channels, so a channel driver need only record the reason for its resume
+  vector. Hold reasons passed in AH: `DevHoldNormal` (memory move), `DevHoldPowerDown` (standby),
+  `DevHoldPowerFail` (supply lost) [HDK p.42].
+
+---
+
+## 10. The SIBO serial link (host ↔ PC / peripheral)
+
+- The **3-Link** is an **ASIC5-based** cable that converts the S3/S3a port-C SIBO serial channel to
+  **RS232** (host ↔ PC/printer), using the ASIC5 on-board UART + line drivers [HDK p.5, p.35].
+- Workabout communications: the OS provides serial comms at up to **19,200 baud**, with **XMODEM /
+  YMODEM** (and ZMODEM except in early models) file transfer, plus a scripting language for modem
+  control [WPG §basic hardware, Tech Spec].
+- The high-speed inter-machine link is the same continuously-clocked SIBO serial channel described
+  in §4; the physical media are the S3a 6-pin port C, the HC 8-pin side port C (used by the HC
+  cradle), or the Workabout 11-pin LIF via the LIF Converter [HDK p.12, p.20; WPG Appendix A].
+
+---
+
+## 11. Programmer's cheat-sheet
+
+- Talking to a peripheral = **own a channel** (`HwGetChannel`) → **select it** (`HwSelectChannel`,
+  save/restore the old one, interrupts off, short bursts) → drive the slave with control/data frames
+  via `SCONTOUT`/`SDATAOUT`/`SDATAIN` → **free it** (`HwFreeChannel`) on close [HDK p.52, p.60].
+- **ASIC4 access** = set Address register (multi-byte, LSB first) → read/write Data register; only
+  even/low-256 addresses in the simple routines; interrupts off during a transfer [HDK p.53–59].
+- **ASIC5 UART** = enable continuous clocking, set peripheral bit (Port-B mode bit 0), write baud
+  divisor `1 − 96000/baud` (LSB reg 10, MSB reg 11), set format in UART Status/Control (reg 8),
+  Tx via reg 9 only when `S_TXEMPTY`, Rx via reg 9, one shared active-high IRQ; read status/interrupt
+  registers to find the cause [HDK p.56–61].
+- **Interrupts** = 8 levels, IRQ0 highest, level-triggered, **no nesting**; clear at the device then
+  write NSEOI [HDK p.3].
+- **Segments** = 8086 model; writing outside your data segment or hogging interrupts → **panic**
+  [WPG §Resetting; HDK p.2].
+
+---
+
+## 12. Known gaps / uncertainties in these sources
+
+- **V30MX / ASIC9MX / Workabout MX:** absent from both supplied manuals. All MX statements above
+  are flagged **[MX — not in supplied manuals]** and are orientation only. Confirm against the MX
+  hardware reference.
+- **Host CPU physical memory map and any bank/page registers:** not in these manuals (deferred to
+  *SIBO Computers Programmers Reference* / *Hardware Reference*). Only the peripheral-side
+  (ASIC4/ASIC5) chip-select block decode is documented here.
+- **Exact ASIC5 register numeric slots (regs ~2, 4, 5, 7):** the printed table is OCR-damaged; names
+  and functions are reliable (prose + `SYS$AS5.ASM`), but verify the numeric indices against
+  `ospack.inc` / `ossibo.inc`.
+- Several connector pin tables in the WPG appendix are OCR-garbled (RS232 module pinouts, VIC 15-way
+  pinout); signal names are recoverable but pin numbers should be checked against a clean copy.