[llvm] f05145c - [docs] Modernize statepoint documentation
Philip Reames via llvm-commits
llvm-commits at lists.llvm.org
Mon Aug 26 13:26:35 PDT 2024
Author: Philip Reames
Date: 2024-08-26T13:26:25-07:00
New Revision: f05145cd31e92c73301e308a6e13c581af3076ce
URL: https://github.com/llvm/llvm-project/commit/f05145cd31e92c73301e308a6e13c581af3076ce
DIFF: https://github.com/llvm/llvm-project/commit/f05145cd31e92c73301e308a6e13c581af3076ce.diff
LOG: [docs] Modernize statepoint documentation
Update syntax (opaque pointers, elementype, gc-live), and remove a couple
of misleading examples.
Added:
Modified:
llvm/docs/Statepoints.rst
Removed:
################################################################################
diff --git a/llvm/docs/Statepoints.rst b/llvm/docs/Statepoints.rst
index ed137ed4fa8edb..27a46a43b5190f 100644
--- a/llvm/docs/Statepoints.rst
+++ b/llvm/docs/Statepoints.rst
@@ -167,10 +167,11 @@ Let's consider a simple call in LLVM IR:
.. code-block:: llvm
- define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
+ declare void @foo()
+ define ptr addrspace(1) @test1(ptr addrspace(1) %obj)
gc "statepoint-example" {
- call void ()* @foo()
- ret i8 addrspace(1)* %obj
+ call void @foo()
+ ret ptr addrspace(1) %obj
}
Depending on our language we may need to allow a safepoint during the execution
@@ -186,11 +187,11 @@ resulting relocation sequence is:
.. code-block:: llvm
- define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
+ define ptr addrspace(1) @test(ptr addrspace(1) %obj)
gc "statepoint-example" {
- %0 = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 0, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 0, i8 addrspace(1)* %obj)
- %obj.relocated = call coldcc i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(token %0, i32 7, i32 7)
- ret i8 addrspace(1)* %obj.relocated
+ %safepoint = call token (i64, i32, ptr, i32, i32, ...) @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 0, i32 0, ptr elementtype(void ()) @foo, i32 0, i32 0, i32 0, i32 0) ["gc-live" (ptr addrspace(1) %obj)]
+ %obj.relocated = call ptr addrspace(1) @llvm.experimental.gc.relocate.p1(token %safepoint, i32 0, i32 0)
+ ret ptr addrspace(1) %obj.relocated
}
Ideally, this sequence would have been represented as a M argument, N
@@ -269,10 +270,13 @@ collector:
.. code-block:: llvm
- define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
- gc "statepoint-example" {
- call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 0, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 0, i8 addrspace(1)* %obj)
- ret i8 addrspace(1)* %obj
+ define void @manual_frame(ptr %a, ptr %b) gc "statepoint-example" {
+ %alloca = alloca ptr
+ %allocb = alloca ptr
+ store ptr %a, ptr %alloca
+ store ptr %b, ptr %allocb
+ call token (i64, i32, ptr, i32, i32, ...) @llvm.experimental.gc.statepoint.p0(i64 0, i32 0, ptr elementtype(void ()) @func, i32 0, i32 0, i32 0, i32 0) ["gc-live" (ptr %alloca, ptr %allocb)]
+ ret void
}
Recording On Stack Regions
@@ -332,25 +336,6 @@ lowering both the base and derived pointer operands are required to be live
over the associated call safepoint even if the base is otherwise unused
afterwards.
-If we extend our previous example to include a pointless derived pointer,
-we get:
-
-.. code-block:: llvm
-
- define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
- gc "statepoint-example" {
- %gep = getelementptr i8, i8 addrspace(1)* %obj, i64 20000
- %token = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 0, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 0, i8 addrspace(1)* %obj, i8 addrspace(1)* %gep)
- %obj.relocated = call i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(token %token, i32 7, i32 7)
- %gep.relocated = call i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(token %token, i32 7, i32 8)
- %p = getelementptr i8, i8 addrspace(1)* %gep, i64 -20000
- ret i8 addrspace(1)* %p
- }
-
-Note that in this example %p and %obj.relocate are the same address and we
-could replace one with the other, potentially removing the derived pointer
-from the live set at the safepoint entirely.
-
.. _gc_transition_args:
GC Transitions
@@ -564,21 +549,20 @@ As an example, given this code:
.. code-block:: llvm
- define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
+ define ptr addrspace(1) @test1(ptr addrspace(1) %obj)
gc "statepoint-example" {
call void @foo()
- ret i8 addrspace(1)* %obj
+ ret ptr addrspace(1) %obj
}
The pass would produce this IR:
.. code-block:: llvm
- define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
- gc "statepoint-example" {
- %0 = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @foo, i32 0, i32 0, i32 0, i32 5, i32 0, i32 -1, i32 0, i32 0, i32 0, i8 addrspace(1)* %obj)
- %obj.relocated = call coldcc i8 addrspace(1)* @llvm.experimental.gc.relocate.p1i8(token %0, i32 12, i32 12)
- ret i8 addrspace(1)* %obj.relocated
+ define ptr addrspace(1) @test_rs4gc(ptr addrspace(1) %obj) gc "statepoint-example" {
+ %statepoint_token = call token (i64, i32, ptr, i32, i32, ...) @llvm.experimental.gc.statepoint.p0(i64 2882400000, i32 0, ptr elementtype(void ()) @foo, i32 0, i32 0, i32 0, i32 0) [ "gc-live"(ptr addrspace(1) %obj) ]
+ %obj.relocated = call coldcc ptr addrspace(1) @llvm.experimental.gc.relocate.p1(token %statepoint_token, i32 0, i32 0) ; (%obj, %obj)
+ ret ptr addrspace(1) %obj.relocated
}
In the above examples, the addrspace(1) marker on the pointers is the mechanism
More information about the llvm-commits
mailing list