Driver lifecycle and configuration API reference

Contents

Driver lifecycle and configuration API reference#

Functions and types for initializing and shutting down the GPU I/O driver, querying and setting driver properties, managing the library reference count, and reading or writing configuration parameters.

For a walkthrough of performing I/O after the driver is open, see Copy a file via GPU memory using hipFile.

Driver lifecycle and properties#

Driver property and flag types and the functions to open and close the GPU I/O driver, query the library reference count, and query or modify driver properties. See the Doxygen descriptions for current implementation status.

enum hipFileDriverStatusFlags_t#

Filesystems/storage protocols supported by GPU IO on this system.

Note

Value 10 is reserved for YRCloudFile

Values:

enumerator hipFileLustreSupported#

Lustre is supported.

enumerator hipFileWekaFSSupported#

Weka is supported.

enumerator hipFileNFSSupported#

NFS is supported.

enumerator hipFileGPFSSupported#

GPFS/IBM Storage Scale is supported.

enumerator hipFileNVMeSupported#

Local NVMe is supported.

enumerator hipFileNVMeoFSupported#

NVMeoF is supported.

enumerator hipFileSCSISupported#

SCSI is supported.

enumerator hipFileScaleFluxCSDSupported#

ScaleFlux CSD is supported.

enumerator hipFileNVMeshSupported#

NVMesh is supported.

enumerator hipFileBeeGFSSupported#

BeeGFS is supported.

enumerator hipFileNVMeP2PSupported#

NVMeP2P is supported.

enumerator hipFileScatefsSupported#

ScateFS is supported.

enum hipFileDriverControlFlags_t#

Control flags for passing to the GPU IO driver.

Values:

enumerator hipFileUsePollMode#

Enable polling for IO completion.

enumerator hipFileAllowCompatMode#

Allow GPU IO to fall back to POSIX IO.

enum hipFileFeatureFlags_t#

GPU IO Transport & Features supported by the system.

Values:

enumerator hipFileDynRoutingSupported#

RDMA dynamic routing is supported.

enumerator hipFileBatchIOSupported#

Batch operations are supported.

enumerator hipFileStreamsSupported#

Streams are supported.

enumerator hipFileParallelIOSupported#

Parallel IO is supported.

HIPFILE_API hipFileError_t hipFileDriverOpen(void)#

Initialize the GPU IO driver for this process.

Each call to hipFileDriverOpen() increments the library’s reference count. If a call to hipFileDriverOpen() results in the reference count transitioning from zero to one, the library’s state will be initialized.

Calling hipFileDriverOpen() is optional. The first call to hipFileBufRegister() or hipFileHandleRegister() will trigger library initialization and increment the library’s reference count.

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileDriverClose(void)#

Close the GPU IO driver for this process.

Each call to hipFileDriverClose() decrements the library’s reference count. If a call to hipFileDriverClose() results in the reference count transitioning from one to zero, the library’s state will be destroyed.

Explicitly closing the library is not required; the library’s state will be destroyed automatically at program exit.

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API int64_t hipFileUseCount(void)#

Obtain the current reference count for the library.

See also

hipFileDriverOpen()

See also

hipFileDriverClose()

Returns:

The library’s reference count

HIPFILE_API hipFileError_t hipFileDriverGetProperties(hipFileDriverProps_t *props)#

Get a list of GPU IO driver properties.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

props – [out] See hipFileDriverProps_t for what properties are reported

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileDriverSetPollMode(bool poll, size_t poll_threshold_size)#

Enable/disable polling mode for GPU IO.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

  • poll – [in] true to enable polling, false to disable

  • poll_threshold_size – [in] Maximum IO size (in KiB) for which polling is used when enabled

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileDriverSetMaxDirectIOSize(size_t max_direct_io_size)#

Set the maximum IO chunk size.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

max_direct_io_size – [in] Maximum IO chunk size (in KiB) for each IO request

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileDriverSetMaxCacheSize(size_t max_cache_size)#

Set the maximum amount of GPU memory that can be used for bounce buffers.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

max_cache_size – [in] Maximum GPU memory (in KiB) that can be reserved for bounce buffers

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileDriverSetMaxPinnedMemSize(size_t max_pinned_size)#

Set the maximum amount of GPU memory that can be pinned.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

max_pinned_size – [in] Maximum GPU memory (in KiB) that can be pinned

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

struct hipFileDriverProps_t#
#include <hipfile.h>

GPU IO configuration.

Core versioning and configuration#

Version macros, the offset type, configuration parameter selectors, and the functions to query the library version and read or write configuration parameters.

enum hipFileSizeTConfigParameter_t#

size_t configuration parameters

Values:

enumerator hipFileParamProfileStats#

Statistics.

