{"action":"created","comment":{"url":"https://api.github.com/repos/01org/parameter-framework/pulls/comments/35517680","id":35517680,"diff_hunk":"@@ -0,0 +1,526 @@\n+High level requirements\n+=======================\n+\n+(Note: some requirements are only motivated by the fact that the reference implementation\n+       implements them. Seach for \"reference implementation\".)\n+\n+# Introduction\n+The PF MUST be a library.\n+(Why: To be reused in different components.)\n+\n+PF instances MUST not share any muttable data.\n+(Why: to guarantee that different PF instances will not impact each others.)\n+\n+# Parameters\n+\n+A PF MUST be able to handle parameters.\n+(Why: because the PF aims to abstract hardware and model it by parameters.)\n+\n+## Definitions\n+\n+hardware: system controlled by the PF. Not necessary material system.\n+          This term was chosen because:\n+ - historically the PF reference implementation was used to abstract hardware\n+ - the subsystem term would arguably fit best is already used.\n+(FIXME: choose subsystem instead, it is not used in fact.)\n+\n+## Value\n+\n+A parameter MUST have a value.\n+(Why: because a parameter without value would not abstract any hardware.)\n+\n+A PF MUST support mutable parameters.\n+(Why: To control the underlined hardware.)\n+\n+A PF MAY support immutable parameters, ie parameters which value is determined on start then read only.\n+(Why: To permit hardware read only value reflection.)\n+(Note: This is not implemented in the PF reference implementation.)\n+\n+This value MUST be gettable and settable (except if immutable).\n+(Why: A parameter that can not be accessed is of no use.)\n+\n+A value MUST be convertible to a string.\n+(Why: To display a parameter value to the human user for debugging purpose.)\n+\n+A bijective conversion string <-> value SHOULD exist.\n+(Why: To support serialization and deserialization of the parameter values.\n+      It is not a MUST because a PF implementation could offer serialization to\n+      custom -not string based- format.)\n+\n+### Data type\n+\n+#### Definition\n+All parameters have a data type.\n+A data type designates parameter invariants.\n+A data type is the the meaning of the data and the way values of that type can be stored.\n+\n+\n+#### Philosophy\n+\n+A data type defines the value properties:\n+ - memory layout\n+ - value constrains\n+\n+A value type is mostly used to:\n+ - pretty display parameter values (not just a as an array of bits)\n+ - check for user error when setting it (out of bound, invalid...)\n+ - offer a type safe api\n+\n+#### Requirements\n+\n+A PF SHOULD support the following types.\n+If a type is chosen to be supported, it MUST respect all MUST clause,\n+SHOULD respect all SHOULD clause, MAY respect all MAY clause of the type.\n+(Why: All type are not necessary to use the PF. For example any parameter could\n+      be represented as an array of char (string). But this would not permit to\n+      check parameter validity (invariants) as well a pretty displaying the values.)\n+\n+Implementation MAY add another API to access a parameter value.\n+(Why: For example a C++ implementation may give access to a string as an std::string object.)\n+\n+##### Integers\n+PF SHOULD support signed and unsigned integer parameters\n+(Why: The reference implementation supports it.)\n+\n+PF MUST support integer with invariant size.\n+(Why: It is common in C API to expect numbers to have a fixed maximum size.)\n+\n+The API to access it MUST respect C integer abi.\n+(Why: For easy access from C code.)\n+\n+Supported integer size SHOULD be at least 8, 16 and 32 bits.\n+(Why: The reference implementation supports it.)\n+\n+PF MAY support constraining the parameter minimum and maximum value.\n+(Why: To catch user out of valid range errors when changing the parameter value.)\n+\n+##### String\n+PF SHOULD support array of characters.\n+(Why: Everything that a computer can store fits in an array of characters.\n+      It can be used as a fallback type if no other matches the parameter.)\n+\n+The array maximum size MAY be invariant (immutable).\n+(Note: This is what the reference implementation does.)\n+\n+The API to access the string value SHOULD support null terminated character array.\n+As it is commonly done in C.\n+(Why: For easy access from C code.)\n+\n+##### Fix point parameter\n+PF SHOULD support fix point parameters. Ie integers divided by a fixed power of two.\n+(Why: The reference implementation supports it.)\n+\n+The API to access the values SHOULD respect the Qm.n and UQm.n standards.\n+(Why: It is the main standard for fix point parameters.)\n+\n+PF SHOULD support at least m + n ∈ [0,32]","path":"doc/Requirements.md","position":116,"original_position":116,"commit_id":"556c345e77a36cdbd4b87a03893e0c911a7e938e","original_commit_id":"556c345e77a36cdbd4b87a03893e0c911a7e938e","user":{"login":"dawagner","id":6430928,"avatar_url":"https://avatars.githubusercontent.com/u/6430928?v=3","gravatar_id":"","url":"https://api.github.com/users/dawagner","html_url":"https://github.com/dawagner","followers_url":"https://api.github.com/users/dawagner/followers","following_url":"https://api.github.com/users/dawagner/following{/other_user}","gists_url":"https://api.github.com/users/dawagner/gists{/gist_id}","starred_url":"https://api.github.com/users/dawagner/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dawagner/subscriptions","organizations_url":"https://api.github.com/users/dawagner/orgs","repos_url":"https://api.github.com/users/dawagner/repos","events_url":"https://api.github.com/users/dawagner/events{/privacy}","received_events_url":"https://api.github.com/users/dawagner/received_events","type":"User","site_admin":false},"body":"- This does not render well because of the brackets\r\n- This is not true for Signed Qn.m\r\n\r\nReplace with: `0 <= m + n <= 31` for a Signed Qn.m and `0 <= m + n <= 32` for an Unsigned Qn.m.","created_at":"2015-07-27T09:13:50Z","updated_at":"2015-07-27T09:13:50Z","html_url":"https://github.com/01org/parameter-framework/pull/144#discussion_r35517680","pull_request_url":"https://api.github.com/repos/01org/parameter-framework/pulls/144","_links":{"self":{"href":"https://api.github.com/repos/01org/parameter-framework/pulls/comments/35517680"},"html":{"href":"https://github.com/01org/parameter-framework/pull/144#discussion_r35517680"},"pull_request":{"href":"https://api.github.com/repos/01org/parameter-framework/pulls/144"}}},"pull_request":{"url":"https://api.github.com/repos/01org/parameter-framework/pulls/144","id":39301509,"html_url":"https://github.com/01org/parameter-framework/pull/144","diff_url":"https://github.com/01org/parameter-framework/pull/144.diff","patch_url":"https://github.com/01org/parameter-framework/pull/144.patch","issue_url":"https://api.github.com/repos/01org/parameter-framework/issues/144","number":144,"state":"open","locked":false,"title":"Parameter Framework requirements","user":{"login":"krocard","id":6862950,"avatar_url":"https://avatars.githubusercontent.com/u/6862950?v=3","gravatar_id":"","url":"https://api.github.com/users/krocard","html_url":"https://github.com/krocard","followers_url":"https://api.github.com/users/krocard/followers","following_url":"https://api.github.com/users/krocard/following{/other_user}","gists_url":"https://api.github.com/users/krocard/gists{/gist_id}","starred_url":"https://api.github.com/users/krocard/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/krocard/subscriptions","organizations_url":"https://api.github.com/users/krocard/orgs","repos_url":"https://api.github.com/users/krocard/repos","events_url":"https://api.github.com/users/krocard/events{/privacy}","received_events_url":"https://api.github.com/users/krocard/received_events","type":"User","site_admin":false},"body":"List the Parameter Framework requirements independently of it's reference implementation.","created_at":"2015-07-06T19:24:05Z","updated_at":"2015-07-27T09:13:50Z","closed_at":null,"merged_at":null,"merge_commit_sha":"c67cbc658b612d1b699f6c8fa63e6b13bdaf8f1c","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/01org/parameter-framework/pulls/144/commits","review_comments_url":"https://api.github.com/repos/01org/parameter-framework/pulls/144/comments","review_comment_url":"https://api.github.com/repos/01org/parameter-framework/pulls/comments{/number}","comments_url":"https://api.github.com/repos/01org/parameter-framework/issues/144/comments","statuses_url":"https://api.github.com/repos/01org/parameter-framework/statuses/556c345e77a36cdbd4b87a03893e0c911a7e938e","head":{"label":"krocard:requirements","ref":"requirements","sha":"556c345e77a36cdbd4b87a03893e0c911a7e938e","user":{"login":"krocard","id":6862950,"avatar_url":"https://avatars.githubusercontent.com/u/6862950?v=3","gravatar_id":"","url":"https://api.github.com/users/krocard","html_url":"https://github.com/krocard","followers_url":"https://api.github.com/users/krocard/followers","following_url":"https://api.github.com/users/krocard/following{/other_user}","gists_url":"https://api.github.com/users/krocard/gists{/gist_id}","starred_url":"https://api.github.com/users/krocard/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/krocard/subscriptions","organizations_url":"https://api.github.com/users/krocard/orgs","repos_url":"https://api.github.com/users/krocard/repos","events_url":"https://api.github.com/users/krocard/events{/privacy}","received_events_url":"https://api.github.com/users/krocard/received_events","type":"User","site_admin":false},"repo":{"id":24673385,"name":"parameter-framework","full_name":"krocard/parameter-framework","owner":{"login":"krocard","id":6862950,"avatar_url":"https://avatars.githubusercontent.com/u/6862950?v=3","gravatar_id":"","url":"https://api.github.com/users/krocard","html_url":"https://github.com/krocard","followers_url":"https://api.github.com/users/krocard/followers","following_url":"https://api.github.com/users/krocard/following{/other_user}","gists_url":"https://api.github.com/users/krocard/gists{/gist_id}","starred_url":"https://api.github.com/users/krocard/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/krocard/subscriptions","organizations_url":"https://api.github.com/users/krocard/orgs","repos_url":"https://api.github.com/users/krocard/repos","events_url":"https://api.github.com/users/krocard/events{/privacy}","received_events_url":"https://api.github.com/users/krocard/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/krocard/parameter-framework","description":"Plugin-based and rule-based framework for describing and controlling parameters","fork":true,"url":"https://api.github.com/repos/krocard/parameter-framework","forks_url":"https://api.github.com/repos/krocard/parameter-framework/forks","keys_url":"https://api.github.com/repos/krocard/parameter-framework/keys{/key_id}","collaborators_url":"https://api.github.com/repos/krocard/parameter-framework/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/krocard/parameter-framework/teams","hooks_url":"https://api.github.com/repos/krocard/parameter-framework/hooks","issue_events_url":"https://api.github.com/repos/krocard/parameter-framework/issues/events{/number}","events_url":"https://api.github.com/repos/krocard/parameter-framework/events","assignees_url":"https://api.github.com/repos/krocard/parameter-framework/assignees{/user}","branches_url":"https://api.github.com/repos/krocard/parameter-framework/branches{/branch}","tags_url":"https://api.github.com/repos/krocard/parameter-framework/tags","blobs_url":"https://api.github.com/repos/krocard/parameter-framework/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/krocard/parameter-framework/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/krocard/parameter-framework/git/refs{/sha}","trees_url":"https://api.github.com/repos/krocard/parameter-framework/git/trees{/sha}","statuses_url":"https://api.github.com/repos/krocard/parameter-framework/statuses/{sha}","languages_url":"https://api.github.com/repos/krocard/parameter-framework/languages","stargazers_url":"https://api.github.com/repos/krocard/parameter-framework/stargazers","contributors_url":"https://api.github.com/repos/krocard/parameter-framework/contributors","subscribers_url":"https://api.github.com/repos/krocard/parameter-framework/subscribers","subscription_url":"https://api.github.com/repos/krocard/parameter-framework/subscription","commits_url":"https://api.github.com/repos/krocard/parameter-framework/commits{/sha}","git_commits_url":"https://api.github.com/repos/krocard/parameter-framework/git/commits{/sha}","comments_url":"https://api.github.com/repos/krocard/parameter-framework/comments{/number}","issue_comment_url":"https://api.github.com/repos/krocard/parameter-framework/issues/comments{/number}","contents_url":"https://api.github.com/repos/krocard/parameter-framework/contents/{+path}","compare_url":"https://api.github.com/repos/krocard/parameter-framework/compare/{base}...{head}","merges_url":"https://api.github.com/repos/krocard/parameter-framework/merges","archive_url":"https://api.github.com/repos/krocard/parameter-framework/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/krocard/parameter-framework/downloads","issues_url":"https://api.github.com/repos/krocard/parameter-framework/issues{/number}","pulls_url":"https://api.github.com/repos/krocard/parameter-framework/pulls{/number}","milestones_url":"https://api.github.com/repos/krocard/parameter-framework/milestones{/number}","notifications_url":"https://api.github.com/repos/krocard/parameter-framework/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/krocard/parameter-framework/labels{/name}","releases_url":"https://api.github.com/repos/krocard/parameter-framework/releases{/id}","created_at":"2014-10-01T09:54:18Z","updated_at":"2015-04-13T15:36:05Z","pushed_at":"2015-07-24T19:20:29Z","git_url":"git://github.com/krocard/parameter-framework.git","ssh_url":"git@github.com:krocard/parameter-framework.git","clone_url":"https://github.com/krocard/parameter-framework.git","svn_url":"https://github.com/krocard/parameter-framework","homepage":"","size":4006,"stargazers_count":0,"watchers_count":0,"language":"C++","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"01org:master","ref":"master","sha":"b03e972701aeb7ffe1047c21a019e2d5c7c7bc5c","user":{"login":"01org","id":1635439,"avatar_url":"https://avatars.githubusercontent.com/u/1635439?v=3","gravatar_id":"","url":"https://api.github.com/users/01org","html_url":"https://github.com/01org","followers_url":"https://api.github.com/users/01org/followers","following_url":"https://api.github.com/users/01org/following{/other_user}","gists_url":"https://api.github.com/users/01org/gists{/gist_id}","starred_url":"https://api.github.com/users/01org/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/01org/subscriptions","organizations_url":"https://api.github.com/users/01org/orgs","repos_url":"https://api.github.com/users/01org/repos","events_url":"https://api.github.com/users/01org/events{/privacy}","received_events_url":"https://api.github.com/users/01org/received_events","type":"Organization","site_admin":false},"repo":{"id":16009363,"name":"parameter-framework","full_name":"01org/parameter-framework","owner":{"login":"01org","id":1635439,"avatar_url":"https://avatars.githubusercontent.com/u/1635439?v=3","gravatar_id":"","url":"https://api.github.com/users/01org","html_url":"https://github.com/01org","followers_url":"https://api.github.com/users/01org/followers","following_url":"https://api.github.com/users/01org/following{/other_user}","gists_url":"https://api.github.com/users/01org/gists{/gist_id}","starred_url":"https://api.github.com/users/01org/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/01org/subscriptions","organizations_url":"https://api.github.com/users/01org/orgs","repos_url":"https://api.github.com/users/01org/repos","events_url":"https://api.github.com/users/01org/events{/privacy}","received_events_url":"https://api.github.com/users/01org/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/01org/parameter-framework","description":"Plugin-based and rule-based framework for describing and controlling parameters","fork":false,"url":"https://api.github.com/repos/01org/parameter-framework","forks_url":"https://api.github.com/repos/01org/parameter-framework/forks","keys_url":"https://api.github.com/repos/01org/parameter-framework/keys{/key_id}","collaborators_url":"https://api.github.com/repos/01org/parameter-framework/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/01org/parameter-framework/teams","hooks_url":"https://api.github.com/repos/01org/parameter-framework/hooks","issue_events_url":"https://api.github.com/repos/01org/parameter-framework/issues/events{/number}","events_url":"https://api.github.com/repos/01org/parameter-framework/events","assignees_url":"https://api.github.com/repos/01org/parameter-framework/assignees{/user}","branches_url":"https://api.github.com/repos/01org/parameter-framework/branches{/branch}","tags_url":"https://api.github.com/repos/01org/parameter-framework/tags","blobs_url":"https://api.github.com/repos/01org/parameter-framework/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/01org/parameter-framework/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/01org/parameter-framework/git/refs{/sha}","trees_url":"https://api.github.com/repos/01org/parameter-framework/git/trees{/sha}","statuses_url":"https://api.github.com/repos/01org/parameter-framework/statuses/{sha}","languages_url":"https://api.github.com/repos/01org/parameter-framework/languages","stargazers_url":"https://api.github.com/repos/01org/parameter-framework/stargazers","contributors_url":"https://api.github.com/repos/01org/parameter-framework/contributors","subscribers_url":"https://api.github.com/repos/01org/parameter-framework/subscribers","subscription_url":"https://api.github.com/repos/01org/parameter-framework/subscription","commits_url":"https://api.github.com/repos/01org/parameter-framework/commits{/sha}","git_commits_url":"https://api.github.com/repos/01org/parameter-framework/git/commits{/sha}","comments_url":"https://api.github.com/repos/01org/parameter-framework/comments{/number}","issue_comment_url":"https://api.github.com/repos/01org/parameter-framework/issues/comments{/number}","contents_url":"https://api.github.com/repos/01org/parameter-framework/contents/{+path}","compare_url":"https://api.github.com/repos/01org/parameter-framework/compare/{base}...{head}","merges_url":"https://api.github.com/repos/01org/parameter-framework/merges","archive_url":"https://api.github.com/repos/01org/parameter-framework/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/01org/parameter-framework/downloads","issues_url":"https://api.github.com/repos/01org/parameter-framework/issues{/number}","pulls_url":"https://api.github.com/repos/01org/parameter-framework/pulls{/number}","milestones_url":"https://api.github.com/repos/01org/parameter-framework/milestones{/number}","notifications_url":"https://api.github.com/repos/01org/parameter-framework/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/01org/parameter-framework/labels{/name}","releases_url":"https://api.github.com/repos/01org/parameter-framework/releases{/id}","created_at":"2014-01-17T19:24:01Z","updated_at":"2015-07-11T10:04:10Z","pushed_at":"2015-07-24T19:20:30Z","git_url":"git://github.com/01org/parameter-framework.git","ssh_url":"git@github.com:01org/parameter-framework.git","clone_url":"https://github.com/01org/parameter-framework.git","svn_url":"https://github.com/01org/parameter-framework","homepage":"","size":45500,"stargazers_count":10,"watchers_count":10,"language":"C++","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":20,"mirror_url":null,"open_issues_count":19,"forks":20,"open_issues":19,"watchers":10,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/01org/parameter-framework/pulls/144"},"html":{"href":"https://github.com/01org/parameter-framework/pull/144"},"issue":{"href":"https://api.github.com/repos/01org/parameter-framework/issues/144"},"comments":{"href":"https://api.github.com/repos/01org/parameter-framework/issues/144/comments"},"review_comments":{"href":"https://api.github.com/repos/01org/parameter-framework/pulls/144/comments"},"review_comment":{"href":"https://api.github.com/repos/01org/parameter-framework/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/01org/parameter-framework/pulls/144/commits"},"statuses":{"href":"https://api.github.com/repos/01org/parameter-framework/statuses/556c345e77a36cdbd4b87a03893e0c911a7e938e"}}}}