Initial draft of PNaCl bitcode files.

Initial draft of PNaCl bitcode files.

Focus of this CL is on the PNaCl records that can appear in bitcode files.
A subsequent CL will add how the records are converted to bitcode sequences.

Replaces CL: https://codereview.chromium.org/364463002

BUG=None
NOTRY=True
(documentation only change).

Committed: https://crrev.com/bc6ae6ad2abb98a9d6e01c9545ea162fcd938eb0
Cr-Commit-Position: refs/heads/master@{#305041}

[Karl, 2014-11-14 23:39:35]

kschimpf@google.com changed reviewers:
+ jfb@chromium.org, jvoung@chromium.org, sbc@google.com, stichnot@chromium.org

[Karl, 2014-11-14 23:41:39]

I have cleaned up this document based on feedback. I would like to try and get
this document committed so that others can see it. If possible, please review
this with to respect to getting this document visible in our documentation for
PNaCl.

Thanks.

[Jim Stichnoth, 2014-11-17 18:54:56]

Early auto-spellcheck pass. :)

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
File native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst (right):

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:870: The block
``ID`` value is dependent on the name ``N``. Valid names and corresponding
Find all 80-char violations:
  grep -n '^.\{81\}' pnacl-bitcode-manual.rst

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:1983: sequence of
ANSCII characters ``B1`` through ``BN``.
ASCII

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:3099: the bitwidth
of the integer result.
Could you make this "bit width" or "bit-width", here and below?

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:5034: ord    7
Ordered (no nans)
For these two lines, maybe write "NaNs" instead of "nans"?

[Karl, 2014-11-17 20:17:28]

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
File native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst (right):

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:870: The block
``ID`` value is dependent on the name ``N``. Valid names and corresponding
On 2014/11/17 18:54:56, stichnot wrote:
> Find all 80-char violations:
>   grep -n '^.\{81\}' pnacl-bitcode-manual.rst

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:1983: sequence of
ANSCII characters ``B1`` through ``BN``.
On 2014/11/17 18:54:56, stichnot wrote:
> ASCII

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:3099: the bitwidth
of the integer result.
On 2014/11/17 18:54:55, stichnot wrote:
> Could you make this "bit width" or "bit-width", here and below?

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:5034: ord    7
Ordered (no nans)
On 2014/11/17 18:54:56, stichnot wrote:
> For these two lines, maybe write "NaNs" instead of "nans"?

Done.

[Jim Stichnoth, 2014-11-18 02:24:43]

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
File native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst (right):

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:121: global
addresses of global variables and constants used by the program. It
"global addresses of global variables" - is the first "global" supposed to be
there?

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:231: particular,
function type signatures, call instructions, phi nodes, switch
phi instructions? (instead of nodes)

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:237: The ``PNaCl
bitstream writer``, which converts records to bit sequences, does
The `` `` formatting doesn't look right in the html file.  Should it be *...* ?

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:241: level, one
important aspect of this appears in ::ref:`block
::ref: ==> :ref:

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:264: abbreviation.
Note: User defined abbreviations are also encoded as records,
"User defined" ==> "User-defined"

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:322:
translator<link_for_pnacl_translator>`, and downloaded from the cloud.
"the cloud"? yuck...

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:383: subsection
defines a syntax rule for the construct. The **Record** subsection
I think most instances of "subsection" can be changed to "section", because the
word subsection is a bit clumsy and section nesting levels are probably hard to
discern in the formatted online docs.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:408: Within a
syntax rule, lowercase characters are literal values. Sequences of
"lower case" for consistency with other uses, including "upper case"

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:423: abbreviation.
Otherwise the corresponding default abbreviation (3) is used.
Can you briefly where the "3" comes from?  E.g.

  default abbreviation (which happens to be 3 for the add instruction)

(or whatever the actual explanation is)

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:591: is a
branch/return instruction.
What about unreachable?  That's kind of distinct from branch and return.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:762: NumBasicBlocks
< ExpectedBasicBlocks
Maybe this paragraph should have some special formatting, like Courier?

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:773: 
Remove this blank line for consistency

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:775: 
Remove this blank line

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:986: Notationally,
Array(EM) encloses the encoding EM, and must appear at the end of
Should Array(EM) be formatted consistently with ``array(EM), array and EM`` in
the next line?

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:1178: **Updates**:
::

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:1807: **Updates**:
::

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:2237: it to define
them once, before instructions. A constants block can only appear
is to define

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:2538:
record<link_for_basic_blocks_count>`. Each ::ref::`terminator
::ref:: ==> :ref: (I think)

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:3623: integral type
``i1``) is disallowed.
Hmm, the html version says "integrl" here, so I guess they are out of sync?

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:3786: The truth
table used for the *or* instruction is:
xor

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:4903: The
comparison instructions compares values returns a boolean (i1) result for
... compare ...
... and return ...

