gpu-aux 1.2.0__py3-none-any.whl

gpu_aux/__init__.py

@@ -0,0 +1,20 @@
+"""Direct Python access to DisplayPort AUX functions."""
+
+from .adl import Adapter, AmdAux, AuxError, Port
+from .api import AuxPort, GpuPorts, enumerate_gpus, enumerate_gpus_and_ports, enumerate_ports
+from .intel import IntelAux
+from .nvapi import NvidiaAux
+
+__all__ = [
+    "Adapter",
+    "AmdAux",
+    "AuxError",
+    "AuxPort",
+    "GpuPorts",
+    "IntelAux",
+    "NvidiaAux",
+    "Port",
+    "enumerate_gpus",
+    "enumerate_gpus_and_ports",
+    "enumerate_ports",
+]

gpu_aux/adl.py

@@ -0,0 +1,370 @@
+from __future__ import annotations
+
+import ctypes
+import threading
+import time
+from dataclasses import dataclass
+from ctypes import POINTER, Structure, byref, c_char, c_int, c_uint8, c_uint32, c_void_p
+
+
+ADL_OK = 0
+ADL_DISPLAY_CONNECTED = 1
+AMD_VENDOR_IDS = {1002, 0x1002}
+ADL_CONNECTOR_DISPLAY_PORT = 15
+ADL_CONNECTOR_EDP = 16
+AUX_CONNECTORS = {ADL_CONNECTOR_DISPLAY_PORT, ADL_CONNECTOR_EDP}
+AUX_CHUNK_SIZE = 16
+RETRY_COUNT = 10
+
+
+class AuxError(RuntimeError):
+    """Raised when ADL or an AUX transaction fails."""
+
+
+class _ADLAdapterInfo(Structure):
+    _fields_ = [
+        ("iSize", c_int),
+        ("iAdapterIndex", c_int),
+        ("strUDID", c_char * 256),
+        ("iBusNumber", c_int),
+        ("iDeviceNumber", c_int),
+        ("iFunctionNumber", c_int),
+        ("iVendorID", c_int),
+        ("strAdapterName", c_char * 256),
+        ("strDisplayName", c_char * 256),
+        ("iPresent", c_int),
+        ("iExist", c_int),
+        ("strDriverPath", c_char * 256),
+        ("strDriverPathExt", c_char * 256),
+        ("strPNPString", c_char * 256),
+        ("iOSDisplayIndex", c_int),
+    ]
+
+
+class _ADLDisplayID(Structure):
+    _fields_ = [
+        ("iDisplayLogicalIndex", c_int),
+        ("iDisplayPhysicalIndex", c_int),
+        ("iDisplayLogicalAdapterIndex", c_int),
+        ("iDisplayPhysicalAdapterIndex", c_int),
+    ]
+
+
+class _ADLDisplayInfo(Structure):
+    _fields_ = [
+        ("displayID", _ADLDisplayID),
+        ("iDisplayControllerIndex", c_int),
+        ("strDisplayName", c_char * 256),
+        ("strDisplayManufacturerName", c_char * 256),
+        ("iDisplayType", c_int),
+        ("iDisplayOutputType", c_int),
+        ("iDisplayConnector", c_int),
+        ("iDisplayInfoMask", c_int),
+        ("iDisplayInfoValue", c_int),
+    ]
+
+
+class _NativeAuxRequest(Structure):
+    _fields_ = [
+        ("size", c_uint32),
+        ("result", c_uint32),
+        ("operation", c_uint32),
+        ("address", c_uint32),
+        ("data_size", c_uint32),
+        ("data", c_uint8 * AUX_CHUNK_SIZE),
+    ]
+
+
+assert ctypes.sizeof(_ADLAdapterInfo) == 0x624
+assert ctypes.sizeof(_ADLDisplayInfo) == 0x228
+assert ctypes.sizeof(_NativeAuxRequest) == 0x24
+
+
+def _text(value: bytes) -> str:
+    return value.split(b"\0", 1)[0].decode("utf-8", errors="replace")
+
+
+@dataclass(frozen=True)
+class Adapter:
+    index: int
+    name: str
+    display_name: str
+    bus: int
+    device: int
+    function: int
+    backend: str = "AMD"
+
+
+@dataclass(frozen=True)
+class Port:
+    adapter: Adapter
+    index: int
+    logical_display_index: int
+    physical_display_index: int
+    name: str
+    manufacturer: str
+    display_type: int
+    output_type: int
+    connector: int
+    connected: bool
+    backend: str = "adl"
+
+    @property
+    def identity(self) -> str:
+        return f"{self.backend}:{self.adapter.index}:{self.logical_display_index}"
+
+    @property
+    def kind(self) -> str:
+        return "eDP" if self.connector == ADL_CONNECTOR_EDP else "DP"
+
+
+class AmdAux:
+    """Direct binding to AMD ADL AUX and DDC functions.
+
+    ADL is process-global, so one instance serializes all transactions.
+    """
+
+    def __init__(self) -> None:
+        if ctypes.sizeof(c_void_p) != 8:
+            raise AuxError("gpu_aux requires 64-bit Python")
+        self._lock = threading.RLock()
+        self._closed = False
+        self._crt = ctypes.CDLL("msvcrt")
+        self._crt.malloc.argtypes = [ctypes.c_size_t]
+        self._crt.malloc.restype = c_void_p
+        self._crt.free.argtypes = [c_void_p]
+        self._alloc_type = ctypes.CFUNCTYPE(c_void_p, c_int)
+        self._allocator = self._alloc_type(self._allocate)
+        self._adl = self._load_adl()
+        self._bind()
+        self._check(self._adl.ADL_Main_Control_Create(self._allocator, 1), "ADL initialization")
+
+    @staticmethod
+    def _load_adl():
+        for name in ("atiadlxx.dll", "atiadlxy.dll"):
+            try:
+                return ctypes.CDLL(name)
+            except OSError:
+                pass
+        raise AuxError("AMD ADL library atiadlxx.dll was not found")
+
+    def _allocate(self, size: int):
+        return self._crt.malloc(size)
+
+    def _bind(self) -> None:
+        adl = self._adl
+        adl.ADL_Main_Control_Create.argtypes = [self._alloc_type, c_int]
+        adl.ADL_Main_Control_Create.restype = c_int
+        adl.ADL_Main_Control_Destroy.argtypes = []
+        adl.ADL_Main_Control_Destroy.restype = c_int
+        adl.ADL_Adapter_NumberOfAdapters_Get.argtypes = [POINTER(c_int)]
+        adl.ADL_Adapter_NumberOfAdapters_Get.restype = c_int
+        adl.ADL_Adapter_AdapterInfo_Get.argtypes = [c_void_p, c_int]
+        adl.ADL_Adapter_AdapterInfo_Get.restype = c_int
+        adl.ADL_Display_DisplayInfo_Get.argtypes = [c_int, POINTER(c_int), POINTER(c_void_p), c_int]
+        adl.ADL_Display_DisplayInfo_Get.restype = c_int
+        adl.ADL_Display_NativeAUXChannel_Access.argtypes = [c_int, c_int, POINTER(_NativeAuxRequest)]
+        adl.ADL_Display_NativeAUXChannel_Access.restype = c_int
+        adl.ADL_Display_DDCBlockAccess_Get.argtypes = [
+            c_int, c_int, c_int, c_int, c_int, c_void_p, POINTER(c_int), c_void_p
+        ]
+        adl.ADL_Display_DDCBlockAccess_Get.restype = c_int
+
+    @staticmethod
+    def _check(rc: int, operation: str) -> None:
+        if rc != ADL_OK:
+            raise AuxError(f"{operation} failed: ADL error {rc}")
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise AuxError("AmdAux is closed")
+
+    def close(self) -> None:
+        with self._lock:
+            if not self._closed:
+                self._adl.ADL_Main_Control_Destroy()
+                self._closed = True
+
+    def __enter__(self) -> "AmdAux":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()
+
+    def adapters(self) -> list[Adapter]:
+        with self._lock:
+            self._ensure_open()
+            count = c_int()
+            self._check(self._adl.ADL_Adapter_NumberOfAdapters_Get(byref(count)), "adapter enumeration")
+            raw = (_ADLAdapterInfo * count.value)()
+            for item in raw:
+                item.iSize = ctypes.sizeof(_ADLAdapterInfo)
+            self._check(self._adl.ADL_Adapter_AdapterInfo_Get(raw, ctypes.sizeof(raw)), "adapter information")
+            adapters = [
+                Adapter(
+                    index=item.iAdapterIndex,
+                    name=_text(item.strAdapterName),
+                    display_name=_text(item.strDisplayName),
+                    bus=item.iBusNumber,
+                    device=item.iDeviceNumber,
+                    function=item.iFunctionNumber,
+                )
+                for item in raw
+                if item.iPresent == 1 and item.iVendorID in AMD_VENDOR_IDS
+            ]
+            # ADL exposes one logical adapter per Windows DISPLAYx even when all
+            # entries refer to the same physical GPU. AUX ports belong to the
+            # physical PCI function, so retain one representative per BDF.
+            unique = {}
+            for adapter in adapters:
+                unique.setdefault((adapter.bus, adapter.device, adapter.function), adapter)
+            return list(unique.values())
+
+    def ports(self, adapter: Adapter, connected_only: bool = True) -> list[Port]:
+        with self._lock:
+            self._ensure_open()
+            count = c_int()
+            pointer = c_void_p()
+            self._check(
+                self._adl.ADL_Display_DisplayInfo_Get(adapter.index, byref(count), byref(pointer), 1),
+                "display enumeration",
+            )
+            try:
+                if not pointer.value or count.value <= 0:
+                    return []
+                raw = ctypes.cast(pointer, POINTER(_ADLDisplayInfo))
+                result = []
+                for position in range(count.value):
+                    item = raw[position]
+                    connected = bool(item.iDisplayInfoValue & ADL_DISPLAY_CONNECTED)
+                    if item.iDisplayConnector not in AUX_CONNECTORS:
+                        continue
+                    if connected_only and not connected:
+                        continue
+                    result.append(
+                        Port(
+                            adapter=adapter,
+                            index=position,
+                            logical_display_index=item.displayID.iDisplayLogicalIndex,
+                            physical_display_index=item.displayID.iDisplayPhysicalIndex,
+                            name=_text(item.strDisplayName),
+                            manufacturer=_text(item.strDisplayManufacturerName),
+                            display_type=item.iDisplayType,
+                            output_type=item.iDisplayOutputType,
+                            connector=item.iDisplayConnector,
+                            connected=connected,
+                        )
+                    )
+                return result
+            finally:
+                if pointer.value:
+                    self._crt.free(pointer)
+
+    @staticmethod
+    def _validate_port(port: Port) -> None:
+        if not port.connected:
+            raise ValueError("port is not connected")
+
+    def _native_aux(self, port: Port, operation: int, address: int, data: bytes) -> bytes:
+        self._validate_port(port)
+        if not 0 <= address <= 0xFFFFF:
+            raise ValueError("DPCD address must be in range 0x00000..0xFFFFF")
+        request = _NativeAuxRequest()
+        request.size = ctypes.sizeof(request)
+        request.operation = operation
+        request.address = address
+        request.data_size = len(data)
+        if operation == 1:
+            request.data[: len(data)] = data
+        rc = -1
+        for _ in range(RETRY_COUNT):
+            rc = self._adl.ADL_Display_NativeAUXChannel_Access(
+                port.adapter.index, port.logical_display_index, byref(request)
+            )
+            if rc == ADL_OK:
+                break
+            time.sleep(0.01)
+        self._check(rc, "DPCD read" if operation == 0 else "DPCD write")
+        if operation == 0 and request.data_size < len(data):
+            raise AuxError(f"DPCD read returned {request.data_size} of {len(data)} bytes")
+        return bytes(request.data[: len(data)])
+
+    def read_dpcd(self, port: Port, address: int, length: int) -> bytes:
+        if length <= 0:
+            raise ValueError("length must be positive")
+        with self._lock:
+            self._ensure_open()
+            output = bytearray()
+            while len(output) < length:
+                size = min(AUX_CHUNK_SIZE, length - len(output))
+                output += self._native_aux(port, 0, address + len(output), bytes(size))
+            return bytes(output)
+
+    def write_dpcd(self, port: Port, address: int, data: bytes) -> None:
+        data = bytes(data)
+        if not data:
+            raise ValueError("data must not be empty")
+        with self._lock:
+            self._ensure_open()
+            for offset in range(0, len(data), AUX_CHUNK_SIZE):
+                self._native_aux(port, 1, address + offset, data[offset : offset + AUX_CHUNK_SIZE])
+
+    @staticmethod
+    def _dev7(address: int) -> int:
+        if not 0 <= address <= 0xFF:
+            raise ValueError("I2C address must fit in one byte")
+        return address >> 1 if address >= 0x80 else address & 0x7F
+
+    def _ddc(self, port: Port, send: bytes, receive_length: int) -> bytes:
+        self._validate_port(port)
+        send_buffer = (c_uint8 * len(send)).from_buffer_copy(send)
+        receive_buffer = (c_uint8 * receive_length)() if receive_length else None
+        receive_size = c_int(receive_length)
+        rc = -1
+        for _ in range(RETRY_COUNT):
+            receive_size.value = receive_length
+            rc = self._adl.ADL_Display_DDCBlockAccess_Get(
+                port.adapter.index,
+                port.logical_display_index,
+                0,
+                0,
+                len(send),
+                send_buffer,
+                byref(receive_size),
+                receive_buffer,
+            )
+            if rc == ADL_OK:
+                break
+            time.sleep(0.01)
+        self._check(rc, "I2C-over-AUX transaction")
+        if receive_size.value < receive_length:
+            raise AuxError(f"I2C-over-AUX returned {receive_size.value} of {receive_length} bytes")
+        return bytes(receive_buffer) if receive_buffer is not None else b""
+
+    def i2c_read(self, port: Port, device: int, register: int, length: int) -> bytes:
+        if length <= 0 or not 0 <= register <= 0xFF:
+            raise ValueError("length must be positive and register must fit in one byte")
+        with self._lock:
+            self._ensure_open()
+            output = bytearray()
+            read_address = (self._dev7(device) << 1) | 1
+            while len(output) < length:
+                size = min(AUX_CHUNK_SIZE, length - len(output))
+                output += self._ddc(port, bytes((read_address, (register + len(output)) & 0xFF)), size)
+            return bytes(output)
+
+    def i2c_write(self, port: Port, device: int, register: int, data: bytes) -> None:
+        data = bytes(data)
+        if not data or not 0 <= register <= 0xFF:
+            raise ValueError("data must not be empty and register must fit in one byte")
+        with self._lock:
+            self._ensure_open()
+            write_address = self._dev7(device) << 1
+            if self._dev7(device) == 0x30:
+                if len(data) != 1:
+                    raise ValueError("EDID segment-pointer writes require exactly one byte")
+                self._ddc(port, bytes((write_address, data[0])), 0)
+                return
+            for offset in range(0, len(data), AUX_CHUNK_SIZE):
+                chunk = data[offset : offset + AUX_CHUNK_SIZE]
+                self._ddc(port, bytes((write_address, (register + offset) & 0xFF)) + chunk, 0)

