148 lines · plain
1.. _libc_gpu_testing:2 3 4=========================5Testing the GPU C library6=========================7 8.. note::9 Running GPU tests with high parallelism is likely to cause spurious failures,10 out of resource errors, or indefinite hangs. limiting the number of threads11 used while testing using ``LIBC_GPU_TEST_JOBS=<N>`` is highly recommended.12 13.. contents:: Table of Contents14 :depth: 415 :local:16 17Testing infrastructure18======================19 20The LLVM C library supports different kinds of :ref:`tests <build_and_test>`21depending on the build configuration. The GPU target is considered a full build22and therefore provides all of its own utilities to build and run the generated23tests. Currently the GPU supports two kinds of tests.24 25#. **Hermetic tests** - These are unit tests built with a test suite similar to26 Google's ``gtest`` infrastructure. These use the same infrastructure as unit27 tests except that the entire environment is self-hosted. This allows us to28 run them on the GPU using our custom utilities. These are used to test the29 majority of functional implementations.30 31#. **Integration tests** - These are lightweight tests that simply call a32 ``main`` function and checks if it returns non-zero. These are primarily used33 to test interfaces that are sensitive to threading.34 35The GPU uses the same testing infrastructure as the other supported ``libc``36targets. We do this by treating the GPU as a standard hosted environment capable37of launching a ``main`` function. Effectively, this means building our own38startup libraries and loader.39 40Testing utilities41=================42 43We provide two utilities to execute arbitrary programs on the GPU. That is the44``loader`` and the ``start`` object.45 46Startup object47--------------48 49This object mimics the standard object used by existing C library50implementations. Its job is to perform the necessary setup prior to calling the51``main`` function. In the GPU case, this means exporting GPU kernels that will52perform the necessary operations. Here we use ``_begin`` and ``_end`` to handle53calling global constructors and destructors while ``_start`` begins the standard54execution. The following code block shows the implementation for AMDGPU55architectures.56 57.. code-block:: c++58 59 extern "C" [[gnu::visibility("protected"), clang::amdgpu_kernel]] void60 _begin(int argc, char **argv, char **env) {61 LIBC_NAMESPACE::atexit(&LIBC_NAMESPACE::call_fini_array_callbacks);62 LIBC_NAMESPACE::call_init_array_callbacks(argc, argv, env);63 }64 65 extern "C" [[gnu::visibility("protected"), clang::amdgpu_kernel]] void66 _start(int argc, char **argv, char **envp, int *ret) {67 __atomic_fetch_or(ret, main(argc, argv, envp), __ATOMIC_RELAXED);68 }69 70 extern "C" [[gnu::visibility("protected"), clang::amdgpu_kernel]] void71 _end(int retval) {72 LIBC_NAMESPACE::exit(retval);73 }74 75Loader runtime76--------------77 78The startup object provides a GPU executable with callable kernels for the79respective runtime. We can then define a minimal runtime that will launch these80kernels on the given device. Currently we provide the ``amdhsa-loader`` and81``nvptx-loader`` targeting the AMD HSA runtime and CUDA driver runtime82respectively. By default these will launch with a single thread on the GPU.83 84.. code-block:: sh85 86 $> clang++ crt1.o test.cpp --target=amdgcn-amd-amdhsa -mcpu=native -flto87 $> amdhsa_loader --threads 1 --blocks 1 ./a.out88 Test Passed!89 90The loader utility will forward any arguments passed after the executable image91to the program on the GPU as well as any set environment variables. The number92of threads and blocks to be set can be controlled with ``--threads`` and93``--blocks``. These also accept additional ``x``, ``y``, ``z`` variants for94multidimensional grids.95 96Running tests97=============98 99Tests will only be built and run if a GPU target architecture is set and the100corresponding loader utility was built. These can be overridden with the101``LIBC_GPU_TEST_ARCHITECTURE`` and ``LIBC_GPU_LOADER_EXECUTABLE`` :ref:`CMake102options <gpu_cmake_options>`. Once built, they can be run like any other tests.103The CMake target depends on how the library was built.104 105#. **Cross build** - If the C library was built using ``LLVM_ENABLE_PROJECTS``106 or a runtimes cross build, then the standard targets will be present in the107 base CMake build directory.108 109 #. All tests - You can run all supported tests with the command:110 111 .. code-block:: sh112 113 $> ninja check-libc114 115 #. Hermetic tests - You can run hermetic with tests the command:116 117 .. code-block:: sh118 119 $> ninja libc-hermetic-tests120 121 #. Integration tests - You can run integration tests by the command:122 123 .. code-block:: sh124 125 $> ninja libc-integration-tests126 127#. **Runtimes build** - If the library was built using ``LLVM_ENABLE_RUNTIMES``128 then the actual ``libc`` build will be in a separate directory.129 130 #. All tests - You can run all supported tests with the command:131 132 .. code-block:: sh133 134 $> ninja check-libc-amdgcn-amd-amdhsa135 $> ninja check-libc-nvptx64-nvidia-cuda136 137 #. Specific tests - You can use the same targets as above by entering the138 runtimes build directory.139 140 .. code-block:: sh141 142 $> ninja -C runtimes/runtimes-amdgcn-amd-amdhsa-bins check-libc143 $> ninja -C runtimes/runtimes-nvptx64-nvidia-cuda-bins check-libc144 $> cd runtimes/runtimes-amdgcn-amd-amdhsa-bins && ninja check-libc145 $> cd runtimes/runtimes-nvptx64-nvidia-cuda-bins && ninja check-libc146 147Tests can also be built and run manually using the respective loader utility.148