|
| 1 | +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. |
| 2 | +# |
| 3 | +# SPDX-License-Identifier: Apache-2.0 |
| 4 | + |
| 5 | +"""Bridge the CUDA driver's ``cuLogs*`` error-log-management callback into |
| 6 | +the standard :mod:`logging` module. |
| 7 | +
|
| 8 | +The CUDA driver (CUDA 12.9+) maintains an internal, human-readable error/ |
| 9 | +warning log stream (see the *Error Log Management* section of the CUDA |
| 10 | +driver API docs) that is otherwise only observable via the ``CUDA_LOG_FILE`` |
| 11 | +environment variable or stderr. This module lets a caller route that stream |
| 12 | +into any :class:`logging.Logger`, so it can be filtered, captured (e.g. via |
| 13 | +pytest's ``caplog``), and forwarded using ordinary Python logging tooling. |
| 14 | +
|
| 15 | +xref: https://github.com/NVIDIA/cuda-python/issues/671 |
| 16 | +""" |
| 17 | + |
| 18 | +from __future__ import annotations |
| 19 | + |
| 20 | +import ctypes |
| 21 | +import logging |
| 22 | +import threading |
| 23 | + |
| 24 | +from cuda.bindings import driver as _driver |
| 25 | +from cuda.core._utils.cuda_utils import handle_return |
| 26 | + |
| 27 | +__all__ = ["register_cuda_log_bridge", "unregister_cuda_log_bridge"] |
| 28 | + |
| 29 | +# C callback signature expected by cuLogsRegisterCallback: |
| 30 | +# void callback(void *userData, CUlogLevel logLevel, char *message, size_t length) |
| 31 | +# |
| 32 | +# Note: cuLogsRegisterCallback requires an actual C function pointer. The |
| 33 | +# cuda.bindings wrapper does *not* accept a plain Python callable directly |
| 34 | +# (it only ever converts the `callbackFunc` argument to an integer address), |
| 35 | +# so we build a real function pointer via ctypes and pass its address. |
| 36 | +_CUlogsCallback_functype = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_size_t) |
| 37 | + |
| 38 | +# CUlogLevel currently only defines two levels (CUDA 12.9 cuLogs* API). |
| 39 | +# Anything unrecognized is conservatively mapped to ERROR. |
| 40 | +_CUDA_LEVEL_TO_PY_LEVEL = { |
| 41 | + int(_driver.CUlogLevel.CU_LOG_LEVEL_ERROR): logging.ERROR, |
| 42 | + int(_driver.CUlogLevel.CU_LOG_LEVEL_WARNING): logging.WARNING, |
| 43 | +} |
| 44 | + |
| 45 | +_lock = threading.Lock() |
| 46 | +# Must hold a reference to the ctypes callback for as long as it is |
| 47 | +# registered: once it is garbage collected, the driver would be left |
| 48 | +# holding a dangling function pointer and crash the process on the next |
| 49 | +# log message. |
| 50 | +_c_callback: ctypes._FuncPointer | None = None |
| 51 | +_callback_handle = None # CUlogsCallbackHandle, needed to unregister |
| 52 | + |
| 53 | + |
| 54 | +def _make_c_callback(logger: logging.Logger) -> ctypes._FuncPointer: |
| 55 | + """Build a ctypes C function pointer that forwards each driver log |
| 56 | + record to ``logger``. |
| 57 | + """ |
| 58 | + |
| 59 | + def _on_log(_user_data, log_level, message_ptr, length): |
| 60 | + # This runs inside a ctypes callback trampoline, potentially from a |
| 61 | + # CUDA-driver-internal thread. It must never raise or block. |
| 62 | + try: |
| 63 | + raw = ctypes.string_at(message_ptr, length) if message_ptr else b"" |
| 64 | + msg = raw.decode("utf-8", errors="replace").rstrip("\n") |
| 65 | + py_level = _CUDA_LEVEL_TO_PY_LEVEL.get(log_level, logging.ERROR) |
| 66 | + logger.log(py_level, "[CUDA Driver] %s", msg) |
| 67 | + except Exception: |
| 68 | + logger.exception("cuda_log_bridge: error while forwarding driver log") |
| 69 | + |
| 70 | + return _CUlogsCallback_functype(_on_log) |
| 71 | + |
| 72 | + |
| 73 | +def register_cuda_log_bridge(logger: logging.Logger | None = None) -> None: |
| 74 | + """Register a bridge that forwards CUDA driver ``cuLogs*`` messages to |
| 75 | + a Python :class:`logging.Logger`. |
| 76 | +
|
| 77 | + This is a process-wide, idempotent operation: the driver only supports |
| 78 | + a global log stream (not scoped to a context/stream/thread), so calling |
| 79 | + this again while a bridge is already registered is a no-op -- the |
| 80 | + logger passed to the first call remains in effect. |
| 81 | +
|
| 82 | + Parameters |
| 83 | + ---------- |
| 84 | + logger : logging.Logger, optional |
| 85 | + The logger that driver messages should be forwarded to. Defaults |
| 86 | + to ``logging.getLogger("cuda.driver")``. |
| 87 | +
|
| 88 | + Raises |
| 89 | + ------ |
| 90 | + cuda.core._utils.cuda_utils.CUDAError |
| 91 | + If the underlying ``cuLogsRegisterCallback`` call fails, e.g. |
| 92 | + because the loaded CUDA driver predates the 12.9 cuLogs* API. |
| 93 | + """ |
| 94 | + global _c_callback, _callback_handle |
| 95 | + |
| 96 | + if logger is None: |
| 97 | + logger = logging.getLogger("cuda.driver") |
| 98 | + |
| 99 | + with _lock: |
| 100 | + if _callback_handle is not None: |
| 101 | + return # already registered; idempotent |
| 102 | + |
| 103 | + c_callback = _make_c_callback(logger) |
| 104 | + addr = ctypes.cast(c_callback, ctypes.c_void_p).value |
| 105 | + |
| 106 | + handle = handle_return(_driver.cuLogsRegisterCallback(addr, None)) |
| 107 | + |
| 108 | + # Keep the ctypes callback object alive for as long as it is |
| 109 | + # registered (see the module-level comment on _c_callback above). |
| 110 | + _c_callback = c_callback |
| 111 | + _callback_handle = handle |
| 112 | + |
| 113 | + |
| 114 | +def unregister_cuda_log_bridge() -> None: |
| 115 | + """Unregister the bridge previously installed by |
| 116 | + :func:`register_cuda_log_bridge`. |
| 117 | +
|
| 118 | + Idempotent: safe to call even if no bridge is currently registered. |
| 119 | +
|
| 120 | + Raises |
| 121 | + ------ |
| 122 | + cuda.core._utils.cuda_utils.CUDAError |
| 123 | + If the underlying ``cuLogsUnregisterCallback`` call fails. |
| 124 | + """ |
| 125 | + global _c_callback, _callback_handle |
| 126 | + |
| 127 | + with _lock: |
| 128 | + if _callback_handle is None: |
| 129 | + return # nothing registered; idempotent |
| 130 | + |
| 131 | + handle_return(_driver.cuLogsUnregisterCallback(_callback_handle)) |
| 132 | + |
| 133 | + _c_callback = None |
| 134 | + _callback_handle = None |
0 commit comments