libcpp: Improvements to comments in line-map.h/c

libcpp/ChangeLog:
	* include/line-map.h: Fix comment at the top of the file.
	(source_location): Rewrite and expand the comment for this
	typedef, adding an ascii-art table to clarify how source_location
	values are allocated.
	* line-map.c: Fix comment at the top of the file.

From-SVN: r222806

diff --git a/libcpp/ChangeLog b/libcpp/ChangeLog
index 7f6603d0842289ecbe700335dca21da82e2a88d9..ba386de280720baa7274ab584b7d42c9dc0c0f27 100644 (file)
--- a/libcpp/ChangeLog
+++ b/libcpp/ChangeLog
@@ -1,3 +1,11 @@
+2015-05-05  David Malcolm  <dmalcolm@redhat.com>
+
+       * include/line-map.h: Fix comment at the top of the file.
+       (source_location): Rewrite and expand the comment for this
+       typedef, adding an ascii-art table to clarify how source_location
+       values are allocated.
+       * line-map.c: Fix comment at the top of the file.
+
 2015-04-09  Richard Biener  <rguenther@suse.de>
 
        PR pch/65550

diff --git a/libcpp/include/line-map.h b/libcpp/include/line-map.h
index 403d79800edeeeff72c0918addbc702834222b51..e1681ea591d91ec59f07f7d5897974243569e448 100644 (file)
--- a/libcpp/include/line-map.h
+++ b/libcpp/include/line-map.h
@@ -1,4 +1,4 @@
-/* Map logical line numbers to (source file, line number) pairs.
+/* Map (unsigned int) keys to (source file, line, column) triples.
    Copyright (C) 2001-2015 Free Software Foundation, Inc.
 
 This program is free software; you can redistribute it and/or modify it
@@ -46,7 +46,74 @@ enum lc_reason
 /* The type of line numbers.  */
 typedef unsigned int linenum_type;
 
-/* A logical line/column number, i.e. an "index" into a line_map.  */
+/* The typedef "source_location" is a key within the location database,
+   identifying a source location or macro expansion.
+
+   This key only has meaning in relation to a line_maps instance.  Within
+   gcc there is a single line_maps instance: "line_table", declared in
+   gcc/input.h and defined in gcc/input.c.
+
+   The values of the keys are intended to be internal to libcpp,
+   but for ease-of-understanding the implementation, they are currently
+   assigned as follows:
+
+  Actual     | Value                         | Meaning
+  -----------+-------------------------------+-------------------------------
+  0x00000000 |                               | Reserved for use by libcpp
+  0x00000001 | RESERVED_LOCATION_COUNT - 1   | Reserved for use by libcpp
+  -----------+-------------------------------+-------------------------------
+  0x00000002 | RESERVED_LOCATION_COUNT       | The first location to be
+             | (also                         | handed out, and the
+             |  ordmap[0]->start_location)   | first line in ordmap 0
+  -----------+-------------------------------+-------------------------------
+             | ordmap[1]->start_location     | First line in ordmap 1
+             | ordmap[1]->start_location+1   | First column in that line
+             | ordmap[1]->start_location+2   | 2nd column in that line
+             |                               | Subsequent lines are offset by
+             |                               | (1 << column_bits),
+             |                               | e.g. 128 for 7 bits, with a
+             |                               | column value of 0 representing
+             |                               | "the whole line".
+             | ordmap[2]->start_location-1   | Final location in ordmap 1
+  -----------+-------------------------------+-------------------------------
+             | ordmap[2]->start_location     | First line in ordmap 2
+             | ordmap[3]->start_location-1   | Final location in ordmap 2
+  -----------+-------------------------------+-------------------------------
+             |                               | (etc)
+  -----------+-------------------------------+-------------------------------
+             | ordmap[n-1]->start_location   | First line in final ord map
+             |                               | (etc)
+             | set->highest_location - 1     | Final location in that ordmap
+  -----------+-------------------------------+-------------------------------
+             | set->highest_location         | Location of the where the next
+             |                               | ordinary linemap would start
+  -----------+-------------------------------+-------------------------------
+             |                               |
+             |                  VVVVVVVVVVVVVVVVVVVVVVVVVVV
+             |                  Ordinary maps grow this way
+             |
+             |                    (unallocated integers)
+             |
+             |                   Macro maps grow this way
+             |                   ^^^^^^^^^^^^^^^^^^^^^^^^
+             |                               |
+  -----------+-------------------------------+-------------------------------
+             | LINEMAPS_MACRO_LOWEST_LOCATION| Locations within macro maps
+             | macromap[m-1]->start_location | Start of last macro map
+             |                               |
+  -----------+-------------------------------+-------------------------------
+             | macromap[m-2]->start_location | Start of penultimate macro map
+  -----------+-------------------------------+-------------------------------
+             | macromap[1]->start_location   | Start of macro map 1
+  -----------+-------------------------------+-------------------------------
+             | macromap[0]->start_location   | Start of macro map 0
+  0x7fffffff | MAX_SOURCE_LOCATION           |
+  -----------+-------------------------------+-------------------------------
+  0x80000000 | Start of ad-hoc values        |
+  ...        |                               |
+  0xffffffff | UINT_MAX                      |
+  -----------+-------------------------------+-------------------------------
+  .  */
 typedef unsigned int source_location;
 
 /* Memory allocation function typedef.  Works like xrealloc.  */

diff --git a/libcpp/line-map.c b/libcpp/line-map.c
index f9260d00008988a5b5f6b23e03f8f9abd61edd16..1db59a7ce45e2aa29dd626934f56a4c01b4d08d6 100644 (file)
--- a/libcpp/line-map.c
+++ b/libcpp/line-map.c
@@ -1,4 +1,4 @@
-/* Map logical line numbers to (source file, line number) pairs.
+/* Map (unsigned int) keys to (source file, line, column) triples.
    Copyright (C) 2001-2015 Free Software Foundation, Inc.
 
 This program is free software; you can redistribute it and/or modify it