Architecture Overview¶

This guide covers extending and developing CREATOR, including architecture, core internals, and customization.

Target Audience¶

Developers adding new features to CREATOR
Researchers implementing custom architectures
Contributors to the CREATOR project
Advanced users customizing behavior

Source Code Structure¶

src/
├── cli/                    # Command-line interface
│   ├── creator6.mts       # Main CLI application
│   ├── runner.mts         # Binary runner
│   ├── tutorial.mts       # Tutorial mode
│   └── utils.mts          # CLI utilities
│
├── core/                   # Core simulator
│   ├── core.mjs           # Main core API
│   ├── events.mjs         # Event system
│   │
│   ├── assembler/         # Assembly compilation
│   │   ├── assembler.mts  # Core assembler
│   │   ├── creatorAssembler/  # Native assembler
│   │   ├── sjasmplus/     # Z80 assembler
│   │   └── rasm/          # Alternative Z80
│   │
│   ├── capi/              # C API and system calls
│   │   ├── initCAPI.mts   # CAPI initialization
│   │   ├── syscall.mts    # System calls
│   │   ├── memory.mts     # Memory operations
│   │   ├── registers.mts  # Register operations
│   │   └── interrupts.mts # Interrupt handling
│   │
│   ├── executor/          # Execution engine
│   │   ├── executor.mjs   # Main executor
│   │   ├── decoder.mjs    # Instruction decoder
│   │   ├── devices.mts    # Device system
│   │   ├── interrupts.mts # Interrupt handling
│   │   ├── IO.mjs         # I/O operations
│   │   ├── stats.mts      # Statistics tracking
│   │   └── timers.mts     # Timer management
│   │
│   ├── memory/            # Memory subsystem
│   │   ├── Memory.mts     # Memory implementation
│   │   └── StackTracker.mts  # Call stack tracking
│   │
│   ├── register/          # Register subsystem
│   │   ├── registerLookup.mjs     # Register lookup
│   │   ├── registerOperations.mjs # Register ops
│   │   └── registerGlowState.mjs  # State tracking
│   │
│   ├── sentinel/          # Security/validation
│   │   └── sentinel.mjs   # Sentinel system
│   │
│   └── utils/             # Utilities
│       ├── architectureProcessor.mjs  # Architecture loading
│       ├── bigint.mjs     # BigInt utilities
│       ├── creator_logger.mjs  # Logging
│       ├── creator_ga.mjs # Analytics
│       ├── float_bigint.mjs  # Float conversion
│       └── schema.mts     # Type definitions
│
├── web/                   # Web interface
│   ├── main.ts            # Web entry point
│   ├── App.vue            # Main Vue component
│   ├── assemblers.ts      # Assembler selection
│   ├── components/        # Vue components
│   └── monaco/            # Editor integration
│
└── rpc/                   # RPC server
    ├── README.md
    └── server.mts         # RPC server implementation

Development Workflow¶

Setting Up Development Environment¶

Clone Repository:

git clone https://github.com/creatorsim/creator.git
cd creator

Install Dependencies:
```
npm install  # or yarn install
```
Build:
```
npm run build
```
Run Tests:
```
npm test
```

Making Changes¶

Branch: Create feature branch
Code: Make your changes
Test: Verify functionality
Document: Update docs
Commit: Descriptive commit message
PR: Submit pull request

Key Concepts¶

Architecture Definition¶

Architectures are defined in YAML files specifying:

Instruction sets
Register banks
Memory layout
System calls
Interrupts

Instruction Execution¶

The execution pipeline:

Fetch: Read instruction from memory
Decode: Parse instruction format
Execute: Perform operation
Writeback: Update registers/memory
Update: Advance PC

State Management¶

CREATOR maintains complete simulator state:

Register values
Memory contents
Program counter
Execution mode
Device states

State can be saved/restored via snapshots.

Device System¶

Devices provide I/O and OS services:

Memory-mapped interface
Control/status registers
Data buffers
Callback handlers

See Devices for details.

API Overview¶

Core API (`core.mjs`)¶

// Load architecture
loadArchitecture(yamlString, isaExtensions)

// Compile assembly
assembly_compile(source, compiler)

// Execute instructions
step()  // Execute one instruction
reset() // Reset to initial state

// State management
snapshot(extraData)
restore(stateJson)

// Register access
dumpRegister(name, format)
getRegisterInfo(name)

// Memory access
main_memory.readWord(address)
main_memory.writeWord(address, bytes)

Memory API¶

// Create memory
new Memory({
    sizeInBytes,
    bitsPerByte,
    wordSize,
    baseAddress,
    endianness
})

// Access
memory.read(address)
memory.write(address, value)
memory.readWord(address)
memory.writeWord(address, bytes)

// Hints
memory.setHint(address, {tag, type, sizeInBits})
memory.getHint(address)

Design Principles¶

Modularity¶

Clear separation of concerns
Independent subsystems
Well-defined interfaces

Extensibility¶

Plugin architecture for assemblers
Custom device support
Flexible architecture definitions

Testability¶

Unit testable components
Integration test support
Snapshot-based testing

Performance¶

Efficient execution
Caching where appropriate
Lazy evaluation

Contributing¶

Code Style¶

TypeScript/JavaScript ES6+
Consistent formatting
Descriptive names
Comments for complex logic

Testing¶

Unit tests for new features
Integration tests for workflows
Regression tests for bugs

Documentation¶

Update relevant docs
Add examples
Explain design decisions

Resources¶

GitHub: Source code and issues
Architecture Files: architecture/ directory
Examples: examples/ directory
Tests: tests/ directory