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
295 changes: 295 additions & 0 deletions docs/architecture/sircl-schedule-selection.md

Large diffs are not rendered by default.

30 changes: 21 additions & 9 deletions integrations/vllm/glm_dcp_decode_comm/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# glm_dcp_decode_comm

A vLLM general plugin (distribution `glm-dcp-decode-comm` 2.0.2, entry point
A vLLM general plugin (distribution `glm-dcp-decode-comm` 2.0.3, entry point
`glm_dcp_decode_comm = glm_dcp_decode_comm:register`) that changes how
GLM-5.3's DSA attention layers run their decode context parallel (DCP)
collectives when those collectives run on a SIRCL DCP session. Every item is
Expand Down Expand Up @@ -89,7 +89,7 @@ GLM_DCP_DECODE_A2A_FUSED=1
GLM_DCP_DECODE_AUDIT=1
```

It passes when every rank logs the startup line `glm_dcp_decode_comm 2.0.2:
It passes when every rank logs the startup line `glm_dcp_decode_comm 2.0.3:
enabled ...` naming the five items and audit mode, no `PatchRefused`, and
every `glm_dcp_decode_comm audit cuda:N: CHECK: ...` line of every rank
reports `0 differ` with a nonzero call count for each of the five checks
Expand Down Expand Up @@ -140,19 +140,31 @@ The pins describe two builds:
- the image's vLLM and b12x files: serving image `816c6d6a7e96`;
- SIRCL: package version 0.3.2, SparkRing's
[`spark_transport/sircl/sparkring_sircl`](../../../spark_transport/sircl/sparkring_sircl)
as commit `32c41e7f` has it, the source of the SIRCL layer of release
2026.10.4's image (Git tree `a385bb72b629` of `sparkring_sircl`).
as commit `ab9e2888` has it, with the opt-in `SIRCL_SUBSET_RING` subset
mode (Git tree `462e000619e1` of `sparkring_sircl`).

Version 2.0.1, which the images of releases 2026.10.2, 2026.10.4 and 2026.10.5 carry,
pins the same files except `vllm/adapter.py`: it pins that file as release
2026.10.2's SIRCL layer has it (SHA-256 `7eab095f…`, Git tree `7b40507046a3`
of `sparkring_sircl`), and 2.0.2 pins it as commit `32c41e7f` has it (SHA-256
`ebe9b323…`), which adds the `max_relays` and `route_scope` fields to
`AdapterConfig` and `GroupPlacement` and leaves `GroupAdapter`'s `.dcp`,
`.session` and `live_adapters` unchanged. Each version therefore refuses an
item flag on the other release's image. With every item flag `0`,
registration patches nothing and compares no pin, so a profile that loads
the plugin with its items off starts on either image.
`.session` and `live_adapters` unchanged.

Version 2.0.3 pins the same files as 2.0.2 except `oneshot/runtime.py`: 2.0.2
pins that file as commit `32c41e7f` has it (SHA-256 `631cc652…`), and 2.0.3
pins it as commit `ab9e2888` has it (SHA-256 `308e278b…`), which adds the
subset admission, the subset schedule notices and the subset early returns.
Every member the file's reason names (`all_gather(out=)`, the arena view,
`_counter_addresses`, `_order_stream`, `_mark_stream`, `_tuned_op`, `_lock`,
`check_health` and the launch geometry) keeps its definition, its signature
and its call order, and every subset statement runs only when
`SIRCL_SUBSET_RING=1`, so a session that leaves the variable unset takes the
ops and settings 2.0.2's build takes.

Each version therefore refuses an item flag on the other release's image.
With every item flag `0`, registration patches nothing and compares no pin,
so a profile that loads the plugin with its items off starts on either image.

