SINTRAN HDLC Implementation Documentation¶

Complete documentation for understanding and implementing the SINTRAN III HDLC (High-Level Data Link Control) subsystem.

🎯 Quick Start - Choose Your Path¶

👋 I'm New to SINTRAN HDLC¶

Start here if: You want to understand the basics before diving into details.

📚 Your Path: 1. Getting Started - System overview and architecture 2. Understanding Packets - How HDLC packets work 3. Hardware Overview - COM5025, X.21, DMA 4. Software Flow - SINTRAN HDLC software structure

🎮 I Need to Build an Emulator¶

Start here if: You're implementing a SINTRAN HDLC emulator in C# or another language.

🔧 Your Path: 1. Getting Started - Quick orientation 2. Register Reference - Complete register specs 3. DMA Reference - DMA descriptor details 4. Emulator Implementation Guide - Build it step-by-step 5. Testing Scenarios - Test your implementation 6. Debugging Guide - Troubleshoot issues

🛠️ I'm Writing a Program That Uses HDLC¶

Start here if: You want to send/receive HDLC frames from your own SINTRAN program (and run it under nd100x).

⚙️ Your Path: 1. HDLC Raw Programming Guide - MON 201B API, DCB layout, send/receive flow 2. Buffer-Pool and Emulator Usage - CHANGE-BUFFER-SIZE setup, pool sizing, the receive-arm trap, running under nd100x 3. MAC Cookbook - writing the MAC program itself (source encoding, monitor-call ABI, file I/O)

🔍 I'm Debugging an Existing System¶

Start here if: Something isn't working and you need to figure out why.

⚡ Your Path: 1. Quick Reference Card - Critical constants and patterns 2. Debugging Guide - Troubleshooting strategies 3. Register Reference - Verify bit definitions 4. Interrupt Reference - Check interrupt logic 5. HDLC-ALL.md - Search for specific topics

🔬 I Need Deep Technical Understanding¶

Start here if: You want to understand every detail and breakthrough discovery.

📖 Your Path: 1. Read all Learning Documents - Build foundation 2. Read all Reference Documents - Complete specifications 3. Read all Deep Dives - Advanced discoveries 4. Read Complete Pseudocode - Source code level 5. Explore HDLC-ALL.md - Everything in one place

📚 Documentation Structure¶

Learning Track (Start Here for Newcomers)¶

Progressive introduction to SINTRAN HDLC

Document	Description	Lines
01-Getting-Started.md	System architecture and component overview	217
02-Understanding-Packets.md	HDLC packet structure and lifecycle	95
03-Hardware-Overview.md	COM5025, X.21 interface, IOX bus	328
04-Software-Flow.md	SINTRAN software organization	32

Technical Reference (Complete Specifications)¶

Detailed technical reference material

Document	Description	Lines
Register-Reference.md	Complete register map and bit definitions	495
DMA-Reference.md	DMA descriptors, LKEY field, operations	86
Interrupt-Reference.md	HIINT/HOINT analysis, WRTC/WTTC control	212
Protocol-Reference.md	LAPB, X.25, X.21, PAD protocols	200

Implementation Guides (Practical)¶

Step-by-step implementation guidance

Document	Description	Lines
Emulator-Implementation-Guide.md	Complete emulator development guide	253
Buffer-Pool-and-Emulator-Usage.md	Buffer setup (`CHANGE-BUFFER-SIZE`), pool sizing, receive-arm tuning, running HDLC apps under nd100x	272
Testing-Scenarios.md	Comprehensive test cases	32
Debugging-Guide.md	Troubleshooting and debugging strategies	39

Deep Dives (Advanced Topics)¶

In-depth analysis of breakthrough discoveries

Document	Description	Lines
Deep-Dive-COM5025-Interface.md	LKEY field breakthrough discovery	278
Deep-Dive-Interrupt-Control.md	WRTC/WTTC interrupt enable analysis	217
Deep-Dive-XSSDATA.md	Complete transmitter analysis	1161
Deep-Dive-PROCPKT.md	Complete receiver packet processing	291

Appendices (Reference Data)¶

Complete pseudocode, constants, traces, history

Document	Description	Lines
Appendix-A-Pseudocode.md	Complete SINTRAN HDLC pseudocode	268
Appendix-B-Constants-Variables.md	All constants, variables, memory map	44
Appendix-C-Packet-Traces.md	Real packet trace analysis	41
Appendix-D-Bug-History.md	Bug discoveries and corrections	84

Special Documents¶

Comprehensive reference and quick lookup

Document	Description	Size
HDLC-ALL.md	Master reference - All content aggregated for searching	23,358 lines
Quick-Reference-Card.md	Cheat sheet with critical info	272 lines
HDLC-Raw-Programming-Guide.md (PDF)	Sending and receiving raw data over HDLC without XMSG: the MON 201B (HDLCfunction) API, DCB layout, send/receive flow	2386 lines
HDLC-Frame-Format-Reference.md	Wire-level decoding reference: the bit-stuffed flag layer, LAPB address/control/FCS framing, and COM5025/DMA/DCB handling	625 lines
ND-100 Pico PCB-Interface Reference.md	Design reference for an RS-422 interface board between the ND-100/110 HDLC card and a Raspberry Pi Pico W	297 lines
WireShark/	`hdlc_tcp.lua` - Wireshark/tshark dissector for SINTRAN III traffic on the `nd100x --hdlc` TCP bridge and the COSMOS Ethernet hub	2 files
archive/	The analysis files this documentation was built from, kept for history	57 files

The old consolidated 01-HDLC-Hardware-Reference.md and the two REORGANIZATION-*.md notes that this table used to list were deleted; the hardware reference now lives in learning/03-Hardware-Overview.md.

