Skip to content

Docs: Use Doxygen macros for common return and parameter types #209

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

Merged
derobins merged 1 commit into from
Mar 5, 2026
Merged

Docs: Use Doxygen macros for common return and parameter types #209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 6 additions & 1 deletion docs/Doxyfile.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,7 +283,12 @@ TAB_SIZE = 4
# with the commands \{ and \} for these it is advised to use the version @{ and
# @} or use a double escape (\\{ and \\})

ALIASES = hipFileError_t="A hipFileError_t struct that holds both hipFile and HIP error values"
ALIASES = hipfile_error_return="A hipFileError_t struct that holds both hipFile and HIP error values"
ALIASES += hipfile_handle_param="Opaque file handle for GPU IO operations"
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"

# 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
94 changes: 46 additions & 48 deletions include/hipfile.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -457,10 +457,10 @@ typedef void *hipFileHandle_t;
* `hipFileHandleRegister()` will initialize the library and increment
* the reference count.
*
* @param [out] fh Opaque file handle for GPU IO operations
* @param [out] fh \hipfile_handle_param
* @param [in] descr Parameters for opening the file
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileHandleRegister(hipFileHandle_t *fh, hipFileDescr_t *descr);
Expand All @@ -469,7 +469,7 @@ hipFileError_t hipFileHandleRegister(hipFileHandle_t *fh, hipFileDescr_t *descr)
* @brief Deregisters a file from GPU IO
* @ingroup file
*
* @param [in] fh Opaque file handle for GPU IO operations
* @param [in] fh \hipfile_handle_param
*/
HIPFILE_API
void hipFileHandleDeregister(hipFileHandle_t fh);
Expand All @@ -484,11 +484,11 @@ void hipFileHandleDeregister(hipFileHandle_t fh);
* `hipFileBufRegister()` will initialize the library and increment
* the reference count.
*
* @param [in] buffer_base Base address of the GPU buffer
* @param [in] buffer_base \buffer_base_param
* @param [in] length Size of the allocated buffer in bytes
* @param [in] flags Control flags for this buffer
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileBufRegister(const void *buffer_base, size_t length, int flags);
Expand All @@ -497,9 +497,9 @@ hipFileError_t hipFileBufRegister(const void *buffer_base, size_t length, int fl
* @brief Deregisters a GPU memory region from being used with GPU IO
* @ingroup file
*
* @param [in] buffer_base Base address of the GPU buffer
* @param [in] buffer_base \buffer_base_param
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileBufDeregister(const void *buffer_base);
Expand All @@ -511,8 +511,8 @@ hipFileError_t hipFileBufDeregister(const void *buffer_base);
* hipFileRead() will transfer at most 0x7ffff000 (2,147,479,552) bytes,
* returning the number of bytes actually transferred.
*
* @param [in] fh Opaque file handle for GPU IO operations
* @param [in] buffer_base Base address of the GPU buffer
* @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
Expand All @@ -532,8 +532,8 @@ ssize_t hipFileRead(hipFileHandle_t fh, void *buffer_base, size_t size, hoff_t f
* hipFileWrite() will transfer at most 0x7ffff000 (2,147,479,552) bytes,
* returning the number of bytes actually transferred.
*
* @param [in] fh Opaque file handle for GPU IO operations
* @param [in] buffer_base Base address of the GPU buffer
* @param [in] fh \hipfile_handle_param
* @param [in] buffer_base \buffer_base_param
* @param [in] size Number of bytes that should be written
* @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
Expand Down Expand Up @@ -562,7 +562,7 @@ ssize_t hipFileWrite(hipFileHandle_t fh, const void *buffer_base, size_t size, h
* `hipFileBufRegister()` or `hipFileHandleRegister()` will trigger
* library initialization and increment the library's reference count.
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileDriverOpen(void);
Expand All @@ -578,7 +578,7 @@ hipFileError_t hipFileDriverOpen(void);
* Explicitly closing the library is not required; the library's state will be
* destroyed automatically at program exit.
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileDriverClose(void);
Expand All @@ -601,7 +601,7 @@ int64_t hipFileUseCount(void);
*
* @param [out] props See `hipFileDriverProps_t` for what properties are reported
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileDriverGetProperties(hipFileDriverProps_t *props);
Expand All @@ -616,7 +616,7 @@ hipFileError_t hipFileDriverGetProperties(hipFileDriverProps_t *props);
* @param [in] poll_threshold_size Maximum IO size (in KiB) for which polling is
* used when enabled
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileDriverSetPollMode(bool poll, size_t poll_threshold_size);
Expand All @@ -629,7 +629,7 @@ hipFileError_t hipFileDriverSetPollMode(bool poll, size_t poll_threshold_size);
*
* @param [in] max_direct_io_size Maximum IO chunk size (in KiB) for each IO request
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileDriverSetMaxDirectIOSize(size_t max_direct_io_size);
Expand All @@ -642,7 +642,7 @@ hipFileError_t hipFileDriverSetMaxDirectIOSize(size_t max_direct_io_size);
*
* @param [in] max_cache_size Maximum GPU memory (in KiB) that can be reserved for bounce buffers
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileDriverSetMaxCacheSize(size_t max_cache_size);
Expand All @@ -655,7 +655,7 @@ hipFileError_t hipFileDriverSetMaxCacheSize(size_t max_cache_size);
*
* @param [in] max_pinned_size Maximum GPU memory (in KiB) that can be pinned
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileDriverSetMaxPinnedMemSize(size_t max_pinned_size);
Expand Down Expand Up @@ -734,10 +734,10 @@ typedef void *hipFileBatchHandle_t;
* @brief Prepare the system to perform a batch IO operation
* @ingroup batch
*
* @param [out] batch_idp Opaque handle for batch operations
* @param [out] batch_idp \batch_handle_param
* @param [in] max_nr Maximum number of requests that can be submitted to this batch handle
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileBatchIOSetUp(hipFileBatchHandle_t *batch_idp, unsigned max_nr);
Expand All @@ -746,14 +746,14 @@ hipFileError_t hipFileBatchIOSetUp(hipFileBatchHandle_t *batch_idp, unsigned max
* @brief Enqueue a batch of IO requests for the GPU to complete asynchronously
* @ingroup batch
*
* @param [in] batch_idp Opaque handle for batch operations
* @param [in] batch_idp \batch_handle_param
* @param [in] nr Number of batch IO requests to submit
* @param [in] iocbp An array of `nr` batch IO requests to submit to the GPU.
* Data will be read into or written from the buffer specified in
* each request.
* @param [in] flags Control Flags for the batch IO. Currently unused.
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileBatchIOSubmit(hipFileBatchHandle_t batch_idp, unsigned nr, hipFileIOParams_t *iocbp,
Expand All @@ -763,7 +763,7 @@ hipFileError_t hipFileBatchIOSubmit(hipFileBatchHandle_t batch_idp, unsigned nr,
* @brief Poll for the status of completed batch IO operations
* @ingroup batch
*
* @param [in] batch_idp Opaque handle for batch operations.
* @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.
* @param [in,out] nr Maximum number of batch operation statuses that can be returned.
Expand All @@ -772,7 +772,7 @@ hipFileError_t hipFileBatchIOSubmit(hipFileBatchHandle_t batch_idp, unsigned nr,
* @param [out] iocbp An array containing up to `nr` statuses from the overall batch operation
* @param [in] timeout Maximum amount of time this function should poll for status updates
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileBatchIOGetStatus(hipFileBatchHandle_t batch_idp, unsigned min_nr, unsigned *nr,
Expand All @@ -782,9 +782,9 @@ hipFileError_t hipFileBatchIOGetStatus(hipFileBatchHandle_t batch_idp, unsigned
* @brief Cancels all pending batch IO operations
* @ingroup batch
*
* @param [in] batch_idp Opaque handle for batch operations
* @param [in] batch_idp \batch_handle_param
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileBatchIOCancel(hipFileBatchHandle_t batch_idp);
Expand All @@ -793,7 +793,7 @@ hipFileError_t hipFileBatchIOCancel(hipFileBatchHandle_t batch_idp);
* @brief Destroys the batch IO handle and frees the associated resources
* @ingroup batch
*
* @param [in] batch_idp Opaque handle for batch operations
* @param [in] batch_idp \batch_handle_param
*/
HIPFILE_API
void hipFileBatchIODestroy(hipFileBatchHandle_t batch_idp);
Expand Down Expand Up @@ -830,16 +830,15 @@ void hipFileBatchIODestroy(hipFileBatchHandle_t batch_idp);
* @brief Perform an asynchronous read from a stream
* @ingroup async
*
* @param [in] fh Opaque file handle for GPU IO operations
* @param [in] buffer_base Base address of the GPU buffer
* @param [in] fh \hipfile_handle_param
* @param [in] buffer_base \buffer_base_param
* @param [in] size_p Number of bytes that should be read
* @param [in] file_offset_p Offset into the file that should be read from
* @param [in] buffer_offset_p Offset of the GPU buffer that that the data should be written to
* @param [out] bytes_read_p Number of bytes read
* @param [in] stream The hipStream to enqueue this async IO request.
* If NULL, this request will be synchronous.
* @param [in] stream \hipstream_param. \hipstream_if_null.
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileReadAsync(hipFileHandle_t fh, void *buffer_base, size_t *size_p, hoff_t *file_offset_p,
Expand All @@ -849,16 +848,15 @@ hipFileError_t hipFileReadAsync(hipFileHandle_t fh, void *buffer_base, size_t *s
* @brief Perform an asynchronous write to a stream
* @ingroup async
*
* @param [in] fh Opaque file handle for GPU IO operations
* @param [in] buffer_base Base address of the GPU buffer
* @param [in] fh \hipfile_handle_param
* @param [in] buffer_base \buffer_base_param
* @param [in] size_p Number of bytes that should be written
* @param [in] file_offset_p Offset into the file that should be written to
* @param [in] buffer_offset_p Offset of the GPU buffer that that the data should be read from
* @param [out] bytes_written_p Number of bytes written
* @param [in] stream The hipStream to enqueue this async IO request.
* If NULL, this request will be synchronous.
* @param [in] stream \hipstream_param. \hipstream_if_null.
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileWriteAsync(hipFileHandle_t fh, void *buffer_base, size_t *size_p, hoff_t *file_offset_p,
Expand All @@ -868,11 +866,11 @@ hipFileError_t hipFileWriteAsync(hipFileHandle_t fh, void *buffer_base, size_t *
* @brief Register a stream to be used by for asynchronous GPU IO
* @ingroup async
*
* @param [in] stream The stream used for for async IO requests
* @param [in] stream \hipstream_param
* @param [in] flags Flags that can optimize stream processing if parameters
* are known/are aligned at time of request submission
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileStreamRegister(hipStream_t stream, unsigned flags);
Expand All @@ -881,9 +879,9 @@ hipFileError_t hipFileStreamRegister(hipStream_t stream, unsigned flags);
* @brief Deregister a stream and free the associated resources
* @ingroup async
*
* @param [in] stream The stream used for async IO requests
* @param [in] stream \hipstream_param
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileStreamDeregister(hipStream_t stream);
Expand All @@ -902,7 +900,7 @@ hipFileError_t hipFileStreamDeregister(hipStream_t stream);
*
* @note Parameters can be set to NULL to ignore that part of the version
*
* @return \hipFileError_t
* @return \hipfile_error_return
*/
HIPFILE_API
hipFileError_t hipFileGetVersion(unsigned *major, unsigned *minor, unsigned *patch);
Expand Down Expand Up @@ -966,7 +964,7 @@ typedef enum hipFileStringConfigParameter_t {
* @param param The configuration parameter
* @param value The location to store the value of the configuration parameter
*
* @return \hipFileError_t
* @return \hipfile_error_return
*
* @note If the driver is open, the value returned is the value currently in use by the driver.
* @note If the driver is closed, the value returned is the value that was last set by hipFileSetParameter*.
Expand All @@ -981,7 +979,7 @@ hipFileError_t hipFileGetParameterSizeT(hipFileSizeTConfigParameter_t param, siz
* @param param The configuration parameter
* @param value The location to store the value of the configuration parameter
*
* @return \hipFileError_t
* @return \hipfile_error_return
*
* @note If the driver is open, the value returned is the value currently in use by the driver.
* @note If the driver is closed, the value returned is the value that was last set by hipFileSetParameter*.
Expand All @@ -997,7 +995,7 @@ hipFileError_t hipFileGetParameterBool(hipFileBoolConfigParameter_t param, bool
* @param desc_str The location to store the value of the configuration parameter
* @param len The length of the desc_str parameter
*
* @return \hipFileError_t
* @return \hipfile_error_return
*
* @note If the driver is open, the value returned is the value currently in use by the driver.
* @note If the driver is closed, the value returned is the value that was last set by hipFileSetParameter*.
Expand All @@ -1012,7 +1010,7 @@ hipFileError_t hipFileGetParameterString(hipFileStringConfigParameter_t param, c
* @param param The configuration parameter
* @param value The value of the configuration parameter
*
* @return \hipFileError_t
* @return \hipfile_error_return
*
* @note Configuration parameter values may only be set when the driver is closed. Values are applied when the
* driver is opened.
Expand All @@ -1027,7 +1025,7 @@ hipFileError_t hipFileSetParameterSizeT(hipFileSizeTConfigParameter_t param, siz
* @param param The configuration parameter
* @param value The value of the configuration parameter
*
* @return \hipFileError_t
* @return \hipfile_error_return
*
* @note Configuration parameter values may only be set when the driver is closed. Values are applied when the
* driver is opened.
Expand All @@ -1042,7 +1040,7 @@ hipFileError_t hipFileSetParameterBool(hipFileBoolConfigParameter_t param, bool
* @param param The configuration parameter
* @param desc_str The value of the configuration parameter
*
* @return \hipFileError_t
* @return \hipfile_error_return
*
* @note Configuration parameter values may only be set when the driver is closed. Values are applied when the
* driver is opened.
Expand Down
Loading