[docs] Only LLVM IR bitstreams begin with 'BC'

[modocache]

Summary

The LLVM Bitcode File Format documentation states that all bitstreams
begin with the magic number 'BC', and that generic bitstream analyzer
tools may check for this number in order to determine whether the
stream is a bitstream.

However, in practice:

• Only LLVM IR bitcode begins with 'BC'. Other bitstreams -- Clang AST files and precompiled headers, Clang serialized diagnostics, Swift modules -- do not start with 'BC'. A tool that actually checked for 'BC' would only be able to recognize LLVM IR.
• The llvm-bcanalyzer, arguably the most used generic bitstream analyzer tool, does not check for a magic number 'BC' (except to determine whether the file is LLVM IR).

Update the bitcode format documentation to make it clear that not all
bitstreams begin with 'BC', and that tools should not rely on that
particular magic number value.

Test Plan:
Build the docs-llvm-html target and confirm the changes render in
a Safari web browser.

[angerman]

LGTM. I still can't shake the feeling that this just happened organically, and that Bitcode file should have the BC magic number and containers their own.

@modocache thanks for bringing the document in sync with what's actually being used!

[modocache]

Yup, I totally agree, it would have been nice if in practice 'BC' was used by all LLVM IR bitstream formats. I wonder if it would possible, one day, to change the magic numbers for the major formats from Clang (and Swift) such that they do begin with 'BC'? Or are there too many clients that rely on the existing magic numbers? For example, does Apple's Xcode parse the magic numbers for serialized diagnostics somehow?

For now, though, I think this change makes the docs more accurate, and so I'll land this. Thanks for the review!

llvm/trunk/docs/BitCodeFormat.rst

 used to dump and inspect arbitrary bitstreams, which is very useful for
 understanding the encoding.
 
 .. _magic number:
 
 Magic Numbers
 -------------
 
-The first two bytes of a bitcode file are 'BC' (``0x42``, ``0x43``).  The second
-two bytes are an application-specific magic number.  Generic bitcode tools can
-look at only the first two bytes to verify the file is bitcode, while
-application-specific programs will want to look at all four.
+The first four bytes of a bitstream are used as an application-specific magic
+number.  Generic bitcode tools may look at the first four bytes to determine
+whether the stream is a known stream type.  However, these tools should *not*
+determine whether a bitstream is valid based on its magic number alone.  New
+application-specific bitstream formats are being developed all the time; tools
+should not reject them just because they have a hitherto unseen magic number.
 
 .. _primitives:
 
 Primitives
 ----------
 
 A bitstream literally consists of a stream of bits, which are read in order
 starting with the least significant bit of each byte.  The stream is made up of

 ------
 
 LLVM IR Magic Number
 ^^^^^^^^^^^^^^^^^^^^
 
 The magic number for LLVM IR files is:
 
 :raw-html:`<tt><blockquote>`
-[0x0\ :sub:`4`, 0xC\ :sub:`4`, 0xE\ :sub:`4`, 0xD\ :sub:`4`]
+['B'\ :sub:`8`, 'C'\ :sub:`8`, 0x0\ :sub:`4`, 0xC\ :sub:`4`, 0xE\ :sub:`4`, 0xD\ :sub:`4`]
 :raw-html:`</blockquote></tt>`
 
-When combined with the bitcode magic number and viewed as bytes, this is
-``"BC 0xC0DE"``.
-
 .. _Signed VBRs:
 
 Signed VBRs
 ^^^^^^^^^^^
 
 `Variable Width Integer`_ encoding is an efficient way to encode arbitrary sized
 unsigned values, but is an extremely inefficient for encoding signed values, as
 signed values are otherwise treated as maximally large unsigned values.