sentryward 0.1.0__tar.gz

sentryward-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# OS files
+.DS_Store
+._*
+Thumbs.db
+
+# Editor state
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Local environments
+.env
+.env.*
+!.env.example
+.venv/
+.venv-*/
+env/
+venv/
+
+# Python outputs
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Tool caches and dependencies
+.cache/
+.ipynb_checkpoints/
+node_modules/
+
+# Project build workspace
+/build/
+
+# Python distribution outputs
+/dist/
+/wheelhouse/
+
+# Local agent instructions
+/AGENTS.md
+
+# Separate repositories
+/paper/
+/vendor/cutlass/

sentryward-0.1.0/ASSUMPTIONS.md

@@ -0,0 +1,214 @@
+# Configurable assumptions
+
+These assumptions can be enabled or disabled to select the behavior analyzed by
+the verifier. The pool is defined in [config/assumption-pool.json](config/assumption-pool.json);
+defaults are maintained in [config/default-assumptions.json](config/default-assumptions.json).
+
+## A001 — Warp-wide TMEM read completion
+
+Configuration key: `warp_tmem_load_completion`.
+
+Assume that all lanes' TMEM reads complete before any lane receives its register
+results. This adds completion dependencies across lanes in the same warp.
+
+- **Enabled:** analyze with these dependencies. Lifecycle and memory-race findings
+  excluded by the added ordering remain visible as A001 warnings, with concrete
+  instruction or access pairs. Unaffected findings remain errors.
+- **Disabled:** analyze the original completion dependencies and report any
+  resulting race or lifecycle error.
+
+Warnings have bounded samples and a total count. The output records whether the
+comparison completed; an unsuccessful comparison does not establish absence of
+excluded findings.
+
+## A002 — Benign duplicate TMA stores
+
+Configuration key: `duplicate_tma_store_benign`.
+
+Assume that matching duplicate TMA stores issued by different lanes of the same
+warp are benign. Matching requires the same PTX instruction occurrence and copy
+footprints; equality of the stored values is assumed rather than proved.
+
+- **Enabled:** report matching unordered stores as warnings and continue checking
+  other accesses. A complete check with no remaining race or unresolved query
+  returns `race_free`, with warnings reported separately.
+- **Disabled:** report these unordered, overlapping writes as race candidates.
+
+## A003 — Immediate memory visibility
+
+Configuration key: `immediate_visibility`.
+
+Assume that a memory effect becomes visible to other participants immediately
+when it executes. Asynchronous operations still execute separately from their
+issue instructions and require completion synchronization.
+
+- **Enabled:** analyze immediate visibility. Pure visibility/ordering fences add
+  no constraints. Async completion waits and synchronization remain modeled.
+  Combined operations such as `tensormap.cp_fenceproxy` retain their copy effects;
+  only their visibility-ordering component is ignored.
+- **Disabled:** report unsupported because weak-memory analysis is unavailable,
+  with a suggestion to enable A003.
+
+## A004 — Representative elected lane
+
+Configuration key: `representative_election`.
+
+Assume that analyzing one representative election outcome is sufficient. Choose
+lane 0 when it participates; otherwise choose the lowest-numbered participating
+lane.
+
+- **Enabled:** analyze that elected lane's execution.
+- **Disabled:** report election instructions as unsupported, with a suggestion
+  to enable A004.
+
+## A005 — Failed cluster launch cancellation
+
+Configuration key: `clc_always_fails`.
+
+Assume that every cluster launch cancellation (CLC) request fails. A CTA therefore
+does not acquire additional work from a canceled launch.
+
+- **Enabled:** analyze the failed-request path.
+- **Disabled:** report CLC instructions as unsupported, with a suggestion to
+  enable A005.
+
+## A006 — Representative data-dependent control
+
+Configuration key: `representative_data_branches`. Related input key:
+`data_branch_loop_iterations` (optional positive integer; default `4`).
+
+Some branches and instruction guards depend on values that the fixed input does
+not determine, such as tensor contents or metadata buffers that were not supplied
+through `shape_arrays`. Assume that analyzing one recorded representative outcome
+for such control is sufficient:
+
+- a data-dependent loop body runs `data_branch_loop_iterations` times;
+- a branch direction whose straight-line code ends in `trap` or `__assertfail`
+  is never chosen;
+- an undetermined instruction guard executes.
+
+Before A006 is considered, a forward region whose arms only compute or read
+parameter, local or constant memory is skipped exactly, whether or not A006 is
+enabled: neither outcome has a memory or synchronization effect, and every
+register the region writes becomes unknown. This extends the single-arm
+treatment to if-else and nested arms; results list these regions under
+`frontend_assumptions.opaque_compute_regions`. Flag polling loops are left only
+under A007.
+
+A006 is a last resort. It applies only after ordinary execution, including the
+shared-memory cluster re-execution and the exact treatment above, has stopped on
+undetermined control, so it never changes a kernel that the fixed input already
+determines. Every lane makes
+the same choice at a given branch visit. Results list each decided PTX line, the
+rule used and the taken/not-taken counts under
+`frontend_assumptions.data_branch_decisions`.
+
+The analyzed execution need not be one that any real input produces. Choices are
+made independently, so two tests of the same value can disagree; divergence that
+a real input would cause between lanes is not explored; and a race that needs
+more loop iterations than the bound, such as a pipeline that has to wrap around,
+is not reached. Prefer supplying the data (`arguments`, `shape_arrays`), which
+keeps the analysis exact, and set the iteration bound above the deepest pipeline
+the kernel cycles through.
+
+- **Enabled:** analyze the representative outcome and record the decisions.
+- **Disabled:** report `branch_not_static` (or `missing_parameter_value`), with
+  a suggestion to supply the data or enable A006.
+
+## A007 — Terminating spin-waits
+
+Configuration key: `terminating_spin_waits`.
+
+Assume that a loop that only polls (compute, `nanosleep`, and global or generic
+reads from addresses the loop does not change) is eventually released by another
+agent, such as another CTA setting a flag. Every iteration touches the same
+locations, so leaving after one poll keeps the CTA's memory and synchronization
+effects; registers written in the loop become unknown. Like A006, A007 applies
+only after ordinary execution has stopped on the loop's undetermined condition.
+Results list these loops under `frontend_assumptions.spin_wait_exits`.
+
+A kernel whose flag is never set hangs on hardware; under A007 that hang is not
+reported.
+
+- **Enabled:** leave polling loops after one poll and record them.
+- **Disabled:** report `branch_not_static` for the loop's condition.
+
+## Address invariants
+
+Input key: `address_invariants` (optional array; default `[]`).
+
+Unlike A001–A007, address invariants are not on/off flags. They are trusted
+facts about runtime address values that the symbolic address model may use to
+prove two memory accesses disjoint. The verifier does not check them. If an
+invariant is false for the analyzed execution, a real race may be reported as
+safe. Any nonempty set makes the result `assumption_dependent`, and results
+repeat the set under `address_model.address_invariants`.
+
+### How the address model uses them
+
+Each address is an allocation plus an offset `c0 + sum(ck * atom_k)`. An atom is
+one runtime value identified by where it came from, so repeated uses of the
+same value share one atom. The model first reuses the exact constant-offset
+analysis. Pairs it cannot decide go through two layers:
+
+- **Allocation separation (no invariants needed).** Accesses in different known
+  memory spaces, or in different named allocations of one space, are disjoint.
+  Allocations sharing an alias scope, `generic` addresses, and unresolved
+  allocations are not separated.
+- **SMT layer.** For two accesses in the same allocation, the model asks Z3
+  whether the byte ranges can intersect under the invariants. They are disjoint
+  only if Z3 proves they cannot. A satisfiable result, a timeout, or an
+  inconsistent invariant set leaves the pair unresolved; the reason includes a
+  candidate valuation when one exists. Offsets differing by a constant are
+  decided without the solver, and an intersection is then reported as an
+  overlap for every valuation.
+
+Without invariants, and in builds configured with `-DSENTRYWARD_WITH_Z3=OFF`,
+same-allocation pairs with symbolic offsets stay unresolved.
+
+### Invariant forms
+
+Each array entry is an object of one of these forms:
+
+| Form | Meaning |
+| --- | --- |
+| `{"term": T, "lower_bound": L, "upper_bound": U, "multiple_of": M}` | `L <= T <= U` and `T` is divisible by `M` (a positive integer). At least one of the three fields is required; bounds are inclusive. |
+| `{"gather": "g", "injective": true, "lower_bound": L, "upper_bound": U}` | Every lookup in table `g` lies in `[L, U]`. If injective, different ground arguments give different results. |
+| `{"joint_injective": ["r", "s", ...]}` | For different ground arguments, at least one of the named tables gives different results. |
+| `{"distinct_allocations": ["A", "B", ...]}` | The named allocations are pairwise distinct storage. |
+
+Unknown fields, empty names, empty ranges and contradictory term bounds make the
+input invalid.
+
+`T` is a scalar expression:
+
+- an integer;
+- `{"operator": "param", "symbol": "PAGE"}`: an immutable runtime scalar;
+- `{"operator": "gather", "symbol": "pages", "args": [3]}`: a table lookup with
+  integer arguments;
+- `add`, `sub`, `mul` or `neg` with an `operands` array.
+
+A product of two non-constant operands becomes its own atom with no assumed
+value. A term that names that product can still bound it.
+
+Allocation names in `distinct_allocations` are binding allocation names (for
+example `epilogue.tensormaps`), or symbolic targets of runtime tensor maps. A
+TMA transfer whose tensor map's global address is unknown reads
+`tensor_map_target(<location>+<offset>)`, where the location and offset identify
+where the tensor map is stored. Unresolved-pair diagnostics print these names.
+Two tensor-map targets are never assumed equal or distinct without an
+invariant.
+
+Example: page table `pages` maps logical blocks to distinct physical pages, and
+the tensor read through one tensor map does not alias a workspace:
+
+```json
+"address_invariants": [
+  {"gather": "pages", "injective": true, "lower_bound": 0},
+  {"distinct_allocations": ["tensor_map_target(input.arg0.1184+0)", "epilogue.tensormaps"]}
+]
+```
+
+The PTX frontend does not yet emit `param` or `gather` atoms. Today the SMT
+layer applies to operand-derived offsets and to source JSON produced by other
+tools, while `distinct_allocations` applies directly to frontend output.