include/rseq/pseudocode.h

   1 /* SPDX-License-Identifier: MIT */
   2 /* SPDX-FileCopyrightText: 2024 Mathieu Desnoyers <mathieu.desnoyers@efficios.com> */
   3
   4 /*
   5  * rseq/pseudocode.h
   6  *
   7  * This file contains the pseudo-code of rseq critical section helpers,
   8  * to be used as reference for architecture implementation.
   9  */
  10
  11 #ifndef _RSEQ_PSEUDOCODE_H
  12 #define _RSEQ_PSEUDOCODE_H
  13
  14 /*
  15  * Pseudo-code conventions:
  16  *
  17  * rX: Register X
  18  * [var]: Register associated with C variable "var".
  19  * [label]: Jump target associated with C label "label".
  20  *
  21  * load(rX, address): load from memory address to rX
  22  * store(rX, address): store to memory address from rX
  23  * cbne(rX, rY, target): compare-and-branch to target if rX != rY
  24  * cbeq(rX, rY, target): compare-and-branch to target if rX == rY
  25  * add(rX, rY): add rY to register rX
  26  * memcpy(dest_address, src_address, len): copy len bytes from src_address to dst_address
  27  *
  28  * Critical section helpers identifier convention:
  29  * - Begin with an "rseq_" prefix,
  30  * - Followed by their simplified pseudo-code,
  31  * - Followed by __ and the type (or eventually types) on which the API
  32  *   applies (similar to the approach taken for C++ mangling).
  33  */
  34
  35 /*
  36  * rseq_load_cbne_store(v, expect, newv)
  37  *
  38  * Pseudo-code:
  39  *   load(r1, [v])
  40  *   cbne(r1, [expect], [ne])
  41  *   store([newv], [v])
  42  *
  43  * Return values:
  44  *   success: 0
  45  *   ne: 1
  46  *   abort: -1
  47  */
  48
  49 /*
  50  * rseq_load_add_store(v, count)
  51  *
  52  * Pseudo-code:
  53  *   load(r1, [v])
  54  *   add(r1, [count])
  55  *   store(r1, [v])
  56  *
  57  * Return values:
  58  *   success: 0
  59  *   abort: -1
  60  */
  61
  62 /*
  63  * rseq_load_cbeq_store_add_load_store(v, expectnot, voffp, load)
  64  *
  65  * Pseudo-code:
  66  *   load(r1, [v])
  67  *   cbeq(r1, [expectnot], [eq])
  68  *   store(r1, [load])
  69  *   add(r1, [voffp])
  70  *   load(r2, r1)
  71  *   store(r2, [v])
  72  *
  73  * Return values:
  74  *   success: 0
  75  *   eq: 1
  76  *   abort: -1
  77  */
  78
  79 /*
  80  * rseq_load_add_load_load_add_store(ptr, off, inc)
  81  *
  82  * Pseudo-code:
  83  *   load(r1, [ptr])
  84  *   add(r1, [off])
  85  *   load(r2, r1)
  86  *   load(r3, r2)
  87  *   add(r3, [inc])
  88  *   store(r3, r2)
  89  *
  90  * Return values:
  91  *   success: 0
  92  *   abort: -1
  93  */
  94
  95 /*
  96  * rseq_load_cbne_load_cbne_store(v, expect, v2, expect2, newv)
  97  *
  98  * Pseudo-code:
  99  *   load(r1, [v])
 100  *   cbne(r1, [expect], [ne])
 101  *   load(r2, [v2])
 102  *   cbne(r2, [expect2], [ne])
 103  *   store([newv], [v])
 104  *
 105  * Return values:
 106  *   success: 0
 107  *   ne: 1
 108  *   abort: -1
 109  */
 110
 111 /*
 112  * rseq_load_cbne_store_store(v, expect, v2, newv2, newv)
 113  *
 114  * Pseudo-code:
 115  *   load(r1, [v])
 116  *   cbne(r1, [expect], [ne])
 117  *   store([newv2], [v2])         // Store attempt
 118  *   store([newv], [v])           // Final store
 119  *
 120  * Return values:
 121  *   success: 0
 122  *   ne: 1
 123  *   abort: -1
 124  */
 125
 126 /*
 127  * rseq_load_cbne_memcpy_store(v, expect, dst, src, len, newv)
 128  *
 129  * Pseudo-code:
 130  *   load(r1, [v])
 131  *   cbne(r1, [expect], [ne])
 132  *   memcpy([dst], [src], [len])  // Memory copy attempt
 133  *   store([newv], [v])           // Final store
 134  *
 135  * Return values:
 136  *   success: 0
 137  *   ne: 1
 138  *   abort: -1
 139  */
 140
 141 #endif  /* _RSEQ_PSEUDOCODE_H */