95 lines
4.4 KiB
Markdown
95 lines
4.4 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 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
|
|
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
|
|
|
|
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
|
|
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:**
|
|
```
|
|
+idev|my-device|pcloudAmbience(n-stencils=4)|livoxGen1-pcloud()|livoxProto1()|3JEDK380010Z39
|
|
```
|
|
|
|
This example allows the stimbuff to allocate up to 4 stencils
|
|
simultaneously.
|
|
|
|
## 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.
|