Python API reference

Python API reference#

The hipFile Python package (hipfile) provides Cython-backed bindings for driver lifecycle management, file handle registration, GPU buffer registration, and error handling. All classes listed below mirror the corresponding C API surface in hipfile.h.

For a guided walkthrough of common operations with these bindings, see Use the Python API.

Module-level functions#

get_version#

hipfile.get_version() -> tuple[int, int, int]

Return the hipFile library version as a (major, minor, patch) tuple.

Raises HipFileException if the version query fails.

driver_get_properties#

hipfile.driver_get_properties() -> dict[str, int]

Return the current hipFile driver properties as a dictionary mapping property names to their integer values.

Raises HipFileException if the properties query fails.

Driver#

from hipfile import Driver

Manage the hipFile driver lifecycle. The driver is reference-counted internally; multiple open calls are balanced by an equal number of close calls.

Driver supports the context-manager protocol:

with Driver() as drv:
    ...  # driver is open
# driver is closed

Methods#

open()#

Open the hipFile driver. Raises HipFileException on failure.

close()#

Close the hipFile driver. Raises HipFileException on failure.

use_count() (static)#

Return the current driver reference count as an int.

FileHandle#

from hipfile import FileHandle

Manage a file descriptor registered with the hipFile driver. Wraps os.open and os.close together with hipFile handle registration so that GPU-accelerated reads and writes can be performed through a single object.

FileHandle supports the context-manager protocol:

with FileHandle(path, os.O_RDONLY | os.O_DIRECT) as fh:
    fh.read(buf, size, 0, 0)

Constructor#

FileHandle(
    path: str | os.PathLike[str],
    flags: int,
    mode: int = 0o644,
    handle_type: FileHandleType = FileHandleType.OPAQUE_FD,
)

The file is not opened until open() is called or the context manager is entered.

Note

Setting handle_type to FileHandleType.OPAQUE_WIN32 raises NotImplementedError.

Properties#

path#

Filesystem path (read-only).

flags#

Flags passed to os.open (read-only).

mode#

File creation permission bits (read-only). Defaults to 0o644.

handle_type#

FileHandleType used for registration. Can be set before the file is opened. Raises RuntimeError if the handle is already open, ValueError if the value is not a FileHandleType member, or NotImplementedError if set to OPAQUE_WIN32.

handle#

Opaque hipFile handle as an int, or None if the file is not open (read-only).

Methods#

open()#

Open the file and register it with the hipFile driver. Raises RuntimeError if already open or HipFileException if registration fails.

close()#

Deregister the hipFile handle and close the file descriptor. Safe to call multiple times; subsequent calls are no-ops.

read(buffer, size, file_offset, buffer_offset)#

Read size bytes from the file at file_offset into buffer at buffer_offset. Returns the number of bytes read.

Raises RuntimeError if the handle is not open, OSError on a system-level I/O error, or HipFileException on a hipFile or HIP driver error.

write(buffer, size, file_offset, buffer_offset)#

Write size bytes from buffer at buffer_offset to the file at file_offset. Returns the number of bytes written.

Raises RuntimeError if the handle is not open, OSError on a system-level I/O error, or HipFileException on a hipFile or HIP driver error.

Buffer#

from hipfile import Buffer

Manage registration of a GPU memory buffer with the hipFile driver. Buffer does not own the underlying GPU allocation; it only manages the hipFile registration lifetime.

Buffer supports the context-manager protocol:

with Buffer.from_ctypes_void_p(ptr, length, 0) as buf:
    fh.read(buf, length, 0, 0)

Class methods#

from_ctypes_void_p(ctypes_void_p, length, flags)#

Create a Buffer from a ctypes.c_void_p. Raises ValueError if the pointer is null.

Constructor#

Buffer(buffer_ptr: int, length: int, flags: int)

Initialize a Buffer from a raw integer pointer.

Properties#

ptr#

Integer address of the GPU memory (read-only).

Methods#

register()#

Register the buffer with the hipFile driver. Raises HipFileException on failure.

deregister()#

Deregister the buffer from the hipFile driver. This is a no-op if the buffer is not currently registered. Raises HipFileException on failure.