🔑 Key Concepts at a Glance¶

What is SINTRAN HDLC?¶

SINTRAN III's implementation of the HDLC protocol for synchronous serial communication over X.21 interfaces. It provides reliable, frame-based data transmission for terminal connections and network communications.

Core Components¶

COM5025 Chip: Multi-protocol communications controller handling HDLC framing
X.21 Interface: Physical layer for synchronous serial communication
DMA Controller: Hardware-based buffer management for efficient data transfer
SINTRAN Software: Interrupt handlers, buffer management, protocol implementation

Critical Discoveries¶

LKEY Field Structure: DMA descriptor bits 7-0 contain actual COM5025 register values
WRTC/WTTC Control: Specific values (1734₈, 1134₈) enable comprehensive interrupt generation
Success Test: Transmission success = (RTTS & 0x8002) == 0 (SILFO+TXUND both clear)
ACTSW Gate: Activity switch controls all interrupt processing

📖 Key Terminology¶

Term	Description
HDLC	High-Level Data Link Control - bit-oriented protocol
LAPB	Link Access Procedure Balanced - HDLC implementation for X.25
X.25	Packet switching protocol built on LAPB
X.21	Physical interface standard for synchronous serial communication
COM5025	SMC/AMD multi-protocol communications controller chip
DMA	Direct Memory Access - hardware-based data transfer
LKEY	DMA descriptor control word containing block status and COM5025 bits
RRTS	Read Receiver Transfer Status - primary receiver status register
RTTS	Read Transmitter Transfer Status - primary transmitter status register
WRTC	Write Receiver Transfer Control - receiver interrupt enable
WTTC	Write Transmitter Transfer Control - transmitter interrupt enable
HIINT	Receiver interrupt handler (Hardware Input INTerrupt)
HOINT	Transmitter interrupt handler (Hardware Output INTerrupt)
ACTSW	Activity Switch - master control for device active state
HASTAT	Hardware STATus - variable storing RRTS/RTTS values
FSERM	Frame Start/End Marker - DMA key for single-block frames (002003₈)
SILFO	Serial Illegal FOrmat - transmitter error bit (bit 15)
TXUND	Transmitter UNDeRrun - transmitter error bit (bit 1)
IOX	Input/Output eXtension - register addressing system

🎓 Learning Resources¶

For Visual Learners¶

All documents include Mermaid diagrams following MERMAID_COLOR_STANDARDS.md: - System architecture diagrams - Data flow charts - State machines - Protocol stack visualizations

For Code-Focused Developers¶

Complete pseudocode and C# implementation examples throughout: - Appendix A: Complete Pseudocode - Emulator Implementation Guide - Code snippets in all technical documents

📊 Document Statistics¶

Measured 2026-09-18.

Total Documentation: 20 focused documents + HDLC-ALL master reference + the 4 standalone references under "Special Documents" (87 tracked files in the folder, 57 of them in archive/)
Learning Documents: 4 files (672 lines)
Reference Documents: 4 files (993 lines)
Implementation Guides: 4 files (596 lines)
Deep Dives: 4 files (1,947 lines)
Appendices: 4 files (437 lines)
Master Reference: HDLC-ALL.md (23,358 lines, 0.83 MB)

🔄 Document Updates¶

This documentation was reorganized from comprehensive analysis files to provide: - ✅ Clear entry points for different audiences - ✅ Progressive disclosure (simple → complex) - ✅ Practical implementation guidance - ✅ Complete technical reference - ✅ Preserved historical analysis

Last Major Reorganization: 2025-10-17 (the date the structured folders were first committed)
Source Material: 59 analysis files consolidated into structured documentation
Added since: the raw programming guide, the frame format reference, the Pico interface board reference, the Wireshark dissector, and implementation/Buffer-Pool-and-Emulator-Usage.md (2026-09-18)

🤝 Contributing & Maintenance¶

Updating Documentation¶

When updating this documentation: 1. Maintain consistency across related documents 2. Update cross-references when moving content 3. Follow Mermaid color standards for diagrams 4. Keep HDLC-ALL.md synchronized with detailed docs 5. Update this README when adding new documents

Document Standards¶

Clear purpose statement at document start
Table of contents for documents >200 lines
"See Also" sections for related documents
Code examples with proper syntax highlighting
Mermaid diagrams following project standards

📞 Need Help?¶

Start Here¶

Not sure where to begin? → Read Getting Started
Looking for something specific? → Search HDLC-ALL.md
Need quick lookup? → Check Quick Reference Card
Having problems? → Read Debugging Guide

Document Map¶

📁 SINTRAN/Devices/HDLC/
├── 📖 README.md ← You are here
├── ⚡ Quick-Reference-Card.md
├── 🛠️ HDLC-Raw-Programming-Guide.md (+ .pdf) (MON 201B from your own program)
├── 📐 HDLC-Frame-Format-Reference.md (wire-level decoding)
├── 🔌 ND-100 Pico PCB-Interface Reference.md (RS-422 interface board)
├── 📚 learning/ (4 docs - start here if new)
├── 📋 reference/ (4 docs - technical specs)
├── 🎮 implementation/ (4 docs - build, run & debug)
├── 🔬 deep-dives/ (4 docs - advanced topics)
├── 📝 appendices/ (4 docs - reference data)
├── 🦈 WireShark/ (hdlc_tcp.lua dissector)
├── 🗄️ archive/ (source analysis files, history only)
└── 📚 HDLC-ALL.md (master reference - 23K lines)

Ready to start? Pick your path above and dive in! 🚀