hipfile 0.2.0.dev0__tar.gz → 0.3.0.dev0__tar.gz

hipfile-0.3.0.dev0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to the hipFile Python bindings will be documented in this file.
+
+## [Unreleased]
+
+## [0.3.0dev0]
+
+### Added
+
+- Docstrings for the public Python API.
+
+## [0.2.0.dev1]
+
+### Fixed
+
+- Release the Python GIL during all C function calls to prevent blocking other
+  threads during GPU IO operations. This resolves a performance regression
+  observed in multi-threaded applications (e.g., LMCache) when switching from
+  ctypes-based bindings to the Cython bindings.
+
+### Added
+
+- Complete typing hints for the public API.
+
+## [0.2.0.dev0]
+
+### Added
+
+- Initial release of the hipFile Python bindings.
+- Cython-based low-level wrappers for the hipFile C API (`_hipfile.pyx`).
+- High-level Pythonic API: `Driver`, `FileHandle`, `Buffer` classes with
+  context manager support.
+- `hipMalloc` / `hipFree` helpers for GPU memory allocation.
+- Error handling via `HipFileException` with hipFile and HIP driver error codes.
+- `FileHandleType` and `OpError` enums.
+- `get_version()` and `driver_get_properties()` utility functions.
+- scikit-build-core based build system.

{hipfile-0.2.0.dev0 → hipfile-0.3.0.dev0}/CMakeLists.txt

@@ -1,3 +1,7 @@
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
 cmake_minimum_required(VERSION 3.21)
 project(hipfile-python LANGUAGES C)
 
@@ -8,11 +12,27 @@ find_program(CYTHON_EXECUTABLE cython REQUIRED)
 
 # ---- hipFile library & headers --------------------------------------------
 
+# ROCm install hints: prefer $ROCM_PATH from env; fall back to a glob of
+# /opt/rocm/core-* (7.11+ layout) plus legacy /opt/rocm.
+if(DEFINED ENV{ROCM_PATH})
+    set(_ROCM_ROOTS "$ENV{ROCM_PATH}")
+else()
+    file(GLOB _ROCM_ROOTS "/opt/rocm/core-*")
+    list(APPEND _ROCM_ROOTS "/opt/rocm")
+endif()
+
+set(_ROCM_INCLUDE_HINTS)
+set(_ROCM_LIB_HINTS)
+foreach(_r IN LISTS _ROCM_ROOTS)
+    list(APPEND _ROCM_INCLUDE_HINTS "${_r}/include")
+    list(APPEND _ROCM_LIB_HINTS "${_r}/lib")
+endforeach()
+
 # hipfile.h location (prefer sibling include/ from source, fall back to installed)
 find_path(HIPFILE_INCLUDE_DIR hipfile.h
     HINTS
         "${CMAKE_CURRENT_SOURCE_DIR}/../include"
-        "/opt/rocm/include"
+        ${_ROCM_INCLUDE_HINTS}
     PATH "Path to directory containing hipfile.h"
 )
 if(NOT HIPFILE_INCLUDE_DIR)
@@ -25,7 +45,7 @@ endif()
 find_library(HIPFILE_LIBRARY hipfile
     HINTS
         "${CMAKE_CURRENT_SOURCE_DIR}/../build/src/amd_detail"
-        "/opt/rocm/lib"
+        ${_ROCM_LIB_HINTS}
 )
 if(NOT HIPFILE_LIBRARY)
     message(FATAL_ERROR
@@ -36,8 +56,7 @@ endif()
 # HIP runtime headers (needed because hipfile.h includes hip/hip_runtime_api.h)
 find_path(HIP_INCLUDE_DIR hip/hip_runtime_api.h
     HINTS
-        "/opt/rocm/include"
-        "/opt/rocm/hip/include"
+        ${_ROCM_INCLUDE_HINTS}
 )
 if(NOT HIP_INCLUDE_DIR)
     message(FATAL_ERROR

{hipfile-0.2.0.dev0 → hipfile-0.3.0.dev0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.2
 Name: hipfile
-Version: 0.2.0.dev0
+Version: 0.3.0.dev0
 Summary: Python bindings for hipFile — direct-to-GPU file IO via AMD Infinity Storage (AIS)
 Keywords: hipfile,rocm,amd,hip,AIS
 Maintainer-Email: AMD hipFile Team <hipfile-maintainer@amd.com>, Riley Dixon <riley.dixon@amd.com>
 License: MIT
 Classifier: Development Status :: 3 - Alpha
-Project-URL: homepage, https://github.com/ROCm/rocm-systems/tree/develop/projects/hipfile
+Project-URL: Homepage, https://github.com/ROCm/rocm-systems/tree/develop/projects/hipfile
+Project-URL: Changelog, https://github.com/ROCm/rocm-systems/blob/develop/projects/hipfile/python/CHANGELOG.md
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 

{hipfile-0.2.0.dev0 → hipfile-0.3.0.dev0}/hipfile/__init__.py

@@ -1,4 +1,8 @@
-# pylint: disable=C0114
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
+"""Python bindings for the hipFile GPU-accelerated file I/O library."""
 
 from hipfile._hipfile import (  # pylint: disable=E0401,E0611
     # Constants

{hipfile-0.2.0.dev0 → hipfile-0.3.0.dev0}/hipfile/_chipfile.pxd

@@ -18,7 +18,7 @@ cdef extern from "hip/hip_runtime_api.h":
     ctypedef enum hipError_t:
         hipSuccess = 0
 
-    hipError_t hipPeekAtLastError()
+    hipError_t hipPeekAtLastError() nogil
 
 
 # ---------------------------------------------------------------------------
@@ -158,33 +158,33 @@ cdef extern from "hipfile.h":
     # -- Function declarations ----------------------------------------------
 
     # Error
-    const char *hipFileGetOpErrorString(hipFileOpError_t status)
+    const char *hipFileGetOpErrorString(hipFileOpError_t status) nogil
 
     # File handles
     hipFileError_t hipFileHandleRegister(hipFileHandle_t *fh,
-                                         hipFileDescr_t *descr)
-    void hipFileHandleDeregister(hipFileHandle_t fh)
+                                         hipFileDescr_t *descr) nogil
+    void hipFileHandleDeregister(hipFileHandle_t fh) nogil
 
     # Buffer registration
     hipFileError_t hipFileBufRegister(const void *buffer_base,
-                                      size_t length, int flags)
-    hipFileError_t hipFileBufDeregister(const void *buffer_base)
+                                      size_t length, int flags) nogil
+    hipFileError_t hipFileBufDeregister(const void *buffer_base) nogil
 
     # Synchronous I/O
     ssize_t hipFileRead(hipFileHandle_t fh, void *buffer_base, size_t size,
-                        hoff_t file_offset, hoff_t buffer_offset)
+                        hoff_t file_offset, hoff_t buffer_offset) nogil
     ssize_t hipFileWrite(hipFileHandle_t fh, const void *buffer_base,
                          size_t size, hoff_t file_offset,
-                         hoff_t buffer_offset)
+                         hoff_t buffer_offset) nogil
 
     # Driver lifecycle
-    hipFileError_t hipFileDriverOpen()
-    hipFileError_t hipFileDriverClose()
-    int64_t hipFileUseCount()
+    hipFileError_t hipFileDriverOpen() nogil
+    hipFileError_t hipFileDriverClose() nogil
+    int64_t hipFileUseCount() nogil
 
     # Driver properties
-    hipFileError_t hipFileDriverGetProperties(hipFileDriverProps_t *props)
+    hipFileError_t hipFileDriverGetProperties(hipFileDriverProps_t *props) nogil
 
     # Version
     hipFileError_t hipFileGetVersion(unsigned *major, unsigned *minor,
-                                      unsigned *patch)
+                                      unsigned *patch) nogil

{hipfile-0.2.0.dev0 → hipfile-0.3.0.dev0}/hipfile/_hipfile.pyx

@@ -9,7 +9,7 @@ Functions that return ``hipFileError_t`` in C return a
 
 from libc.errno cimport errno
 from libc.string cimport memset
-from libc.stdint cimport uintptr_t
+from libc.stdint cimport int64_t, uintptr_t
 
 cimport hipfile._chipfile as _c
 
@@ -96,7 +96,9 @@ def is_hipfile_err(int err_code):
 
 def hipfile_errstr(int err_code):
     """Equivalent of the ``HIPFILE_ERRSTR`` C macro."""
-    cdef const char *s = _c.hipFileGetOpErrorString(<_c.hipFileOpError_t>abs(err_code))
+    cdef const char *s
+    with nogil:
+        s = _c.hipFileGetOpErrorString(<_c.hipFileOpError_t>abs(err_code))
     if s == NULL:
         return ""
     return s.decode("utf-8")
@@ -120,7 +122,9 @@ def hip_drv_err(tuple err):
 
 def hipFileGetOpErrorString(int status):
     """Wrapper for ``hipFileGetOpErrorString``."""
-    cdef const char *s = _c.hipFileGetOpErrorString(<_c.hipFileOpError_t>status)
+    cdef const char *s
+    with nogil:
+        s = _c.hipFileGetOpErrorString(<_c.hipFileOpError_t>status)
     if s == NULL:
         return ""
     return s.decode("utf-8")
@@ -132,17 +136,26 @@ def hipFileGetOpErrorString(int status):
 
 def hipFileDriverOpen():
     """Wrapper for ``hipFileDriverOpen``."""
-    return _err(_c.hipFileDriverOpen())
+    cdef _c.hipFileError_t e
+    with nogil:
+        e = _c.hipFileDriverOpen()
+    return _err(e)
 
 
 def hipFileDriverClose():
     """Wrapper for ``hipFileDriverClose``."""
-    return _err(_c.hipFileDriverClose())
+    cdef _c.hipFileError_t e
+    with nogil:
+        e = _c.hipFileDriverClose()
+    return _err(e)
 
 
 def hipFileUseCount():
     """Wrapper for ``hipFileUseCount``."""
-    return <int>_c.hipFileUseCount()
+    cdef int64_t count
+    with nogil:
+        count = _c.hipFileUseCount()
+    return <int>count
 
 
 # ---------------------------------------------------------------------------
@@ -155,7 +168,9 @@ def hipFileGetVersion():
     Returns ``((major, minor, patch), error_tuple)``.
     """
     cdef unsigned major = 0, minor = 0, patch = 0
-    cdef _c.hipFileError_t e = _c.hipFileGetVersion(&major, &minor, &patch)
+    cdef _c.hipFileError_t e
+    with nogil:
+        e = _c.hipFileGetVersion(&major, &minor, &patch)
     return ((major, minor, patch), _err(e))
 
 
@@ -178,19 +193,22 @@ def hipFileHandleRegister(uintptr_t handle_value, int handle_type):
     """
     cdef _c.hipFileHandle_t fh = NULL
     cdef _c.hipFileDescr_t descr
