diff --git a/docs/components/xdr.md b/docs/components/xdr.md index 489cbbb7..356dcb50 100644 --- a/docs/components/xdr.md +++ b/docs/components/xdr.md @@ -22,14 +22,16 @@ floating-point bit patterns; choose explicit modes for comparisons or debugging. | --- | --- | --- | --- | | `postprocess` | `--xdr-postprocess` | `auto`, `fused`, `separate`, `native` | Restore byte order and scatter decoded tiles. | | `gzip_decoder` | `--xdr-gzip-decoder` | `auto`, `gzip`, `deflate` | Use native Gzip when available; otherwise decode aligned raw DEFLATE. | -| `decompression_backend` | `--xdr-decompression-backend` | `auto`, `cuda` | Let nvCOMP choose a compatible decompression engine for native Gzip, with CUDA fallback. | +| `decompression_backend` | `--xdr-decompression-backend` | `auto`, `cuda`, `hardware` | Let nvCOMP choose a compatible decompression engine for native Gzip, with CUDA fallback. | `postprocess="fused"` selects the same kernel as `auto`; `"separate"` runs individual restoration kernels. `gzip_decoder="gzip"` requires native Gzip support. `"deflate"` strips the Gzip framing and aligns payloads for raw DEFLATE. `decompression_backend="cuda"` requires a native extension with -backend selection support and selects CUDA kernels explicitly. The native -raw DEFLATE decoder uses CUDA in either backend mode. +backend selection support and selects CUDA kernels explicitly. +`decompression_backend="hardware"` requires native Gzip hardware decoding, +with no CUDA fallback. Use it with `gzip_decoder="auto"` or `"gzip"`; the +native raw DEFLATE decoder supports only the `auto` and `cuda` backends. `postprocess="native"` requires the [native imaging extension](../packaging.md). For `GZIP_1` and `GZIP_2` image tiles it runs byte-order restoration, unshuffle, @@ -109,9 +111,9 @@ defaults. Full batch FITS loading still requires the native FITS planner; codec fallback does not remove that requirement. -When xDR decodes compressed HDUs, explicit `gzip` or `cuda` requests fail clearly -if the installed extension cannot honor them. Rebuild an older source extension -using the [native build instructions](#native-extension-availability). The `auto` +When xDR decodes compressed HDUs, explicit `gzip`, `cuda` or `hardware` +requests fail clearly if the installed extension cannot honor them. Rebuild +an older source extension using the [native build instructions](#native-extension-availability). The `auto` choices select available capabilities before decoding. I/O or decoder exceptions propagate; they do not trigger another reader, codec or postprocessing attempt. The supported FITS compression formats remain `GZIP_1` and `GZIP_2`. @@ -131,13 +133,27 @@ tiles beyond the hardware limit. Batch readers retain native pooled scratch buffers. The low-level non-pooled path, including `GpuCompImageReader.read()` without an explicit stream, uses `cudaMallocAsync` scratch, which is not hardware-decompression capable. That -path selects CUDA directly, including with `decompression_backend="auto"`, -to avoid a failed hardware attempt on each call. Custom CuPy allocators can -also affect eligibility in pooled calls. +path selects CUDA directly with `auto` or `cuda` and rejects `hardware`. +Pass an explicit stream to `GpuCompImageReader.read` or use a batch reader +for pooled scratch. Custom CuPy allocators can also affect eligibility in +pooled calls. An `auto` receipt and a compatible GPU therefore do not establish hardware use. See [nvCOMP logging](../troubleshooting.md#confirm-the-decompression-engine) to inspect the actual decoder calls. +For a hardware-only diagnostic run on supported compressed FITS inputs: + +```bash +cuphoton xdr benchmark-fits --hdu-indices 1 \ + --xdr-gzip-decoder gzip --xdr-decompression-backend hardware exposure.fits +``` + +The decode fails if the device, buffers or tile sizes are incompatible; it +does not retry with CUDA. In workflows, combine the hardware option with +`reader="xdr"` (CLI `--fits-reader xdr`) to require xDR as well. Uncompressed +HDUs perform no decompression, and Astropy-selected reads do not apply this +backend option. A receipt records the request, including these cases. + The benchmark's `--output-json` report includes `capabilities.hardware_decompression`: the current device's algorithm mask, `supports_deflate`, and `max_chunk_bytes`. Unavailable queries leave those diff --git a/docs/guide/read-fits.qmd b/docs/guide/read-fits.qmd index 711392af..c28205f4 100644 --- a/docs/guide/read-fits.qmd +++ b/docs/guide/read-fits.qmd @@ -205,7 +205,7 @@ With `reader="astropy"`, `device=True` decodes on the CPU and copies the arrays |---|---|---|---| | `postprocess` | `--xdr-postprocess` | `auto`, `fused`, `separate`, `native` | restores the pixels with one fused kernel | | `gzip_decoder` | `--xdr-gzip-decoder` | `auto`, `gzip`, `deflate` | uses native Gzip when available, otherwise raw DEFLATE | -| `decompression_backend` | `--xdr-decompression-backend` | `auto`, `cuda` | lets nvCOMP pick its decompression engine, with CUDA as the fallback | +| `decompression_backend` | `--xdr-decompression-backend` | `auto`, `cuda`, `hardware` | lets nvCOMP pick its decompression engine, with CUDA as the fallback | `postprocess="native"` restores compressed tiles with the precompiled kernels of cuPhoton's native extension (@sec-install). Every key defaults to `auto`. The keys choose how xDR decodes, not whether it runs, and none changes a pixel value. The call checks them on any machine and records them in the receipt: @@ -215,6 +215,8 @@ checked = read_fits_images("sample/target.fits", [0], reader="auto", print(checked.metadata()["xdr_options"]) ``` +Use `decompression_backend="hardware"` with `reader="xdr"` to require native Gzip hardware decoding for compressed HDUs. It fails when the hardware engine, buffers or tile sizes are incompatible. Uncompressed HDUs need no decompression. See [hardware eligibility](https://github.com/NVIDIA/cuPhoton/blob/main/docs/components/xdr.md#hardware-eligibility-and-diagnostics) for supported devices and allocation requirements. + The receipt records the requested choices, not the engine that ran. To load the same HDUs from many files of one shape, `batch_to_device` returns one CuPy array per HDU, shaped (file, y, x): ```{python} @@ -268,8 +270,8 @@ CPU runs of xFit, xPois and xRep turn `auto` into `astropy` before they read. Th `No module named 'cupy'` : `device=True` needs CuPy, even when Astropy decodes. Install the `gpu` profile. -An explicit `gzip_decoder="gzip"` or `decompression_backend="cuda"` fails on a GPU host -: The native extension is older than these choices. Rebuild it, as the [troubleshooting guide](https://github.com/NVIDIA/cuPhoton/blob/main/docs/troubleshooting.md#an-explicit-compression-choice-is-unavailable) describes. +An explicit decoder or backend choice fails on a GPU host +: The native extension may predate the requested choice. Rebuild it, as the [troubleshooting guide](https://github.com/NVIDIA/cuPhoton/blob/main/docs/troubleshooting.md#an-explicit-compression-choice-is-unavailable) describes. A `hardware` request also requires a supported device, compatible buffers and tile sizes. ## Next steps diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 9e7bec11..6d4543fa 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -71,6 +71,9 @@ error. GPUDirect Storage also requires host and storage configuration; use `--xdr-gzip-decoder gzip` requires native Gzip support; `--xdr-decompression-backend cuda` requires an extension with backend selection. +`--xdr-decompression-backend hardware` additionally requires native Gzip +hardware selection, a supported GPU, compatible pooled buffers and tile sizes. +Use `auto` or `gzip` as the Gzip decoder for this mode. An importable extension may predate those entry points. After updating a source checkout, rebuild it with the [native build instructions](components/xdr.md#native-extension-availability) in the environment running your command. Use `auto` when capability fallback @@ -81,7 +84,9 @@ reader, decoder and backend policies. ### Confirm the decompression engine -Enable [nvCOMP logging](https://docs.nvidia.com/cuda/nvcomp/getting_started.html#logging) +Use `--xdr-decompression-backend hardware` to require hardware execution +for compressed xDR reads. It fails if the hardware engine cannot be used. +To inspect automatic selection, enable [nvCOMP logging](https://docs.nvidia.com/cuda/nvcomp/getting_started.html#logging) for a diagnostic run. Level 5 includes API calls as well as informational messages; use a separate log file to keep them out of the command output: diff --git a/scripts/coverage/xdr.sh b/scripts/coverage/xdr.sh index 172fae39..5e38a3e2 100755 --- a/scripts/coverage/xdr.sh +++ b/scripts/coverage/xdr.sh @@ -33,7 +33,9 @@ PY python -m pytest -q -rs -o "pythonpath=$PYTHONPATH" \ --junitxml="$coverage_build/junit.xml" \ - tests/xdr/test_native.py tests/xdr/test_deflate_gpu.py + tests/xdr/test_native.py tests/xdr/test_deflate_gpu.py \ + tests/xdr/test_gzip_gpu.py::test_forced_hardware_roundtrip_or_unsupported_device \ + tests/xdr/test_gzip_gpu.py::test_native_hardware_rejects_incompatible_route python - <<'PY' from xml.etree import ElementTree as ET diff --git a/src/cuphoton/core/cli/fits.py b/src/cuphoton/core/cli/fits.py index fa65edd1..885a40a5 100644 --- a/src/cuphoton/core/cli/fits.py +++ b/src/cuphoton/core/cli/fits.py @@ -49,8 +49,10 @@ class XdrDecompressionBackendArg(SetInvariant): _help = ( "xDR decompression backend: auto permits compatible Gzip " "hardware with CUDA fallback; cuda requires explicit CUDA " - "selection support. Omitted preserves input choices or uses " - "xDR defaults; applies when the FITS reader uses xDR." + "selection support; hardware requires native Gzip on the " + "hardware engine, with no CUDA fallback. Omitted preserves " + "input choices or uses xDR defaults; applies when the FITS " + "reader uses xDR." ) _set = XDR_OPTION_CHOICES["decompression_backend"] _default = None diff --git a/src/cuphoton/core/fits_io.py b/src/cuphoton/core/fits_io.py index dd7f5876..c40946e1 100644 --- a/src/cuphoton/core/fits_io.py +++ b/src/cuphoton/core/fits_io.py @@ -253,11 +253,14 @@ def read_fits_images( ``xdr_options`` accepts ``postprocess`` (auto/fused/separate/native), ``gzip_decoder`` (auto/gzip/deflate), and ``decompression_backend`` - (auto/cuda). Omitted choices use xDR's ``auto`` defaults. For example, + (auto/cuda/hardware). Omitted choices use xDR's ``auto`` defaults. + For example, ``xdr_options={"decompression_backend": "cuda"}`` requests CUDA kernels when xDR decodes a compressed HDU; it requires a native helper with - backend selection. These choices do not change the reader or its Astropy - fallback policy. Metadata records explicit choices as requested settings, + backend selection. ``hardware`` requires native Gzip hardware decoding + without CUDA fallback. These choices do not change the reader or its + Astropy fallback policy; use ``reader="xdr"`` to require GPU reading. + Metadata records explicit choices as requested settings, including when Astropy is selected; it does not identify an nvCOMP engine. """ validate_fits_reader(reader) diff --git a/src/cuphoton/core/fits_options.py b/src/cuphoton/core/fits_options.py index 931bd125..69fbb6bc 100644 --- a/src/cuphoton/core/fits_options.py +++ b/src/cuphoton/core/fits_options.py @@ -9,7 +9,7 @@ XDR_OPTION_CHOICES = { "postprocess": frozenset({"auto", "fused", "separate", "native"}), "gzip_decoder": frozenset({"auto", "gzip", "deflate"}), - "decompression_backend": frozenset({"auto", "cuda"}), + "decompression_backend": frozenset({"auto", "cuda", "hardware"}), } @@ -32,6 +32,14 @@ def normalize_xdr_options( choices = ", ".join(sorted(XDR_OPTION_CHOICES[name])) raise ValueError(f"xDR {name} must be one of: {choices}") result[name] = value + if ( + result.get("decompression_backend") == "hardware" + and result.get("gzip_decoder") == "deflate" + ): + raise ValueError( + "xDR decompression_backend='hardware' requires " + "gzip_decoder='auto' or 'gzip'" + ) return result @@ -40,4 +48,6 @@ def merge_xdr_options( overrides: Mapping[str, str] | None, ) -> dict[str, str]: """Override only supplied keys and preserve other manifest choices.""" - return {**normalize_xdr_options(base), **normalize_xdr_options(overrides)} + return normalize_xdr_options( + {**normalize_xdr_options(base), **normalize_xdr_options(overrides)} + ) diff --git a/src/cuphoton/xdr/convenience.py b/src/cuphoton/xdr/convenience.py index 26cfc6ab..8bc8836f 100644 --- a/src/cuphoton/xdr/convenience.py +++ b/src/cuphoton/xdr/convenience.py @@ -78,11 +78,12 @@ def batch_to_device( gzip_decoder : {"auto", "gzip", "deflate"} ``auto`` prefers native Gzip, with aligned raw DEFLATE fallback. ``gzip`` requires native Gzip support; ``deflate`` selects raw decode. - decompression_backend : {"auto", "cuda"} + decompression_backend : {"auto", "cuda", "hardware"} ``auto`` lets native Gzip select compatible hardware with CUDA fallback. ``cuda`` requires a native helper with backend selection. - Native raw DEFLATE uses CUDA in either mode. All three runtime - controls apply with either value of ``parallel``. + ``hardware`` requires native Gzip on the hardware engine without CUDA + fallback. Native raw DEFLATE supports only ``auto`` and ``cuda``. + All three runtime controls apply with either value of ``parallel``. Returns ------- diff --git a/src/cuphoton/xdr/nvcomp_batch.py b/src/cuphoton/xdr/nvcomp_batch.py index 8628bc8e..41f42954 100644 --- a/src/cuphoton/xdr/nvcomp_batch.py +++ b/src/cuphoton/xdr/nvcomp_batch.py @@ -894,10 +894,12 @@ def gpu_gzip_decompress_batch( "auto" uses native Gzip when available, otherwise raw DEFLATE. "gzip" requires the native Gzip helper and gzip-wrapped inputs. "deflate" strips gzip framing and aligns payloads before decoding. - decompression_backend : "auto" | "cuda" + decompression_backend : "auto" | "cuda" | "hardware" "auto" lets native Gzip use compatible hardware with CUDA fallback. - Native raw DEFLATE uses CUDA in either mode. + Native raw DEFLATE supports only "auto" and "cuda" and uses CUDA. "cuda" requires a rebuilt native helper and uses CUDA kernels. + "hardware" requires native Gzip and pooled allocations, and fails + when the device, buffers, or tile sizes cannot use hardware decoding. use_cpp_helper : "auto" | True | False "auto" (default) → use the C++ pybind11 helper when importable, else fall back to the Python loop. True forces the C++ path (raises if @@ -939,12 +941,35 @@ def gpu_gzip_decompress_batch( """ if _decode_checks is not None and keepalive is None: raise ValueError("deferred decode requires an explicit owner list") - if decompression_backend not in ("auto", "cuda"): - raise ValueError("decompression_backend must be 'auto' or 'cuda'") + if decompression_backend not in ("auto", "cuda", "hardware"): + raise ValueError( + "decompression_backend must be 'auto', 'cuda', or 'hardware'" + ) if gzip_decoder not in ("auto", "gzip", "deflate"): raise ValueError("gzip_decoder must be 'auto', 'gzip', or 'deflate'") if gzip_decoder == "gzip" and not gzip_wrapped: raise ValueError("gzip_decoder='gzip' requires gzip_wrapped=True") + if decompression_backend == "hardware": + if gzip_decoder == "deflate": + raise ValueError( + "decompression_backend='hardware' requires " + "gzip_decoder='auto' or 'gzip'" + ) + if not gzip_wrapped: + raise ValueError( + "decompression_backend='hardware' requires native Gzip " + "decoding of gzip-wrapped inputs" + ) + if not use_native_pool: + raise ValueError( + "decompression_backend='hardware' requires " + "use_native_pool=True" + ) + if use_cpp_helper is False: + raise ValueError( + "decompression_backend='hardware' requires " + "use_cpp_helper enabled" + ) import cupy as cp @@ -1017,14 +1042,22 @@ def gpu_gzip_decompress_batch( ext = None else: ext = _try_get_cpp_ext() - if ext is None and gzip_decoder != "gzip": + if ( + ext is None + and gzip_decoder != "gzip" + and decompression_backend != "hardware" + ): _warn_python_fallback_once() backend_selection = getattr(ext, "supports_decompression_backend", False) - if decompression_backend != "auto" and not backend_selection: + if (decompression_backend != "auto" and not backend_selection) or ( + decompression_backend == "hardware" + and not getattr(ext, "supports_hardware_decompression", False) + ): raise RuntimeError( - "decompression_backend='cuda' requires a rebuilt native " - "extension with backend selection and use_cpp_helper enabled" + f"decompression_backend={decompression_backend!r} requires a " + "rebuilt native extension with backend selection and " + "use_cpp_helper enabled" ) backend_kwargs = ( {"decompression_backend": decompression_backend} @@ -1032,10 +1065,12 @@ def gpu_gzip_decompress_batch( else {} ) gzip_fn = getattr(ext, "batch_gzip_decompress", None) - if gzip_decoder == "gzip" and gzip_fn is None: + if ( + gzip_decoder == "gzip" or decompression_backend == "hardware" + ) and gzip_fn is None: raise RuntimeError( - "gzip_decoder='gzip' requires a native extension with Gzip " - "support and use_cpp_helper enabled" + "the requested decoder/backend requires a native extension with " + "Gzip support and use_cpp_helper enabled" ) use_gzip = ( gzip_wrapped and gzip_decoder != "deflate" and gzip_fn is not None @@ -1113,7 +1148,11 @@ def gpu_gzip_decompress_batch( out_offsets, size_array, stream_ptr, - use_native_pool and keepalive is not None, + use_native_pool + and ( + keepalive is not None + or decompression_backend == "hardware" + ), **backend_kwargs, ) if keepalive is not None and scratch_owner is not None: diff --git a/src/cuphoton/xdr/prefetch.py b/src/cuphoton/xdr/prefetch.py index f3272f76..539c3de7 100644 --- a/src/cuphoton/xdr/prefetch.py +++ b/src/cuphoton/xdr/prefetch.py @@ -1771,8 +1771,9 @@ def batch_to_device_stream( "gzip" requires native Gzip support; "deflate" selects raw DEFLATE. decompression_backend "auto" lets Gzip select compatible hardware with CUDA fallback. "cuda" - requires a rebuilt native helper and uses CUDA kernels. Native raw - DEFLATE uses CUDA in either mode. + requires a rebuilt native helper and uses CUDA kernels. "hardware" + requires native Gzip on the hardware engine without CUDA fallback. + Native raw DEFLATE supports only "auto" and "cuda". section Optional 2D ROI applied uniformly to CompImageHDUs. stream diff --git a/src/cuphoton/xdr/reader.py b/src/cuphoton/xdr/reader.py index 7357f7ce..1d4b849a 100644 --- a/src/cuphoton/xdr/reader.py +++ b/src/cuphoton/xdr/reader.py @@ -451,6 +451,7 @@ def inflate_device_heap( offsets into that output buffer. ``gzip_decoder`` and ``decompression_backend`` use the choices documented by :func:`cuphoton.xdr.batch_to_device_stream`. + ``hardware`` requires an explicit ``keepalive`` owner list. """ normalize_xdr_options( { @@ -458,6 +459,11 @@ def inflate_device_heap( "decompression_backend": decompression_backend, } ) + if decompression_backend == "hardware" and keepalive is None: + raise ValueError( + "decompression_backend='hardware' requires an explicit " + "keepalive owner list" + ) import cupy as cp with stream or cp.cuda.Stream.null: @@ -662,6 +668,7 @@ def decode_from_device_heap( consumer calls after staging its pinned host heap to device. ``postprocess``, ``gzip_decoder`` and ``decompression_backend`` use the choices documented by :func:`cuphoton.xdr.batch_to_device_stream`. + ``hardware`` requires an explicit ``keepalive`` owner list. """ normalize_xdr_options( { @@ -670,6 +677,11 @@ def decode_from_device_heap( "decompression_backend": decompression_backend, } ) + if decompression_backend == "hardware" and keepalive is None: + raise ValueError( + "decompression_backend='hardware' requires an explicit " + "keepalive owner list" + ) if keepalive is not None: keepalive.append(d_concat) d_pixels, tile_byte_offsets_np = ( @@ -725,10 +737,13 @@ def read( ``auto`` prefers native Gzip with aligned DEFLATE fallback. ``gzip`` requires native Gzip support; ``deflate`` selects aligned raw DEFLATE decoding. - decompression_backend : {"auto", "cuda"} + decompression_backend : {"auto", "cuda", "hardware"} ``auto`` lets native Gzip select compatible hardware with CUDA fallback. ``cuda`` requires a native helper with backend - selection. Native raw DEFLATE uses CUDA in either mode. + selection. ``hardware`` requires native Gzip on the hardware + engine and an explicit stream for pooled scratch; it has no CUDA + fallback. + Native raw DEFLATE supports only ``auto`` and ``cuda``. Notes ----- @@ -749,6 +764,11 @@ def read( "decompression_backend": decompression_backend, } ) + if decompression_backend == "hardware" and stream is None: + raise ValueError( + "decompression_backend='hardware' requires an explicit " + "stream for pooled scratch in GpuCompImageReader.read" + ) import cupy as cp plan = self.prepare_plan(section=section) diff --git a/src/cuphoton/xdr/src/nvcomp_batch_ext.cpp b/src/cuphoton/xdr/src/nvcomp_batch_ext.cpp index cf1ba12b..742cd576 100644 --- a/src/cuphoton/xdr/src/nvcomp_batch_ext.cpp +++ b/src/cuphoton/xdr/src/nvcomp_batch_ext.cpp @@ -15,6 +15,8 @@ #include #include +#include +#include #include #include #include @@ -38,6 +40,83 @@ inline void check_nvcomp(nvcompStatus_t s, const char* ctx) { } } +// Check device limits and allocation eligibility before hardware submission. +void validate_hardware_gzip( + std::uintptr_t input, std::uintptr_t output, std::size_t max_chunk_bytes) { + // Select the ABI of each function, independently of the device attributes + // queried below. cuCtxGetDevice gained a second argument in API 13000. + auto entry_point = [](const char* symbol, unsigned int version) { + void* entry = nullptr; + cudaDriverEntryPointQueryResult status; + check_cuda( + cudaGetDriverEntryPointByVersion( + symbol, &entry, version, cudaEnableDefault, &status), + "hardware Gzip driver query"); + if (status != cudaDriverEntryPointSuccess || entry == nullptr) { + throw std::runtime_error( + std::string("hardware Gzip requires CUDA driver query ") + + symbol); + } + return entry; + }; + auto check_driver = [](CUresult status, const char* context) { + if (status != CUDA_SUCCESS) { + throw std::runtime_error( + std::string("hardware Gzip ") + context + + " failed: CUDA driver status=" + + std::to_string(static_cast(status))); + } + }; + const auto get_device = reinterpret_cast( + entry_point("cuCtxGetDevice", 2000)); + const auto get_attribute = reinterpret_cast( + entry_point("cuDeviceGetAttribute", 2000)); + const auto get_pointer_attribute = + reinterpret_cast( + entry_point("cuPointerGetAttribute", 4000)); + CUdevice device; + check_driver(get_device(&device), "device query"); + int algorithms = 0; + check_driver( + get_attribute( + &algorithms, + CU_DEVICE_ATTRIBUTE_MEM_DECOMPRESS_ALGORITHM_MASK, + device), + "algorithm query"); + if ((algorithms & CU_MEM_DECOMPRESS_ALGORITHM_DEFLATE) == 0) { + throw std::runtime_error( + "hardware Gzip decompression is unavailable on this device"); + } + int maximum = 0; + check_driver( + get_attribute( + &maximum, + CU_DEVICE_ATTRIBUTE_MEM_DECOMPRESS_MAXIMUM_LENGTH, + device), + "chunk-limit query"); + if (maximum <= 0 || max_chunk_bytes > static_cast(maximum)) { + throw std::runtime_error( + "hardware Gzip chunk size " + std::to_string(max_chunk_bytes) + + " exceeds device limit " + std::to_string(maximum)); + } + // Both buffers are contiguous. Scratch and actual-size buffers come from + // the native cudaMalloc pool, which supports hardware decompression. + for (auto pointer : {input, output}) { + bool capable = false; + check_driver( + get_pointer_attribute( + &capable, + CU_POINTER_ATTRIBUTE_IS_HW_DECOMPRESS_CAPABLE, + static_cast(pointer)), + "allocation query"); + if (!capable) { + throw std::runtime_error( + "hardware Gzip requires hardware-decompression-capable " + "input and output allocations"); + } + } +} + // Own every metadata transfer until decode completion. Downstream kernels may // use the device status/size arrays, so callers retain this object through their // final stream event, not merely until check() returns. @@ -233,7 +312,8 @@ py::object batch_deflate_decompress_pooled( // Gzip uses the same pointer/size arrays, with offsets and lengths covering // complete RFC-1952 streams. "auto" permits compatible hardware with CUDA -// fallback; "cuda" selects CUDA. A pooled owner must survive stream completion. +// fallback; "cuda" selects CUDA, and "hardware" requires pooled hardware +// decoding. A pooled owner must survive stream completion. py::object batch_gzip_decompress( std::uintptr_t d_concat_ptr, py::array_t @@ -282,9 +362,16 @@ py::object batch_decompress_impl( backend = NVCOMP_DECOMPRESS_BACKEND_DEFAULT; } else if (decompression_backend == "cuda") { backend = NVCOMP_DECOMPRESS_BACKEND_CUDA; + } else if (decompression_backend == "hardware") { + if (!gzip_wrapped || !use_native_pool) { + throw std::invalid_argument( + "decompression_backend='hardware' requires native Gzip " + "decoding with use_native_pool=True"); + } + backend = NVCOMP_DECOMPRESS_BACKEND_HARDWARE; } else { throw std::invalid_argument( - "decompression_backend must be 'auto' or 'cuda'"); + "decompression_backend must be 'auto', 'cuda', or 'hardware'"); } const std::size_t n = static_cast(rel_offsets.size()); if (lengths.size() != static_cast(n) @@ -337,6 +424,14 @@ py::object batch_decompress_impl( max_uncomp = std::max(max_uncomp, h_out_sizes[i]); total_uncomp += h_out_sizes[i]; } + if (backend == NVCOMP_DECOMPRESS_BACKEND_HARDWARE) { + validate_hardware_gzip( + d_concat_ptr, + d_out_ptr, + std::max( + max_uncomp, + *std::max_element(h_comp_sizes.begin(), h_comp_sizes.end()))); + } // Allocate device-side mirror arrays + temp in one stream-ordered batch. void* d_comp_ptrs = nullptr; @@ -540,8 +635,11 @@ py::object batch_decompress_impl( opts, static_cast(d_statuses), stream), - gzip_wrapped ? "batched gzip decompression" - : "batched deflate decompression"); + backend == NVCOMP_DECOMPRESS_BACKEND_HARDWARE + ? "hardware Gzip decompression (check device, allocation " + "and chunk-size compatibility)" + : (gzip_wrapped ? "batched gzip decompression" + : "batched deflate decompression")); check_cuda( cudaMemcpyAsync( deferred ? completion->statuses : h_statuses.data(), @@ -628,6 +726,7 @@ PYBIND11_MODULE(_nvcomp_batch_ext, m) { "Batched Gzip/DEFLATE decompression — device-pointer interface to nvcomp."; m.attr("supports_decompression_backend") = true; + m.attr("supports_hardware_decompression") = true; xdr_gpu::bind_io(m); xdr_gpu::bind_memory_manager(m); @@ -753,5 +852,5 @@ PYBIND11_MODULE(_nvcomp_batch_ext, m) { "Waits for decode completion and validates per-tile status and size.\n" "Pooled calls return an owner capsule for scratch buffers.\n" "decompression_backend=auto permits compatible hardware with CUDA fallback;\n" - "cuda selects CUDA explicitly."); + "cuda selects CUDA explicitly; hardware requires pooled hardware decoding."); } diff --git a/tests/core/test_fits_io.py b/tests/core/test_fits_io.py index b6bedb5c..9687ee95 100644 --- a/tests/core/test_fits_io.py +++ b/tests/core/test_fits_io.py @@ -13,11 +13,23 @@ from astropy.io import fits from cuphoton.core import fits_io +from cuphoton.core.fits_options import merge_xdr_options -@pytest.mark.parametrize("decompression_backend", ["auto", "cuda"]) +@pytest.mark.parametrize( + ("gzip_decoder", "decompression_backend"), + [ + ("auto", "auto"), + ("auto", "cuda"), + ("gzip", "auto"), + ("gzip", "cuda"), + ("deflate", "auto"), + ("deflate", "cuda"), + ("auto", "hardware"), + ("gzip", "hardware"), + ], +) @pytest.mark.parametrize("postprocess", ["fused", "separate"]) -@pytest.mark.parametrize("gzip_decoder", ["auto", "gzip", "deflate"]) def test_xdr_options_reach_batch_dispatch( tmp_path, monkeypatch, postprocess, gzip_decoder, decompression_backend ): @@ -56,7 +68,13 @@ def batch(paths, hdus, **options): @pytest.mark.parametrize( - "options", ["fused", {"unknown": "auto"}, {"postprocess": True}] + "options", + [ + "fused", + {"unknown": "auto"}, + {"postprocess": True}, + {"gzip_decoder": "deflate", "decompression_backend": "hardware"}, + ], ) def test_invalid_xdr_options_fail_before_input_access(tmp_path, options): with pytest.raises(ValueError, match="xDR|xdr_options"): @@ -65,6 +83,20 @@ def test_invalid_xdr_options_fail_before_input_access(tmp_path, options): ) +@pytest.mark.parametrize("reverse", [False, True]) +def test_merged_xdr_options_reject_incompatible_decoder(reverse): + options = [ + {"gzip_decoder": "deflate"}, + {"decompression_backend": "hardware"}, + ] + if reverse: + options.reverse() + with pytest.raises( + ValueError, match="requires gzip_decoder='auto' or 'gzip'" + ): + merge_xdr_options(*options) + + def _write(tmp_path, array, *, compression=None, **kwargs): path = tmp_path / "images.fits" hdu = ( @@ -162,7 +194,13 @@ def test_cpu_reader_does_not_import_gpu_dependencies(tmp_path, monkeypatch): path = _write(tmp_path, np.ones((3, 4), dtype="i4")) for name in ("cupy", "kvikio", "nvidia.nvcomp", "cuphoton.xdr"): monkeypatch.setitem(sys.modules, name, None) - assert fits_io.read_fits_images(path, [1]).reader == "astropy" + result = fits_io.read_fits_images( + path, [1], xdr_options={"decompression_backend": "hardware"} + ) + assert result.reader == "astropy" + assert result.metadata()["xdr_options"] == { + "decompression_backend": "hardware" + } def test_explicit_selection_rejects_table_empty_and_invalid_hdu(tmp_path): diff --git a/tests/xdr/test_benchmark_fits.py b/tests/xdr/test_benchmark_fits.py index 896dd2b7..676d78f7 100644 --- a/tests/xdr/test_benchmark_fits.py +++ b/tests/xdr/test_benchmark_fits.py @@ -141,9 +141,14 @@ def test_benchmark_invalid_hdu_indices_preserve_parser_error(capsys): ) +@pytest.mark.parametrize( + ("decoder", "backend"), [("deflate", "cuda"), ("gzip", "hardware")] +) def test_benchmark_command_preserves_ordered_positionals_and_options( monkeypatch, capsys, + decoder, + backend, ): import cuphoton.xdr.commands as commands @@ -166,9 +171,9 @@ def fake_run_benchmark(fits_files, **kwargs): "--xdr-postprocess", "separate", "--xdr-gzip-decoder", - "deflate", + decoder, "--xdr-decompression-backend", - "cuda", + backend, "--mock-storage", "host", "--skip-gds-read", @@ -190,8 +195,8 @@ def fake_run_benchmark(fits_files, **kwargs): assert received["hdu_indices"] == [2, 1, 2] assert received["native_batcher"] == "off" assert received["postprocess"] == "separate" - assert received["gzip_decoder"] == "deflate" - assert received["decompression_backend"] == "cuda" + assert received["gzip_decoder"] == decoder + assert received["decompression_backend"] == backend assert received["mock_storage_kind"] == "host" assert received["skip_gds_read"] is True assert received["output_json"] == Path("report.json") diff --git a/tests/xdr/test_gzip_gpu.py b/tests/xdr/test_gzip_gpu.py index a73ef719..4d1c53f3 100644 --- a/tests/xdr/test_gzip_gpu.py +++ b/tests/xdr/test_gzip_gpu.py @@ -229,6 +229,144 @@ def test_native_decoder_rejects_invalid_backend(cp, entrypoint): ) +def _hardware_limits(cp): + from cuda.bindings import driver + + device = cp.cuda.runtime.getDevice() + status, mask = driver.cuDeviceGetAttribute( + driver.CUdevice_attribute.CU_DEVICE_ATTRIBUTE_MEM_DECOMPRESS_ALGORITHM_MASK, + device, + ) + assert status == driver.CUresult.CUDA_SUCCESS + status, maximum = driver.cuDeviceGetAttribute( + driver.CUdevice_attribute.CU_DEVICE_ATTRIBUTE_MEM_DECOMPRESS_MAXIMUM_LENGTH, + device, + ) + assert status == driver.CUresult.CUDA_SUCCESS + return bool(mask & 1), maximum + + +@pytest.mark.parametrize("deferred", [False, True]) +def test_forced_hardware_roundtrip_or_unsupported_device(cp, deferred): + supported, _ = _hardware_limits(cp) + originals = [bytes(range(256)) * 1024, b"second tile" * 513] + payloads = [gzip.compress(value) for value in originals] + lengths = np.array([len(value) for value in payloads], dtype="i8") + offsets = np.cumsum(lengths) - lengths + owners = [] if deferred else None + checks = [] if deferred else None + stream = cp.cuda.Stream(non_blocking=True) + + def decode(): + return nvcomp_batch.gpu_gzip_decompress_batch( + data, + offsets, + lengths, + [len(value) for value in originals], + gzip_decoder="gzip", + decompression_backend="hardware", + use_native_pool=True, + keepalive=owners, + _decode_checks=checks, + ) + + with stream: + data = nvcomp_batch._native_device_empty_uint8(sum(lengths)) + data.set(np.frombuffer(b"".join(payloads), dtype="u1")) + if not supported: + with pytest.raises( + RuntimeError, match="unavailable on this device" + ): + decode() + return + result, out_offsets = decode() + for completion in checks or (): + completion.check() + stream.synchronize() + np.testing.assert_array_equal(out_offsets, [0, len(originals[0])]) + np.testing.assert_array_equal( + cp.asnumpy(result), np.frombuffer(b"".join(originals), dtype="u1") + ) + + +@pytest.mark.parametrize( + "ineligible,match", + [ + ("allocation", "hardware-decompression-capable"), + ("chunk_size", "exceeds device limit"), + ], +) +def test_forced_hardware_rejects_ineligible_input(cp, ineligible, match): + supported, maximum = _hardware_limits(cp) + if not supported: + pytest.skip("device has no hardware DEFLATE engine") + original = ( + bytes(maximum + 1) + if ineligible == "chunk_size" + else bytes(range(256)) + ) + payload = gzip.compress(original) + stream = cp.cuda.Stream(non_blocking=True) + with stream: + if ineligible == "allocation": + # The ordinary asynchronous pool does not opt in to hardware + # decompression. This must error, even though CUDA can decode it. + with cp.cuda.using_allocator(cp.cuda.malloc_async): + data = cp.asarray(np.frombuffer(payload, dtype="u1")) + else: + data = nvcomp_batch._native_device_empty_uint8(len(payload)) + data.set(np.frombuffer(payload, dtype="u1")) + with pytest.raises(RuntimeError, match=match): + nvcomp_batch.gpu_gzip_decompress_batch( + data, + [0], + [len(payload)], + [len(original)], + gzip_decoder="gzip", + decompression_backend="hardware", + use_native_pool=True, + ) + result, _ = nvcomp_batch.gpu_gzip_decompress_batch( + data, + [0], + [len(payload)], + [len(original)], + gzip_decoder="gzip", + decompression_backend="cuda", + use_native_pool=True, + ) + stream.synchronize() + np.testing.assert_array_equal( + cp.asnumpy(result), np.frombuffer(original, dtype="u1") + ) + + +@pytest.mark.parametrize( + "entrypoint,kwargs", + [ + ("batch_gzip_decompress", {}), + ("batch_gzip_decompress_deferred", {"use_native_pool": False}), + ("batch_deflate_decompress", {}), + ("batch_deflate_decompress_pooled", {}), + ("batch_deflate_decompress_deferred", {}), + ], +) +def test_native_hardware_rejects_incompatible_route(cp, entrypoint, kwargs): + extension = nvcomp_batch._try_get_cpp_ext() + empty = np.empty(0, dtype="i8") + with pytest.raises(ValueError, match="requires native Gzip"): + getattr(extension, entrypoint)( + 0, + empty, + empty, + 0, + empty, + empty, + decompression_backend="hardware", + **kwargs, + ) + + @pytest.mark.parametrize("native", [False, True]) @pytest.mark.parametrize("decoder", ["gzip", "deflate"]) def test_batch_decode_failure_skips_pixels_and_raises( diff --git a/tests/xdr/test_io_gpu.py b/tests/xdr/test_io_gpu.py index 4e53c72b..9f2c6f0e 100644 --- a/tests/xdr/test_io_gpu.py +++ b/tests/xdr/test_io_gpu.py @@ -247,3 +247,53 @@ def test_native_readers_recover_independently_after_failure( finally: for builder in builders: builder.request_stop() + + +@pytest.mark.parametrize("compression", ["GZIP_1", "GZIP_2"]) +def test_hardware_batch_matches_astropy(tmp_path, native_io, compression): + from astropy.io import fits + from cuda.bindings import driver + + from cuphoton.xdr import batch_to_device + + cp, _ = native_io + status, mask = driver.cuDeviceGetAttribute( + driver.CUdevice_attribute.CU_DEVICE_ATTRIBUTE_MEM_DECOMPRESS_ALGORITHM_MASK, + cp.cuda.runtime.getDevice(), + ) + assert status == driver.CUresult.CUDA_SUCCESS + if not mask & 1: + pytest.skip("device has no hardware DEFLATE engine") + + paths, expected = [], [] + for index in range(2): + image = np.arange(65 * 97, dtype=np.int32).reshape(65, 97) - index * 7 + path = tmp_path / f"image-{index}.fits" + fits.HDUList( + [ + fits.PrimaryHDU(), + fits.CompImageHDU( + image, + compression_type=compression, + tile_shape=(4, 32), + ), + ] + ).writeto(path) + with fits.open(path) as source: + expected.append(np.asarray(source[1].data, dtype=image.dtype)) + paths.append(path) + + (actual,) = batch_to_device( + paths, + hdu_indices=[1], + native_batcher=True, + native_read_threads=1, + native_plan_threads=1, + decode_batch_files=2, + decompression_backend="hardware", + ) + actual = cp.asnumpy(actual) + expected = np.stack(expected) + assert actual.dtype == expected.dtype + assert actual.shape == expected.shape + assert actual.tobytes() == expected.tobytes() diff --git a/tests/xdr/test_nvcomp_batch.py b/tests/xdr/test_nvcomp_batch.py index db3bf0d0..42b45fa5 100644 --- a/tests/xdr/test_nvcomp_batch.py +++ b/tests/xdr/test_nvcomp_batch.py @@ -935,7 +935,7 @@ def fail_decode(*args): ) -@pytest.mark.parametrize("backend", ["invalid", "hardware", "", True]) +@pytest.mark.parametrize("backend", ["invalid", "", True]) def test_gpu_batch_rejects_invalid_backend_before_import(backend): with pytest.raises(ValueError, match="decompression_backend must be"): nvcomp_batch.gpu_gzip_decompress_batch( @@ -943,9 +943,17 @@ def test_gpu_batch_rejects_invalid_backend_before_import(backend): ) -@pytest.mark.parametrize("extension", [None, SimpleNamespace()]) -def test_forced_cuda_rejects_missing_native_capability( - monkeypatch, extension +@pytest.mark.parametrize( + "backend,extension", + [ + (backend, extension) + for backend in ("cuda", "hardware") + for extension in (None, SimpleNamespace()) + ] + + [("hardware", SimpleNamespace(supports_decompression_backend=True))], +) +def test_forced_backend_rejects_missing_native_capability( + monkeypatch, extension, backend ): monkeypatch.setitem(sys.modules, "cupy", SimpleNamespace()) monkeypatch.setattr(nvcomp_batch, "_try_get_cpp_ext", lambda: extension) @@ -959,13 +967,67 @@ def test_forced_cuda_rejects_missing_native_capability( [20], [1], header_sizes=[10], - decompression_backend="cuda", + decompression_backend=backend, + use_native_pool=True, + ) + + +@pytest.mark.parametrize( + "kwargs,match", + [ + ({"gzip_wrapped": False}, "requires native Gzip"), + ( + {"gzip_decoder": "deflate"}, + "requires gzip_decoder='auto' or 'gzip'", + ), + ({"use_native_pool": False}, "requires use_native_pool=True"), + ({"use_cpp_helper": False}, "requires use_cpp_helper enabled"), + ], +) +def test_hardware_rejects_incompatible_configuration_before_import( + kwargs, match +): + options = {"use_native_pool": True, **kwargs} + with pytest.raises(ValueError, match=match): + nvcomp_batch.gpu_gzip_decompress_batch( + None, [], [], [], decompression_backend="hardware", **options + ) + + +def test_hardware_rejects_extension_without_gzip(monkeypatch): + monkeypatch.setitem(sys.modules, "cupy", SimpleNamespace()) + monkeypatch.setattr( + nvcomp_batch, + "_try_get_cpp_ext", + lambda: SimpleNamespace( + supports_decompression_backend=True, + supports_hardware_decompression=True, + ), + ) + with pytest.raises(RuntimeError, match="native extension with Gzip"): + nvcomp_batch.gpu_gzip_decompress_batch( + SimpleNamespace(size=20), + [0], + [20], + [1], + header_sizes=[10], + decompression_backend="hardware", + use_native_pool=True, ) -@pytest.mark.parametrize("backend", ["auto", "cuda"]) -@pytest.mark.parametrize("route", ["gzip", "deflate", "deflate_pooled"]) -def test_native_backend_forwarding(monkeypatch, backend, route): +@pytest.mark.parametrize( + "backend,route,retain_owners", + [ + (backend, route, True) + for backend in ("auto", "cuda") + for route in ("gzip", "deflate", "deflate_pooled") + ] + + [("hardware", "gzip_pooled", retain) for retain in (False, True)], +) +def test_native_backend_forwarding( + monkeypatch, backend, route, retain_owners +): calls = [] output = SimpleNamespace(data=SimpleNamespace(ptr=200)) owner = object() @@ -977,11 +1039,14 @@ def record(*args, **kwargs): entrypoint = { "gzip": "batch_gzip_decompress", + "gzip_pooled": "batch_gzip_decompress", "deflate": "batch_deflate_decompress", "deflate_pooled": "batch_deflate_decompress_pooled", }[route] extension = SimpleNamespace( - supports_decompression_backend=True, **{entrypoint: record} + supports_decompression_backend=True, + supports_hardware_decompression=True, + **{entrypoint: record}, ) monkeypatch.setattr(nvcomp_batch, "_try_get_cpp_ext", lambda: extension) monkeypatch.setattr( @@ -998,14 +1063,14 @@ def record(*args, **kwargs): ), ), ) - keepalive = [] if pooled else None + keepalive = [] if pooled and retain_owners else None actual, _ = nvcomp_batch.gpu_gzip_decompress_batch( SimpleNamespace(size=20, data=SimpleNamespace(ptr=100)), [0], [20], [8], - gzip_wrapped=route == "gzip", - header_sizes=[10] if route == "gzip" else None, + gzip_wrapped=route.startswith("gzip"), + header_sizes=[10] if route.startswith("gzip") else None, use_native_pool=pooled, keepalive=keepalive, decompression_backend=backend, @@ -1017,4 +1082,9 @@ def record(*args, **kwargs): assert args[6] == 300 assert kwargs == {"decompression_backend": backend} if pooled: - assert keepalive == [output, owner] + if retain_owners: + assert keepalive == [output, owner] + else: + assert keepalive is None + if route == "gzip_pooled": + assert args[7] is True diff --git a/tests/xdr/test_reader.py b/tests/xdr/test_reader.py index 7ca10f85..4e295b81 100644 --- a/tests/xdr/test_reader.py +++ b/tests/xdr/test_reader.py @@ -18,6 +18,36 @@ from cuphoton.xdr.reader import GpuCompImageReader, _validate_comp_geometry +def test_hardware_read_requires_stream_before_planning(monkeypatch): + def forbidden(*args, **kwargs): + pytest.fail("planning started for unsupported non-pooled decode") + + monkeypatch.setattr(GpuCompImageReader, "prepare_plan", forbidden) + comp_reader = object.__new__(GpuCompImageReader) + with pytest.raises(ValueError, match="requires an explicit stream"): + comp_reader.read(decompression_backend="hardware") + + +@pytest.mark.parametrize("decode", [False, True]) +def test_hardware_device_heap_requires_keepalive_before_import( + monkeypatch, decode +): + monkeypatch.setitem(sys.modules, "cupy", None) + with pytest.raises(ValueError, match="requires an explicit keepalive"): + if decode: + GpuCompImageReader.decode_from_device_heap( + None, [], {}, decompression_backend="hardware" + ) + else: + GpuCompImageReader.inflate_device_heap( + None, + [], + lengths=[], + out_bytes=[], + decompression_backend="hardware", + ) + + @pytest.mark.parametrize("use_loader", [False, True]) @pytest.mark.parametrize( ("contiguous", "short_read"),