# oneapi-src/level-zero architecture

> Architecture diagram of the GitHub repository oneapi-src/level-zero, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oneapi-src/level-zero
- Repository: https://github.com/oneapi-src/level-zero

## Overview

Level Zero provides a C API for applications to discover devices and use compute, system-management, and tooling facilities through a loader that discovers drivers and dispatches API calls. Optional validation and tracing layers inspect or observe calls; drivers provide the device-specific implementation. The README identifies the API headers, loader, validation layer, and tracing layer as the repository’s main components. Layer-to-loader wiring is represented at a high level because the sampled excerpts do not show its complete setup.

Main entry points: [`source/loader/ze_loader_api.cpp`](https://github.com/oneapi-src/level-zero/blob/master/source/loader/ze_loader_api.cpp) (Loader API entry), [`source/loader/ze_ldrddi.cpp`](https://github.com/oneapi-src/level-zero/blob/master/source/loader/ze_ldrddi.cpp) (Loader dispatch), [`source/layers/validation/ze_validation_layer.cpp`](https://github.com/oneapi-src/level-zero/blob/master/source/layers/validation/ze_validation_layer.cpp) (Validation layer), [`source/loader/driver_discovery.h`](https://github.com/oneapi-src/level-zero/blob/master/source/loader/driver_discovery.h) (Driver discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_api_headers["Level Zero APIs<br/>[ze_api.h]"]
  node_sysman_api["System management API<br/>[zes_api.h]"]
  node_tools_api["Tools API<br/>[zet_api.h]"]
end

subgraph group_loader["Loader and dispatch"]
  node_loader_api["Loader API entry<br/>[ze_loader_api.cpp]"]
  node_discovery["Driver discovery<br/>[driver_discovery.h]"]
  node_loader_dispatch["Loader dispatch<br/>[ze_ldrddi.cpp]"]
  node_sysman_dispatch["Sysman dispatch<br/>[zes_ldrddi.cpp]"]
  node_tools_dispatch["Tools dispatch<br/>[zet_ldrddi.cpp]"]
end

subgraph group_layers["Runtime layers"]
  node_validation["Validation layer"]
  node_parameter_checks["Parameter checks"]
  node_lifetime_checks["Handle lifetime checks"]
  node_other_checkers["Runtime checkers"]
  node_tracing["Tracing layer"]
  node_tracer_callbacks["Tracer callbacks"]
end

subgraph group_drivers["Driver implementations"]
  node_device_driver["Device driver"]
  node_null_driver["Null driver<br/>[ze_null.cpp]"]
end

node_application(("Application"))

node_application -->|"uses API"| node_api_headers
node_application -->|"calls"| node_loader_api
node_loader_api -->|"discovers drivers"| node_discovery
node_loader_api -->|"dispatches calls"| node_loader_dispatch
node_loader_api -->|"dispatches Sysman"| node_sysman_dispatch
node_loader_api -->|"dispatches Tools"| node_tools_dispatch
node_loader_dispatch -->|"forwards calls"| node_device_driver
node_sysman_dispatch -->|"forwards calls"| node_device_driver
node_tools_dispatch -->|"forwards calls"| node_device_driver
node_discovery -->|"finds drivers"| node_device_driver
node_null_driver -.->|"example implementation"| node_device_driver
node_application -->|"uses Sysman"| node_sysman_api
node_application -->|"uses Tools"| node_tools_api
node_validation -->|"checks parameters"| node_parameter_checks
node_validation -->|"checks handles"| node_lifetime_checks
node_validation -->|"runs checkers"| node_other_checkers
node_tracing -->|"registers callbacks"| node_tracer_callbacks
node_loader_dispatch -.->|"may route through"| node_validation
node_loader_dispatch -.->|"may route through"| node_tracing

click node_api_headers "https://github.com/oneapi-src/level-zero/blob/master/include/ze_api.h"
click node_sysman_api "https://github.com/oneapi-src/level-zero/blob/master/include/zes_api.h"
click node_tools_api "https://github.com/oneapi-src/level-zero/blob/master/include/zet_api.h"
click node_loader_api "https://github.com/oneapi-src/level-zero/blob/master/source/loader/ze_loader_api.cpp"
click node_discovery "https://github.com/oneapi-src/level-zero/blob/master/source/loader/driver_discovery.h"
click node_loader_dispatch "https://github.com/oneapi-src/level-zero/blob/master/source/loader/ze_ldrddi.cpp"
click node_sysman_dispatch "https://github.com/oneapi-src/level-zero/blob/master/source/loader/zes_ldrddi.cpp"
click node_tools_dispatch "https://github.com/oneapi-src/level-zero/blob/master/source/loader/zet_ldrddi.cpp"
click node_validation "https://github.com/oneapi-src/level-zero/blob/master/source/layers/validation/ze_validation_layer.cpp"
click node_parameter_checks "https://github.com/oneapi-src/level-zero/blob/master/source/layers/validation/checkers/parameter_validation/ze_parameter_validation.cpp"
click node_lifetime_checks "https://github.com/oneapi-src/level-zero/blob/master/source/layers/validation/handle_lifetime_tracking/ze_handle_lifetime.cpp"
click node_other_checkers "https://github.com/oneapi-src/level-zero/tree/master/source/layers/validation/checkers"
click node_tracing "https://github.com/oneapi-src/level-zero/blob/master/source/layers/tracing/ze_tracing_layer.cpp"
click node_tracer_callbacks "https://github.com/oneapi-src/level-zero/blob/master/source/layers/tracing/ze_tracing_register_cb.cpp"
click node_null_driver "https://github.com/oneapi-src/level-zero/blob/master/source/drivers/null/ze_null.cpp"

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_api_headers,node_sysman_api,node_tools_api toneBlue
class node_loader_api,node_discovery,node_loader_dispatch,node_sysman_dispatch,node_tools_dispatch toneAmber
class node_validation,node_parameter_checks,node_lifetime_checks,node_other_checkers,node_tracing,node_tracer_callbacks toneMint
class node_device_driver,node_null_driver toneRose
class node_application toneIndigo
```

## Components

### API surface

- [Level Zero APIs](https://github.com/oneapi-src/level-zero/blob/master/include/ze_api.h): `include/ze_api.h`
- [System management API](https://github.com/oneapi-src/level-zero/blob/master/include/zes_api.h): `include/zes_api.h`
- [Tools API](https://github.com/oneapi-src/level-zero/blob/master/include/zet_api.h): `include/zet_api.h`

### Loader and dispatch

- [Loader API entry](https://github.com/oneapi-src/level-zero/blob/master/source/loader/ze_loader_api.cpp): `source/loader/ze_loader_api.cpp`
- [Driver discovery](https://github.com/oneapi-src/level-zero/blob/master/source/loader/driver_discovery.h): `source/loader/driver_discovery.h`
- [Loader dispatch](https://github.com/oneapi-src/level-zero/blob/master/source/loader/ze_ldrddi.cpp): `source/loader/ze_ldrddi.cpp`
- [Sysman dispatch](https://github.com/oneapi-src/level-zero/blob/master/source/loader/zes_ldrddi.cpp): `source/loader/zes_ldrddi.cpp`
- [Tools dispatch](https://github.com/oneapi-src/level-zero/blob/master/source/loader/zet_ldrddi.cpp): `source/loader/zet_ldrddi.cpp`

### Runtime layers

- [Validation layer](https://github.com/oneapi-src/level-zero/blob/master/source/layers/validation/ze_validation_layer.cpp): `source/layers/validation/ze_validation_layer.cpp`
- [Parameter checks](https://github.com/oneapi-src/level-zero/blob/master/source/layers/validation/checkers/parameter_validation/ze_parameter_validation.cpp): `source/layers/validation/checkers/parameter_validation/ze_parameter_validation.cpp`
- [Handle lifetime checks](https://github.com/oneapi-src/level-zero/blob/master/source/layers/validation/handle_lifetime_tracking/ze_handle_lifetime.cpp): `source/layers/validation/handle_lifetime_tracking/ze_handle_lifetime.cpp`
- [Runtime checkers](https://github.com/oneapi-src/level-zero/tree/master/source/layers/validation/checkers): `source/layers/validation/checkers`
- [Tracing layer](https://github.com/oneapi-src/level-zero/blob/master/source/layers/tracing/ze_tracing_layer.cpp): `source/layers/tracing/ze_tracing_layer.cpp`
- [Tracer callbacks](https://github.com/oneapi-src/level-zero/blob/master/source/layers/tracing/ze_tracing_register_cb.cpp): `source/layers/tracing/ze_tracing_register_cb.cpp`

### Driver implementations

- **Device driver**
- [Null driver](https://github.com/oneapi-src/level-zero/blob/master/source/drivers/null/ze_null.cpp): `source/drivers/null/ze_null.cpp`

### Other components

- **Application**

## Connections

- Application → Level Zero APIs: uses API
- Application → Loader API entry: calls
- Loader API entry → Driver discovery: discovers drivers
- Loader API entry → Loader dispatch: dispatches calls
- Loader API entry → Sysman dispatch: dispatches Sysman
- Loader API entry → Tools dispatch: dispatches Tools
- Loader dispatch → Device driver: forwards calls
- Sysman dispatch → Device driver: forwards calls
- Tools dispatch → Device driver: forwards calls
- Driver discovery → Device driver: finds drivers
- Null driver → Device driver: example implementation
- Application → System management API: uses Sysman
- Application → Tools API: uses Tools
- Validation layer → Parameter checks: checks parameters
- Validation layer → Handle lifetime checks: checks handles
- Validation layer → Runtime checkers: runs checkers
- Tracing layer → Tracer callbacks: registers callbacks
- Loader dispatch → Validation layer: may route through
- Loader dispatch → Tracing layer: may route through