# intel/gmmlib architecture

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

- Interactive diagram: https://gitdiagram.com/intel/gmmlib
- Repository: https://github.com/intel/gmmlib

## Overview

#### Purpose and consumers
GmmLib is a C/C++ graphics-memory management library, built as `libigdgmm` for Intel’s OpenCL Compute Runtime and VAAPI Media Driver. It supplies GPU-platform-specific resource layout, allocation metadata, cache policy, tiling/swizzle, and translation-table management; it is not a standalone application.

#### Build and public entry boundary
CMake is the primary build entry point; Android also has a Blueprint entry. The library’s installed/public API is separated from implementation headers.
- `CMakeLists.txt`
- `Android.bp`
- `Source/GmmLib/CMakeLists.txt`
- `Source/GmmLib/inc/GmmLib.h`
- `Source/GmmLib/inc/External/Common/GmmResourceInfo.h`

Linux is the currently supported runtime target, including Linux-specific resource wrappers and package metadata.
- `Source/GmmLib/Linux.cmake`
- `Source/GmmLib/igdgmm.h.in`
- `Source/GmmLib/igdgmm.pc.in`

#### Context and platform dispatch
Clients create/use a GMM client context and global information layer, which identifies platform/SKU characteristics and selects generation-specific behavior. This is the main control boundary between stable external API objects and internal hardware implementations.
- `Source/GmmLib/GlobalInfo/GmmClientContext.cpp`
- `Source/GmmLib/GlobalInfo/GmmInfo.cpp`
- `Source/GmmLib/Platform/GmmPlatform.cpp`
- `Source/GmmLib/Platform/GmmPlatforms.h`

Per-generation platform implementations cover Gen8 through Gen12 in this tree; newer Xe-family specialization is visible primarily in cache-policy and texture paths.
- `Source/GmmLib/Platform/GmmGen8Platform.cpp`
- `Source/GmmLib/Platform/GmmGen12Platform.cpp`

#### Resource-description and layout pipeline
The primary data flow starts with client resource descriptors/flags, then computes restrictions, size/alignment, pitch, offsets, tiling, and associated metadata. `GmmResourceInfoCommon` centralizes generic behavior while platform texture calculators provide hardware-specific layout rules.
- `Source/GmmLib/Resource/GmmResourceInfo.cpp`
- `Source/GmmLib/Resource/GmmResourceInfoCommon.cpp`
- `Source/GmmLib/Resource/GmmRestrictions.cpp`
- `Source/GmmLib/Texture/GmmTexture.cpp`
- `Source/GmmLib/Texture/GmmTextureAlloc.cpp`

Generation-specific texture calculation is the key hardware boundary for surfaces.
- `Source/GmmLib/Texture/GmmGen12Texture.cpp`
- `Source/GmmLib/Texture/GmmXe_LPGTexture.cpp`
- `Source/GmmLib/inc/Internal/Common/Texture/GmmTextureCalc.h`

#### Cache-policy resolution
Resource usage and platform capabilities are translated into cacheability/memory-object-control policy. Common policy code is extended by separate implementations for Intel generations and Xe variants, so changes here can affect all client resource programming.
- `Source/GmmLib/CachePolicy/GmmCachePolicy.cpp`
- `Source/GmmLib/CachePolicy/GmmCachePolicyCommon.cpp`
- `Source/GmmLib/CachePolicy/GmmGen12CachePolicy.cpp`
- `Source/GmmLib/CachePolicy/GmmXe3P_XPCCachePolicy.cpp`

#### Address translation and auxiliary metadata
Translation-table components manage GPU virtual-address mappings and auxiliary/compression-related tables. They sit downstream of resource creation and expose page-table/auxiliary-table integration points to user-mode consumers.
- `Source/GmmLib/TranslationTable/GmmPageTableMgr.cpp`
- `Source/GmmLib/TranslationTable/GmmAuxTable.cpp`
- `Source/GmmLib/TranslationTable/GmmUmdTranslationTable.cpp`

#### OS integration, diagnostics, and validation
Linux exposes a C wrapper around resource information; CPU swizzle blits support CPU-side access/layout conversion. Diagnostics include assertion tracing and bundled `spdlog`; neither is the stable client ABI.
- `Source/GmmLib/Resource/Linux/GmmResourceInfoLinCWrapper.cpp`
- `Source/GmmLib/Utility/CpuSwizzleBlt/CpuSwizzleBlt.c`
- `Source/Common/AssertTracer/AssertTracer.cpp`
- `Source/GmmLib/Utility/GmmLog/GmmLog.cpp`

Unit-level tests compile with the library and cover resource, cache-policy, and translation behavior using vendored GoogleTest.
- `Source/GmmLib/ULT/CMakeLists.txt`
- `Source/GmmLib/ULT/GmmULT.cpp`

