hayodea
fc1fcae0b0
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.
110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# Stencils
|
|
|
|
## Overview
|
|
|
|
Stencils are an intrin info event data type used by SMO to efficiently
|
|
identify and process intrinsic stimuli (postrins and negtrins). Each stim
|
|
feature may have a stencil type if it's expected that devices exporting
|
|
stimbuffs for that feature can raise intrins. Stencils are derived classes
|
|
that provide sparse lists of body spots whose stim feature values have
|
|
passed the importance threshold for a particular intrin.
|
|
|
|
## Purpose
|
|
|
|
Stencils enable SMO's mind layer to quickly "just know" where an intrin is
|
|
occurring on the body. When an intrin is raised, SMO doesn't have to first
|
|
scan its percepts to figure out where the intrin is. The stencil
|
|
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 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
|
|
this point on the body and not just hazily generally for "all over the
|
|
body". We get to make the new item of knowledge more specific.
|
|
|
|
## Format and Allocation Model
|
|
|
|
Stencils' formats are specified and standardized by SMO, as well as the
|
|
number of stencils that a stimbuff may deliver at once. But the size of the
|
|
stencil allocated by a stimbuff cannot be known by the SMO layer. Only the
|
|
stimbuff itself knows how much memory is required to hold a stencil for
|
|
describing intrin events that it raises.
|
|
|
|
For example, only the livoxGen1 stimbuff knows the upper bound on how many
|
|
sparse descriptors are needed to describe an ambience event, for its current
|
|
configuration. Because for example, the stencil memory size is determined
|
|
by its nDgramsPerFrame parameter.
|
|
|
|
So SMO must specify the format and number of stencils (for rate limiting)
|
|
per stimbuff. But the stimbuff library will determine internally the memory
|
|
size required for each stencil. This means that SMO can't pre-allocate and
|
|
loan stencils to the stimbuffs. That would be ideal because it would give
|
|
total control to SMO over intrin events -- because SMO could reject any
|
|
intrin event whose stencil's internal memory doesn't match one that it
|
|
previously loaned out.
|
|
|
|
We could probably still enforce this by making the stimbuffs "register"
|
|
their stencils with SMO before raising intrins. This would have the effect
|
|
of ensuring that SMO can verify that only its permitted number of stencils
|
|
have been allocated. Moreover, we also regain the ability to reject stencils
|
|
whose internal memory doesn't match the memory of a registered stencil.
|
|
|
|
But it's fine because we don't expect the relationship between SMO and
|
|
stimbuff libraries to be inimical enough for security measures like that to
|
|
be non-negotiable.
|
|
|
|
## n-stencils QualeIfaceApi Parameter
|
|
|
|
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
|
|
raising new intrins.
|
|
|
|
**Specification:**
|
|
- The parameter is specified as part of the `quale-iface-api-params` in the
|
|
DAP specification
|
|
- The value is an integer representing the maximum number of stencils that
|
|
can be allocated simultaneously
|
|
- This parameter controls rate limiting for intrin events
|
|
- Stimbuffs must respect this limit and wait for stencil returns before
|
|
allocating new ones
|
|
|
|
**Example (generic dedicated intrin line—shape only; names depend on device):**
|
|
```
|
|
+idev|my-device|negtrin(from-stimbuff=someSensoryQuale|n-stencils=4)|someStimBuffApi()|livoxProto1()|SERIAL
|
|
```
|
|
|
|
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.
|
|
|
|
**Invalid (sensory qualeIfaceApi must not carry intrin-oriented params):**
|
|
```
|
|
+idev|my-device|pcloudAmbience(n-stencils=4)|livoxGen1-pcloud()|livoxProto1()|3JEDK380010Z39
|
|
```
|
|
|
|
## Notes
|
|
|
|
The stencil registration mechanism discussed above is not currently
|
|
implemented. The current design relies on the cooperative relationship
|
|
between SMO and stimbuff libraries, where stimbuffs are expected to respect
|
|
the n-stencils limit without requiring explicit registration or validation
|
|
by SMO.
|