1 % Parameter Framework \ 2 High level requirements 3 4 <!-- 5 Copyright (c) 2015, Intel Corporation 6 All rights reserved. 7 8 Redistribution and use in source and binary forms, with or without modification, 9 are permitted provided that the following conditions are met: 10 11 1. Redistributions of source code must retain the above copyright notice, this 12 list of conditions and the following disclaimer. 13 14 2. Redistributions in binary form must reproduce the above copyright notice, 15 this list of conditions and the following disclaimer in the documentation and/or 16 other materials provided with the distribution. 17 18 3. Neither the name of the copyright holder nor the names of its contributors 19 may be used to endorse or promote products derived from this software without 20 specific prior written permission. 21 22 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 23 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 24 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 25 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 26 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 27 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 28 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 29 ANY 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 31 SOFTWARE, 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 37 implementation implements them. Search for "reference implementation".</note> 38 39 # Introduction 40 41 The Parameter Framework is abreviated as PF in the rest of the document. 42 43 ## Philosophy 44 45 The Parameter Framework aims to be a hardware control abstraction layer. 46 Specificaly 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 52 The fundamental constraint on the underlined hardware is to be representable 53 by independent parameters. Ie: When changing one parameter it must not change 54 an other. 55 56 ### Hardware api abstraction 57 The goal of this layer is to abstract the apis of the underline hardwares. 58 Each abstracted hardware usualy have different apis, this layer responsibility 59 is to set and get parameters using the underlined native api. 60 61 See the [syncer] chapter. 62 <!--Fixme why are pandoc auto references not working ? --> 63 64 ### Hardware parameter abstraction 65 The goal if this layer is to name and organize and describing 66 the hardware parameter properties (domain of validity, size, human representation...). 67 68 See the "Parameters" chapter. 69 70 ### High level hardware independent abstraction 71 The goal of this layer is to abstract the hardware parameters behind abstract parameters 72 (called criterion in the reference implementation). 73 74 This is done by linking those abstract parameters and the hardware parameters with 75 arbitrary rules. 76 77 See the "Rule based dynamic abstraction". 78 79 ## Requirements 80 81 ### Reusability 82 The PF **SHOULD** be reusable between components. 83 <why>To be reused in different components.</why> 84 85 ### Instances independence 86 PF 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. 93 Ie parameter set order should not impact the final state. 94 Need to find justification for this. Maybe it is only a convention? 95 Maybe 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 105 chosen 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 115 A 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 120 A parameter **MUST** have a value. 121 <why>because a parameter without value would not abstract any hardware.</why> 122 123 ### Mutability 124 A PF **MUST** support mutable parameters. 125 <why>To control the underlined hardware.</why> 126 127 ### Set ability 128 This 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 132 This value **SHOULD** be gettable for a mutable parameter. 133 <why>To dump all parameter value, debug a hardware state, 134 save parameters values, display the current hardware state, 135 for coherency with the immutable parameter...</why> 136 137 ### Data type 138 139 #### Definition 140 141 <dl> 142 <dt>Data type</dt> 143 <dd> 144 All parameters have a data type. A data type designates parameter invariants. 145 146 A data type is the meaning of the data and the way values of that type can be 147 stored. 148 </dd> 149 </dl> 150 151 152 #### Philosophy 153 154 A data type defines the value properties: 155 156 - memory layout 157 - value constrains 158 159 A 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 168 A PF **SHOULD** support the following types. 169 If 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 172 be represented as an array of char (string). But this would not permit to 173 check parameter validity (invariants) nor a pretty display of the values.</why> 174 175 ##### Typed API 176 Implementation **MAY** add another API to access a parameter value. 177 <why>For example a C++ implementation may give access to a string as an 178 std::string object.</why> 179 180 ##### Integers 181 182 ###### Signed and unsigned support 183 PF **SHOULD** support signed and unsigned integer parameters 184 <why>The reference implementation supports it.</why> 185 186 ###### Size immutability 187 PF **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 191 The API to access it **MUST** respect C integer ABI. 192 <why>For easy access from C code.</why> 193 194 ###### Supported size 195 Supported integer size **SHOULD** be at least 8, 16 and 32 bits. 196 <why>The reference implementation supports it.</why> 197 198 ###### Min max support 199 PF **MAY** support constraining the parameter minimum and maximum value. 200 <why>To catch user out of valid range errors when changing the parameter 201 value.</why> 202 203 ##### String 204 ###### Support 205 PF **SHOULD** support array of characters. 206 <why>Everything that a computer can store fits in an array of characters. It can 207 be used as a fallback type if no other matches the parameter.</why> 208 209 ###### String max size 210 The array maximum size **MAY** be invariant (immutable). 211 <unknown>This is what the reference implementation does.</unknown> 212 213 ###### API 214 The API to access the string value **SHOULD** support null terminated character 215 array. As it is commonly done in C. 216 <why>For easy access from C code.</why> 217 218 ##### Fix point parameter 219 220 ###### Support 221 PF **SHOULD** support fix point parameters. I.e. integers divided by a fixed power 222 of two. 223 <unknown>The reference implementation supports it.</unknown> 224 225 ###### API 226 The 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 230 PF **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 236 PF **MAY** support constraining the parameter minimum and maximum value. 237 <why>To catch user out of valid range errors when changing the parameter 238 value.</why> 239 <unknown>The reference implementation does not support it</unknown> 240 241 ##### Floating point 242 ###### Support 243 PF **SHOULD** support floating point parameters . 244 <unknown>The reference implementation supports it.</unknown> 245 246 ###### API 247 The API to access the values **SHOULD** respect C platform float abi. 248 <note>Usually the IEEE 754 standard.</note> 249 250 ###### Size 251 PF **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 256 PF **MAY** support constraining the parameter minimum and maximum value. 257 <why>To catch user out of valid range errors when changing the parameter 258 value.</why> 259 260 ##### Bit field 261 262 ###### Support 263 PF **SHOULD** support 1 or more bit sized integers. 264 <unknown>The reference implementation supports it.</unknown> 265 266 ###### Single bit access API 267 The 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 271 Such bit parameters **SHOULD** be grouped in a bit field. 272 A bit field is an ordered set of bit parameter. 273 The API to access a bit filed **SHOULD** give access to a packed bit 274 field 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> 285 A bijective pure function converting a parameter value between the syncer 286 and other parameter reader/writer (including the inference engine). 287 288 The 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, 294 thus the transformation must be bijective. 295 </why> 296 </dd> 297 </dl> 298 299 #### Philosophy 300 301 Parameters 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 303 be necessary for upper layer to access in a range 0-100.</note>\ 304 305 This 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 307 to expose it in mm. </note>\ 308 309 Parameters types offer a way to abstract underlined implementation. 310 <note>For example a Q2,2 (see [fix-point-parameter]) when setting 1 311 will be translated to 0100. </note>\ 312 313 With parameter adaptation, types can be even further parameterised. 314 <note>For example, Qn,m Fix point parameter could be emulated with a $*2^n$ 315 adaptation over an n + m integer. </note>\ 316 317 Parameter adaptation could be implemented by the syncer. 318 Nevertheless syncers are supposed to contain only 319 business logic and should not be impacted by upper layer needs. 320 321 #### Requirements 322 323 ##### Support 324 The 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 337 A PF **MAY** offer Parameter adaptation composition. I.e. combine multiple parameter 338 adaptation 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 342 builtin 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 344 adaptation is always combined with the affine adaptation</ko> 345 346 ### Parameter tree 347 A parameter **SHOULD** be structured in a tree. Each parameter being a distinct 348 tree leaf. 349 <why>Tree is a simple data structure that can be easily represented and is 350 enough to map underlined layers.</why> 351 352 #### Identifier 353 Each node of the tree **SHOULD** have its own identifier with the same 354 characteristics (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 362 The PF philosophy is to map the hardware characteristics to parameters. 363 In order to impact the hardware when parameters are modified, a hardware specific 364 code must be used. 365 366 Syncers are responsible for synchronizing the values of parameters to the underlined hardware. 367 Ie, it is the glue between hardware and parameters. It contains the code specific 368 to access an hardware. 369 370 The 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> 377 Entity that keeps synchronised PF parameters and their associated hardware. 378 </dd> 379 </dl> 380 381 ## Requirements 382 383 ### Mapping 384 A 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 388 One parameter **MUST NOT** be mapped to two or more syncer. 389 Ie: a parameter MUST be mapped to zero or one syncer. 390 <why>Which syncer should be responsible to retrieve the initial parameter value 391 if they are multiple per parameter?</why> 392 393 ### Read hardware 394 A syncer **MUST** support retrieving the mapped parameters value from the mapped 395 hardware. 396 <why>to retrieve a parameter value at the start of the PF.</why> 397 398 #### Write hardware 399 A syncer **MUST** support setting the mapped parameters value to the mapped 400 hardware. 401 <why>to synchronise hardware on parameter change.</why> 402 403 #### API 404 This API **MAY** be a packed parameter structure, following the C ABI without 405 padding. 406 <note>This is what the reference implementation does.</note> 407 <unknown>TODO</unknown> 408 409 ## Parameter introspection 410 The syncer API **SHOULD** allow introspection of the mapped parameters. 411 <why>the parameter structure may be useful for the syncer to communicate with 412 the hardware. For example a syncer might need each to know each associated 413 parameter 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 421 The PF creates syncer using syncer builder. 422 423 ### Requirements 424 The PF **MUST** be able to create syncers. 425 <why>To bind on the corresponding parameters.</why> 426 427 ### Identifier 428 429 #### Syncer library 430 All syncers mapping to the same hardware **SHOULD** have their builders regrouped 431 in 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. 441 For example all parameters that are mapped to sound card should be linked to a 442 sound card syncer library. (Each parameter are then individually mapped to a specific syncer.) 443 </why> 444 445 #### Syncer ID 446 A syncer builder **MUST** have a unique identifier in its containing syncer 447 library. 448 <why>To uniquely identify the syncer that should bind on parameters. Given that 449 the syncer library has already been specified.</why> 450 451 #### Library UID 452 A 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 458 Syncer 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 463 Such syncer plugins **SHOULD** have an unique entry point that -- when called -- 464 should register its payload (syncer library/builder) in the provided gatherer. 465 <note>This permit to merge multiple syncer libraries in one shared 466 library.</note> 467 <unknown>The reference implementation supports it.</unknown> 468 469 #### Plugin interdependancies 470 Multiple syncer plugins, may depend on each other. The PF should appropriately 471 handle 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> 480 A 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 493 Syncer **SHOULD** synchronise the mapped hardware on parameter change. 494 <why>To always keep synchronise the underlined hardware and the PF 495 parameters.</why> 496 497 ### Read hardware 498 Syncer **SHOULD** retrieve parameter value from the hardware if no value has be 499 set since the PF start. 500 <note>This is usually implemented on PF start, initialize the parameter values 501 with the mapped hardware current state.</note> 502 <why>To allow introspection of the hardware.</why> 503 504 ### Explicit sync 505 A mode with synchronisation on client request **SHOULD** be supported. 506 <why>The user may want to group the synchronization of multiple parameters -- 507 for instance if a syncer contains more than 1 parameter -- in order to avoid 508 undesired intermediary states.</why> 509 510 ### Out of sync 511 Syncers **MAY** report an 'out-of-sync' condition indicating that the hardware 512 parameter values are not (or no longer) reflecting the last values set by the 513 Parameter Framework. 514 <why>This can happen when the underlying hardware subsystem 515 crashes/reboots/...</why> 516 517 #### Recovery 518 When a syncer reports an out-of-sync condition, the PF **MUST** try to resync 519 the hardware values. 520 521 # Rule based dynamic abstraction 522 523 ## Philosophy 524 525 The PF offers parameters mapped on hardware. This is a good but weak 526 abstraction as there is often a 1/1 relation between a parameter and the hardware 527 it maps. Ie: parameter abstract how to access hardware and what hardware but 528 are still hardware specific. 529 530 A PF offers a mechanism to abstract the parameters to a higher level concept. 531 532 The goal is to hide numerous parameters and their dynamic values behind simple 533 and human friendly API. 534 535 It works by grouping parameters with similar management and defining 536 configurations for each "scenario". These "scenario" are then given a priority 537 and 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> 548 Set of values for different parameters. A configuration **MUST NOT** contain 2 549 values of the same parameter. 550 551 For example, given a PF with 3 integer parameters A,B,C, a configuration can 552 contain: 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> 561 A Parameter that is not contained by any configuration. 562 <dd> 563 </dl> 564 565 ## Configuration 566 567 ### Support 568 A PF **MUST** offer configurations as described in the Definition chapter. 569 <note>rule based parameter engine does not manipulate directly values, it 570 applies configuration on the parameters.</note> 571 <unknown>This is what the reference implementation does.</unknown> 572 573 ### Eligibility 574 Each configuration **MUST** be associated with a predicate that condition its 575 eligibility. A configuration with a predicate that evaluates to `true` is called 576 an "eligible configuration" 577 <why>This is what the reference implementation does.</why> 578 579 ### Default 580 It **SHOULD** be possible to express a predicate to always evaluates to `true`. 581 Ie: 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 583 configuration in a domain -- see below.</why> 584 585 ### Predicate implementation 586 The predicate **SHOULD** be a "selection criterion rule". See next chapter for a 587 definition. 588 <why>The reference implementation uses a boolean expression based engine.</why> 589 590 ## Selection criterion 591 592 ### State uniqueness 593 A selection criterion **MUST** have one, and only one, state at a given time. 594 595 ### State validity 596 A selection criterion **MUST** have a always known immutable domain of definition. 597 Ie All the possible state that a selection criterion can take **MUST** be known 598 at 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 606 The selection criterion possible states **MUST** be specifiable by directly a 607 state 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 613 The selection criterion possible states **SHOULD** be specifiable by a combination 614 of 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 619 empty set -- would not be empty. The empty set would be the only possible 620 criteria state.</note> 621 <why>The reference implementation supports it.</why> 622 623 ### Criteria number 624 The PF **SHOULD NOT** limit the number of criteria. 625 626 #### State number 627 The 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 629 criterion and 2^32 values for an exclusive criterion</ko> 630 631 ### Definitions 632 <dl> 633 <dt>Selection criterion rule</dt> 634 <dd> 635 Function (in the mathematical sense) that **MUST** given selection criteria 636 return a Boolean. Ie, a [predicate](https://en.wikipedia.org/wiki/Predicate_%28mathematical_logic%29). 637 </dd> 638 639 <dt>Rule</dt> 640 <dd> 641 A 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 649 The API to change criterion values **MUST** allow atomicity regarding 650 configuration application. I.e. it **MUST** be possible to change multiple 651 criterion values without triggering a configuration application. 652 <why>Two criterion might have an excluding state. If configuration application 653 was triggered after each criterion change this transitory incompatible state 654 would impact the system. 655 For example 2 criterion `Tx` and `Rx` with 2 values `"on"` and `"off"` may have 656 an incompatible state `Tx = Rx = "on"`. Ie this state is unspecified and the 657 inference engine would gave unknown result. 658 \ 659 When 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 ? --> 663 a transitory state `Tx = "on" and Rx = "on"` may be reached. Nevertheless 664 the inference engine must not be run on such. There must be a way to go 665 from one state 1 to state 2 without triggering configuration application. 666 </why> 667 668 ### Rules 669 670 It **MUST** always be able to express a selection criterion rule from a given 671 selection criterion state. 672 I.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, 674 the hardware can not be abstracted in this state witch defeats the PF purpose.</why> 675 676 Parameter values change **SHOULD** be selected by Rules. 677 <why>A rule based inference engine has been chosen based on implementation and 678 configuration ease</why> 679 680 ## Domains 681 682 ### Definition 683 <dl> 684 <dt>Domain</dt> 685 <dd> 686 Ordered set of configuration, all of which contain the values for the 687 same parameters. 688 </dd> 689 </dl> 690 691 ### Philosophy 692 693 When creating configurations for parameters, a pattern emerges. 694 Some parameters are naturally grouping together. Ie changing on the same predicates. 695 696 Without carefully crafting configuration predicates for mutual exclusivity, 697 multiples configuration of the same parameter could be eligible on the same 698 criterion state. This would lead to an ambiguity: which configuration should be applied. 699 700 Multiple 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 706 The domains this specification recommend is this last solution. 707 It has been chosen as the recommended solution (just like parameter tree) 708 because it is a simple solution and is implemented in the reference implementation. 709 710 The constraint of this solution is that a configuration can no longer be shared 711 between domains. For example a global default configuration can not exist. 712 It must be split up for each domain. 713 714 This choice also force parameters to be independently accessible. 715 716 ### Requirement 717 718 #### Configuration application ambiguity 719 There **MUST** be a mechanism to avoid ambiguity on multiple configuration eligibility 720 for the same parameter. 721 <why>Applying multiple configurations would leave the parameters in an unknown state.</why> 722 723 #### Domain support 724 Each configuration **SHOULD** be in a "domain" (see Definition chapter). 725 <why>Domains are mostly a way to define the priority of configuration application 726 for some parameters.</why> 727 <ko>It is not a MUST because this goal could also be achieve with (for 728 example) global configurations and per parameter priority. It is not a MAY 729 because the reference implementation uses domains.</ko> 730 731 #### Configuration priority 732 If multiple configuration are eligible, the first one **MUST** be applied. 733 <why>If multiple configuration are eligible, there must be a way to discriminate 734 them. The order was arbitrary chosen. 735 See the domain philosophy section for more information about this choice.</why> 736 737 #### Lazy application 738 If no configuration is eligible, no configuration **MUST** be applied. 739 <note>It means that if none of the configurations is eligible, none is applied. 740 This also mean that no function can be defined between criteria and states. 741 I.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 745 Parameter 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 749 Domains **MAY** be sequence aware. Such domains update their associated 750 parameters 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. 753 This is contradictory with the fact that parameters MUST be accessed independently.</why> 754 755 # (de)serialization 756 757 ## Philosophy 758 Serialization and deserialization are meant to support destruction recovery and 759 configuration deployment. 760 761 These are the same requirements than for a database, it needs to be able to save 762 its state and restore for backup, deployment, reboot... 763 764 ## Definition 765 PF 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 778 The PF data **MUST** be deserializable. 779 <why>Otherwise a PF instance could only be created empty and then be filled by 780 the tuning interface. The reference implementation supports it.</why> 781 782 ### Deserializable from a file 783 The PF data **SHOULD** be deserializable from a config file. 784 <why>This is usually how program configuration are stored. The reference 785 implementation supports it.</why> 786 787 ### Serializable 788 The PF data **SHOULD** be serializable. 789 <why>In order to save a PF instance state and restore it later. This achieve 790 destruction recovery. The reference implementation supports it.</why> 791 792 ### (De)Serialization of individual data 793 The PF data **SHOULD** be serializable/deserializable by parts. 794 <why>For easier configuration management: for versioning; for selecting only wanted parts of a 795 complete configuration.</why> 796 797 ### Serialization format 798 **TODO**: XML ? 799 800 ### Implementation 801 Syncer build and syncer library identifiers **SHOULD** be strings. 802 <unknown>The reference application does so.</unknown> 803 804 # Post mortem debug 805 A PF **MAY** save all data needed to replay it's state evolution. 806 <note>Eg: log criterion change, configuration application, parameter 807 external change. 808 809 This 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). 811 This is kind of like the bash -x feature. 812 </why> 813 814 # Introspection 815 ## Philosophy 816 In order to debug the user configuration, allow introspection of PF data at runtime. 817 As data is meant to be displayed to user, lots are requirements are towards 818 pretty printing PF data. 819 820 ## Requirements 821 822 ### Support 823 User **SHOULD** be able to inspect PF data. 824 <why>To offer run time debugging. 825 This 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 836 PF **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 844 Users **SHOULD** be able to modify rogue parameters through the native API at 845 all time. 846 <why>Otherwise, a rogue parameter is of no use.</why> 847 <ko>In the reference implementation, under certain conditions, this is not 848 possible (tuning mode)</ko> 849 850 ### Parameter Identifiers 851 852 #### Support 853 Every parameter **MUST** have an identifier that uniquely identifies it. 854 <why>to identify a parameter outside the framework</why> 855 856 #### String 857 This identifier **SHOULD** be a string. 858 <why>So that a human user can identify a parameter with ease.</why> 859 860 #### Determinism 861 Two PF instances with the same parameters **MUST** have the same identifier for 862 those parameters. 863 I.e. this identifier should be the same across all instances with the same 864 configuration. 865 <why>Persistence of parameter identifier across PF instances with the same 866 configuration. To identify parameters independently of the host machine and PF 867 instance</why> 868 869 #### Tree path 870 The identifier of each node of a parameter tree **SHOULD** be a combination of its 871 parents. More specifically, if the identifier is a string it **SHOULD** be 872 formated 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> 883 Tuning 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 891 As 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 893 understand and should be easily modified not correct. 894 895 To address this need, a fast modify-update-test cycle should be possible. 896 897 ## Requirements 898 899 ### Inference engine 900 Users **SHOULD** be able to modify the PF inference engine behaviour (rules, 901 configuration...) with minimal effort. 902 <why>To enable a fast modify-update-test cycle during tuning. 903 This 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 909 may not disappear on PF restart. This could be implemented in several way, for 910 example: 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 920 Tuning **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 924 Users **SHOULD** be able to modify the parameter values at any time. 925 This change **SHOULD NOT** be overwritten without a user action. 926 <note>User overwritten user action could be a log out, leaving some tuning mode, 927 forcing 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 932 A 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 934 tuning).</why> 935 936 # Command line interface 937 <ko>Is this not an implementation detail? Does a client really needs it?</ko> 938 939 ## Support 940 The 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 942 protocol.</why> 943 <note>This requirement is fulfilled by remote-processor and remote-command on the reference implementation.</note> 944 945 ## Introspection & tunning 946 This 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 948 system.</why> 949 950 ## Auto completion 951 This command line interface **MAY** offer argument auto completion. 952 <why>Is more user friendly.</why> 953 954 # Bindings 955 956 ## C 957 The PF **SHOULD** expose its API in C. 958 <why>The PF aims to be a hardware abstraction thus middle ware which is often 959 written in C or a language compatible with C. Virtually all programing language 960 support C Foreign Procedure Call, having a C API ease integration whichever the 961 host language is.</why> 962 963 ## Programing language 964 The PF **MAY** expose its API to multiple programing language. 965 <unknown>The reference implementation has python bindings.</unknown> 966 967 # Performance 968 969 The reference Parameter Framework implementation is mainly intended for use 970 in consumer electronics such as smartphones and tablets. Such platforms are 971 often referred to as "embedded" platforms but their capacity today is so huge in 972 terms of both computing and memory that they can be considered as small personal 973 computers. 974 975 Moreover, since one of the Parameter Framework's primary feature is to implement 976 storage of 977 978 - hardware description 979 - settings 980 981 its memory footprint largely depends on how many such items are stored. 982 983 For those reasons, there are no performance requirements imposed on the 984 architecture. Performance considerations are left to the implementation of the 985 Parameter Framework and/or the client and/or the build chain. 986 987 # Next 988 989 <ko> 990 The following requirements are not implemented in the reference implementation 991 and are to be considered draft. 992 </ko> 993 994 ## Multi OS 995 PF **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, 1002 needs emerge to use it on other platform.</why> 1003 1004 ## Tuning 1005 ### Get and set multiple parameter values in one request 1006 #### Atomicity 1007 When setting multiple parameters from one client request, 1008 and when one or more parameter value is invalid (eg. out of range), 1009 no parameter **SHOULD** be set. 1010 Eg: an invalid request to change parameters **SHOULD** not impact the parameters 1011 values nor the subsystems. 1012 <note>This may be implemented by first checking parameters validity 1013 before setting them, or implementing a rollback mechanism, or any other way.</note> 1014 <why>To provide parameter mutation atomicity to the client. 1015 This is especially important if the client wants to implement parameter consistency. 1016 Eg: let two parameters have excluding values, 1017 if a transaction fail after the first parameter is set but not the second, 1018 the excluding constraint may be violated. 1019 It also usefull for the client to know the state of the parameters 1020 after a parameter set without having to query the PF.</why> 1021 1022 #### Access parameters as Xml 1023 Getting and setting the content of one or more ([one, all]) parameters **SHOULD** 1024 be possible in xml. 1025 <why>For performance reason. Tools often need to update multiple parameter 1026 and having one call per parameter is too slow. (benchmark ?). 1027 This feature permit the client to save and restore from an external database parameter 1028 values a la `alsa.state`.</why> 1029 1030 #### Access parameters as binary 1031 The PF host API **SHOULD** expose parameter values with the same API syncer use. 1032 <why>The current reference implementation abstracts the memory layout of 1033 parameters. This memory layout is specified in the parameter structure thus 1034 is known by the client.</why> 1035 1036 ## Stage and commit Sync 1037 Explicit 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 1039 transition state, manual parameter synchronisation is requested. 1040 1041 Sync request was implemented in the reference implementation by syncing all 1042 parameters, including the one that were not changed since last sync. 1043 1044 For performance reason only the changed parameters should be send to hardware.</why> 1045 1046 1047 ## Structured api API 1048 The PF host API **SHOULD** be structured. 1049 I.e.: the PF, when requested for a list of domains, should return a list of 1050 structured object, each containing configuration objects, containing their 1051 values... 1052 <why>The reference implementation has a string oriented API. E.g/: The list of 1053 domains is returned as a concatenation of domains name in one big string. This 1054 leads to hard to use API from C and C++ code. Especially for testing</why> 1055 1056 ### Implementation language 1057 The 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 1061 It will be compatible with android thank to clang's libc++" 1062 1063 <note>Put this in a design document.</note> 1064 1065 ## Long term 1066 The following requirements are not planned to be implemented any time soon as 1067 their is not need identified but are rather a long term guidance. 1068 1069 ### Custom parameter types 1070 The client **MAY** inject custom parameters types. 1071 <why>As the client creates parameters it should also be able to specify the 1072 parameter contains ie its types. Without this possibility the client has to 1073 choose a built-in that may not match what he wants. 1074 1075 For example representing a prime number with an integer would not allow to enforce primness. 1076 1077 For example a complex number could be represented with two float but `a+bi` format 1078 could not be used. 1079 1080 For example stocking a parameter with a dynamic type, say either a string or a number 1081 could be done with a boolean a string and a number but this could not be pretty 1082 print and not memory efficient. 1083 </why> 1084 1085 ### Structure tunning 1086 Users **MAY** be able to modify the parameters (types, identifiers, tree...) with 1087 minimal 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 1092 A PF **MAY** support immutable parameters, i.e. parameters which value is determined 1093 on 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 1097 This 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 1101 A parameter or a block of parameters might be presented by the Parameter 1102 Framework but only used as a passthrough to the underlying subsystem (think 1103 "`(void *)` interfaces"). It is then possible that the endianess of the 1104 subsystem differs from the one the Parameter Framework is running on, an 1105 endianness adaptation would allow supporting those cases. 1106 1107 This can be seen as related to the "Parameter Adaptation" requirement or even 1108 as a special case. 1109 1110 </article> 1111