From 88f6589ad257b418ad42140a8f2c891f14945617 Mon Sep 17 00:00:00 2001 From: Jordan Patterson Date: Wed, 2 Sep 2026 20:42:52 -0600 Subject: [PATCH 1/5] Remove warnings from batch API documentation. --- projects/hipfile/docs/reference/api-batch.rst | 7 ------- projects/hipfile/include/hipfile.h | 6 ------ 2 files changed, 13 deletions(-) diff --git a/projects/hipfile/docs/reference/api-batch.rst b/projects/hipfile/docs/reference/api-batch.rst index c2090079f683..fe66dbbc7f20 100644 --- a/projects/hipfile/docs/reference/api-batch.rst +++ b/projects/hipfile/docs/reference/api-batch.rst @@ -11,13 +11,6 @@ requests in a single call, poll for completion, cancel pending operations, and tear down batch handles. All batch types and functions belong to the ``batch`` Doxygen group declared in ``hipfile.h``. -.. warning:: - - The batch API is not currently supported on the AMD backend. - ``hipFileBatchIOGetStatus``, ``hipFileBatchIOCancel``, and - ``hipFileBatchIODestroy`` are not implemented and return errors or perform - no operation. The maximum batch size is 128 operations. - For related API surfaces, see :doc:`/reference/api-synchronous-io`, :doc:`/reference/api-async`, and :doc:`/reference/api-errors`. diff --git a/projects/hipfile/include/hipfile.h b/projects/hipfile/include/hipfile.h index bb8592b3103f..3351e86df289 100644 --- a/projects/hipfile/include/hipfile.h +++ b/projects/hipfile/include/hipfile.h @@ -767,8 +767,6 @@ hipFileError_t hipFileBatchIOSubmit(hipFileBatchHandle_t batch_idp, unsigned nr, * @brief Poll for the status of completed batch IO operations * @ingroup batch * - * \warn_not_implemented - * * @param [in] batch_idp \batch_handle_param * @param [in] min_nr Minimum number of batch operation statuses that should be returned. * If `timeout` is exceeded, fewer statuses may be returned. @@ -788,8 +786,6 @@ hipFileError_t hipFileBatchIOGetStatus(hipFileBatchHandle_t batch_idp, unsigned * @brief Cancels all pending batch IO operations * @ingroup batch * - * \warn_not_implemented - * * @param [in] batch_idp \batch_handle_param * * @return \hipfile_error_return @@ -801,8 +797,6 @@ hipFileError_t hipFileBatchIOCancel(hipFileBatchHandle_t batch_idp); * @brief Destroys the batch IO handle and frees the associated resources * @ingroup batch * - * \warn_not_implemented_void - * * @param [in] batch_idp \batch_handle_param */ HIPFILE_API From 7aa2e9547701d1d4b0743eddfcee0316c70512f6 Mon Sep 17 00:00:00 2001 From: Jordan Patterson Date: Wed, 2 Sep 2026 20:45:26 -0600 Subject: [PATCH 2/5] Update hipFileBatchIOSetUp doxygen comments --- projects/hipfile/include/hipfile.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/projects/hipfile/include/hipfile.h b/projects/hipfile/include/hipfile.h index 3351e86df289..c0e7ac4a3e8e 100644 --- a/projects/hipfile/include/hipfile.h +++ b/projects/hipfile/include/hipfile.h @@ -735,11 +735,11 @@ typedef struct hipFileIOEvents { typedef void *hipFileBatchHandle_t; /*! - * @brief Prepare the system to perform a batch IO operation + * @brief Prepare the system to perform batch IO operations * @ingroup batch * * @param [out] batch_idp \batch_handle_param - * @param [in] max_nr Maximum number of requests that can be submitted to this batch handle + * @param [in] max_nr Size of the queue for this batch handle. Cannot exceed 128. * * @return \hipfile_error_return */ From 785a711c743e0f47d7c9d13d954fab6df5f6b0b6 Mon Sep 17 00:00:00 2001 From: Jordan Patterson Date: Thu, 3 Sep 2026 10:09:36 -0600 Subject: [PATCH 3/5] Remove mentions of fastpath not being supported on async. --- projects/hipfile/docs/reference/api-async.rst | 3 +-- projects/hipfile/docs/tutorials/async-multistream-io.rst | 4 ---- projects/hipfile/examples/README.md | 5 ----- 3 files changed, 1 insertion(+), 11 deletions(-) diff --git a/projects/hipfile/docs/reference/api-async.rst b/projects/hipfile/docs/reference/api-async.rst index b4f33807af75..40394110a043 100644 --- a/projects/hipfile/docs/reference/api-async.rst +++ b/projects/hipfile/docs/reference/api-async.rst @@ -8,8 +8,7 @@ Asynchronous I/O API reference The hipFile asynchronous API lets you enqueue non-blocking reads and writes on HIP streams. Stream registration communicates hints about fixed offsets and -alignment to the driver. On the AMD backend, asynchronous operations are -serviced through the fallback path rather than the fastpath. +alignment to the driver. For a step-by-step guide to using these functions, see :doc:`/tutorials/async-multistream-io`. diff --git a/projects/hipfile/docs/tutorials/async-multistream-io.rst b/projects/hipfile/docs/tutorials/async-multistream-io.rst index 87589cb5b9b4..5bee51319d61 100644 --- a/projects/hipfile/docs/tutorials/async-multistream-io.rst +++ b/projects/hipfile/docs/tutorials/async-multistream-io.rst @@ -10,10 +10,6 @@ Asynchronous multi-stream I/O with registered streams writes it back out, and splits the work across multiple HIP streams that run concurrently. -.. note:: - - Asynchronous I/O does not currently support the fastpath backend and will perform fallback I/O using a CPU bounce buffer. - When to use this pattern ========================= diff --git a/projects/hipfile/examples/README.md b/projects/hipfile/examples/README.md index bf9b3533d22c..1c228379d585 100644 --- a/projects/hipfile/examples/README.md +++ b/projects/hipfile/examples/README.md @@ -152,11 +152,6 @@ deterministic pattern, issues a GPU-mediated read+write round trip on one or more HIP streams, synchronizes, and verifies the output by FNV-1a hash. They share the helpers in [`common`](common) and print `OK …` on success. -> **Note:** The `O_DIRECT` fast path is not currently supported for -> asynchronous I/O — async operations always run through the POSIX compat -> (fallback) path, regardless of whether the file or filesystem is -> `O_DIRECT`-capable. Fast-path async support is planned for the future. - | Program | What it shows | | --- | --- | | `roundtrip-async` | Async read + write on the **default stream**, a single `hipStreamSynchronize`, then verify. | From be3e899e9919da3baf5fbe3b700780a98a466787 Mon Sep 17 00:00:00 2001 From: Jordan Patterson Date: Thu, 3 Sep 2026 10:22:37 -0600 Subject: [PATCH 4/5] Add note to known issues about lack of async fastpath retries. --- projects/hipfile/docs/troubleshooting/known-issues.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/projects/hipfile/docs/troubleshooting/known-issues.rst b/projects/hipfile/docs/troubleshooting/known-issues.rst index 140ff7409f8b..91a65f9890d8 100644 --- a/projects/hipfile/docs/troubleshooting/known-issues.rst +++ b/projects/hipfile/docs/troubleshooting/known-issues.rst @@ -8,6 +8,14 @@ Known issues This page documents known issues with hipFile. +Asynchronous operations that use the fastpath backend will not retry on the fallback backend +============================================================================================ + +If asynchronous operations satisfy fastpath prerequisites, they now run on the +fastpath backend. If the fastpath device lookup fails or the p2pdma transfer +is not supported between the devices, the asynchronous operation will now +fail. + Poor performance with GPU Virtual Functions =========================================== From b04f95d1ea113910f79e4afcf5cb9fe1a2a71510 Mon Sep 17 00:00:00 2001 From: Jordan Patterson Date: Thu, 3 Sep 2026 10:28:32 -0600 Subject: [PATCH 5/5] Add :members: to documentation to show struct member descriptions. --- projects/hipfile/docs/reference/api-batch.rst | 1 + projects/hipfile/docs/reference/api-driver.rst | 2 ++ projects/hipfile/docs/reference/api-errors.rst | 1 + projects/hipfile/docs/reference/api-file-and-buffer.rst | 1 + projects/hipfile/docs/reference/api-synchronous-io.rst | 1 + 5 files changed, 6 insertions(+) diff --git a/projects/hipfile/docs/reference/api-batch.rst b/projects/hipfile/docs/reference/api-batch.rst index fe66dbbc7f20..3c9396f7f4d3 100644 --- a/projects/hipfile/docs/reference/api-batch.rst +++ b/projects/hipfile/docs/reference/api-batch.rst @@ -23,3 +23,4 @@ contexts. .. doxygengroup:: batch :content-only: + :members: diff --git a/projects/hipfile/docs/reference/api-driver.rst b/projects/hipfile/docs/reference/api-driver.rst index 2f7aabb105ae..0a241c4198e8 100644 --- a/projects/hipfile/docs/reference/api-driver.rst +++ b/projects/hipfile/docs/reference/api-driver.rst @@ -19,6 +19,7 @@ properties. See the Doxygen descriptions for current implementation status. .. doxygengroup:: driver :content-only: + :members: Core versioning and configuration ==================================== @@ -29,3 +30,4 @@ parameters. .. doxygengroup:: core :content-only: + :members: diff --git a/projects/hipfile/docs/reference/api-errors.rst b/projects/hipfile/docs/reference/api-errors.rst index cc6dd3322ad6..a62781e53aae 100644 --- a/projects/hipfile/docs/reference/api-errors.rst +++ b/projects/hipfile/docs/reference/api-errors.rst @@ -38,3 +38,4 @@ Error types .. doxygengroup:: error :content-only: + :members: diff --git a/projects/hipfile/docs/reference/api-file-and-buffer.rst b/projects/hipfile/docs/reference/api-file-and-buffer.rst index 4336b3369db3..17a8fa568929 100644 --- a/projects/hipfile/docs/reference/api-file-and-buffer.rst +++ b/projects/hipfile/docs/reference/api-file-and-buffer.rst @@ -19,3 +19,4 @@ hipFile driver. .. doxygengroup:: file :content-only: + :members: diff --git a/projects/hipfile/docs/reference/api-synchronous-io.rst b/projects/hipfile/docs/reference/api-synchronous-io.rst index 22ff07b08e47..c8c515d00cc5 100644 --- a/projects/hipfile/docs/reference/api-synchronous-io.rst +++ b/projects/hipfile/docs/reference/api-synchronous-io.rst @@ -18,3 +18,4 @@ functions themselves. .. doxygengroup:: sync :content-only: + :members: