1% Parameter Framework \
2High level requirements
3
4<!--
5Copyright (c) 2015, Intel Corporation
6All rights reserved.
7
8Redistribution and use in source and binary forms, with or without modification,
9are permitted provided that the following conditions are met:
10
111. Redistributions of source code must retain the above copyright notice, this
12list of conditions and the following disclaimer.
13
142. Redistributions in binary form must reproduce the above copyright notice,
15this list of conditions and the following disclaimer in the documentation and/or
16other materials provided with the distribution.
17
183. Neither the name of the copyright holder nor the names of its contributors
19may be used to endorse or promote products derived from this software without
20specific prior written permission.
21
22THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
23ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
24WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
26ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
27(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
29ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
31SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32-->
33
34<article class="markdown-body">
35
36<note>Some requirements are only motivated by the fact that the reference
37implementation implements them. Search for "reference implementation".</note>
38
39# Introduction
40
41The Parameter Framework is abreviated as PF in the rest of the document.
42
43## Philosophy
44
45The Parameter Framework aims to be a hardware control abstraction layer.
46Specificaly the PF contains 3 stacked abstraction layers:
47
48 1) hardware api abstraction
49 2) hardware parameter abstraction
50 3) high level hardware independent abstraction
51
52The fundamental constraint on the underlined hardware is to be representable
53by independent parameters. Ie: When changing one parameter it must not change
54an other.
55
56### Hardware api abstraction
57The goal of this layer is to abstract the apis of the underline hardwares.
58Each abstracted hardware usualy have different apis, this layer responsibility
59is to set and get parameters using the underlined native api.
60
61See the [syncer] chapter.
62<!--Fixme why are pandoc auto references not working ? -->
63
64### Hardware parameter abstraction
65The goal if this layer is to name and organize and describing
66the hardware parameter properties (domain of validity, size, human representation...).
67
68See the "Parameters" chapter.
69
70### High level hardware independent abstraction
71The goal of this layer is to abstract the hardware parameters behind abstract parameters
72(called criterion in the reference implementation).
73
74This is done by linking those abstract parameters and the hardware parameters with
75arbitrary rules.
76
77See the "Rule based dynamic abstraction".
78
79## Requirements
80
81### Reusability
82The PF **SHOULD** be reusable between components.
83<why>To be reused in different components.</why>
84
85### Instances independence
86PF instances **MUST NOT** mutate each others.
87<note>This may be implemented by not sharing any mutable data between PF instances.</note>
88<why>Different PF instances are expected to be completely independent thus accessing one should not impact any others.</why>
89
90# Parameters
91
92<note>TODO: add a paragraph/requirement about parameter independences.
93Ie parameter set order should not impact the final state.
94Need to find justification for this. Maybe it is only a convention?
95Maybe it is a consequences of the domains ?</note>
96
97
98## Definitions
99
100<dl>
101<dt>Parameter</dt>
102<dd>TODO</dd>
103<dt>Hardware</dt>
104<dd>System controlled by the PF. Not necessary material system. This term was
105chosen because:
106
107 - historically the PF reference implementation was used to abstract hardware
108 - the subsystem term would arguably fit best is already used.
109
110(FIXME: choose "subsystem" instead of "hardware" ?)
111</dd>
112</dl>
113
114## Requirements
115A PF **MUST** be able to handle parameters.
116<why>because the PF aims to abstract hardware and model it by parameters.</why>
117
118## Value
119
120A parameter **MUST** have a value.
121<why>because a parameter without value would not abstract any hardware.</why>
122
123### Mutability
124A PF **MUST** support mutable parameters.
125<why>To control the underlined hardware.</why>
126
127### Set ability
128This value **MUST** be settable for a mutable parameter.
129<why>By definition, a mutable parameter that can not be mutated it a immutable parameter.</why>
130
131### Get ability
132This value **SHOULD** be gettable for a mutable parameter.
133<why>To dump all parameter value, debug a hardware state,
134save parameters values, display the current hardware state,
135for coherency with the immutable parameter...</why>
136
137### Data type
138
139#### Definition
140
141<dl>
142<dt>Data type</dt>
143<dd>
144All parameters have a data type. A data type designates parameter invariants.
145
146A data type is the meaning of the data and the way values of that type can be
147stored.
148</dd>
149</dl>
150
151
152#### Philosophy
153
154A data type defines the value properties:
155
156 - memory layout
157 - value constrains
158
159A value type is mostly used to:
160
161 - pretty display parameter values (not just a as an array of bits)
162 - check for user error when setting it (out of bound, invalid...)
163 - offer a type safe API
164
165#### Requirements
166
167##### Supported types
168A PF **SHOULD** support the following types.
169If a type is chosen to be supported, it **MUST** respect all MUST clause,
170**SHOULD** respect all SHOULD clause, **MAY** respect all MAY clause of the type.
171<why>All type are not necessary to use the PF. For example any parameter could
172be represented as an array of char (string). But this would not permit to
173check parameter validity (invariants) nor a pretty display of the values.</why>
174
175##### Typed API
176Implementation **MAY** add another API to access a parameter value.
177<why>For example a C++ implementation may give access to a string as an
178std::string object.</why>
179
180##### Integers
181
182###### Signed and unsigned support
183PF **SHOULD** support signed and unsigned integer parameters
184<why>The reference implementation supports it.</why>
185
186###### Size immutability
187PF **MUST** support integer with invariant size.
188<why>It is common in C API to expect numbers to have a fixed maximum size.</why>
189
190###### ABI
191The API to access it **MUST** respect C integer ABI.
192<why>For easy access from C code.</why>
193
194###### Supported size
195Supported integer size **SHOULD** be at least 8, 16 and 32 bits.
196<why>The reference implementation supports it.</why>
197
198###### Min max support
199PF **MAY** support constraining the parameter minimum and maximum value.
200<why>To catch user out of valid range errors when changing the parameter
201value.</why>
202
203##### String
204###### Support
205PF **SHOULD** support array of characters.
206<why>Everything that a computer can store fits in an array of characters. It can
207be used as a fallback type if no other matches the parameter.</why>
208
209###### String max size
210The array maximum size **MAY** be invariant (immutable).
211<unknown>This is what the reference implementation does.</unknown>
212
213###### API
214The API to access the string value **SHOULD** support null terminated character
215array. As it is commonly done in C.
216<why>For easy access from C code.</why>
217
218##### Fix point parameter
219
220###### Support
221PF **SHOULD** support fix point parameters. I.e. integers divided by a fixed power
222of two.
223<unknown>The reference implementation supports it.</unknown>
224
225###### API
226The API to access the values **SHOULD** respect the Qm.n and UQm.n standards.
227<why>It is the main standard for fix point parameters.</why>
228
229###### Size
230PF **SHOULD** support at least `0 <= m + n <= 31` for a Signed Qm.n and
231`0 <= m + n <= 32` for an Unsigned Qm.n (or "UQm.n").
232<unknown>The reference implementation supports it.</unknown>
233<ko>The reference implementation only supports Signed Qn.m</ko>
234
235###### Min and max support
236PF **MAY** support constraining the parameter minimum and maximum value.
237<why>To catch user out of valid range errors when changing the parameter
238value.</why>
239<unknown>The reference implementation does not support it</unknown>
240
241##### Floating point
242###### Support
243PF **SHOULD** support floating point parameters .
244<unknown>The reference implementation supports it.</unknown>
245
246###### API
247The API to access the values **SHOULD** respect C platform float abi.
248<note>Usually the IEEE 754 standard.</note>
249
250###### Size
251PF **SHOULD** support at least 32 and 64 bit size floats.
252<why>The reference implementation supports it.</why>
253<unknown>The reference implementation only supports 32bits</unknown>
254
255###### Min and max support
256PF **MAY** support constraining the parameter minimum and maximum value.
257<why>To catch user out of valid range errors when changing the parameter
258value.</why>
259
260##### Bit field
261
262###### Support
263PF **SHOULD** support 1 or more bit sized integers.
264<unknown>The reference implementation supports it.</unknown>
265
266###### Single bit access API
267The API to access a bit parameter is implementation defined.
268<why>C has no way to point to a single (or more) bits. Thus there is no </why>
269
270###### Bit field access API
271Such bit parameters **SHOULD** be grouped in a bit field.
272A bit field is an ordered set of bit parameter.
273The API to access a bit filed **SHOULD** give access to a packed bit
274field following the C abi.
275<note>This bit field may contain only bit parameter.</note>
276<why>To offer a C compatible api to fit field.</why>
277
278
279### Parameter adaptation
280
281#### Definition
282<dl>
283<dt>Parameter adaptation<dt>
284<dd>
285A bijective pure function converting a parameter value between the syncer
286and other parameter reader/writer (including the inference engine).
287
288The adaptation function maps the syncer and client space. It:
289
290 - scales the user value to the hardware value (client => syncer)
291 - converts the hardware value to the user's value space. (syncer => client)
292
293<why>For coherency a client getting a previously set parameter should return the setted value,
294thus the transformation must be bijective.
295</why>
296</dd>
297</dl>
298
299#### Philosophy
300
301Parameters exposed by hardware sometimes need to be normalized.
302<note>For example a hardware integer parameter could have a range 64-128 but it might
303be necessary for upper layer to access in a range 0-100.</note>\
304
305This transformation can also permits to change the unit of a parameter.
306<note>For example the hardware could expose a parameter in cm but it might better
307to expose it in mm. </note>\
308
309Parameters types offer a way to abstract underlined implementation.
310<note>For example a Q2,2 (see [fix-point-parameter]) when setting 1
311will be translated to 0100. </note>\
312
313With parameter adaptation, types can be even further parameterised.
314<note>For example, Qn,m Fix point parameter could be emulated with a $*2^n$
315adaptation over an n + m integer. </note>\
316
317Parameter adaptation could be implemented by the syncer.
318Nevertheless syncers are supposed to contain only
319business logic and should not be impacted by upper layer needs.
320
321#### Requirements
322
323##### Support
324The following parameter adaptation **SHOULD** be supported
325
326 - Affine adaptation: `affAd(value) = slope * value + offset` where slope and
327   offset and user-defined constants
328   <unknown>The reference implementation supports it.</unknown>
329
330 - Logarithm adaptation: `logAd(base, value) = ln(value) / ln(base)` where
331   `ln` is the natural logarithm and base is a user-defined constant.
332   <unknown>The reference application supports it.</unknown>
333   <note>The reference implementation also supports passing a floor value to be
334   applied after conversion.</note>
335
336##### Composition
337A PF **MAY** offer Parameter adaptation composition. I.e. combine multiple parameter
338adaptation
339<note>E.g.: composing the affine and logarithm adaptation to
340`compAd(value) = slope * logAd(base, value) + offset`.</note>
341<why>To avoid combination explosion of parameter adaptations. The idea is to
342builtin basic function and let the user compose them to meet its need.</why>
343<ko>The reference application supports in a tricky way: the logarithm
344adaptation is always combined with the affine adaptation</ko>
345
346### Parameter tree
347A parameter **SHOULD** be structured in a tree. Each parameter being a distinct
348tree leaf.
349<why>Tree is a simple data structure that can be easily represented and is
350enough to map underlined layers.</why>
351
352#### Identifier
353Each node of the tree **SHOULD** have its own identifier with the same
354characteristics (type, independence...) than a parameter.
355<why>To represent the tree without treating the leaf nodes specifically.</why>
356
357
358# Syncer
359
360## Philosophy
361
362The PF philosophy is to map the hardware characteristics to parameters.
363In order to impact the hardware when parameters are modified, a hardware specific
364code must be used.
365
366Syncers are responsible for synchronizing the values of parameters to the underlined hardware.
367Ie, it is the glue between hardware and parameters. It contains the code specific
368to access an hardware.
369
370The aim of the PF is to keep this hardware specific code as light as possible.
371
372## Definition
373
374<dl>
375<dt>Syncer<dt>
376<dd>
377Entity that keeps synchronised PF parameters and their associated hardware.
378</dd>
379</dl>
380
381## Requirements
382
383### Mapping
384A syncer **MUST** be mapped to one or more parameters.
385<why>The hardware minimal access may be bigger than one parameter.</why>
386
387### Uniqueness
388One parameter **MUST NOT** be mapped to two or more syncer.
389Ie: a parameter MUST be mapped to zero or one syncer.
390<why>Which syncer should be responsible to retrieve the initial parameter value
391if they are multiple per parameter?</why>
392
393### Read hardware
394A syncer **MUST** support retrieving the mapped parameters value from the mapped
395hardware.
396<why>to retrieve a parameter value at the start of the PF.</why>
397
398#### Write hardware
399A syncer **MUST** support setting the mapped parameters value to the mapped
400hardware.
401<why>to synchronise hardware on parameter change.</why>
402
403#### API
404This API **MAY** be a packed parameter structure, following the C ABI without
405padding.
406<note>This is what the reference implementation does.</note>
407<unknown>TODO</unknown>
408
409## Parameter introspection
410The syncer API **SHOULD** allow introspection of the mapped parameters.
411<why>the parameter structure may be useful for the syncer to communicate with
412the hardware. For example a syncer might need each to know each associated
413parameter type to send it to the hardware.</why>
414
415## Plugins
416
417 - This formation is object oriented. Requirements should not require any programing paradigm.
418 - Is this section about syncer creation and builders too close to implementation ?
419
420### Definition
421The PF creates syncer using syncer builder.
422
423### Requirements
424The PF **MUST** be able to create syncers.
425<why>To bind on the corresponding parameters.</why>
426
427### Identifier
428
429#### Syncer library
430All syncers mapping to the same hardware **SHOULD** have their builders regrouped
431in a syncer library.
432<note>FIXME:
433
434 - Is this syncer library concept not a definition ? Ie a syncer builder set.
435 - The concept is needed by other requirement but it does not stand by itself.
436 - Why is there a requirement of "same hardware" ?
437      Is this not more a convention than a requirement ?
438
439</note>
440<why>To be able to link a group of parameters and a given hardware.
441For example all parameters that are mapped to sound card should be linked to a
442sound card syncer library. (Each parameter are then individually mapped to a specific syncer.)
443</why>
444
445#### Syncer ID
446A syncer builder **MUST** have a unique identifier in its containing syncer
447library.
448<why>To uniquely identify the syncer that should bind on parameters. Given that
449the syncer library has already been specified.</why>
450
451#### Library UID
452A syncer library **MUST** have a unique identifier in the host system.
453<why>To identify the library associated to parameters.</why>
454
455### Loading
456
457#### DLL
458Syncer library or/and builder **MAY** be loaded from dynamically linked libraries
459(called syncer plugins).
460<unknown>The reference implementation supports it.</unknown>
461
462#### Plugin entry point
463Such syncer plugins **SHOULD** have an unique entry point that -- when called --
464should register its payload (syncer library/builder) in the provided gatherer.
465<note>This permit to merge multiple syncer libraries in one shared
466library.</note>
467<unknown>The reference implementation supports it.</unknown>
468
469#### Plugin interdependancies
470Multiple syncer plugins, may depend on each other. The PF should appropriately
471handle the case and not fail.
472<unknown>The reference implementation supports it.</unknown>
473
474## Mapping
475### Definition
476
477<dl>
478<dt>Virtual Parameter</dt>
479<dd>
480A parameter not bound to a syncer.
481(Todo: remove if not used in the requirements.)
482</dd>
483</dl>
484
485### Requirements
486**TODO**:
487 - Plugins
488 - association builder <-> parameters
489
490## Sync
491
492### Sync on change
493Syncer **SHOULD** synchronise the mapped hardware on parameter change.
494<why>To always keep synchronise the underlined hardware and the PF
495parameters.</why>
496
497### Read hardware
498Syncer **SHOULD** retrieve parameter value from the hardware if no value has be
499set since the PF start.
500<note>This is usually implemented on PF start, initialize the parameter values
501with the mapped hardware current state.</note>
502<why>To allow introspection of the hardware.</why>
503
504### Explicit sync
505A mode with synchronisation on client request **SHOULD** be supported.
506<why>The user may want to group the synchronization of multiple parameters --
507for instance if a syncer contains more than 1 parameter -- in order to avoid
508undesired intermediary states.</why>
509
510### Out of sync
511Syncers **MAY** report an 'out-of-sync' condition indicating that the hardware
512parameter values are not (or no longer) reflecting the last values set by the
513Parameter Framework.
514<why>This can happen when the underlying hardware subsystem
515crashes/reboots/...</why>
516
517#### Recovery
518When a syncer reports an out-of-sync condition, the PF **MUST** try to resync
519the hardware values.
520
521# Rule based dynamic abstraction
522
523## Philosophy
524
525The PF offers parameters mapped on hardware. This is a good but weak
526abstraction as there is often a 1/1 relation between a parameter and the hardware
527it maps. Ie: parameter abstract how to access hardware and what hardware but
528are still hardware specific.
529
530A PF offers a mechanism to abstract the parameters to a higher level concept.
531
532The goal is to hide numerous parameters and their dynamic values behind simple
533and human friendly API.
534
535It works by grouping parameters with similar management and defining
536configurations for each "scenario". These "scenario" are then given a priority
537and a detection predicate. Configuration are applied when their associated
538"scenario" is detected.
539
540"Scenario" are detected through arbitrary criterion provided by the PF host
541(see below).
542
543## Definition
544
545<dl>
546<dt>Configuration</dt>
547<dd>
548Set of values for different parameters. A configuration **MUST NOT** contain 2
549values of the same parameter.
550
551For example, given a PF with 3 integer parameters A,B,C, a configuration can
552contain:
553
554 - 1 value: (A) or (B) or (C); or
555 - 2 values: (A,B) or (A,C) or (B,C); or
556 - 3 values: (A,B,C).
557</dd>
558
559<dt>Rogue Parameter</dt>
560<dd>
561A Parameter that is not contained by any configuration.
562<dd>
563</dl>
564
565## Configuration
566
567### Support
568A PF **MUST** offer configurations as described in the Definition chapter.
569<note>rule based parameter engine does not manipulate directly values, it
570applies configuration on the parameters.</note>
571<unknown>This is what the reference implementation does.</unknown>
572
573### Eligibility
574Each configuration **MUST** be associated with a predicate that condition its
575eligibility. A configuration with a predicate that evaluates to `true` is called
576an "eligible configuration"
577<why>This is what the reference implementation does.</why>
578
579### Default
580It **SHOULD** be possible to express a predicate to always evaluates to `true`.
581Ie: It *SHOULD* be possible to make a configuration always eligible.
582<why>In order to have parameters set to constant values or have a fallback
583configuration in a domain -- see below.</why>
584
585### Predicate implementation
586The predicate **SHOULD** be a "selection criterion rule". See next chapter for a
587definition.
588<why>The reference implementation uses a boolean expression based engine.</why>
589
590## Selection criterion
591
592### State uniqueness
593A selection criterion **MUST** have one, and only one, state at a given time.
594
595### State validity
596A selection criterion **MUST** have a always known immutable domain of definition.
597Ie All the possible state that a selection criterion can take **MUST** be known
598at all time.
599<why>To be able to validate:\
600 - rules on start\
601 - state changes
602</why>
603
604### State domain specification
605#### Naive
606The selection criterion possible states **MUST** be specifiable by directly a
607state set (`Input -> states == identity`)
608<note>called **exclusive criterion**</note>
609<note>An empty set is not allowed as the criterion could not have a state.</note>
610<why>Any criterion can be created from this API.</why>
611
612#### Combination
613The selection criterion possible states **SHOULD** be specifiable by a combination
614of values
615<note>combination in the [mathematical sense](https://en.wikipedia.org/wiki/Combination)
616`"ab" -> ["", "a", "b", "ab"]`</note>
617<note>called **inclusive criterion**</note>
618<note>An empty value set is allowed as its combination -- a set containing the
619empty set -- would not be empty. The empty set would be the only possible
620criteria state.</note>
621<why>The reference implementation supports it.</why>
622
623### Criteria number
624The PF **SHOULD NOT** limit the number of criteria.
625
626#### State number
627The PF **SHOULD NOT** limit the number of possible states of any given criterion
628<ko>The reference implementation only supports 32 values for an inclusive
629criterion and 2^32 values for an exclusive criterion</ko>
630
631### Definitions
632<dl>
633<dt>Selection criterion rule</dt>
634<dd>
635Function (in the mathematical sense) that **MUST** given selection criteria
636return a Boolean. Ie, a [predicate](https://en.wikipedia.org/wiki/Predicate_%28mathematical_logic%29).
637</dd>
638
639<dt>Rule</dt>
640<dd>
641A Boolean expression of Selection criterion rules.
642<note>implementation only allows AND and OR combination</note>
643<dd>
644</dl>
645
646### Criterion changes
647
648#### Multiple criterion change atomicity
649The API to change criterion values **MUST** allow atomicity regarding
650configuration application. I.e. it **MUST** be possible to change multiple
651criterion values without triggering a configuration application.
652<why>Two criterion might have an excluding state. If configuration application
653was triggered after each criterion change this transitory incompatible state
654would impact the system.
655For example 2 criterion `Tx` and `Rx` with 2 values `"on"` and `"off"` may have
656an incompatible state `Tx = Rx = "on"`. Ie this state is unspecified and the
657inference engine would gave unknown result.
658\
659When going: \
660 - from `Tx = "on" and Rx = "on"` (state 1) \
661 - to `Tx = "off" and Rx = "off"` (state 2) \
662<!-- FIXME: why are list closing the why block ?  -->
663a transitory state `Tx = "on" and Rx = "on"` may be reached. Nevertheless
664the inference engine must not be run on such. There must be a way to go
665from one state 1 to state 2 without triggering configuration application.
666</why>
667
668### Rules
669
670It **MUST** always be able to express a selection criterion rule from a given
671selection criterion state.
672I.e.: a criteria **MUST** always have a state that can be matched by a rule.
673<why>If no rules can be formulated from a criterion state,
674the hardware can not be abstracted in this state witch defeats the PF purpose.</why>
675
676Parameter values change **SHOULD** be selected by Rules.
677<why>A rule based inference engine has been chosen based on implementation and
678configuration ease</why>
679
680## Domains
681
682### Definition
683<dl>
684<dt>Domain</dt>
685<dd>
686Ordered set of configuration, all of which contain the values for the
687same parameters.
688</dd>
689</dl>
690
691### Philosophy
692
693When creating configurations for parameters, a pattern emerges.
694Some parameters are naturally grouping together. Ie changing on the same predicates.
695
696Without carefully crafting configuration predicates for mutual exclusivity,
697multiples configuration of the same parameter could be eligible on the same
698criterion state. This would lead to an ambiguity: which configuration should be applied.
699
700Multiple solution could be imagine like:
701 - ask to the client/user
702 - having configuration predicate mutual exclusive
703 - choose randomly
704 - group configuration applicable on the same in a priority ordered set
705
706The domains this specification recommend is this last solution.
707It has been chosen as the recommended solution (just like parameter tree)
708because it is a simple solution and is implemented in the reference implementation.
709
710The constraint of this solution is that a configuration can no longer be shared
711between domains. For example a global default configuration can not exist.
712It must be split up for each domain.
713
714This choice also force parameters to be independently accessible.
715
716### Requirement
717
718#### Configuration application ambiguity
719There **MUST** be a mechanism to avoid ambiguity on multiple configuration eligibility
720for the same parameter.
721<why>Applying multiple configurations would leave the parameters in an unknown state.</why>
722
723#### Domain support
724Each configuration **SHOULD** be in a "domain" (see Definition chapter).
725<why>Domains are mostly a way to define the priority of configuration application
726for some parameters.</why>
727<ko>It is not a MUST because this goal could also be achieve with (for
728example) global configurations and per parameter priority. It is not a MAY
729because the reference implementation uses domains.</ko>
730
731#### Configuration priority
732If multiple configuration are eligible, the first one **MUST** be applied.
733<why>If multiple configuration are eligible, there must be a way to discriminate
734them. The order was arbitrary chosen.
735See the domain philosophy section for more information about this choice.</why>
736
737#### Lazy application
738If no configuration is eligible, no configuration **MUST** be applied.
739<note>It means that if none of the configurations is eligible, none is applied.
740This also mean that no function can be defined between criteria and states.
741I.e.: parameter values MAY depend on previous selection criterion states.</note>
742<why>This is what the reference implementation does.</why>
743
744#### Sequence indifference
745Parameter set and get order MUST not change the final state.
746<why>Their is no way to order such access if the parameters are from different domains.</why>
747
748#### Sequence aware domain
749Domains **MAY** be sequence aware. Such domains update their associated
750parameters in a specific, predictable and configurable order.
751<ko>The reference application supports it.</ko>
752<why>Some parameters might require specific ordering on set.
753This is contradictory with the fact that parameters MUST be accessed independently.</why>
754
755# (de)serialization
756
757## Philosophy
758Serialization and deserialization are meant to support destruction recovery and
759configuration deployment.
760
761These are the same requirements than for a database, it needs to be able to save
762its state and restore for backup, deployment, reboot...
763
764## Definition
765PF data includes:
766
767- parameters tree
768- configurations:
769    - selection rule
770    - parameter/value couples
771- domain:
772    - list of associated configurations
773    - order of priority
774
775## Requirement
776
777### Deserializable
778The PF data **MUST** be deserializable.
779<why>Otherwise a PF instance could only be created empty and then be filled by
780the tuning interface. The reference implementation supports it.</why>
781
782### Deserializable from a file
783The PF data **SHOULD** be deserializable from a config file.
784<why>This is usually how program configuration are stored. The reference
785implementation supports it.</why>
786
787### Serializable
788The PF data **SHOULD** be serializable.
789<why>In order to save a PF instance state and restore it later. This achieve
790destruction recovery. The reference implementation supports it.</why>
791
792### (De)Serialization of individual data
793The PF data **SHOULD** be serializable/deserializable by parts.
794<why>For easier configuration management: for versioning; for selecting only wanted parts of a
795complete configuration.</why>
796
797### Serialization format
798**TODO**: XML ?
799
800### Implementation
801Syncer build and syncer library identifiers **SHOULD** be strings.
802<unknown>The reference application does so.</unknown>
803
804# Post mortem debug
805A PF **MAY** save all data needed to replay it's state evolution.
806<note>Eg: log criterion change, configuration application, parameter
807external change.
808
809This is implementing by logging events by the reference implementation.</note>
810<why>In order for the user to debug the user configuration after a bug occurred (post mortem or rare bug).
811This is kind of like the bash -x feature.
812</why>
813
814# Introspection
815## Philosophy
816In order to debug the user configuration, allow introspection of PF data at runtime.
817As data is meant to be displayed to user, lots are requirements are towards
818pretty printing PF data.
819
820## Requirements
821
822### Support
823User **SHOULD** be able to inspect PF data.
824<why>To offer run time debugging.
825This includes: \
826- listing \
827\ \ \ \ + domains\
828\ \ \ \ + configurations of a domains\
829\ \ \ \ + parameters\
830\ \ \ \ + a domain's associated parameters\
831- getting their properties. Including:\
832\ \ \ \ + parameters values, min, max, size...
833</why>
834
835### Pretty print
836PF **MAY** offer pretty print of data. Including:
837
838- printing parameter value in decimal
839    <why>For human readability</why>
840- pretty print parameter tree (such as the Unix tree command for files)
841    <why>In order to ease runtime debug.</why>
842
843### Rogue parameter
844Users **SHOULD** be able to modify rogue parameters through the native API at
845all time.
846<why>Otherwise, a rogue parameter is of no use.</why>
847<ko>In the reference implementation, under certain conditions, this is not
848possible (tuning mode)</ko>
849
850### Parameter Identifiers
851
852#### Support
853Every parameter **MUST** have an identifier that uniquely identifies it.
854<why>to identify a parameter outside the framework</why>
855
856#### String
857This identifier **SHOULD** be a string.
858<why>So that a human user can identify a parameter with ease.</why>
859
860#### Determinism
861Two PF instances with the same parameters **MUST** have the same identifier for
862those parameters.
863I.e. this identifier should be the same across all instances with the same
864configuration.
865<why>Persistence of parameter identifier across PF instances with the same
866configuration. To identify parameters independently of the host machine and PF
867instance</why>
868
869#### Tree path
870The identifier of each node of a parameter tree **SHOULD** be a combination of its
871parents. More specifically, if the identifier is a string it **SHOULD** be
872formated in a similar way as a file system path. E.g. `/root/child1/4/parameter1`.
873<why>Usual syntax to address trees.</why>
874
875
876# Tuning
877
878## Definition
879
880<dl>
881<dt>Tuning</dt>
882<dd>
883Tuning is the ability to modify the PF data structure at runtime.
884</dd>
885</dl>
886
887<note>Is this naming "Tuning" not too audio oriented.</note>
888
889## Philosophy
890
891As the PF might model a complex system with its dynamic parameter value engine
892(rule based in the default implementation), its behaviour might be hard to
893understand and should be easily modified not correct.
894
895To address this need, a fast modify-update-test cycle should be possible.
896
897## Requirements
898
899### Inference engine
900Users **SHOULD** be able to modify the PF inference engine behaviour (rules,
901configuration...) with minimal effort.
902<why>To enable a fast modify-update-test cycle during tuning.
903This usually mean avoiding for the user to: \
904 - recompile \
905 - restart the host process/service
906</why>
907
908<note>No requirement is made on the persistence of those changes, they may or
909may not disappear on PF restart. This could be implemented in several way, for
910example:
911
912- exposed in the PF API
913- changing a config file and sending a signal to the PF
914- providing a IPC
915- directly modifying the memory
916
917</note>
918
919### Native api
920Tuning **SHOULD** be possible from the PF native API.
921<why>In order to let the host system implement its own tuning mechanism.</why>
922
923### Parameter overwriting
924Users **SHOULD** be able to modify the parameter values at any time.
925This change **SHOULD NOT** be overwritten without a user action.
926<note>User overwritten user action could be a log out, leaving some tuning mode,
927forcing an inference engine update...</note>
928<why>Even if a parameter is managed by the inference engine, it often is useful
929(test, debugging) to overwrite its value temporally.</why>
930
931### Disabling
932A PF tuning capability **MAY** be disabled in a context where no tuning is needed.
933<why>The reference implementation does so (phone end users can not change the
934tuning).</why>
935
936# Command line interface
937<ko>Is this not an implementation detail? Does a client really needs it?</ko>
938
939## Support
940The PF **MAY** offer a command line interface that binds to its IPC.
941<why>To have a reference way to interact with a PF without implementing its IPC
942protocol.</why>
943<note>This requirement is fulfilled by remote-processor and remote-command on the reference implementation.</note>
944
945## Introspection & tunning
946This command line interface **SHOULD** support all tuning and introspection ability.
947<why>In order to be used in scripting and live tuning/debugging on an embedded
948system.</why>
949
950## Auto completion
951This command line interface **MAY** offer argument auto completion.
952<why>Is more user friendly.</why>
953
954# Bindings
955
956## C
957The PF **SHOULD** expose its API in C.
958<why>The PF aims to be a hardware abstraction thus middle ware which is often
959written in C or a language compatible with C. Virtually all programing language
960support C Foreign Procedure Call, having a C API ease integration whichever the
961host language is.</why>
962
963## Programing language
964The PF **MAY** expose its API to multiple programing language.
965<unknown>The reference implementation has python bindings.</unknown>
966
967# Performance
968
969The reference Parameter Framework implementation is mainly intended for use
970in consumer electronics such as smartphones and tablets. Such platforms are
971often referred to as "embedded" platforms but their capacity today is so huge in
972terms of both computing and memory that they can be considered as small personal
973computers.
974
975Moreover, since one of the Parameter Framework's primary feature is to implement
976storage of
977
978 - hardware description
979 - settings
980
981its memory footprint largely depends on how many such items are stored.
982
983For those reasons, there are no performance requirements imposed on the
984architecture. Performance considerations are left to the implementation of the
985Parameter Framework and/or the client and/or the build chain.
986
987# Next
988
989<ko>
990The following requirements are not implemented in the reference implementation
991and are to be considered draft.
992</ko>
993
994## Multi OS
995PF **MAY** support at least:
996
997 - Linux (and Android)
998 - Windows
999 - Mac OSX
1000
1001<why>As the reference PF implementation leaves its original Android environment,
1002needs emerge to use it on other platform.</why>
1003
1004## Tuning
1005### Get and set multiple parameter values in one request
1006#### Atomicity
1007When setting multiple parameters from one client request,
1008and when one or more parameter value is invalid (eg. out of range),
1009no parameter **SHOULD** be set.
1010Eg: an invalid request to change parameters **SHOULD** not impact the parameters
1011values nor the subsystems.
1012<note>This may be implemented by first checking parameters validity
1013before setting them, or implementing a rollback mechanism, or any other way.</note>
1014<why>To provide parameter mutation atomicity to the client.
1015This is especially important if the client wants to implement parameter consistency.
1016Eg: let two parameters have excluding values,
1017if a transaction fail after the first parameter is set but not the second,
1018the excluding constraint may be violated.
1019It also usefull for the client to know the state of the parameters
1020after a parameter set without having to query the PF.</why>
1021
1022#### Access parameters as Xml
1023Getting and setting the content of one or more ([one, all]) parameters **SHOULD**
1024be possible in xml.
1025<why>For performance reason. Tools often need to update multiple parameter
1026and having one call per parameter is too slow. (benchmark ?).
1027This feature permit the client to save and restore from an external database parameter
1028values a la `alsa.state`.</why>
1029
1030#### Access parameters as binary
1031The PF host API **SHOULD** expose parameter values with the same API syncer use.
1032<why>The current reference implementation abstracts the memory layout of
1033parameters. This memory layout is specified in the parameter structure thus
1034is known by the client.</why>
1035
1036## Stage and commit Sync
1037Explicit sync **SHOULD** only sync parameters which values were updated since last sync.
1038<why>For performance reason or when an hardware does not support certain
1039transition state, manual parameter synchronisation is requested.
1040
1041Sync request was implemented in the reference implementation by syncing all
1042parameters, including the one that were not changed since last sync.
1043
1044For performance reason only the changed parameters should be send to hardware.</why>
1045
1046
1047## Structured api API
1048The PF host API **SHOULD** be structured.
1049I.e.: the PF, when requested for a list of domains, should return a list of
1050structured object, each containing configuration objects, containing their
1051values...
1052<why>The reference implementation has a string oriented API. E.g/: The list of
1053domains is returned as a concatenation of domains name in one big string. This
1054leads to hard to use API from C and C++ code. Especially for testing</why>
1055
1056### Implementation language
1057The main implementation will transition to C++11 for
1058 - cross platform support of multi-threading
1059 - remove dependency to pthread
1060 - reduce the gap with the "next" branch
1061It will be compatible with android thank to clang's libc++"
1062
1063<note>Put this in a design document.</note>
1064
1065## Long term
1066The following requirements are not planned to be implemented any time soon as
1067their is not need identified but are rather a long term guidance.
1068
1069### Custom parameter types
1070The client **MAY** inject custom parameters types.
1071<why>As the client creates parameters it should also be able to specify the
1072parameter contains ie its types. Without this possibility the client has to
1073choose a built-in that may not match what he wants.
1074
1075For example representing a prime number with an integer would not allow to enforce primness.
1076
1077For example a complex number could be represented with two float but `a+bi` format
1078could not be used.
1079
1080For example stocking a parameter with a dynamic type, say either a string or a number
1081could be done with a boolean a string and a number but this could not be pretty
1082print and not memory efficient.
1083</why>
1084
1085### Structure tunning
1086Users **MAY** be able to modify the parameters (types, identifiers, tree...) with
1087minimal effort (in the same way they can modify the inference engine).
1088<ko>The reference implementation does not support it.</ko>
1089<why>To enable a fast modify-update-test cycle on PF configuration.</why>
1090
1091### Immutable parameters
1092A PF **MAY** support immutable parameters, i.e. parameters which value is determined
1093on start then read only.
1094<why>To permit hardware read only value reflection.</why>
1095<ko>This is not implemented in the PF reference implementation.</ko>
1096
1097This value **MUST** be gettable for an immutable parameter.
1098<why>A parameter that can not be accessed (read or write) is of no use.</why>
1099
1100### Endianess adaptation
1101A parameter or a block of parameters might be presented by the Parameter
1102Framework but only used as a passthrough to the underlying subsystem (think
1103"`(void *)` interfaces"). It is then possible that the endianess of the
1104subsystem differs from the one the Parameter Framework is running on, an
1105endianness adaptation would allow supporting those cases.
1106
1107This can be seen as related to the "Parameter Adaptation" requirement or even
1108as a special case.
1109
1110</article>
1111