Add rseq critical section pseudocode documentation

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Change-Id: Ic7bd7df3566401562a41ffc8112fe95d740c0016

10 files changed, 185 insertions, 0 deletions

diff --git a/include/Makefile.am b/include/Makefile.am
index e3c664d..b01cf31 100644
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -15,6 +15,7 @@ nobase_include_HEADERS = \
 	rseq/rseq-mips-bits.h \
 	rseq/rseq-ppc.h \
 	rseq/rseq-ppc-bits.h \
+	rseq/rseq-pseudocode.h \
 	rseq/rseq-riscv.h \
 	rseq/rseq-riscv-bits.h \
 	rseq/rseq-s390.h \
diff --git a/include/rseq/rseq-arm-bits.h b/include/rseq/rseq-arm-bits.h
index 2cff022..9fbeedd 100644
--- a/include/rseq/rseq-arm-bits.h
+++ b/include/rseq/rseq-arm-bits.h
@@ -7,6 +7,12 @@
 
 #include "rseq-bits-template.h"
 
+/*
+ * Refer to rseq-pseudocode.h for documentation and pseudo-code of the
+ * rseq critical section helpers.
+ */
+#include "rseq-pseudocode.h"
+
 #if defined(RSEQ_TEMPLATE_MO_RELAXED) && \
 	(defined(RSEQ_TEMPLATE_CPU_ID) || defined(RSEQ_TEMPLATE_MM_CID))
 
diff --git a/include/rseq/rseq-arm64-bits.h b/include/rseq/rseq-arm64-bits.h
index 6b77d89..709990f 100644
--- a/include/rseq/rseq-arm64-bits.h
+++ b/include/rseq/rseq-arm64-bits.h
@@ -8,6 +8,12 @@
 
 #include "rseq-bits-template.h"
 
+/*
+ * Refer to rseq-pseudocode.h for documentation and pseudo-code of the
+ * rseq critical section helpers.
+ */
+#include "rseq-pseudocode.h"
+
 #if defined(RSEQ_TEMPLATE_MO_RELAXED) && \
 	(defined(RSEQ_TEMPLATE_CPU_ID) || defined(RSEQ_TEMPLATE_MM_CID))
 
diff --git a/include/rseq/rseq-mips-bits.h b/include/rseq/rseq-mips-bits.h
index a025bde..529f380 100644
--- a/include/rseq/rseq-mips-bits.h
+++ b/include/rseq/rseq-mips-bits.h
@@ -8,6 +8,12 @@
 
 #include "rseq-bits-template.h"
 
+/*
+ * Refer to rseq-pseudocode.h for documentation and pseudo-code of the
+ * rseq critical section helpers.
+ */
+#include "rseq-pseudocode.h"
+
 #if defined(RSEQ_TEMPLATE_MO_RELAXED) && \
 	(defined(RSEQ_TEMPLATE_CPU_ID) || defined(RSEQ_TEMPLATE_MM_CID))
 
diff --git a/include/rseq/rseq-ppc-bits.h b/include/rseq/rseq-ppc-bits.h
index 9cd7ca2..ad8559b 100644
--- a/include/rseq/rseq-ppc-bits.h
+++ b/include/rseq/rseq-ppc-bits.h
@@ -8,6 +8,12 @@
 
 #include "rseq-bits-template.h"
 
+/*
+ * Refer to rseq-pseudocode.h for documentation and pseudo-code of the
+ * rseq critical section helpers.
+ */
+#include "rseq-pseudocode.h"
+
 #if defined(RSEQ_TEMPLATE_MO_RELAXED) && \
 	(defined(RSEQ_TEMPLATE_CPU_ID) || defined(RSEQ_TEMPLATE_MM_CID))
 