-    memset(&descr, 0, sizeof(descr))
-    descr.type = <_c.hipFileFileHandleType_t>handle_type
-    if handle_type == <int>_c.hipFileHandleTypeOpaqueWin32:
-        descr.hFile = <void *>handle_value
-    else:
-        descr.fd = <int>handle_value
-    cdef _c.hipFileError_t e = _c.hipFileHandleRegister(&fh, &descr)
+    cdef _c.hipFileError_t e
+    with nogil:
+        memset(&descr, 0, sizeof(descr))
+        descr.type = <_c.hipFileFileHandleType_t>handle_type
+        if handle_type == <int>_c.hipFileHandleTypeOpaqueWin32:
+            descr.hFile = <void *>handle_value
+        else:
+            descr.fd = <int>handle_value
+        e = _c.hipFileHandleRegister(&fh, &descr)
     return (<uintptr_t>fh, _err(e))
 
 
 def hipFileHandleDeregister(uintptr_t handle):
     """Wrapper for ``hipFileHandleDeregister``."""
-    _c.hipFileHandleDeregister(<_c.hipFileHandle_t>handle)
+    with nogil:
+        _c.hipFileHandleDeregister(<_c.hipFileHandle_t>handle)
 
 
 # ---------------------------------------------------------------------------
@@ -199,12 +217,18 @@ def hipFileHandleDeregister(uintptr_t handle):
 
 def hipFileBufRegister(uintptr_t buffer_base, size_t length, int flags=0):
     """Wrapper for ``hipFileBufRegister``."""
-    return _err(_c.hipFileBufRegister(<const void *>buffer_base, length, flags))
+    cdef _c.hipFileError_t e
+    with nogil:
+        e = _c.hipFileBufRegister(<const void *>buffer_base, length, flags)
+    return _err(e)
 
 
 def hipFileBufDeregister(uintptr_t buffer_base):
     """Wrapper for ``hipFileBufDeregister``."""
-    return _err(_c.hipFileBufDeregister(<const void *>buffer_base))
+    cdef _c.hipFileError_t e
+    with nogil:
+        e = _c.hipFileBufDeregister(<const void *>buffer_base)
+    return _err(e)
 
 
 # ---------------------------------------------------------------------------
