[docs][OpaquePtr] Shuffle around the transition plan section

[aeubanks]

Summary

Emphasize that this is basically an attempt to remove
`PointerType::getElementType and Type::getPointerElementType()`.

Add a couple more subtasks.

[dblaikie]

Sounds good to me - couple of optional comments/questions that could be clarified in the text.

llvm/docs/OpaquePointers.rst

118

May be confusing to say "This may already be done" when the line before sort of seems like it says "this is already done".

Maybe rephrase this to "More cases may be found as work continues"?

140–143

Oh, yeah. I remember that one.

Are there cases you know of where we will need overloading based on pointee type? Or might it be a case of mangling opaque pointer types as opaque being sufficient?

[aeubanks]

wording

[aeubanks]

llvm/docs/OpaquePointers.rst

140–143

So far I've found D61524 that needs to be done.
But I'm confused about your question. We won't have pointee types, so we won't be able to mangle based on pointee type, we can only mangle opaque pointers as opaque pointers (with their address space).

[dblaikie]

llvm/docs/OpaquePointers.rst

140–143

What I mean is are there intrinsics that have different behavior based on the pointee type (ie: a function that takes only a pointer parameter, but actually has different behavior (I could imagine something like a typed memcpy where the type information (size of elements to copy) is communicated through the pointee type)) - or, to the best of our current knowledge, the intrinsic overloading for pointee types is only because it's necessary for those functions to have different names to account for the different parameters (and not require bitcasts for every parameter) but have the same implementation.

[aeubanks]

llvm/docs/OpaquePointers.rst

140–143

Ah I haven't looked through all of the intrinsics, I've only stumbled upon D61524 so far, which isn't exactly specializing implementations per pointee type, rather just looking at the pointee type.

[dblaikie]

llvm/docs/OpaquePointers.rst

140–143

Oh, so in that case it is specialized in the sense that it does do something different, by the sounds of it, depending on the type? (where "different" is "touches more or fewer bytes based on the size of the pointee type" - same algorithm, but not exactly the same instructions - that's "different" enough for what I'm thinking about/getting at)

So in that case it won't be as simple as updating the mangling code to do the right thing for opaque pointers (I see there's another review out to make that change, which seems good) - but it'll need to deliberately mangle in a type that isn't a parameter type (I don't know if there's precedent for that - hopefully it's not too complicated) into the function name, and recover that to do the gep-like thing?

[aeubanks]

llvm/docs/OpaquePointers.rst

140–143

I think mangling is purely based on argument types, you currently can't encode a random type into an intrinsic, so there isn't any precedent.
A random thought I had was to add a dummy parameter with the underlying GEP type (and just pass undef into it) so we can retrieve the type later, but perhaps there's a better way.

llvm/docs/OpaquePointers.rst

 
 If you have use cases that this sort of fix doesn't cover, please email
 llvm-dev.
 
 Transition Plan
 ===============
 
 LLVM currently has many places that depend on pointee types. Each dependency on
-pointee types needs to be resolved in some way or another.
+pointee types needs to be resolved in some way or another. This essentially
+translates to figuring out how to remove all calls to
+``PointerType::getElementType`` and ``Type::getPointerElementType()``.
 
 Making everything use opaque pointers in one huge commit is infeasible. This
 needs to be done incrementally. The following steps need to be done, in no
 particular order:
 
 * Introduce the opaque pointer type
 
-* Various ABI attributes and instructions that need a type can be changed one at
-  a time
+  * Already done
 
-  * This has already happened for many instructions like loads, stores, GEPs,
+* Remove remaining in-tree users of pointee types
+
+  * There are many miscellaneous uses that should be cleaned up individually
+
+  * Some of the larger use cases are mentioned below
+
+* Various ABI attributes and instructions that rely on pointee types need to be
+  modified to specify the type separately
+
+  * This has already happened for all instructions like loads, stores, GEPs,
     and various attributes like ``byval``
 
-* Fix up existing in-tree users of pointee types to not rely on LLVM pointer
-  pointee types
+  * This may already be done
 
-  * Specifically ``PointerType::getElementType`` and
-    ``Type::getPointerElementType()``
+* Remove calls to and deprecate ``IRBuilder`` methods that rely on pointee types
+
+  * For example, some of the ``IRBuilder::CreateGEP()`` methods use the pointer
+    operand's pointee type to determine the GEP operand type
+
+  * Some methods are already deprecated with ``LLVM_ATTRIBUTE_DEPRECATED``, such
+    as some overloads of ``IRBuilder::CreateLoad()``
 
 * Allow bitcode auto-upgrade of legacy pointer type to the new opaque pointer
   type (not to be turned on until ready)
 
   * To support legacy bitcode, such as legacy stores/loads, we need to track
     pointee types for all values since legacy instructions may infer the types
     from a pointer operand's pointee type
 
 * Migrate frontends to not keep track of frontend pointee types via LLVM pointer
   pointee types
 
   * This is mostly Clang, see ``clang::CodeGen::Address::getElementType()``
 
+* Figure out how to name overloaded intrinsics with pointer parameters
+
+  * See ``getMangledTypeStr()``
+
 * Add option to internally treat all pointer types opaque pointers and see what
   breaks, starting with LLVM tests, then run Clang over large codebases
 
+  * We don't want to start mass-updating tests until we're fairly confident that opaque pointers won't cause major issues
+
 * Replace legacy pointer types in LLVM tests with opaque pointer types
 
 Frontend Migration Steps
 ========================
 
 If you have your own frontend, there are a couple of things to do after opaque
 pointer types fully work.
 
 * Don't rely on LLVM pointee types to keep track of frontend pointee types
 
 * Migrate away from LLVM IR instruction builders that rely on pointee types
 
   * For example, ``IRBuilder::CreateGEP()`` has multiple overloads; make sure to
     use one where the source element type is explicitly passed in, not inferred
     from the pointer operand pointee type