Add a Doxygen note about max IO size to API calls

[derobins]

No description provided.

[Copilot]

Pull request overview

Adds a reusable Doxygen note describing the maximum single-call I/O size limit, and inserts that note into the public API documentation for read/write calls.

Changes:

• Introduce a new Doxygen alias (max_io_size_note) describing the max I/O size limit.
• Reference \max_io_size_note in the documentation blocks for hipFileRead, hipFileWrite, hipFileReadAsync, and hipFileWriteAsync.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
include/hipfile.h	Adds \max_io_size_note to multiple API doc blocks (sync + async read/write).
docs/Doxyfile.in	Defines the max_io_size_note Doxygen alias used by the header docs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Same issue as hipFileRead(): the comment includes a fixed max (0x7ffff000) and also \max_io_size_note (“2^31 - PAGE_SIZE”). To avoid potentially conflicting documentation, prefer one source of truth (either use the alias in place of the hard-coded value, or make the alias explicitly reflect the constant hipFile enforces).

[Copilot]

This alias claims the max IO size is “determined by the Linux kernel” and “currently 2^31 - PAGE_SIZE”, but hipFile appears to hard-code MAX_RW_COUNT to 0x7ffff000 (see src/amd_detail/backend.h). On systems with non-4K PAGE_SIZE, the kernel’s MAX_RW_COUNT differs, so this note could be misleading. Suggest rewording to match what hipFile actually enforces (e.g., explicitly say hipFile caps requests to 0x7ffff000 / Linux MAX_RW_COUNT on supported platforms), or update the implementation to derive the limit from PAGE_SIZE if that’s the intended behavior.

Suggested change

	ALIASES += max_io_size_note="@note The maximum IO size is determined by the Linux kernel and is currently 2^31 - PAGE_SIZE"
	ALIASES += max_io_size_note="@note hipFile currently caps individual IO requests to 0x7ffff000 bytes (matching Linux MAX_RW_COUNT on systems with 4 KiB pages)."

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

include/hipfile.h:536

• The doc comment still hard-codes the max transfer size as 0x7ffff000 (2,147,479,552) for hipFileRead/hipFileWrite, but the new implementation/note makes this dependent on the system page size (e.g., 64KiB pages yield a different limit). To avoid incorrect docs on non-4KiB systems, please remove or update these hard-coded values and rely on the new \max_io_size_note (or make the text page-size-aware).

 * hipFileRead() will transfer at most 0x7ffff000 (2,147,479,552) bytes,
 * returning the number of bytes actually transferred.
 *
 * @param [in] fh            \hipfile_handle_param
 * @param [in] buffer_base   \buffer_base_param
 * @param [in] size          Number of bytes that should be read
 * @param [in] file_offset   Offset into the file that should be read from
 * @param [in] buffer_offset Offset of the GPU buffer that that the data should be written to
 *
 * \max_io_size_note
 *
 * @return if >= 0: Number of bytes read
 * @return if -1:   System error (check `errno` for the specific error)
 * @return else:    Negative value of the related hipFileOpError_t
 */
HIPFILE_API
ssize_t hipFileRead(hipFileHandle_t fh, void *buffer_base, size_t size, hoff_t file_offset,
                    hoff_t buffer_offset);

/*!
 * @brief Synchronously write data from a GPU buffer to a file
 * @ingroup file
 *
 * hipFileWrite() will transfer at most 0x7ffff000 (2,147,479,552) bytes,
 * returning the number of bytes actually transferred.
 *

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.