@@ -222,14 +246,16 @@ def hipFileRead(uintptr_t handle, uintptr_t buffer_base, size_t size,
         ``-hipFileHipDriverError``, ``extra = hipError_t`` from
         ``hipPeekAtLastError()``, otherwise ``extra = 0``
     """
-    cdef ssize_t ret = _c.hipFileRead(<_c.hipFileHandle_t>handle,
-                                      <void *>buffer_base, size,
-                                      file_offset, buffer_offset)
+    cdef ssize_t ret
     cdef int extra = 0
-    if ret == -1:
-        extra = errno
-    elif ret == -<int>_c.hipFileHipDriverError:
-        extra = <int>_c.hipPeekAtLastError()
+    with nogil:
+        ret = _c.hipFileRead(<_c.hipFileHandle_t>handle,
+                             <void *>buffer_base, size,
+                             file_offset, buffer_offset)
+        if ret == -1:
+            extra = errno
+        elif ret == -<int>_c.hipFileHipDriverError:
+            extra = <int>_c.hipPeekAtLastError()
     return (ret, extra)
 
 
@@ -244,14 +270,16 @@ def hipFileWrite(uintptr_t handle, uintptr_t buffer_base, size_t size,
         ``-hipFileHipDriverError``, ``extra = hipError_t`` from
         ``hipPeekAtLastError()``, otherwise ``extra = 0``
     """
-    cdef ssize_t ret = _c.hipFileWrite(<_c.hipFileHandle_t>handle,
-                                       <const void *>buffer_base, size,
-                                       file_offset, buffer_offset)
+    cdef ssize_t ret
     cdef int extra = 0
-    if ret == -1:
-        extra = errno
-    elif ret == -<int>_c.hipFileHipDriverError:
-        extra = <int>_c.hipPeekAtLastError()
+    with nogil:
+        ret = _c.hipFileWrite(<_c.hipFileHandle_t>handle,
+                              <const void *>buffer_base, size,
+                              file_offset, buffer_offset)
+        if ret == -1:
+            extra = errno
+        elif ret == -<int>_c.hipFileHipDriverError:
+            extra = <int>_c.hipPeekAtLastError()
     return (ret, extra)
 
 
@@ -265,8 +293,10 @@ def hipFileDriverGetProperties():
     Returns ``(props_dict, error_tuple)``.
     """
     cdef _c.hipFileDriverProps_t props
-    memset(&props, 0, sizeof(props))
-    cdef _c.hipFileError_t e = _c.hipFileDriverGetProperties(&props)
+    cdef _c.hipFileError_t e
+    with nogil:
+        memset(&props, 0, sizeof(props))
+        e = _c.hipFileDriverGetProperties(&props)
     d = {
         "nvfs_major_version":        props.nvfs_major_version,
         "nvfs_minor_version":        props.nvfs_minor_version,

hipfile-0.3.0.dev0/hipfile/buffer.py

@@ -0,0 +1,133 @@
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
+"""GPU memory buffer registration for hipFile I/O."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from sys import stderr
+
+from hipfile._hipfile import (  # pylint: disable=E0401,E0611
+    hipFileBufDeregister,
+    hipFileBufRegister,
+)
+from hipfile.error import HipFileException
+
+if TYPE_CHECKING:
+    from ctypes import c_void_p
+    from types import TracebackType
+
+
+class Buffer:
+    """Manage registration of a GPU memory buffer with hipFile.
+
+    ``Buffer`` does **not** own the underlying GPU allocation; it only
+    manages the hipFile registration lifetime.
+
+    Supports the context-manager protocol for automatic
+    ``register``/``deregister``::
+
+        with Buffer.from_ctypes_void_p(ptr, length, 0) as buf:
+            fh.read(buf, length, 0, 0)
+    """
+
+    @classmethod
+    def from_ctypes_void_p(
+        cls, ctypes_void_p: c_void_p, length: int, flags: int
+    ) -> Buffer:
+        """Create a ``Buffer`` from a ``ctypes.c_void_p``.
+
+        Parameters
+        ----------
+        ctypes_void_p : ctypes.c_void_p
+            Pointer to GPU memory.  Must not be null.
+        length : int
+            Size of the buffer in bytes.
+        flags : int
+            Registration flags (pass ``0`` for default behavior).
+
+        Raises
+        ------
+        ValueError
+            If *ctypes_void_p* is null.
+        """
+        if ctypes_void_p.value is None:
+            raise ValueError("Cannot pass in a null pointer.")
+        return cls(ctypes_void_p.value, length, flags)
+
+    def __init__(self, buffer_ptr: int, length: int, flags: int) -> None:
+        """Initialize a ``Buffer`` from a raw integer pointer.
+
+        Parameters
+        ----------
+        buffer_ptr : int
+            Integer address of the GPU memory.
+        length : int
+            Size of the buffer in bytes.
+        flags : int
+            Registration flags (pass ``0`` for default behavior).
+        """
+        self._buffer_ptr = buffer_ptr
+        self._flags = flags
+        self._length = length
+        self._registered = False
+
+    def __del__(self) -> None:
+        """Deregister on garbage collection if still registered."""
+        # We did not create the underlying buffer. Don't try to free it.
+        try:
+            self.deregister()
+        except Exception:  # pylint: disable=W0718  # Suppress exceptions in a dtor
+            print(
+                "Failed to deregister hipFile.Buffer at destruction time.", file=stderr
+            )
+
+    def __enter__(self) -> Buffer:
+        """Register the buffer and return *self*."""
+        self.register()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Deregister the buffer."""
+        self.deregister()
+
+    @property
+    def ptr(self) -> int:
+        """Integer address of the GPU memory."""
+        return self._buffer_ptr
+
+    def deregister(self) -> None:
+        """Deregister the buffer from the hipFile driver.
+
+        This is a no-op if the buffer is not currently registered.
+
+        Raises
+        ------
+        HipFileException
+            If the deregistration call fails.
+        """
+        if self._registered:
+            err = hipFileBufDeregister(self._buffer_ptr)
+            if err[0] != 0:
+                raise HipFileException(err[0], err[1])
+            self._registered = False
+
+    def register(self) -> None:
+        """Register the buffer with the hipFile driver.
+
+        Raises
+        ------
+        HipFileException
+            If the registration call fails.
+        """
+        err = hipFileBufRegister(self._buffer_ptr, self._length, self._flags)
+        if err[0] != 0:
+            raise HipFileException(err[0], err[1])
+        self._registered = True

hipfile-0.3.0.dev0/hipfile/driver.py

@@ -0,0 +1,77 @@
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
+"""hipFile driver lifecycle management."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hipfile._hipfile import (  # pylint: disable=E0401,E0611
+    hipFileDriverOpen,
+    hipFileDriverClose,
+    hipFileUseCount,
+)
+from hipfile.error import HipFileException
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+
+class Driver:
+    """Manage the hipFile driver lifecycle.
+
+    Wraps the driver open/close calls and supports the
+    context-manager protocol::
+
+        with Driver() as drv:
+            ...  # driver is open
+        # driver is closed
+
+    The driver is reference-counted internally; multiple ``open``
+    calls are balanced by an equal number of ``close`` calls.
+    """
+
+    @staticmethod
+    def use_count() -> int:
+        """Return the current driver reference count."""
+        return hipFileUseCount()
+
+    def __enter__(self) -> Driver:
+        """Open the driver and return *self*."""
+        self.open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the driver."""
+        self.close()
+
+    def close(self) -> None:
+        """Close the hipFile driver.
+
+        Raises
+        ------
+        HipFileException
+            If the close call fails.
+        """
+        err = hipFileDriverClose()
+        if err[0] != 0:
+            raise HipFileException(err[0], err[1])
+
+    def open(self) -> None:
+        """Open the hipFile driver.
+
+        Raises
+        ------
+        HipFileException
+            If the open call fails.
+        """
+        err = hipFileDriverOpen()
+        if err[0] != 0:
+            raise HipFileException(err[0], err[1])

{hipfile-0.2.0.dev0 → hipfile-0.3.0.dev0}/hipfile/enums.py

@@ -1,4 +1,9 @@
-# pylint: disable=C0114,C0115,C0116
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
+"""Enumerations mirroring hipFile C types."""
+
 from enum import IntEnum
 
 from hipfile._hipfile import (  # pylint: disable=E0401,E0611

hipfile-0.3.0.dev0/hipfile/error.py

@@ -0,0 +1,54 @@
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
+"""Exception type for hipFile operations."""
+
+from __future__ import annotations
+
+from hipfile._hipfile import hipFileGetOpErrorString  # pylint: disable=E0401,E0611
+from hipfile.enums import OpError
+
+
+class HipFileException(Exception):
+    """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.
+    """
+
+    def __init__(self, hipfile_err: int, hip_err: int) -> None:
+        """Initialize a ``HipFileException``.
+
+        Parameters
+        ----------
+        hipfile_err : int
+            ``hipFileOpError_t`` value describing the failure.
+        hip_err : int
+            ``hipError_t`` value from the HIP runtime.  Only meaningful
+            when *hipfile_err* equals ``OpError.HIP_DRIVER_ERROR``.
+        """
+        self._hipfile_err = hipfile_err
+        self._hip_err = hip_err
+
+    @property
+    def hipfile_err(self) -> int:
+        """``hipFileOpError_t`` code for this error."""
+        return self._hipfile_err
+
+    @property
+    def hip_err(self) -> int:
+        """``hipError_t`` code from the HIP runtime.
+
+        Only meaningful when ``hipfile_err`` equals
+        ``OpError.HIP_DRIVER_ERROR``.
+        """
+        return self._hip_err
+
+    def __str__(self) -> str:
+        """Return a human-readable description of the error."""
+        err_msg = f"{self._hipfile_err} - {hipFileGetOpErrorString(self._hipfile_err)}"
+        if self._hipfile_err == OpError.HIP_DRIVER_ERROR:
+            err_msg += f" {self._hip_err}"
+        return err_msg

hipfile-0.3.0.dev0/hipfile/file.py

@@ -0,0 +1,271 @@
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
+"""GPU-accelerated file I/O through hipFile."""
+
+from __future__ import annotations
+
+import os
+import stat
+from sys import stderr
+from typing import TYPE_CHECKING
+
+from hipfile._hipfile import (  # pylint: disable=E0401,E0611
+    hipFileHandleRegister,
+    hipFileHandleDeregister,
+    hipFileRead,
+    hipFileWrite,
+)
+from hipfile.enums import FileHandleType
+from hipfile.error import HipFileException
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from hipfile.buffer import Buffer
+
+
+class FileHandle:
+    """Manage a file descriptor registered with the hipFile driver.
+
+    Wraps ``os.open``/``os.close`` together with hipFile handle
+    registration so that GPU-accelerated reads and writes can be
+    performed through a single object.
+
+    Supports the context-manager protocol for automatic
+    ``open``/``close``::
+
+        with FileHandle(path, os.O_RDONLY | os.O_DIRECT) as fh:
+            fh.read(buf, size, 0, 0)
+    """
+
+    DEFAULT_MODE = stat.S_IRUSR | stat.S_IWUSR | stat.S_IRGRP | stat.S_IROTH  # 0o644
+
+    def __init__(
+        self,
+        path: str | os.PathLike[str],
+        flags: int,
+        mode: int = DEFAULT_MODE,
+        handle_type: FileHandleType = FileHandleType.OPAQUE_FD,
+    ) -> None:
+        """Initialize a ``FileHandle``.
+
+        The file is **not** opened until ``open`` is called (or the
+        context manager is entered).
+
+        Parameters
+        ----------
+        path : str or os.PathLike[str]
+            Filesystem path to open.
+        flags : int
+            Flags passed to ``os.open`` (e.g. ``os.O_RDONLY | os.O_DIRECT``).
+        mode : int, optional
+            Permission bits used when creating a file.  Defaults to
+            ``0o644``.
+        handle_type : FileHandleType, optional
+            Type of handle to register.  Defaults to
+            ``FileHandleType.OPAQUE_FD``.
+        """
+        self._fd: int | None = None
+        self._flags = flags
+        self._handle: int | None = None
+        self._handle_type: FileHandleType | None = None
+        self._mode = mode
+        self._path = path
+
+        self.handle_type = handle_type
+
+    def __del__(self) -> None:
+        """Close on garbage collection if still open."""
+        try:
+            self.close()
+        except Exception:  # pylint: disable=W0718  # Suppress exceptions in a dtor
+            print(
+                "Failed to deregister hipFile.FileHandle at destruction time.",
+                file=stderr,
+            )
+
+    def __enter__(self) -> FileHandle:
+        """Open the file and return *self*."""
+        self.open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the file."""
+        self.close()
+
+    @property
+    def flags(self) -> int:
+        """Flags passed to ``os.open``."""
+        return self._flags
+
+    @property
+    def handle(self) -> int | None:
+        """Opaque hipFile handle, or ``None`` if not open."""
+        return self._handle
+
+    @property
+    def handle_type(self) -> FileHandleType | None:
+        """Handle type used for registration."""
+        return self._handle_type
+
+    @handle_type.setter
+    def handle_type(self, _handle_type: FileHandleType) -> None:
+        """Set the handle type.
+
+        Raises
+        ------
+        RuntimeError
+            If the file handle is already open.
+        ValueError
+            If *_handle_type* is not a ``FileHandleType`` member.
+        NotImplementedError
+            If *_handle_type* is ``OPAQUE_WIN32``.
+        """
+        if self._handle is not None:
+            raise RuntimeError("Cannot modify handle_type while FileHandle is open")
+        if _handle_type not in FileHandleType:
+            raise ValueError(f"'{_handle_type}' is not a member of enum FileHandleType")
+        if _handle_type == FileHandleType.OPAQUE_WIN32:
+            raise NotImplementedError(
+                "FileHandle does not currently support Win32 Handles"
+            )
+        self._handle_type = _handle_type
+
+    @property
+    def mode(self) -> int:
+        """File creation permission bits."""
+        return self._mode
+
+    @property
+    def path(self) -> str | os.PathLike[str]:
+        """Filesystem path."""
+        return self._path
+
+    def open(self) -> None:
+        """Open the file and register it with the hipFile driver.
+
+        Raises
+        ------
+        RuntimeError
+            If the file handle is already open.
+        HipFileException
+            If hipFile handle registration fails.
+        """
+        if self._handle is not None:
+            raise RuntimeError("The FileHandle is already open.")
+        self._fd = os.open(self._path, self._flags, self._mode)
+        handle, err = hipFileHandleRegister(self._fd, self._handle_type)
+        if err[0] != 0:
+            os.close(self._fd)
+            self._fd = None
+            raise HipFileException(err[0], err[1])
+        self._handle = handle
+
+    def close(self) -> None:
+        """Deregister the hipFile handle and close the file descriptor.
+
+        Safe to call multiple times; subsequent calls are no-ops.
+        """
+        if self._handle is not None:
+            hipFileHandleDeregister(self._handle)
+            self._handle = None
+        if self._fd is not None:
+            os.close(self._fd)
+            self._fd = None
+
+    def read(
+        self, buffer: Buffer, size: int, file_offset: int, buffer_offset: int
+    ) -> int:
+        """Read from the file into a GPU buffer.
+
+        Parameters
+        ----------
+        buffer : Buffer
+            GPU buffer to read into.
+        size : int
+            Number of bytes to read.
+        file_offset : int
+            Byte offset within the file to start reading from.
+        buffer_offset : int
+            Byte offset within the GPU buffer to read into.
+
+        Returns
+        -------
+        int
+            Number of bytes actually read.
+
+        Raises
+        ------
+        RuntimeError
+            If the file handle is not open.
+        OSError
+            On a system-level I/O error (wraps ``errno``).
+        HipFileException
+            On a hipFile or HIP driver error.
+        """
+        if self._handle is None:
+            raise RuntimeError("The FileHandle is not open.")
+        bytes_read, extra_err = hipFileRead(
+            self._handle, buffer.ptr, size, file_offset, buffer_offset
+        )
+        if bytes_read == -1:
+            # extra_err is errno
+            raise OSError(extra_err, os.strerror(extra_err))
+        if bytes_read < -1:
+            # hipFile Error
+            # If -bytes_read == OpError.HIP_DRIVER_ERROR, extra_err is hipError_t.
+            # Otherwise, extra_err is 0.
+            raise HipFileException(-bytes_read, extra_err)
+        return bytes_read
+
+    def write(
+        self, buffer: Buffer, size: int, file_offset: int, buffer_offset: int
+    ) -> int:
+        """Write from a GPU buffer into the file.
+
+        Parameters
+        ----------
+        buffer : Buffer
+            GPU buffer to write from.
+        size : int
+            Number of bytes to write.
+        file_offset : int
+            Byte offset within the file to start writing to.
+        buffer_offset : int
+            Byte offset within the GPU buffer to write from.
+
+        Returns
+        -------
+        int
+            Number of bytes actually written.
+
+        Raises
+        ------
+        RuntimeError
+            If the file handle is not open.
+        OSError
+            On a system-level I/O error (wraps ``errno``).
+        HipFileException
+            On a hipFile or HIP driver error.
+        """
+        if self._handle is None:
+            raise RuntimeError("The FileHandle is not open.")
+        bytes_written, extra_err = hipFileWrite(
+            self._handle, buffer.ptr, size, file_offset, buffer_offset
+        )
+        if bytes_written == -1:
+            # extra_err is errno
+            raise OSError(extra_err, os.strerror(extra_err))
+        if bytes_written < -1:
+            # hipFile Error
+            # If -bytes_written == OpError.HIP_DRIVER_ERROR, extra_err is hipError_t.
+            # Otherwise, extra_err is 0.
+            raise HipFileException(-bytes_written, extra_err)
+        return bytes_written

