public inbox for gcc-patches@gcc.gnu.org
 help / color / mirror / Atom feed
* [PATCH] libcpp: add examples to source_location description
@ 2015-11-10 16:26 David Malcolm
  2015-11-10 21:18 ` Jeff Law
  0 siblings, 1 reply; 2+ messages in thread
From: David Malcolm @ 2015-11-10 16:26 UTC (permalink / raw)
  To: gcc-patches; +Cc: David Malcolm

This is a followup to:
  [PATCH 10/10] Compress short ranges into source_location
which adds some worked examples of what a source_location/location_t
can encode.

Successfully bootstrapped&regrtested on x86_64-pc-linux-gnu
(although it only touches a comment).

OK for trunk?

libcpp/ChangeLog:
	* include/line-map.h (source_location): Add worked examples of
	location encoding to the leading commment.
---
 libcpp/include/line-map.h | 97 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 95 insertions(+), 2 deletions(-)

diff --git a/libcpp/include/line-map.h b/libcpp/include/line-map.h
index 36247b2..e7169af 100644
--- a/libcpp/include/line-map.h
+++ b/libcpp/include/line-map.h
@@ -163,8 +163,101 @@ typedef unsigned int linenum_type;
   0xffffffff | UINT_MAX                      |
   -----------+-------------------------------+-------------------------------
 
-  To see how this works in practice, see the worked example in
-  libcpp/location-example.txt.  */
+   Examples of location encoding.
+
+   Packed ranges
+   =============
+
+   Consider encoding the location of a token "foo", seen underlined here
+   on line 523, within an ordinary line_map that starts at line 500:
+
+                 11111111112
+        12345678901234567890
+     522
+     523   return foo + bar;
+                  ^~~
+     524
+
+   The location's caret and start are both at line 523, column 11; the
+   location's finish is on the same line, at column 13 (an offset of 2
+   columns, for length 3).
+
+   Line 523 is offset 23 from the starting line of the ordinary line_map.
+
+   caret == start, and the offset of the finish fits within 5 bits, so
+   this can be stored as a packed range.
+
+   This is encoded as:
+      ordmap->start
+         + (line_offset << ordmap->m_column_and_range_bits)
+         + (column << ordmap->m_range_bits)
+         + (range_offset);
+   i.e. (for line offset 23, column 11, range offset 2):
+      ordmap->start
+         + (23 << 12)
+         + (11 << 5)
+         + 2;
+   i.e.:
+      ordmap->start + 0x17162
+   assuming that the line_map uses the default of 7 bits for columns and
+   5 bits for packed range (giving 12 bits for m_column_and_range_bits).
+
+
+   "Pure" locations
+   ================
+
+   These are a special case of the above, where
+      caret == start == finish
+   They are stored as packed ranges with offset == 0.
+   For example, the location of the "f" of "foo" could be stored
+   as above, but with range offset 0, giving:
+      ordmap->start
+         + (23 << 12)
+         + (11 << 5)
+         + 0;
+   i.e.:
+      ordmap->start + 0x17160
+
+
+   Unoptimized ranges
+   ==================
+
+   Consider encoding the location of the binary expression
+   below:
+
+                 11111111112
+        12345678901234567890
+     521
+     523   return foo + bar;
+                  ~~~~^~~~~
+     523
+
+   The location's caret is at the "+", line 523 column 15, but starts
+   earlier, at the "f" of "foo" at column 11.  The finish is at the "r"
+   of "bar" at column 19.
+
+   This can't be stored as a packed range since start != caret.
+   Hence it is stored as an ad-hoc location e.g. 0x80000003.
+
+   Stripping off the top bit gives us an index into the ad-hoc
+   lookaside table:
+
+     line_table->location_adhoc_data_map.data[0x3]
+
+   from which the caret, start and finish can be looked up,
+   encoded as "pure" locations:
+
+     start  == ordmap->start + (23 << 12) + (11 << 5)
+            == ordmap->start + 0x17160  (as above; the "f" of "foo")
+
+     caret  == ordmap->start + (23 << 12) + (15 << 5)
+            == ordmap->start + 0x171e0
+
+     finish == ordmap->start + (23 << 12) + (19 << 5)
+            == ordmap->start + 0x17260
+
+   To further see how source_location works in practice, see the
+   worked example in libcpp/location-example.txt.  */
 typedef unsigned int source_location;
 
 /* A range of source locations.
-- 
1.8.5.3

^ permalink raw reply	[flat|nested] 2+ messages in thread

* Re: [PATCH] libcpp: add examples to source_location description
  2015-11-10 16:26 [PATCH] libcpp: add examples to source_location description David Malcolm
@ 2015-11-10 21:18 ` Jeff Law
  0 siblings, 0 replies; 2+ messages in thread
From: Jeff Law @ 2015-11-10 21:18 UTC (permalink / raw)
  To: David Malcolm, gcc-patches

On 11/10/2015 09:44 AM, David Malcolm wrote:
> This is a followup to:
>    [PATCH 10/10] Compress short ranges into source_location
> which adds some worked examples of what a source_location/location_t
> can encode.
>
> Successfully bootstrapped&regrtested on x86_64-pc-linux-gnu
> (although it only touches a comment).
>
> OK for trunk?
>
> libcpp/ChangeLog:
> 	* include/line-map.h (source_location): Add worked examples of
> 	location encoding to the leading commment.
OK.
jeff

^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2015-11-10 21:18 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-11-10 16:26 [PATCH] libcpp: add examples to source_location description David Malcolm
2015-11-10 21:18 ` Jeff Law

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).