POC: hipFile Python API using Cython bindings

.gitignore

@@ -6,3 +6,9 @@ build/
 
 # Ignore .cache directory generated by clangd
 .cache/
+
+# Ignore any Python Virtual Environments
+.venv/
+
+# Ignore any pycache files
+__pycache__/

python/CMakeLists.txt

@@ -0,0 +1,67 @@
+cmake_minimum_required(VERSION 3.21)
+project(hipfile-python LANGUAGES C)
+
+# ---- Python & Cython -----------------------------------------------------
+
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+find_program(CYTHON_EXECUTABLE cython REQUIRED)
+
+# ---- hipFile library & headers --------------------------------------------
+
+# hipfile.h location (default: sibling include/ directory)
+set(HIPFILE_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../include"
+    CACHE PATH "Path to directory containing hipfile.h")
+
+# libhipfile.so location
+find_library(HIPFILE_LIBRARY hipfile
+    HINTS
+        "${CMAKE_CURRENT_SOURCE_DIR}/../build/src/amd_detail"
+        "/opt/rocm/lib"
+)
+if(NOT HIPFILE_LIBRARY)
+    message(FATAL_ERROR
+        "Could not find libhipfile. Set -DHIPFILE_LIBRARY=<path> or "
+        "install hipfile to /opt/rocm.")
+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"
+)
+if(NOT HIP_INCLUDE_DIR)
+    message(FATAL_ERROR
+        "Could not find hip/hip_runtime_api.h. Set -DHIP_INCLUDE_DIR=<path> "
+        "or install HIP development headers.")
+endif()
+
+# ---- Cythonize ------------------------------------------------------------
+
+set(_PYX_SRC "${CMAKE_CURRENT_SOURCE_DIR}/hipfile/_hipfile.pyx")
+set(_C_OUT   "${CMAKE_CURRENT_BINARY_DIR}/_hipfile.c")
+
+add_custom_command(
+    OUTPUT  "${_C_OUT}"
+    COMMAND "${CYTHON_EXECUTABLE}" "${_PYX_SRC}" -o "${_C_OUT}" -3
+    DEPENDS
+        "${_PYX_SRC}"
+        "${CMAKE_CURRENT_SOURCE_DIR}/hipfile/_chipfile.pxd"
+    COMMENT "Cythonizing _hipfile.pyx"
+)
+
+# ---- Build extension module -----------------------------------------------
+# lint_cmake: -readability/wonkycase
+Python_add_library(_hipfile MODULE "${_C_OUT}" WITH_SOABI)
+# lint_cmake: +readability/wonkycase
+target_include_directories(_hipfile PRIVATE
+    "${HIPFILE_INCLUDE_DIR}"
+    "${HIP_INCLUDE_DIR}"
+)
+
+target_link_libraries(_hipfile PRIVATE "${HIPFILE_LIBRARY}")
+
+# _hipfile bindings only support AMD for now
+target_compile_definitions(_hipfile PRIVATE __HIP_PLATFORM_AMD__)
+
+install(TARGETS _hipfile DESTINATION hipfile)

python/README.md

@@ -0,0 +1,25 @@
+# hipFile Python Bindings
+
+> [!CAUTION] 
+> These bindings in particular are *experimental* and the API will change.
+
+## Building & Installing
+
+1. Setup a Python virtual environment.
+```bash
+$ python3 -m venv .venv
+```
+2. Activate the Python virtual environment.
+```bash
+$ source .venv/bin/activate
+```
+3. Build the C hipFile library. See [INSTALL.md](../INSTALL.md).
+4. Build & Install the hipFile package.
+```bash
+(.venv) $ pip install -e python -Ccmake.define.HIPFILE_INCLUDE_DIR=../include -Ccmake.define.HIP_INCLUDE_DIR=/opt/rocm/include
+```
+
+This will install an editable version of hipFile in your virtual environment.
+It is editable in the sense that any changes you make to the hipFile <ins>Python</ins>
+source code will be immediately available for any tests/scripts that use the hipFile library.
+Any changes to the <ins>Cython</ins> source code will require a rebuild step.

python/hipfile/__init__.py

