+<!-- *********************************************************************** -->
+<div class="doc_subsection">
+ <a name="firstptr"><b>What is the first index of the GEP instruction?</b></a>
+</div>
+<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
+ the GetElementPtr instruction as if it was a C index operator. They aren't the
+ same. For example, when we write, in "C":</p>
+ <pre>
+ AType* Foo;
+ ...
+ X = &Foo->F;</pre>
+ <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
+ pointer must be indexed explicitly in LLVM. C, on the other hand, indexs
+ through it transparently. To arrive at the same address location as the C
+ 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>
+ <pre>
+ X = &Foo[0].F;</pre>
+ <p>Sometimes this question gets rephrased as:</p>
+ <blockquote><p><i>Why is it okay to index through the first pointer, but
+ subsequent pointers won't be dereferenced?</i></p></blockquote>
+ <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
+ 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>
+ <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>
+ <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
+ 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
+ <tt>f2</tt> field. So, in LLVM assembly the <tt>munge</tt> function looks
+ like:</p>
+ <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>
+ <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>
+ <pre>
+ %MyVar = unintialized global i32
+ ...
+ %idx1 = getelementptr i32* %MyVar, i64 0
+ %idx2 = getelementptr i32* %MyVar, i64 1
+ %idx3 = getelementptr i32* %MyVar, i64 2</pre>
+ <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>
+ <ul>
+ <li> idx1 = (char*) &MyVar + 0</li>
+ <li> idx2 = (char*) &MyVar + 4</li>
+ <li> idx3 = (char*) &MyVar + 8</li>
+ </ul>
+ <p>Since the type <tt>i32</tt> is known to be four bytes long, the indices
+ 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
+ <tt>i32</tt> long, not three <tt>i32</tt>s long. While this is legal in LLVM,
+ it is inadvisable because any load or store with the pointer that results
+ from these GEP instructions would produce undefined results.</p>
+</div>
+