libcpp: Improvements to description of source_location in line-map.h

libcpp/ChangeLog:
	* include/line-map.h (source_location): In the table in the
	descriptive comment, show UNKNOWN_LOCATION, BUILTINS_LOCATION,
	LINE_MAP_MAX_LOCATION_WITH_COLS, LINE_MAP_MAX_SOURCE_LOCATION.
	Add notes about ad-hoc values.

From-SVN: r229673

libcpp/ChangeLog

+2015-11-02  David Malcolm  <dmalcolm@redhat.com>
+
+	* include/line-map.h (source_location): In the table in the
+	descriptive comment, show UNKNOWN_LOCATION, BUILTINS_LOCATION,
+	LINE_MAP_MAX_LOCATION_WITH_COLS, LINE_MAP_MAX_SOURCE_LOCATION.
+	Add notes about ad-hoc values.
+
 2015-10-21  Mikhail Maltsev  <maltsevm@gmail.com>
 
 	* include/line-map.h: Use CHECKING_P instead of ENABLE_CHECKING.

libcpp/include/line-map.h

@@ -59,8 +59,10 @@ typedef unsigned int linenum_type;
 
   Actual     | Value                         | Meaning
   -----------+-------------------------------+-------------------------------
-  0x00000000 |                               | Reserved for use by libcpp
-  0x00000001 | RESERVED_LOCATION_COUNT - 1   | Reserved for use by libcpp
+  0x00000000 | UNKNOWN_LOCATION (gcc/input.h)| Unknown/invalid location.
+  -----------+-------------------------------+-------------------------------
+  0x00000001 | BUILTINS_LOCATION             | The location for declarations
+             |   (gcc/input.h)               | in "<built-in>"
   -----------+-------------------------------+-------------------------------
   0x00000002 | RESERVED_LOCATION_COUNT       | The first location to be
              | (also                         | handed out, and the
@@ -94,6 +96,16 @@ typedef unsigned int linenum_type;
              |
              |                    (unallocated integers)
              |
+  0x60000000 | LINE_MAP_MAX_LOCATION_WITH_COLS
+             |   Beyond this point, ordinary linemaps have 0 bits per column:
+             |   each increment of the value corresponds to a new source line.
+             |
+  0x70000000 | LINE_MAP_MAX_SOURCE_LOCATION
+             |   Beyond the point, we give up on ordinary maps; attempts to
+             |   create locations in them lead to UNKNOWN_LOCATION (0).
+             |
+             |                    (unallocated integers)
+             |
              |                   Macro maps grow this way
              |                   ^^^^^^^^^^^^^^^^^^^^^^^^
              |                               |
@@ -107,10 +119,11 @@ typedef unsigned int linenum_type;
              | macromap[1]->start_location   | Start of macro map 1
   -----------+-------------------------------+-------------------------------
              | macromap[0]->start_location   | Start of macro map 0
-  0x7fffffff | MAX_SOURCE_LOCATION           |
+  0x7fffffff | MAX_SOURCE_LOCATION           | Also used as a mask for
+             |                               | accessing the ad-hoc data table
   -----------+-------------------------------+-------------------------------
-  0x80000000 | Start of ad-hoc values        |
-  ...        |                               |
+  0x80000000 | Start of ad-hoc values; the lower 31 bits are used as an index
+  ...        | into the line_table->location_adhoc_data_map.data array.
   0xffffffff | UINT_MAX                      |
   -----------+-------------------------------+-------------------------------