enumerator hipFileParamExecutionMaxIOQueueDepth#

Max IO queue depth.

enumerator hipFileParamExecutionMaxIOThreads#

Max number of IO threads.

enumerator hipFileParamExecutionMinIOThresholdSizeKB#

Min IO threshold (KiB)

enumerator hipFileParamExecutionMaxRequestParallelism#

Max request parallelism.

enumerator hipFileParamPropertiesMaxDirectIOSizeKB#

Max direct IO size (KiB)

enumerator hipFileParamPropertiesMaxDeviceCacheSizeKB#

Max device cache size (KiB)

enumerator hipFileParamPropertiesPerBufferCacheSizeKB#

Max buffer cache size (KiB)

enumerator hipFileParamPropertiesMaxDevicePinnedMemSizeKB#

Max device pinned memory size (KiB)

enumerator hipFileParamPropertiesIOBatchsize#

IO batch size.

enumerator hipFileParamPollthresholdSizeKB#

Poll threshold size (KiB)

enumerator hipFileParamPropertiesBatchIOTimeoutMs#

Batch IO timeout (ms)

enum hipFileBoolConfigParameter_t#

Boolean configuration parameters.

Values:

enumerator hipFileParamPropertiesUsePollMode#

Use poll mode.

enumerator hipFileParamPropertiesAllowCompatMode#

Allow compatibility mode.

enumerator hipFileParamForceCompatMode#

Force compatibility mode.

enumerator hipFileParamFsMiscApiCheckAggressive#

Use aggressive checks in API calls.

enumerator hipFileParamExecutionParallelIO#

Allow parallel IO execution.

enumerator hipFileParamProfileNvtx#

Use NVTX profiler.

enumerator hipFileParamPropertiesAllowSystemMemory#

Allow system memory use.

enumerator hipFileParamUsePcip2pdma#

Use P2P DMA.

enumerator hipFileParamPreferIOUring#

Prefer io_uring.

enumerator hipFileParamForceOdirectMode#

Force O_DIRECT mode.

enumerator hipFileParamSkipTopologyDetection#

Skip topology detection.

enumerator hipFileParamStreamMemopsBypass#

Bypass stream memory operations.

enum hipFileStringConfigParameter_t#

String configuration parameters.

Values:

enumerator hipFileParamLoggingLevel#

Logging level.

enumerator hipFileParamEnvLogfilePath#

Logfile path.

enumerator hipFileParamLogDir#

Logfile directory.

HIPFILE_API hipFileError_t hipFileGetVersion(unsigned *major, unsigned *minor, unsigned *patch)#

Get the version of the hipFile library.

Note

Parameters can be set to NULL to ignore that part of the version

Parameters:

  • major – [out] The major version

  • minor – [out] The minor version

  • patch – [out] The patch version

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileGetParameterSizeT(hipFileSizeTConfigParameter_t param, size_t *value)#

Get the value of a size_t configuration parameter.

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*.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

  • param – The configuration parameter

  • value – The location to store the value of the configuration parameter

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileGetParameterBool(hipFileBoolConfigParameter_t param, bool *value)#

Get the value of a Boolean configuration parameter.

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*.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

  • param – The configuration parameter

  • value – The location to store the value of the configuration parameter

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileGetParameterString(hipFileStringConfigParameter_t param, char *desc_str, int len)#

Get the value of a string configuration parameter.

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*.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

  • param – The configuration parameter

  • desc_str – The location to store the value of the configuration parameter

  • len – The length of the desc_str parameter

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileSetParameterSizeT(hipFileSizeTConfigParameter_t param, size_t value)#

Set the value of a size_t configuration parameter.

Note

Configuration parameter values may only be set when the driver is closed. Values are applied when the driver is opened.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

  • param – The configuration parameter

  • value – The value of the configuration parameter

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileSetParameterBool(hipFileBoolConfigParameter_t param, bool value)#

Set the value of a Boolean configuration parameter.

Note

Configuration parameter values may only be set when the driver is closed. Values are applied when the driver is opened.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

  • param – The configuration parameter

  • value – The value of the configuration parameter

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileSetParameterString(hipFileStringConfigParameter_t param, const char *desc_str)#

Set the value of a string configuration parameter.

Note

Configuration parameter values may only be set when the driver is closed. Values are applied when the driver is opened.

Warning

This function is only a stub on AMD and will always return an error (typically hipFileInternalError with hip_drv_err set to hipSuccess)

Parameters:

  • param – The configuration parameter

  • desc_str – The value of the configuration parameter

Returns:

A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_VERSION_MAJOR#

hipFile major version number

HIPFILE_VERSION_MINOR#

hipFile minor version number

HIPFILE_VERSION_PATCH#

hipFile patch version number

Contents