devskill 2.0.7 → 2.0.8

package/skills/legacy-circuit-mockups/references/7400-series.md

@@ -0,0 +1,177 @@
+# 7400-Series Logic ICs Specification
+
+## 1. Overview
+
+The **7400-series** is a large family of **digital logic integrated circuits** originally implemented in **TTL (Transistor-Transistor Logic)** and later expanded to include **CMOS-compatible variants**. These devices provide fundamental building blocks such as gates, flip-flops, counters, multiplexers, decoders, and bus transceivers.
+
+7400-series ICs are widely used in **retrocomputing**, **6502/Z80 systems**, **glue logic**, and educational designs.
+
+---
+
+## 2. Logic Families
+
+| Family  | Technology              | Notes                   |
+| ------- | ----------------------- | ----------------------- |
+| 74xx    | TTL                     | Original bipolar TTL    |
+| 74LSxx  | Low-power Schottky TTL  | Faster, lower power     |
+| 74HCTxx | CMOS (TTL-level inputs) | Ideal for mixed systems |
+| 74HCxx  | CMOS                    | Wide voltage range      |
+| 74ACTxx | Advanced CMOS TTL-level | Very fast               |
+
+---
+
+## 3. Electrical Characteristics (Typical)
+
+| Parameter         | TTL     | CMOS                |
+| ----------------- | ------- | ------------------- |
+| VCC               | 5 V     | 2-6 V (5 V typical) |
+| Input HIGH        | ≥ 2.0 V | ≥ 0.7xVCC           |
+| Input LOW         | ≤ 0.8 V | ≤ 0.3xVCC           |
+| Fan-out           | ~10     | Very high           |
+| Power consumption | Higher  | Lower               |
+
+---
+
+## 4. Standard Package Types
+
+| Package | Pins       | Notes               |
+| ------- | ---------- | ------------------- |
+| DIP     | 14, 16, 20 | Breadboard-friendly |
+| SOIC    | 14, 16, 20 | Surface-mount       |
+| TSSOP   | 14, 16     | Compact SMT         |
+
+---
+
+## 5. Common Logic Categories
+
+### 5.1 Basic Logic Gates
+
+| IC   | Function          |
+| ---- | ----------------- |
+| 7400 | Quad 2-input NAND |
+| 7402 | Quad 2-input NOR  |
+| 7404 | Hex inverter      |
+| 7408 | Quad 2-input AND  |
+| 7432 | Quad 2-input OR   |
+| 7486 | Quad 2-input XOR  |
+
+---
+
+### 5.2 Latches and Flip-Flops
+
+| IC    | Function              |
+| ----- | --------------------- |
+| 7474  | Dual D-type flip-flop |
+| 7473  | Dual JK flip-flop     |
+| 7475  | Quad latch            |
+| 74175 | Quad D-type FF        |
+
+---
+
+### 5.3 Counters and Registers
+
+| IC    | Function                              |
+| ----- | ------------------------------------- |
+| 74161 | Synchronous 4-bit counter             |
+| 74163 | Synchronous binary counter            |
+| 74193 | Up/down counter                       |
+| 74164 | Serial-in/parallel-out shift register |
+| 74165 | Parallel-in/serial-out shift register |
+
+---
+
+### 5.4 Decoders and Multiplexers
+
+| IC    | Function                |
+| ----- | ----------------------- |
+| 74138 | 3-to-8 decoder          |
+| 74139 | Dual 2-to-4 decoder     |
+| 74151 | 8-to-1 multiplexer      |
+| 74157 | Quad 2-to-1 multiplexer |
+
+---
+
+### 5.5 Bus Interface and Glue Logic
+
+| IC    | Function                            |
+| ----- | ----------------------------------- |
+| 74244 | Octal buffer / line driver          |
+| 74245 | Octal bidirectional bus transceiver |
+| 74373 | Octal transparent latch             |
+| 74574 | Octal D-type FF                     |
+
+---
+
+## 6. Pin Numbering Convention
+
+* DIP packages use **counter-clockwise numbering**
+* Pin 1 identified by notch or dot
+
+```text
+       ________
+  1 °|       |° 14
+  2 °|        |° 13
+  3 °|        |° 12
+  4 °|        |° 11
+  5 °|        |° 10
+  6 °|        |°  9
+  7 °|________|°  8
+```
+
+---
+
+## 7. Power and Ground Pins
+
+| Package | VCC | GND |
+| ------- | --- | --- |
+| DIP-14  | 14  | 7   |
+| DIP-16  | 16  | 8   |
+| DIP-20  | 20  | 10  |
+
+---
+
+## 8. Timing Characteristics (General)
+
+| Parameter         | TTL     | CMOS     |
+| ----------------- | ------- | -------- |
+| Propagation delay | 5-15 ns | 8-25 ns  |
+| Max frequency     | ~25 MHz | ~50+ MHz |
+
+---
+
+## 9. Interfacing Notes
+
+* TTL outputs reliably drive TTL inputs
+* CMOS inputs must not float
+* Use **74HCT** when interfacing CMOS with TTL signals
+* Decoupling capacitors (0.1 µF) required per IC
+
+---
+
+## 10. Typical Retrocomputer Applications
+
+* Address decoding
+* Chip-select generation
+* Bus buffering
+* Clock gating and control
+* State machines
+
+---
+
+## 11. Absolute Maximum Ratings (Summary)
+
+| Parameter           | Rating                |
+| ------------------- | --------------------- |
+| VCC                 | -0.5 V to +7.0 V      |
+| Input voltage       | -0.5 V to VCC + 0.5 V |
+| Storage temperature | -65 °C to +150 °C     |
+
+---
+
+## 12. References
+
+* <https://www.ti.com/lit/ds/symlink/sn74ls00.pdf>
+* <https://archive.org/details/TTLCookBook>
+* <https://digilent.com/reference/test-and-measurement/analog-discovery-2/hardware-design-guide>
+
+---

