Asynchronous I/O API reference

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.

For a step-by-step guide to using these functions, see Asynchronous multi-stream I/O with registered streams.

Stream registration flags#

Flags passed to hipFileStreamRegister to optimize stream processing when transfer parameters are known at registration time.

HIPFILE_STREAM_FIXED_BUF_OFFSET#

Buffer offset is fixed at time of submission.

HIPFILE_STREAM_FIXED_FILE_OFFSET#

File offset is fixed at time of submission.

HIPFILE_STREAM_FIXED_FILE_SIZE#

File size is fixed at time of submission.

HIPFILE_STREAM_PAGE_ALIGNED_INPUTS#

Offsets and size are 4k aligned.

HIPFILE_STREAM_FLAGS_MASK#

Mask for selecting flag bits.

Asynchronous I/O and stream registration functions#

Functions to enqueue non-blocking reads and writes on HIP streams and to register and deregister streams with the hipFile driver.

HIPFILE_API hipFileError_t hipFileReadAsync(hipFileHandle_t fh, void *buffer_base, size_t *size_p, hoff_t *file_offset_p, hoff_t *buffer_offset_p, ssize_t *bytes_read_p, hipStream_t stream)#

Perform an asynchronous read from a stream.

Note

The maximum I/O size is determined by the Linux kernel and is currently 2^31 - the system page size

Parameters:

  • fh – [in] Opaque file handle for GPU I/O operations

  • buffer_base – [in] Base address of the GPU buffer

  • size_p – [in] Number of bytes that should be read

  • file_offset_p – [in] Offset into the file that should be read from

  • buffer_offset_p – [in] Offset of the GPU buffer that that the data should be written to

  • bytes_read_p – [out] Number of bytes read

  • stream – [in] The stream used for async I/O requests. If NULL, this request will be synchronous.

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileWriteAsync(hipFileHandle_t fh, void *buffer_base, size_t *size_p, hoff_t *file_offset_p, hoff_t *buffer_offset_p, ssize_t *bytes_written_p, hipStream_t stream)#

Perform an asynchronous write to a stream.

Note

The maximum I/O size is determined by the Linux kernel and is currently 2^31 - the system page size

Parameters:

  • fh – [in] Opaque file handle for GPU I/O operations

  • buffer_base – [in] Base address of the GPU buffer

  • size_p – [in] Number of bytes that should be written

  • file_offset_p – [in] Offset into the file that should be written to

  • buffer_offset_p – [in] Offset of the GPU buffer that that the data should be read from

  • bytes_written_p – [out] Number of bytes written

  • stream – [in] The stream used for async I/O requests. If NULL, this request will be synchronous.

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileStreamRegister(hipStream_t stream, unsigned flags)#

Register a stream to be used by for asynchronous GPU IO.

Parameters:

  • stream – [in] The stream used for async I/O requests

  • flags – [in] Flags that can optimize stream processing if parameters are known/are aligned at time of request submission

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileStreamDeregister(hipStream_t stream)#

Deregister a stream and free the associated resources.

Parameters:

stream – [in] The stream used for async I/O requests

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

Contents