Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions .github/RELEASE-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,8 +101,7 @@ cuda-bindings floor" in `cuda_core/AGENTS.md`. Check the floors instead:
`cuda-bindings==<floor>`, and no "predates ... headers" line. Standard
CI does not install the CUDA 12 floor: its rows use the 12.9.x backport
build.
- The release notes list every floor move since the last release under
"Breaking Changes".
- The release notes list every floor move since the last release.

Update the `cuda-core` pin in `cuda_python/setup.py` to the new minor
series (`cuda-core~=X.Y.0`), and plan a `cuda-python` release right after
Expand Down
43 changes: 31 additions & 12 deletions ci/tools/cuda_core_bindings_floor.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,12 @@
from the checkout, so a nightly job that tests a wheel built from another
commit reads that wheel's floor.

The floors are declared once, by the `cu12`/`cu13` extras in
cuda_core/pyproject.toml, and the wheel's METADATA carries them as
`Requires-Dist: cuda-bindings[all]<14,>=13.4.1; extra == "cu13"`. This script
reads that line.
The floors are declared once, by the `minimal-sysctk12`/`minimal-sysctk13`
extras in cuda_core/pyproject.toml, which the `cu12`/`cu13` extras include. The
wheel's METADATA carries them as
`Requires-Dist: cuda-bindings<14,>=13.4.1; extra == "minimal-sysctk13"` and
`Requires-Dist: cuda-core[minimal-sysctk13]; extra == "cu13"`. This script
reads the floor of the `cu<major>` extra, following that self-reference.
"""

from __future__ import annotations
Expand All @@ -28,21 +30,38 @@
import zipfile
from pathlib import Path

# The cuda-bindings requirement of one `cu<major>` extra in METADATA. The name
# is followed by `[`, an operator or whitespace so that other names do not match.
# A cuda-bindings requirement of one extra in METADATA. The name is followed by
# `[`, an operator or whitespace so that other names do not match.
_REQUIRES_DIST_RE = re.compile(
r"^Requires-Dist:\s*cuda-bindings(?=[\[<>=!~\s])(?P<spec>[^;]*);\s*extra\s*==\s*['\"]cu(?P<major>\d+)['\"]"
r"^Requires-Dist:\s*cuda-bindings(?=[\[<>=!~\s])(?P<spec>[^;]*);\s*extra\s*==\s*['\"](?P<extra>[^'\"]+)['\"]"
)
# A self-reference of one extra, such as `cuda-core[minimal-sysctk13]; extra == "cu13"`.
_SELF_REFERENCE_RE = re.compile(
r"^Requires-Dist:\s*cuda-core\s*\[(?P<extras>[^\]]*)\]\s*;\s*extra\s*==\s*['\"](?P<extra>[^'\"]+)['\"]"
)
_FLOOR_RE = re.compile(r">=\s*(\d+)\.(\d+)\.(\d+)")


def _bindings_requirements(metadata: str, extra: str, seen: tuple[str, ...] = ()) -> list[tuple[str, str]]:
"""(line, specifier) of each versioned cuda-bindings requirement of `extra`, following self-references."""
seen = (*seen, extra)
found = []
for line in metadata.splitlines():
if (m := _REQUIRES_DIST_RE.match(line)) is not None and m.group("extra") == extra:
# An unversioned requirement such as `cuda-bindings[all]` only selects extras of cuda-bindings.
if re.sub(r"\[[^\]]*\]", "", m.group("spec")).strip():
found.append((line, m.group("spec")))
elif (m := _SELF_REFERENCE_RE.match(line)) is not None and m.group("extra") == extra:
for name in (name.strip() for name in m.group("extras").split(",")):
if name and name not in seen:
found.extend(_bindings_requirements(metadata, name, seen))
return found


def floor_from_metadata(metadata: str, major: int) -> str:
"""The floor that the `cu<major>` extra of a wheel's METADATA pins cuda-bindings to."""
for line in metadata.splitlines():
m = _REQUIRES_DIST_RE.match(line)
if m is None or int(m.group("major")) != major:
continue
floor = _FLOOR_RE.search(m.group("spec"))
for line, spec in _bindings_requirements(metadata, f"cu{major}"):
floor = _FLOOR_RE.search(spec)
if floor is None:
raise SystemExit(f"METADATA pins cuda-bindings without a floor for the cu{major} extra: {line.strip()!r}")
if int(floor.group(1)) != major:
Expand Down
35 changes: 35 additions & 0 deletions ci/tools/tests/test_cuda_core_bindings_floor.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,41 @@ def test_ignores_lookalike_names_and_other_extras():
assert tool.floor_from_metadata(metadata, 13) == "13.4.1"


