Add HIP-Basic execution context example

HIP-Basic/CMakeLists.txt

@@ -101,6 +101,7 @@ add_subdirectory(device_query)
 add_subdirectory(device_globals)
 add_subdirectory(dynamic_shared)
 add_subdirectory(events)
+add_subdirectory(execution_context)
 add_subdirectory(gpu_arch)
 add_subdirectory(hello_world)
 if(NOT CMAKE_SYSTEM_NAME MATCHES "Windows")

HIP-Basic/execution_context/.gitignore

@@ -0,0 +1 @@
+hip_execution_context

HIP-Basic/execution_context/CMakeLists.txt

@@ -0,0 +1,56 @@
+# MIT License
+#
+# Copyright (c) 2026 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+set(example_name hip_execution_context)
+
+cmake_minimum_required(VERSION 3.21 FATAL_ERROR)
+project(${example_name} LANGUAGES CXX)
+
+include("${CMAKE_CURRENT_LIST_DIR}/../../Common/HipPlatform.cmake")
+select_gpu_language()
+enable_language(${ROCM_EXAMPLES_GPU_LANGUAGE})
+select_hip_platform()
+
+set(CMAKE_${ROCM_EXAMPLES_GPU_LANGUAGE}_STANDARD 17)
+set(CMAKE_${ROCM_EXAMPLES_GPU_LANGUAGE}_EXTENSIONS OFF)
+set(CMAKE_${ROCM_EXAMPLES_GPU_LANGUAGE}_STANDARD_REQUIRED ON)
+
+include("${CMAKE_CURRENT_LIST_DIR}/../../Common/ROCmPath.cmake")
+
+add_executable(${example_name} main.hip)
+# Make example runnable using ctest
+add_test(NAME ${example_name} COMMAND ${example_name})
+set(include_dirs "../../Common" "../../External")
+if(ROCM_EXAMPLES_GPU_LANGUAGE STREQUAL "CUDA")
+    list(APPEND include_dirs "${ROCM_PATH}/include")
+endif()
+
+target_include_directories(${example_name} PRIVATE ${include_dirs})
+set_source_files_properties(main.hip PROPERTIES LANGUAGE ${ROCM_EXAMPLES_GPU_LANGUAGE})
+
+if(ROCM_EXAMPLES_GPU_LANGUAGE STREQUAL "CUDA")
+    # The CUDA green-context path uses the CUDA driver API, so link libcuda.
+    find_package(CUDAToolkit REQUIRED)
+    target_link_libraries(${example_name} PRIVATE CUDA::cuda_driver)
+endif()
+
+install(TARGETS ${example_name})

HIP-Basic/execution_context/Makefile

@@ -0,0 +1,65 @@
+# MIT License
+#
+# Copyright (c) 2026 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+EXAMPLE := hip_execution_context
+COMMON_INCLUDE_DIR := ../../Common
+GPU_RUNTIME ?= HIP
+
+# HIP variables
+ROCM_PATH ?= /opt/rocm
+HIP_INCLUDE_DIR  := $(ROCM_PATH)/include
+
+HIPCXX ?= $(ROCM_PATH)/bin/hipcc
+
+# Common variables and flags
+CXX_STD   := c++17
+ICXXFLAGS := -std=$(CXX_STD)
+ICPPFLAGS := -I $(COMMON_INCLUDE_DIR)
+ILDFLAGS  :=
+ILDLIBS   :=
+
+ifeq ($(GPU_RUNTIME), CUDA)
+  ICXXFLAGS += -x cu
+  ICPPFLAGS += -isystem $(HIP_INCLUDE_DIR)
+  # The CUDA green-context path uses the CUDA driver API, so link libcuda.
+  ILDLIBS   += -lcuda
+else ifeq ($(GPU_RUNTIME), HIP)
+  CXXFLAGS ?= -Wall -Wextra
+else
+  $(error GPU_RUNTIME is set to "$(GPU_RUNTIME)". GPU_RUNTIME must be either CUDA or HIP)
+endif
+
+ICXXFLAGS += $(CXXFLAGS)
+ICPPFLAGS += $(CPPFLAGS)
+ILDFLAGS  += $(LDFLAGS)
+ILDLIBS   += $(LDLIBS)
+
+$(EXAMPLE): main.hip $(COMMON_INCLUDE_DIR)/example_utils.hpp
+	$(HIPCXX) $(ICXXFLAGS) $(ICPPFLAGS) $(ILDFLAGS) -o $@ $< $(ILDLIBS)
+
+test: $(EXAMPLE)
+	./$(EXAMPLE) $(TEST_ARGS)
+
+clean:
+	$(RM) $(EXAMPLE)
+
+.PHONY: clean test

HIP-Basic/execution_context/README.md

