Batch I/O API reference

Batch I/O API reference#

The hipFile batch I/O API lets you create batch contexts, submit multiple I/O 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.

Batch I/O types and functions#

Enumerations, structures, and handles used by batch I/O operations, together with the functions to create, submit, poll, cancel, and destroy batch I/O contexts.

enum hipFileOpcode_t#

The direction of data movement in a batch IO request.

Values:

enumerator hipFileBatchRead#: Read batch IO operation.

enumerator hipFileBatchWrite#: Write batch IO operation.

enum hipFileStatus_t#

The status of a batch IO operation.

Values:

enumerator hipFileWaiting#: Batch IO operation pending acceptance.

enumerator hipFilePending#: Batch IO operation accepted and queued.

enumerator hipFileInvalid#: Batch IO operation was rejected for being invalid or could not be queued.

enumerator hipFileCanceled#: Batch IO operation was canceled.

enumerator hipFileComplete#: Batch IO operation completed.

enumerator hipFileTimeout#: Batch IO operation timed out.

enumerator hipFileFailed#: Batch IO operation failed.

enum hipFileBatchMode_t#

Mode of a batch IO operation.

Values:

enumerator hipFileBatch#: Normal batch IO operation.

typedef void *hipFileBatchHandle_t#: Opaque batch operations handle.

HIPFILE_API hipFileError_t hipFileBatchIOSetUp(hipFileBatchHandle_t *batch_idp, unsigned max_nr)#

Prepare the system to perform batch IO operations.

Parameters:

batch_idp – [out] Opaque handle for batch operations
max_nr – [in] Size of the queue for this batch handle. Cannot exceed 128.

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileBatchIOSubmit(hipFileBatchHandle_t batch_idp, unsigned nr, hipFileIOParams_t *iocbp, unsigned flags)#

Enqueue a batch of IO requests for the GPU to complete asynchronously.

Parameters:

batch_idp – [in] Opaque handle for batch operations
nr – [in] Number of batch IO requests to submit
iocbp – [in] 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.
flags – [in] Control Flags for the batch IO. Currently unused.

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileBatchIOGetStatus(hipFileBatchHandle_t batch_idp, unsigned min_nr, unsigned *nr, hipFileIOEvents_t *iocbp, struct timespec *timeout)#

Poll for the status of completed batch IO operations.

Parameters:

batch_idp – [in] Opaque handle for batch operations
min_nr – [in] Minimum number of batch operation statuses that should be returned. If timeout is exceeded, fewer statuses may be returned.
nr – [inout] Maximum number of batch operation statuses that can be returned. This is parameter is modified to return the number of statuses returned in iocbp.
iocbp – [out] An array containing up to nr statuses from the overall batch operation
timeout – [in] Maximum amount of time this function should poll for status updates

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileBatchIOCancel(hipFileBatchHandle_t batch_idp)#

Cancels all pending batch IO operations.

Parameters:: batch_idp – [in] Opaque handle for batch operations
Returns:: A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API void hipFileBatchIODestroy(hipFileBatchHandle_t batch_idp)#

Destroys the batch IO handle and frees the associated resources.

Parameters:: batch_idp – [in] Opaque handle for batch operations

struct hipFileIOParams_t#

#include <hipfile.h>

Input parameters for a batch IO request.

Public Members

hipFileBatchMode_t mode#: Mode of the batch IO request.

void *devPtr_base#: Base address of the GPU buffer where data should be read/written.

int64_t file_offset#: Offset into the file that should be read/written.

int64_t devPtr_offset#: Offset of the GPU buffer that should be read/written.

size_t size#: Number of bytes to read or write.

struct hipFileIOParams_t batch#: Parameters for the read/write batch request.

union hipFileIOParams_t u#: Wrapping union for batch IO parameters.

hipFileHandle_t fh#: Registered hipFile handle for the target file.

hipFileOpcode_t opcode#: Direction data is moving for the batch request.

void *cookie#: Optionally used to track IO operations (e.g. self-reference pointer)

struct hipFileIOEvents_t#

#include <hipfile.h>

Status of a batch IO operation.

Public Members

void *cookie#: Optionally used to track IO operations (e.g. pointer to corresponding hipFileIOParams)

hipFileStatus_t status#: Status of the batch IO operation.

size_t ret#: Number of bytes transferred or error code. Cast to ssize_t to inspect. If non-negative, number of bytes transferred If negative, POSIX or hipFileOpError_t error

Batch I/O API reference

Contents

Batch I/O API reference#

Batch I/O types and functions#