Main entry points: [`Source/GmmLib/Resource/GmmResourceInfoCommon.cpp`](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Resource/GmmResourceInfoCommon.cpp) (Resource info core), [`Source/GmmLib/Platform/GmmPlatform.cpp`](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Platform/GmmPlatform.cpp) (Platform dispatch), [`Source/GmmLib/inc/External/Common/GmmResourceInfo.h`](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/inc/External/Common/GmmResourceInfo.h) (Public resource API), [`Source/GmmLib/Texture/GmmTexture.cpp`](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Texture/GmmTexture.cpp) (Texture layout pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & Distribution"]
  node_cmake["CMake build<br/>build entry<br/>[CMakeLists.txt]"]
  node_android["Android Blueprint<br/>build entry<br/>[Android.bp]"]
  node_linux_package["Linux packaging<br/>target packaging<br/>[Linux.cmake]"]
end

subgraph group_api["Public Context &amp; Platform"]
  node_public_api["Public resource API<br/>installed C/C++ API<br/>[GmmResourceInfo.h]"]
  node_client_context["Client context<br/>context control"]
  node_global_info["Global platform info<br/>platform discovery<br/>[GmmInfo.cpp]"]
  node_platform_dispatch["Platform dispatch<br/>generation selector<br/>[GmmPlatform.cpp]"]
end

subgraph group_resource["Resource Layout &amp; Policy"]
  node_resource_info["Resource info core<br/>resource metadata"]
  node_restrictions["Resource restrictions<br/>layout constraints"]
  node_texture_layout["Texture layout pipeline<br/>surface layout<br/>[GmmTexture.cpp]"]
  node_gen_texture["Gen12/Xe texture rules<br/>hardware layout"]
  node_cache_policy["Cache policy core<br/>memory policy"]
  node_gen_cache_policy["Gen/Xe cache policy<br/>hardware policy"]
  node_translation_tables[("Translation tables")]
end

subgraph group_integration["Integration &amp; Support"]
  node_linux_wrapper["Linux resource wrapper<br/>C OS wrapper"]
  node_cpu_swizzle["CPU swizzle blit<br/>CPU layout conversion<br/>[CpuSwizzleBlt.c]"]
  node_diagnostics["Diagnostics<br/>logging and assertions<br/>[GmmLog.cpp]"]
end

node_consumers(("OpenCL Runtime &amp; VAAPI<br/>library consumers"))

node_cmake -->|"builds library API"| node_public_api
node_cmake -->|"Linux target"| node_linux_package
node_android -->|"builds"| node_public_api
node_consumers -->|"uses"| node_public_api
node_public_api -->|"creates and queries"| node_client_context
node_client_context -->|"initializes"| node_global_info
node_global_info -->|"identifies platform"| node_platform_dispatch
node_platform_dispatch -->|"configures behavior"| node_resource_info
node_platform_dispatch -->|"selects layout rules"| node_gen_texture
node_platform_dispatch -->|"selects policy rules"| node_gen_cache_policy
node_client_context -->|"creates resource metadata"| node_resource_info
node_resource_info -->|"applies constraints"| node_restrictions
node_resource_info -->|"computes layout"| node_texture_layout
node_restrictions -->|"constrains"| node_texture_layout
node_gen_texture -->|"provides hardware calculations"| node_texture_layout
node_resource_info -->|"resolves usage policy"| node_cache_policy
node_gen_cache_policy -->|"extends"| node_cache_policy
node_resource_info -->|"supplies allocation metadata"| node_translation_tables
node_linux_wrapper -->|"wraps for Linux C clients"| node_resource_info
node_cpu_swizzle -->|"converts CPU-visible layouts"| node_texture_layout
node_resource_info -.->|"reports diagnostics"| node_diagnostics

click node_cmake "https://github.com/intel/gmmlib/blob/master/CMakeLists.txt"
click node_android "https://github.com/intel/gmmlib/blob/master/Android.bp"
click node_linux_package "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Linux.cmake"
click node_public_api "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/inc/External/Common/GmmResourceInfo.h"
click node_client_context "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/GlobalInfo/GmmClientContext.cpp"
click node_global_info "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/GlobalInfo/GmmInfo.cpp"
click node_platform_dispatch "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Platform/GmmPlatform.cpp"
click node_resource_info "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Resource/GmmResourceInfoCommon.cpp"
click node_restrictions "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Resource/GmmRestrictions.cpp"
click node_texture_layout "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Texture/GmmTexture.cpp"
click node_gen_texture "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Texture/GmmGen12Texture.cpp"
click node_cache_policy "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/CachePolicy/GmmCachePolicyCommon.cpp"
click node_gen_cache_policy "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/CachePolicy/GmmGen12CachePolicy.cpp"
click node_translation_tables "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/TranslationTable/GmmUmdTranslationTable.cpp"
click node_linux_wrapper "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Resource/Linux/GmmResourceInfoLinCWrapper.cpp"
click node_cpu_swizzle "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Utility/CpuSwizzleBlt/CpuSwizzleBlt.c"
click node_diagnostics "https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Utility/GmmLog/GmmLog.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_cmake,node_android,node_linux_package toneBlue
class node_public_api,node_client_context,node_global_info,node_platform_dispatch toneAmber
class node_resource_info,node_restrictions,node_texture_layout,node_gen_texture,node_cache_policy,node_gen_cache_policy,node_translation_tables toneMint
class node_linux_wrapper,node_cpu_swizzle,node_diagnostics toneRose
class node_consumers toneNeutral
```

## Components

### Build & Distribution

- [CMake build](https://github.com/intel/gmmlib/blob/master/CMakeLists.txt): build entry · Primary build for libigdgmm. · `CMakeLists.txt`
- [Android Blueprint](https://github.com/intel/gmmlib/blob/master/Android.bp): build entry · `Android.bp`
- [Linux packaging](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Linux.cmake): target packaging · `Source/GmmLib/Linux.cmake`

### Public Context & Platform

- [Public resource API](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/inc/External/Common/GmmResourceInfo.h): installed C/C++ API · Stable resource-information interface for runtime clients. · `Source/GmmLib/inc/External/Common/GmmResourceInfo.h`
- [Client context](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/GlobalInfo/GmmClientContext.cpp): context control · Connects external API usage to platform-specific internals. · `Source/GmmLib/GlobalInfo/GmmClientContext.cpp`
- [Global platform info](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/GlobalInfo/GmmInfo.cpp): platform discovery · `Source/GmmLib/GlobalInfo/GmmInfo.cpp`
- [Platform dispatch](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Platform/GmmPlatform.cpp): generation selector · Selects SKU and GPU-generation behavior. · `Source/GmmLib/Platform/GmmPlatform.cpp`

### Resource Layout & Policy

- [Resource info core](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Resource/GmmResourceInfoCommon.cpp): resource metadata · Owns generic resource layout and allocation metadata behavior. · `Source/GmmLib/Resource/GmmResourceInfoCommon.cpp`
- [Resource restrictions](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Resource/GmmRestrictions.cpp): layout constraints · `Source/GmmLib/Resource/GmmRestrictions.cpp`
- [Texture layout pipeline](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Texture/GmmTexture.cpp): surface layout · Calculates size, alignment, pitch, offsets, tiling, and metadata. · `Source/GmmLib/Texture/GmmTexture.cpp`
- [Gen12/Xe texture rules](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Texture/GmmGen12Texture.cpp): hardware layout · Generation-specific surface calculation boundary. · `Source/GmmLib/Texture/GmmGen12Texture.cpp`
- [Cache policy core](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/CachePolicy/GmmCachePolicyCommon.cpp): memory policy · Resolves usage and capabilities into cacheability policy. · `Source/GmmLib/CachePolicy/GmmCachePolicyCommon.cpp`
- [Gen/Xe cache policy](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/CachePolicy/GmmGen12CachePolicy.cpp): hardware policy · `Source/GmmLib/CachePolicy/GmmGen12CachePolicy.cpp`
- [Translation tables](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/TranslationTable/GmmUmdTranslationTable.cpp): GPU VA and aux tables · Manages page-table mappings and auxiliary-table integration. · `Source/GmmLib/TranslationTable/GmmUmdTranslationTable.cpp`

### Integration & Support

- [Linux resource wrapper](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Resource/Linux/GmmResourceInfoLinCWrapper.cpp): C OS wrapper · `Source/GmmLib/Resource/Linux/GmmResourceInfoLinCWrapper.cpp`
- [CPU swizzle blit](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Utility/CpuSwizzleBlt/CpuSwizzleBlt.c): CPU layout conversion · `Source/GmmLib/Utility/CpuSwizzleBlt/CpuSwizzleBlt.c`
- [Diagnostics](https://github.com/intel/gmmlib/blob/master/Source/GmmLib/Utility/GmmLog/GmmLog.cpp): logging and assertions · Internal tracing and logging, outside the stable ABI. · `Source/GmmLib/Utility/GmmLog/GmmLog.cpp`

### Other components

- **OpenCL Runtime & VAAPI**: library consumers · User-mode clients link against libigdgmm.

## Connections

- CMake build → Public resource API: builds library API
- CMake build → Linux packaging: Linux target
- Android Blueprint → Public resource API: builds
- OpenCL Runtime & VAAPI → Public resource API: uses
- Public resource API → Client context: creates and queries
- Client context → Global platform info: initializes
- Global platform info → Platform dispatch: identifies platform
- Platform dispatch → Resource info core: configures behavior
- Platform dispatch → Gen12/Xe texture rules: selects layout rules
- Platform dispatch → Gen/Xe cache policy: selects policy rules
- Client context → Resource info core: creates resource metadata
- Resource info core → Resource restrictions: applies constraints
- Resource info core → Texture layout pipeline: computes layout
- Resource restrictions → Texture layout pipeline: constrains
- Gen12/Xe texture rules → Texture layout pipeline: provides hardware calculations
- Resource info core → Cache policy core: resolves usage policy
- Gen/Xe cache policy → Cache policy core: extends
- Resource info core → Translation tables: supplies allocation metadata
- Linux resource wrapper → Resource info core: wraps for Linux C clients
- CPU swizzle blit → Texture layout pipeline: converts CPU-visible layouts
- Resource info core → Diagnostics: reports diagnostics