# The layout in which cu<N> includes minimal-sysctk<N>, which pins the floor.
SELF_REFERENCING_METADATA = """\
Metadata-Version: 2.4
Name: cuda-core
Version: 1.3.1
Requires-Dist: cuda-pathfinder>=1.4.2
Requires-Dist: numpy
Provides-Extra: minimal-sysctk12
Requires-Dist: cuda-bindings<13,>=12.9.8; extra == "minimal-sysctk12"
Provides-Extra: minimal-sysctk13
Requires-Dist: cuda-bindings<14,>=13.5.0; extra == "minimal-sysctk13"
Provides-Extra: cu12
Requires-Dist: cuda-core[minimal-sysctk12]; extra == "cu12"
Requires-Dist: cuda-bindings[all]; extra == "cu12"
Requires-Dist: cuda-toolkit==12.*; extra == "cu12"
Provides-Extra: cu13
Requires-Dist: cuda-core[minimal-sysctk13]; extra == "cu13"
Requires-Dist: cuda-bindings[all]; extra == "cu13"
Requires-Dist: cuda-toolkit==13.*; extra == "cu13"
"""


@pytest.mark.agent_authored(model="claude-opus-5-5")
@pytest.mark.parametrize(("major", "floor"), [(12, "12.9.8"), (13, "13.5.0")])
def test_follows_the_self_reference_of_a_cu_extra(tmp_path, major, floor):
assert tool.floor_from_wheel(_wheel(tmp_path, SELF_REFERENCING_METADATA), major) == floor


@pytest.mark.agent_authored(model="claude-opus-5-5")
def test_rejects_a_self_reference_to_an_extra_without_cuda_bindings():
metadata = 'Requires-Dist: cuda-core[minimal-sysctk13]; extra == "cu13"\nRequires-Dist: cuda-bindings[all]; extra == "cu13"\n'
with pytest.raises(SystemExit, match="no cuda-bindings requirement for the cu13 extra"):
tool.floor_from_metadata(metadata, 13)


@pytest.mark.agent_authored(model="claude-fable-5-1")
def test_rejects_a_missing_extra(tmp_path):
with pytest.raises(SystemExit, match="no cuda-bindings requirement for the cu11 extra"):
Expand Down
20 changes: 12 additions & 8 deletions cuda_core/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,18 +74,21 @@ Nothing else moves a floor. A new `cuda-bindings` release does not, and a
`cuda.core` release does not. Do not raise a floor to the newest release. To
bump:

1. Edit the `cuda-bindings` pin in the `cu12` or `cu13` extra in
`pyproject.toml`. That is the only version to type.
1. Edit the `cuda-bindings` pin in the `minimal-sysctk12` or
`minimal-sysctk13` extra in `pyproject.toml`. That is the only version to
type. The `cu12` and `cu13` extras include these extras and carry no
version of their own.
2. Check `ci/versions.yml`. The `build` pin is the current major and the
`prev_build` pin is the prior major. Neither toolkit pin may sit below its
floor's major.minor, or CI builds a configuration that the build rejects. A
toolkit ahead of the floor is the bump window described below. The
pre-commit hook `check-cuda-core-bindings-floor`
(`toolshed/check_cuda_core_bindings_floor.py`) checks the pins. It also
checks that no documentation page spells a floor out by hand.
3. Add to the release notes a "Breaking Changes" entry that names the new
floors. The support-policy table in `docs/source/support.rst` reads the
floors and the release version at docs-build time. It needs no edit.
validates the extras and checks that no documentation page spells a floor
out by hand.
3. Add to the release notes an entry that names the new floors. The
support-policy table in `docs/source/support.rst` reads the floors and the
release version at docs-build time. It needs no edit.
4. If the pins moved past what the pixi lock files resolve, refresh the lock
files.
5. Pin `cuda-bindings` to match in the conda-forge `cuda-core` feedstock. The
Expand Down Expand Up @@ -119,8 +122,9 @@ the literal floor, until the floor is bumped. The order is:
is normally its first release.

