106 lines
5.1 KiB
Markdown
106 lines
5.1 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 (and even if not, because stencils
|
|
are used for projection). 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, because the sense
|
|
organ itself conveyed that information via the stencil.
|
|
|
|
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 raised from a `negtrin(...)` segment attached to a
|
|
nontrin DAP line (e.g. `pcloudLightAmbience` / `pcloudDarkAmbience`),
|
|
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 Intrin-Segment Parameter
|
|
|
|
Where a stim buff supports it, a parameter called `n-stencils` tells the
|
|
stimbuff how many stencils it can allocate and deliver to SMO
|
|
simultaneously for **intrinsic** delivery. `n-stencils` belongs on the
|
|
`postrin(...)` / `negtrin(...)` segment it rate-limits — **not** on the
|
|
nontrin qualeIfaceApi params. Postrin and negtrin get independent
|
|
budgets.
|
|
|
|
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 inside a `postrin(...)` or `negtrin(...)`
|
|
segment on a DAP line
|
|
- The value is an integer representing the maximum number of stencils
|
|
that can be allocated simultaneously for that segment's intrin path
|
|
- This parameter controls rate limiting for intrin events
|
|
- Stimbuffs must respect this limit and wait for stencil returns before
|
|
allocating new ones
|
|
|
|
**Example (generic shape — names depend on device):**
|
|
```
|
|
+idev|my-device
|
|
|negtrin(interest-pc=85|n-stencils=4)|someSensoryQuale()|someStimBuffApi()
|
|
|livoxProto1()|SERIAL
|
|
```
|
|
|
|
The Livox Gen1 **`pcloudLightAmbience`** / **`pcloudDarkAmbience`** sensory
|
|
lines do **not** use `n-stencils`; each emits one `uint32` passband count
|
|
per stimframe. If Livox adds `n-stencils` for its intrinsic pipelines, it
|
|
would appear inside the `postrin(...)` / `negtrin(...)` segments attached to
|
|
the ambience line, not on the ambience qualeIfaceApi itself.
|
|
|
|
**Invalid (sensory qualeIfaceApi must not carry intrin-oriented params):**
|
|
```
|
|
+idev|my-device|pcloudLightAmbience(n-stencils=4)|livoxGen1-pcloud()|livoxProto1()|3JEDK380010Z39
|
|
```
|