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:
@@ -9,6 +9,32 @@ allow the stimbuff API library to determine when to construct a stencil
|
||||
for postrin or negtrin data and present it to SMO with appropriate
|
||||
importance classifications.
|
||||
|
||||
**Intrinsic parameters may appear only on dedicated intrinsic qualeIfaceApi
|
||||
specs.** The only supported forms are **`negtrin(...)`** and **`postrin(...)`**.
|
||||
You cannot attach intrinsic threshold params to a sensory or other
|
||||
non-intrinsic qualeIfaceApi (for example `pcloudIntensity`, `pcloudAmbience`,
|
||||
`mesh`, `pcloud`, and so on). Those lines are for sensory streams only.
|
||||
|
||||
A dedicated intrinsic line must name the sensory stimbuff it derives from via
|
||||
**`from-stimbuff=<qualeIfaceApi>`** (non-empty). Policy validation rejects
|
||||
intrinsic params and passband-style comparators on sensory lines, and rejects
|
||||
dedicated lines that omit `from-stimbuff`.
|
||||
|
||||
## Dedicated `negtrin` / `postrin` qualeIfaceApi names
|
||||
|
||||
On **`negtrin(...)`** or **`postrin(...)`**, the intrinsic family (negative vs
|
||||
positive) is fixed by the API name. The **`negtrin-`** and **`postrin-`**
|
||||
prefixes on parameter names are **optional**: you may use short forms
|
||||
**`interest-...`**, **`distraction-...`**, **`stupefaction-` / `stupefying-...`**,
|
||||
and **`intolerable-...`** with the unit suffix rules below. Prefixed names such
|
||||
as **`negtrin-interest-pc`** remain valid when you prefer explicit spelling.
|
||||
|
||||
Example (negtrin driven by ambience, short interest param, passband comparator):
|
||||
|
||||
````
|
||||
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
|
||||
````
|
||||
|
||||
## Unit Suffix Rules
|
||||
|
||||
All intrinsic threshold params must include an explicit unit suffix.
|
||||
@@ -30,118 +56,74 @@ intrinsic classification. If multiple unit-suffixed variants targeting
|
||||
the same classification are supplied anyway, the lattermost supplied
|
||||
parameter takes precedence.
|
||||
|
||||
Shorthand params without a unit suffix are not permitted anymore. The
|
||||
following forms are invalid because they all omit units:
|
||||
Shorthand params without a unit suffix are not permitted. The following
|
||||
forms are invalid because they omit units:
|
||||
|
||||
- `[<pos|neg>trin-]<interest|distraction|stupef<action|ying>|intolerable>`
|
||||
|
||||
For stupefying and intolerable thresholds specifically, the `postrin-`
|
||||
or `negtrin-` prefix may be omitted when the intended intrinsic is
|
||||
already implied by the classification itself. Even in those cases, a
|
||||
unit suffix is still mandatory.
|
||||
On dedicated **`postrin(...)`** / **`negtrin(...)`** lines, the short forms
|
||||
**`interest-...`**, **`distraction-...`**, etc. still require those unit
|
||||
suffixes.
|
||||
|
||||
## Interest Threshold Parameters
|
||||
|
||||
**Parameter forms:**
|
||||
- `postrin-interest-<percentage|pc|threshold|thresh|thr>`
|
||||
- `negtrin-interest-<percentage|pc|threshold|thresh|thr>`
|
||||
**Parameter forms (only inside `negtrin(...)` or `postrin(...)`):**
|
||||
|
||||
- Prefixed: `postrin-interest-<percentage|pc|threshold|thresh|thr>`,
|
||||
`negtrin-interest-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short (prefix optional because the line is already negtrin or postrin):
|
||||
`interest-<percentage|pc|threshold|thresh|thr>`
|
||||
|
||||
**Description:**
|
||||
These parameters denote the value at which the stimbuff API library
|
||||
should construct a stencil for the postrin or negtrin that it delivers
|
||||
for this DAPSpec's qualeIfaceApi's stimfeat, and present it to SMO via
|
||||
postrinInd/negtrinInd with the "importance" argument set to "INTERESTING".
|
||||
for this intrinsic spec, and present it to SMO via postrinInd/negtrinInd
|
||||
with the "importance" argument set to "INTERESTING".
|
||||
|
||||
**Specification:**
|
||||
- The parameter is specified as part of the `quale-iface-api-params`
|
||||
in the DAP specification
|
||||
- The unit suffix rules from the top of this document apply here too
|
||||
- Separate thresholds can be specified for postrin and negtrin using the
|
||||
respective prefixes
|
||||
|
||||
**Example:**
|
||||
**Example (dedicated negtrin line):**
|
||||
````
|
||||
+idev|my-device|pcloudIntensity(postrin-interest-percentage=50|negtrin-interest-thr=30)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
|
||||
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
|
||||
````
|
||||
|
||||
This example sets the interest threshold to 50% for postrins
|
||||
(percentage-based) and 30 for negtrins (absolute threshold value).
|
||||
|
||||
## Distraction Threshold Parameters
|
||||
|
||||
**Parameter forms:**
|
||||
- `postrin-distraction-<percentage|pc|threshold|thresh|thr>`
|
||||
- `negtrin-distraction-<percentage|pc|threshold|thresh|thr>`
|
||||
**Parameter forms (only inside `negtrin(...)` or `postrin(...)`):**
|
||||
|
||||
- Prefixed: `postrin-distraction-<percentage|pc|threshold|thresh|thr>`,
|
||||
`negtrin-distraction-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short: `distraction-<percentage|pc|threshold|thresh|thr>` (family is
|
||||
fixed by the `negtrin` / `postrin` API name)
|
||||
|
||||
**Description:**
|
||||
These parameters denote the value at which the stimbuff API library
|
||||
ought to construct a stencil and deliver it to SMO via
|
||||
negtrinInd/postrinInd with the importance argument set to "DISTRACTION".
|
||||
|
||||
**Specification:**
|
||||
- The parameter is specified as part of the `quale-iface-api-params`
|
||||
in the DAP specification
|
||||
- The unit suffix rules from the top of this document apply here too
|
||||
- Separate thresholds can be specified for postrin and negtrin using the
|
||||
respective prefixes
|
||||
|
||||
**Example:**
|
||||
````
|
||||
+idev|my-device|pcloudIntensity(negtrin-distraction-thr=60|postrin-distraction-thr=40)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
|
||||
````
|
||||
|
||||
This example sets the distraction threshold to 60 for negtrins and 40
|
||||
for postrins.
|
||||
|
||||
## Stupefying Threshold Parameters (Postrin)
|
||||
|
||||
**Parameter forms:**
|
||||
- `[postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>`
|
||||
- `[postrin-]stupefying-<percentage|pc|threshold|thresh|thr>`
|
||||
**Parameter forms (only inside `postrin(...)`):**
|
||||
|
||||
- Prefixed: `[postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>`,
|
||||
`[postrin-]stupefying-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short: `stupefaction-...`, `stupefying-...` with unit suffix
|
||||
|
||||
**Description:**
|
||||
These parameters denote the value at which the stimbuff API library
|
||||
ought to construct a stencil and deliver it to SMO via postrinInd with
|
||||
the importance argument set to "STUPEFYING".
|
||||
|
||||
**Specification:**
|
||||
- The parameter is specified as part of the `quale-iface-api-params`
|
||||
in the DAP specification
|
||||
- The unit suffix rules from the top of this document apply here too
|
||||
- These parameters apply only to postrin data (positive intrinsic
|
||||
stimuli)
|
||||
|
||||
**Example:**
|
||||
````
|
||||
+idev|my-device|pcloudIntensity(stupefying-thr=80)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
|
||||
````
|
||||
|
||||
This example sets the stupefying threshold to 80 for postrins.
|
||||
|
||||
## Intolerable Threshold Parameters (Negtrin)
|
||||
|
||||
**Parameter forms:**
|
||||
- `[negtrin-]intolerable-<percentage|pc|threshold|thresh|thr>`
|
||||
**Parameter forms (only inside `negtrin(...)`):**
|
||||
|
||||
- Prefixed: `[negtrin-]intolerable-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short: `intolerable-<percentage|pc|threshold|thresh|thr>`
|
||||
|
||||
**Description:**
|
||||
These parameters denote the value at which the stimbuff API library
|
||||
ought to construct a stencil and deliver it to SMO via negtrinInd with
|
||||
the importance argument set to "INTOLERABLE".
|
||||
|
||||
**Specification:**
|
||||
- The parameter is specified as part of the `quale-iface-api-params`
|
||||
in the DAP specification
|
||||
- The unit suffix rules from the top of this document apply here too
|
||||
- These parameters apply only to negtrin data (negative intrinsic
|
||||
stimuli)
|
||||
|
||||
**Example:**
|
||||
````
|
||||
+idev|my-device|pcloudIntensity(intolerable-thr=90)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
|
||||
````
|
||||
|
||||
This example sets the intolerable threshold to 90 for negtrins.
|
||||
|
||||
## Notes
|
||||
|
||||
The way that SMO handles these importance levels is not yet fully worked
|
||||
|
||||
+21
-10
@@ -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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user