From 46813c58bb07afa1bb7dade551361f7d9e7ece56 Mon Sep 17 00:00:00 2001 From: Bill Wendling Date: Fri, 4 Jan 2008 12:04:32 +0000 Subject: doc_code-ify some code in this doc. llvm-svn: 45581 --- llvm/docs/GetElementPtr.html | 193 ++++++++++++++++++++++++++++--------------- 1 file changed, 126 insertions(+), 67 deletions(-) (limited to 'llvm/docs/GetElementPtr.html') diff --git a/llvm/docs/GetElementPtr.html b/llvm/docs/GetElementPtr.html index 710273fb6da..6bf1f4f61e8 100644 --- a/llvm/docs/GetElementPtr.html +++ b/llvm/docs/GetElementPtr.html @@ -53,7 +53,7 @@

When people are first confronted with the GEP instruction, they tend to relate it to known concepts from other programming paradigms, most notably C array indexing and field selection. However, GEP is a little different and - this leads to the following questions, all of which are answered in the + this leads to the following questions; all of which are answered in the following sections.

  1. What is the first index of the GEP instruction? @@ -74,10 +74,15 @@

    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":

    - 
    -  AType* Foo;
-  ...
-  X = &Foo->F;
    + +
    +
    +AType *Foo;
+...
+X = &Foo->F;
+
    +
    +

    it is natural to think that there is only one index, the selection of the field F. However, in this example, Foo is a pointer. That pointer must be indexed explicitly in LLVM. C, on the other hand, indexs @@ -85,8 +90,13 @@ code, you would provide the GEP instruction with two index operands. The first operand indexes through the pointer; the second operand indexes the field F of the structure, just as if you wrote:

    - 
    -  X = &Foo[0].F;
    + +
    +
    +X = &Foo[0].F;
+
    +
    +

    Sometimes this question gets rephrased as:

    Why is it okay to index through the first pointer, but subsequent pointers won't be dereferenced?

    @@ -96,19 +106,23 @@ 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:

    - 
    -  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);
    + +
    +
    +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);
+
    +
    +

    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 P will be the first operand of each @@ -117,36 +131,50 @@ struct munger_struct type, for either the f1 or f2 field. So, in LLVM assembly the munge function looks like:

    - 
    -  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
-  }
    + +
    +
    +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
+}
+
    +
    +

    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.

    To make this clear, let's consider a more obtuse example:

    - 
    -  %MyVar = unintialized global i32
-  ...
-  %idx1 = getelementptr i32* %MyVar, i64 0
-  %idx2 = getelementptr i32* %MyVar, i64 1
-  %idx3 = getelementptr i32* %MyVar, i64 2
    + +
    +
    +%MyVar = unintialized global i32
+...
+%idx1 = getelementptr i32* %MyVar, i64 0
+%idx2 = getelementptr i32* %MyVar, i64 1
+%idx3 = getelementptr i32* %MyVar, i64 2
+
    +
    +

    These GEP instructions are simply making address computations from the base address of MyVar. They compute, as follows (using C syntax):

    -
      -
    • idx1 = (char*) &MyVar + 0
      • -
    • idx2 = (char*) &MyVar + 4
      • -
    • idx3 = (char*) &MyVar + 8
      • -
    + +
    +
    +idx1 = (char*) &MyVar + 0
+idx2 = (char*) &MyVar + 4
+idx3 = (char*) &MyVar + 8
+
    +
    +

    Since the type i32 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 @@ -168,10 +196,16 @@

    Quick answer: there are no superfluous indices.

    This question arises most often when the GEP instruction is applied to a global variable which is always a pointer type. For example, consider - this:

    -  %MyStruct = uninitialized global { float*, i32 }
-  ...
-  %idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1
    + this:

    + +
    +
    +%MyStruct = uninitialized global { float*, i32 }
+...
+%idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1
+
    +
    +

    The GEP above yields an i32* by indexing the i32 typed field of the structure %MyStruct. When people first look at it, they wonder why the i64 0 index is needed. However, a closer inspection @@ -205,10 +239,15 @@ 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:

    - 
    -  %MyVar = uninitialized global { [40 x i32 ]* }
-  ...
-  %idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
    + +
    +
    +%MyVar = uninitialized global { [40 x i32 ]* }
+...
+%idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
+
    +
    +

    In this example, we have a global variable, %MyVar that is a pointer to a structure containing a pointer to an array of 40 ints. The GEP instruction seems to be accessing the 18th integer of the structure's @@ -218,17 +257,27 @@ GEP instruction never accesses memory, it is illegal.

    In order to access the 18th integer in the array, you would need to do the following:

    - 
    -  %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
    + +
    +
    +%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
+
    +
    +

    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:

    - 
    -  %MyVar = uninitialized global { [40 x i32 ] }
-  ...
-  %idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17
    + +
    +
    +%MyVar = uninitialized global { [40 x i32 ] }
+...
+%idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17
+
    +
    +

    then everything works fine. In this case, the structure does not contain a pointer and the GEP instruction can index through the global variable, into the first field of the structure and access the 18th i32 in the @@ -244,10 +293,15 @@

    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:

    - 
    -  %MyVar = global { [10 x i32 ] }
-  %idx1 = getlementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1
-  %idx2 = getlementptr { [10 x i32 ] }* %MyVar, i64 1
    + +
    +
    +%MyVar = global { [10 x i32 ] }
+%idx1 = getlementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1
+%idx2 = getlementptr { [10 x i32 ] }* %MyVar, i64 1
+
    +
    +

    In this example, idx1 computes the address of the second integer in the array that is in the structure in %MyVar, that is MyVar+4. The type of idx1 is i32*. However, idx2 computes the @@ -267,10 +321,15 @@

    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:

    - 
    -  %MyVar = global { [10 x i32 ] }
-  %idx1 = getlementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0
-  %idx2 = getlementptr { [10 x i32 ] }* %MyVar, i64 1
    + +
    +
    +%MyVar = global { [10 x i32 ] }
+%idx1 = getlementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0
+%idx2 = getlementptr { [10 x i32 ] }* %MyVar, i64 1
+
    +
    +

    In this example, the value of %idx1 is %MyVar+40 and its type is i32*. The value of %idx2 is also MyVar+40 but its type is { [10 x i32] }*.

    -- cgit v1.2.3