TheRock/math-libs/libhipcxx/docs/overview.md

libhipcxx: The C++ Standard Library for Your Entire System

libhipcxx, is a HIP enabled C++ Standard Library for your entire system. It provides a heterogeneous implementation of the C++ Standard Library that can be used in and between CPU and GPU code.

Libhipcxx provides a compatible interface to the C++ Standard Library, so you only need to add hip/std to the start of your Standard Library include and cuda:: before any uses of std:::

#include <hip/hip_runtime.h>
#include <cuda/std/atomic>
cuda::std::atomic<int> x;

IMPORTANT: Please make sure to always include the header hip/hip_runtime.h before including any header from libhipcxx.

cuda:: and cuda::std::

When used with hipcc, libhipcxx facilities live in their own header hierarchy and namespace with the same structure as, but distinct from, the host compiler's Standard Library:

• std::/<*>: When using hipcc, this is your host compiler's Standard Library that works in __host__ code only. With hipcc, libhip++ does not replace or interfere with host compiler's Standard Library.
• cuda::std::/<cuda/std/*>: Strictly conforming implementations of facilities from the Standard Library that work in __host__ __device__ code.
• cuda::/<cuda/*>: Conforming extensions to the Standard Library that work in __host__ __device__ code.
• cuda::device/<cuda/device/*>: Conforming extensions to the Standard Library that work only in __device__ code.

// Standard C++, __host__ only.
#include <atomic>
std::atomic<int> x;

// HIP C++, __host__ __device__.
// Strictly conforming to the C++ Standard.
#include <cuda/std/atomic>
cuda::std::atomic<int> x;

// HIP C++, __host__ __device__.
// Conforming extensions to the C++ Standard.
#include <cuda/atomic>
cuda::atomic<int, cuda::thread_scope_block> x;

libhipcxx is Heterogeneous

libhipcxx works across your entire codebase, both in and across host and device code. libhipcxx is a C++ Standard Library for your entire system, not just your CPU or GPU. Everything in cuda:: is __host__ __device__.

libhipcxx facilities are designed to be passed between host and device code. Unless otherwise noted, any libhipcxx object which is copyable or movable can be copied or moved between host and device code.

cuda::device::

A small number of libhipcxx facilities only work in device code, usually because there is no sensible implementation in host code.

Such facilities live in cuda::device::.

libhipcxx is Incremental

Today, the libhipcxx delivers a high-priority subset of the C++ Standard Library today, and each release increases the feature set. But it is a subset; not everything is available today.

Conformance

libhipcxx aims to be a conforming implementation of the C++ Standard, [ISO/IEC IS 14882], Clause 16 through 32.

Requirements

• CMake >=3.12
• ROCm with HIP >=6.2.0
• AMD Architectures CDNA, CDNA2, CDNA3, RDNA2, RDNA3, RDNA4. See ROCm docs for more details about supported architectures. (NVIDIA GPUs are currently not supported)
• Linux OS (Windows is currently not supported)

For running the integrated LIT unit tests:

• Python 3
• pip (for installing lit)
• lit 18.1.8+
• sccache
• ninja

Build and Installation

It is assumed that the test dependencies have been installed (e.g., pip3 install lit==18.1.8 for the lit dependency). The following commands can be run from the root directory to configure libhipcxx, build it and run the unit tests:

1. Create build directory mkdir build && cd build
2. Run CMake to configure LIT testing cmake -DCMAKE_INSTALL_PREFIX=<path to install directory> ..
3. Compile all headers that are part of the library make
4. Install the headers locally: make install

Build with HIPRTC

If you would like to build libhipcxx with HIPRTC support, you can modify step 2 as follows:

• Run CMake with HIPRTC support enabled: cmake -DLIBHIPCXX_TEST_WITH_HIPRTC=ON -DCMAKE_INSTALL_PREFIX=<path-to-install-directory> ..

Optional: Creating Distribution Packages

Libhipcxx can be packaged using cpack:

1. Switch to the build directory cd build
2. Run CPack to generate packaged archives of libhipcxx: cpack .

Note: Per default, this will only generate TGZ, ZIP and DEB packages. You can generate other package formats, e.g., with:

cpack -G RPM .

Running the Tests

To run the tests on host and device based on LIT, you can use make check-hipcxx.

Alternatively, there is a helper script at utils/amd/linux/perform_tests.bash which can be used as follows:

1. Change directory to build directory: cd build
2. bash ../utils/amd/linux/perform_tests.bash

Please note the following regarding test behavior:

• If you pass the LIBHIPCXX_TEST_WITH_HIPRTC option to CMake, the tests will run with HIPRTC support enabled.
• If you do not pass this option, the tests will run without HIPRTC support.

For automated testing in continuous integration environments or when you need a predefined testing workflow, it is recommended to use the CI scripts provided in the ci directory. These scripts can run tests with both HIP and HIPRTC configurations.

Using CI Scripts for Automated Testing

1. Change directory to ci directory: cd ci
2. If you want to run tests without HIPRTC: bash ./test_libhipcxx.sh
3. If you want to run tests with HIPRTC: bash ./hiprtc_libhipcxx.sh

How to use libhipcxx in your CMake Project

Example CMakeLists.txt:

...
find_package(libhipcxx)
...
target_link_libraries(<your_target> PRIVATE libhipcxx::libhipcxx)

Make sure to set CMAKE_PREFIX_PATH when running CMake for your project, in case you installed libhipcxx in a non-default installation directory.

Limitations/Unsupported Features/APIs

• Libhipcxx does not support for CUDA backend/NVIDIA hardware.
• Libhipcxx does not support the Windows OS.
• cuda::std::chrono::system_clock::now() does not return a UNIX timestamp, host system clock and device system clock are not synchronized and they may run at different clock rates.
• The following APIs from libcudacxx are NOT supported in libhipcxx:

Group	API Header	Description
Synchronization Library	<cuda/std/latch>	Single-phase asynchronous thread-coordination mechanism
Synchronization Library	<cuda/std/barrier>	Multi-phase asynchronous thread-coordination mechanism
Synchronization Library	<cuda/std/semaphore>	Primitives for constraining concurrent access
Extended Synchronization Library	<cuda/latch>	System-wide cuda::std::latch single-phase asynchronous thread coordination mechanism.
Extended Synchronization Library	<cuda/barrier>	System-wide cuda::std::barrier multi-phase asynchronous thread coordination mechanism.
Extended Synchronization Library	<cuda/semaphore>	System-wide primitives for constraining concurrent access.
Extended Synchronization Library	<cuda/pipeline>	Coordination mechanisms to sequence asynchronous operations.
Extended Memory Access Properties Library	<cuda/annotated_ptr>	Memory access properties for pointers.

License

libhipcxx is an open source project. It is derived from libcudacxx and LLVM's libc++. The original libcudacxx and LLVM's libc++ are distributed under the Apache License v2.0 with LLVM Exceptions. Any new files and modifications made to exisiting files by AMD are distributed under MIT.