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. On the AMD backend, asynchronous operations are serviced through the fallback path rather than the fastpath.

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