# openipc/qemu-hisilicon architecture

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

- Interactive diagram: https://gitdiagram.com/openipc/qemu-hisilicon
- Repository: https://github.com/openipc/qemu-hisilicon

## Overview

This repository emulates HiSilicon IPC, DVR/NVR, and STB SoCs in QEMU so unmodified firmware can boot into Linux. The main workflow is selecting a machine, configuring its CPU, memory, and peripherals, then booting firmware; fastboot supports serial download when no kernel is supplied. Peripheral models cover the documented flash, networking, I2C, SPI, video, and accelerator capabilities. OMS tools form a separate model-format branch. The README and excerpts establish the architecture, but many peripheral instantiations and unsampled subsystems are not shown, so their specific links are omitted.

Main entry points: [`qemu/hw/arm/hisilicon.c`](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/arm/hisilicon.c) (Machine Setup), [`qemu/include/hw/misc/hisi-fastboot.h`](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/include/hw/misc/hisi-fastboot.h) (Fastboot Interface), [`qemu/hw/i2c/hisi-i2c.c`](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/i2c/hisi-i2c.c) (I2C Controller), [`qemu/hw/misc/hisi-fastboot.c`](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/misc/hisi-fastboot.c) (Serial Fastboot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_machine["Machine and Boot"]
  node_soc_config["SoC Configuration<br/>[hisilicon.h]"]
  node_machine_init["Machine Setup<br/>[hisilicon.c]"]
  node_fastboot["Serial Fastboot<br/>[hisi-fastboot.c]"]
  node_fastboot_api["Fastboot Interface<br/>[hisi-fastboot.h]"]
end

subgraph group_devices["SoC Peripherals"]
  node_flash["Flash Controllers<br/>[hisi-fmc.c]"]
  node_i2c["I2C Controller<br/>[hisi-i2c.c]"]
  node_sensors["I2C Sensors<br/>[hisi-imx385.c]"]
  node_spi["SPI Controller<br/>[hisi-spi.c]"]
end

subgraph group_models["IVE and Models"]
  node_ive["IVE Accelerator<br/>[hisi-ive.c]"]
  node_nnie["NNIE Accelerator<br/>[hisi-nnie.c]"]
  node_oms_builder["OMS Builder<br/>[oms_builder.py]"]
  node_oms_parser["OMS Parser<br/>[oms_parser.py]"]
end

subgraph group_network["Networking"]
  node_femac["Fast Ethernet<br/>[hisi-femac.c]"]
  node_gmac["Gigabit Ethernet<br/>[hisi-gmac.c]"]
end

node_operator(("QEMU User"))
node_firmware["Guest Firmware"]
node_linux(("Guest Linux"))

node_operator -->|"selects machine"| node_machine_init
node_soc_config -->|"configures"| node_machine_init
node_firmware -->|"boots on"| node_machine_init
node_machine_init -->|"boots guest"| node_linux
node_machine_init -->|"uses interface"| node_fastboot_api
node_fastboot_api -->|"configures"| node_fastboot
node_operator -->|"uploads firmware"| node_fastboot
node_machine_init -.->|"models flash"| node_flash
node_machine_init -.->|"models I2C"| node_i2c
node_i2c -.->|"drives sensor"| node_sensors
node_machine_init -.->|"models SPI"| node_spi
node_machine_init -.->|"models IVE"| node_ive
node_machine_init -.->|"models NPU"| node_nnie
node_oms_builder -->|"uses parser"| node_oms_parser
node_machine_init -.->|"models Ethernet"| node_femac
node_machine_init -.->|"models Ethernet"| node_gmac

click node_soc_config "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/include/hw/arm/hisilicon.h"
click node_machine_init "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/arm/hisilicon.c"
click node_fastboot "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/misc/hisi-fastboot.c"
click node_fastboot_api "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/include/hw/misc/hisi-fastboot.h"
click node_flash "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/misc/hisi-fmc.c"
click node_i2c "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/i2c/hisi-i2c.c"
click node_sensors "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/i2c/hisi-imx385.c"
click node_spi "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/ssi/hisi-spi.c"
click node_ive "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/misc/hisi-ive.c"
click node_nnie "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/misc/hisi-nnie.c"
click node_oms_builder "https://github.com/openipc/qemu-hisilicon/blob/master/tools/oms_builder.py"
click node_oms_parser "https://github.com/openipc/qemu-hisilicon/blob/master/tools/oms_parser.py"
click node_femac "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/net/hisi-femac.c"
click node_gmac "https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/net/hisi-gmac.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_soc_config,node_machine_init,node_fastboot,node_fastboot_api,node_operator toneBlue
class node_flash,node_i2c,node_sensors,node_spi toneAmber
class node_ive,node_nnie,node_oms_builder,node_oms_parser toneMint
class node_femac,node_gmac toneRose
class node_firmware,node_linux toneIndigo
```

## Components

### Machine and Boot

- [SoC Configuration](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/include/hw/arm/hisilicon.h): `qemu/include/hw/arm/hisilicon.h`
- [Machine Setup](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/arm/hisilicon.c): `qemu/hw/arm/hisilicon.c`
- [Serial Fastboot](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/misc/hisi-fastboot.c): `qemu/hw/misc/hisi-fastboot.c`
- [Fastboot Interface](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/include/hw/misc/hisi-fastboot.h): `qemu/include/hw/misc/hisi-fastboot.h`

### SoC Peripherals

- [Flash Controllers](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/misc/hisi-fmc.c): `qemu/hw/misc/hisi-fmc.c`
- [I2C Controller](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/i2c/hisi-i2c.c): `qemu/hw/i2c/hisi-i2c.c`
- [I2C Sensors](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/i2c/hisi-imx385.c): `qemu/hw/i2c/hisi-imx385.c`
- [SPI Controller](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/ssi/hisi-spi.c): `qemu/hw/ssi/hisi-spi.c`

### IVE and Models

- [IVE Accelerator](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/misc/hisi-ive.c): `qemu/hw/misc/hisi-ive.c`
- [NNIE Accelerator](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/misc/hisi-nnie.c): `qemu/hw/misc/hisi-nnie.c`
- [OMS Builder](https://github.com/openipc/qemu-hisilicon/blob/master/tools/oms_builder.py): `tools/oms_builder.py`
- [OMS Parser](https://github.com/openipc/qemu-hisilicon/blob/master/tools/oms_parser.py): `tools/oms_parser.py`

### Networking

- [Fast Ethernet](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/net/hisi-femac.c): `qemu/hw/net/hisi-femac.c`
- [Gigabit Ethernet](https://github.com/openipc/qemu-hisilicon/blob/master/qemu/hw/net/hisi-gmac.c): `qemu/hw/net/hisi-gmac.c`

### Other components

- **QEMU User**
- **Guest Firmware**
- **Guest Linux**

## Connections

- QEMU User → Machine Setup: selects machine
- SoC Configuration → Machine Setup: configures (evidence: `qemu/hw/arm/hisilicon.c`)
- Guest Firmware → Machine Setup: boots on
- Machine Setup → Guest Linux: boots guest
- Machine Setup → Fastboot Interface: uses interface (evidence: `qemu/hw/arm/hisilicon.c`)
- Fastboot Interface → Serial Fastboot: configures (evidence: `qemu/hw/misc/hisi-fastboot.c`)
- QEMU User → Serial Fastboot: uploads firmware (evidence: `qemu/hw/misc/hisi-fastboot.c`)
- Machine Setup → Flash Controllers: models flash
- Machine Setup → I2C Controller: models I2C
- I2C Controller → I2C Sensors: drives sensor
- Machine Setup → SPI Controller: models SPI
- Machine Setup → IVE Accelerator: models IVE
- Machine Setup → NNIE Accelerator: models NPU
- OMS Builder → OMS Parser: uses parser (evidence: `tools/oms_builder.py`)
- Machine Setup → Fast Ethernet: models Ethernet
- Machine Setup → Gigabit Ethernet: models Ethernet
