From dfecbe9b0c9f14f60bf285f9e62bbb1c728f09e2 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 17 Feb 2010 22:47:06 +0000 Subject: [PATCH] Add an "advanced" GetElementPtr FAQ document, with answers to questions left unanswered by the first GetElementPtr FAQ. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@96526 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/AdvancedGetElementPtr.html | 356 ++++++++++++++++++++++++++++++++ docs/index.html | 3 + 2 files changed, 359 insertions(+) create mode 100644 docs/AdvancedGetElementPtr.html diff --git a/docs/AdvancedGetElementPtr.html b/docs/AdvancedGetElementPtr.html new file mode 100644 index 00000000000..128effee092 --- /dev/null +++ b/docs/AdvancedGetElementPtr.html @@ -0,0 +1,356 @@ + + + + + The Revenge Of The Often Misunderstood GEP Instruction + + + + + +
+ The Revenge Of The Often Misunderstood GEP Instruction +
+ + +
Introduction
+ +
+

GEP was mysterious and wily at first, but it turned out that the basic + workings were fairly comprehensible. However the dragon was merely subdued; + now it's back, and it has more fundamental complexity to confront. This + document seeks to uncover misunderstandings of the GEP operator that tend + to persist past initial confusion about the funky "extra 0" thing. Here we + show that the GEP instruction is really not quite as simple as it seems, + even after the initial confusion is overcome.

+
+ + +
+ How is GEP different from ptrtoint, arithmetic, + and inttoptr? +
+
+

It's very similar; there are only subtle differences.

+ +

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

Also, GEP carries additional pointer aliasing rules. It's invalid to take a + GEP from one object and address into a different separately allocated + object. IR producers (front-ends) must follow this rule, and consumers + (optimizers, specifically alias analysis) benefit from being able to rely + on it.

+ +

And, GEP is more concise in common cases.

+ +

However, for of the underlying integer computation implied, there + is no difference.

+ +
+ + +
+ I'm writing a backend for a target which needs custom + lowering for GEP. How do I do this? +
+
+

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.

+ +

GEP does use target-dependent parameters for the size and layout of data + types, which targets can customize.

+ +

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.

+ +
+ + +
+ Why do struct member indices always use i32? +
+
+

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.

+ +
+ + +
+ How does VLA addressing work with GEPs? +
+
+

GEPs don't natively support VLAs. LLVM's type system is entirely static, + and GEP address computations are guided by an LLVM type.

+ +

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.

+ +

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.

+ +
+ + +
+ What happens if an array index is out of bounds? +
+
+

There are two senses in which an array index can be out of bounds.

+ +

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.

+ +

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.

+ +

This sense is unconnected with inbounds keyword. The + inbounds keyword is designed to describe low-level pointer + arithmetic overflow conditions, rather than high-level array + indexing rules. + +

Analysis passes which wish to understand array indexing should not + assume that the static array type bounds are respected.

+ +

The second sense of being out of bounds is computing an address that's + beyond of the actual underlying allocated object.

+ +

With the inbounds 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.

+ +

Without the inbounds 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.

+ +
+ + +
+ Can array indices be negative? +
+
+

Yes. This is basically a special case of array indices being out + of bounds.

+ +
+ + +
+ Can I compare two values computed with GEPs? +
+
+

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.

+ +
+ + +
+ Can I do GEP with a different pointer type than the type of + the underlying object? +
+
+

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.

+ +

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.

+ +
+ + +
+ Can I cast an object's address to integer and add it + to null? +
+
+

You can 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.

+ +

The underlying integer computation is sufficiently defined; null has a + defined value -- zero -- and you can add whatever value you want to it.

+ +

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.

+ +
+ + +
+ Can I compute the distance between two objects, and add + that value to one address to compute the other address? +
+
+

As with arithmetic on null, You can 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.

+ +
+ + +
+ Can I do type-based alias analysis on LLVM IR? +
+
+

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.

+ +

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.

+ +
+ + + +
+ What's an uglygep? +
+
+

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.

+ +
+ + + +
+ Can GEP index into vector elements? +
+
+

Sort of. This hasn't always been forcefully disallowed, though it's + not recommended. It leads to awkward special cases in the optimizers. + In the future, it may be outright disallowed.

+ +

Instead, you should cast your pointer types and use arrays instead of + vectors for addressing. Arrays have the same in-memory representation + as vectors, so the addressing is interchangeable.

+ +
+ + + +
+ Can GEP index into unions? +
+
+

Unknown.

+ +
+ + + +
+ What happens if a GEP computation overflows? +
+
+

If the GEP has the inbounds keyword, the result value is + undefined.

+ +

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.

+ +
+ + + +
+ What effect do address spaces have on GEPs? +
+
+

None, except that the address space qualifier on the first operand pointer + type always matches the address space qualifier on the result type.

+ +
+ + + +
+ Why is GEP designed this way? +
+
+

The design of GEP has the following goals, in rough unofficial + order of priority:

+

+

    +
  1. Support C, C-like languages, and languages which can be + conceptually lowered into C (this covers a lot).
    2. +
  2. Support optimizations such as those that are common in + C compilers.
    3. +
  3. 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.
    4. +
  4. Support non-C-like languages, to the extent that it doesn't + interfere with other goals.
    5. +
  5. Minimize target-specific information in the IR.
    6. +
+

+
+ + + +
+
+ Valid CSS + Valid HTML 4.01 + The LLVM Compiler Infrastructure
+ Last modified: $Date$ +
+ + + diff --git a/docs/index.html b/docs/index.html index 28f4cded777..936eae16e3a 100644 --- a/docs/index.html +++ b/docs/index.html @@ -54,6 +54,9 @@ Lifelong Program Analysis & Transformation - Design overview. Multi-Stage Optimization - More details (quite old now).
  • GetElementPtr FAQ - Answers to some very frequent questions about LLVM's most frequently misunderstood instruction.
    • +
  • Advanced GetElementPtr FAQ - Answers +to questions about the GetElementPtr operator for those who have made it through +the first FAQ.