</head>
<body>
-<div class="doc_title">
+<h1>
The Often Misunderstood GEP Instruction
-</div>
+</h1>
<ol>
<li><a href="#intro">Introduction</a></li>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="intro"><b>Introduction</b></a></div>
+<h2><a name="intro">Introduction</a></h2>
<!-- *********************************************************************** -->
<div class="doc_text">
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="addresses"><b>Address Computation</b></a></div>
+<h2><a name="addresses">Address Computation</a></h2>
<!-- *********************************************************************** -->
<div class="doc_text">
<p>When people are first confronted with the GEP instruction, they tend to
</div>
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="firstptr"><b>What is the first index of the GEP instruction?</b></a>
-</div>
+<h3>
+ <a name="firstptr">What is the first index of the GEP instruction?</a>
+</h3>
<div class="doc_text">
<p>Quick answer: The index stepping through the first operand.</p>
<p>The confusion with the first index usually arises from thinking about
</div>
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="extra_index"><b>Why is the extra 0 index required?</b></a>
-</div>
+<h3>
+ <a name="extra_index">Why is the extra 0 index required?</a>
+</h3>
<!-- *********************************************************************** -->
<div class="doc_text">
<p>Quick answer: there are no superfluous indices.</p>
</div>
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="deref"><b>What is dereferenced by GEP?</b></a>
-</div>
+<h3>
+ <a name="deref">What is dereferenced by GEP?</a>
+</h3>
<div class="doc_text">
<p>Quick answer: nothing.</p>
<p>The GetElementPtr instruction dereferences nothing. That is, it doesn't
</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>
+<h3>
+ <a name="lead0">Why don't GEP x,0,0,1 and GEP x,1 alias?</a>
+</h3>
<div class="doc_text">
<p>Quick Answer: They compute different address locations.</p>
<p>If you look at the first indices in these GEP
</div>
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="trail0"><b>Why do GEP x,1,0,0 and GEP x,1 alias?</b></a>
-</div>
+<h3>
+ <a name="trail0">Why do GEP x,1,0,0 and GEP x,1 alias?</a>
+</h3>
<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
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="vectors"><b>Can GEP index into vector elements?</b></a>
-</div>
+<h3>
+ <a name="vectors">Can GEP index into vector elements?</a>
+</h3>
<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
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="addrspace"><b>What effect do address spaces have on GEPs?</b></a>
-</div>
+<h3>
+ <a name="addrspace">What effect do address spaces have on GEPs?</a>
+</h3>
<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 class="doc_subsection">
- <a name="int"><b>How is GEP different from ptrtoint, arithmetic,
- and inttoptr?</b></a>
-</div>
+<h3>
+ <a name="int">
+ How is GEP different from ptrtoint, arithmetic, and inttoptr?
+ </a>
+</h3>
<div class="doc_text">
<p>It's very similar; there are only subtle differences.</p>
<!-- *********************************************************************** -->
-<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>
+<h3>
+ <a name="be">
+ I'm writing a backend for a target which needs custom lowering for GEP.
+ How do I do this?
+ </a>
+</h3>
<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
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="vla"><b>How does VLA addressing work with GEPs?</b></a>
-</div>
+<h3>
+ <a name="vla">How does VLA addressing work with GEPs?</a>
+</h3>
<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>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="rules"><b>Rules</b></a></div>
+<h2><a name="rules">Rules</a></h2>
<!-- *********************************************************************** -->
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="bounds"><b>What happens if an array index is out of bounds?</b></a>
-</div>
+<h3>
+ <a name="bounds">What happens if an array index is out of bounds?</a>
+</h3>
<div class="doc_text">
<p>There are two senses in which an array index can be out of bounds.</p>
</div>
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="negative"><b>Can array indices be negative?</b></a>
-</div>
+<h3>
+ <a name="negative">Can array indices be negative?</a>
+</h3>
<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>
+<h3>
+ <a name="compare">Can I compare two values computed with GEPs?</a>
+</h3>
<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
</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>
+<h3>
+ <a name="types">
+ Can I do GEP with a different pointer type than the type of
+ the underlying object?
+ </a>
+</h3>
<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
</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>
+<h3>
+ <a name="null">
+ Can I cast an object's address to integer and add it to null?
+ </a>
+</h3>
<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
</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>
+<h3>
+ <a name="ptrdiff">
+ Can I compute the distance between two objects, and add
+ that value to one address to compute the other address?
+ </a>
+</h3>
<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
</div>
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="tbaa"><b>Can I do type-based alias analysis on LLVM IR?</b></a>
-</div>
+<h3>
+ <a name="tbaa">Can I do type-based alias analysis on LLVM IR?</a>
+</h3>
<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
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="overflow"><b>What happens if a GEP computation overflows?</b></a>
-</div>
+<h3>
+ <a name="overflow">What happens if a GEP computation overflows?</a>
+</h3>
<div class="doc_text">
<p>If the GEP lacks the <tt>inbounds</tt> keyword, the value is the result
from evaluating the implied two's complement integer computation. However,
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="check"><b>How can I tell if my front-end is following the
- rules?</b></a>
-</div>
+<h3>
+ <a name="check">
+ How can I tell if my front-end is following the rules?
+ </a>
+</h3>
<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
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="rationale"><b>Rationale</b></a></div>
+<h2><a name="rationale">Rationale</a></h2>
<!-- *********************************************************************** -->
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="goals"><b>Why is GEP designed this way?</b></a>
-</div>
+<h3>
+ <a name="goals">Why is GEP designed this way?</a>
+</h3>
<div class="doc_text">
<p>The design of GEP has the following goals, in rough unofficial
order of priority:</p>
</div>
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="i32"><b>Why do struct member indices always use i32?</b></a>
-</div>
+<h3>
+ <a name="i32">Why do struct member indices always use i32?</a>
+</h3>
<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.
<!-- *********************************************************************** -->
-<div class="doc_subsection">
- <a name="uglygep"><b>What's an uglygep?</b></a>
-</div>
+<h3>
+ <a name="uglygep">What's an uglygep?</a>
+</h3>
<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
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="summary"><b>Summary</b></a></div>
+<h2><a name="summary">Summary</a></h2>
<!-- *********************************************************************** -->
<div class="doc_text">
projects / oota-llvm.git / blobdiff