███████╗██╗ ██████╗
 ██╔════╝██║██╔════╝
 ███████╗██║██║
 ╚════██║██║██║
 ███████║██║╚██████╗
 ╚══════╝╚═╝ ╚═════╝
  ASSEMBLER  API

• What is SIC?
• Why This Project?
• Features at a Glance
• Architecture
• Quick Start
• API Reference
  • Request Modes
  • Response Schema
  • Error Handling
• Object Code & Records
• Instruction Formats
• Pseudo-Instructions
• Supported Registers
• cURL Examples
• End-to-End Walkthrough
• Limitations & Roadmap
• Contributing

The Simplified Instructional Computer (SIC) is a hypothetical machine architecture defined in System Software by Leland Beck. It exists purely for education — a clean, minimal ISA that strips away the complexity of real-world architectures so students can focus on the concepts that matter:

• How assemblers translate mnemonics to opcodes
• How symbol tables get built across two passes
• How addressing modes affect instruction encoding
• How loaders consume H/T/E record formats

SIC and its extended variant SIC/XE appear in virtually every systems programming course. This API makes those concepts tangible.

Low-level systems concepts are hard to demonstrate without a concrete artifact. This API gives you exactly that.

✅  59-instruction opcode table
✅  Two-pass assembly (symbol resolution + object code generation)
✅  All four SIC/XE instruction formats (1, 2, 3, 4)
✅  Complete addressing mode support (PC-relative, base-relative, immediate, indirect, indexed)
✅  Pseudo-instruction handling (START, BASE, WORD, BYTE, RESW, RESB, END)
✅  Symbol table extraction
✅  Hexadecimal location counter per line
✅  H / T / E record output for loaders
✅  Two input modes: inline JSON  OR  multipart file upload

POST /assemble
      │
      ├─ JSON body  ──────────┐
      └─ multipart/form-data ─┤
                              │
                        [ multer ]
                        [ body-parser ]
                              │
                        ┌─────▼──────┐
                        │  PASS ONE  │  Build symbol table
                        │            │  Compute location counters
                        └─────┬──────┘
                              │  Symbol Table
                        ┌─────▼──────┐
                        │  PASS TWO  │  Resolve symbols
                        │            │  Generate object codes
                        └─────┬──────┘
                              │
                        ┌─────▼──────┐
                        │  RECORDS   │  Emit H / T / E records
                        └─────┬──────┘
                              │
                         JSON Response

All logic lives in server.js and is exposed through a single Express endpoint.

sic-assembler-api/
├── server.js           ← API server + full assembler logic
├── package.json        ← scripts and dependencies
├── package-lock.json
└── uploads/            ← temporary uploaded source files

• Node.js v14 or later
• npm (bundled with Node.js)

git clone <your-repo-url>
cd sic-assembler-api
npm install

npm start

The API will be listening at:

http://localhost:5000

Note: The port is hardcoded to 5000 in server.js. See Roadmap for planned environment-variable support.

curl -s -X POST http://localhost:5000/assemble \
  -H "Content-Type: application/json" \
  -d '{"code": "PROG START 1000\nLDA #3\nSTA ALPHA\nRSUB\nALPHA RESW 1\nEND PROG"}' \
  | python3 -m json.tool

If you get a JSON response with objectCode and records keys — you're up and running.

The single endpoint. Accepts SIC assembly source and returns full assembler output.

Send the source program as a JSON string with \n line separators.

POST /assemble HTTP/1.1
Host: localhost:5000
Content-Type: application/json

{
  "code": "COPY START 1000\nFIRST STL RETADR\nCLOOP JSUB RDREC\n LDA LENGTH\n RSUB\nRETADR RESW 1\nLENGTH WORD 3\nEND FIRST"
}

Upload a .asm or plain-text source file as multipart form data.

POST /assemble HTTP/1.1
Host: localhost:5000
Content-Type: multipart/form-data

file=@program.asm

The file field must contain a plain-text file with one SIC instruction per line. Uploaded files are saved temporarily to the uploads/ directory.

A successful assembly returns HTTP 200 with the following JSON body:

{
  // Source tokens, one entry per line
  "label":          ["COPY",   "FIRST",  "CLOOP",  "-",      ...],
  "instruction":    ["START",  "STL",    "JSUB",   "LDA",    ...],
  "reference":      ["1000",   "RETADR", "RDREC",  "LENGTH", ...],

  // Location counter values in hex, per line (pass one output)
  "locationCounter": ["1000",  "1000",   "1003",   "1006",   ...],

  // Symbol table: label → address (hex)
  "symbolTable": {
    "COPY":   "1000",
    "FIRST":  "1000",
    "CLOOP":  "1003",
    "RETADR": "100C",
    "LENGTH": "100F"
  },

  // Total program size in hex bytes
  "programLength": "12",

  // Object code per line ("No Object code" for pseudo-instructions)
  "objectCode": ["No Object code", "172009", "4B2FFA", "032006", ...],

  // Loader records
  "records": [
    "H^COPY  ^001000^001012",
    "T^001000^0C^1720094B2FFA0320064F00003",
    "E^001000"
  ]
}

