Using hipFORT in your application

Using hipFORT in your application#

The following topic provides instructions and tips for using hipFORT.

Fortran interfaces#

hipFORT provides interfaces to the HIP runtime and to the ROCm libraries:

  • HIP runtime and tooling:

    • HIP runtime

    • ROCTx

  • ROCm math libraries (roc*):

    • rocBLAS

    • rocFFT

    • rocRAND

    • rocSOLVER

    • rocSPARSE

  • HIP math libraries (hip*), whose APIs follow their NVIDIA counterparts:

    • hipBLAS

    • hipFFT

    • hipRAND

    • hipSOLVER

    • hipSPARSE

  • FFTW3-compatible interface:

    • hipFFTW, whose routine names, planner flags, and calling sequence follow FFTW3 rather than an NVIDIA library

The available interfaces depend on which Fortran compiler was used to compile the hipFORT modules and libraries. The interfaces use the iso_c_binding module, so the minimum requirement is a Fortran compiler that supports the Fortran 2003 standard (f2003). These interfaces typically require passing type(c_ptr) variables and the number of bytes to memory management routines such as hipMalloc, and type(c_ptr) variables to math library routines such as hipblasDgemm.

If your compiler can understand the Fortran 2008 (f2008) code constructs, additional interfaces are compiled into the hipFORT modules and libraries. These interfaces take Fortran (array) variables and the number of elements, instead of type(c_ptr) variables and the number of bytes. Therefore, they reduce the chance of introducing compile-time and runtime errors into your code and make it easier to read.

These additional interfaces are enabled automatically once hipFORT detects Fortran 2008 support in your compiler. This includes the hipMalloc, hipMemcpy and hipHostRegister array overloads. By convention, application and test sources that rely on them use the .f08 file extension (see the test/f2008 examples), while Fortran 2003 sources use .f03.

For a side-by-side comparison of the call sites, the hipMalloc mold, source and dsource overloads, and the experimental Fortran 2018 assumed-rank mode, see Fortran interface variants.

AMD’s amdflang (ROCm’s LLVM Flang, bundled with ROCm) is the recommended default, and gfortran (version 7.5.0 or newer) is also supported. Please open an issue at ROCm/hipfort#issues if you run into problems.

Building your application with CMake#

hipFORT installs CMake package files, so you can locate it with find_package and link against its exported hipfort::* targets. Each target pulls in the right Fortran module (.mod) search path, the hipFORT library, and the underlying ROCm library it wraps.

cmake_minimum_required(VERSION 3.18)
# C is required by the CMake package of HIP, which finds Threads.
project(my_app LANGUAGES Fortran C)

find_package(hipfort REQUIRED COMPONENTS hip rocblas hipblas)

add_executable(my_app main.f08)
target_link_libraries(my_app PRIVATE hipfort::rocblas hipfort::hipblas hipfort::hip)

List the libraries your code uses as COMPONENTS (hip, roctx, rocblas, rocfft, rocrand, rocsolver, rocsparse, hipblas, hipfft, hipfftw, hiprand, hipsolver, hipsparse) and link the matching hipfort::<component> targets. A hipfort::<component> target is only defined when that component is listed, and the Fortran language must be enabled before find_package(hipfort). If hipFORT is not in a default location, point CMake at it with -Dhipfort_ROOT=/path/to/hipfort (or CMAKE_PREFIX_PATH).

Multiple Fortran toolchains#

Fortran .mod files are compiler-specific, so a hipFORT build works only with the compiler that produced it. To let several toolchains coexist, hipFORT installs its modules and libraries into compiler-specific subdirectories (include/fortran/<compiler> and lib/fortran/<compiler>). This is enabled by the HIPFORT_MULTITOOLCHAIN_LAYOUT CMake option (ON by default). The exported hipfort::* targets resolve these paths automatically, so your application picks the right modules and library by using the hipFORT installation that was built with the same Fortran compiler.

To build hipFORT itself with a specific compiler or backend, use one of the example toolchain files in cmake/toolchains via -DCMAKE_TOOLCHAIN_FILE=....

Examples#

For complete, runnable programs, see the HIP runtime examples and, for the ROCm math libraries, the rocBLAS examples, the rocFFT examples, the rocRAND examples, the rocSOLVER examples, and the rocSPARSE examples. The hip* libraries, whose APIs follow their NVIDIA counterparts, have their own examples: the hipBLAS examples, the hipFFT examples, the hipRAND examples, the hipSOLVER examples, and the hipSPARSE examples. For the FFTW3-compatible interface, see the hipFFTW examples.

Supported HIP and ROCm APIs#

The current set of hipFORT interfaces is derived from ROCm 10.1.0. The following tables list the supported APIs:

Note

Use the Search function from the hipFORT table of contents to get more information on the arguments for an interface.

Contents