Against SIRCL 0.3.0 (image `816c6d6a7e96`), 0.3.1 changes five of the 17
pinned files: the version in `__init__.py`; aligned working buffers around
Expand Down Expand Up @@ -207,7 +219,7 @@ and the qualification run again.
| `glm_dcp_decode_comm/_scatter_pack_cute.py` | the CuTe DSL packed all-to-all, the pinned SIRCL build's scatter op with the pack in its staging |
| `glm_dcp_decode_comm/layout.py` | the query and wire-format geometry and the kernel's index helpers (pure Python) |
| `glm_dcp_decode_comm/reference.py` | torch references of the image's computations and of the plugin's replacements |
| `dist-info/glm_dcp_decode_comm-2.0.2.dist-info/` | the installed distribution's metadata and its `vllm.general_plugins` entry point |
| `dist-info/glm_dcp_decode_comm-2.0.3.dist-info/` | the installed distribution's metadata and its `vllm.general_plugins` entry point |
| `tools/refresh_pins.py` | records or checks every pin against vLLM, b12x and SIRCL trees |
| `tests/` | the CPU suite (`test_dcp_decode_*.py`), the subprocess driver over SIRCL's CUDA stand-in (`scatter_driver.py`) and the GPU checks (`gpu_checks.py`) |

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Metadata-Version: 2.1
Name: glm-dcp-decode-comm
Version: 2.0.2
Version: 2.0.3
Summary: vLLM general plugin that makes the GLM-5.3 DSA decode collectives of decode context parallelism cheaper on a SIRCL DCP session of image 816c6d6a7e96, with exact results: the query built by one kernel and gathered into the attention workspace, the DCP collectives on their own stream, the indexer wk GEMM beside the latent projection, one top-k slot conversion per indexer layer and the all-to-all combine packed into the scatter op; each item off until its GLM_DCP_DECODE_* flag is 1
Requires-Python: >=3.12
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@
from types import CodeType, FunctionType, ModuleType

