lib/librte_eal/include/generic/rte_pflock.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2021 Microsoft Corp.
   3  * All rights reserved.
   4  *
   5  * Derived from Concurrency Kit
   6  * Copyright 2011-2015 Samy Al Bahra.
   7  */
   8
   9 #ifndef _RTE_PFLOCK_H_
  10 #define _RTE_PFLOCK_H_
  11
  12 /**
  13  * @file
  14  *
  15  * Phase-fair locks
  16  *
  17  * This file defines an API for phase-fair reader writer locks,
  18  * which is a variant of typical reader-writer locks that prevent
  19  * starvation. In this type of lock, readers and writers alternate.
  20  * This significantly reduces the worst-case blocking for readers and writers.
  21  *
  22  * This is an implementation derived from FreeBSD
  23  * based on the work described in:
  24  *    Brandenburg, B. and Anderson, J. 2010. Spin-Based
  25  *    Reader-Writer Synchronization for Multiprocessor Real-Time Systems
  26  *
  27  * All locks must be initialised before use, and only initialised once.
  28  */
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 #include <rte_common.h>
  35 #include <rte_pause.h>
  36
  37 /**
  38  * The rte_pflock_t type.
  39  */
  40 struct rte_pflock {
  41         struct {
  42                 uint16_t in;
  43                 uint16_t out;
  44         } rd, wr;
  45 };
  46 typedef struct rte_pflock rte_pflock_t;
  47
  48 /*
  49  * Allocation of bits to reader
  50  *
  51  * 15                 4 3 2 1 0
  52  * +-------------------+---+-+-+
  53  * | rin: reads issued |x|x| | |
  54  * +-------------------+---+-+-+
  55  *                          ^ ^
  56  *                          | |
  57  * PRES: writer present ----/ |
  58  * PHID: writer phase id -----/
  59  *
  60  * 15                4 3 2 1 0
  61  * +------------------+------+
  62  * |rout:read complete|unused|
  63  * +------------------+------+
  64  *
  65  * The maximum number of readers is 4095
  66  */
  67
  68 /* Constants used to map the bits in reader counter */
  69 #define RTE_PFLOCK_WBITS 0x3    /* Writer bits in reader. */
  70 #define RTE_PFLOCK_PRES  0x2    /* Writer present bit. */
  71 #define RTE_PFLOCK_PHID  0x1    /* Phase ID bit. */
  72 #define RTE_PFLOCK_LSB   0xFFF0 /* reader bits. */
  73 #define RTE_PFLOCK_RINC  0x10   /* Reader increment. */
  74
  75 /**
  76  * A static pflock initializer.
  77  */
  78 #define RTE_PFLOCK_INITIALIZER {  }
  79
  80 /**
  81  * @warning
  82  * @b EXPERIMENTAL: this API may change without prior notice.
  83  *
  84  * Initialize the pflock to an unlocked state.
  85  *
  86  * @param pf
  87  *   A pointer to the pflock.
  88  */
  89 __rte_experimental
  90 static inline void
  91 rte_pflock_init(struct rte_pflock *pf)
  92 {
  93         pf->rd.in = 0;
  94         pf->rd.out = 0;
  95         pf->wr.in = 0;
  96         pf->wr.out = 0;
  97 }
  98
  99 /**
 100  * @warning
 101  * @b EXPERIMENTAL: this API may change without prior notice.
 102  *
 103  * Take a pflock for read.
 104  *
 105  * @param pf
 106  *   A pointer to a pflock structure.
 107  */
 108 __rte_experimental
 109 static inline void
 110 rte_pflock_read_lock(rte_pflock_t *pf)
 111 {
 112         uint16_t w;
 113
 114         /*
 115          * If no writer is present, then the operation has completed
 116          * successfully.
 117          */
 118         w = __atomic_fetch_add(&pf->rd.in, RTE_PFLOCK_RINC, __ATOMIC_ACQUIRE)
 119                 & RTE_PFLOCK_WBITS;
 120         if (w == 0)
 121                 return;
 122
 123         /* Wait for current write phase to complete. */
 124         while ((__atomic_load_n(&pf->rd.in, __ATOMIC_ACQUIRE)
 125                 & RTE_PFLOCK_WBITS) == w)
 126                 rte_pause();
 127 }
 128
 129 /**
 130  * @warning
 131  * @b EXPERIMENTAL: this API may change without prior notice.
 132  *
 133  * Release a pflock locked for reading.
 134  *
 135  * @param pf
 136  *   A pointer to the pflock structure.
 137  */
 138 __rte_experimental
 139 static inline void
 140 rte_pflock_read_unlock(rte_pflock_t *pf)
 141 {
 142         __atomic_fetch_add(&pf->rd.out, RTE_PFLOCK_RINC, __ATOMIC_RELEASE);
 143 }
 144
 145 /**
 146  * @warning
 147  * @b EXPERIMENTAL: this API may change without prior notice.
 148  *
 149  * Take the pflock for write.
 150  *
 151  * @param pf
 152  *   A pointer to the pflock structure.
 153  */
 154 __rte_experimental
 155 static inline void
 156 rte_pflock_write_lock(rte_pflock_t *pf)
 157 {
 158         uint16_t ticket, w;
 159
 160         /* Acquire ownership of write-phase.
 161          * This is same as rte_tickelock_lock().
 162          */
 163         ticket = __atomic_fetch_add(&pf->wr.in, 1, __ATOMIC_RELAXED);
 164         rte_wait_until_equal_16(&pf->wr.out, ticket, __ATOMIC_ACQUIRE);
 165
 166         /*
 167          * Acquire ticket on read-side in order to allow them
 168          * to flush. Indicates to any incoming reader that a
 169          * write-phase is pending.
 170          *
 171          * The load of rd.out in wait loop could be executed
 172          * speculatively.
 173          */
 174         w = RTE_PFLOCK_PRES | (ticket & RTE_PFLOCK_PHID);
 175         ticket = __atomic_fetch_add(&pf->rd.in, w, __ATOMIC_RELAXED);
 176
 177         /* Wait for any pending readers to flush. */
 178         rte_wait_until_equal_16(&pf->rd.out, ticket, __ATOMIC_ACQUIRE);
 179 }
 180
 181 /**
 182  * @warning
 183  * @b EXPERIMENTAL: this API may change without prior notice.
 184  *
 185  * Release a pflock held for writing.
 186  *
 187  * @param pf
 188  *   A pointer to a pflock structure.
 189  */
 190 __rte_experimental
 191 static inline void
 192 rte_pflock_write_unlock(rte_pflock_t *pf)
 193 {
 194         /* Migrate from write phase to read phase. */
 195         __atomic_fetch_and(&pf->rd.in, RTE_PFLOCK_LSB, __ATOMIC_RELEASE);
 196
 197         /* Allow other writers to continue. */
 198         __atomic_fetch_add(&pf->wr.out, 1, __ATOMIC_RELEASE);
 199 }
 200
 201 #ifdef __cplusplus
 202 }
 203 #endif
 204
 205 #endif /* RTE_PFLOCK_H */