The API currently returns assembler output for valid programs. Malformed input may result in unexpected output rather than a structured error response. Improved error diagnostics are tracked in the Roadmap.

The assembler emits three record types in the standard SIC loader format:

H^<name>^<start address>^<program length>

Example:

H^COPY  ^001000^001012

• name — program name, 6 characters, padded with spaces
• start address — 6-digit hex
• program length — 6-digit hex byte count

T^<start address>^<length>^<object codes...>

Example:

T^001000^0C^1720094B2FFA0320064F0000

• start address — 6-digit hex address of the first byte in this record
• length — 2-digit hex byte count of this record (max 30 bytes / 60 hex chars)
• object codes — concatenated hex object bytes with no separators

E^<transfer address>

Example:

E^001000

• transfer address — hex address of the program entry point (from END operand)

SIC/XE supports four instruction formats. The assembler automatically selects the correct format based on the mnemonic and any prefix characters.

┌────────┐
│ opcode │  8 bits
└────────┘

No operand. Used by a small set of instructions (e.g., FLOAT, FIX, NORM).

┌────────┬────┬────┐
│ opcode │ r1 │ r2 │
└────────┴────┴────┘
  8 bits  4b   4b

Register-to-register operations. Operand is one or two register names (e.g., ADDR A, X).

┌────────┬──┬──┬─┬─┬─┬─────────────┐
│ opcode │ni│xi│b│p│e│  disp/addr  │
└────────┴──┴──┴─┴─┴─┴─────────────┘
  6 bits  1b 1b 1b 1b 1b   12 bits

The workhorse format. Supports:

┌────────┬──┬──┬─┬─┬─┬──────────────────────┐
│ opcode │ni│xi│b│p│e│       address        │
└────────┴──┴──┴─┴─┴─┴──────────────────────┘
  6 bits  1b 1b 1b 1b 1b      20 bits

Used when the target address exceeds 12-bit PC/base-relative range. Triggered by prefixing the mnemonic with + (e.g., +JSUB BIGFUNC). The e flag is set to 1.

Pseudo-instructions (assembler directives) control assembly but do not generate machine code directly.

curl -X POST http://localhost:5000/assemble \
  -H "Content-Type: application/json" \
  -d '{
    "code": "PROG START 1000\nLDA #3\nSTA ALPHA\nRSUB\nALPHA RESW 1\nEND PROG"
  }'

curl -X POST http://localhost:5000/assemble \
  -F "file=@program.asm"

curl -s -X POST http://localhost:5000/assemble \
  -H "Content-Type: application/json" \
  -d '{"code": "PROG START 1000\nLDA #3\nSTA ALPHA\nRSUB\nALPHA RESW 1\nEND PROG"}' \
  | python3 -m json.tool

Let's trace exactly what happens when you assemble the classic COPY program.

COPY   START  1000
FIRST  STL    RETADR
CLOOP  JSUB   RDREC
       LDA    LENGTH
       RSUB
RETADR RESW   1
LENGTH WORD   3
       END    FIRST

The assembler steps through each line, assigns hex addresses, and records labels:

Symbol Table after Pass One:

{
  "COPY":   "1000",
  "FIRST":  "1000",
  "CLOOP":  "1003",
  "RETADR": "100C",
  "LENGTH": "100F"
}

Each instruction's operand is now resolved to an address and the object bytes are computed.

{
  "label":           ["COPY", "FIRST", "CLOOP", "-",      "-",      "RETADR", "LENGTH", "-"],
  "instruction":     ["START","STL",   "JSUB",  "LDA",    "RSUB",   "RESW",   "WORD",   "END"],
  "reference":       ["1000", "RETADR","RDREC", "LENGTH", "-",      "1",      "3",      "FIRST"],
  "locationCounter": ["1000", "1000",  "1003",  "1006",   "1009",   "100C",   "100F",   "1012"],
  "symbolTable": {
    "COPY":   "1000",
    "FIRST":  "1000",
    "CLOOP":  "1003",
    "RETADR": "100C",
    "LENGTH": "100F"
  },
  "programLength": "12",
  "objectCode": [
    "No Object code",
    "172009",
    "4B2FFA",
    "032006",
    "4F0000",
    "No Object code",
    "3",
    "No Object code"
  ],
  "records": [
    "H^COPY  ^001000^001012",
    "T^001000^0C^1720094B2FFA0320064F00003",
    "E^001000"
  ]
}

Contributions are welcome. Fork the repository, make your changes, and open a pull request.

# Install dependencies
npm install

# Start with auto-restart on file changes (requires nodemon)
npx nodemon server.js

# Run tests (placeholder — contribute real tests!)
npm test

Licensed under the ISC License.
See package.json for metadata. Adding a dedicated LICENSE file is recommended before public distribution.