@@ -0,0 +1,61 @@
+# HIP-Basic Execution Context Example
+
+## Description
+
+By default, kernels compete for all of a GPU's compute units (CUs), so a short kernel can be delayed behind a large one that already occupies the device. An execution context binds work to a fixed set of CUs: any kernel on a stream belonging to the context is confined to those CUs, and no kernel source changes are needed. This is HIP's counterpart to CUDA green contexts.
+
+This example runs a fixed latency-sensitive workload against a saturated device and sweeps how many CUs the workload gets to itself, so the effect of partitioning is visible as a trend. In every case a long-running background kernel is launched to occupy the device, and a shorter critical kernel is timed while the background kernel runs:
+
+1. **Baseline (shared CUs)**: the two kernels run on ordinary streams and compete for all of the device's CUs, so the critical kernel waits behind the background kernel.
+2. **Partitioned (own CUs)**: the CUs are split into two execution contexts, the background kernel is confined to the larger group, and the critical kernel runs on its own group. This is repeated for a few partition sizes (roughly an eighth, a quarter, and half of the device).
+
+The program prints a table with each configuration's critical- and background-kernel runtimes and the critical kernel's speedup over the baseline. As the critical partition grows, its runtime drops well below the contended baseline, while the background kernel (confined to fewer CUs) takes longer.
+
+HIP execution contexts map directly to CUDA green contexts. On the AMD (HIP) backend the example uses the HIP execution-context API; on the CUDA backend it uses the equivalent CUDA driver-API green-context calls (`cuGreenCtxCreate`, `cuDevSmResourceSplitByCount`, `cuGreenCtxStreamCreate`). The backend-specific code is selected with `__HIP_PLATFORM_AMD__`, and the baseline and sweep behave the same on both.
+
+### Application flow
+
+1. The device is selected with `hipSetDevice`.
+2. The number of compute units (SMs on NVIDIA) is determined from the device's SM resource: `hipDeviceGetDevResource` with `hipDevResourceTypeSm` on the HIP backend, or `cuDeviceGetDevResource` with `CU_DEV_RESOURCE_TYPE_SM` on the CUDA backend. (The field is named `smCount` for CUDA source compatibility; on AMD GPUs it represents compute units.)
+3. **Baseline.** Two ordinary non-blocking streams are created with `hipStreamCreateWithFlags`. The background kernel is launched on one, and the critical kernel is launched and timed on the other with HIP events while the background kernel runs. Both share all CUs.
+4. **Partitioned sweep.** For each candidate partition size, the SM resource is split into two disjoint groups - a group dedicated to the critical kernel and the remainder for the background kernel - with `hipDevSmResourceSplit` (HIP) or `cuDevSmResourceSplitByCount` (CUDA).
+5. A resource descriptor is generated for each group with `hipDevResourceGenerateDesc` / `cuDevResourceGenerateDesc`.
+6. An execution context (HIP) or green context (CUDA) is created from each descriptor with `hipGreenCtxCreate` / `cuGreenCtxCreate`.
+7. A stream is created on each context with `hipExecutionCtxStreamCreate` / `cuGreenCtxStreamCreate`, and the same background-plus-critical timing is repeated. The critical kernel runs on its own partitioned CUs. The contexts and streams are then destroyed before the next partition size.
+8. Each configuration's critical-kernel runtime and speedup over the baseline are printed as a row in the results table.
+9. The device output buffers are freed with `hipFree`.
+
+## Key APIs and Concepts
+
+Execution contexts carve a GPU's CUs into separate slices within one process, so urgent work has resources ready instead of waiting for a busy device to free up. Setting one up is a four-step sequence: read the device resources, split the CU resource, wrap the pieces in a descriptor, and create the context from it. A stream created on the context keeps every kernel launched on it inside that context's CUs. Sweeping the partition size while the background kernel saturates the device shows the critical kernel's latency fall as it gets more dedicated CUs.
+
+## Demonstrated API Calls
+
+### HIP runtime
+
+- `hipSetDevice`
+- `hipGetDeviceProperties`
+- `hipDeviceGetDevResource`
+- `hipDevResourceTypeSm`
+- `hipDevResource`
+- `hipDevSmResourceGroupParams`
+- `hipDevSmResourceSplit`
+- `hipDevResourceGenerateDesc`
+- `hipDevResourceDesc_t`
+- `hipGreenCtxCreate`
+- `hipExecutionCtx_t`
+- `hipExecutionCtxStreamCreate`
+- `hipExecutionCtxDestroy`
+- `hipStream_t`
+- `hipStreamCreateWithFlags`
+- `hipStreamSynchronize`
+- `hipStreamDestroy`
+- `hipDeviceSynchronize`
+- `hipMalloc`
+- `hipFree`
+- `hipEventCreate`
+- `hipEventRecord`
+- `hipEventSynchronize`
+- `hipEventElapsedTime`
+- `hipEventDestroy`
+- `hipGetLastError`