% Parameter Framework
High level requirements
Some requirements are only motivated by the fact that the reference implementation implements them. Search for “reference implementation”.
The Parameter Framework is abreviated as PF in the rest of the document.
The Parameter Framework aims to be a hardware control abstraction layer. Specificaly the PF contains 3 stacked abstraction layers:
The fundamental constraint on the underlined hardware is to be representable by independent parameters. Ie: When changing one parameter it must not change an other.
The goal of this layer is to abstract the apis of the underline hardwares. Each abstracted hardware usualy have different apis, this layer responsibility is to set and get parameters using the underlined native api.
See the [syncer] chapter.
The goal if this layer is to name and organize and describing the hardware parameter properties (domain of validity, size, human representation...).
See the “Parameters” chapter.
The goal of this layer is to abstract the hardware parameters behind abstract parameters (called criterion in the reference implementation).
This is done by linking those abstract parameters and the hardware parameters with arbitrary rules.
See the “Rule based dynamic abstraction”.
The PF SHOULD be reusable between components. To be reused in different components.
PF instances MUST NOT mutate each others. This may be implemented by not sharing any mutable data between PF instances. Different PF instances are expected to be completely independent thus accessing one should not impact any others.
TODO: add a paragraph/requirement about parameter independences. Ie parameter set order should not impact the final state. Need to find justification for this. Maybe it is only a convention? Maybe it is a consequences of the domains ?
(FIXME: choose “subsystem” instead of “hardware” ?)
A PF MUST be able to handle parameters. because the PF aims to abstract hardware and model it by parameters.
A parameter MUST have a value. because a parameter without value would not abstract any hardware.
A PF MUST support mutable parameters. To control the underlined hardware.
This value MUST be settable for a mutable parameter. By definition, a mutable parameter that can not be mutated it a immutable parameter.
This value SHOULD be gettable for a mutable parameter. To dump all parameter value, debug a hardware state, save parameters values, display the current hardware state, for coherency with the immutable parameter...
A data type is the meaning of the data and the way values of that type can be stored.
A data type defines the value properties:
A value type is mostly used to:
A PF SHOULD support the following types. If a type is chosen to be supported, it MUST respect all MUST clause, SHOULD respect all SHOULD clause, MAY respect all MAY clause of the type. All type are not necessary to use the PF. For example any parameter could be represented as an array of char (string). But this would not permit to check parameter validity (invariants) nor a pretty display of the values.
Implementation MAY add another API to access a parameter value. For example a C++ implementation may give access to a string as an std::string object.
PF SHOULD support signed and unsigned integer parameters The reference implementation supports it.
PF MUST support integer with invariant size. It is common in C API to expect numbers to have a fixed maximum size.
The API to access it MUST respect C integer ABI. For easy access from C code.
Supported integer size SHOULD be at least 8, 16 and 32 bits. The reference implementation supports it.
PF MAY support constraining the parameter minimum and maximum value. To catch user out of valid range errors when changing the parameter value.
PF SHOULD support array of characters. Everything that a computer can store fits in an array of characters. It can be used as a fallback type if no other matches the parameter.
The array maximum size MAY be invariant (immutable). This is what the reference implementation does.
The API to access the string value SHOULD support null terminated character array. As it is commonly done in C. For easy access from C code.
PF SHOULD support fix point parameters. I.e. integers divided by a fixed power of two. The reference implementation supports it.
The API to access the values SHOULD respect the Qm.n and UQm.n standards. It is the main standard for fix point parameters.
PF SHOULD support at least 0 <= m + n <= 31 for a Signed Qm.n and 0 <= m + n <= 32 for an Unsigned Qm.n (or “UQm.n”). The reference implementation supports it. The reference implementation only supports Signed Qn.m
PF MAY support constraining the parameter minimum and maximum value. To catch user out of valid range errors when changing the parameter value. The reference implementation does not support it
PF SHOULD support floating point parameters . The reference implementation supports it.
The API to access the values SHOULD respect C platform float abi. Usually the IEEE 754 standard.
PF SHOULD support at least 32 and 64 bit size floats. The reference implementation supports it. The reference implementation only supports 32bits
PF MAY support constraining the parameter minimum and maximum value. To catch user out of valid range errors when changing the parameter value.
PF SHOULD support 1 or more bit sized integers. The reference implementation supports it.
The API to access a bit parameter is implementation defined. C has no way to point to a single (or more) bits. Thus there is no
Such bit parameters SHOULD be grouped in a bit field. A bit field is an ordered set of bit parameter. The API to access a bit filed SHOULD give access to a packed bit field following the C abi. This bit field may contain only bit parameter. To offer a C compatible api to fit field.
The adaptation function maps the syncer and client space. It:
For coherency a client getting a previously set parameter should return the setted value, thus the transformation must be bijective.
Parameters exposed by hardware sometimes need to be normalized. For example a hardware integer parameter could have a range 64-128 but it might be necessary for upper layer to access in a range 0-100.\
This transformation can also permits to change the unit of a parameter. For example the hardware could expose a parameter in cm but it might better to expose it in mm. \
Parameters types offer a way to abstract underlined implementation. For example a Q2,2 (see [fix-point-parameter]) when setting 1 will be translated to 0100. \
With parameter adaptation, types can be even further parameterised. For example, Qn,m Fix point parameter could be emulated with a $*2^n$ adaptation over an n + m integer. \
Parameter adaptation could be implemented by the syncer. Nevertheless syncers are supposed to contain only business logic and should not be impacted by upper layer needs.
The following parameter adaptation SHOULD be supported
Affine adaptation: affAd(value) = slope * value + offset where slope and offset and user-defined constants The reference implementation supports it.
Logarithm adaptation: logAd(base, value) = ln(value) / ln(base) where ln is the natural logarithm and base is a user-defined constant. The reference application supports it. The reference implementation also supports passing a floor value to be applied after conversion.
A PF MAY offer Parameter adaptation composition. I.e. combine multiple parameter adaptation E.g.: composing the affine and logarithm adaptation to compAd(value) = slope * logAd(base, value) + offset. To avoid combination explosion of parameter adaptations. The idea is to builtin basic function and let the user compose them to meet its need. The reference application supports in a tricky way: the logarithm adaptation is always combined with the affine adaptation
A parameter SHOULD be structured in a tree. Each parameter being a distinct tree leaf. Tree is a simple data structure that can be easily represented and is enough to map underlined layers.
Each node of the tree SHOULD have its own identifier with the same characteristics (type, independence...) than a parameter. To represent the tree without treating the leaf nodes specifically.
The PF philosophy is to map the hardware characteristics to parameters. In order to impact the hardware when parameters are modified, a hardware specific code must be used.
Syncers are responsible for synchronizing the values of parameters to the underlined hardware. Ie, it is the glue between hardware and parameters. It contains the code specific to access an hardware.
The aim of the PF is to keep this hardware specific code as light as possible.
A syncer MUST be mapped to one or more parameters. The hardware minimal access may be bigger than one parameter.
One parameter MUST NOT be mapped to two or more syncer. Ie: a parameter MUST be mapped to zero or one syncer. Which syncer should be responsible to retrieve the initial parameter value if they are multiple per parameter?
A syncer MUST support retrieving the mapped parameters value from the mapped hardware. to retrieve a parameter value at the start of the PF.
A syncer MUST support setting the mapped parameters value to the mapped hardware. to synchronise hardware on parameter change.
This API MAY be a packed parameter structure, following the C ABI without padding. This is what the reference implementation does. TODO
The syncer API SHOULD allow introspection of the mapped parameters. the parameter structure may be useful for the syncer to communicate with the hardware. For example a syncer might need each to know each associated parameter type to send it to the hardware.
The PF creates syncer using syncer builder.
The PF MUST be able to create syncers. To bind on the corresponding parameters.
All syncers mapping to the same hardware SHOULD have their builders regrouped in a syncer library. FIXME:
A syncer builder MUST have a unique identifier in its containing syncer library. To uniquely identify the syncer that should bind on parameters. Given that the syncer library has already been specified.
A syncer library MUST have a unique identifier in the host system. To identify the library associated to parameters.
Syncer library or/and builder MAY be loaded from dynamically linked libraries (called syncer plugins). The reference implementation supports it.
Such syncer plugins SHOULD have an unique entry point that -- when called -- should register its payload (syncer library/builder) in the provided gatherer. This permit to merge multiple syncer libraries in one shared library. The reference implementation supports it.
Multiple syncer plugins, may depend on each other. The PF should appropriately handle the case and not fail. The reference implementation supports it.
TODO:
Syncer SHOULD synchronise the mapped hardware on parameter change. To always keep synchronise the underlined hardware and the PF parameters.
Syncer SHOULD retrieve parameter value from the hardware if no value has be set since the PF start. This is usually implemented on PF start, initialize the parameter values with the mapped hardware current state. To allow introspection of the hardware.
A mode with synchronisation on client request SHOULD be supported. The user may want to group the synchronization of multiple parameters -- for instance if a syncer contains more than 1 parameter -- in order to avoid undesired intermediary states.
Syncers MAY report an ‘out-of-sync’ condition indicating that the hardware parameter values are not (or no longer) reflecting the last values set by the Parameter Framework. This can happen when the underlying hardware subsystem crashes/reboots/...
When a syncer reports an out-of-sync condition, the PF MUST try to resync the hardware values.
The PF offers parameters mapped on hardware. This is a good but weak abstraction as there is often a 1/1 relation between a parameter and the hardware it maps. Ie: parameter abstract how to access hardware and what hardware but are still hardware specific.
A PF offers a mechanism to abstract the parameters to a higher level concept.
The goal is to hide numerous parameters and their dynamic values behind simple and human friendly API.
It works by grouping parameters with similar management and defining configurations for each “scenario”. These “scenario” are then given a priority and a detection predicate. Configuration are applied when their associated “scenario” is detected.
“Scenario” are detected through arbitrary criterion provided by the PF host (see below).
For example, given a PF with 3 integer parameters A,B,C, a configuration can contain:
A PF MUST offer configurations as described in the Definition chapter. rule based parameter engine does not manipulate directly values, it applies configuration on the parameters. This is what the reference implementation does.
Each configuration MUST be associated with a predicate that condition its eligibility. A configuration with a predicate that evaluates to true is called an “eligible configuration” This is what the reference implementation does.
It SHOULD be possible to express a predicate to always evaluates to true. Ie: It SHOULD be possible to make a configuration always eligible. In order to have parameters set to constant values or have a fallback configuration in a domain -- see below.
The predicate SHOULD be a “selection criterion rule”. See next chapter for a definition. The reference implementation uses a boolean expression based engine.
A selection criterion MUST have one, and only one, state at a given time.
A selection criterion MUST have a always known immutable domain of definition. Ie All the possible state that a selection criterion can take MUST be known at all time. To be able to validate:\
The selection criterion possible states MUST be specifiable by directly a state set (Input -> states == identity) called exclusive criterion An empty set is not allowed as the criterion could not have a state. Any criterion can be created from this API.
The selection criterion possible states SHOULD be specifiable by a combination of values combination in the mathematical sense "ab" -> ["", "a", "b", "ab"] called inclusive criterion An empty value set is allowed as its combination -- a set containing the empty set -- would not be empty. The empty set would be the only possible criteria state. The reference implementation supports it.
The PF SHOULD NOT limit the number of criteria.
The PF SHOULD NOT limit the number of possible states of any given criterion The reference implementation only supports 32 values for an inclusive criterion and 2^32 values for an exclusive criterion
The API to change criterion values MUST allow atomicity regarding configuration application. I.e. it MUST be possible to change multiple criterion values without triggering a configuration application. Two criterion might have an excluding state. If configuration application was triggered after each criterion change this transitory incompatible state would impact the system. For example 2 criterion Tx and Rx with 2 values "on" and "off" may have an incompatible state Tx = Rx = "on". Ie this state is unspecified and the inference engine would gave unknown result.
When going: \
Tx = "on" and Rx = "on" (state 1) \Tx = "off" and Rx = "off" (state 2) \a transitory state Tx = "on" and Rx = "on" may be reached. Nevertheless the inference engine must not be run on such. There must be a way to go from one state 1 to state 2 without triggering configuration application.
It MUST always be able to express a selection criterion rule from a given selection criterion state. I.e.: a criteria MUST always have a state that can be matched by a rule. If no rules can be formulated from a criterion state, the hardware can not be abstracted in this state witch defeats the PF purpose.
Parameter values change SHOULD be selected by Rules. A rule based inference engine has been chosen based on implementation and configuration ease
When creating configurations for parameters, a pattern emerges. Some parameters are naturally grouping together. Ie changing on the same predicates.
Without carefully crafting configuration predicates for mutual exclusivity, multiples configuration of the same parameter could be eligible on the same criterion state. This would lead to an ambiguity: which configuration should be applied.
Multiple solution could be imagine like:
The domains this specification recommend is this last solution. It has been chosen as the recommended solution (just like parameter tree) because it is a simple solution and is implemented in the reference implementation.
The constraint of this solution is that a configuration can no longer be shared between domains. For example a global default configuration can not exist. It must be split up for each domain.
This choice also force parameters to be independently accessible.
There MUST be a mechanism to avoid ambiguity on multiple configuration eligibility for the same parameter. Applying multiple configurations would leave the parameters in an unknown state.
Each configuration SHOULD be in a “domain” (see Definition chapter). Domains are mostly a way to define the priority of configuration application for some parameters. It is not a MUST because this goal could also be achieve with (for example) global configurations and per parameter priority. It is not a MAY because the reference implementation uses domains.
If multiple configuration are eligible, the first one MUST be applied. If multiple configuration are eligible, there must be a way to discriminate them. The order was arbitrary chosen. See the domain philosophy section for more information about this choice.
If no configuration is eligible, no configuration MUST be applied. It means that if none of the configurations is eligible, none is applied. This also mean that no function can be defined between criteria and states. I.e.: parameter values MAY depend on previous selection criterion states. This is what the reference implementation does.
Parameter set and get order MUST not change the final state. Their is no way to order such access if the parameters are from different domains.
Domains MAY be sequence aware. Such domains update their associated parameters in a specific, predictable and configurable order. The reference application supports it. Some parameters might require specific ordering on set. This is contradictory with the fact that parameters MUST be accessed independently.
Serialization and deserialization are meant to support destruction recovery and configuration deployment.
These are the same requirements than for a database, it needs to be able to save its state and restore for backup, deployment, reboot...
PF data includes:
The PF data MUST be deserializable. Otherwise a PF instance could only be created empty and then be filled by the tuning interface. The reference implementation supports it.
The PF data SHOULD be deserializable from a config file. This is usually how program configuration are stored. The reference implementation supports it.
The PF data SHOULD be serializable. In order to save a PF instance state and restore it later. This achieve destruction recovery. The reference implementation supports it.
The PF data SHOULD be serializable/deserializable by parts. For easier configuration management: for versioning; for selecting only wanted parts of a complete configuration.
TODO: XML ?
Syncer build and syncer library identifiers SHOULD be strings. The reference application does so.
A PF MAY save all data needed to replay it's state evolution. Eg: log criterion change, configuration application, parameter external change.
This is implementing by logging events by the reference implementation. In order for the user to debug the user configuration after a bug occurred (post mortem or rare bug). This is kind of like the bash -x feature.
In order to debug the user configuration, allow introspection of PF data at runtime. As data is meant to be displayed to user, lots are requirements are towards pretty printing PF data.
User SHOULD be able to inspect PF data. To offer run time debugging. This includes: \
PF MAY offer pretty print of data. Including:
Users SHOULD be able to modify rogue parameters through the native API at all time. Otherwise, a rogue parameter is of no use. In the reference implementation, under certain conditions, this is not possible (tuning mode)
Every parameter MUST have an identifier that uniquely identifies it. to identify a parameter outside the framework
This identifier SHOULD be a string. So that a human user can identify a parameter with ease.
Two PF instances with the same parameters MUST have the same identifier for those parameters. I.e. this identifier should be the same across all instances with the same configuration. Persistence of parameter identifier across PF instances with the same configuration. To identify parameters independently of the host machine and PF instance
The identifier of each node of a parameter tree SHOULD be a combination of its parents. More specifically, if the identifier is a string it SHOULD be formated in a similar way as a file system path. E.g. /root/child1/4/parameter1. Usual syntax to address trees.
Is this naming “Tuning” not too audio oriented.
As the PF might model a complex system with its dynamic parameter value engine (rule based in the default implementation), its behaviour might be hard to understand and should be easily modified not correct.
To address this need, a fast modify-update-test cycle should be possible.
Users SHOULD be able to modify the PF inference engine behaviour (rules, configuration...) with minimal effort. To enable a fast modify-update-test cycle during tuning. This usually mean avoiding for the user to: \
No requirement is made on the persistence of those changes, they may or may not disappear on PF restart. This could be implemented in several way, for example:
Tuning SHOULD be possible from the PF native API. In order to let the host system implement its own tuning mechanism.
Users SHOULD be able to modify the parameter values at any time. This change SHOULD NOT be overwritten without a user action. User overwritten user action could be a log out, leaving some tuning mode, forcing an inference engine update... Even if a parameter is managed by the inference engine, it often is useful (test, debugging) to overwrite its value temporally.
A PF tuning capability MAY be disabled in a context where no tuning is needed. The reference implementation does so (phone end users can not change the tuning).
Is this not an implementation detail? Does a client really needs it?
The PF MAY offer a command line interface that binds to its IPC. To have a reference way to interact with a PF without implementing its IPC protocol. This requirement is fulfilled by remote-processor and remote-command on the reference implementation.
This command line interface SHOULD support all tuning and introspection ability. In order to be used in scripting and live tuning/debugging on an embedded system.
This command line interface MAY offer argument auto completion. Is more user friendly.
The PF SHOULD expose its API in C. The PF aims to be a hardware abstraction thus middle ware which is often written in C or a language compatible with C. Virtually all programing language support C Foreign Procedure Call, having a C API ease integration whichever the host language is.
The PF MAY expose its API to multiple programing language. The reference implementation has python bindings.
The reference Parameter Framework implementation is mainly intended for use in consumer electronics such as smartphones and tablets. Such platforms are often referred to as “embedded” platforms but their capacity today is so huge in terms of both computing and memory that they can be considered as small personal computers.
Moreover, since one of the Parameter Framework's primary feature is to implement storage of
its memory footprint largely depends on how many such items are stored.
For those reasons, there are no performance requirements imposed on the architecture. Performance considerations are left to the implementation of the Parameter Framework and/or the client and/or the build chain.
PF MAY support at least:
As the reference PF implementation leaves its original Android environment, needs emerge to use it on other platform.
When setting multiple parameters from one client request, and when one or more parameter value is invalid (eg. out of range), no parameter SHOULD be set. Eg: an invalid request to change parameters SHOULD not impact the parameters values nor the subsystems. This may be implemented by first checking parameters validity before setting them, or implementing a rollback mechanism, or any other way. To provide parameter mutation atomicity to the client. This is especially important if the client wants to implement parameter consistency. Eg: let two parameters have excluding values, if a transaction fail after the first parameter is set but not the second, the excluding constraint may be violated. It also usefull for the client to know the state of the parameters after a parameter set without having to query the PF.
Getting and setting the content of one or more ([one, all]) parameters SHOULD be possible in xml. For performance reason. Tools often need to update multiple parameter and having one call per parameter is too slow. (benchmark ?). This feature permit the client to save and restore from an external database parameter values a la alsa.state.
The PF host API SHOULD expose parameter values with the same API syncer use. The current reference implementation abstracts the memory layout of parameters. This memory layout is specified in the parameter structure thus is known by the client.
Explicit sync SHOULD only sync parameters which values were updated since last sync. For performance reason or when an hardware does not support certain transition state, manual parameter synchronisation is requested.
Sync request was implemented in the reference implementation by syncing all parameters, including the one that were not changed since last sync.
For performance reason only the changed parameters should be send to hardware.
The PF host API SHOULD be structured. I.e.: the PF, when requested for a list of domains, should return a list of structured object, each containing configuration objects, containing their values... The reference implementation has a string oriented API. E.g/: The list of domains is returned as a concatenation of domains name in one big string. This leads to hard to use API from C and C++ code. Especially for testing
The main implementation will transition to C++11 for
Put this in a design document.
The following requirements are not planned to be implemented any time soon as their is not need identified but are rather a long term guidance.
The client MAY inject custom parameters types. As the client creates parameters it should also be able to specify the parameter contains ie its types. Without this possibility the client has to choose a built-in that may not match what he wants.
For example representing a prime number with an integer would not allow to enforce primness.
For example a complex number could be represented with two float but a+bi format could not be used.
For example stocking a parameter with a dynamic type, say either a string or a number could be done with a boolean a string and a number but this could not be pretty print and not memory efficient.
Users MAY be able to modify the parameters (types, identifiers, tree...) with minimal effort (in the same way they can modify the inference engine). The reference implementation does not support it. To enable a fast modify-update-test cycle on PF configuration.
A PF MAY support immutable parameters, i.e. parameters which value is determined on start then read only. To permit hardware read only value reflection. This is not implemented in the PF reference implementation.
This value MUST be gettable for an immutable parameter. A parameter that can not be accessed (read or write) is of no use.
A parameter or a block of parameters might be presented by the Parameter Framework but only used as a passthrough to the underlying subsystem (think “(void *) interfaces”). It is then possible that the endianess of the subsystem differs from the one the Parameter Framework is running on, an endianness adaptation would allow supporting those cases.
This can be seen as related to the “Parameter Adaptation” requirement or even as a special case.