DAP: Add intrin DAPSpecs

We now specify intrins as separate DAPS lines. This syntax is much
nicer and well-grouped than the previous negtrin-*/postrin-* param
names.

Alas, we're about to replace it in the next few commits already though.
This commit is contained in:
2026-04-12 04:06:47 -04:00
parent c696316a1e
commit fc1fcae0b0
14 changed files with 595 additions and 284 deletions
+21 -10
View File
@@ -18,9 +18,11 @@ descriptors tell it exactly which body spots are raising it.
This direct information also assists SMO in narrowing down the scope of its
DB searches for methods to handle (increase or decrease) the stimval. For
example, for a pcloudIntensity negtrin, we don't search DB by trying to
match all possible body spots with their stimvals. Rather, we search for all
the body spots that are described in the stencil. This optimizes DB searches
example, for a negtrin whose intrinsic pipeline is declared with a dedicated
`negtrin(...)` spec (and whose sensory data may come from intensity or another
stimbuff via `from-stimbuff`), we don't search DB by trying to match all
possible body spots with their stimvals. Rather, we search for all the body
spots that are described in the stencil. This optimizes DB searches
and also makes negtrin relieving/postrin satisfying searches more explicit
and obviously scoped items of knowledge. The eventual solution is
automatically classified as being a method to relieve/satisfy intrins at
@@ -60,9 +62,15 @@ be non-negotiable.
## n-stencils QualeIfaceApi Parameter
A new qualeIfaceApi parameter called `n-stencils` tells the stimbuff how
many stencils it can allocate and deliver to SMO simultaneously. The
stimbuff must wait until SMO returns stencils to it via postrinEventRdy or
Where a stim buff supports it, a qualeIfaceApi parameter called `n-stencils`
tells the stimbuff how many stencils it can allocate and deliver to SMO
simultaneously for **intrinsic** delivery. Intrinsic rate limiting and stencil
counts apply to **dedicated** intrinsic qualeIfaceApi specs (`negtrin(...)`,
`postrin(...)`) when the implementation attaches them—not to sensory-only
lines such as `pcloudIntensity` or `pcloudAmbience` (see
`docs/design/intrin-thresholds.md`).
The stimbuff must wait until SMO returns stencils to it via postrinEventRdy or
negtrinEventRdy before delivering new intrin events. Stimbuffs can deliver
as many intrin events as they have stencils for. When all of their stencils
have been given to SMO, they must wait until SMO returns a stencil before
@@ -77,14 +85,17 @@ raising new intrins.
- Stimbuffs must respect this limit and wait for stencil returns before
allocating new ones
**Example (generic device):**
**Example (generic dedicated intrin line—shape only; names depend on device):**
```
+idev|my-device|someQualeApi(n-stencils=4)|someStimBuffApi()|livoxProto1()|SERIAL
+idev|my-device|negtrin(from-stimbuff=someSensoryQuale|n-stencils=4)|someStimBuffApi()|livoxProto1()|SERIAL
```
The `pcloudAmbience` Livox Gen1 path does **not** use the `n-stencils` parameter; ambience data is delivered as a dense float vector in the stimulus frame buffer, not via a separate stencil allocation list.
The Livox Gen1 **`pcloudAmbience`** sensory line does **not** use `n-stencils`;
ambience floats are delivered in the stimulus frame buffer. If Livox adds
`n-stencils` for intrinsic pipelines, it would appear on **`negtrin(...)`** /
**`postrin(...)`** lines (with `from-stimbuff`), not on `pcloudAmbience` itself.
**Deprecated example (do not use for Livox Gen1 ambience):**
**Invalid (sensory qualeIfaceApi must not carry intrin-oriented params):**
```
+idev|my-device|pcloudAmbience(n-stencils=4)|livoxGen1-pcloud()|livoxProto1()|3JEDK380010Z39
```