{hipfile-0.2.0.dev0 → hipfile-0.3.0.dev0}/hipfile/hipMalloc.py

@@ -1,4 +1,9 @@
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
 # pylint: disable=all
+
 """
 This is a hack to have some semblance of GPU memory management
 without introducing a dependency at this early stage of
@@ -28,6 +33,18 @@ _hip.hipFree.restype = ctypes.c_int
 
 
 def hipMalloc(size_bytes: int) -> ctypes.c_void_p:
+    """Allocate *size_bytes* of GPU device memory.
+
+    Returns
+    -------
+    ctypes.c_void_p
+        Pointer to the allocated device memory.
+
+    Raises
+    ------
+    RuntimeError
+        If the HIP runtime reports an error.
+    """
     d_ptr = ctypes.c_void_p()
     status = _hip.hipMalloc(ctypes.byref(d_ptr), ctypes.c_size_t(size_bytes))
     if status != 0:
@@ -36,6 +53,13 @@ def hipMalloc(size_bytes: int) -> ctypes.c_void_p:
 
 
 def hipFree(ptr: ctypes.c_void_p) -> None:
+    """Free GPU device memory previously allocated by ``hipMalloc``.
+
+    Raises
+    ------
+    RuntimeError
+        If the HIP runtime reports an error.
+    """
     status = _hip.hipFree(ptr)
     if status != 0:
         raise RuntimeError(f"hipFree failed ({status})")

hipfile-0.3.0.dev0/hipfile/properties.py

@@ -0,0 +1,51 @@
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
+"""Query hipFile driver properties and version information."""
+
+from __future__ import annotations
+
+from hipfile._hipfile import (  # pylint: disable=E0401,E0611
+    hipFileDriverGetProperties,
+    hipFileGetVersion,
+)
+from hipfile.error import HipFileException
+
+
+def driver_get_properties() -> dict[str, int]:
+    """Return the current hipFile driver properties.
+
+    Returns
+    -------
+    dict[str, int]
+        Property names mapped to their integer values.
+
+    Raises
+    ------
+    HipFileException
+        If the properties query fails.
+    """
+    _props, err = hipFileDriverGetProperties()
+    if err[0] != 0:
+        raise HipFileException(err[0], err[1])
+    return _props
+
+
+def get_version() -> tuple[int, int, int]:
+    """Return the hipFile driver version.
+
+    Returns
+    -------
+    tuple[int, int, int]
+        ``(major, minor, patch)`` version components.
+
+    Raises
+    ------
+    HipFileException
+        If the version query fails.
+    """
+    version_tuple, err = hipFileGetVersion()
+    if err[0] != 0:
+        raise HipFileException(err[0], err[1])
+    return version_tuple

{hipfile-0.2.0.dev0 → hipfile-0.3.0.dev0}/main.py

@@ -1,3 +1,7 @@
+# Copyright (c) Advanced Micro Devices, Inc. All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+
 """
 A quick & rough script for testing the Cython bindings to the
 hipFile C library. Reads a given file and copies it to an

