# havenoverflow/gscemu architecture

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

- Interactive diagram: https://gitdiagram.com/havenoverflow/gscemu
- Repository: https://github.com/havenoverflow/gscemu

## Overview

gscemulator is a Python/Unicorn emulator for Google's GSC, with Haven/Cr50 as its implemented target. The main workflow is launching the emulator, initializing its chip model and firmware, then running it and interacting with the Cr50 console over UART. The graph groups the chip’s CPU, security, storage, and peripheral models, plus shared runtime support. Some subsystem wiring is visible through the component registry and imports; unsampled implementation details and the TBC chip targets are not expanded.

Main entry points: [`src/haven/components/__init__.py`](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/__init__.py) (Component registry), [`src/haven/emulator.py`](https://github.com/havenoverflow/gscemu/blob/main/src/haven/emulator.py) (Haven emulator), [`src/haven/components/uart.py`](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/uart.py) (UART console), [`src/haven/components/m3.py`](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/m3.py) (Cortex-M3 and interrupts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and setup"]
  node_launcher["CLI launcher<br/>[main.py]"]
  node_emulator["Haven emulator<br/>[emulator.py]"]
  node_context["Emulator context"]
  node_helpers["Emulation helpers<br/>[helpers.py]"]
  node_logger["Logger<br/>[logger.py]"]
  node_settings["Runtime settings<br/>[env.py]"]
  node_threading["Thread and Unicorn locks<br/>[threadutils.py]"]
  node_uc_thread["Unicorn execution thread<br/>[ucthread.py]"]
  node_component_registry["Component registry<br/>[__init__.py]"]
  node_firmware_setup["Firmware initialization<br/>[init_utils.py]"]
  node_firmware["Firmware images"]
  node_endorsement["Endorsement certificates"]
end

subgraph group_cpu["CPU and execution"]
  node_hooks["Execution hooks<br/>[hooks.py]"]
  node_m3["Cortex-M3 and interrupts<br/>[m3.py]"]
  node_registers["Register definitions<br/>[registers.py]"]
  node_pin_registers["Pinmux registers"]
  node_fuse_registers["Fuse registers<br/>[fuse_registers.py]"]
end

subgraph group_security["Security engines"]
  node_crypto["Cryptographic engine<br/>[crypto.py]"]
  node_keymgr["Key manager<br/>[keymgr.py]"]
  node_trng["Random generator<br/>[trng.py]"]
  node_timels["Time and lifecycle<br/>[timels.py]"]
end

subgraph group_storage["Chip state"]
  node_flash["Flash memory<br/>[flash.py]"]
  node_fuse["Fuse storage<br/>[fuse.py]"]
  node_globalsec["Global security<br/>[globalsec.py]"]
  node_pmu["Power management<br/>[pmu.py]"]
end

subgraph group_peripherals["Peripherals and pins"]
  node_pin_device["Pin signal model<br/>[pindevice.py]"]
  node_pinmux["Pin multiplexing<br/>[pinmux.py]"]
  node_gpio["GPIO<br/>[gpio.py]"]
  node_sps["SPI slave<br/>[sps.py]"]
  node_uart["UART console<br/>[uart.py]"]
  node_usb["USB<br/>[usb.py]"]
  node_swdp["Debug port<br/>[swdp.py]"]
  node_ap["Application processor model<br/>[ap_emu.py]"]
end

node_user(("Operator"))

node_user -->|"launches"| node_launcher
node_launcher -->|"creates"| node_emulator
node_emulator -->|"initializes"| node_context
node_emulator -->|"registers components"| node_component_registry
node_emulator -->|"loads firmware"| node_firmware_setup
node_firmware_setup -.->|"loads images"| node_firmware
node_firmware_setup -->|"installs certificates"| node_endorsement
node_emulator -->|"installs hooks"| node_hooks
node_emulator -->|"initializes model"| node_ap
node_emulator -->|"accepts UART input"| node_uart
node_emulator -->|"starts execution"| node_uc_thread
node_user -->|"uses console"| node_uart
node_component_registry -->|"registers"| node_m3
node_component_registry -->|"registers"| node_crypto
node_component_registry -->|"registers"| node_keymgr
node_component_registry -->|"registers"| node_trng
node_component_registry -->|"registers"| node_timels
node_component_registry -->|"registers"| node_flash
node_component_registry -->|"registers"| node_fuse
node_component_registry -->|"registers"| node_globalsec
node_component_registry -->|"registers"| node_pmu
node_component_registry -->|"registers"| node_pinmux
node_component_registry -->|"registers"| node_gpio
node_component_registry -->|"registers"| node_sps
node_component_registry -->|"registers"| node_uart
node_component_registry -->|"registers"| node_usb
node_component_registry -->|"registers"| node_swdp
node_emulator -->|"loads definitions"| node_registers
node_emulator -->|"loads definitions"| node_pin_registers
node_component_registry -->|"imports definitions"| node_fuse_registers
node_context -->|"creates mutex"| node_threading
node_context -->|"creates thread"| node_uc_thread
node_uc_thread -->|"logs failures"| node_logger
node_settings -->|"configures"| node_logger
node_pinmux -->|"models pin signals"| node_pin_device
node_ap -->|"uses"| node_pinmux
node_ap -->|"uses"| node_sps
node_gpio -->|"models pin signals"| node_pin_device
node_sps -->|"models pin signals"| node_pin_device
node_crypto -->|"references CPU"| node_m3
node_uart -->|"references CPU"| node_m3
node_hooks -->|"references CPU"| node_m3

click node_launcher "https://github.com/havenoverflow/gscemu/blob/main/main.py"
click node_emulator "https://github.com/havenoverflow/gscemu/blob/main/src/haven/emulator.py"
click node_context "https://github.com/havenoverflow/gscemu/blob/main/lib/emulator_context.py"
click node_helpers "https://github.com/havenoverflow/gscemu/blob/main/lib/helpers.py"
click node_logger "https://github.com/havenoverflow/gscemu/blob/main/lib/logger.py"
click node_settings "https://github.com/havenoverflow/gscemu/blob/main/env.py"
click node_threading "https://github.com/havenoverflow/gscemu/blob/main/lib/threadutils.py"
click node_uc_thread "https://github.com/havenoverflow/gscemu/blob/main/lib/ucthread.py"
click node_hooks "https://github.com/havenoverflow/gscemu/blob/main/src/haven/hooks.py"
click node_m3 "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/m3.py"
click node_registers "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/regdefs/registers.py"
click node_pin_registers "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/regdefs/pinmux_registers.py"
click node_fuse_registers "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/regdefs/fuse_registers.py"
click node_crypto "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/crypto.py"
click node_keymgr "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/keymgr.py"
click node_trng "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/trng.py"
click node_timels "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/timels.py"
click node_flash "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/flash.py"
click node_fuse "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/fuse.py"
click node_globalsec "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/globalsec.py"
click node_pmu "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/pmu.py"
click node_pin_device "https://github.com/havenoverflow/gscemu/blob/main/lib/pindevice.py"
click node_pinmux "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/pinmux.py"
click node_gpio "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/gpio.py"
click node_sps "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/sps.py"
click node_uart "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/uart.py"
click node_usb "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/usb.py"
click node_swdp "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/swdp.py"
click node_ap "https://github.com/havenoverflow/gscemu/blob/main/src/haven/ap_emu.py"
click node_component_registry "https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/__init__.py"
click node_firmware_setup "https://github.com/havenoverflow/gscemu/blob/main/src/haven/init_utils.py"
click node_firmware "https://github.com/havenoverflow/gscemu/tree/main/src/haven/fw"
click node_endorsement "https://github.com/havenoverflow/gscemu/blob/main/src/haven/endorsement_cert.py"

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_launcher,node_emulator,node_context,node_helpers,node_logger,node_settings,node_threading,node_uc_thread,node_component_registry,node_firmware_setup,node_firmware,node_endorsement toneBlue
class node_hooks,node_m3,node_registers,node_pin_registers,node_fuse_registers toneAmber
class node_crypto,node_keymgr,node_trng,node_timels toneMint
class node_flash,node_fuse,node_globalsec,node_pmu toneRose
class node_pin_device,node_pinmux,node_gpio,node_sps,node_uart,node_usb,node_swdp,node_ap,node_user toneIndigo
```

## Components

### Runtime and setup

- [CLI launcher](https://github.com/havenoverflow/gscemu/blob/main/main.py): `main.py`
- [Haven emulator](https://github.com/havenoverflow/gscemu/blob/main/src/haven/emulator.py): `src/haven/emulator.py`
- [Emulator context](https://github.com/havenoverflow/gscemu/blob/main/lib/emulator_context.py): `lib/emulator_context.py`
- [Emulation helpers](https://github.com/havenoverflow/gscemu/blob/main/lib/helpers.py): `lib/helpers.py`
- [Logger](https://github.com/havenoverflow/gscemu/blob/main/lib/logger.py): `lib/logger.py`
- [Runtime settings](https://github.com/havenoverflow/gscemu/blob/main/env.py): `env.py`
- [Thread and Unicorn locks](https://github.com/havenoverflow/gscemu/blob/main/lib/threadutils.py): `lib/threadutils.py`
- [Unicorn execution thread](https://github.com/havenoverflow/gscemu/blob/main/lib/ucthread.py): `lib/ucthread.py`
- [Component registry](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/__init__.py): `src/haven/components/__init__.py`
- [Firmware initialization](https://github.com/havenoverflow/gscemu/blob/main/src/haven/init_utils.py): `src/haven/init_utils.py`
- [Firmware images](https://github.com/havenoverflow/gscemu/tree/main/src/haven/fw): `src/haven/fw`
- [Endorsement certificates](https://github.com/havenoverflow/gscemu/blob/main/src/haven/endorsement_cert.py): `src/haven/endorsement_cert.py`

### CPU and execution

- [Execution hooks](https://github.com/havenoverflow/gscemu/blob/main/src/haven/hooks.py): `src/haven/hooks.py`
- [Cortex-M3 and interrupts](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/m3.py): `src/haven/components/m3.py`
- [Register definitions](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/regdefs/registers.py): `src/haven/components/regdefs/registers.py`
- [Pinmux registers](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/regdefs/pinmux_registers.py): `src/haven/components/regdefs/pinmux_registers.py`
- [Fuse registers](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/regdefs/fuse_registers.py): `src/haven/components/regdefs/fuse_registers.py`

### Security engines

- [Cryptographic engine](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/crypto.py): `src/haven/components/crypto.py`
- [Key manager](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/keymgr.py): `src/haven/components/keymgr.py`
- [Random generator](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/trng.py): `src/haven/components/trng.py`
- [Time and lifecycle](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/timels.py): `src/haven/components/timels.py`

### Chip state

- [Flash memory](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/flash.py): `src/haven/components/flash.py`
- [Fuse storage](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/fuse.py): `src/haven/components/fuse.py`
- [Global security](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/globalsec.py): `src/haven/components/globalsec.py`
- [Power management](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/pmu.py): `src/haven/components/pmu.py`

### Peripherals and pins

- [Pin signal model](https://github.com/havenoverflow/gscemu/blob/main/lib/pindevice.py): `lib/pindevice.py`
- [Pin multiplexing](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/pinmux.py): `src/haven/components/pinmux.py`
- [GPIO](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/gpio.py): `src/haven/components/gpio.py`
- [SPI slave](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/sps.py): `src/haven/components/sps.py`
- [UART console](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/uart.py): `src/haven/components/uart.py`
- [USB](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/usb.py): `src/haven/components/usb.py`
- [Debug port](https://github.com/havenoverflow/gscemu/blob/main/src/haven/components/swdp.py): `src/haven/components/swdp.py`
- [Application processor model](https://github.com/havenoverflow/gscemu/blob/main/src/haven/ap_emu.py): `src/haven/ap_emu.py`

### Other components

- **Operator**

## Connections

- Operator → CLI launcher: launches (evidence: `README.md`)
- CLI launcher → Haven emulator: creates (evidence: `main.py`)
- Haven emulator → Emulator context: initializes (evidence: `src/haven/emulator.py`)
- Haven emulator → Component registry: registers components (evidence: `src/haven/emulator.py`)
- Haven emulator → Firmware initialization: loads firmware (evidence: `src/haven/emulator.py`)
- Firmware initialization → Firmware images: loads images
- Firmware initialization → Endorsement certificates: installs certificates (evidence: `src/haven/init_utils.py`)
- Haven emulator → Execution hooks: installs hooks (evidence: `src/haven/emulator.py`)
- Haven emulator → Application processor model: initializes model (evidence: `src/haven/emulator.py`)
- Haven emulator → UART console: accepts UART input (evidence: `src/haven/emulator.py`)
- Haven emulator → Unicorn execution thread: starts execution (evidence: `src/haven/emulator.py`)
- Operator → UART console: uses console (evidence: `README.md`)
- Component registry → Cortex-M3 and interrupts: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Cryptographic engine: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Key manager: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Random generator: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Time and lifecycle: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Flash memory: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Fuse storage: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Global security: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Power management: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Pin multiplexing: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → GPIO: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → SPI slave: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → UART console: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → USB: registers (evidence: `src/haven/components/__init__.py`)
- Component registry → Debug port: registers (evidence: `src/haven/components/__init__.py`)
- Haven emulator → Register definitions: loads definitions (evidence: `src/haven/emulator.py`)
- Haven emulator → Pinmux registers: loads definitions (evidence: `src/haven/emulator.py`)
- Component registry → Fuse registers: imports definitions
- Emulator context → Thread and Unicorn locks: creates mutex (evidence: `lib/emulator_context.py`)
- Emulator context → Unicorn execution thread: creates thread (evidence: `lib/emulator_context.py`)
- Unicorn execution thread → Logger: logs failures (evidence: `lib/ucthread.py`)
- Runtime settings → Logger: configures (evidence: `env.py`)
- Pin multiplexing → Pin signal model: models pin signals (evidence: `src/haven/components/pinmux.py`)
- Application processor model → Pin multiplexing: uses (evidence: `src/haven/ap_emu.py`)
- Application processor model → SPI slave: uses (evidence: `src/haven/ap_emu.py`)
- GPIO → Pin signal model: models pin signals (evidence: `src/haven/components/gpio.py`)
- SPI slave → Pin signal model: models pin signals (evidence: `src/haven/components/sps.py`)
- Cryptographic engine → Cortex-M3 and interrupts: references CPU (evidence: `src/haven/components/crypto.py`)
- UART console → Cortex-M3 and interrupts: references CPU (evidence: `src/haven/components/uart.py`)
- Execution hooks → Cortex-M3 and interrupts: references CPU (evidence: `src/haven/hooks.py`)
