Skip to content
Merged
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
90 changes: 49 additions & 41 deletions cuda_core/docs/source/api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,45 @@ Memory management
VirtualMemoryResourceOptions


CUDA compilation toolchain
--------------------------

.. currentmodule:: cuda.core

.. autosummary::
:toctree: generated/

:template: autosummary/cyclass.rst

Program
Linker
ObjectCode
Kernel

:template: dataclass.rst

ProgramOptions
LinkerOptions

Program caches
``````````````

``Program.compile`` accepts a ``cache=`` keyword argument that integrates
with any :class:`~cuda.core.utils.ProgramCacheResource`, so callers can
avoid recompiling identical source + options + target without writing the
:func:`~cuda.core.utils.make_program_cache_key` lookup by hand.

.. currentmodule:: cuda.core.utils

.. autosummary::
:toctree: generated/

ProgramCacheResource
InMemoryProgramCache
FileStreamProgramCache
make_program_cache_key


CUDA graphs
-----------

Expand All @@ -89,6 +128,8 @@ CPU overhead. Graphs can be constructed in two ways:
edges. Both produce an executable :class:`~graph.Graph` that can be
launched on a :class:`Stream`.

.. currentmodule:: cuda.core

.. autosummary::
:toctree: generated/

Expand Down Expand Up @@ -138,6 +179,8 @@ Each subclass exposes attributes unique to its operation type.
Graphics interoperability
-------------------------

.. currentmodule:: cuda.core

.. autosummary::
:toctree: generated/

Expand All @@ -149,6 +192,8 @@ Graphics interoperability
Tensor Memory Accelerator (TMA)
-------------------------------

.. currentmodule:: cuda.core

.. autosummary::
:toctree: generated/

Expand Down Expand Up @@ -208,47 +253,6 @@ The associated enumerations —
alongside the other ``cuda.core`` enumerations.


CUDA compilation toolchain
--------------------------

.. currentmodule:: cuda.core

.. autosummary::
:toctree: generated/

:template: autosummary/cyclass.rst

Program
Linker
ObjectCode
Kernel

:template: dataclass.rst

ProgramOptions
LinkerOptions

Program caches
``````````````

``Program.compile`` accepts a ``cache=`` keyword argument that integrates
with any :class:`~cuda.core.utils.ProgramCacheResource`, so callers can
avoid recompiling identical source + options + target without writing the
:func:`~cuda.core.utils.make_program_cache_key` lookup by hand.

.. currentmodule:: cuda.core.utils

.. autosummary::
:toctree: generated/

ProgramCacheResource
InMemoryProgramCache
FileStreamProgramCache
make_program_cache_key

.. currentmodule:: cuda.core


CUDA process checkpointing
--------------------------

Expand Down Expand Up @@ -303,6 +307,8 @@ Use ``Process.restore_thread_id`` to discover that thread before calling
persistence mode to be enabled or ``cuInit`` to have been called before
execution.

.. currentmodule:: cuda.core

.. autosummary::
:toctree: generated/

Expand All @@ -314,6 +320,8 @@ execution.
Utility functions
-----------------

.. currentmodule:: cuda.core

.. autosummary::
:toctree: generated/

Expand Down
104 changes: 101 additions & 3 deletions cuda_core/docs/source/release/1.1.0-notes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,33 @@
=================================


Highlights
----------

- ``cuda.core`` now ships with ``.pyi`` type stubs for all public APIs,
giving IDEs and type checkers full autocompletion and static analysis.
- New :mod:`cuda.core.texture` module for texture and surface memory:
:class:`~texture.OpaqueArray`, :class:`~texture.MipmappedArray`,
:class:`~texture.TextureObject`, and :class:`~texture.SurfaceObject`,
constructed through the corresponding ``Device.create_*`` factories.
- Richer managed-memory support: the new :class:`ManagedBuffer` exposes a
property-style advice API (:attr:`~ManagedBuffer.read_mostly`,
:attr:`~ManagedBuffer.preferred_location`,
:attr:`~ManagedBuffer.accessed_by`) with NUMA-aware host locations via the
new :class:`Host` type, plus batched range operations in
:mod:`cuda.core.utils` for prefetching and discarding many buffers at once.
- CUDA 13.3 toolkit support.
(`#2139 <https://github.com/NVIDIA/cuda-python/pull/2139>`__)


