# sca-research/elmo architecture

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

- Interactive diagram: https://gitdiagram.com/sca-research/elmo
- Repository: https://github.com/sca-research/elmo

## Overview

ELMO is an ARM M0 leakage simulator and analysis tool. The principal workflow starts with user-compiled Thumb binaries: ELMO emulates execution and pipeline context, applies statistical power models, and produces traces that can be analyzed for fixed-vs-random leakage or energy. Separate M3 model-building code captures hardware traces and provides single- and sequential-instruction experiments. The README also documents mask-flow analysis, a memory-bus extension, alternate-core coefficients, and TVLA sample-size support. Some internal calls and unsampled subsystems are not shown, so links without direct evidence are omitted.

Main entry points: [`elmo.c`](https://github.com/sca-research/elmo/blob/master/elmo.c) (ELMO emulator), [`ModelBuilding_M3/AcqCode/BuildModel_M3_Full.py`](https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/AcqCode/BuildModel_M3_Full.py) (M3 trace capture), [`ModelBuilding_M3/ARMCode/SingleInstr/BuildModel_Single.c`](https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/ARMCode/SingleInstr/BuildModel_Single.c) (Single-instruction target), [`ModelBuilding_M3/ARMCode/SeqInstr/BuildModel_Seq.c`](https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/ARMCode/SeqInstr/BuildModel_Seq.c) (Sequence target)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Emulation and leakage"]
  node_elmo["ELMO emulator<br/>[elmo.c]"]
  node_configuration["Core configuration<br/>[elmodefines.h]"]
  node_flow["Execution dataflow<br/>[elmodefines.h]"]
  node_power["Power models<br/>[powermodel.h]"]
  node_memory["Memory extension<br/>[elmodefines.h]"]
  node_traces["Trace outputs<br/>[elmo.c]"]
end

subgraph group_analysis["Trace analysis"]
  node_tvla["Fixed-random TVLA<br/>[fixedvsrandom.h]"]
  node_mask["Mask-flow analysis<br/>[maskflow.h]"]
  node_energy["Energy analysis<br/>[energy.h]"]
end

subgraph group_modeling["Model building"]
  node_single_target["Single-instruction target"]
  node_sequence_target["Sequence target<br/>[BuildModel_Seq.c]"]
end

subgraph group_acquisition["Hardware acquisition"]
  node_capture["M3 trace capture"]
  node_trace_set["TRS trace writer<br/>[TRS_TraceSet.py]"]
end

node_user(("User"))
node_thumb["Thumb binary"]
node_scope["PicoScope"]

node_user -->|"compiles code"| node_thumb
node_thumb -->|"provides binary"| node_elmo
node_elmo -->|"records execution"| node_flow
node_elmo -->|"uses model"| node_power
node_elmo -->|"uses settings"| node_configuration
node_elmo -->|"writes traces"| node_traces
node_elmo -->|"tracks bus"| node_memory
node_elmo -->|"supports testing"| node_tvla
node_elmo -->|"tracks mask flow"| node_mask
node_elmo -->|"supports energy"| node_energy
node_single_target -.->|"measured by"| node_capture
node_sequence_target -.->|"measured by"| node_capture
node_capture -->|"captures samples"| node_scope
node_capture -->|"writes traces"| node_trace_set

click node_elmo "https://github.com/sca-research/elmo/blob/master/elmo.c"
click node_configuration "https://github.com/sca-research/elmo/blob/master/elmodefines.h"
click node_flow "https://github.com/sca-research/elmo/blob/master/elmodefines.h"
click node_power "https://github.com/sca-research/elmo/blob/master/include/powermodel.h"
click node_memory "https://github.com/sca-research/elmo/blob/master/elmodefines.h"
click node_traces "https://github.com/sca-research/elmo/blob/master/elmo.c"
click node_tvla "https://github.com/sca-research/elmo/blob/master/include/fixedvsrandom.h"
click node_mask "https://github.com/sca-research/elmo/blob/master/include/maskflow.h"
click node_energy "https://github.com/sca-research/elmo/blob/master/include/energy.h"
click node_single_target "https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/ARMCode/SingleInstr/BuildModel_Single.c"
click node_sequence_target "https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/ARMCode/SeqInstr/BuildModel_Seq.c"
click node_capture "https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/AcqCode/BuildModel_M3_Full.py"
click node_trace_set "https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/AcqCode/TRS_TraceSet.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_elmo,node_configuration,node_flow,node_power,node_memory,node_traces,node_user toneBlue
class node_tvla,node_mask,node_energy toneAmber
class node_single_target,node_sequence_target toneMint
class node_capture,node_trace_set toneRose
class node_thumb,node_scope toneIndigo
```

## Components

### Emulation and leakage

- [ELMO emulator](https://github.com/sca-research/elmo/blob/master/elmo.c): `elmo.c`
- [Core configuration](https://github.com/sca-research/elmo/blob/master/elmodefines.h): `elmodefines.h`
- [Execution dataflow](https://github.com/sca-research/elmo/blob/master/elmodefines.h): `elmodefines.h`
- [Power models](https://github.com/sca-research/elmo/blob/master/include/powermodel.h): `include/powermodel.h`
- [Memory extension](https://github.com/sca-research/elmo/blob/master/elmodefines.h): `elmodefines.h`
- [Trace outputs](https://github.com/sca-research/elmo/blob/master/elmo.c): `elmo.c`

### Trace analysis

- [Fixed-random TVLA](https://github.com/sca-research/elmo/blob/master/include/fixedvsrandom.h): `include/fixedvsrandom.h`
- [Mask-flow analysis](https://github.com/sca-research/elmo/blob/master/include/maskflow.h): `include/maskflow.h`
- [Energy analysis](https://github.com/sca-research/elmo/blob/master/include/energy.h): `include/energy.h`

### Model building

- [Single-instruction target](https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/ARMCode/SingleInstr/BuildModel_Single.c): `ModelBuilding_M3/ARMCode/SingleInstr/BuildModel_Single.c`
- [Sequence target](https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/ARMCode/SeqInstr/BuildModel_Seq.c): `ModelBuilding_M3/ARMCode/SeqInstr/BuildModel_Seq.c`

### Hardware acquisition

- [M3 trace capture](https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/AcqCode/BuildModel_M3_Full.py): `ModelBuilding_M3/AcqCode/BuildModel_M3_Full.py`
- [TRS trace writer](https://github.com/sca-research/elmo/blob/master/ModelBuilding_M3/AcqCode/TRS_TraceSet.py): `ModelBuilding_M3/AcqCode/TRS_TraceSet.py`

### Other components

- **User**
- **Thumb binary**
- **PicoScope**

## Connections

- User → Thumb binary: compiles code (evidence: `README.md`)
- Thumb binary → ELMO emulator: provides binary (evidence: `README.md`)
- ELMO emulator → Execution dataflow: records execution (evidence: `elmo.c`)
- ELMO emulator → Power models: uses model (evidence: `elmo.c`)
- ELMO emulator → Core configuration: uses settings (evidence: `elmo.c`)
- ELMO emulator → Trace outputs: writes traces (evidence: `README.md`)
- ELMO emulator → Memory extension: tracks bus (evidence: `README.md`)
- ELMO emulator → Fixed-random TVLA: supports testing (evidence: `README.md`)
- ELMO emulator → Mask-flow analysis: tracks mask flow (evidence: `README.md`)
- ELMO emulator → Energy analysis: supports energy (evidence: `README.md`)
- Single-instruction target → M3 trace capture: measured by
- Sequence target → M3 trace capture: measured by
- M3 trace capture → PicoScope: captures samples (evidence: `ModelBuilding_M3/AcqCode/BuildModel_M3_Full.py`)
- M3 trace capture → TRS trace writer: writes traces (evidence: `ModelBuilding_M3/AcqCode/BuildModel_M3_Full.py`)