diff --git a/include/rseq/rseq-pseudocode.h b/include/rseq/rseq-pseudocode.h
new file mode 100644
index 0000000..8f220fb
--- /dev/null
+++ b/include/rseq/rseq-pseudocode.h
@@ -0,0 +1,136 @@
+/* SPDX-License-Identifier: MIT */
+/* SPDX-FileCopyrightText: 2024 Mathieu Desnoyers <mathieu.desnoyers@efficios.com> */
+
+/*
+ * rseq-pseudocode.h
+ *
+ * This file contains the pseudo-code of rseq critical section helpers,
+ * to be used as reference for architecture implementation.
+ */
+
+/*
+ * Pseudo-code conventions:
+ *
+ * rX: Register X
+ * [var]: Register associated with C variable "var".
+ * [label]: Jump target associated with C label "label".
+ *
+ * load(rX, address): load from memory address to rX
+ * store(rX, address): store to memory address from rX
+ * cbne(rX, rY, target): compare-and-branch to target if rX != rY
+ * cbeq(rX, rY, target): compare-and-branch to target if rX == rY
+ * add(rX, rY): add rY to register rX
+ * memcpy(dest_address, src_address, len): copy len bytes from src_address to dst_address
+ *
+ * Critical section helpers identifier convention:
+ * - Begin with an "rseq_" prefix,
+ * - Followed by their simplified pseudo-code,
+ * - Followed by __ and the type (or eventually types) on which the API
+ *   applies (similar to the approach taken for C++ mangling).
+ */
+
+/*
+ * rseq_load_cbne_store(v, expect, newv)
+ *
+ * Pseudo-code:
+ *   load(r1, [v])
+ *   cbne(r1, [expect], [ne])
+ *   store([newv], [v])
+ *
+ * Return values:
+ *   success: 0
+ *   ne: 1
+ *   abort: -1
+ */
+
+/*
+ * rseq_load_add_store(v, count)
+ *
+ * Pseudo-code:
+ *   load(r1, [v])
+ *   add(r1, [count])
+ *   store(r1, [v])
+ *
+ * Return values:
+ *   success: 0
+ *   abort: -1
+ */
+
+/*
+ * rseq_load_cbeq_store_add_load_store(v, expectnot, voffp, load)
+ *
+ * Pseudo-code:
+ *   load(r1, [v])
+ *   cbeq(r1, [expectnot], [eq])
+ *   store(r1, [load])
+ *   add(r1, [voffp])
+ *   load(r2, r1)
+ *   store(r2, [v])
+ *
+ * Return values:
+ *   success: 0
+ *   eq: 1
+ *   abort: -1
+ */
+
+/*
+ * rseq_load_add_load_add_store(ptr, off, inc)
+ *
+ * Pseudo-code:
+ *   load(r1, [ptr])
+ *   add(r1, [off])
+ *   load(r2, r1)
+ *   load(r3, r2)
+ *   add(r3, [inc])
+ *   store(r3, r2)
+ *
+ * Return values:
+ *   success: 0
+ *   abort: -1
+ */
+
+/*
+ * rseq_load_cbne_load_cbne_store(v, expect, v2, expect2, newv)
+ *
+ * Pseudo-code:
+ *   load(r1, [v])
+ *   cbne(r1, [expect], [ne])
+ *   load(r2, [v2])
+ *   cbne(r2, [expect2], [ne])
+ *   store([newv], [v])
+ *
+ * Return values:
+ *   success: 0
+ *   ne: 1
+ *   abort: -1
+ */
+
+/*
+ * rseq_load_cbne_store_store(v, expect, v2, newv2, newv)
+ *
+ * Pseudo-code:
+ *   load(r1, [v])
+ *   cbne(r1, [expect], [ne])
+ *   store([newv2], [v2])         // Store attempt
+ *   store([newv], [v])           // Final store
+ *
+ * Return values:
+ *   success: 0
+ *   ne: 1
+ *   abort: -1
+ */
+
+/*
+ * rseq_load_cbne_memcpy_store(v, expect, dst, src, len, newv)
+ *
+ * Pseudo-code:
+ *   load(r1, [v])
+ *   cbne(r1, [expect], [ne])
+ *   memcpy([dst], [src], [len])  // Memory copy attempt
+ *   store([newv], [v])           // Final store
+ *
+ * Return values:
+ *   success: 0
+ *   ne: 1
+ *   abort: -1
+ */
diff --git a/include/rseq/rseq-riscv-bits.h b/include/rseq/rseq-riscv-bits.h
index cfb0972..467781b 100644
--- a/include/rseq/rseq-riscv-bits.h
+++ b/include/rseq/rseq-riscv-bits.h
@@ -3,6 +3,12 @@
 
 #include "rseq-bits-template.h"
 
+/*
+ * Refer to rseq-pseudocode.h for documentation and pseudo-code of the
+ * rseq critical section helpers.
+ */
+#include "rseq-pseudocode.h"
+
 #if defined(RSEQ_TEMPLATE_MO_RELAXED) && \
 	(defined(RSEQ_TEMPLATE_CPU_ID) || defined(RSEQ_TEMPLATE_MM_CID))
 
diff --git a/include/rseq/rseq-s390-bits.h b/include/rseq/rseq-s390-bits.h
index c3641b7..e94f602 100644
--- a/include/rseq/rseq-s390-bits.h
+++ b/include/rseq/rseq-s390-bits.h
@@ -3,6 +3,12 @@
 
 #include "rseq-bits-template.h"
 
+/*
+ * Refer to rseq-pseudocode.h for documentation and pseudo-code of the
+ * rseq critical section helpers.
+ */
+#include "rseq-pseudocode.h"
+
 #if defined(RSEQ_TEMPLATE_MO_RELAXED) && \
 	(defined(RSEQ_TEMPLATE_CPU_ID) || defined(RSEQ_TEMPLATE_MM_CID))
 
diff --git a/include/rseq/rseq-x86-bits.h b/include/rseq/rseq-x86-bits.h
index fd3c6b8..937092e 100644
--- a/include/rseq/rseq-x86-bits.h
+++ b/include/rseq/rseq-x86-bits.h
@@ -6,6 +6,12 @@
 
 #include "rseq-bits-template.h"
 
+/*
+ * Refer to rseq-pseudocode.h for pseudo-code of the rseq critical
+ * section helpers.
+ */
+#include "rseq-pseudocode.h"
+
 #ifdef __x86_64__
 
 #if defined(RSEQ_TEMPLATE_MO_RELAXED) && \
diff --git a/include/rseq/rseq.h b/include/rseq/rseq.h
index 080508e..222c36a 100644
--- a/include/rseq/rseq.h
+++ b/include/rseq/rseq.h
@@ -268,6 +268,12 @@ static inline void rseq_prepare_unload(void)
 	rseq_clear_rseq_cs();
 }
 
+/*
+ * Refer to rseq-pseudocode.h for documentation and pseudo-code of the
+ * rseq critical section helpers.
+ */
+#include "rseq-pseudocode.h"
+
 static inline __attribute__((always_inline))
 int rseq_cmpeqv_storev(enum rseq_mo rseq_mo, enum rseq_percpu_mode percpu_mode,
 		       intptr_t *v, intptr_t expect,