[Karl, 2014-11-19 20:28:53]

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
File native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst (right):

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:121: global
addresses of global variables and constants used by the program. It
On 2014/11/18 02:24:42, stichnot wrote:
> "global addresses of global variables" - is the first "global" supposed to be
> there?

Yes. All global variables and addresses must appear in this block. However, this
doesn't appear to be the right place to bring this up. This is a high-level
overview. Details should be further down.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:231: particular,
function type signatures, call instructions, phi nodes, switch
On 2014/11/18 02:24:42, stichnot wrote:
> phi instructions? (instead of nodes)

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:237: The ``PNaCl
bitstream writer``, which converts records to bit sequences, does
On 2014/11/18 02:24:43, stichnot wrote:
> The `` `` formatting doesn't look right in the html file.  Should it be *...*
?

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:241: level, one
important aspect of this appears in ::ref:`block
On 2014/11/18 02:24:42, stichnot wrote:
> ::ref: ==> :ref:

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:264: abbreviation.
Note: User defined abbreviations are also encoded as records,
On 2014/11/18 02:24:42, stichnot wrote:
> "User defined" ==> "User-defined"

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:322:
translator<link_for_pnacl_translator>`, and downloaded from the cloud.
On 2014/11/18 02:24:42, stichnot wrote:
> "the cloud"? yuck...

How about simply "when downloaded into Chrome".

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:383: subsection
defines a syntax rule for the construct. The **Record** subsection
On 2014/11/18 02:24:42, stichnot wrote:
> I think most instances of "subsection" can be changed to "section", because
the
> word subsection is a bit clumsy and section nesting levels are probably hard
to
> discern in the formatted online docs.

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:408: Within a
syntax rule, lowercase characters are literal values. Sequences of
On 2014/11/18 02:24:42, stichnot wrote:
> "lower case" for consistency with other uses, including "upper case"

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:423: abbreviation.
Otherwise the corresponding default abbreviation (3) is used.
On 2014/11/18 02:24:42, stichnot wrote:
> Can you briefly where the "3" comes from?  E.g.
> 
>   default abbreviation (which happens to be 3 for the add instruction)
> 
> (or whatever the actual explanation is)

Replaces with reference to "default abbreviation index", and did not bother with
actual value (which is defined at the reference as 3).

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:591: is a
branch/return instruction.
On 2014/11/18 02:24:42, stichnot wrote:
> What about unreachable?  That's kind of distinct from branch and return.

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:762: NumBasicBlocks
< ExpectedBasicBlocks
On 2014/11/18 02:24:42, stichnot wrote:
> Maybe this paragraph should have some special formatting, like Courier?

Oops, I forgot the "::" after "That is". Fixing.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:773: 
On 2014/11/18 02:24:42, stichnot wrote:
> Remove this blank line for consistency

Actually, the consistent form is to leave a blank line between each (labeled)
case.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:775: 
On 2014/11/18 02:24:42, stichnot wrote:
> Remove this blank line

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:986: Notationally,
Array(EM) encloses the encoding EM, and must appear at the end of
On 2014/11/18 02:24:42, stichnot wrote:
> Should Array(EM) be formatted consistently with ``array(EM), array and EM`` in
> the next line?

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:1178: **Updates**:
On 2014/11/18 02:24:43, stichnot wrote:
> ::

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:1807: **Updates**:
On 2014/11/18 02:24:42, stichnot wrote:
> ::

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:2237: it to define
them once, before instructions. A constants block can only appear
On 2014/11/18 02:24:42, stichnot wrote:
> is to define

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:2538:
record<link_for_basic_blocks_count>`. Each ::ref::`terminator
On 2014/11/18 02:24:43, stichnot wrote:
> ::ref:: ==> :ref: (I think)

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:3623: integral type
``i1``) is disallowed.
On 2014/11/18 02:24:42, stichnot wrote:
> Hmm, the html version says "integrl" here, so I guess they are out of sync?

Will regenerate to verify.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:3786: The truth
table used for the *or* instruction is:
On 2014/11/18 02:24:42, stichnot wrote:
> xor

Done.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:4903: The
comparison instructions compares values returns a boolean (i1) result for
On 2014/11/18 02:24:42, stichnot wrote:
> ... compare ...
> ... and return ...

Done.

[Jim Stichnoth, 2014-11-19 21:12:01]

This version lgtm with respect to the goal of getting a reasonable reference out
there that partners can develop against.  Ideally, I think maybe there would be
a gentle intro / light tutorial followed by a deep dive, or something like that,
but I think it's more important not to spend weeks bikeshedding on these things.

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
File native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst (right):