A `cuda.core` release must not ship while the window is open. In the window,
the `cu<major>` extra can resolve to a `cuda-bindings` that fails the header
check at import, and CI does not test the literal floor.
the `minimal-sysctk<major>` and `cu<major>` extras can resolve to a
`cuda-bindings` that fails the header check at import, and CI does not test
the literal floor.

## Testing expectations

Expand Down
2 changes: 2 additions & 0 deletions cuda_core/DESCRIPTION.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,6 @@ Installation

pip install cuda-core[cu12]

Use ``[cu13]`` for CUDA 13. With a CUDA Toolkit installed on the system, ``[minimal-sysctk12]`` and ``[minimal-sysctk13]`` install only ``cuda-bindings``.

Please refer to the `installation instructions <https://nvidia.github.io/cuda-python/cuda-core/latest/install.html>`_ for different ways of installing ``cuda.core``, including building from source.
42 changes: 36 additions & 6 deletions cuda_core/cuda/core/_bindings_floor.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,13 @@
https://github.com/NVIDIA/cuda-python/issues/2783 and the support policy in the
documentation.

Exactly one place declares the floors: the ``cu12`` and ``cu13`` extras in
``pyproject.toml``. Each extra pins ``cuda-bindings>=<floor>,<<next major>``.
Everything else derives from them through :func:`floors_from_extras`:
Exactly one place declares the floors: the ``minimal-sysctk12`` and
``minimal-sysctk13`` extras in ``pyproject.toml``. Each pins
``cuda-bindings>=<floor>,<<next major>``. The ``cu12`` and ``cu13`` extras
include them through a ``cuda-core[minimal-sysctk<major>]`` self-reference, so
that pip and uv see the floor whichever extra a dependent requests. Everything
else reads the floor of each ``cu<major>`` extra, following that
self-reference, through :func:`floors_from_extras`:

- The build backend, ``build_hooks.py``, checks the installed cuda-bindings
against the floor. It checks that the ``cuda.h`` that it compiles against is
Expand All @@ -28,6 +32,8 @@
- The documentation reads the floors into substitutions in ``docs/source/conf.py``.
- ``toolshed/check_cuda_core_bindings_floor.py``, a pre-commit hook, checks
that the CI toolkit pins in ``ci/versions.yml`` sit in the minors of the floors.
It also validates the extras and checks that each ``cu<major>`` extra includes
its ``minimal-sysctk<major>`` extra.

