Add more comments about this builtin

Author: Azoy

include/swift/AST/Builtins.def

@@ -1112,6 +1112,12 @@ BUILTIN_MISC_OPERATION_WITH_SILGEN(DistributedActorAsAnyActor, "distributedActor
 /// Returns a raw pointer to the address of the raw layout type. This address is
 /// only valid during a borrow access of the raw layout type or until the value
 /// is either moved or consumed.
+///
+/// Note: The purpose of this builtin is to get an opaque pointer to the address
+/// of the raw layout type. We explicitly do not want the optimizer looking into
+/// this pointer or address thereof to start assuming things about mutability or
+/// immutability. This builtin _must_ persist throughout all of SIL and must be
+/// lowered away at IRGen, no sooner.
 BUILTIN_MISC_OPERATION_WITH_SILGEN(AddressOfRawLayout, "addressOfRawLayout", "n", Special)
 
 /// Builtins for instrumentation added by sanitizers during SILGen.

lib/IRGen/GenBuiltin.cpp

@@ -1477,6 +1477,9 @@ void irgen::emitBuiltinCall(IRGenFunction &IGF, const BuiltinInfo &Builtin,
     return;
   }
 
+  // LLVM must not see the address generated here as 'invariant' or immutable
+  // ever. A raw layout's address defies all formal access, so immutable looking
+  // uses may actually mutate the underlying value!
   if (Builtin.ID == BuiltinValueKind::AddressOfRawLayout) {
     auto addr = args.claimNext();
     auto value = IGF.Builder.CreateBitCast(addr, IGF.IGM.Int8PtrTy);