TheRock/rocm-libraries/projects/rocblas/.github/copilot-instructions.md

GitHub Copilot Instructions for rocBLAS

Help Improve These Rules: If you notice these instructions don't match the codebase or could be clearer, suggest updates in your responses.

Project Overview

rocBLAS is the AMD ROCm Basic Linear Algebra Subprograms (BLAS) library, implemented in HIP and optimized for AMD GPUs. It provides highly optimized implementations of standard BLAS operations (Level 1, 2, and 3) with support for multiple data types and batched operations.

Code Style and Conventions

Naming

• Use snake_case for functions and variables (e.g., rocblas_gemm, matrix_size)
• Use SCREAMING_SNAKE_CASE for macros and constants
• Follow BLAS naming: rocblas_<precision><operation> (e.g., rocblas_sgemm, rocblas_daxpy)
• Precision prefixes: s=float, d=double, c=complex float, z=complex double, h=half, bf16=bfloat16

File Headers

Always include the MIT license header, replacing the end year with the current year:

/* ************************************************************************
 * Copyright (C) 2016-[CURRENT YEAR] 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 cop-
 * ies 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 IM-
 * PLIED, 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 CONNE-
 * CTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * ************************************************************************ */

Use #pragma once for header include guards.

Code Practices

• Use explicit type conversions with static_cast<>
• Always use braces for control flow statements
• Check return codes from rocBLAS API calls
• Never use hipMalloc/hipFree - use handle->device_malloc() for device memory (see Device Memory section below)
• Use other HIP functions as needed (hipMemcpy, hipStreamSynchronize, etc.)
• Follow const-correctness patterns

Device Memory Allocation

Critical: rocBLAS code must NOT call hipMalloc() or hipFree() directly because they are synchronizing APIs.

Use the rocBLAS device memory manager instead:

// Allocate device memory using RAII wrapper
auto w_mem = handle->device_malloc(dev_bytes);
if(!w_mem)
    return rocblas_status_memory_error;

// Use the memory
void* workspace = static_cast<void*>(w_mem);
// Memory automatically freed when w_mem goes out of scope

Key points:

• All device memory must be allocated upfront at the function level
• Use RAII pattern with rocblas_device_malloc for automatic cleanup
• Lower-level kernels receive pre-allocated memory from higher-level routines
• Use variable names like w_mem, workspace, or w_ prefix for clarity

Project Structure

• library/ - Core rocBLAS implementation
  • library/src/blas1/ - Vector-vector operations (O(n))
  • library/src/blas2/ - Matrix-vector operations (O(n²))
  • library/src/blas3/ - Matrix-matrix operations (O(n³)), includes Tensile
  • library/src/blas_ex/ - Extended precision and batched operations
• clients/ - Testing and benchmarking
  • clients/gtest/ - Google Test test suite
  • clients/benchmarks/ - Performance benchmarking tools
  • clients/samples/ - Example programs
• docs/ - Sphinx documentation
• scripts/ - Utility scripts for performance testing

Building and Testing

Build Commands (Linux)

./install.sh -d              # Install dependencies
./install.sh -c              # Build with clients
./install.sh -c --architecture auto  # Build for detected GPU only (faster)

Build Commands (Windows)

$env:HIP_PATH = "C:\Program Files\AMD\ROCm\<version>"  # Set HIP path
python rmake.py -d           # Install dependencies
python rmake.py -c           # Build with clients

Testing

python3 rtest.py -t smoke    # Quick smoke tests (5-10 min)
python3 rtest.py -t psdb     # Pre-submit tests (30-60 min)
python3 rtest.py -t osdb     # Nightly tests (1.5-2 hrs)

# Direct test execution
./build/release/clients/staging/rocblas-test --gtest_filter=*gemm*
./build/release/clients/staging/rocblas-bench -f gemm -r f32_r -m 4096

API Patterns

Standard BLAS API

rocblas_status rocblas_<precision><operation>(
    rocblas_handle handle,
    // operation-specific parameters
    const <type>* input_ptr,
    <type>* output_ptr);

Implementation Pattern (with device memory)

