ROCM.ECLASS

Section: eclass-manpages (5)
Updated: Oct 2024
Index Return to Main Contents

NAME

rocm.eclass - Common functions and variables for ROCm packages written in HIP

DESCRIPTION

ROCm packages such as sci-libs/<roc|hip>*, and packages built on top of ROCm libraries, can utilize variables and functions provided by this eclass. It handles the AMDGPU_TARGETS variable via USE_EXPAND, so user can edit USE flag to control which GPU architecture to compile. Using ${ROCM_USEDEP} can ensure coherence among dependencies. Ebuilds can call the function get_amdgpu_flag to translate activated target to GPU compile flags, passing it to configuration. Function rocm_use_hipcc switches active compiler to hipcc and cleans incompatible flags (useful for users with gcc-only flags in /etc/portage/make.conf). Function check_amdgpu can help ebuild ensure read and write permissions to GPU device in src_test phase, throwing friendly error message if unavailable. However src_configure in general should not access any AMDGPU devices. If it does, it usually means that CMakeLists.txt ignores AMDGPU_TARGETS in favor of autodetected GPU, which is not desired.

SUPPORTED EAPIS

EXAMPLE

Example ebuild for ROCm library in https://github.com/ROCmSoftwarePlatform which uses cmake to build and test, and depends on rocBLAS:

ROCM_VERSION=${PV}
inherit cmake rocm
# ROCm libraries SRC_URI is usually in form of:
SRC_URI="https://github.com/ROCmSoftwarePlatform/${PN}/archive/rocm-${PV}.tar.gz -> ${P}.tar.gz"
S=${WORKDIR}/${PN}-rocm-${PV}
SLOT="0/$(ver_cut 1-2)"
IUSE="test"
REQUIRED_USE="${ROCM_REQUIRED_USE}"
RESTRICT="!test? ( test )"

RDEPEND="
    dev-util/hip
    sci-libs/rocBLAS:${SLOT}[${ROCM_USEDEP}]
"

src_configure() {
    rocm_use_hipcc
    local mycmakeargs=(
        -DAMDGPU_TARGETS="$(get_amdgpu_flags)"
        -DBUILD_CLIENTS_TESTS=$(usex test ON OFF)
    )
    cmake_src_configure
}

src_test() {
    check_amdgpu
    # export LD_LIBRARY_PATH=<path to built lib dir> if necessary
    cmake_src_test # for packages using the cmake test
    # For packages using a standalone test binary rather than cmake test,
    # just execute it (or using edob)
}

Examples for packages depend on ROCm libraries -- a package which depends on rocBLAS, uses comma separated ${HCC_AMDGPU_TARGET} to determine GPU architectures, and requires ROCm version >=5.1

ROCM_VERSION=5.1
inherit rocm
IUSE="rocm"
REQUIRED_USE="rocm? ( ${ROCM_REQUIRED_USE} )"
DEPEND="rocm? ( >=dev-util/hip-${ROCM_VERSION}
    >=sci-libs/rocBLAS-${ROCM_VERSION}[${ROCM_USEDEP}] )"

src_configure() {
    if use rocm; then
        local amdgpu_flags=$(get_amdgpu_flags)
        export HCC_AMDGPU_TARGET=${amdgpu_flags//;/,}
    fi
    default
}
src_test() {
    use rocm && check_amdgpu
    default
}

FUNCTIONS

_rocm_set_globals: Set global variables useful to ebuilds: IUSE, ROCM_REQUIRED_USE, and ROCM_USEDEP, unless ROCM_SKIP_GLOBALS is set.
get_amdgpu_flags get_amdgpu_flags: Convert specified use flag of amdgpu_targets to compilation flags. Append default target feature to GPU arch. See https://llvm.org/docs/AMDGPUUsage.html#target-features
check_amdgpu check_amdgpu: grant and check read-write permissions on AMDGPU devices, die if not available.
rocm_use_hipcc rocm_use_hipcc: switch active C and C++ compilers to hipcc, clean unsupported flags and setup ROCM_TARGET_LST file.

ECLASS VARIABLES

ROCM_VERSION (REQUIRED) (SET BEFORE INHERIT)

The ROCm version of current package. For ROCm libraries, it should be ${PV}; for other packages that depend on ROCm libraries, this can be set to match the version required for ROCm libraries.

ROCM_REQUIRED_USE (GENERATED BY ECLASS)

Requires at least one AMDGPU target to be compiled. Example use for ROCm libraries:

REQUIRED_USE="${ROCM_REQUIRED_USE}"

Example use for packages that depend on ROCm libraries:

IUSE="rocm"
REQUIRED_USE="rocm? ( ${ROCM_REQUIRED_USE} )"

ROCM_USEDEP (GENERATED BY ECLASS)

This is an eclass-generated USE-dependency string which can be used to depend on another ROCm package being built for the same AMDGPU architecture.

The generated USE-flag list is compatible with packages using rocm.eclass.

Example use:

DEPEND="sci-libs/rocBLAS[${ROCM_USEDEP}]"

ROCM_SKIP_GLOBALS

Controls whether _rocm_set_globals() is executed. This variable is for ebuilds that call check_amdgpu() without the need to define amdgpu_targets_* USE-flags, such as dev-util/hip and dev-libs/rocm-opencl-runtime.

Example use:

ROCM_SKIP_GLOBALS=1
inherit rocm

AUTHORS

Yiyang Wu <xgreenlandforwyy@gmail.com>

MAINTAINERS

Gentoo Science Project <sci@gentoo.org>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

rocm.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:01 GMT, October 07, 2024