Move the hipFFT Xt API to hipfort_hipfftxt

CHANGELOG.md

@@ -32,20 +32,25 @@
   and `getrs` routines and `hipsolverDnXtrtri` in hipSOLVER, the `gehd2` and
   `gehrd` families in rocSOLVER, and `rocsparse_spsort_*`,
   `rocsparse_dnmat_copy_data` and `rocsparse_dnmat_transpose` in rocSPARSE.
-* The hipFFT Xt API in `hipfort_hipfft`, as `bind(C)` interfaces (with `_typed`
-  forms for `hipfftXtMakePlanMany` and `hipfftXtGetSizeMany`): the multi-GPU
-  routines (`hipfftXtSetGPUs`, `hipfftXtMalloc`, `hipfftXtMemcpy`, `hipfftXtFree`,
-  the `hipfftXtExecDescriptor*` family), `hipfftXtMakePlanMany`,
+* The hipFFT Xt API in the new `hipfort_hipfftxt` module (`hipfort::hipfftxt`
+  CMake component), as CUDA Fortran's `cufftXt`: it uses `hipfort_hipfft`, so
+  `use hipfort_hipfftxt` alone gives the whole hipFFT API, and
+  `hipfort_hipfft` keeps the `hipfft.h` API only. The routines are `bind(C)`
+  interfaces (with `_typed` forms for `hipfftXtMakePlanMany` and
+  `hipfftXtGetSizeMany`): the multi-GPU routines (`hipfftXtSetGPUs`,
+  `hipfftXtSetWorkArea`, `hipfftXtMalloc`, `hipfftXtMemcpy`, `hipfftXtFree`, the
+  `hipfftXtExecDescriptor*` family), `hipfftXtMakePlanMany`,
   `hipfftXtGetSizeMany` and `hipfftXtExec` on `hipDataType`, and the callback
-  routines. The `hipXtDesc` and `hipLibXtDesc` types are in the new
-  `hipfort_hipfft_types` module, and the Xt enums in `hipfort_hipfft_enums`.
+  routines. The `hipXtDesc` and `hipLibXtDesc` types are in
+  `hipfort_hipfftxt_types`, and the Xt enums in `hipfort_hipfftxt_enums`.
   On AMD GPUs the descriptor routines need a plan spread over two or more GPUs,
   and a multi-GPU plan writes one work size per GPU: pass `c_loc` of an
   `integer(c_size_t)` array as `workSize`. The multi-process routines
   of `hipfftMp.h` (`hipfftMpAttachComm`, `hipfftXtSetDistribution`,
   `hipfftXtSetSubformatDefault`) are bound too, but exist only in a hipFFT built
   with MPI support, which the ROCm packages are not. On the CUDA backend the Xt
-  and multi-process routines added here are not available. The hipFFT examples document
+  routines bind their `cufftXt*` counterparts; the multi-process routines have
+  none. The hipFFT examples document
   the multi-GPU and MPI workflows.
 * Array overloads (`rank_N`, `full_rank`, assumed-rank) for the ILP64 (`_64`)
   routines of rocBLAS, hipBLAS and rocSOLVER (`rocblas_sscal_64`, ...), the same

README.md

