Hierarchy#

2026-10-23

3 min read time

Applies to Linux and Windows

The hierarchy API provides abstractions for representing and querying levels in the HIP thread hierarchy (grid, block, warp, and thread levels). It enables compile-time and runtime queries of thread dimensions and counts across different hierarchy levels. See the HIP programming model for an introduction to the thread hierarchy.

Note

The API also defines a cluster level (cuda::cluster, cuda::cluster_dims) for thread block clusters. Thread block clusters are not supported on AMD GPUs: cluster dimensions are ignored when launching a kernel, so do not use the cluster level in libhipcxx code.

cuda::hierarchy#

cuda::hierarchy is a type representing a hierarchy of HIP threads. It combines hierarchy level descriptors to represent dimensions of a (possibly partial) hierarchy. It supports accessing individual levels and queries combining dimensions of multiple levels.

A hierarchy should be created using cuda::make_hierarchy rather than being constructed directly. The hierarchy type can be used by itself, but its main purpose is to be part of a kernel launch configuration described here: Launch. In that case, instead of calling cuda::make_hierarchy, the same arguments can be passed to cuda::make_config.

Availability: libhipcxx 3.4

Example:

#include <cuda/hierarchy>

auto h = cuda::make_hierarchy(
  cuda::grid_dims(256),
  cuda::block_dims<8, 8, 8>()
);

// Access level dimensions
assert(h.level(cuda::grid).dims.x == 256);

// Query counts across levels
static_assert(cuda::gpu_thread.count(cuda::block, h) == 8 * 8 * 8);

cuda::make_hierarchy#

cuda::make_hierarchy creates a hierarchy from passed hierarchy level descriptors. Levels can be passed in ascending or descending order, and the function will automatically order them correctly.

Availability: libhipcxx 3.4

Example:

#include <cuda/hierarchy>

// Levels can be passed in any order
auto h1 = cuda::make_hierarchy(
  cuda::grid_dims(256),
  cuda::block_dims<8, 8, 8>()
);

auto h2 = cuda::make_hierarchy(
  cuda::block_dims<8, 8, 8>(),
  cuda::grid_dims(256)
);

// Both create equivalent hierarchies
static_assert(cuda::std::is_same_v<decltype(h1), decltype(h2)>);

Hierarchy Level Descriptors#

The hierarchy API provides level descriptor functions for grid and block levels. Each level supports both compile-time and runtime dimensions:

  • cuda::grid_dims (compile-time and runtime overload forms)

  • cuda::block_dims (compile-time and runtime overload forms)

Warp and thread levels are implicit and are queried via level objects (e.g., cuda::warp, cuda::gpu_thread).

Availability: libhipcxx 3.4

Example:

#include <cuda/hierarchy>

auto h = cuda::make_hierarchy(
  cuda::grid_dims(256, 128),      // Runtime grid dimensions
  cuda::block_dims<32, 16>()      // Compile-time block dimensions
);

Hierarchy Queries#

Hierarchies support various query operations via level objects (cuda::grid, cuda::block, cuda::warp, cuda::gpu_thread):

  • unit.count(level, hierarchy) - Count units within a level (e.g., threads per block)

  • unit.rank(level, hierarchy) - Get the rank (linear index) of a unit within a level (device only)

  • unit.dims(level, hierarchy) - Get dimensions of units within a level

  • hierarchy.level<Level>() - Get the level descriptor for a specific level

  • hierarchy.fragment<Unit, Level>() - Extract a fragment of the hierarchy

Availability: libhipcxx 3.4

Example:

#include <cuda/hierarchy>

auto h = cuda::make_hierarchy(
  cuda::grid_dims(256),
  cuda::block_dims<8, 8, 8>()
);

// Get block-level descriptor
auto block_desc = h.level(cuda::block);
assert(block_desc.dims.x == 8);

// Count threads per block
static_assert(cuda::gpu_thread.count(cuda::block, h) == 512);

// Get fragment (block to grid)
auto fragment = h.fragment(cuda::block, cuda::grid);

cuda::hierarchy_add_level#

cuda::hierarchy_add_level returns a new hierarchy that is a copy of the supplied hierarchy with a new level added. The function automatically determines whether to add the level at the top or bottom based on the existing levels.

Availability: libhipcxx 3.4

Example:

#include <cuda/hierarchy>

auto partial = cuda::make_hierarchy<cuda::block_level>(
  cuda::grid_dims(256)
);

auto complete = cuda::hierarchy_add_level(
  partial,
  cuda::block_dims<8, 8, 8>()
);

cuda::get_launch_dimensions#

cuda::get_launch_dimensions returns a tuple of hierarchy_query_result objects containing dimensions from the hierarchy that can be used to launch kernels. For a hierarchy without a cluster level, the returned tuple has two elements (grid, block dimensions).

Availability: libhipcxx 3.4

Example:

#include <cuda/hierarchy>

auto h = cuda::make_hierarchy(
  cuda::grid_dims(256),
  cuda::block_dims<8, 8, 8>()
);

auto [grid_dims, block_dims] = cuda::get_launch_dimensions(h);
// Can be used with hipLaunchKernel or similar APIs