package/skills/legacy-circuit-mockups/references/assembly-compiler.md

@@ -0,0 +1,258 @@
+# 6502 SBC Assembly Compilation & ROM Build Specification
+
+## Overview
+
+This document defines a **complete specification for compiling 6502 assembly language** for a single-board computer consisting of:
+
+* **MOS 6502 CPU**
+* **MOS 6522 VIA**
+* **AS6C62256 (32 KB SRAM)**
+* **AT28C256 (32 KB EEPROM / ROM)**
+* **DFRobot FIT0127 (HD44780-compatible 16x2 LCD)**
+
+The focus is on **toolchain behavior, memory layout, ROM construction, and firmware conventions**, not electrical wiring.
+
+---
+
+## Target System Architecture
+
+### Memory Map (Canonical)
+
+```
+$0000-$00FF  Zero Page (RAM)
+$0100-$01FF  Stack (RAM)
+$0200-$7FFF  General RAM (AS6C62256)
+$8000-$8FFF  6522 VIA I/O space
+$9000-$FFFF  ROM (AT28C256)
+```
+
+> Address decoding may mirror devices; assembler assumes this canonical layout.
+
+---
+
+## ROM Organization (AT28C256)
+
+| Address     | Purpose              |
+| ----------- | -------------------- |
+| $9000-$FFEF | Program code + data  |
+| $FFF0-$FFF9 | Optional system data |
+| $FFFA-$FFFB | NMI vector           |
+| $FFFC-$FFFD | RESET vector         |
+| $FFFE-$FFFF | IRQ/BRK vector       |
+
+ROM image size: **32,768 bytes**
+
+---
+
+## Reset & Startup Convention
+
+On reset:
+
+1. CPU fetches RESET vector at `$FFFC`
+2. Code initializes stack pointer
+3. Zero-page variables initialized
+4. VIA configured
+5. LCD initialized
+6. Main program entered
+
+---
+
+## Assembler Requirements
+
+Assembler **MUST** support:
+
+* `.org` absolute addressing
+* Symbolic labels
+* Binary output (`.bin`)
+* Little-endian word emission
+* Zero-page optimization
+
+Recommended assemblers:
+
+* **ca65** (cc65 toolchain)
+* **vasm6502**
+* **64tass**
+
+---
+
+## Assembly Source Structure
+
+```asm
+;---------------------------
+; Reset Vector Entry Point
+;---------------------------
+        .org $9000
+RESET:
+        sei
+        cld
+        ldx #$FF
+        txs
+        jsr init_via
+        jsr init_lcd
+MAIN:
+        jsr lcd_print
+        jmp MAIN
+```
+
+---
+
+## Vector Table Definition
+
+```asm
+        .org $FFFA
+        .word nmi_handler
+        .word RESET
+        .word irq_handler
+```
+
+---
+
+## 6522 VIA Programming Model
+
+### Register Map (Base = $8000)
+
+| Offset | Register |
+| ------ | -------- |
+| $0     | ORB      |
+| $1     | ORA      |
+| $2     | DDRB     |
+| $3     | DDRA     |
+| $4     | T1CL     |
+| $5     | T1CH     |
+| $6     | T1LL     |
+| $7     | T1LH     |
+| $8     | T2CL     |
+| $9     | T2CH     |
+| $B     | ACR      |
+| $C     | PCR      |
+| $D     | IFR      |
+| $E     | IER      |
+
+---
+
+## LCD Interface Convention
+
+### LCD Wiring Assumption
+
+| LCD   | VIA     |
+| ----- | ------- |
+| D4-D7 | PB4-PB7 |
+| RS    | PA0     |
+| E     | PA1     |
+| R/W   | GND     |
+
+4-bit mode assumed.
+
+---
+
+## LCD Initialization Sequence
+
+```asm
+lcd_init:
+        lda #$33
+        jsr lcd_cmd
+        lda #$32
+        jsr lcd_cmd
+        lda #$28
+        jsr lcd_cmd
+        lda #$0C
+        jsr lcd_cmd
+        lda #$06
+        jsr lcd_cmd
+        lda #$01
+        jsr lcd_cmd
+        rts
+```
+
+---
+
+## LCD Command/Data Interface
+
+| Operation | RS | Data            |
+| --------- | -- | --------------- |
+| Command   | 0  | Instruction     |
+| Data      | 1  | ASCII character |
+
+---
+
+## Zero Page Usage Convention
+
+| Address | Purpose      |
+| ------- | ------------ |
+| $00-$0F | Scratch      |
+| $10-$1F | LCD routines |
+| $20-$2F | VIA state    |
+| $30-$FF | User-defined |
+
+---
+
+## RAM Usage (AS6C62256)
+
+* Stack uses page `$01`
+* All RAM assumed volatile
+* No ROM shadowing
+
+---
+
+## Build Pipeline
+
+### Step 1: Assemble
+
+```bash
+ca65 main.asm -o main.o
+```
+
+### Step 2: Link
+
+```bash
+ld65 -C rom.cfg main.o -o rom.bin
+```
+
+### Step 3: Pad ROM
+
+Ensure `rom.bin` is exactly **32768 bytes**.
+
+---
+
+## EEPROM Programming
+
+* Target device: **AT28C256**
+* Programmer: **MiniPro / T48**
+* Verify after write
+
+---
+
+## Emulator Expectations
+
+Emulator must:
+
+* Load ROM at `$9000-$FFFF`
+* Emulate VIA I/O side effects
+* Render LCD output
+* Honor RESET vector
+
+---
+
+## Testing Checklist
+
+* Reset vector execution
+* VIA register writes
+* LCD displays correct text
+* Stack operations valid
+* ROM image maps correctly
+
+---
+
+## References
+
+* [MOS 6502 Programming Manual](http://archive.6502.org/datasheets/synertek_programming_manual.pdf)
+* [MOS 6522 VIA Datasheet](http://archive.6502.org/datasheets/mos_6522_preliminary_nov_1977.pdf)
+* [AT28C256 Datasheet](https://ww1.microchip.com/downloads/aemDocuments/documents/MPD/ProductDocuments/DataSheets/AT28C256-Industrial-Grade-256-Kbit-Paged-Parallel-EEPROM-Data-Sheet-DS20006386.pdf)
+* [HD44780 LCD Datasheet](https://www.futurlec.com/LED/LCD16X2BLa.shtml)
+* [cc65 Toolchain Docs](https://cc65.github.io/doc/cc65.html)
+
+---
+
+## Notes
+
+This specification is intentionally **end-to-end**: from assembly source to EEPROM image to running hardware or emulator. It defines a stable contract so ROMs, emulators, and real SBCs behave identically.

package/skills/legacy-circuit-mockups/references/assembly-language.md

@@ -0,0 +1,226 @@
+# 6502 Assembly Language with AT28C256 EEPROM
+
+A practical specification for writing **6502/65C02 assembly language programs** intended to be stored in and executed from an **AT28C256 (32 KB) parallel EEPROM** in single-board computers (SBCs) and retro systems.
+
+---
+
+## 1. Scope and Assumptions
+
+This document assumes:
+
+* A **6502-family CPU** (6502, 65C02, or compatible)
+* Program code stored in an **AT28C256 (32K x 8) EEPROM**
+* Memory-mapped I/O (e.g., 6522 VIA)
+* Reset and interrupt vectors located in EEPROM
+* External RAM mapped elsewhere (e.g., 62256 SRAM)
+
+---
+
+## 2. AT28C256 EEPROM Overview
+
+| Parameter      | Value               |
+| -------------- | ------------------- |
+| Capacity       | 32 KB (32768 bytes) |
+| Address Lines  | A0-A14              |
+| Data Lines     | D0-D7               |
+| Access Time    | ~150 ns             |
+| Supply Voltage | 5 V                 |
+| Package        | DIP-28 / PLCC       |
+
+### Typical Memory Map Usage
+
+| Address Range | Usage                   |
+| ------------- | ----------------------- |
+| `$8000-$FFFF` | EEPROM (code + vectors) |
+| `$FFFA-$FFFF` | Interrupt vectors       |
+
+---
+
+## 3. 6502 Memory Map Example
+
+```
+$0000-$00FF  Zero Page (RAM)
+$0100-$01FF  Stack
+$0200-$7FFF  RAM / I/O
+$8000-$FFFF  AT28C256 EEPROM
+```
+
+---
+
+## 4. Reset and Interrupt Vectors
+
+The 6502 reads vectors from the **top of memory**:
+
+| Vector  | Address       | Description            |
+| ------- | ------------- | ---------------------- |
+| NMI     | `$FFFA-$FFFB` | Non-maskable interrupt |
+| RESET   | `$FFFC-$FFFD` | Reset entry point      |
+| IRQ/BRK | `$FFFE-$FFFF` | Maskable interrupt     |
+
+### Vector Definition Example
+
+```asm
+        .org $FFFA
+        .word nmi_handler
+        .word reset
+        .word irq_handler
+```
+
+---
+
+## 5. Assembly Program Structure
+
+### Typical Layout
+
+```asm
+        .org $8000
+
+reset:
+        sei             ; Disable IRQs
+        cld             ; Clear decimal mode
+        ldx #$FF
+        txs             ; Initialize stack
+
+main:
+        jmp main
+```
+
+---
+
+## 6. Essential 6502 Instructions
+
+### Registers
+
+| Register | Purpose          |
+| -------- | ---------------- |
+| A        | Accumulator      |
+| X, Y     | Index registers  |
+| SP       | Stack pointer    |
+| PC       | Program counter  |
+| P        | Processor status |
+
+### Common Instructions
+
+| Instruction | Function               |
+| ----------- | ---------------------- |
+| LDA/STA     | Load/store accumulator |
+| LDX/LDY     | Load index registers   |
+| JMP/JSR     | Jump / subroutine      |
+| RTS         | Return from subroutine |
+| BEQ/BNE     | Conditional branch     |
+| SEI/CLI     | Disable/enable IRQ     |
+
+---
+
+## 7. Addressing Modes (Common)
+
+| Mode      | Example       | Notes        |
+| --------- | ------------- | ------------ |
+| Immediate | `LDA #$01`    | Constant     |
+| Zero Page | `LDA $00`     | Fast         |
+| Absolute  | `LDA $8000`   | Full address |
+| Indexed   | `LDA $2000,X` | Tables       |
+| Indirect  | `JMP ($FFFC)` | Vectors      |
+
+---
+
+## 8. Writing Code for EEPROM Execution
+
+### Key Considerations
+
+* Code is **read-only at runtime**
+* Self-modifying code not recommended
+* Place jump tables and constants in EEPROM
+* Use RAM for variables and stack
+
+### Zero Page Variable Example
+
+```asm
+counter = $00
+
+        lda #$00
+        sta counter
+```
+
+---
+
+## 9. Timing and Performance
+
+* EEPROM access time must meet CPU clock requirements
+* AT28C256 supports ~1 MHz comfortably
+* Faster clocks may require wait states or ROM shadowing
+
+---
+
+## 10. Example: Simple LED Toggle (Memory-Mapped I/O)
+
+```asm
+PORTB = $6000
+DDRB  = $6002
+
+        .org $8000
+reset:
+        sei
+        ldx #$FF
+        txs
+
+        lda #$FF
+        sta DDRB
+
+loop:
+        lda #$FF
+        sta PORTB
+        jsr delay
+        lda #$00
+        sta PORTB
+        jsr delay
+        jmp loop
+```
+
+---
+
+## 11. Assembling and Programming Workflow
+
+1. Write source (`.asm`)
+2. Assemble to binary
+3. Pad or relocate to `$8000`
+4. Program AT28C256 via T48 / minipro
+5. Insert EEPROM and reset CPU
+
+---
+
+## 12. Assembler Directives (Common)
+
+| Directive  | Purpose                     |
+| ---------- | --------------------------- |
+| `.org`     | Set program origin          |
+| `.byte`    | Define byte                 |
+| `.word`    | Define word (little-endian) |
+| `.include` | Include file                |
+| `.equ`     | Constant definition         |
+
+---
+
+## 13. Common Mistakes
+
+| Issue                      | Result             |
+| -------------------------- | ------------------ |
+| Missing vectors            | CPU hangs on reset |
+| Wrong `.org`               | Code not executed  |
+| Using RAM addresses in ROM | Crash              |
+| Stack not initialized      | Undefined behavior |
+
+---
+
+## 14. Reference Links
+
+* [https://www.masswerk.at/6502/6502_instruction_set.html](https://www.masswerk.at/6502/6502_instruction_set.html)
+* [https://www.nesdev.org/wiki/6502](https://www.nesdev.org/wiki/6502)
+* [https://www.westerndesigncenter.com/wdc/documentation](https://www.westerndesigncenter.com/wdc/documentation)
+* [https://en.wikipedia.org/wiki/MOS_Technology_6502](https://en.wikipedia.org/wiki/MOS_Technology_6502)
+
+---
+
+**Document Scope:** 6502 assembly stored in AT28C256 EEPROM
+**Audience:** Retrocomputing, SBC designers, embedded hobbyists
+**Status:** Stable reference