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