salmanoff/docs/design/stencils.md

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