devskill 2.0.6 → 2.0.8

package/skills/legacy-circuit-mockups/references/emulator-6C62256.md

@@ -0,0 +1,233 @@
+# AS6C62256 (32K x 8 SRAM) Emulation Specification
+
+A technical Markdown specification for **emulating the AS6C62256 / 62256-family static RAM**, suitable for 6502-family emulators, SBC simulators, and memory subsystem modeling.
+
+---
+
+## 1. Scope
+
+This document specifies functional behavior for emulating:
+
+* Alliance Memory **AS6C62256**
+* Compatible **62256 (32K x 8) SRAM** devices
+
+Out of scope:
+
+* Analog electrical timing margins
+* Bus contention and signal rise/fall times
+* Power consumption characteristics
+
+---
+
+## 2. Chip Overview
+
+### Core Characteristics
+
+| Feature        | Value                |
+| -------------- | -------------------- |
+| Memory Type    | Static RAM (SRAM)    |
+| Capacity       | 32,768 bytes (32 KB) |
+| Data Width     | 8-bit                |
+| Address Width  | 15-bit (A0-A14)      |
+| Access Type    | Asynchronous         |
+| Supply Voltage | 5 V (typical)        |
+
+---
+
+## 3. External Signals (Logical Model)
+
+| Signal | Direction | Purpose                    |
+| ------ | --------- | -------------------------- |
+| A0-A14 | Input     | Address bus                |
+| D0-D7  | I/O       | Data bus                   |
+| CE#    | Input     | Chip enable (active low)   |
+| OE#    | Input     | Output enable (active low) |
+| WE#    | Input     | Write enable (active low)  |
+
+> `#` indicates active-low signals.
+
+---
+
+## 4. Address Space Mapping
+
+* Address range: `0x0000-0x7FFF`
+* Address lines select one byte per address
+
+### Typical 6502 System Mapping Example
+
+| CPU Address Range | Device         |
+| ----------------- | -------------- |
+| `$0000-$7FFF`     | AS6C62256 SRAM |
+| `$8000-$FFFF`     | ROM / EEPROM   |
+
+---
+
+## 5. Read and Write Behavior
+
+### Read Cycle (Logical)
+
+Conditions:
+
+* `CE# = 0`
+* `OE# = 0`
+* `WE# = 1`
+
+Behavior:
+
+```text
+D[7:0]  memory[A]
+```
+
+If `OE# = 1` or `CE# = 1`, data bus is **high-impedance**.
+
+---
+
+### Write Cycle (Logical)
+
+Conditions:
+
+* `CE# = 0`
+* `WE# = 0`
+
+Behavior:
+
+```text
+memory[A]  D[7:0]
+```
+
+* `OE#` is ignored during writes
+* Write occurs on active WE#
+
+---
+
+## 6. Control Signal Priority
+
+| CE# | WE# | OE# | Result          |
+| --- | --- | --- | --------------- |
+| 1   | X   | X   | Disabled (Hi-Z) |
+| 0   | 0   | X   | Write           |
+| 0   | 1   | 0   | Read            |
+| 0   | 1   | 1   | Hi-Z            |
+
+---
+
+## 7. Emulator Interface Requirements
+
+An emulator must expose:
+
+```text
+read(address)  -> byte
+write(address, byte)
+```
+
+Internal storage:
+
+```text
+uint8_t ram[32768]
+```
+
+Address masking:
+
+```text
+address = address & 0x7FFF
+```
+
+---
+
+## 8. Timing Model (Abstracted)
+
+### Emulation Levels
+
+| Level          | Description               |
+| -------------- | ------------------------- |
+| Functional     | Instantaneous access      |
+| Cycle-based    | Access per CPU cycle      |
+| Cycle-accurate | Honors enable transitions |
+
+For most systems, **functional emulation** is sufficient.
+
+---
+
+## 9. Power and Data Retention
+
+* SRAM contents persist as long as power is applied
+* Emulator shall retain contents until explicitly reset
+
+### Reset Behavior
+
+* **No automatic clearing** on reset
+* Memory contents undefined unless initialized
+
+---
+
+## 10. Bus Contention and Hi-Z Modeling (Optional)
+
+Optional advanced behavior:
+
+* Track when SRAM drives the data bus
+* Detect illegal simultaneous writes
+
+Most emulators may ignore Hi-Z state.
+
+---
+
+## 11. Error Conditions
+
+| Condition            | Emulator Response             |
+| -------------------- | ----------------------------- |
+| Out-of-range address | Mask or ignore                |
+| Read when disabled   | Return last bus value or 0xFF |
+| Write when disabled  | Ignore write                  |
+
+---
+
+## 12. Integration with 6502 Emulator
+
+```text
+CPU memory access
+  address decode
+  if in SRAM range:
+      AS6C62256.read/write
+```
+
+* SRAM access is typically single-cycle
+* No wait states required
+
+---
+
+## 13. Testing and Validation
+
+### Basic Tests
+
+* Write/read patterns
+* Boundary addresses ($0000, $7FFF)
+* Randomized memory tests
+
+### Validation Checklist
+
+* Writes persist
+* Reads return correct values
+* Address wrapping correct
+
+---
+
+## 14. Common Mistakes
+
+| Mistake               | Result                      |
+| --------------------- | --------------------------- |
+| Clearing RAM on reset | Breaks software assumptions |
+| Wrong address mask    | Mirrored memory errors      |
+| Treating as ROM       | Writes ignored              |
+
+---
+
+## 15. Reference Links
+
+* [Alliance Memory AS6C62256 Datasheet](https://www.alliancememory.com/wp-content/uploads/AS6C62256-23-March-2016-rev1.2.pdf)
+* [https://en.wikipedia.org/wiki/Static_random-access_memory](https://en.wikipedia.org/wiki/Static_random-access_memory)
+
+---
+
+**Document Scope:** Software emulation of AS6C62256 SRAM
+**Audience:** Emulator developers, retro SBC designers
+**Status:** Stable technical reference

package/skills/legacy-circuit-mockups/references/emulator-lcd.md

@@ -0,0 +1,266 @@
+# DFRobot FIT0127 LCD Character Display Emulation Specification
+
+## Overview
+
+This document specifies how to **emulate the DFRobot FIT0127 LCD Character Display module**. FIT0127 is a **16x2 character LCD** compatible with the **HD44780 controller**, commonly used in 6502 and microcontroller breadboard systems.
+
+The goal is **functional correctness** for SBC emulators, firmware testing, and UI visualization rather than electrical signal simulation.
+
+---
+
+## Module Summary
+
+| Feature          | Value                   |
+| ---------------- | ----------------------- |
+| Display Type     | Character LCD           |
+| Resolution       | 16 columns x 2 rows     |
+| Controller       | HD44780-compatible      |
+| Interface        | 8-bit or 4-bit parallel |
+| Character Matrix | 5x8 dots                |
+| Supply Voltage   | 5V                      |
+
+---
+
+## Pin Definitions
+
+| Pin  | Name  | Function         |
+| ---- | ----- | ---------------- |
+| 1    | GND   | Ground           |
+| 2    | VCC   | +5V              |
+| 3    | VO    | Contrast control |
+| 4    | RS    | Register Select  |
+| 5    | R/W   | Read / Write     |
+| 6    | E     | Enable           |
+| 7-14 | D0-D7 | Data bus         |
+| 15   | A     | Backlight +      |
+| 16   | K     | Backlight -      |
+
+---
+
+## Logical Registers
+
+| RS | Register             |
+| -- | -------------------- |
+| 0  | Instruction Register |
+| 1  | Data Register        |
+
+---
+
+## Instruction Set (Subset)
+
+| Command         | Code        | Description               |
+| --------------- | ----------- | ------------------------- |
+| Clear Display   | `0x01`      | Clears DDRAM, cursor home |
+| Return Home     | `0x02`      | Cursor to home position   |
+| Entry Mode Set  | `0x04-0x07` | Cursor direction          |
+| Display Control | `0x08-0x0F` | Display, cursor, blink    |
+| Cursor/Shift    | `0x10-0x1F` | Shift cursor/display      |
+| Function Set    | `0x20-0x3F` | Data length, lines        |
+| Set CGRAM Addr  | `0x40-0x7F` | Custom chars              |
+| Set DDRAM Addr  | `0x80-0xFF` | Cursor position           |
+
+---
+
+## Internal Memory Model
+
+### DDRAM (Display Data RAM)
+
+* Size: 80 bytes
+* Line 1 base: `0x00`
+* Line 2 base: `0x40`
+
+Emulator mapping:
+
+```text
+Row 0: DDRAM[0x00-0x0F]
+Row 1: DDRAM[0x40-0x4F]
+```
+
+### CGRAM (Character Generator RAM)
+
+* Stores up to 8 custom characters
+* 8 bytes per character
+
+---
+
+## Data Write Cycle
+
+A write occurs when:
+
+```
+RS = 1
+R/W = 0
+E: HIGH  LOW
+```
+
+### Emulator Behavior
+
+* On falling edge of `E`, latch data
+* Write data to DDRAM or CGRAM depending on address mode
+* Auto-increment or decrement address based on entry mode
+
+---
+
+## Instruction Write Cycle
+
+A command write occurs when:
+
+```
+RS = 0
+R/W = 0
+E: HIGH  LOW
+```
+
+---
+
+## Read Cycle (Optional)
+
+Reads are uncommon in hobby systems.
+
+```
+RS = 0/1
+R/W = 1
+E: HIGH
+```
+
+Emulator may simplify:
+
+* Ignore reads entirely
+* Or return busy flag + address counter
+
+---
+
+## Busy Flag Emulation
+
+### Real Hardware
+
+* Busy flag = D7
+* Commands take 37-1520 µs
+
+### Emulator Options
+
+| Mode       | Behavior          |
+| ---------- | ----------------- |
+| Simplified | Always ready      |
+| Timed      | Busy for N cycles |
+
+Recommended default: **Always ready**
+
+---
+
+## Power-Up State
+
+On reset:
+
+* Display OFF
+* Cursor OFF
+* DDRAM cleared or undefined
+* Address counter = 0
+
+Emulator should:
+
+* Clear DDRAM
+* Set cursor to (0,0)
+* Display enabled
+
+---
+
+## Cursor and Display Model
+
+State variables:
+
+```text
+cursor_row
+cursor_col
+display_on
+cursor_on
+blink_on
+```
+
+Cursor moves automatically after writes based on entry mode.
+
+---
+
+## 4-bit vs 8-bit Interface
+
+### 8-bit Mode
+
+* Full byte transferred on D0-D7
+
+### 4-bit Mode
+
+* High nibble sent first
+* Two enable pulses per byte
+
+Emulator simplification:
+
+* Accept full byte writes
+* Ignore nibble timing
+
+---
+
+## Rendering Model (Emulator UI)
+
+Recommended approach:
+
+* Maintain 16x2 character buffer
+* Render ASCII subset
+* Substitute unsupported glyphs
+* Optionally render custom CGRAM chars
+
+---
+
+## Emulator API Model
+
+```c
+typedef struct {
+    uint8_t ddram[80];
+    uint8_t cgram[64];
+    uint8_t addr;
+    bool display_on;
+    bool cursor_on;
+    bool blink_on;
+    uint8_t entry_mode;
+} FIT0127_LCD;
+```
+
+---
+
+## Common Wiring in 6502 Systems
+
+```
+VIA Port  LCD D4-D7 (4-bit mode)
+RS  VIA bit
+E   VIA bit
+R/W  GND
+```
+
+---
+
+## Testing Checklist
+
+* Clear display command
+* Cursor positioning via DDRAM addresses
+* Sequential character writes
+* Line wrap behavior
+* Custom character display
+
+---
+
+## References
+
+* [HD44780U Datasheet (Hitachi)](https://academy.cba.mit.edu/classes/output_devices/44780.pdf)
+* [Ben Eater LCD Interface Notes](https://hackaday.io/project/174128-db6502/log/181838-adventures-with-hd44780-lcd-controller)
+* [Ben Eater's 6502 Computer](https://github.com/tedkotz/be6502)
+* [Build a 6502 Computer](https://eater.net/6502)
+
+---
+
+## Notes
+
+This spec intentionally prioritizes **firmware-visible behavior** over electrical accuracy, making it ideal for:
+
+* SBC emulators
+* ROM and monitor development
+* Automated testing of LCD output
+* Educational CPU projects

package/skills/legacy-circuit-mockups/references/lcd.md

@@ -0,0 +1,208 @@
+# DFRobot FIT0127 LCD Character Display Specification
+
+## 1. Overview
+
+The **DFRobot FIT0127** is a family of **HD44780-compatible character LCD modules** commonly used in embedded systems and hobbyist projects. These displays provide alphanumeric output using a dot-matrix character generator and support both 8-bit and 4-bit parallel interfaces.
+
+FIT0127 modules are frequently paired with microcontrollers and 8-bit CPUs such as the **6502**, **AVR**, **PIC**, and **Arduino** platforms.
+
+---
+
+## 2. General Characteristics
+
+| Feature           | Description                                         |
+| ----------------- | --------------------------------------------------- |
+| Display type      | Character LCD (STN, Yellow-Green backlight typical) |
+| Controller        | HD44780 or compatible                               |
+| Interface         | Parallel (4-bit or 8-bit)                           |
+| Character size    | 5 x 8 dot matrix                                    |
+| Operating voltage | 5 V logic (some variants support 3.3 V)             |
+| Backlight         | LED (separate power pins)                           |
+| Viewing mode      | Transflective                                       |
+
+---
+
+## 3. Display Variants
+
+The FIT0127 designation is commonly associated with **16x2 character LCD modules**.
+
+| Variant | Characters          |
+| ------- | ------------------- |
+| FIT0127 | 16 columns x 2 rows |
+
+---
+
+## 4. Pin Configuration
+
+### 4.1 Pinout (Standard 16-pin Header)
+
+| Pin | Name | Description           |
+| --: | ---- | --------------------- |
+|   1 | VSS  | Ground                |
+|   2 | VDD  | +5 V supply           |
+|   3 | VO   | Contrast adjust       |
+|   4 | RS   | Register Select       |
+|   5 | R/W  | Read/Write select     |
+|   6 | E    | Enable                |
+|   7 | D0   | Data bit 0            |
+|   8 | D1   | Data bit 1            |
+|   9 | D2   | Data bit 2            |
+|  10 | D3   | Data bit 3            |
+|  11 | D4   | Data bit 4            |
+|  12 | D5   | Data bit 5            |
+|  13 | D6   | Data bit 6            |
+|  14 | D7   | Data bit 7            |
+|  15 | A    | Backlight Anode (+)   |
+|  16 | K    | Backlight Cathode (-) |
+
+---
+
+## 5. Electrical Characteristics (Typical)
+
+| Parameter           | Value       |
+| ------------------- | ----------- |
+| Logic voltage (VDD) | 4.5 - 5.5 V |
+| Logic current       | ~1-2 mA     |
+| Backlight voltage   | ~4.2 V      |
+| Backlight current   | 15-30 mA    |
+
+---
+
+## 6. Interface Signals
+
+### 6.1 RS (Register Select)
+
+| RS | Function             |
+| -- | -------------------- |
+| 0  | Instruction register |
+| 1  | Data register        |
+
+### 6.2 R/W
+
+| R/W | Operation     |
+| --- | ------------- |
+| 0   | Write to LCD  |
+| 1   | Read from LCD |
+
+### 6.3 Enable (E)
+
+* Data is latched on the **falling edge** of E
+* E must be pulsed HIGH  LOW for each transfer
+
+---
+
+## 7. Data Bus Operation
+
+### 7.1 8-bit Mode
+
+* Uses D0-D7
+* Faster operation
+
+### 7.2 4-bit Mode
+
+* Uses D4-D7 only
+* Data transferred in two nibbles (high first)
+* Saves I/O pins
+
+---
+
+## 8. Internal Memory Map
+
+### 8.1 DDRAM (Display Data RAM)
+
+|   Address | Display Position |
+| --------: | ---------------- |
+| 0x00-0x0F | Line 1, Col 1-16 |
+| 0x40-0x4F | Line 2, Col 1-16 |
+
+### 8.2 CGRAM (Character Generator RAM)
+
+* Supports up to **8 custom characters**
+* Each character uses 8 bytes
+
+---
+
+## 9. Instruction Set (Summary)
+
+| Instruction | Description            |
+| ----------- | ---------------------- |
+| 0x01        | Clear display          |
+| 0x02        | Return home            |
+| 0x04-0x07   | Entry mode set         |
+| 0x08-0x0F   | Display on/off control |
+| 0x10-0x1F   | Cursor/display shift   |
+| 0x20-0x3F   | Function set           |
+| 0x40-0x7F   | Set CGRAM address      |
+| 0x80-0xFF   | Set DDRAM address      |
+
+---
+
+## 10. Initialization Sequence (4-bit Mode)
+
+```text
+Wait >15 ms after VDD rises
+Function set: 0x33
+Function set: 0x32
+Function set: 0x28 (4-bit, 2-line)
+Display ON/OFF: 0x0C
+Entry mode: 0x06
+Clear display: 0x01
+```
+
+---
+
+## 11. Timing Characteristics (Typical)
+
+| Operation          | Time     |
+| ------------------ | -------- |
+| Enable pulse width | ≥ 450 ns |
+| Command execution  | ~37 µs   |
+| Clear / Home       | ~1.52 ms |
+
+---
+
+## 12. Typical System Integration (6502 Example)
+
+```text
+RS   VIA output
+E    VIA output
+D4-D7  VIA Port B
+R/W  Grounded (write-only)
+```
+
+---
+
+## 13. Contrast and Backlight Control
+
+* Contrast adjusted via potentiometer on VO pin
+* Backlight may require series resistor
+* PWM dimming supported via external control
+
+---
+
+## 14. Absolute Maximum Ratings (Summary)
+
+| Parameter      | Rating                |
+| -------------- | --------------------- |
+| VDD            | -0.3 V to +6.0 V      |
+| Input voltage  | -0.3 V to VDD + 0.3 V |
+| Operating temp | -20 °C to +70 °C      |
+
+---
+
+## 15. Common Use Cases
+
+* Status displays
+* Debug output for SBCs
+* User interfaces for embedded systems
+* Retrocomputer front panels
+
+---
+
+## 16. References
+
+* <https://static6.arrow.com/aropdfconversion/1f68489996f057bb6611f71d5fdb5f60f44faa72/pgurl_58439499065092.pdf>
+* <https://cdn.sparkfun.com/assets/9/5/f/7/b/HD44780.pdf>
+* <https://predictabledesigns.com/introduction-embedded-electronic-displays/>
+
+---