{"action":"created","comment":{"url":"https://api.github.com/repos/mundya/rig/pulls/comments/25423494","id":25423494,"diff_hunk":"@@ -0,0 +1,434 @@\n+.. py:module::rig.bitfield\n+.. py:class::rig.bitfield.BitField\n+\n+Defining bit fields with :py:class:`.BitField`\n+==============================================\n+\n+In many applications there is a need to define bit fields, for example when\n+defining SpiNNaker routing keys. Rig provides the class\n+:py:class:`rig.bitfield.BitField` which allows the definition of hierarchical\n+bit fields. A tutorial introduction to this class is provided below and is\n+followed by the full API documentation.\n+\n+Tutorial\n+--------\n+\n+In this tutorial we will tackle the commonly faced challenge of defining the\n+SpiNNaker routing keys. In SpiNNaker, routing keys are 32-bit values which are\n+used to uniquely identify multicast streams of packets flowing from one core to\n+many others. We'll walk through a few simple example scenarios and demonstrate\n+the key features of :py:class:`.BitField`\\ s.\n+\n+Defining a basic bit field\n+^^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+We'll start by defining a 32-bit bit field:\n+\n+.. doctest::\n+\n+    >>> from rig.bitfield import BitField\n+    >>> b = BitField(32)\n+    >>> b\n+    <32-bit BitField >\n+\n+Initially no fields are defined and so we must define some. Lets define the\n+following fields:\n+\n+`chip`\n+    Bits 31-16: The unique chip ID number of the chip which produced the packet.\n+`core`\n+    Bits 12-8: The core ID number of the core which produced the packet.\n+`type`\n+    Bits 7-0: Some application specific message-type indicator.\n+\n+These fields can be defined like so:\n+\n+.. doctest::\n+\n+    >>> b.add_field(\"chip\", length=16, start_at=16)\n+    >>> b.add_field(\"core\", length=5, start_at=8)\n+    >>> b.add_field(\"type\", length=8, start_at=0)\n+    >>> b\n+    <32-bit BitField 'chip':?, 'core':?, 'type':?>\n+\n+We can now specify the value of these fields to define a specific routing key:\n+\n+.. doctest::\n+\n+    >>> TYPE_START = 0x01\n+    >>> TYPE_STOP = 0x02\n+    >>> # ...\n+    \n+    >>> start_master = b(chip=1024, core=1, type=TYPE_START)\n+    >>> start_master\n+    <32-bit BitField 'chip':1024, 'core':1, 'type':1>\n+\n+Notice that a new :py:class:`.BitField` is produced but this one has its fields\n+allocated specific values.\n+\n+.. note::\n+    The newly created :py:class:`.BitField` is linked to the original\n+    :py:class:`.BitField`. Amongst other things this means that if new fields\n+    are added to the original, they will also appear in this bit field. The\n+    utility of this will become more apparent later.\n+\n+Since all the fields in `start_master` have been defined, we can use the","path":"docs/source/bitfield.rst","position":75,"original_position":75,"commit_id":"8a3335769ccf45ca882a906c862e5c1cc561f98f","original_commit_id":"8a3335769ccf45ca882a906c862e5c1cc561f98f","user":{"login":"mundya","id":3439837,"avatar_url":"https://avatars.githubusercontent.com/u/3439837?v=3","gravatar_id":"","url":"https://api.github.com/users/mundya","html_url":"https://github.com/mundya","followers_url":"https://api.github.com/users/mundya/followers","following_url":"https://api.github.com/users/mundya/following{/other_user}","gists_url":"https://api.github.com/users/mundya/gists{/gist_id}","starred_url":"https://api.github.com/users/mundya/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mundya/subscriptions","organizations_url":"https://api.github.com/users/mundya/orgs","repos_url":"https://api.github.com/users/mundya/repos","events_url":"https://api.github.com/users/mundya/events{/privacy}","received_events_url":"https://api.github.com/users/mundya/received_events","type":"User","site_admin":false},"body":"\"Since all the fields (and their lengths and positions)\"","created_at":"2015-02-26T12:34:27Z","updated_at":"2015-02-26T12:34:27Z","html_url":"https://github.com/mundya/rig/pull/27#discussion_r25423494","pull_request_url":"https://api.github.com/repos/mundya/rig/pulls/27","_links":{"self":{"href":"https://api.github.com/repos/mundya/rig/pulls/comments/25423494"},"html":{"href":"https://github.com/mundya/rig/pull/27#discussion_r25423494"},"pull_request":{"href":"https://api.github.com/repos/mundya/rig/pulls/27"}}},"pull_request":{"url":"https://api.github.com/repos/mundya/rig/pulls/27","id":30063019,"html_url":"https://github.com/mundya/rig/pull/27","diff_url":"https://github.com/mundya/rig/pull/27.diff","patch_url":"https://github.com/mundya/rig/pull/27.patch","issue_url":"https://api.github.com/repos/mundya/rig/issues/27","number":27,"state":"open","locked":false,"title":"Rename Keyspace to BitField.","user":{"login":"mossblaser","id":193514,"avatar_url":"https://avatars.githubusercontent.com/u/193514?v=3","gravatar_id":"","url":"https://api.github.com/users/mossblaser","html_url":"https://github.com/mossblaser","followers_url":"https://api.github.com/users/mossblaser/followers","following_url":"https://api.github.com/users/mossblaser/following{/other_user}","gists_url":"https://api.github.com/users/mossblaser/gists{/gist_id}","starred_url":"https://api.github.com/users/mossblaser/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mossblaser/subscriptions","organizations_url":"https://api.github.com/users/mossblaser/orgs","repos_url":"https://api.github.com/users/mossblaser/repos","events_url":"https://api.github.com/users/mossblaser/events{/privacy}","received_events_url":"https://api.github.com/users/mossblaser/received_events","type":"User","site_admin":false},"body":"* Corrects issue #24.\r\n* Improves BitField documentation","created_at":"2015-02-26T09:47:28Z","updated_at":"2015-02-26T12:34:27Z","closed_at":null,"merged_at":null,"merge_commit_sha":"15a4e5b6af77b180cc01adcb242ad35cb24b8ffc","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/mundya/rig/pulls/27/commits","review_comments_url":"https://api.github.com/repos/mundya/rig/pulls/27/comments","review_comment_url":"https://api.github.com/repos/mundya/rig/pulls/comments{/number}","comments_url":"https://api.github.com/repos/mundya/rig/issues/27/comments","statuses_url":"https://api.github.com/repos/mundya/rig/statuses/8a3335769ccf45ca882a906c862e5c1cc561f98f","head":{"label":"mundya:rename_keyspace","ref":"rename_keyspace","sha":"8a3335769ccf45ca882a906c862e5c1cc561f98f","user":{"login":"mundya","id":3439837,"avatar_url":"https://avatars.githubusercontent.com/u/3439837?v=3","gravatar_id":"","url":"https://api.github.com/users/mundya","html_url":"https://github.com/mundya","followers_url":"https://api.github.com/users/mundya/followers","following_url":"https://api.github.com/users/mundya/following{/other_user}","gists_url":"https://api.github.com/users/mundya/gists{/gist_id}","starred_url":"https://api.github.com/users/mundya/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mundya/subscriptions","organizations_url":"https://api.github.com/users/mundya/orgs","repos_url":"https://api.github.com/users/mundya/repos","events_url":"https://api.github.com/users/mundya/events{/privacy}","received_events_url":"https://api.github.com/users/mundya/received_events","type":"User","site_admin":false},"repo":{"id":29497314,"name":"rig","full_name":"mundya/rig","owner":{"login":"mundya","id":3439837,"avatar_url":"https://avatars.githubusercontent.com/u/3439837?v=3","gravatar_id":"","url":"https://api.github.com/users/mundya","html_url":"https://github.com/mundya","followers_url":"https://api.github.com/users/mundya/followers","following_url":"https://api.github.com/users/mundya/following{/other_user}","gists_url":"https://api.github.com/users/mundya/gists{/gist_id}","starred_url":"https://api.github.com/users/mundya/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mundya/subscriptions","organizations_url":"https://api.github.com/users/mundya/orgs","repos_url":"https://api.github.com/users/mundya/repos","events_url":"https://api.github.com/users/mundya/events{/privacy}","received_events_url":"https://api.github.com/users/mundya/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/mundya/rig","description":"A set of tools for rigging SpiNNaker programs.","fork":false,"url":"https://api.github.com/repos/mundya/rig","forks_url":"https://api.github.com/repos/mundya/rig/forks","keys_url":"https://api.github.com/repos/mundya/rig/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mundya/rig/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mundya/rig/teams","hooks_url":"https://api.github.com/repos/mundya/rig/hooks","issue_events_url":"https://api.github.com/repos/mundya/rig/issues/events{/number}","events_url":"https://api.github.com/repos/mundya/rig/events","assignees_url":"https://api.github.com/repos/mundya/rig/assignees{/user}","branches_url":"https://api.github.com/repos/mundya/rig/branches{/branch}","tags_url":"https://api.github.com/repos/mundya/rig/tags","blobs_url":"https://api.github.com/repos/mundya/rig/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mundya/rig/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mundya/rig/git/refs{/sha}","trees_url":"https://api.github.com/repos/mundya/rig/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mundya/rig/statuses/{sha}","languages_url":"https://api.github.com/repos/mundya/rig/languages","stargazers_url":"https://api.github.com/repos/mundya/rig/stargazers","contributors_url":"https://api.github.com/repos/mundya/rig/contributors","subscribers_url":"https://api.github.com/repos/mundya/rig/subscribers","subscription_url":"https://api.github.com/repos/mundya/rig/subscription","commits_url":"https://api.github.com/repos/mundya/rig/commits{/sha}","git_commits_url":"https://api.github.com/repos/mundya/rig/git/commits{/sha}","comments_url":"https://api.github.com/repos/mundya/rig/comments{/number}","issue_comment_url":"https://api.github.com/repos/mundya/rig/issues/comments{/number}","contents_url":"https://api.github.com/repos/mundya/rig/contents/{+path}","compare_url":"https://api.github.com/repos/mundya/rig/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mundya/rig/merges","archive_url":"https://api.github.com/repos/mundya/rig/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mundya/rig/downloads","issues_url":"https://api.github.com/repos/mundya/rig/issues{/number}","pulls_url":"https://api.github.com/repos/mundya/rig/pulls{/number}","milestones_url":"https://api.github.com/repos/mundya/rig/milestones{/number}","notifications_url":"https://api.github.com/repos/mundya/rig/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mundya/rig/labels{/name}","releases_url":"https://api.github.com/repos/mundya/rig/releases{/id}","created_at":"2015-01-19T21:20:40Z","updated_at":"2015-02-25T12:55:07Z","pushed_at":"2015-02-26T10:05:19Z","git_url":"git://github.com/mundya/rig.git","ssh_url":"git@github.com:mundya/rig.git","clone_url":"https://github.com/mundya/rig.git","svn_url":"https://github.com/mundya/rig","homepage":"","size":728,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":7,"forks":0,"open_issues":7,"watchers":0,"default_branch":"master"}},"base":{"label":"mundya:master","ref":"master","sha":"ff2f4865e238d3c329d3157a08fb567fa4dc4246","user":{"login":"mundya","id":3439837,"avatar_url":"https://avatars.githubusercontent.com/u/3439837?v=3","gravatar_id":"","url":"https://api.github.com/users/mundya","html_url":"https://github.com/mundya","followers_url":"https://api.github.com/users/mundya/followers","following_url":"https://api.github.com/users/mundya/following{/other_user}","gists_url":"https://api.github.com/users/mundya/gists{/gist_id}","starred_url":"https://api.github.com/users/mundya/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mundya/subscriptions","organizations_url":"https://api.github.com/users/mundya/orgs","repos_url":"https://api.github.com/users/mundya/repos","events_url":"https://api.github.com/users/mundya/events{/privacy}","received_events_url":"https://api.github.com/users/mundya/received_events","type":"User","site_admin":false},"repo":{"id":29497314,"name":"rig","full_name":"mundya/rig","owner":{"login":"mundya","id":3439837,"avatar_url":"https://avatars.githubusercontent.com/u/3439837?v=3","gravatar_id":"","url":"https://api.github.com/users/mundya","html_url":"https://github.com/mundya","followers_url":"https://api.github.com/users/mundya/followers","following_url":"https://api.github.com/users/mundya/following{/other_user}","gists_url":"https://api.github.com/users/mundya/gists{/gist_id}","starred_url":"https://api.github.com/users/mundya/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mundya/subscriptions","organizations_url":"https://api.github.com/users/mundya/orgs","repos_url":"https://api.github.com/users/mundya/repos","events_url":"https://api.github.com/users/mundya/events{/privacy}","received_events_url":"https://api.github.com/users/mundya/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/mundya/rig","description":"A set of tools for rigging SpiNNaker programs.","fork":false,"url":"https://api.github.com/repos/mundya/rig","forks_url":"https://api.github.com/repos/mundya/rig/forks","keys_url":"https://api.github.com/repos/mundya/rig/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mundya/rig/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mundya/rig/teams","hooks_url":"https://api.github.com/repos/mundya/rig/hooks","issue_events_url":"https://api.github.com/repos/mundya/rig/issues/events{/number}","events_url":"https://api.github.com/repos/mundya/rig/events","assignees_url":"https://api.github.com/repos/mundya/rig/assignees{/user}","branches_url":"https://api.github.com/repos/mundya/rig/branches{/branch}","tags_url":"https://api.github.com/repos/mundya/rig/tags","blobs_url":"https://api.github.com/repos/mundya/rig/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mundya/rig/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mundya/rig/git/refs{/sha}","trees_url":"https://api.github.com/repos/mundya/rig/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mundya/rig/statuses/{sha}","languages_url":"https://api.github.com/repos/mundya/rig/languages","stargazers_url":"https://api.github.com/repos/mundya/rig/stargazers","contributors_url":"https://api.github.com/repos/mundya/rig/contributors","subscribers_url":"https://api.github.com/repos/mundya/rig/subscribers","subscription_url":"https://api.github.com/repos/mundya/rig/subscription","commits_url":"https://api.github.com/repos/mundya/rig/commits{/sha}","git_commits_url":"https://api.github.com/repos/mundya/rig/git/commits{/sha}","comments_url":"https://api.github.com/repos/mundya/rig/comments{/number}","issue_comment_url":"https://api.github.com/repos/mundya/rig/issues/comments{/number}","contents_url":"https://api.github.com/repos/mundya/rig/contents/{+path}","compare_url":"https://api.github.com/repos/mundya/rig/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mundya/rig/merges","archive_url":"https://api.github.com/repos/mundya/rig/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mundya/rig/downloads","issues_url":"https://api.github.com/repos/mundya/rig/issues{/number}","pulls_url":"https://api.github.com/repos/mundya/rig/pulls{/number}","milestones_url":"https://api.github.com/repos/mundya/rig/milestones{/number}","notifications_url":"https://api.github.com/repos/mundya/rig/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mundya/rig/labels{/name}","releases_url":"https://api.github.com/repos/mundya/rig/releases{/id}","created_at":"2015-01-19T21:20:40Z","updated_at":"2015-02-25T12:55:07Z","pushed_at":"2015-02-26T10:05:19Z","git_url":"git://github.com/mundya/rig.git","ssh_url":"git@github.com:mundya/rig.git","clone_url":"https://github.com/mundya/rig.git","svn_url":"https://github.com/mundya/rig","homepage":"","size":728,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":7,"forks":0,"open_issues":7,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/mundya/rig/pulls/27"},"html":{"href":"https://github.com/mundya/rig/pull/27"},"issue":{"href":"https://api.github.com/repos/mundya/rig/issues/27"},"comments":{"href":"https://api.github.com/repos/mundya/rig/issues/27/comments"},"review_comments":{"href":"https://api.github.com/repos/mundya/rig/pulls/27/comments"},"review_comment":{"href":"https://api.github.com/repos/mundya/rig/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/mundya/rig/pulls/27/commits"},"statuses":{"href":"https://api.github.com/repos/mundya/rig/statuses/8a3335769ccf45ca882a906c862e5c1cc561f98f"}}}}