Skip to content

Add a Doxygen note about max IO size to API calls #206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
derobins wants to merge 2 commits into
base: develop
Choose a base branch
from
+21 −1
Open

Add a Doxygen note about max IO size to API calls #206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
19c9f05
Add a Doxygen note about max IO size to API calls
derobins Mar 3, 2026
ca7c174
hipFile: Mirror kernel's MAX_RW_COUNT computation
kurtmcmillan Mar 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/Doxyfile.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,7 @@ ALIASES += buffer_base_param="Base address of the GPU buffer"
ALIASES += batch_handle_param="Opaque handle for batch operations"
ALIASES += hipstream_param="The stream used for async IO requests"
ALIASES += hipstream_if_null="If NULL, this request will be synchronous"
ALIASES += max_io_size_note="@note The maximum IO size is determined by the Linux kernel and is currently 2^31 - PAGE_SIZE"
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
# only. Doxygen will then generate output that is more tailored for C. For
Expand Down
8 changes: 8 additions & 0 deletions include/hipfile.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -517,6 +517,8 @@ hipFileError_t hipFileBufDeregister(const void *buffer_base);
* @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
Expand All @@ -538,6 +540,8 @@ ssize_t hipFileRead(hipFileHandle_t fh, void *buffer_base, size_t size, hoff_t f
* @param [in] file_offset Offset into the file that should be written to
* @param [in] buffer_offset Offset of the GPU buffer that the data should be read from
*
* \max_io_size_note
*
* @return if >= 0: Number of bytes written
* @return if -1: System error (check `errno` for the specific error)
* @return else: Negative value of the related hipFileOpError_t
Expand Down Expand Up @@ -838,6 +842,8 @@ void hipFileBatchIODestroy(hipFileBatchHandle_t batch_idp);
* @param [out] bytes_read_p Number of bytes read
* @param [in] stream \hipstream_param. \hipstream_if_null.
*
* \max_io_size_note
*
* @return \hipfile_error_return
*/
HIPFILE_API
Expand All @@ -856,6 +862,8 @@ hipFileError_t hipFileReadAsync(hipFileHandle_t fh, void *buffer_base, size_t *s
* @param [out] bytes_written_p Number of bytes written
* @param [in] stream \hipstream_param. \hipstream_if_null.
*
* \max_io_size_note
*
* @return \hipfile_error_return
*/
HIPFILE_API
Expand Down
13 changes: 12 additions & 1 deletion src/amd_detail/backend.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,26 @@
#include "sys.h"

#include <cstddef>
#include <climits>
#include <memory>
#include <sys/types.h>
#include <unistd.h>

namespace hipFile {

static const size_t PAGE_SIZE{[] {
long v = sysconf(_SC_PAGE_SIZE);
if (v == -1) {
throw std::runtime_error("sysconf(_SC_PAGE_SIZE) failed");
}
return static_cast<size_t>(v);
}()};

static const size_t PAGE_MASK{~(PAGE_SIZE - 1)};
Comment on lines +22 to +30

// The maximum number of bytes that can be transferred in a single read() or
// write() system call. Mirrors kernel's MAX_RW_COUNT
static const size_t MAX_RW_COUNT = 0x7ffff000;
static const size_t MAX_RW_COUNT = (INT_MAX & PAGE_MASK);

struct Backend {
virtual ~Backend() = default;
Expand Down
Loading