New features
------------

- Added :class:`Host` as the symmetric counterpart of :class:`Device` for
expressing managed-memory locations: ``Host()`` (any host),
``Host(numa_id=N)`` (specific NUMA node), and ``Host.numa_current()``
(calling thread's NUMA node).
(`#1775 <https://github.com/NVIDIA/cuda-python/pull/1775>`__)

- Added :class:`ManagedBuffer`, a :class:`Buffer` subclass returned by
:meth:`ManagedMemoryResource.allocate` that exposes a property-style
Expand All @@ -30,13 +50,16 @@ New features

Use :meth:`ManagedBuffer.from_handle` to wrap an existing managed-memory
pointer.
(`#1775 <https://github.com/NVIDIA/cuda-python/pull/1775>`__)

- Added batched managed-memory range operations to :mod:`cuda.core.utils`
(CUDA 13+): :func:`~utils.prefetch_batch`, :func:`~utils.discard_batch`,
and :func:`~utils.discard_prefetch_batch`. Each takes a sequence of
managed :class:`Buffer` instances and dispatches to the corresponding
``cuMem*BatchAsync`` driver entry point, addressing the managed-memory
portion of #1333. Single-buffer operations are exposed as instance
portion of
`#1333 <https://github.com/NVIDIA/cuda-python/issues/1333>`__. Single-buffer
operations are exposed as instance
methods on :class:`ManagedBuffer` (:meth:`~ManagedBuffer.prefetch`,
:meth:`~ManagedBuffer.discard`, :meth:`~ManagedBuffer.discard_prefetch`)
and as property setters (:attr:`~ManagedBuffer.read_mostly`,
Expand All @@ -48,28 +71,103 @@ New features
:meth:`system.Device.get_nvlinks` for device-specific NVLink enumeration.
These APIs avoid relying on the static NVML ``NVML_NVLINK_MAX_LINKS`` macro
when querying the links available on a particular device.
(`#2192 <https://github.com/NVIDIA/cuda-python/pull/2192>`__)

- Added the :attr:`graph.GraphBuilder.graph_definition` property, which
exposes a captured graph as an explicit :class:`graph.GraphDefinition`
view sharing ownership of the same underlying graph. This enables hybrid
flows that mix the capture and explicit graph-building APIs, such as
inspecting or augmenting a captured graph, or populating a conditional
body entirely through the explicit API.
(`#2026 <https://github.com/NVIDIA/cuda-python/pull/2026>`__)

- Added the :mod:`cuda.core.texture` module for texture and surface memory:
:class:`~texture.OpaqueArray` and :class:`~texture.MipmappedArray` for
hardware-laid-out array allocations, and :class:`~texture.TextureObject` and
:class:`~texture.SurfaceObject` for bindless kernel-side sampled reads and
typed load/store. Objects are constructed from a
:class:`~texture.ResourceDescriptor` via
:meth:`Device.create_opaque_array`, :meth:`Device.create_mipmapped_array`,
:meth:`Device.create_texture_object`, and :meth:`Device.create_surface_object`.
(`#467 <https://github.com/NVIDIA/cuda-python/issues/467>`__,
`#2095 <https://github.com/NVIDIA/cuda-python/pull/2095>`__,
`#2307 <https://github.com/NVIDIA/cuda-python/pull/2307>`__)

- ``cuda.core`` now ships with ``.pyi`` stubs for all public APIs, enabling
users' IDEs and type checkers to provide better autocompletion and static
analysis.
(`#2061 <https://github.com/NVIDIA/cuda-python/pull/2061>`__)

- :class:`ObjectCode` and :class:`Program` now accept path-like inputs in
addition to strings and bytes.
(`#2123 <https://github.com/NVIDIA/cuda-python/pull/2123>`__)

- Exposed a :attr:`Buffer.size` accessor to Python.
(`#2068 <https://github.com/NVIDIA/cuda-python/pull/2068>`__,
closes `#2049 <https://github.com/NVIDIA/cuda-python/issues/2049>`__)

Bug fixes
---------
Fixes and enhancements
----------------------

- On WSL, ``cuda.core.system.get_process_name`` would raise a
``UnicodeDecodeError``. It should now return the correct result.
(`#2118 <https://github.com/NVIDIA/cuda-python/pull/2118>`__)
- Calling ``cuda.core.system.get_process_name`` before querying any device's
``compute_running_processes`` would raise a ``NvmlNotFoundError``. Now it will
correctly return the process name, if it is a GPU-using process.
- :meth:`system.Device.get_nvlink` now validates link numbers against the
device-specific NVLink count and raises ``ValueError`` for unsupported links.
(`#2192 <https://github.com/NVIDIA/cuda-python/pull/2192>`__)
- Hardened the IPC buffer import path against malformed or untrusted peer
descriptors: descriptor payloads shorter than the driver struct are now
rejected before import
(`#2223 <https://github.com/NVIDIA/cuda-python/pull/2223>`__), an imported
buffer's size is validated against the mapped allocation extent before any
copy (`#2224 <https://github.com/NVIDIA/cuda-python/pull/2224>`__), and
negative allocation handles are always rejected, including under ``-O``
(`#2219 <https://github.com/NVIDIA/cuda-python/pull/2219>`__).
- :attr:`ManagedBuffer.accessed_by` now validates every location before
issuing any advice, so a bulk assignment containing an invalid entry can no
longer leave the applied advice in a torn state.
(`#2222 <https://github.com/NVIDIA/cuda-python/pull/2222>`__)
- Graph nodes now keep their Python-owned attachments (kernel-argument
buffers, host-callback functions and user data, and memcpy/memset operands)
alive for the lifetime of the graph. Previously, keeping these objects alive
was the caller's responsibility.
(`#2280 <https://github.com/NVIDIA/cuda-python/pull/2280>`__)
- Hardened the graph user-object destructor against races during Python
interpreter shutdown.
(`#2074 <https://github.com/NVIDIA/cuda-python/pull/2074>`__)
- Free-threading correctness fixes: buffer and memory-resource threading
(`#2162 <https://github.com/NVIDIA/cuda-python/pull/2162>`__), critical-section
guards on shared accessors
(`#2215 <https://github.com/NVIDIA/cuda-python/pull/2215>`__), and an atomic
flag guarding buffer memory-attribute initialization
(`#2216 <https://github.com/NVIDIA/cuda-python/pull/2216>`__).
- :meth:`Program.compile` cache keys are now FIPS-safe.
(`#2087 <https://github.com/NVIDIA/cuda-python/pull/2087>`__)
- Memory-pool driver errors are now preserved instead of being masked by
out-of-memory handling.
(`#2084 <https://github.com/NVIDIA/cuda-python/pull/2084>`__)
- DLPack export now raises ``BufferError`` (the intended exception) instead of
``RuntimeError`` when a buffer cannot be exported.
(`#2160 <https://github.com/NVIDIA/cuda-python/pull/2160>`__)
- Corrected the :class:`Buffer` and :class:`MemoryResource` ``__eq__``
implementations.
(`#2067 <https://github.com/NVIDIA/cuda-python/pull/2067>`__,
closes `#2050 <https://github.com/NVIDIA/cuda-python/issues/2050>`__)
- Checkpoint restore now validates GPU UUID inputs early.
(`#2086 <https://github.com/NVIDIA/cuda-python/pull/2086>`__)
- Bumped the PyTorch tensor-bridge upper bound to 2.12.
(`#2099 <https://github.com/NVIDIA/cuda-python/pull/2099>`__)

Documentation
-------------

- Documented the IPC buffer pickle trust boundary: :meth:`Buffer.__reduce__`
and multi-process IPC users should review the security note before
unpickling buffer handles from untrusted sources.
(`#2225 <https://github.com/NVIDIA/cuda-python/pull/2225>`__)

Deprecated APIs
---------------
Expand Down
Loading