MySQL Bugs: #68868: Documentation for InnoDB tablespace flags for file format incorrect

Bug #68868	Documentation for InnoDB tablespace flags for file format incorrect
Submitted:	4 Apr 2013 21:08	Modified:	3 Jun 2013 15:27
Reporter:	Jeremy Cole (Basic Quality Contributor) (OCA)	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.5, 5.6	OS:	Any
Assigned to:	Bugs System	CPU Architecture:	Any

Description:
The MySQL 5.5 (and 5.6) documentation says, in "Identifying the File Format in Use" (http://dev.mysql.com/doc/refman/5.5/en/innodb-file-format-identifying.html):

"... Otherwise, the least significant bit should be set in the tablespace flags, and the file format identifier is
written in the bits 5 through 11. ..."

This is incorrect for any version due to a bug in how the tablespace flags were stored (which caused only 1 bit to be reserved, rather than 6). While this has been fixed (and rewritten) in MySQL 5.6, the documentation is incorrect for both 5.5 and 5.6 now. Additionally, the extremely confusing and misleading code has been left in 5.5 untouched, which is unfortunate.

How to repeat:
N/A. The relevant code is in storage/innobase/include/dict0mem.h specifically DICT_TF_FORMAT_MASK.

Suggested fix:
Describe the actual storage of file format identifier (1 bit) for 5.5. Describe the new storage layout in 5.6 for 5.6.

I wrote a somewhat more complete description here:

http://blog.jcole.us/2013/04/04/how-innodb-accidentally-reserved-only-1-bit-for-table-form...

Thank you for the bug report.

Even though the code in version 5.1 and 5.5 seems to pack other information after bit 6 of this table flag, that is only done in a flag stored in memory.  Any future version of InnoDB that may have expanded the file format to use more than one bit could have been done because only 6 bits were ever written to disk.  This kind of flags is written to the SYS_TABLES system table and to the header of each tablespace.  But the flag written to disk in either place was always padded with zeros after the initial 6 bits, so the documentation describing future possibilities of using more bits to describe any future file format was not incorrect.

However, in version 5.6, the plans have changed.  All of this code related to table flags has been reworked to make it more descriptive and easier to follow. In addition, there is now a clear distinction between table flags and tablespace flags.  Both of these types of flags have been expanded.  And neither one reserve bits 7 - 11 for a 'file format'.  So the 5.6 documentation should be fixed on this point.

The 5.5, 5.6, and 5.7 reference manuals have been revised with new tablespace flag and table flag content. Content will appear in the next documentation build on the following pages: 

http://dev.mysql.com/doc/refman/5.5/en/innodb-file-format-identifying.html
http://dev.mysql.com/doc/refman/5.6/en/innodb-file-format-identifying.html
http://dev.mysql.com/doc/refman/5.7/en/innodb-file-format-identifying.html

I truly fail to see any explanation of flags or anything about the bits interpretation on the (supposedly) fixed page https://dev.mysql.com/doc/refman/5.6/en/innodb-file-format-identifying.html