https://codereview.chromium.org/725333002/diff/1/native_client_sdk/src/doc/re...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:121: global
addresses of global variables and constants used by the program. It
On 2014/11/19 20:28:53, Karl wrote:
> On 2014/11/18 02:24:42, stichnot wrote:
> > "global addresses of global variables" - is the first "global" supposed to
be
> > there?
> 
> Yes. All global variables and addresses must appear in this block. However,
this
> doesn't appear to be the right place to bring this up. This is a high-level
> overview. Details should be further down.

Per our offline discussion, I think we both agree this should read "the set of
addresses of global variables".

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
File native_client_sdk/src/doc/devguide/devcycle/building.rst (right):

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/devguide/devcycle/building.rst:141: pnacl-abicheck
Should the tool names be formatted in Courier?

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/devguide/devcycle/building.rst:146: Objdumper for
PNaCl bitcode files.
Change to Object dumper?

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/devguide/devcycle/building.rst:373: Objumping PNaCl
Bitcode files
Same comment about "objdump".

Also, I think bitcode shouldn't be capitalized, for consistency with the rest of
the section names in this document.  (But note that the bitcode manual document
does consistently capitalize most words in the section names.)

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/devguide/devcycle/building.rst:376: Sometimes you may
be interesting in the contents of a PNaCl bitcode
interested

Reformat with fill-column-80

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
File native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst (right):

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:229: While most
records (for a given record code) have the same length, it
Reformat with fill-column=80

[Karl, 2014-11-20 17:05:07]

The CQ bit was checked by kschimpf@google.com

[Karl, 2014-11-20 17:05:33]

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
File native_client_sdk/src/doc/devguide/devcycle/building.rst (right):

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/devguide/devcycle/building.rst:141: pnacl-abicheck
On 2014/11/19 21:12:00, stichnot wrote:
> Should the tool names be formatted in Courier?

Done.

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/devguide/devcycle/building.rst:146: Objdumper for
PNaCl bitcode files.
On 2014/11/19 21:12:00, stichnot wrote:
> Change to Object dumper?

Done.

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/devguide/devcycle/building.rst:373: Objumping PNaCl
Bitcode files
On 2014/11/19 21:12:00, stichnot wrote:
> Same comment about "objdump".
> 
> Also, I think bitcode shouldn't be capitalized, for consistency with the rest
of
> the section names in this document.  (But note that the bitcode manual
document
> does consistently capitalize most words in the section names.)

Done.

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/devguide/devcycle/building.rst:376: Sometimes you may
be interesting in the contents of a PNaCl bitcode
On 2014/11/19 21:12:00, stichnot wrote:
> interested
> 
> Reformat with fill-column-80

Done.

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/devguide/devcycle/building.rst:377: file.  The tool
``pnacl-bcdis`` objdumps the contents of a PNaCl
Also replaced "objdumps" with "object dumps".

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
File native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst (right):

https://codereview.chromium.org/725333002/diff/40001/native_client_sdk/src/do...
native_client_sdk/src/doc/reference/pnacl-bitcode-manual.rst:229: While most
records (for a given record code) have the same length, it
On 2014/11/19 21:12:01, stichnot wrote:
> Reformat with fill-column=80

Done.

[commit-bot: I haz the power, 2014-11-20 17:06:34]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/725333002/60001

[commit-bot: I haz the power, 2014-11-20 17:06:37]

The CQ bit was unchecked by commit-bot@chromium.org

[commit-bot: I haz the power, 2014-11-20 17:06:38]

No LGTM from a valid reviewer yet. Only full committers are accepted.
Even if an LGTM may have been provided, it was from a non-committer,
_not_ a full super star committer.
See http://www.chromium.org/getting-involved/become-a-committer
Note that this has nothing to do with OWNERS files.

[Sam Clegg, 2014-11-20 18:07:13]

sbc@chromium.org changed reviewers:
+ sbc@chromium.org

[Sam Clegg, 2014-11-20 18:07:14]

lgtm

[Karl, 2014-11-20 18:33:07]

The CQ bit was checked by kschimpf@google.com

[commit-bot: I haz the power, 2014-11-20 18:34:54]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/725333002/60001

[commit-bot: I haz the power, 2014-11-20 18:36:18]

Committed patchset #4 (id:60001)

[commit-bot: I haz the power, 2014-11-20 18:37:11]

Patchset 4 (id:??) landed as
https://crrev.com/bc6ae6ad2abb98a9d6e01c9545ea162fcd938eb0
Cr-Commit-Position: refs/heads/master@{#305041}