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.
-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, 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.
- -And, GEP is more concise in common cases.
- -However, for the underlying integer computation implied, there - is no difference.
- -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.
- -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.
- -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.
- -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 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.
- -Yes. This is basically a special case of array indices being out - of bounds.
- -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.
- -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.
- -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.
- -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.
- -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.
- -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.
- -Also as above, ptrtoint and inttoptr provide an alternative way to do this - which do not have this restriction.
- -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.
- -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.
- -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.
- -Unknown.
- -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.
- -None, except that the address space qualifier on the first operand pointer - type always matches the address space qualifier on the result type.
- -The design of GEP has the following goals, in rough unofficial - order of priority:
-
- This document seeks to dispel the mystery and confusion surrounding LLVM's - GetElementPtr (GEP) instruction. Questions about the wiley GEP instruction are + GetElementPtr (GEP) instruction. Questions about the wily GEP instruction are probably the most frequently occurring questions once a developer gets down to coding with LLVM. Here we lay out the sources of confusion and show that the GEP instruction is really quite simple. @@ -47,22 +72,14 @@
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 - following sections.
- + 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.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 + pointer must be indexed explicitly in LLVM. C, on the other hand, indices 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 @@ -155,7 +172,7 @@ entry:
-%MyVar = unintialized global i32 +%MyVar = uninitialized global i32 ... %idx1 = getelementptr i32* %MyVar, i64 0 %idx2 = getelementptr i32* %MyVar, i64 1 @@ -210,7 +227,7 @@ idx3 = (char*) &MyVar + 8 field of the structure %MyStruct. When people first look at it, they wonder why the i64 0 index is needed. However, a closer inspection of how globals and GEPs work reveals the need. Becoming aware of the following - facts will dispell the confusion: + facts will dispel the confusion:
- The type of %MyStruct is not { float*, i32 } but rather { float*, i32 }*. That is, %MyStruct is a @@ -297,8 +314,8 @@ idx3 = (char*) &MyVar + 8
@@ -326,8 +343,8 @@ idx3 = (char*) &MyVar + 8%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 +%idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1 +%idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1@@ -336,6 +353,352 @@ idx3 = (char*) &MyVar + 8 MyVar+40 but its type is { [10 x i32] }*.%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 +%idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0 +%idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1
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.
+ +Unknown.
+ +None, except that the address space qualifier on the first operand pointer + type always matches the address space qualifier on the result type.
+ +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, 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 Rules section for more + information.
+ +And, GEP is more concise in common cases.
+ +However, for the underlying integer computation implied, there + is no difference.
+ +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.
+ +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.
+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 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.
+ +Yes. This is basically a special case of array indices being out + of bounds.
+ +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.
+ +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.
+ +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.
+ +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.
+ +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.
+ +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.
+ +Also as above, ptrtoint and inttoptr provide an alternative way to do this + which do not have this restriction.
+ +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.
+ +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.
+ +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.
+ +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.
+ +The design of GEP has the following goals, in rough unofficial + order of priority:
+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.
+ +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.
+ +