gpu_aux/api.py

@@ -0,0 +1,240 @@
+"""Object-oriented public API for selecting and using one AUX port."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+
+from .adl import Adapter, AmdAux, AuxError, Port
+from .intel import IntelAux
+from .nvapi import NvidiaAux
+
+
+_context_lock = threading.RLock()
+_contexts = {}
+
+
+def _normalize_backend(backend: str) -> str:
+    if not isinstance(backend, str):
+        raise TypeError("backend must be 'AMD', 'NVIDIA', or 'INTEL'")
+    normalized = backend.strip().upper()
+    if normalized in {"AMD", "NVIDIA", "INTEL"}:
+        return normalized
+    raise ValueError("backend must be 'AMD', 'NVIDIA', or 'INTEL'")
+
+
+def _create_aux(backend: str):
+    if backend == "AMD":
+        return AmdAux()
+    if backend == "NVIDIA":
+        return NvidiaAux()
+    if backend == "INTEL":
+        return IntelAux()
+    raise ValueError("backend must be 'AMD', 'NVIDIA', or 'INTEL'")
+
+
+def _acquire_aux(backend: str):
+    normalized_backend = _normalize_backend(backend)
+    with _context_lock:
+        context = _contexts.get(normalized_backend)
+        if context is None:
+            context = [_create_aux(normalized_backend), 0]
+            _contexts[normalized_backend] = context
+        context[1] += 1
+        return context[0]
+
+
+def _release_aux(backend: str, aux) -> None:
+    normalized_backend = _normalize_backend(backend)
+    with _context_lock:
+        context = _contexts.get(normalized_backend)
+        if context is None or aux is not context[0] or context[1] <= 0:
+            return
+        context[1] -= 1
+        if context[1] == 0:
+            aux.close()
+            del _contexts[normalized_backend]
+
+
+@dataclass(frozen=True)
+class GpuPorts:
+    """A physical GPU and a snapshot of its connected DP/eDP ports."""
+
+    gpu_index: int
+    adapter: Adapter
+    ports: tuple[Port, ...]
+
+
+def enumerate_gpus(backend: str) -> list[Adapter]:
+    """Return physical GPUs for one backend without creating an ``AuxPort``."""
+
+    normalized_backend = _normalize_backend(backend)
+    aux = _acquire_aux(normalized_backend)
+    try:
+        return aux.adapters()
+    finally:
+        _release_aux(normalized_backend, aux)
+
+
+def enumerate_ports(backend: str, gpu_index: int = 0) -> list[Port]:
+    """Return connected DP/eDP ports on one GPU without creating an ``AuxPort``."""
+
+    if gpu_index < 0:
+        raise ValueError("gpu_index must not be negative")
+    normalized_backend = _normalize_backend(backend)
+    aux = _acquire_aux(normalized_backend)
+    try:
+        adapters = aux.adapters()
+        if gpu_index >= len(adapters):
+            raise AuxError(
+                f"GPU index {gpu_index} is unavailable for {normalized_backend}; "
+                f"found {len(adapters)} GPU(s)"
+            )
+        return aux.ports(adapters[gpu_index])
+    finally:
+        _release_aux(normalized_backend, aux)
+
+
+def enumerate_gpus_and_ports(backend: str) -> list[GpuPorts]:
+    """Return a combined GPU/port snapshot without creating an ``AuxPort``."""
+
+    normalized_backend = _normalize_backend(backend)
+    aux = _acquire_aux(normalized_backend)
+    try:
+        result = []
+        for gpu_index, adapter in enumerate(aux.adapters()):
+            result.append(
+                GpuPorts(
+                    gpu_index=gpu_index,
+                    adapter=adapter,
+                    ports=tuple(aux.ports(adapter)),
+                )
+            )
+        return result
+    finally:
+        _release_aux(normalized_backend, aux)
+
+
+class AuxPort:
+    """An opened DP/eDP AUX endpoint.
+
+    ``index`` is counted within ports of the requested kind on one physical
+    GPU. For example, ``AuxPort("DP", index=1, backend="NVIDIA")`` selects the
+    second external DP port on the first NVIDIA GPU.
+    """
+
+    def __init__(self, kind: str, index: int = 0, gpu_index: int = 0, *, backend: str) -> None:
+        self._aux = None
+        self._port = None
+
+        normalized_backend = _normalize_backend(backend)
+        normalized_kind = self._normalize_kind(kind)
+        if index < 0 or gpu_index < 0:
+            raise ValueError("index and gpu_index must not be negative")
+
+        aux = _acquire_aux(normalized_backend)
+        try:
+            adapters = aux.adapters()
+            if gpu_index >= len(adapters):
+                raise AuxError(
+                    f"GPU index {gpu_index} is unavailable for {normalized_backend}; "
+                    f"found {len(adapters)} GPU(s)"
+                )
+            adapter = adapters[gpu_index]
+            matching_ports = [
+                port for port in aux.ports(adapter) if port.kind == normalized_kind
+            ]
+            if index >= len(matching_ports):
+                raise AuxError(
+                    f"{normalized_kind} port index {index} is unavailable on GPU {gpu_index}; "
+                    f"found {len(matching_ports)} matching port(s)"
+                )
+            self._aux = aux
+            self._port = matching_ports[index]
+            self._backend = normalized_backend
+            self._gpu_index = gpu_index
+            self._kind_index = index
+        except Exception:
+            _release_aux(normalized_backend, aux)
+            raise
+
+    @staticmethod
+    def _normalize_kind(kind: str) -> str:
+        if not isinstance(kind, str):
+            raise TypeError("kind must be 'eDP' or 'DP'")
+        normalized = kind.strip().lower()
+        if normalized == "edp":
+            return "eDP"
+        if normalized == "dp":
+            return "DP"
+        raise ValueError("kind must be 'eDP' or 'DP'")
+
+    def _require_open(self) -> tuple[AmdAux, Port]:
+        if self._aux is None or self._port is None:
+            raise AuxError("AuxPort is closed")
+        return self._aux, self._port
+
+    @property
+    def info(self) -> Port:
+        """Return the immutable port information."""
+
+        return self._require_open()[1]
+
+    @property
+    def identity(self) -> str:
+        return self.info.identity
+
+    @property
+    def kind(self) -> str:
+        return self.info.kind
+
+    @property
+    def gpu_index(self) -> int:
+        self._require_open()
+        return self._gpu_index
+
+    @property
+    def backend(self) -> str:
+        self._require_open()
+        return self._backend
+
+    @property
+    def index(self) -> int:
+        self._require_open()
+        return self._kind_index
+
+    def read_dpcd(self, address: int, length: int) -> bytes:
+        aux, port = self._require_open()
+        return aux.read_dpcd(port, address, length)
+
+    def write_dpcd(self, address: int, data: bytes) -> None:
+        aux, port = self._require_open()
+        aux.write_dpcd(port, address, data)
+
+    def i2c_read(self, device: int, register: int, length: int) -> bytes:
+        aux, port = self._require_open()
+        return aux.i2c_read(port, device, register, length)
+
+    def i2c_write(self, device: int, register: int, data: bytes) -> None:
+        aux, port = self._require_open()
+        aux.i2c_write(port, device, register, data)
+
+    def close(self) -> None:
+        if self._aux is not None:
+            _release_aux(self._backend, self._aux)
+            self._aux = None
+            self._port = None
+
+    def __enter__(self) -> "AuxPort":
+        self._require_open()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            # Interpreter shutdown may have already released module globals.
+            pass