@@ -134,6 +134,7 @@ The following tables list the supported API:
 * [HIP](https://rocm.docs.amd.com/projects/hipfort/en/develop/doxygen/html/md_input_2supported__api__hip.html)
 * [hipBLAS](https://rocm.docs.amd.com/projects/hipfort/en/develop/doxygen/html/md_input_2supported__api__hipblas.html)
 * [hipFFT](https://rocm.docs.amd.com/projects/hipfort/en/develop/doxygen/html/md_input_2supported__api__hipfft.html)
+* [hipFFT Xt](https://rocm.docs.amd.com/projects/hipfort/en/develop/doxygen/html/md_input_2supported__api__hipfftxt.html)
 * [hipFFTW](https://rocm.docs.amd.com/projects/hipfort/en/develop/doxygen/html/md_input_2supported__api__hipfftw.html)
 * [hipRAND](https://rocm.docs.amd.com/projects/hipfort/en/develop/doxygen/html/md_input_2supported__api__hiprand.html)
 * [hipSOLVER](https://rocm.docs.amd.com/projects/hipfort/en/develop/doxygen/html/md_input_2supported__api__hipsolver.html)

docs/doxygen/input/supported_api_hipfft.md

@@ -25,35 +25,13 @@
 21 | [hipfftGetSize](interfacehipfort__hipfft_1_1hipfftgetsize.html "Interface documentation") | C binding, typed
 22 | [hipfftSetAutoAllocation](interfacehipfort__hipfft_1_1hipfftsetautoallocation.html "Interface documentation") | C binding
 23 | [hipfftSetWorkArea](interfacehipfort__hipfft_1_1hipfftsetworkarea.html "Interface documentation") | C binding
-24 | [hipfftXtSetWorkArea](interfacehipfort__hipfft_1_1hipfftxtsetworkarea.html "Interface documentation") | C binding
-25 | [hipfftExecC2C](interfacehipfort__hipfft_1_1hipfftexecc2c.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
-26 | [hipfftExecR2C](interfacehipfort__hipfft_1_1hipfftexecr2c.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
-27 | [hipfftExecC2R](interfacehipfort__hipfft_1_1hipfftexecc2r.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
-28 | [hipfftExecZ2Z](interfacehipfort__hipfft_1_1hipfftexecz2z.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
-29 | [hipfftExecD2Z](interfacehipfort__hipfft_1_1hipfftexecd2z.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
-30 | [hipfftExecZ2D](interfacehipfort__hipfft_1_1hipfftexecz2d.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
-31 | [hipfftSetStream](interfacehipfort__hipfft_1_1hipfftsetstream.html "Interface documentation") | C binding
-32 | [hipfftDestroy](interfacehipfort__hipfft_1_1hipfftdestroy.html "Interface documentation") | C binding
-33 | [hipfftGetVersion](interfacehipfort__hipfft_1_1hipfftgetversion.html "Interface documentation") | C binding, typed
-34 | [hipfftGetProperty](interfacehipfort__hipfft_1_1hipfftgetproperty.html "Interface documentation") | C binding, typed
-35 | [hipfftXtSetCallback](interfacehipfort__hipfft_1_1hipfftxtsetcallback.html "Interface documentation") | C binding
-36 | [hipfftXtClearCallback](interfacehipfort__hipfft_1_1hipfftxtclearcallback.html "Interface documentation") | C binding
-37 | [hipfftXtSetCallbackSharedSize](interfacehipfort__hipfft_1_1hipfftxtsetcallbacksharedsize.html "Interface documentation") | C binding
-38 | [hipfftXtSetJITCallback](interfacehipfort__hipfft_1_1hipfftxtsetjitcallback.html "Interface documentation") | C binding
-39 | [hipfftXtMakePlanMany](interfacehipfort__hipfft_1_1hipfftxtmakeplanmany.html "Interface documentation") | C binding, rank_0, rank_1, assumed_rank, typed
-40 | [hipfftXtGetSizeMany](interfacehipfort__hipfft_1_1hipfftxtgetsizemany.html "Interface documentation") | C binding, rank_0, rank_1, assumed_rank, typed
-41 | [hipfftXtExec](interfacehipfort__hipfft_1_1hipfftxtexec.html "Interface documentation") | C binding
-42 | [hipfftXtSetGPUs](interfacehipfort__hipfft_1_1hipfftxtsetgpus.html "Interface documentation") | C binding, rank_0, rank_1, assumed_rank
-43 | [hipfftXtMalloc](interfacehipfort__hipfft_1_1hipfftxtmalloc.html "Interface documentation") | C binding
-44 | [hipfftXtMemcpy](interfacehipfort__hipfft_1_1hipfftxtmemcpy.html "Interface documentation") | C binding
-45 | [hipfftXtFree](interfacehipfort__hipfft_1_1hipfftxtfree.html "Interface documentation") | C binding
-46 | [hipfftXtExecDescriptorC2C](interfacehipfort__hipfft_1_1hipfftxtexecdescriptorc2c.html "Interface documentation") | C binding
-47 | [hipfftXtExecDescriptorR2C](interfacehipfort__hipfft_1_1hipfftxtexecdescriptorr2c.html "Interface documentation") | C binding
-48 | [hipfftXtExecDescriptorC2R](interfacehipfort__hipfft_1_1hipfftxtexecdescriptorc2r.html "Interface documentation") | C binding
-49 | [hipfftXtExecDescriptorZ2Z](interfacehipfort__hipfft_1_1hipfftxtexecdescriptorz2z.html "Interface documentation") | C binding
-50 | [hipfftXtExecDescriptorD2Z](interfacehipfort__hipfft_1_1hipfftxtexecdescriptord2z.html "Interface documentation") | C binding
-51 | [hipfftXtExecDescriptorZ2D](interfacehipfort__hipfft_1_1hipfftxtexecdescriptorz2d.html "Interface documentation") | C binding
-52 | [hipfftXtExecDescriptor](interfacehipfort__hipfft_1_1hipfftxtexecdescriptor.html "Interface documentation") | C binding
-53 | [hipfftMpAttachComm](interfacehipfort__hipfft_1_1hipfftmpattachcomm.html "Interface documentation") | C binding
-54 | [hipfftXtSetDistribution](interfacehipfort__hipfft_1_1hipfftxtsetdistribution.html "Interface documentation") | C binding
-55 | [hipfftXtSetSubformatDefault](interfacehipfort__hipfft_1_1hipfftxtsetsubformatdefault.html "Interface documentation") | C binding
+24 | [hipfftExecC2C](interfacehipfort__hipfft_1_1hipfftexecc2c.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
+25 | [hipfftExecR2C](interfacehipfort__hipfft_1_1hipfftexecr2c.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
+26 | [hipfftExecC2R](interfacehipfort__hipfft_1_1hipfftexecc2r.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
+27 | [hipfftExecZ2Z](interfacehipfort__hipfft_1_1hipfftexecz2z.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
+28 | [hipfftExecD2Z](interfacehipfort__hipfft_1_1hipfftexecd2z.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
+29 | [hipfftExecZ2D](interfacehipfort__hipfft_1_1hipfftexecz2d.html "Interface documentation") | C binding, rank_0, rank_1, rank_2, rank_3, assumed_rank
+30 | [hipfftSetStream](interfacehipfort__hipfft_1_1hipfftsetstream.html "Interface documentation") | C binding
+31 | [hipfftDestroy](interfacehipfort__hipfft_1_1hipfftdestroy.html "Interface documentation") | C binding
+32 | [hipfftGetVersion](interfacehipfort__hipfft_1_1hipfftgetversion.html "Interface documentation") | C binding, typed
+33 | [hipfftGetProperty](interfacehipfort__hipfft_1_1hipfftgetproperty.html "Interface documentation") | C binding, typed

docs/doxygen/input/supported_api_hipfftxt.md

@@ -0,0 +1,26 @@
+# hipFFT Xt API Support
+
+\# | API Name | Variants
+----|---------------|---------
+1 | [hipfftXtSetWorkArea](interfacehipfort__hipfftxt_1_1hipfftxtsetworkarea.html "Interface documentation") | C binding
+2 | [hipfftXtSetCallback](interfacehipfort__hipfftxt_1_1hipfftxtsetcallback.html "Interface documentation") | C binding
+3 | [hipfftXtClearCallback](interfacehipfort__hipfftxt_1_1hipfftxtclearcallback.html "Interface documentation") | C binding
+4 | [hipfftXtSetCallbackSharedSize](interfacehipfort__hipfftxt_1_1hipfftxtsetcallbacksharedsize.html "Interface documentation") | C binding
+5 | [hipfftXtSetJITCallback](interfacehipfort__hipfftxt_1_1hipfftxtsetjitcallback.html "Interface documentation") | C binding
+6 | [hipfftXtMakePlanMany](interfacehipfort__hipfftxt_1_1hipfftxtmakeplanmany.html "Interface documentation") | C binding, rank_0, rank_1, assumed_rank, typed
+7 | [hipfftXtGetSizeMany](interfacehipfort__hipfftxt_1_1hipfftxtgetsizemany.html "Interface documentation") | C binding, rank_0, rank_1, assumed_rank, typed
+8 | [hipfftXtExec](interfacehipfort__hipfftxt_1_1hipfftxtexec.html "Interface documentation") | C binding
+9 | [hipfftXtSetGPUs](interfacehipfort__hipfftxt_1_1hipfftxtsetgpus.html "Interface documentation") | C binding, rank_0, rank_1, assumed_rank
+10 | [hipfftXtMalloc](interfacehipfort__hipfftxt_1_1hipfftxtmalloc.html "Interface documentation") | C binding
+11 | [hipfftXtMemcpy](interfacehipfort__hipfftxt_1_1hipfftxtmemcpy.html "Interface documentation") | C binding
+12 | [hipfftXtFree](interfacehipfort__hipfftxt_1_1hipfftxtfree.html "Interface documentation") | C binding
+13 | [hipfftXtExecDescriptorC2C](interfacehipfort__hipfftxt_1_1hipfftxtexecdescriptorc2c.html "Interface documentation") | C binding
+14 | [hipfftXtExecDescriptorR2C](interfacehipfort__hipfftxt_1_1hipfftxtexecdescriptorr2c.html "Interface documentation") | C binding
+15 | [hipfftXtExecDescriptorC2R](interfacehipfort__hipfftxt_1_1hipfftxtexecdescriptorc2r.html "Interface documentation") | C binding
+16 | [hipfftXtExecDescriptorZ2Z](interfacehipfort__hipfftxt_1_1hipfftxtexecdescriptorz2z.html "Interface documentation") | C binding
+17 | [hipfftXtExecDescriptorD2Z](interfacehipfort__hipfftxt_1_1hipfftxtexecdescriptord2z.html "Interface documentation") | C binding
+18 | [hipfftXtExecDescriptorZ2D](interfacehipfort__hipfftxt_1_1hipfftxtexecdescriptorz2d.html "Interface documentation") | C binding
+19 | [hipfftXtExecDescriptor](interfacehipfort__hipfftxt_1_1hipfftxtexecdescriptor.html "Interface documentation") | C binding
+20 | [hipfftMpAttachComm](interfacehipfort__hipfftxt_1_1hipfftmpattachcomm.html "Interface documentation") | C binding
+21 | [hipfftXtSetDistribution](interfacehipfort__hipfftxt_1_1hipfftxtsetdistribution.html "Interface documentation") | C binding
+22 | [hipfftXtSetSubformatDefault](interfacehipfort__hipfftxt_1_1hipfftxtsetsubformatdefault.html "Interface documentation") | C binding

docs/how-to/using-hipfort.rst

@@ -87,7 +87,7 @@ underlying ROCm library it wraps.
 
 List the libraries your code uses as ``COMPONENTS`` (``hip``, ``roctx``,
 ``rocblas``, ``rocfft``, ``rocrand``, ``rocsolver``, ``rocsparse``,
-``hipblas``, ``hipfft``, ``hipfftw``, ``hiprand``, ``hipsolver``,
+``hipblas``, ``hipfft``, ``hipfftw``, ``hipfftxt``, ``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)``.
@@ -180,6 +180,7 @@ links as long as it does not call them. The following tables list the supported
 * :doc:`HIP API <../doxygen/html/md_input_2supported__api__hip>`
 * :doc:`hipBLAS API <../doxygen/html/md_input_2supported__api__hipblas>`
 * :doc:`hipFFT API <../doxygen/html/md_input_2supported__api__hipfft>`
+* :doc:`hipFFT Xt API <../doxygen/html/md_input_2supported__api__hipfftxt>`
 * :doc:`hipFFTW API <../doxygen/html/md_input_2supported__api__hipfftw>`
 * :doc:`hipRAND API <../doxygen/html/md_input_2supported__api__hiprand>`
 * :doc:`hipSOLVER API <../doxygen/html/md_input_2supported__api__hipsolver>`

docs/reference/index.md

@@ -11,6 +11,7 @@ This section provides technical descriptions and important information about the
 - {doc}`/doxygen/html/md_input_2supported__api__hip`
 - {doc}`/doxygen/html/md_input_2supported__api__hipblas`
 - {doc}`/doxygen/html/md_input_2supported__api__hipfft`
+- {doc}`/doxygen/html/md_input_2supported__api__hipfftxt`
 - {doc}`/doxygen/html/md_input_2supported__api__hipfftw`
 - {doc}`/doxygen/html/md_input_2supported__api__hiprand`
 - {doc}`/doxygen/html/md_input_2supported__api__hipsolver`

docs/tutorials/hipfft-examples.rst

@@ -8,14 +8,17 @@ hipFFT examples
 
 `hipFFT <https://rocm.docs.amd.com/projects/hipFFT/en/latest/>`_ is a thin layer
 over rocFFT with an API that follows cuFFT. hipFORT exposes it through the
-``hipfort_hipfft`` module.
+``hipfort_hipfft`` module, and its Xt and multi-process APIs through the
+``hipfort_hipfftxt`` module, as CUDA Fortran does with ``cufft`` and ``cufftXt``.
+``hipfort_hipfftxt`` uses ``hipfort_hipfft``, so ``use hipfort_hipfftxt`` alone
+gives the whole hipFFT API.
 
 Every program on this page is complete and self-contained, and is built
 and run as part of the hipFORT test suite. The Fortran 2008 version of each
 program lives in ``test/f2008/hipfft``, and the equivalent Fortran 2003 version,
 which uses ``type(c_ptr)`` device pointers and explicit byte counts instead of
 Fortran array pointers, lives in ``test/f2003/hipfft``. The Xt programs exist
-only in the Fortran 2003 form.
+only in the Fortran 2003 form, in ``test/f2003/hipfftxt``.
 
 If you want direct access to rocFFT rather than a cuFFT-style interface, see
 the :doc:`rocFFT examples <rocfft-examples>`. For FFTW3-compatible code, see the
@@ -177,7 +180,7 @@ names the input, output and execution data types with ``hipDataType`` values
 ``hipfftXtExec`` runs the plan whatever its data types, taking the direction for
 complex transforms.
 
-.. literalinclude:: ../../test/f2003/hipfft/hipfft_xt_makeplanmany_c.f03
+.. literalinclude:: ../../test/f2003/hipfftxt/hipfftxt_makeplanmany_c.f03
    :language: fortran
 
 Multi-GPU transforms
@@ -211,25 +214,25 @@ copy of the type: ``hipfftXtFree`` would then release the wrong address. The
 ``GPUs``, ``data`` and ``size`` fields say where each part of the data is.
 
 The ``hipLibXtDesc`` and ``hipXtDesc`` types are in the
-``hipfort_hipfft_types`` module, which ``hipfort_hipfft`` uses, and the Xt
-constants (``HIPFFT_XT_FORMAT_INPLACE``, ``HIPFFT_COPY_HOST_TO_DEVICE``, ...)
-are in ``hipfort_hipfft_enums``.
+``hipfort_hipfftxt_types`` module, and the Xt constants
+(``HIPFFT_XT_FORMAT_INPLACE``, ``HIPFFT_COPY_HOST_TO_DEVICE``, ...) in
+``hipfort_hipfftxt_enums``; ``hipfort_hipfftxt`` uses both.
 
 On AMD GPUs a descriptor needs a plan over two or more GPUs, and unbatched
 one-dimensional transforms are not supported. This program runs a
 two-dimensional transform on two GPUs, forward then inverse, and checks the
 result against the input; on a machine with fewer than two GPUs it reports so
 and the test is skipped.
 
-.. literalinclude:: ../../test/f2003/hipfft/hipfft_xt_descriptor_z.f03
+.. literalinclude:: ../../test/f2003/hipfftxt/hipfftxt_descriptor_z.f03
    :language: fortran
 
 Multi-process transforms with MPI
 =================================
 
 ``hipfftMpAttachComm``, ``hipfftXtSetDistribution`` and
 ``hipfftXtSetSubformatDefault`` distribute a transform over the ranks of an MPI
-communicator. They are bound in ``hipfort_hipfft``, but exist only in a hipFFT
+communicator. They are bound in ``hipfort_hipfftxt``, but exist only in a hipFFT
 built with MPI support (``HIPFFT_MPI_ENABLE``), which the ROCm packages are
 not: with those, a program that calls them does not link.
 
@@ -256,7 +259,7 @@ depend on the MPI implementation, so build it in C from the Fortran handle with
    use iso_c_binding
    use mpi_f08
    use hipfort_check
-   use hipfort_hipfft
+   use hipfort_hipfftxt
 
    interface
      function c_comm_from_fortran(fcomm) bind(c, name="c_comm_from_fortran")

lib/CMakeLists.txt

@@ -322,6 +322,8 @@ if(HIP_PLATFORM STREQUAL "amd" AND TARGET hipfort-amdgcn)
     else()
       hipfort_add_component(hipfftw hip::hipfft)
     endif()
+    # hipFFT's Xt and Mp APIs (hipfort_hipfftxt), in libhipfft.
+    hipfort_add_component(hipfftxt hip::hipfft)
   else()
     message(STATUS "Skipping hipfort::hipfft target export")
   endif()
@@ -372,7 +374,7 @@ elseif(CUDAToolkit_FOUND AND TARGET hipfort-nvptx)
   # Only the hip* components exist here; roc* and the FFTW3 API have no CUDA counterpart.
   set(HIPFORT_BASE_LIB hipfort-nvptx)
   foreach(pair "hip:cudart" "hipblas:cublas" "hipfft:cufft"
-               "hiprand:curand" "hipsolver:cusolver" "hipsparse:cusparse")
+               "hipfftxt:cufft" "hiprand:curand" "hipsolver:cusolver" "hipsparse:cusparse")
     string(REPLACE ":" ";" pair "${pair}")
     list(GET pair 0 _comp)
     list(GET pair 1 _cudalib)

lib/hipfort-config.cmake.in

@@ -29,19 +29,20 @@ include(CMakeFindDependencyMacro)
 
 set(_hipfort_supported_components hip roctx
   rocblas rocfft rocrand rocsolver rocsparse
-  hipblas hipfft hipfftw hiprand hipsolver hipsparse)
+  hipblas hipfft hipfftw hipfftxt hiprand hipsolver hipsparse)
 
 # Most components map 1:1 to a ROCm package of the same name. A few do not:
-# hipfftw is provided by the hipfft package (there is no standalone hipfftw
-# package), and roctx by rocprofiler-sdk-roctx.
+# hipfftw and hipfftxt are provided by the hipfft package (there is no standalone
+# hipfftw or hipfftxt package), and roctx by rocprofiler-sdk-roctx.
 set(_hipfort_hipfftw_dependency hipfft)
+set(_hipfort_hipfftxt_dependency hipfft)
 set(_hipfort_roctx_dependency rocprofiler-sdk-roctx)
 
 # A build of the CUDA (nvptx) backend exports only the hip* components, and
 # links them against the CUDA:: targets of CUDAToolkit instead.
 set(_hipfort_base_arch "@HIPFORT_BASE_ARCH@")
 if(_hipfort_base_arch STREQUAL "nvptx")
-  set(_hipfort_supported_components hip hipblas hipfft hiprand hipsolver hipsparse)
+  set(_hipfort_supported_components hip hipblas hipfft hipfftxt hiprand hipsolver hipsparse)
 endif()
 
 include("${CMAKE_CURRENT_LIST_DIR}/hipfort-${_hipfort_base_arch}-targets.cmake")