From: Mathieu Desnoyers Date: Fri, 23 Feb 2024 19:48:28 +0000 (-0500) Subject: Add rseq critical section pseudocode documentation X-Git-Url: http://drtracing.org/?a=commitdiff_plain;h=201c1a2a7a84281a2eaacb0f5c93c52d2df6ff0e;p=librseq.git Add rseq critical section pseudocode documentation Signed-off-by: Mathieu Desnoyers Change-Id: Ic7bd7df3566401562a41ffc8112fe95d740c0016 --- 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 */ + +/* + * 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,