// _impl template: handles error checking, logging, memory allocation
template <typename API_INT, typename T>
rocblas_status rocblas_<operation>_impl(rocblas_handle handle, ...)
{
    // Argument error checking
    if(!handle) return rocblas_status_invalid_handle;
    
    // Logging
    log_trace(handle, ...);
    
    // Allocate device memory
    auto w_mem = handle->device_malloc(dev_bytes);
    if(!w_mem)
        return rocblas_status_memory_error;
    
    // Call launcher
    return rocblas_<operation>_launcher<API_INT, T>(..., w_mem);
}

// _launcher template: fast computation, no checking/allocation
template <typename API_INT, typename T>
rocblas_status rocblas_<operation>_launcher(..., void* workspace)
{
    // Launch kernels using pre-allocated workspace
    // No error checking, logging, or memory allocation
}

Example: GEMM

rocblas_status rocblas_sgemm(
    rocblas_handle handle,
    rocblas_operation transA,
    rocblas_operation transB,
    rocblas_int m, rocblas_int n, rocblas_int k,
    const float* alpha,
    const float* A, rocblas_int lda,
    const float* B, rocblas_int ldb,
    const float* beta,
    float* C, rocblas_int ldc);

Testing Patterns

Note: Tests use rocblas_gemm<T> as a test infrastructure wrapper. End users should call precision-specific functions directly: rocblas_sgemm, rocblas_dgemm, rocblas_cgemm, rocblas_zgemm, etc.

Test Structure

template <typename T>
void testing_gemm(const Arguments& arg)
{
    // Test wrapper that dispatches to precision-specific APIs
    auto rocblas_gemm_fn = rocblas_gemm<T>;
    
    rocblas_local_handle handle{arg};
    
    // Allocate memory using test infrastructure
    DEVICE_MEMCHECK(device_matrix<T>, dA, (m, k, lda));
    DEVICE_MEMCHECK(device_matrix<T>, dB, (k, n, ldb));
    DEVICE_MEMCHECK(device_matrix<T>, dC, (m, n, ldc));
    
    // Execute via test wrapper
    DAPI_CHECK(rocblas_gemm_fn, 
               (handle, transA, transB, m, n, k, &alpha, dA, lda, dB, ldb, &beta, dC, ldc));
}

TEST(gemm_gtest, float)
{
    Arguments arg;
    arg.M = 128; arg.N = 128; arg.K = 128;
    testing_gemm<float>(arg);
}

Test Categories

• *quick* - Fast tests for rapid iteration
• *pre_checkin* - PR validation tests
• *nightly* - Comprehensive regression tests
• *known_bug* - Known issues (excluded)

Important Notes

• Tensile Integration: GEMM operations use Tensile-generated kernels (build-time generation)
• Architecture Flag: Use --architecture auto for faster local builds
• Multi-Platform: Support Linux (primary) and Windows
• Data Types: Support float, double, complex, half, bfloat16, int8, int32
• Batched Operations: Many operations support batched and strided batched variants

Environment Variables

• ROCBLAS_LAYER=1 - Enable verbose logging
• ROCBLAS_CHECK_NUMERICS=4 - Enable numerical checks
• ROCBLAS_LAYER=4 - Enable profiling
• HIP_PATH - HIP SDK location (Windows)

Common Operations

BLAS Level 1 (Vector-Vector)

• axpy - y = alpha*x + y
• dot - dot product
• scal - x = alpha*x
• nrm2 - Euclidean norm

BLAS Level 2 (Matrix-Vector)

• gemv - matrix-vector multiply
• ger - outer product
• trmv - triangular matrix-vector multiply

BLAS Level 3 (Matrix-Matrix)

• gemm - general matrix multiply (most performance-critical)
• trmm - triangular matrix multiply
• symm - symmetric matrix multiply
• syrk - symmetric rank-k update

When Suggesting Code

1. Always include proper copyright headers
2. Follow snake_case naming conventions
3. Use appropriate BLAS naming (precision prefix + operation)
4. Include error checking for rocBLAS API calls
5. Use const-correctness for parameters
6. Use handle->device_malloc() for device memory - NEVER hipMalloc/hipFree
7. Follow _impl/_launcher pattern for functions needing device memory
8. Add tests in clients/gtest/ for new functionality
9. Consider all supported data types (s, d, c, z, h, bf16)
10. Document any new APIs in docs/reference/