2006-08-10 20:15:58 +00:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
|
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
|
|
|
<title>The Often Misunderstood GEP Instruction</title>
|
|
|
|
|
<link rel="stylesheet" href="llvm.css" type="text/css">
|
2006-08-10 21:01:14 +00:00
|
|
|
<style type="text/css">
|
|
|
|
|
TABLE { text-align: left; border: 1px solid black; border-collapse: collapse; margin: 0 0 0 0; }
|
|
|
|
|
</style>
|
2006-08-10 20:15:58 +00:00
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
<div class="doc_title">
|
|
|
|
|
The Often Misunderstood GEP Instruction
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<ol>
|
|
|
|
|
<li><a href="#intro">Introduction</a></li>
|
2010-02-25 18:16:03 +00:00
|
|
|
<li><a href="#addresses">Address Computation</a>
|
2006-08-10 20:15:58 +00:00
|
|
|
<ol>
|
|
|
|
|
<li><a href="#extra_index">Why is the extra 0 index required?</a></li>
|
|
|
|
|
<li><a href="#deref">What is dereferenced by GEP?</a></li>
|
|
|
|
|
<li><a href="#firstptr">Why can you index through the first pointer but not
|
|
|
|
|
subsequent ones?</a></li>
|
|
|
|
|
<li><a href="#lead0">Why don't GEP x,0,0,1 and GEP x,1 alias? </a></li>
|
|
|
|
|
<li><a href="#trail0">Why do GEP x,1,0,0 and GEP x,1 alias? </a></li>
|
2010-02-25 18:16:03 +00:00
|
|
|
<li><a href="#vectors">Can GEP index into vector elements?</a>
|
|
|
|
|
<li><a href="#unions">Can GEP index into unions?</a>
|
|
|
|
|
<li><a href="#addrspace">What effect do address spaces have on GEPs?</a>
|
|
|
|
|
<li><a href="#int">How is GEP different from ptrtoint, arithmetic, and inttoptr?</a></li>
|
|
|
|
|
<li><a href="#be">I'm writing a backend for a target which needs custom lowering for GEP. How do I do this?</a>
|
|
|
|
|
<li><a href="#vla">How does VLA addressing work with GEPs?</a>
|
|
|
|
|
</ol></li>
|
|
|
|
|
<li><a href="#rules">Rules</a>
|
|
|
|
|
<ol>
|
|
|
|
|
<li><a href="#bounds">What happens if an array index is out of bounds?</a>
|
|
|
|
|
<li><a href="#negative">Can array indices be negative?</a>
|
|
|
|
|
<li><a href="#compare">Can I compare two values computed with GEPs?</a>
|
|
|
|
|
<li><a href="#types">Can I do GEP with a different pointer type than the type of the underlying object?</a>
|
|
|
|
|
<li><a href="#null">Can I cast an object's address to integer and add it to null?</a>
|
|
|
|
|
<li><a href="#ptrdiff">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a>
|
|
|
|
|
<li><a href="#tbaa">Can I do type-based alias analysis on LLVM IR?</a>
|
|
|
|
|
<li><a href="#overflow">What happens if a GEP computation overflows?</a>
|
|
|
|
|
<li><a href="#check">How can I tell if my front-end is following the rules?</a>
|
|
|
|
|
</ol></li>
|
|
|
|
|
<li><a href="#rationale">Rationale</a>
|
|
|
|
|
<ol>
|
|
|
|
|
<li><a href="#goals">Why is GEP designed this way?</a></li>
|
|
|
|
|
<li><a href="#i32">Why do struct member indices always use i32?</a></li>
|
|
|
|
|
<li><a href="#uglygep">What's an uglygep?</a>
|
2006-08-10 20:15:58 +00:00
|
|
|
</ol></li>
|
|
|
|
|
<li><a href="#summary">Summary</a></li>
|
|
|
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
<div class="doc_author">
|
|
|
|
|
<p>Written by: <a href="mailto:rspencer@reidspencer.com">Reid Spencer</a>.</p>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_section"><a name="intro"><b>Introduction</b></a></div>
|
|
|
|
|
<!-- *********************************************************************** -->
|
2010-02-25 18:16:03 +00:00
|
|
|
|
2006-08-10 20:15:58 +00:00
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>This document seeks to dispel the mystery and confusion surrounding LLVM's
|
2010-07-06 15:26:33 +00:00
|
|
|
<a href="LangRef.html#i_getelementptr">GetElementPtr</a> (GEP) instruction.
|
|
|
|
|
Questions about the wily GEP instruction are
|
2009-10-12 14:46:08 +00:00
|
|
|
probably the most frequently occurring questions once a developer gets down to
|
2006-08-10 20:15:58 +00:00
|
|
|
coding with LLVM. Here we lay out the sources of confusion and show that the
|
|
|
|
|
GEP instruction is really quite simple.
|
|
|
|
|
</p>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
2010-02-25 18:16:03 +00:00
|
|
|
<div class="doc_section"><a name="addresses"><b>Address Computation</b></a></div>
|
2006-08-10 20:15:58 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>When people are first confronted with the GEP instruction, they tend to
|
|
|
|
|
relate it to known concepts from other programming paradigms, most notably C
|
2010-02-25 18:16:03 +00:00
|
|
|
array indexing and field selection. GEP closely resembles C array indexing
|
|
|
|
|
and field selection, however it's is a little different and this leads to
|
|
|
|
|
the following questions.</p>
|
2006-08-10 20:15:58 +00:00
|
|
|
</div>
|
|
|
|
|
|
2006-08-15 03:32:10 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="firstptr"><b>What is the first index of the GEP instruction?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
2006-08-15 03:43:31 +00:00
|
|
|
<p>Quick answer: The index stepping through the first operand.</p>
|
|
|
|
|
<p>The confusion with the first index usually arises from thinking about
|
|
|
|
|
the GetElementPtr instruction as if it was a C index operator. They aren't the
|
|
|
|
|
same. For example, when we write, in "C":</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
AType *Foo;
|
|
|
|
|
...
|
|
|
|
|
X = &Foo->F;
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-15 04:00:29 +00:00
|
|
|
<p>it is natural to think that there is only one index, the selection of the
|
|
|
|
|
field <tt>F</tt>. However, in this example, <tt>Foo</tt> is a pointer. That
|
2010-02-25 18:16:03 +00:00
|
|
|
pointer must be indexed explicitly in LLVM. C, on the other hand, indices
|
2006-08-15 08:14:19 +00:00
|
|
|
through it transparently. To arrive at the same address location as the C
|
2006-08-15 04:00:29 +00:00
|
|
|
code, you would provide the GEP instruction with two index operands. The
|
|
|
|
|
first operand indexes through the pointer; the second operand indexes the
|
|
|
|
|
field <tt>F</tt> of the structure, just as if you wrote:</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
X = &Foo[0].F;
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-15 03:43:31 +00:00
|
|
|
<p>Sometimes this question gets rephrased as:</p>
|
2006-08-17 03:26:50 +00:00
|
|
|
<blockquote><p><i>Why is it okay to index through the first pointer, but
|
|
|
|
|
subsequent pointers won't be dereferenced?</i></p></blockquote>
|
2006-08-15 03:32:10 +00:00
|
|
|
<p>The answer is simply because memory does not have to be accessed to
|
|
|
|
|
perform the computation. The first operand to the GEP instruction must be a
|
|
|
|
|
value of a pointer type. The value of the pointer is provided directly to
|
2006-08-15 03:57:05 +00:00
|
|
|
the GEP instruction as an operand without any need for accessing memory. It
|
|
|
|
|
must, therefore be indexed and requires an index operand. Consider this
|
|
|
|
|
example:</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
struct munger_struct {
|
|
|
|
|
int f1;
|
|
|
|
|
int f2;
|
|
|
|
|
};
|
|
|
|
|
void munge(struct munger_struct *P) {
|
|
|
|
|
P[0].f1 = P[1].f1 + P[2].f2;
|
|
|
|
|
}
|
|
|
|
|
...
|
|
|
|
|
munger_struct Array[3];
|
|
|
|
|
...
|
|
|
|
|
munge(Array);
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-15 03:32:10 +00:00
|
|
|
<p>In this "C" example, the front end compiler (llvm-gcc) will generate three
|
|
|
|
|
GEP instructions for the three indices through "P" in the assignment
|
|
|
|
|
statement. The function argument <tt>P</tt> will be the first operand of each
|
2006-08-16 05:53:32 +00:00
|
|
|
of these GEP instructions. The second operand indexes through that pointer.
|
|
|
|
|
The third operand will be the field offset into the
|
|
|
|
|
<tt>struct munger_struct</tt> type, for either the <tt>f1</tt> or
|
2006-08-15 03:32:10 +00:00
|
|
|
<tt>f2</tt> field. So, in LLVM assembly the <tt>munge</tt> function looks
|
|
|
|
|
like:</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
void %munge(%struct.munger_struct* %P) {
|
|
|
|
|
entry:
|
|
|
|
|
%tmp = getelementptr %struct.munger_struct* %P, i32 1, i32 0
|
|
|
|
|
%tmp = load i32* %tmp
|
|
|
|
|
%tmp6 = getelementptr %struct.munger_struct* %P, i32 2, i32 1
|
|
|
|
|
%tmp7 = load i32* %tmp6
|
|
|
|
|
%tmp8 = add i32 %tmp7, %tmp
|
|
|
|
|
%tmp9 = getelementptr %struct.munger_struct* %P, i32 0, i32 0
|
|
|
|
|
store i32 %tmp8, i32* %tmp9
|
|
|
|
|
ret void
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-15 03:32:10 +00:00
|
|
|
<p>In each case the first operand is the pointer through which the GEP
|
|
|
|
|
instruction starts. The same is true whether the first operand is an
|
|
|
|
|
argument, allocated memory, or a global variable. </p>
|
|
|
|
|
<p>To make this clear, let's consider a more obtuse example:</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
2010-02-25 18:16:03 +00:00
|
|
|
%MyVar = uninitialized global i32
|
2008-01-04 12:04:32 +00:00
|
|
|
...
|
|
|
|
|
%idx1 = getelementptr i32* %MyVar, i64 0
|
|
|
|
|
%idx2 = getelementptr i32* %MyVar, i64 1
|
|
|
|
|
%idx3 = getelementptr i32* %MyVar, i64 2
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-15 03:32:10 +00:00
|
|
|
<p>These GEP instructions are simply making address computations from the
|
|
|
|
|
base address of <tt>MyVar</tt>. They compute, as follows (using C syntax):
|
|
|
|
|
</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
idx1 = (char*) &MyVar + 0
|
|
|
|
|
idx2 = (char*) &MyVar + 4
|
|
|
|
|
idx3 = (char*) &MyVar + 8
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2007-02-09 17:56:02 +00:00
|
|
|
<p>Since the type <tt>i32</tt> is known to be four bytes long, the indices
|
2006-08-15 03:32:10 +00:00
|
|
|
0, 1 and 2 translate into memory offsets of 0, 4, and 8, respectively. No
|
|
|
|
|
memory is accessed to make these computations because the address of
|
|
|
|
|
<tt>%MyVar</tt> is passed directly to the GEP instructions.</p>
|
|
|
|
|
<p>The obtuse part of this example is in the cases of <tt>%idx2</tt> and
|
|
|
|
|
<tt>%idx3</tt>. They result in the computation of addresses that point to
|
|
|
|
|
memory past the end of the <tt>%MyVar</tt> global, which is only one
|
2007-02-09 17:56:02 +00:00
|
|
|
<tt>i32</tt> long, not three <tt>i32</tt>s long. While this is legal in LLVM,
|
2006-08-15 03:32:10 +00:00
|
|
|
it is inadvisable because any load or store with the pointer that results
|
|
|
|
|
from these GEP instructions would produce undefined results.</p>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-10 20:15:58 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="extra_index"><b>Why is the extra 0 index required?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>Quick answer: there are no superfluous indices.</p>
|
|
|
|
|
<p>This question arises most often when the GEP instruction is applied to a
|
|
|
|
|
global variable which is always a pointer type. For example, consider
|
2008-01-04 12:04:32 +00:00
|
|
|
this:</p>
|
|
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
%MyStruct = uninitialized global { float*, i32 }
|
|
|
|
|
...
|
|
|
|
|
%idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2007-02-09 17:56:02 +00:00
|
|
|
<p>The GEP above yields an <tt>i32*</tt> by indexing the <tt>i32</tt> typed
|
2006-08-10 20:15:58 +00:00
|
|
|
field of the structure <tt>%MyStruct</tt>. When people first look at it, they
|
2007-02-09 17:56:02 +00:00
|
|
|
wonder why the <tt>i64 0</tt> index is needed. However, a closer inspection
|
2006-08-15 03:32:10 +00:00
|
|
|
of how globals and GEPs work reveals the need. Becoming aware of the following
|
2010-02-25 18:16:03 +00:00
|
|
|
facts will dispel the confusion:</p>
|
2006-08-10 20:15:58 +00:00
|
|
|
<ol>
|
2007-02-09 17:56:02 +00:00
|
|
|
<li>The type of <tt>%MyStruct</tt> is <i>not</i> <tt>{ float*, i32 }</tt>
|
|
|
|
|
but rather <tt>{ float*, i32 }*</tt>. That is, <tt>%MyStruct</tt> is a
|
2006-08-10 20:15:58 +00:00
|
|
|
pointer to a structure containing a pointer to a <tt>float</tt> and an
|
2007-02-09 17:56:02 +00:00
|
|
|
<tt>i32</tt>.</li>
|
2006-08-10 20:15:58 +00:00
|
|
|
<li>Point #1 is evidenced by noticing the type of the first operand of
|
|
|
|
|
the GEP instruction (<tt>%MyStruct</tt>) which is
|
2007-02-09 17:56:02 +00:00
|
|
|
<tt>{ float*, i32 }*</tt>.</li>
|
|
|
|
|
<li>The first index, <tt>i64 0</tt> is required to step over the global
|
2006-08-15 03:32:10 +00:00
|
|
|
variable <tt>%MyStruct</tt>. Since the first argument to the GEP
|
|
|
|
|
instruction must always be a value of pointer type, the first index
|
|
|
|
|
steps through that pointer. A value of 0 means 0 elements offset from that
|
|
|
|
|
pointer.</li>
|
2007-02-09 17:56:02 +00:00
|
|
|
<li>The second index, <tt>i32 1</tt> selects the second field of the
|
|
|
|
|
structure (the <tt>i32</tt>). </li>
|
2006-08-10 20:15:58 +00:00
|
|
|
</ol>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="deref"><b>What is dereferenced by GEP?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>Quick answer: nothing.</p>
|
|
|
|
|
<p>The GetElementPtr instruction dereferences nothing. That is, it doesn't
|
2006-08-15 03:32:10 +00:00
|
|
|
access memory in any way. That's what the Load and Store instructions are for.
|
|
|
|
|
GEP is only involved in the computation of addresses. For example, consider
|
|
|
|
|
this:</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
%MyVar = uninitialized global { [40 x i32 ]* }
|
|
|
|
|
...
|
|
|
|
|
%idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-10 20:15:58 +00:00
|
|
|
<p>In this example, we have a global variable, <tt>%MyVar</tt> that is a
|
|
|
|
|
pointer to a structure containing a pointer to an array of 40 ints. The
|
2006-08-15 03:43:31 +00:00
|
|
|
GEP instruction seems to be accessing the 18th integer of the structure's
|
2006-08-10 20:15:58 +00:00
|
|
|
array of ints. However, this is actually an illegal GEP instruction. It
|
|
|
|
|
won't compile. The reason is that the pointer in the structure <i>must</i>
|
|
|
|
|
be dereferenced in order to index into the array of 40 ints. Since the
|
|
|
|
|
GEP instruction never accesses memory, it is illegal.</p>
|
|
|
|
|
<p>In order to access the 18th integer in the array, you would need to do the
|
|
|
|
|
following:</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
%idx = getelementptr { [40 x i32]* }* %, i64 0, i32 0
|
|
|
|
|
%arr = load [40 x i32]** %idx
|
|
|
|
|
%idx = getelementptr [40 x i32]* %arr, i64 0, i64 17
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-10 20:15:58 +00:00
|
|
|
<p>In this case, we have to load the pointer in the structure with a load
|
|
|
|
|
instruction before we can index into the array. If the example was changed
|
|
|
|
|
to:</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
%MyVar = uninitialized global { [40 x i32 ] }
|
|
|
|
|
...
|
|
|
|
|
%idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-10 20:15:58 +00:00
|
|
|
<p>then everything works fine. In this case, the structure does not contain a
|
2006-08-15 03:43:31 +00:00
|
|
|
pointer and the GEP instruction can index through the global variable,
|
2007-02-09 17:56:02 +00:00
|
|
|
into the first field of the structure and access the 18th <tt>i32</tt> in the
|
2006-08-10 20:15:58 +00:00
|
|
|
array there.</p>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="lead0"><b>Why don't GEP x,0,0,1 and GEP x,1 alias?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>Quick Answer: They compute different address locations.</p>
|
|
|
|
|
<p>If you look at the first indices in these GEP
|
|
|
|
|
instructions you find that they are different (0 and 1), therefore the address
|
|
|
|
|
computation diverges with that index. Consider this example:</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
%MyVar = global { [10 x i32 ] }
|
2010-02-25 18:16:03 +00:00
|
|
|
%idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1
|
|
|
|
|
%idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1
|
2008-01-04 12:04:32 +00:00
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-10 20:15:58 +00:00
|
|
|
<p>In this example, <tt>idx1</tt> computes the address of the second integer
|
2009-08-18 19:18:40 +00:00
|
|
|
in the array that is in the structure in <tt>%MyVar</tt>, that is
|
|
|
|
|
<tt>MyVar+4</tt>. The type of <tt>idx1</tt> is <tt>i32*</tt>. However,
|
|
|
|
|
<tt>idx2</tt> computes the address of <i>the next</i> structure after
|
|
|
|
|
<tt>%MyVar</tt>. The type of <tt>idx2</tt> is <tt>{ [10 x i32] }*</tt> and its
|
|
|
|
|
value is equivalent to <tt>MyVar + 40</tt> because it indexes past the ten
|
|
|
|
|
4-byte integers in <tt>MyVar</tt>. Obviously, in such a situation, the
|
|
|
|
|
pointers don't alias.</p>
|
|
|
|
|
|
2006-08-10 20:15:58 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
2006-08-15 12:15:08 +00:00
|
|
|
<a name="trail0"><b>Why do GEP x,1,0,0 and GEP x,1 alias?</b></a>
|
2006-08-10 20:15:58 +00:00
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>Quick Answer: They compute the same address location.</p>
|
|
|
|
|
<p>These two GEP instructions will compute the same address because indexing
|
|
|
|
|
through the 0th element does not change the address. However, it does change
|
|
|
|
|
the type. Consider this example:</p>
|
2008-01-04 12:04:32 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
%MyVar = global { [10 x i32 ] }
|
2010-02-25 18:16:03 +00:00
|
|
|
%idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0
|
|
|
|
|
%idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1
|
2008-01-04 12:04:32 +00:00
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-10 20:15:58 +00:00
|
|
|
<p>In this example, the value of <tt>%idx1</tt> is <tt>%MyVar+40</tt> and
|
2007-02-09 17:56:02 +00:00
|
|
|
its type is <tt>i32*</tt>. The value of <tt>%idx2</tt> is also
|
|
|
|
|
<tt>MyVar+40</tt> but its type is <tt>{ [10 x i32] }*</tt>.</p>
|
2006-08-10 20:15:58 +00:00
|
|
|
</div>
|
|
|
|
|
|
2010-02-25 18:16:03 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="vectors"><b>Can GEP index into vector elements?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>This hasn't always been forcefully disallowed, though it's not recommended.
|
|
|
|
|
It leads to awkward special cases in the optimizers, and fundamental
|
|
|
|
|
inconsistency in the IR. In the future, it will probably be outright
|
|
|
|
|
disallowed.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="unions"><b>Can GEP index into unions?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>Unknown.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="addrspace"><b>What effect do address spaces have on GEPs?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>None, except that the address space qualifier on the first operand pointer
|
|
|
|
|
type always matches the address space qualifier on the result type.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="int"><b>How is GEP different from ptrtoint, arithmetic,
|
|
|
|
|
and inttoptr?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>It's very similar; there are only subtle differences.</p>
|
|
|
|
|
|
|
|
|
|
<p>With ptrtoint, you have to pick an integer type. One approach is to pick i64;
|
|
|
|
|
this is safe on everything LLVM supports (LLVM internally assumes pointers
|
|
|
|
|
are never wider than 64 bits in many places), and the optimizer will actually
|
|
|
|
|
narrow the i64 arithmetic down to the actual pointer size on targets which
|
|
|
|
|
don't support 64-bit arithmetic in most cases. However, there are some cases
|
|
|
|
|
where it doesn't do this. With GEP you can avoid this problem.
|
|
|
|
|
|
|
|
|
|
<p>Also, GEP carries additional pointer aliasing rules. It's invalid to take a
|
|
|
|
|
GEP from one object, address into a different separately allocated
|
|
|
|
|
object, and dereference it. IR producers (front-ends) must follow this rule,
|
|
|
|
|
and consumers (optimizers, specifically alias analysis) benefit from being
|
|
|
|
|
able to rely on it. See the <a href="#rules">Rules</a> section for more
|
|
|
|
|
information.</p>
|
|
|
|
|
|
|
|
|
|
<p>And, GEP is more concise in common cases.</p>
|
|
|
|
|
|
|
|
|
|
<p>However, for the underlying integer computation implied, there
|
|
|
|
|
is no difference.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="be"><b>I'm writing a backend for a target which needs custom
|
|
|
|
|
lowering for GEP. How do I do this?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>You don't. The integer computation implied by a GEP is target-independent.
|
|
|
|
|
Typically what you'll need to do is make your backend pattern-match
|
|
|
|
|
expressions trees involving ADD, MUL, etc., which are what GEP is lowered
|
|
|
|
|
into. This has the advantage of letting your code work correctly in more
|
|
|
|
|
cases.</p>
|
|
|
|
|
|
|
|
|
|
<p>GEP does use target-dependent parameters for the size and layout of data
|
|
|
|
|
types, which targets can customize.</p>
|
|
|
|
|
|
|
|
|
|
<p>If you require support for addressing units which are not 8 bits, you'll
|
|
|
|
|
need to fix a lot of code in the backend, with GEP lowering being only a
|
|
|
|
|
small piece of the overall picture.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="vla"><b>How does VLA addressing work with GEPs?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>GEPs don't natively support VLAs. LLVM's type system is entirely static,
|
|
|
|
|
and GEP address computations are guided by an LLVM type.</p>
|
|
|
|
|
|
|
|
|
|
<p>VLA indices can be implemented as linearized indices. For example, an
|
|
|
|
|
expression like X[a][b][c], must be effectively lowered into a form
|
|
|
|
|
like X[a*m+b*n+c], so that it appears to the GEP as a single-dimensional
|
|
|
|
|
array reference.</p>
|
|
|
|
|
|
|
|
|
|
<p>This means if you want to write an analysis which understands array
|
|
|
|
|
indices and you want to support VLAs, your code will have to be
|
|
|
|
|
prepared to reverse-engineer the linearization. One way to solve this
|
|
|
|
|
problem is to use the ScalarEvolution library, which always presents
|
|
|
|
|
VLA and non-VLA indexing in the same manner.</p>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_section"><a name="rules"><b>Rules</b></a></div>
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="bounds"><b>What happens if an array index is out of bounds?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>There are two senses in which an array index can be out of bounds.</p>
|
|
|
|
|
|
|
|
|
|
<p>First, there's the array type which comes from the (static) type of
|
|
|
|
|
the first operand to the GEP. Indices greater than the number of elements
|
|
|
|
|
in the corresponding static array type are valid. There is no problem with
|
|
|
|
|
out of bounds indices in this sense. Indexing into an array only depends
|
|
|
|
|
on the size of the array element, not the number of elements.</p>
|
|
|
|
|
|
|
|
|
|
<p>A common example of how this is used is arrays where the size is not known.
|
|
|
|
|
It's common to use array types with zero length to represent these. The
|
|
|
|
|
fact that the static type says there are zero elements is irrelevant; it's
|
|
|
|
|
perfectly valid to compute arbitrary element indices, as the computation
|
|
|
|
|
only depends on the size of the array element, not the number of
|
|
|
|
|
elements. Note that zero-sized arrays are not a special case here.</p>
|
|
|
|
|
|
|
|
|
|
<p>This sense is unconnected with <tt>inbounds</tt> keyword. The
|
|
|
|
|
<tt>inbounds</tt> keyword is designed to describe low-level pointer
|
|
|
|
|
arithmetic overflow conditions, rather than high-level array
|
|
|
|
|
indexing rules.
|
|
|
|
|
|
|
|
|
|
<p>Analysis passes which wish to understand array indexing should not
|
|
|
|
|
assume that the static array type bounds are respected.</p>
|
|
|
|
|
|
|
|
|
|
<p>The second sense of being out of bounds is computing an address that's
|
|
|
|
|
beyond the actual underlying allocated object.</p>
|
|
|
|
|
|
|
|
|
|
<p>With the <tt>inbounds</tt> keyword, the result value of the GEP is
|
|
|
|
|
undefined if the address is outside the actual underlying allocated
|
|
|
|
|
object and not the address one-past-the-end.</p>
|
|
|
|
|
|
|
|
|
|
<p>Without the <tt>inbounds</tt> keyword, there are no restrictions
|
|
|
|
|
on computing out-of-bounds addresses. Obviously, performing a load or
|
|
|
|
|
a store requires an address of allocated and sufficiently aligned
|
|
|
|
|
memory. But the GEP itself is only concerned with computing addresses.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="negative"><b>Can array indices be negative?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>Yes. This is basically a special case of array indices being out
|
|
|
|
|
of bounds.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="compare"><b>Can I compare two values computed with GEPs?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>Yes. If both addresses are within the same allocated object, or
|
|
|
|
|
one-past-the-end, you'll get the comparison result you expect. If either
|
|
|
|
|
is outside of it, integer arithmetic wrapping may occur, so the
|
|
|
|
|
comparison may not be meaningful.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="types"><b>Can I do GEP with a different pointer type than the type of
|
|
|
|
|
the underlying object?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>Yes. There are no restrictions on bitcasting a pointer value to an arbitrary
|
|
|
|
|
pointer type. The types in a GEP serve only to define the parameters for the
|
|
|
|
|
underlying integer computation. They need not correspond with the actual
|
|
|
|
|
type of the underlying object.</p>
|
|
|
|
|
|
|
|
|
|
<p>Furthermore, loads and stores don't have to use the same types as the type
|
|
|
|
|
of the underlying object. Types in this context serve only to specify
|
|
|
|
|
memory size and alignment. Beyond that there are merely a hint to the
|
|
|
|
|
optimizer indicating how the value will likely be used.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="null"><b>Can I cast an object's address to integer and add it
|
|
|
|
|
to null?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>You can compute an address that way, but if you use GEP to do the add,
|
|
|
|
|
you can't use that pointer to actually access the object, unless the
|
|
|
|
|
object is managed outside of LLVM.</p>
|
|
|
|
|
|
|
|
|
|
<p>The underlying integer computation is sufficiently defined; null has a
|
|
|
|
|
defined value -- zero -- and you can add whatever value you want to it.</p>
|
|
|
|
|
|
|
|
|
|
<p>However, it's invalid to access (load from or store to) an LLVM-aware
|
|
|
|
|
object with such a pointer. This includes GlobalVariables, Allocas, and
|
|
|
|
|
objects pointed to by noalias pointers.</p>
|
|
|
|
|
|
|
|
|
|
<p>If you really need this functionality, you can do the arithmetic with
|
|
|
|
|
explicit integer instructions, and use inttoptr to convert the result to
|
|
|
|
|
an address. Most of GEP's special aliasing rules do not apply to pointers
|
|
|
|
|
computed from ptrtoint, arithmetic, and inttoptr sequences.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="ptrdiff"><b>Can I compute the distance between two objects, and add
|
|
|
|
|
that value to one address to compute the other address?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>As with arithmetic on null, You can use GEP to compute an address that
|
|
|
|
|
way, but you can't use that pointer to actually access the object if you
|
|
|
|
|
do, unless the object is managed outside of LLVM.</p>
|
|
|
|
|
|
|
|
|
|
<p>Also as above, ptrtoint and inttoptr provide an alternative way to do this
|
|
|
|
|
which do not have this restriction.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="tbaa"><b>Can I do type-based alias analysis on LLVM IR?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>You can't do type-based alias analysis using LLVM's built-in type system,
|
|
|
|
|
because LLVM has no restrictions on mixing types in addressing, loads or
|
|
|
|
|
stores.</p>
|
|
|
|
|
|
|
|
|
|
<p>It would be possible to add special annotations to the IR, probably using
|
|
|
|
|
metadata, to describe a different type system (such as the C type system),
|
|
|
|
|
and do type-based aliasing on top of that. This is a much bigger
|
|
|
|
|
undertaking though.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="overflow"><b>What happens if a GEP computation overflows?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>If the GEP has the <tt>inbounds</tt> keyword, the result value is
|
|
|
|
|
undefined.</p>
|
|
|
|
|
|
|
|
|
|
<p>Otherwise, the result value is the result from evaluating the implied
|
|
|
|
|
two's complement integer computation. However, since there's no
|
|
|
|
|
guarantee of where an object will be allocated in the address space,
|
|
|
|
|
such values have limited meaning.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="check"><b>How can I tell if my front-end is following the
|
|
|
|
|
rules?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>There is currently no checker for the getelementptr rules. Currently,
|
|
|
|
|
the only way to do this is to manually check each place in your front-end
|
|
|
|
|
where GetElementPtr operators are created.</p>
|
|
|
|
|
|
|
|
|
|
<p>It's not possible to write a checker which could find all rule
|
|
|
|
|
violations statically. It would be possible to write a checker which
|
|
|
|
|
works by instrumenting the code with dynamic checks though. Alternatively,
|
|
|
|
|
it would be possible to write a static checker which catches a subset of
|
|
|
|
|
possible problems. However, no such checker exists today.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_section"><a name="rationale"><b>Rationale</b></a></div>
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="goals"><b>Why is GEP designed this way?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>The design of GEP has the following goals, in rough unofficial
|
|
|
|
|
order of priority:</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>Support C, C-like languages, and languages which can be
|
|
|
|
|
conceptually lowered into C (this covers a lot).</li>
|
|
|
|
|
<li>Support optimizations such as those that are common in
|
2010-07-06 15:26:33 +00:00
|
|
|
C compilers. In particular, GEP is a cornerstone of LLVM's
|
|
|
|
|
<a href="LangRef.html#pointeraliasing">pointer aliasing model</a>.</li>
|
2010-02-25 18:16:03 +00:00
|
|
|
<li>Provide a consistent method for computing addresses so that
|
|
|
|
|
address computations don't need to be a part of load and
|
|
|
|
|
store instructions in the IR.</li>
|
|
|
|
|
<li>Support non-C-like languages, to the extent that it doesn't
|
|
|
|
|
interfere with other goals.</li>
|
|
|
|
|
<li>Minimize target-specific information in the IR.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="i32"><b>Why do struct member indices always use i32?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>The specific type i32 is probably just a historical artifact, however it's
|
|
|
|
|
wide enough for all practical purposes, so there's been no need to change it.
|
|
|
|
|
It doesn't necessarily imply i32 address arithmetic; it's just an identifier
|
|
|
|
|
which identifies a field in a struct. Requiring that all struct indices be
|
|
|
|
|
the same reduces the range of possibilities for cases where two GEPs are
|
|
|
|
|
effectively the same but have distinct operand types.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="uglygep"><b>What's an uglygep?</b></a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>Some LLVM optimizers operate on GEPs by internally lowering them into
|
|
|
|
|
more primitive integer expressions, which allows them to be combined
|
|
|
|
|
with other integer expressions and/or split into multiple separate
|
|
|
|
|
integer expressions. If they've made non-trivial changes, translating
|
|
|
|
|
back into LLVM IR can involve reverse-engineering the structure of
|
|
|
|
|
the addressing in order to fit it into the static type of the original
|
|
|
|
|
first operand. It isn't always possibly to fully reconstruct this
|
|
|
|
|
structure; sometimes the underlying addressing doesn't correspond with
|
|
|
|
|
the static type at all. In such cases the optimizer instead will emit
|
|
|
|
|
a GEP with the base pointer casted to a simple address-unit pointer,
|
|
|
|
|
using the name "uglygep". This isn't pretty, but it's just as
|
|
|
|
|
valid, and it's sufficient to preserve the pointer aliasing guarantees
|
|
|
|
|
that GEP provides.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
2006-08-10 20:15:58 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
<div class="doc_section"><a name="summary"><b>Summary</b></a></div>
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>In summary, here's some things to always remember about the GetElementPtr
|
|
|
|
|
instruction:</p>
|
|
|
|
|
<ol>
|
|
|
|
|
<li>The GEP instruction never accesses memory, it only provides pointer
|
|
|
|
|
computations.</li>
|
|
|
|
|
<li>The first operand to the GEP instruction is always a pointer and it must
|
|
|
|
|
be indexed.</li>
|
|
|
|
|
<li>There are no superfluous indices for the GEP instruction.</li>
|
|
|
|
|
<li>Trailing zero indices are superfluous for pointer aliasing, but not for
|
|
|
|
|
the types of the pointers.</li>
|
|
|
|
|
<li>Leading zero indices are not superfluous for pointer aliasing nor the
|
|
|
|
|
types of the pointers.</li>
|
|
|
|
|
</ol>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<address>
|
|
|
|
|
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
|
2008-12-11 17:34:48 +00:00
|
|
|
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
|
2006-08-10 20:15:58 +00:00
|
|
|
<a href="http://validator.w3.org/check/referer"><img
|
2008-12-11 18:23:24 +00:00
|
|
|
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
|
2006-08-10 20:15:58 +00:00
|
|
|
<a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br/>
|
|
|
|
|
Last modified: $Date$
|
|
|
|
|
</address>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