@@ -0,0 +1,27 @@
+# pylint: disable=C0114
+
+from hipfile._hipfile import (  # pylint: disable=E0401,E0611
+    # Constants
+    VERSION_MAJOR as _VERSION_MAJOR,
+    VERSION_MINOR as _VERSION_MINOR,
+    VERSION_PATCH as _VERSION_PATCH,
+)
+from hipfile.buffer import Buffer
+from hipfile.driver import Driver
+from hipfile.enums import FileHandleType, OpError
+from hipfile.error import HipFileException
+from hipfile.file import FileHandle
+from hipfile.properties import driver_get_properties, get_version
+
+__all__ = [
+    "__version__",
+    "Driver",
+    "FileHandle",
+    "Buffer",
+    "HipFileException",
+    "FileHandleType",
+    "OpError",
+    "driver_get_properties",
+    "get_version",
+]
+__version__ = f"{_VERSION_MAJOR}.{_VERSION_MINOR}.{_VERSION_PATCH}"

python/hipfile/_chipfile.pxd

@@ -0,0 +1,190 @@
+# cython: language_level=3
+"""
+C declarations for hipFile API (extern from hipfile.h).
+
+This .pxd file declares the subset of the hipFile C API that is
+wrapped by the low-level Cython bindings.
+"""
+
+from libc.stdint cimport int64_t, uint64_t
+from posix.types cimport off_t
+
+
+# ---------------------------------------------------------------------------
+#  HIP runtime stub — only hipError_t is needed
+# ---------------------------------------------------------------------------
+
+cdef extern from "hip/hip_runtime_api.h":
+    ctypedef enum hipError_t:
+        hipSuccess = 0
+
+    hipError_t hipPeekAtLastError()
+
+
+# ---------------------------------------------------------------------------
+#  hipFile public API
+# ---------------------------------------------------------------------------
+
+cdef extern from "hipfile.h":
+
+    # -- Version constants --------------------------------------------------
+
+    int HIPFILE_VERSION_MAJOR
+    int HIPFILE_VERSION_MINOR
+    int HIPFILE_VERSION_PATCH
+    int HIPFILE_BASE_ERR
+
+    # -- Platform-independent types -----------------------------------------
+
+    ctypedef off_t hoff_t
+
+    # -- Error handling -----------------------------------------------------
+
+    ctypedef enum hipFileOpError_t:
+        hipFileSuccess
+        hipFileDriverNotInitialized
+        hipFileDriverInvalidProps
+        hipFileDriverUnsupportedLimit
+        hipFileDriverVersionMismatch
+        hipFileDriverVersionReadError
+        hipFileDriverClosing
+        hipFilePlatformNotSupported
+        hipFileIONotSupported
+        hipFileDeviceNotSupported
+        hipFileDriverError
+        hipFileHipDriverError
+        hipFileHipPointerInvalid
+        hipFileHipMemoryTypeInvalid
+        hipFileHipPointerRangeError
+        hipFileHipContextMismatch
+        hipFileInvalidMappingSize
+        hipFileInvalidMappingRange
+        hipFileInvalidFileType
+        hipFileInvalidFileOpenFlag
+        hipFileDIONotSet
+        # 5021 intentionally unused
+        hipFileInvalidValue
+        hipFileMemoryAlreadyRegistered
+        hipFileMemoryNotRegistered
+        hipFilePermissionDenied
+        hipFileDriverAlreadyOpen
+        hipFileHandleNotRegistered
+        hipFileHandleAlreadyRegistered
+        hipFileDeviceNotFound
+        hipFileInternalError
+        hipFileGetNewFDFailed
+        # 5032 intentionally unused
+        hipFileDriverSetupError
+        hipFileIODisabled
+        hipFileBatchSubmitFailed
+        hipFileGPUMemoryPinningFailed
+        hipFileBatchFull
+        hipFileAsyncNotSupported
+        hipFileIOMaxError
+
+    ctypedef struct hipFileError_t:
+        hipFileOpError_t err
+        hipError_t hip_drv_err
+
+    # -- Opaque handles -----------------------------------------------------
+
+    ctypedef void *hipFileHandle_t
+
+    # -- File handle types --------------------------------------------------
+
+    ctypedef enum hipFileFileHandleType_t:
+        hipFileHandleTypeOpaqueFD
+        hipFileHandleTypeOpaqueWin32
+        hipFileHandleTypeUserspaceFS
+
+    # -- Userspace FS ops (opaque — only needed as pointer type) ------------
+
+    ctypedef struct hipFileFSOps_t:
+        pass
+
+    # -- File descriptor ----------------------------------------------------
+    # The anonymous union is accessed via Cython C-name strings.
+
+    ctypedef struct hipFileDescr_t:
+        hipFileFileHandleType_t type
+        int fd       "handle.fd"
+        void *hFile  "handle.hFile"
+        const hipFileFSOps_t *fs_ops
+
+    # -- Driver status / control / feature flag enums -----------------------
+
+    ctypedef enum hipFileDriverStatusFlags_t:
+        hipFileLustreSupported
+        hipFileWekaFSSupported
+        hipFileNFSSupported
+        hipFileGPFSSupported
+        hipFileNVMeSupported
+        hipFileNVMeoFSupported
+        hipFileSCSISupported
+        hipFileScaleFluxCSDSupported
+        hipFileNVMeshSupported
+        hipFileBeeGFSSupported
+        # 10 reserved for YRCloudFile
+        hipFileNVMeP2PSupported
+        hipFileScatefsSupported
+
+    ctypedef enum hipFileDriverControlFlags_t:
+        hipFileUsePollMode
+        hipFileAllowCompatMode
+
+    ctypedef enum hipFileFeatureFlags_t:
+        hipFileDynRoutingSupported
+        hipFileBatchIOSupported
+        hipFileStreamsSupported
+        hipFileParallelIOSupported
+
+    # -- Driver properties --------------------------------------------------
+    # Nested anonymous struct ``nvfs`` is flattened with C-name strings.
+
+    ctypedef struct hipFileDriverProps_t:
+        unsigned int nvfs_major_version        "nvfs.major_version"
+        unsigned int nvfs_minor_version        "nvfs.minor_version"
+        uint64_t     nvfs_poll_thresh_size     "nvfs.poll_thresh_size"
+        uint64_t     nvfs_max_direct_io_size   "nvfs.max_direct_io_size"
+        unsigned int nvfs_driver_status_flags  "nvfs.driver_status_flags"
+        unsigned int nvfs_driver_control_flags "nvfs.driver_control_flags"
+        unsigned int feature_flags
+        uint64_t     max_device_cache_size
+        uint64_t     per_buffer_cache_size
+        uint64_t     max_device_pinned_mem_size
+        unsigned int max_batch_io_count
+        unsigned int max_batch_io_timeout_msecs
+
+    # -- Function declarations ----------------------------------------------
+
+    # Error
+    const char *hipFileGetOpErrorString(hipFileOpError_t status)
+
+    # File handles
+    hipFileError_t hipFileHandleRegister(hipFileHandle_t *fh,
+                                         hipFileDescr_t *descr)
+    void hipFileHandleDeregister(hipFileHandle_t fh)
+
+    # Buffer registration
+    hipFileError_t hipFileBufRegister(const void *buffer_base,
+                                      size_t length, int flags)
+    hipFileError_t hipFileBufDeregister(const void *buffer_base)
+
+    # Synchronous I/O
+    ssize_t hipFileRead(hipFileHandle_t fh, void *buffer_base, size_t size,
+                        hoff_t file_offset, hoff_t buffer_offset)
+    ssize_t hipFileWrite(hipFileHandle_t fh, const void *buffer_base,
+                         size_t size, hoff_t file_offset,
+                         hoff_t buffer_offset)
+
+    # Driver lifecycle
+    hipFileError_t hipFileDriverOpen()
+    hipFileError_t hipFileDriverClose()
+    int64_t hipFileUseCount()
+
+    # Driver properties
+    hipFileError_t hipFileDriverGetProperties(hipFileDriverProps_t *props)
+
+    # Version
+    hipFileError_t hipFileGetVersion(unsigned *major, unsigned *minor,
+                                      unsigned *patch)