Build Config	Build Status
GN/Clang
CMake/MSVC

GPGMM is a General-Purpose GPU Memory Management C++ library used by GPU applications/runtimes that use modern graphics and compute APIs (D3D12 or Vulkan) that allow low-level memory management. GPGMM is a fast, multi-threaded, full-fledged GPU Memory Manager (GMM) implementation that replaces what older graphics and compute APIs (D3D11 or OpenGL) had accomplished through the GPU driver.

• API Documentation
• Changelog
• License
• Design Doc

• Error handing uses GPU API error codes (HRESULT and VkResult for D3D12 and Vulkan, respectively).

First create an allocator then create allocations from it:

#include <gpgmm_d3d12.h>

// Required
gpgmm::d3d12::ALLOCATOR_DESC allocatorDesc = {};
allocatorDesc.Device = Device;
allocatorDesc.Adapter = Adapter;

// Use CheckFeatureSupport
allocatorDesc.ResourceHeapTier = D3D12_RESOURCE_HEAP_TIER_1;

ComPtr<gpgmm::d3d12::IResidencyManager> residency; // Optional
ComPtr<gpgmm::d3d12::IResourceAllocator> allocator;
gpgmm::d3d12::CreateResourceAllocator(desc, &allocator, &residency);

D3D12_RESOURCE_DESC& resourceDesc = {};
D3D12_RESOURCE_STATES initialState = {}
gpgmm::d3d12::ALLOCATION_DESC allocationDesc = {};

ComPtr<gpgmm::d3d12::IResourceAllocation> allocation;
allocator->CreateResource(allocationDesc, resourceDesc, initialState, nullptr, &allocation);

GPUs do not support page-faulting, so it's up the GPU application to avoid using too much physical GPU memory. GPGMM integrates residency into the resource allocators to simplify and optimize allocation:

ComPtr<gpgmm::d3d12::IResidencyList> list;
CreateResidencyList(&list);
list->Add(allocation->GetMemory());

residency->ExecuteCommandList(&queue, &commandList, &list, 1);

// Prepare for next frame.
list->Reset();

Residency also works for non-resources too:

gpgmm::d3d12::HEAP_DESC shaderVisibleHeap = {};
shaderVisibleHeap.SizeInBytes = kHeapSize;
shaderVisibleHeap.MemorySegmentGroup = DXGI_MEMORY_SEGMENT_GROUP_LOCAL;

ComPtr<gpgmm::d3d12::IHeap> descriptorHeap;
gpgmm::d3d12::CreateHeap(shaderVisibleHeap, residencyManager,
  [&](ID3D12Pageable** ppPageableOut) -> HRESULT {
      ComPtr<ID3D12DescriptorHeap> heap;
      mDevice->CreateDescriptorHeap(&heapDesc, IID_PPV_ARGS(&heap));
      *ppPageableOut = heap.Detach();
      return S_OK;
}, &descriptorHeap);

// Shader-visible heaps should be locked or always resident.
residency->LockHeap(descriptorHeap.get());

To clean-up, simply call Release() once the is GPU is finished.

#include <gpgmm_vk.h>

gpgmm::vk::GpAllocatorCreateInfo allocatorInfo = {};

gpgmm::vk::GpResourceAllocator resourceAllocator;
gpgmm::vk::gpCreateResourceAllocator(allocatorInfo, &resourceAllocator)

VkBufferCreateInfo bufferInfo = {};
VkBuffer buffer;

gpgmm::vk::GpResourceAllocation allocation;
gpgmm::vk::GpResourceAllocationCreateInfo allocationInfo = {};

gpgmm::vk::gpCreateBuffer(resourceAllocator, &bufferInfo, &buffer, &allocationInfo, &allocation)

Then to clean-up:

gpgmm::vk::gpDestroyBuffer(resourceAllocator, buffer, allocation); // Make sure GPU is finished!
gpgmm::vk::gpDestroyResourceAllocator(resourceAllocator);

It is recommended to use the built-in GN or CMake build targets. Otherwise, a shared library can be used for other build systems.

Allows GPGMM to be added as a source-package dependency to an existing build system.

BUILD.gn

source_set("proj") {
  deps = [ "${gpgmm_dir}:src/gpgmm" ]
}

