Add rseq critical section pseudocode documentation

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

diff --git a/include/Makefile.am b/include/Makefile.am
index e3c664d533c6701faf30460ad7659b647120310f..b01cf31f6892c9bd70f8e54c110d088c11b8972c 100644 (file)
--- 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 2cff022f379429e2d0911481522ebfb38944ccbb..9fbeeddd4a49bc1e580c9c332057f8c336f6a047 100644 (file)
--- 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 6b77d8983a509b029c753974ef4964d491dba2a9..709990f4b298812e49b9926a3f1c76a62e670d26 100644 (file)
--- 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 a025bde1a023c771325cc25828beb516b1d858aa..529f380982bd9a372aef69f0dd4a2097cf0eaafc 100644 (file)
--- 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 9cd7ca2fc6669aaedf826f91c0f3fcc49e81ba75..ad8559b028ed4452b950152dc7ca460fcf0e8a94 100644 (file)
--- 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 (file)
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 cfb097236eb038bd518c02c2e0ca05cf90232222..467781bcd15a551d00ccb83860d232a24c2a9ded 100644 (file)
--- 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 c3641b7dd49b8b87322db0e6d333f7cf803d23ca..e94f60280d4a26d8ad720dd8bf909757220448ee 100644 (file)
--- 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 fd3c6b8df0fa92eb2cef03861a6b16d3733c1d2f..937092ee846ff2179ac19024823fc189fb235109 100644 (file)
--- 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 080508e2988de275367e101a8d571398fc72cfa1..222c36a9589bfc573800b2e577e1389abce258b6 100644 (file)
--- 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,