The build and the tools above load this module by file path. It therefore uses
the standard library only and must not import anything from ``cuda``.
Expand Down Expand Up @@ -56,6 +62,8 @@
_REQUIREMENT_RE = re.compile(
r"^\s*cuda-bindings(?=[\[<>=!~;\s]|$)\s*(?:\[[^\]]*\])?\s*(?P<specifiers>[^;]*?)\s*(?:;.*)?$"
)
# A self-reference such as `cuda-core[minimal-sysctk13]`, up to an optional environment marker.
_SELF_REFERENCE_RE = re.compile(r"^\s*cuda-core\s*\[(?P<extras>[^\]]*)\]\s*(?:;.*)?$")
_FLOOR_SPEC_RE = re.compile(r"^>=(\d+)\.(\d+)\.(\d+)$")
# The upper bound: `<14`, `<14.0` or `<14.0.0`, or the equivalent `==13.*`.
_UPPER_SPEC_RE = re.compile(r"^<(\d+)(?:\.0)*$")
Expand Down Expand Up @@ -92,20 +100,27 @@ def floors_from_extras(extras: Mapping[str, Sequence[str]]) -> dict[int, tuple[i
"""The floor per CUDA major, from the ``cu<major>`` extras of ``pyproject.toml``.

``extras`` is the parsed ``[project.optional-dependencies]`` table. Each
``cu<N>`` extra must list exactly one cuda-bindings requirement with two
``cu<N>`` extra must list exactly one versioned cuda-bindings requirement,
either itself or through a ``cuda-core[<extra>]`` self-reference such as
``cuda-core[minimal-sysctk<N>]``. An unversioned requirement such as
``cuda-bindings[all]`` does not count. The requirement has two
specifiers, in either order. One is the floor, ``>=<N>.<minor>.<patch>``.
The other is an upper bound that excludes the next major, ``<<N+1>`` or
``==<N>.*``. Anything else raises ValueError with the name of the extra, so
a typo fails the build and the pre-commit hook instead of a silent shift of
the floor.
"""
floors: dict[int, tuple[int, int, int]] = {}
for extra, requirements in extras.items():
for extra in extras:
m = _EXTRA_RE.match(extra)
if m is None:
continue
major = int(m.group(1))
matches = [(r, rm) for r in requirements if (rm := _REQUIREMENT_RE.match(r)) is not None]
matches = [
(r, rm)
for r in _expand_self_references(extras, extra)
if (rm := _REQUIREMENT_RE.match(r)) is not None and rm.group("specifiers")
]
if len(matches) != 1:
raise ValueError(
f"the {extra!r} extra must list exactly one cuda-bindings requirement, found {len(matches)}"
Expand All @@ -130,6 +145,21 @@ def floors_from_extras(extras: Mapping[str, Sequence[str]]) -> dict[int, tuple[i
return dict(sorted(floors.items()))


def _expand_self_references(extras: Mapping[str, Sequence[str]], extra: str, seen: tuple[str, ...] = ()) -> list[str]:
"""The requirements of ``extra``, with each ``cuda-core[...]`` replaced by the requirements of the extras it names."""
seen = (*seen, extra)
requirements = []
for requirement in extras.get(extra, ()):
m = _SELF_REFERENCE_RE.match(requirement)
if m is None:
requirements.append(requirement)
continue
for name in (name.strip() for name in m.group("extras").split(",")):
if name and name not in seen:
requirements.extend(_expand_self_references(extras, name, seen))
return requirements


def _confined_major(specifier: str) -> int | None:
"""The one major a specifier confines cuda-bindings to: ``<14`` -> 13, ``==13.*`` -> 13, else None."""
if (m := _UPPER_SPEC_RE.match(specifier)) is not None:
Expand Down
4 changes: 3 additions & 1 deletion cuda_core/cuda/core/_cpp/rt/api.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,9 @@ DevicePtrHandle deviceptr_create_mapped_graphics(

// Import a device pointer from IPC via cuMemPoolImportPointer.
// When the last reference is released, cuMemFreeAsync is called on the stored stream.
// Note: Does not yet implement reference counting for nvbug 5570902.
// Repeat imports of one descriptor share one handle, because the driver's first
// free of an imported pointer unmaps every import of it (nvbug 5570902). An
// import that races the release of the last handle waits until the free is done.
// On error, returns empty handle and sets thread-local error (use get_last_error()).
DevicePtrHandle deviceptr_import_ipc(
const MemoryPoolHandle &h_pool, const void *export_data, const StreamHandle &h_stream
Expand Down
43 changes: 36 additions & 7 deletions cuda_core/cuda/core/_cpp/rt/memory.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,13 @@
#include "error.hpp"
#include "internal.hpp"
#include <atomic>
#include <condition_variable>
#include <cstddef>
#include <cstring>
#include <memory>
#include <mutex>
#include <stdexcept>
#include <unordered_map>
#include <utility>
#ifndef _WIN32
#include <unistd.h>
Expand Down Expand Up @@ -519,10 +521,21 @@ struct ExportDataKeyHash {
}
};

// The handle imported for one descriptor, and the box it aliases.
struct IpcCacheEntry {
std::weak_ptr<const CUdeviceptr> handle;
const DevicePtrBox *box;
};

} // namespace

static HandleRegistry<ExportDataKey, DevicePtrHandle, ExportDataKeyHash> ipc_ptr_cache;
// Guarded by ipc_import_mutex. An entry outlives its handle's last reference:
// only that handle's deleter erases it, under the mutex, together with the
// free. An importer that finds an expired entry therefore knows a release of
// the same mapping is in flight and waits on ipc_release_cv until it is done.
static std::unordered_map<ExportDataKey, IpcCacheEntry, ExportDataKeyHash> ipc_ptr_cache;
static std::mutex ipc_import_mutex;
static std::condition_variable ipc_release_cv;

DevicePtrHandle
deviceptr_import_ipc(const MemoryPoolHandle &h_pool, const void *export_data, const StreamHandle &h_stream)
Expand Down Expand Up @@ -552,10 +565,17 @@ deviceptr_import_ipc(const MemoryPoolHandle &h_pool, const void *export_data, co
CUresult discard_status = CUDA_SUCCESS;
CUdeviceptr discarded = 0;
{
std::scoped_lock lock(ipc_import_mutex);
std::unique_lock lock(ipc_import_mutex);

if (auto h = ipc_ptr_cache.lookup(key)) {
return h;
for (auto it = ipc_ptr_cache.find(key); it != ipc_ptr_cache.end(); it = ipc_ptr_cache.find(key)) {
if (DevicePtrHandle h = it->second.handle.lock()) {
return h;
}
// Expired but not erased: the last reference is gone and its
// deleter has not freed the mapping yet. A re-import now would
// share that mapping, and the deleter's cuMemFreeAsync would
// unmap it under us (nvbug 5570902). Wait for the release.
ipc_release_cv.wait(lock);
}

CUdeviceptr ptr;
Expand All @@ -579,20 +599,29 @@ deviceptr_import_ipc(const MemoryPoolHandle &h_pool, const void *export_data, co
GILReleaseGuard gil;
const DeallocationStream& stream = b->deallocation;
ContextHandle h_dealloc = deallocation_context(stream);
// Explicit template argument: MSVC cannot deduce it here (C2955).
std::unique_lock<std::mutex> lock(ipc_import_mutex);
ipc_ptr_cache.unregister_handle(key);
// Erase only this box's entry (importers wait while it
// exists, so no other box can own the key yet).
auto entry = ipc_ptr_cache.find(key);
if (entry != ipc_ptr_cache.end() && entry->second.box == b) {
ipc_ptr_cache.erase(entry);
}
cleanup_in_context(
h_dealloc, "cuMemFreeAsync", handle_bits(b->resource),
[&]() noexcept {
return p_cuMemFreeAsync(b->resource, as_cu(stream.h_stream)); // raw: under ipc_import_mutex
},
[&]() noexcept { lock.release()->unlock(); });
[&]() noexcept {
ipc_release_cv.notify_all();
lock.release()->unlock();
});
delete b;
}
);
// clang-format on
DevicePtrHandle h(box, &box->resource);
ipc_ptr_cache.register_handle(key, h);
ipc_ptr_cache[key] = IpcCacheEntry{h, box.get()};
return h;
}

Expand Down
3 changes: 3 additions & 0 deletions cuda_core/cuda/core/_memory/_memory_pool.pxd
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ cdef int MP_init_current_pool(

cdef int MP_raise_release_threshold(_MemPool self) except? -1

cdef int MP_set_access(
_MemPool self, const cydriver.CUmemAccessDesc* desc, size_t count) except? -1


cdef inline int MP_check_open(_MemPool self) except -1:
if not self._h_pool:
Expand Down
18 changes: 18 additions & 0 deletions cuda_core/cuda/core/_memory/_memory_pool.pyx
Original file line number Diff line number Diff line change
Expand Up @@ -461,6 +461,24 @@ cdef int MP_raise_release_threshold(_MemPool self) except? -1:
return 0


cdef int MP_set_access(
_MemPool self, const cydriver.CUmemAccessDesc* desc, size_t count) except? -1:
"""Set device access to the pool.

Runs in relaxed capture mode, like every pool attribute access (see
``_enter_relaxed_capture_mode``): the driver refuses cuMemPoolSetAccess,
and invalidates the capture, while a global-mode capture is active on
any thread or a thread-local one on the calling thread.
"""
cdef cydriver.CUstreamCaptureMode mode
cdef cydriver.CUresult err
with nogil:
_enter_relaxed_capture_mode(&mode)
err = cydriver.cuMemPoolSetAccess(as_cu(self._h_pool), desc, count)
_exit_relaxed_capture_mode(err, &mode)
return 0


# Raise an exception if the given stream is capturing.
# A result of CU_STREAM_CAPTURE_STATUS_INVALIDATED is considered an error.
cdef inline int check_not_capturing(cydriver.CUstream s) except?-1 nogil:
Expand Down
3 changes: 2 additions & 1 deletion cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,8 @@ class PinnedMemoryResource(_MemPool):
default, so the resource grants the device that is current when it is
created read and write access to the pool. Kernels on other devices cannot
access its buffers. Without options, the grant applies to the driver's
current pool, which the whole process shares.
current pool, which the whole process shares. Construction without options
does not affect a CUDA graph capture in progress on any thread.

To create an IPC-Enabled memory resource (MR) that is capable of sharing
allocations between processes, specify ``ipc_enabled=True`` in the initializer
Expand Down
Loading
Loading