Create build_overrides/gpgmm.gni file in root directory.

To build with a backend, add the corresponding argument from following table in ``build_overrides/gpgmm.gni`:

CMakeLists.txt

Using CMake 3.14 or newer:

include(FetchContent)
FetchContent_Declare(gpgmm
  GIT_REPOSITORY https://github.com/intel/gpgmm.git
  GIT_TAG main
)

# Specify GPGMM build options (see below).
...

FetchContent_MakeAvailable(gpgmm)

Or alternatively, manually fetch:

git clone https://github.com/intel/gpgmm.git third_party/gpgmm

And make available:

add_subdirectory(third_party/gpgmm)
...

# Specify GPGMM build options (see below).
...

Then add:

target_link_libraries(proj PRIVATE gpgmm)

Allows GPGMM to be built as a library-binary then linked as build-dependency.

First install vcpkg then run install gpgmm.

vcpkg install gpgmm

Use is_clang=false gpgmm_shared_library=true when Setting up the build. Then use ninja -C out/Release gpgmm or ninja -C out/Debug gpgmm to build the shared library.

cmake -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Debug .
cmake --build . --config Debug

1. Copy the DLL into the $(OutputPath) folder and configure the VS build:
2. Highlight project in the Solution Explorer, and then select Project > Properties.
3. Under Configuration Properties > C/C++ > General, add gpgmm\include to Additional Include Directories.
4. Under Configuration Properties > Linker > Input, add gpgmm.dll.lib to Additional Dependencies.
5. Under Configuration Properties > Linker > General, add the folder path to out\Release to Additional Library Directories.

Building GPGMM for development.

GPGMM uses the Chromium build system and dependency management so you need to install depot_tools and add it to the PATH.

Notes:

• On Windows, you'll need to set the environment variable DEPOT_TOOLS_WIN_TOOLCHAIN=0. This tells depot_tools to use your locally installed version of Visual Studio (by default, depot_tools will try to download a Google-internal version).

Get the source code as follows:

# Clone the repo as "GPGMM"
> git clone https://github.com/intel/GPGMM.git GPGMM && cd GPGMM

# Bootstrap the gclient configuration
> cp scripts/standalone.gclient .gclient

# Fetch external dependencies and toolchains with gclient
> gclient sync

Generate build files using gn args out/Debug or gn args out/Release.

A text editor will appear asking build arguments, the most common argument is is_debug=true/false; otherwise gn args out/Release --list shows all the possible options.

Then use ninja -C out/Release or ninja -C out/Debug to build.

GPGMM uses CMake 3.14 or higher for the build system and dependency management, so you need to install cmake and add it to the PATH.

Generate build files using cmake . -DCMAKE_BUILD_TYPE=Debug or cmake . -DCMAKE_BUILD_TYPE=Release.

To build with a backend, please specify the corresponding argument from following table.

For example, adding -DGPGMM_ENABLE_VK=OFF builds without Vulkan.

Additional build options further configure GPGMM:

For example, adding -dGPGMM_STANDALONE=OFF, and -dBUILD_SHARED_LIBS builds GPGMM as a shared DLL.

Notes: CMake 3.14 or higher is required for GPGMM_ENABLE_TESTS or GPGMM_ENABLE_VK.

The following build options are only available when GPGMM_ENABLE_VK=ON:

For example, adding -dGPGMM_ENABLE_VK_STATIC_FUNCTIONS=ON will use Vulkan by statically linking functions (from the built-in Vulkan Loader).

cmake --build .

• Unit tests check the front-end code in isolation or without a GPU.
• End2End tests check both the front AND backend code with a GPU.
• Capture replay checks using pre-recorded memory patterns with a GPU.
• Fuzzer checks using random memory patterns with a GPU.

> cd out/Debug # or out/Release

> gpgmm_unittests

> gpgmm_end2end_tests

> gpgmm_capture_replay_tests

To re-generate the capture:

gpgmm_capture_replay_tests.exe --gtest_filter=*Replay/* --event-mask=0x3 --disable-memory-playback

> gpgmm_*_fuzzer  -max_total_time=<seconds_to_run>

> cd Debug # or Release

> cmake --build . --target RUN_TESTS

Apache 2.0 Public License, please see LICENSE.