PLUGIN_NAME = "glm_dcp_decode_comm"
PLUGIN_VERSION = "2.0.2"
PLUGIN_VERSION = "2.0.3"
MARKER = "__glm_dcp_decode_comm__"
HELPER_PREFIX = "_glm_dcp_decode_comm_"
IMAGE = "816c6d6a7e96"
Expand Down Expand Up @@ -314,7 +314,7 @@ class FileCheck:
"bebd8e7117ae5ec462b1871a12ebde30eadbebf89a45dc4bf645fa076f2b9411",
"the scatter piece rules that decide when an all-to-all is one op"),
FileCheck("sparkring_sircl", "oneshot/runtime.py",
"631cc65241508e60ed48d30b9f6dbedbef831f025661f8d355350834d7ea5645",
"308e278b87cb352d71efeb647907156d600d289c8b3fca757bf3a145df6b73e9",
"RoceOneshotAllReduce: all_gather(out=), the arena view, _counter_addresses, _order_stream, "
"_mark_stream, _tuned_op, _lock, check_health and the launch geometry"),
FileCheck("sparkring_sircl", "oneshot/_scatter_ops.py",
Expand Down
2 changes: 1 addition & 1 deletion runtime/common/test_image_lock.py
Original file line number Diff line number Diff line change
Expand Up @@ -463,7 +463,7 @@ def test_the_glm53_tp8_profile_runs_only_on_an_image_that_carries_the_glm53_plug
profile = "glm53-nvfp4-tp8"
assert image_lock.required_plugins(profile) == ["glm_dsa_indexer_split", "glm53full_speedups",
"glm_dcp_decode_comm"]
assert derive_glm53_plugins.PLUGINS == {**PLUGINS, "glm_dcp_decode_comm": "2.0.2"}
assert derive_glm53_plugins.PLUGINS == {**PLUGINS, "glm_dcp_decode_comm": "2.0.3"}
with pytest.raises(ValueError, match=f"{profile} loads the vLLM plugins glm_dsa_indexer_split, "
"glm53full_speedups, glm_dcp_decode_comm"):
image_lock.for_profile(profile, with_eight_spark_profiles())
Expand Down
4 changes: 2 additions & 2 deletions runtime/images/derive_glm53_plugins.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
the fused ``q_a``/``kv_a`` latent projection is column-parallel over TP8
with one all-gather (``GLM53FULL_LATENT_SHARD=1``) and the MTP ``eh_proj``
is row-parallel (``GLM53FULL_EH_PROJ_TP=1``);
- ``glm_dcp_decode_comm`` 2.0.2 (``integrations/vllm/glm_dcp_decode_comm``):
- ``glm_dcp_decode_comm`` 2.0.3 (``integrations/vllm/glm_dcp_decode_comm``):
exact changes to the DSA attention's decode context parallel collectives on
a SIRCL DCP session, five items behind the ``GLM_DCP_DECODE_*`` flags (the
query pack, the communication-stream overlap, the indexer ``wk`` overlap,
Expand Down Expand Up @@ -84,7 +84,7 @@
SPEEDUPS = "integrations/vllm/glm53full_speedups/"
DCP = "integrations/vllm/glm_dcp_decode_comm/"
DCP_MODULES = ("__init__.py", "_scatter_pack_cute.py", "kernels.py", "layout.py", "reference.py", "runtime.py")
DCP_DIST_INFO = "glm_dcp_decode_comm-2.0.2.dist-info/"
DCP_DIST_INFO = "glm_dcp_decode_comm-2.0.3.dist-info/"

# Every added file: the site-packages path, its repository source and the
# SHA-256 of the repository bytes (the layer pins each result; additions have
Expand Down
2 changes: 1 addition & 1 deletion runtime/images/installer-images.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ inherited SHA-256 `None`, and the parent receipt must not record it.
tool-result policy as a vLLM module and pins the `serving.py` that installs it.
[derive_glm53_plugins.py](derive_glm53_plugins.py) adds the GLM-5.3 vLLM
general plugins `glm_dsa_indexer_split` and `glm53full_speedups` 1.1.0 and
`glm_dcp_decode_comm` 2.0.2 with their dist-info directories and names all
`glm_dcp_decode_comm` 2.0.3 with their dist-info directories and names all
three in `Layer.plugins`.

The derived lock has its parent lock's schema. A parent with a
Expand Down
4 changes: 2 additions & 2 deletions runtime/images/test_derive_glm53_plugins.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ def test_replace_returns_only_the_pinned_files():

@pytest.mark.parametrize("plugin,package,version", [("glm_dsa_indexer_split", "glm-dsa-indexer-split", "1.1.0"),
("glm53full_speedups", "glm53full-speedups", "1.1.0"),
("glm_dcp_decode_comm", "glm-dcp-decode-comm", "2.0.2")])
("glm_dcp_decode_comm", "glm-dcp-decode-comm", "2.0.3")])
def test_dist_info_registers_the_plugin_in_vllm_general_plugins(plugin, package, version):
root = Path(derive_glm53_plugins.ROOT)
metadata = (root / "integrations/vllm" / plugin / "dist-info"
Expand Down Expand Up @@ -72,7 +72,7 @@ def re_fullmatch(value: str) -> bool:

def test_the_layer_declares_each_plugin_at_its_dist_info_version():
"""The derived v3 lock lists exactly the entry points and versions the layer's dist-info files register."""
assert derive_glm53_plugins.PLUGINS == {"glm53full_speedups": "1.1.0", "glm_dcp_decode_comm": "2.0.2",
assert derive_glm53_plugins.PLUGINS == {"glm53full_speedups": "1.1.0", "glm_dcp_decode_comm": "2.0.3",
"glm_dsa_indexer_split": "1.1.0"}
assert derive_glm53_plugins.LAYER.plugins == derive_glm53_plugins.PLUGINS
for name, version in derive_glm53_plugins.PLUGINS.items():
Expand Down
176 changes: 176 additions & 0 deletions spark_transport/sircl/SUBSET_RING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
# Subset chain all-gather

**Experimental.** Set `SIRCL_SUBSET_RING=1` and `SIRCL_ROUTE_SCOPE=fabric`
on the tensor-parallel session, or use the serve/bundle option `--subset-ring`.
The public option retains its name for compatibility. It is off by default.

On an admitted subset, only flat (1-D) `all_gather_large` can use chain.
The input shard must be at least 4 MiB, satisfy the existing alignment/shape
checks, and meet the configured chain minimum for automatic selection.
Explicit `pieces` disables it. A `ring` gather request becomes `auto`.
All-reduce, reduce-scatter, row, padded and 2-D gathers use the pieces path;
small collectives retain their existing one-shot/two-shot behavior. Runtime
schedule overrides and tuning choices cannot enable subset ring operations.
Every native ring neighbor is disabled and its window is zero.

Admission requires a cable-connected arc of at least three ranks on a cycle
of four to eight Sparks, leaving one or two adjacent non-members. Wrapping
arcs and reordered ranks are supported. Larger complements are refused,
including when idle. Use the universal same-function relay table of the
complete cycle; setup verifies every lane against that table. The mode
does not install or modify fabric routes. Full-fabric sessions retain their
existing behavior even when the option is set.

## Selection evidence

The six-rank measurement of `cb519293` on ring8 positions 0-5, with DCP2
on 6-7, found flat all-gather chain throughput at 1.20x OFF for 4 MiB
shards and 1.32x for 16 MiB shards. Those are hardware measurements of that
revision, not qualification of this policy. The 4 MiB floor avoids enabling
chain for the small and 1 MiB cases. Other sizes at or above that floor and
other admitted placements require hardware confirmation.

Reduce-scatter can traverse the same direct chain, but its two partial
reductions, scratch storage and rendezvous differ from forwarding gather
shards. All-reduce also performs reduction and return traffic. Direct cables
alone do not establish a speedup for either collective; both remain on pieces.

The measured padded/2-D gather regression occurred despite unchanged 2 MiB
pieces. The former opt-in changed the underlying transport: chunks shrank
from 32 KiB to 4 KiB, the common per-queue allowance shrank from 393,216 to
90,112 bytes, and delivery-proof credit release was disabled. On the busiest
five-lane queues, per-lane windows shrank from 65,536 to 16,384 bytes.
More chunk posts and longer credit waits can slow the same GPU pieces.
The measurement changed these settings together and does not isolate their
individual costs. This mode now uses exactly the OFF pieces sizes, forward
windows, transport chunks and native ACK-release policy, including explicit
user overrides. Recovery of throughput still needs hardware verification.

## Capacity and isolation

The active chain consists solely of direct neighbor lanes in both directions.
It adds **zero data or ACK bytes** to every relay hairpin queue. There is no
closing edge, ring-window reservation or relayed link operation. Sessions
confined to the one/two adjacent non-members likewise add zero relay bytes.
These facts hold independently of traffic rate and are checked across the
admitted layouts. Direct traffic still competes for cables and NIC resources;
DCP2 decode isolation must be measured with no unrelated clients.

Pieces keeps the OFF capacity model: default forward windows share 75% of
the declared queue, rounded to 32 KiB chunks; disabling windows uses the
existing relay-load piece limit. On the admitted default lane maps the sum
of windows is at most 393,216 bytes per 524,288-byte queue. Chain adds zero
to that bound. The mode continues reserving the full collective share from
the same-instance P2P allocator, preventing extra relayed P2P sessions.
Overlapping independent deployments on the member positions are not covered.

This is a payload/delivery bound inherited from OFF, **not** a proof of
physical packet occupancy including NIC cell accounting, pending ACKs and
retransmissions. In particular, restoring early credit release invalidates
using the former conservative combined ring/arena packet envelope as an
active-session guarantee. No such guarantee is claimed here.

The conservative helpers remain unused by the active subset runtime and
planner: `subset.payload_budget`, and `routes.ring_window` /
`routes.forward_windows` with `subset_ring=True`. Their tests still verify
`4B + C(q) <= Q`, with `B = min(floor(.75Q), floor((Q-Cmax)/4))` and
`C(q) = n(q)*64*2*128`, and exercise bounded native ring progress.
That conditional model assumes MTU >= 256, at most 128 bytes of framing
and queue accounting per packet, no retained retransmission copies and
credit release only on returning completion. It applies only to those
explicitly bounded helper configurations, not the restored OFF pieces path.

## Larger-window analysis

The offline helper `subset.ring_packet_bound` fixes the conservative arena
windows from `forward_windows(..., chunk=4096, subset_ring=True)` and solves
each queue separately for a common ring window R. It does not configure the
runtime. For each directed QP i, let A_i be its arena window. Its shared
native `unacked` counter bounds arena plus ring payload by `max(A_i, R)`
when it carries the ring, and by A_i otherwise. Let D(q,R) sum those bounds
for every QP traversing q. The inequality is:

```text
1.5*D(q,R) + 0.5*D(reverse(q),R) + C(q) <= 524288
```

This uses `_roce_proxy.c`'s `post_stream_write`, `link_pump_windowed` and
`ack_push`: both pumps test the same device/peer byte counter. With delivery
proof disabled, only returning completion releases those bytes. Payload on
other QPs can remain live. The helper includes ACK-only queues and finds the
largest common 32 KiB-aligned window satisfying every inequality. This is the
maximum **within this fixed-arena, shared-QP envelope**. Trading arena capacity
for ring capacity changes the optimization problem. Control credits are also
shared by arena and ring on each native QP and are counted once.

For TP6 on positions 0-5 of ring8, the closing route is 5-6-7-0. A deployment
confined to 6-7 sends both its payload and ACKs over their direct cable, using
zero hairpin bytes. The limiting queues are the secondary function toward
port 0 on positions 6 and 7:

| Quantity | Bytes |
|---|---:|
| Conservative arena windows in each direction (three lanes) | 86,016 |
| Control reserve (six directed QPs times 16,384) | 98,304 |
| Arena window on the QP that also carries the ring | 28,672 |
| Other forward arena QPs, still independently live | 57,344 |
| Fixed other-QP framing, reverse arena ACKs and controls | 227,328 |
| Residual for shared ring-QP payload and framing | 296,960 |
| Unrounded ring payload allowance, floor(296960 / 1.5) | 197,973 |
| Largest common 32 KiB-aligned window | **196,608** |
| Occupancy bound at that window | 522,240 |
| Occupancy at the next 32 KiB window (229,376) | 571,392: refused |

This improves the retained helper's 65,536-byte common budget by three times.
It is not close to the normal 393,216-byte ring window. Even an isolated
393,216-byte data window would require 589,824 bytes with the minimum-MTU
framing assumption, before controls or reverse traffic. An isolated single
ring lane with no arena traffic can fit 327,680 bytes under this envelope;
that requires an arena/ACK drain, which the active subset runtime does not
establish. Larger MTU assumptions require negotiated-MTU enforcement and a
separate reviewed proof; measured absence of drops does not supply that proof.

The active arena windows are larger than the conservative helper's and retain
delivery-proof release. Its proof assumptions therefore do not hold merely by
setting `SIRCL_SUBSET_RING=1`. Subset ring all-reduce stays disabled, and flat
all-gather keeps chain. No default or opt-in transport setting changes here.

Using the inferred SIRCL window/RTT model in
[schedule selection](../../docs/architecture/sircl-schedule-selection.md),
196,608 bytes over two relays predicts 16.90 GB/s before kernel and cable/NIC
contention, or about 1.47 times 11.5 GB/s pieces. Applying the measured
57/46.4 RTT-growth sensitivity gives 13.76 GB/s, about 1.20 times pieces.
These are conditional steady-state predictions, not measured gains. A
co-resident DCP2 workload can further reduce available bandwidth. Using the
profiled net-sircl 40.3 us directly instead predicts 9.76 GB/s (0.85 times
pieces); the different transport/profiling conditions are material.

## Validation gates

Run `python -m pytest spark_transport/sircl -q`. The subset tests cover
admission, direct chain lanes, active payload bounds, retained conservative
helper bounds, runtime schedule selection, ON/OFF pieces equality, native
progress and OFF byte hashes generated from `df86c93d`.
GPU emulation must cover exact eager and captured/replayed flat and padded
gathers and all-reduces, with delayed link progress and matching native
ACK-release settings. Emulation does not measure hairpin drops or serving
performance.

The offline selector tests cover every path/cycle size from two to eight,
representative subset and co-resident placements, odd cycles, ACK-only queues,
measurement precedence and rejection of unbounded candidates. The fixed-arena
ring bound is checked for every admitted subset, including failure of the
next larger common window. The selector's drained candidates do not change
runtime admission. Both hardware plans, including the restoration budget and
the 25-minute feasibility limit, are in the
[selection design](../../docs/architecture/sircl-schedule-selection.md#hardware-validation-plans).

Before promotion, coordinate a maximum 25-minute TP6 outage on positions
0-5, preserving DCP2 on 6-7 with no other client. Pre-stage artifacts and
budget restoration time before taking TP6 down. Measure three ABBA blocks
(12 arms) of large flat/row/padded gathers and all-reduces, plus small
messages, using identical configurations except the opt-in. Require exact
results, zero drops on all eight Sparks, DCP2 decode within predeclared A/A
noise, and every case at least 0.97x OFF throughput (OFF/ON latency for
small messages). An incomplete block, noisy baseline or missed deadline
is inconclusive; restore TP6 within the reserved time and keep the mode off.
Loading
Loading