{hipfile-0.2.0.dev0 → hipfile-0.3.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "hipfile"
-version = "0.2.0.dev0"
+version = "0.3.0.dev0"
 classifiers = [
     "Development Status :: 3 - Alpha",
 ]
@@ -19,7 +19,8 @@ readme = "README.md"
 requires-python = ">=3.10"
 
 [project.urls]
-homepage = "https://github.com/ROCm/rocm-systems/tree/develop/projects/hipfile"
+Homepage = "https://github.com/ROCm/rocm-systems/tree/develop/projects/hipfile"
+Changelog = "https://github.com/ROCm/rocm-systems/blob/develop/projects/hipfile/python/CHANGELOG.md"
 
 [tool.scikit-build]
 cmake.build-type = "Release"

hipfile-0.2.0.dev0/hipfile/buffer.py

@@ -1,59 +0,0 @@
-# pylint: disable=C0114,C0115,C0116
-from __future__ import annotations
-from typing import TYPE_CHECKING
-from sys import stderr
-
-from hipfile._hipfile import (  # pylint: disable=E0401,E0611
-    hipFileBufDeregister,
-    hipFileBufRegister,
-)
-from hipfile.error import HipFileException
-
-if TYPE_CHECKING:
-    from ctypes import c_void_p
-
-
-class Buffer:
-
-    @classmethod
-    def from_ctypes_void_p(cls, ctypes_void_p: c_void_p, length, flags):
-        return cls(ctypes_void_p.value, length, flags)
-
-    def __init__(self, buffer_ptr, length, flags) -> None:
-        self._buffer_ptr = buffer_ptr
-        self._flags = flags
-        self._length = length
-        self._registered = False
-
-    def __del__(self):
-        # We did not create the underlying buffer. Don't try to free it.
-        try:
-            self.deregister()
-        except Exception:  # pylint: disable=W0718  # Suppress exceptions in a dtor
-            print(
-                "Failed to deregister hipFile.Buffer at destruction time.", file=stderr
-            )
-
-    def __enter__(self):
-        self.register()
-        return self
-
-    def __exit__(self, exc_type, exc, tb):
-        self.deregister()
-
-    @property
-    def ptr(self):
-        return self._buffer_ptr
-
-    def deregister(self):
-        if self._registered:
-            err = hipFileBufDeregister(self._buffer_ptr)
-            if err[0] != 0:
-                raise HipFileException(err[0], err[1])
-            self._registered = False
-
-    def register(self):
-        err = hipFileBufRegister(self._buffer_ptr, self._length, self._flags)
-        if err[0] != 0:
-            raise HipFileException(err[0], err[1])
-        self._registered = True

hipfile-0.2.0.dev0/hipfile/driver.py

@@ -1,31 +0,0 @@
-# pylint: disable=C0114,C0115,C0116
-from hipfile._hipfile import (  # pylint: disable=E0401,E0611
-    hipFileDriverOpen,
-    hipFileDriverClose,
-    hipFileUseCount,
-)
-from hipfile.error import HipFileException
-
-
-class Driver:
-
-    @staticmethod
-    def use_count():
-        return hipFileUseCount()
-
-    def __enter__(self):
-        self.open()
-        return self
-
-    def __exit__(self, exc_type, exc_value, traceback):
-        self.close()
-
-    def close(self):
-        err = hipFileDriverClose()
-        if err[0] != 0:
-            raise HipFileException(err[0], err[1])
-
-    def open(self):
-        err = hipFileDriverOpen()
-        if err[0] != 0:
-            raise HipFileException(err[0], err[1])

hipfile-0.2.0.dev0/hipfile/error.py

@@ -1,23 +0,0 @@
-# pylint: disable=C0114,C0115,C0116
-from hipfile._hipfile import hipFileGetOpErrorString  # pylint: disable=E0401,E0611
-from hipfile.enums import OpError
-
-
-class HipFileException(Exception):
-    def __init__(self, hipfile_err, hip_err):
-        self._hipfile_err = hipfile_err
-        self._hip_err = hip_err
-
-    @property
-    def hipfile_err(self):
-        return self._hipfile_err
-
-    @property
-    def hip_err(self):
-        return self._hip_err
-
-    def __str__(self):
-        err_msg = f"{self._hipfile_err} - {hipFileGetOpErrorString(self._hipfile_err)}"
-        if self._hipfile_err == OpError.HIP_DRIVER_ERROR:
-            err_msg += f" {self._hip_err}"
-        return err_msg

hipfile-0.2.0.dev0/hipfile/file.py

@@ -1,128 +0,0 @@
-# pylint: disable=C0114,C0115,C0116
-import os
-import stat
-from sys import stderr
-
-from hipfile._hipfile import (  # pylint: disable=E0401,E0611
-    hipFileHandleRegister,
-    hipFileHandleDeregister,
-    hipFileRead,
-    hipFileWrite,
-)
-from hipfile.enums import FileHandleType
-from hipfile.error import HipFileException
-
-
-class FileHandle:
-    DEFAULT_MODE = stat.S_IRUSR | stat.S_IWUSR | stat.S_IRGRP | stat.S_IROTH
-
-    def __init__(
-        self, path, flags, mode=DEFAULT_MODE, handle_type=FileHandleType.OPAQUE_FD
-    ):
-        self._fd = None
-        self._flags = flags
-        self._handle = None
-        self._handle_type = None
-        self._mode = mode
-        self._path = path
-
-        self.handle_type = handle_type
-
-    def __del__(self):
-        try:
-            self.close()
-        except Exception:  # pylint: disable=W0718  # Suppress exceptions in a dtor
-            print(
-                "Failed to deregister hipFile.FileHandle at destruction time.",
-                file=stderr,
-            )
-
-    def __enter__(self):
-        self.open()
-        return self
-
-    def __exit__(self, exc_type, exc_value, traceback):
-        self.close()
-
-    @property
-    def flags(self):
-        return self._flags
-
-    @property
-    def handle(self):
-        return self._handle
-
-    @property
-    def handle_type(self):
-        return self._handle_type
-
-    @handle_type.setter
-    def handle_type(self, _handle_type):
-        if self._handle is not None:
-            raise RuntimeError("Cannot modify handle_type while FileHandle is open")
-        if _handle_type not in FileHandleType:
-            raise ValueError(f"'{_handle_type}' is not a member of enum FileHandleType")
-        if _handle_type == FileHandleType.OPAQUE_WIN32:
-            raise NotImplementedError(
-                "FileHandle does not currently support Win32 Handles"
-            )
-        self._handle_type = _handle_type
-
-    @property
-    def mode(self):
-        return self._mode
-
-    @property
-    def path(self):
-        return self._path
-
-    def open(self):
-        if self._handle is not None:
-            raise RuntimeError("The FileHandle is already open.")
-        self._fd = os.open(self._path, self._flags, self._mode)
-        handle, err = hipFileHandleRegister(self._fd, self._handle_type)
-        if err[0] != 0:
-            os.close(self._fd)
-            self._fd = None
-            raise HipFileException(err[0], err[1])
-        self._handle = handle
-
-    def close(self):
-        if self._handle is not None:
-            hipFileHandleDeregister(self._handle)
-            self._handle = None
-        if self._fd is not None:
-            os.close(self._fd)
-            self._fd = None
-
-    def read(self, buffer, size, file_offset, buffer_offset):
-        if self._handle is None:
-            raise RuntimeError("The FileHandle is not open.")
-        bytes_read, extra_err = hipFileRead(
-            self._handle, buffer.ptr, size, file_offset, buffer_offset
-        )
-        if bytes_read == -1:
-            # extra_err is errno
-            raise OSError(extra_err, os.strerror(extra_err))
-        if bytes_read < -1:
-            # hipFile Error
-            # If -bytes_read == OpError.HIP_DRIVER_ERROR, extra_err is hipError_t.
-            # Otherwise, extra_err is 0.
-            raise HipFileException(-bytes_read, extra_err)
-        return bytes_read
-
-    def write(self, buffer, size, file_offset, buffer_offset):
-        if self._handle is None:
-            raise RuntimeError("The FileHandle is not open.")
-        bytes_written, extra_err = hipFileWrite(
-            self._handle, buffer.ptr, size, file_offset, buffer_offset
-        )
-        if bytes_written == -1:
-            # extra_err is errno
-            raise OSError(extra_err, os.strerror(extra_err))
-        if bytes_written < -1:
-            # hipFile Error
-            # If -bytes_written == OpError.HIP_DRIVER_ERROR, extra_err is hipError_t.
-            # Otherwise, extra_err is 0.
-            raise HipFileException(-bytes_written, extra_err)
-        return bytes_written

hipfile-0.2.0.dev0/hipfile/properties.py

@@ -1,20 +0,0 @@
-# pylint: disable=C0114,C0116
-from hipfile._hipfile import (  # pylint: disable=E0401,E0611
-    hipFileDriverGetProperties,
-    hipFileGetVersion,
-)
-from hipfile.error import HipFileException
-
-
-def driver_get_properties():
-    _props, err = hipFileDriverGetProperties()
-    if err[0] != 0:
-        raise HipFileException(err[0], err[1])
-    return _props
-
-
-def get_version():
-    version_tuple, err = hipFileGetVersion()
-    if err[0] != 0:
-        raise HipFileException(err[0], err[1])
-    return version_tuple