# kxtzownsu/gscemulator-c architecture

> Architecture diagram of the GitHub repository kxtzownsu/gscemulator-c, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kxtzownsu/gscemulator-c
- Repository: https://github.com/kxtzownsu/gscemulator-c

## Overview

better-gscemu is a standalone C rewrite of GSCEmulator, not a library. Its visible workflow parses command-line options, selects H1B3C, initializes Unicorn with the BootROM and CPU state, starts emulation, then shuts down. The source also shows reusable MMIO component registration and a FOOBAR peripheral. Peripheral initialization is invoked by the emulator, but the sampled excerpts do not establish how individual peripheral implementations are wired or mapped.

Main entry points: [`src/H1B3C/emulator.c`](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/H1B3C/emulator.c) (Unicorn emulator), [`src/main.c`](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/main.c) (CLI entry), [`src/common/file.c`](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/common/file.c) (File reader), [`src/libargs.c`](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/libargs.c) (Argument parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command line"]
  node_entry["CLI entry<br/>[main.c]"]
  node_args["Argument parser<br/>[libargs.c]"]
end

subgraph group_core["Emulator core"]
  node_engine["Unicorn emulator<br/>[emulator.c]"]
end

subgraph group_platform["H1B3C platform"]
  node_periphinit["Peripheral initialization<br/>[_init.c]"]
  node_foobar["FOOBAR peripheral<br/>[foobar.c]"]
end

subgraph group_shared["Shared runtime"]
  node_emuctx["Runtime context<br/>[ctx.c]"]
  node_fileio["File reader<br/>[file.c]"]
  node_component["MMIO components<br/>[component.c]"]
  node_logger["Logging<br/>[logger.c]"]
end

node_user(("Operator"))
node_unicorn["Unicorn engine"]
node_rom["BootROM file"]

node_user -->|"provides options"| node_entry
node_entry -->|"parses flags"| node_args
node_entry -->|"initializes context"| node_emuctx
node_entry -->|"selects and starts"| node_engine
node_args -->|"returns values"| node_entry
node_engine -->|"configures and runs"| node_unicorn
node_rom -->|"supplies bytes"| node_fileio
node_engine -->|"reads BootROM"| node_fileio
node_engine -->|"initializes peripherals"| node_periphinit
node_foobar -->|"registers component"| node_component
node_component -->|"maps MMIO callbacks"| node_unicorn
node_engine -->|"logs emulator events"| node_logger
node_fileio -->|"logs file errors"| node_logger

click node_entry "https://github.com/kxtzownsu/gscemulator-c/blob/main/src/main.c"
click node_args "https://github.com/kxtzownsu/gscemulator-c/blob/main/src/libargs.c"
click node_emuctx "https://github.com/kxtzownsu/gscemulator-c/blob/main/src/common/ctx.c"
click node_engine "https://github.com/kxtzownsu/gscemulator-c/blob/main/src/H1B3C/emulator.c"
click node_fileio "https://github.com/kxtzownsu/gscemulator-c/blob/main/src/common/file.c"
click node_periphinit "https://github.com/kxtzownsu/gscemulator-c/blob/main/src/H1B3C/peripherals/_init.c"
click node_component "https://github.com/kxtzownsu/gscemulator-c/blob/main/src/common/peripherals/component.c"
click node_foobar "https://github.com/kxtzownsu/gscemulator-c/blob/main/src/H1B3C/peripherals/foobar.c"
click node_logger "https://github.com/kxtzownsu/gscemulator-c/blob/main/src/common/logger.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_args toneBlue
class node_engine toneAmber
class node_periphinit,node_foobar toneMint
class node_emuctx,node_fileio,node_component,node_logger toneRose
class node_user,node_unicorn,node_rom toneIndigo
```

## Components

### Command line

- [CLI entry](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/main.c): `src/main.c`
- [Argument parser](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/libargs.c): `src/libargs.c`

### Emulator core

- [Unicorn emulator](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/H1B3C/emulator.c): `src/H1B3C/emulator.c`

### H1B3C platform

- [Peripheral initialization](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/H1B3C/peripherals/_init.c): `src/H1B3C/peripherals/_init.c`
- [FOOBAR peripheral](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/H1B3C/peripherals/foobar.c): `src/H1B3C/peripherals/foobar.c`

### Shared runtime

- [Runtime context](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/common/ctx.c): `src/common/ctx.c`
- [File reader](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/common/file.c): `src/common/file.c`
- [MMIO components](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/common/peripherals/component.c): `src/common/peripherals/component.c`
- [Logging](https://github.com/kxtzownsu/gscemulator-c/blob/main/src/common/logger.c): `src/common/logger.c`

### Other components

- **Operator**
- **Unicorn engine**
- **BootROM file**

## Connections

- Operator → CLI entry: provides options (evidence: `src/main.c`)
- CLI entry → Argument parser: parses flags (evidence: `src/main.c`)
- CLI entry → Runtime context: initializes context (evidence: `src/main.c`)
- CLI entry → Unicorn emulator: selects and starts (evidence: `src/main.c`)
- Argument parser → CLI entry: returns values (evidence: `src/main.c`)
- Unicorn emulator → Unicorn engine: configures and runs (evidence: `src/H1B3C/emulator.c`)
- BootROM file → File reader: supplies bytes
- Unicorn emulator → File reader: reads BootROM (evidence: `src/H1B3C/emulator.c`)
- Unicorn emulator → Peripheral initialization: initializes peripherals (evidence: `src/H1B3C/emulator.c`)
- FOOBAR peripheral → MMIO components: registers component (evidence: `src/H1B3C/peripherals/foobar.c`)
- MMIO components → Unicorn engine: maps MMIO callbacks (evidence: `src/common/peripherals/component.c`)
- Unicorn emulator → Logging: logs emulator events (evidence: `src/H1B3C/emulator.c`)
- File reader → Logging: logs file errors (evidence: `src/common/file.c`)
