Pipeline Creation Result#

The pipelining API creates host-side pipeline objects before launching kernels. Creation functions return an expected result so callers can handle recoverable validation and CUDA runtime failures without relying on assertions.

Creation Return Type#

Use suggest_pipeline to select the shared-memory layouts and (in its non-depth overload) a pipeline depth. Use make_pipeline when supplying an explicit depth and shared-memory layouts.

When constructing a pipeline with make_pipeline:

  • when BlocksPerCluster<M, N> is used, the shared-memory layouts of A and B must be either both generated by cuBLASDx (suggest_layout_smem_a() and suggest_layout_smem_b()) or both not (for example get_layout_smem_a() and get_layout_smem_b()); mixing them is rejected at compile time. Using this operator may make the blocks of a cluster divide the inputs between them, so a suggested layout can differ from the tile size implied by Size<>; that is why only layouts generated together are compatible. Without BlocksPerCluster<> suggested and non-suggested layouts may be mixed;

  • prefer suggest_pipeline over creating pipelines manually with make_pipeline.

On SM107, automatic depth selection normally uses a 227 KiB shared-memory budget. If one stage plus fixed storage (including a shared C tile, when supplied) exceeds that budget but fits below 327 KiB, it selects depth 1. For these launches, use cudaFuncSetAttribute to set cudaFuncAttributeSharedMemoryMode to cudaSharedMemoryModeAllowOversizedSharedMemory before setting cudaFuncAttributeMaxDynamicSharedMemorySize.

suggest_pipeline and make_pipeline return a non-movable cublasdx::detail::expected<host_pipeline, pipeline_error> object.

API

Meaning

if(pipeline) { ... }

Enters the success branch when a usable host pipeline was created.

if(not pipeline) { ... }

Enters the error branch when pipeline creation failed.

pipeline->buffer_alignment()

Required dynamic shared-memory alignment for the device pipeline storage.

pipeline->buffer_size()

Required dynamic shared-memory bytes for the device pipeline storage.

pipeline->get_block_dim()

CUDA block configuration expected by this pipeline.

pipeline->get_device_handle()

Device-side pipeline handle to pass by value to the kernel.

pipeline->get_cluster_dim()

Cluster dimension (dim3) for clustered launches; 1 x 1 x 1 when clustered execution is not active. A pipeline that reports clustered execution must be launched with this cluster dimension.

decltype(pipeline->get_device_handle())::uses_cluster

static constexpr bool of the pipeline type; true when the pipeline launches as a thread-block cluster. Read it from the type (as shown, or Pipeline::uses_cluster on the kernel-side handle type) so it can be used in if constexpr; expected::operator-> is not constexpr.

pipeline.error()

Returns cublasdx::pipeline_error when creation fails.

pipeline_error#

cublasdx::pipeline_error stores the cuBLASDx validation reason and, when applicable, a CUDA runtime status.


Diagram showing pipeline_error_code separately from CUDA runtime status in cublasdx::pipeline_error.

auto pipeline = cublasdx::suggest_pipeline<BLAS>(global_a, global_b);
if(not pipeline) {
    auto const& error = pipeline.error();
    if (error.code != cublasdx::pipeline_error_code::none) {
        std::cout << cublasdx::pipeline_error_string(error.code);
    }
    if (error.get_cuda_error() != cudaSuccess) {
        std::cout << cudaGetErrorString(error.get_cuda_error());
    }
}

Member

Meaning

pipeline_error::code

A cublasdx::pipeline_error_code value describing a cuBLASDx validation or allocation failure, cuda for a CUDA-only preprocessing failure, or unknown for an unclassified cuBLASDx failure.

pipeline_error::get_cuda_error()

CUDA runtime status associated with allocation or emulation preprocessing. In NVRTC builds this returns the stored integer status.

Emulation preprocessing can fail after cuBLASDx validation succeeds. In that case, code == pipeline_error_code::cuda and the CUDA runtime status is reported through get_cuda_error(). Always inspect both fields when reporting a pipeline creation failure.

pipeline_error_code#

Code

Meaning

none

No pipeline error code. A non-success CUDA status is normalized to cuda instead of none.

incompatible_k_dimensions

The A and B global tensors do not have the same K dimension.

tile_divisibility

The global M, N, or K dimension is not divisible by the BLAS tile size from Size<M, N, K>.

cluster_grid_divisibility

The global M/N tile grid is not an exact multiple of the active BlocksPerCluster<M, N> extents.

alignment_unfulfilled

The promise declared by the Alignment operator was not fulfilled by the actual A or B global tensors: the base pointer or a dynamic leading dimension is not a multiple of the effective alignment.

insufficient_stages

Retained for compatibility. Pipeline creation now allows fewer K tiles than the requested depth and does not return this code for that condition.

emulation_k_dimension_too_large

A flexible-precision emulation pipeline has K > 33025 which is the internal upper limit to avoid overflow. Emulation slices inputs to int8 and accumulates products of sliced 8-bit values in an internal int32 GEMM path; use split-K for larger emulation problems.

allocation_failed

Temporary stream-ordered device memory allocation (cudaMallocAsync / memory pool) for flexible-precision emulation failed. Check get_cuda_error() for the CUDA status.

unknown

Reserved fallback for an unclassified cuBLASDx failure.

cuda

CUDA runtime failure with no more specific cuBLASDx pipeline error code. Check get_cuda_error() for the CUDA status.

pipeline_error_string#

cublasdx::pipeline_error_string(code) returns a stable human-readable string for each pipeline_error_code value. It is intended for diagnostics and logging; programmatic handling should switch on pipeline_error_code directly.