HipFileException#

from hipfile import HipFileException

Exception raised when a hipFile operation fails. Wraps both the hipFileOpError_t code and, when the error is HIP_DRIVER_ERROR, the underlying hipError_t from the HIP runtime.

Constructor#

HipFileException(hipfile_err: int, hip_err: int)

Properties#

hipfile_err#

hipFileOpError_t code for this error.

hip_err#

hipError_t code from the HIP runtime. Only meaningful when hipfile_err equals OpError.HIP_DRIVER_ERROR.

__str__#

Returns a human-readable description of the error, including the descriptive string from hipFileGetOpErrorString. When the error is OpError.HIP_DRIVER_ERROR, the HIP error code is appended.

Enumerations#

OpError#

from hipfile import OpError

IntEnum mirroring hipFileOpError_t. Values are sourced from the C enum through the Cython layer and are not redefined in Python. Members include:

Member

C equivalent

SUCCESS

hipFileSuccess

DRIVER_NOT_INITIALIZED

hipFileDriverNotInitialized

DRIVER_INVALID_PROPS

hipFileDriverInvalidProps

DRIVER_UNSUPPORTED_LIMIT

hipFileDriverUnsupportedLimit

DRIVER_VERSION_MISMATCH

hipFileDriverVersionMismatch

DRIVER_VERSION_READ_ERROR

hipFileDriverVersionReadError

DRIVER_CLOSING

hipFileDriverClosing

PLATFORM_NOT_SUPPORTED

hipFilePlatformNotSupported

IO_NOT_SUPPORTED

hipFileIONotSupported

DEVICE_NOT_SUPPORTED

hipFileDeviceNotSupported

DRIVER_ERROR

hipFileDriverError

HIP_DRIVER_ERROR

hipFileHipDriverError

HIP_POINTER_INVALID

hipFileHipPointerInvalid

HIP_MEMORY_TYPE_INVALID

hipFileHipMemoryTypeInvalid

HIP_POINTER_RANGE_ERROR

hipFileHipPointerRangeError

HIP_CONTEXT_MISMATCH

hipFileHipContextMismatch

INVALID_MAPPING_SIZE

hipFileInvalidMappingSize

INVALID_MAPPING_RANGE

hipFileInvalidMappingRange

INVALID_FILE_TYPE

hipFileInvalidFileType

INVALID_FILE_OPEN_FLAG

hipFileInvalidFileOpenFlag

DIO_NOT_SET

hipFileDIONotSet

INVALID_VALUE

hipFileInvalidValue

MEMORY_ALREADY_REGISTERED

hipFileMemoryAlreadyRegistered

MEMORY_NOT_REGISTERED

hipFileMemoryNotRegistered

PERMISSION_DENIED

hipFilePermissionDenied

DRIVER_ALREADY_OPEN

hipFileDriverAlreadyOpen

HANDLE_NOT_REGISTERED

hipFileHandleNotRegistered

HANDLE_ALREADY_REGISTERED

hipFileHandleAlreadyRegistered

DEVICE_NOT_FOUND

hipFileDeviceNotFound

INTERNAL_ERROR

hipFileInternalError

GET_NEW_FD_FAILED

hipFileGetNewFDFailed

DRIVER_SETUP_ERROR

hipFileDriverSetupError

IO_DISABLED

hipFileIODisabled

BATCH_SUBMIT_FAILED

hipFileBatchSubmitFailed

GPU_MEMORY_PINNING_FAILED

hipFileGPUMemoryPinningFailed

BATCH_FULL

hipFileBatchFull

ASYNC_NOT_SUPPORTED

hipFileAsyncNotSupported

IO_MAX_ERROR

hipFileIOMaxError

FileHandleType#

from hipfile import FileHandleType

IntEnum mirroring hipFileFileHandleType_t. Members:

Member

C equivalent

Notes

OPAQUE_FD

hipFileHandleTypeOpaqueFD

POSIX file descriptor

OPAQUE_WIN32

hipFileHandleTypeOpaqueWin32

Raises NotImplementedError

USERSPACE_FS

hipFileHandleTypeUserspaceFS

Userspace RDMA filesystem
Contents