lib/librte_eal/common/include/generic/rte_rwlock.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2014 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_RWLOCK_H_
   6 #define _RTE_RWLOCK_H_
   7
   8 /**
   9  * @file
  10  *
  11  * RTE Read-Write Locks
  12  *
  13  * This file defines an API for read-write locks. The lock is used to
  14  * protect data that allows multiple readers in parallel, but only
  15  * one writer. All readers are blocked until the writer is finished
  16  * writing.
  17  *
  18  */
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 #include <rte_common.h>
  25 #include <rte_atomic.h>
  26 #include <rte_pause.h>
  27
  28 /**
  29  * The rte_rwlock_t type.
  30  *
  31  * cnt is -1 when write lock is held, and > 0 when read locks are held.
  32  */
  33 typedef struct {
  34         volatile int32_t cnt; /**< -1 when W lock held, > 0 when R locks held. */
  35 } rte_rwlock_t;
  36
  37 /**
  38  * A static rwlock initializer.
  39  */
  40 #define RTE_RWLOCK_INITIALIZER { 0 }
  41
  42 /**
  43  * Initialize the rwlock to an unlocked state.
  44  *
  45  * @param rwl
  46  *   A pointer to the rwlock structure.
  47  */
  48 static inline void
  49 rte_rwlock_init(rte_rwlock_t *rwl)
  50 {
  51         rwl->cnt = 0;
  52 }
  53
  54 /**
  55  * Take a read lock. Loop until the lock is held.
  56  *
  57  * @param rwl
  58  *   A pointer to a rwlock structure.
  59  */
  60 static inline void
  61 rte_rwlock_read_lock(rte_rwlock_t *rwl)
  62 {
  63         int32_t x;
  64         int success = 0;
  65
  66         while (success == 0) {
  67                 x = __atomic_load_n(&rwl->cnt, __ATOMIC_RELAXED);
  68                 /* write lock is held */
  69                 if (x < 0) {
  70                         rte_pause();
  71                         continue;
  72                 }
  73                 success = __atomic_compare_exchange_n(&rwl->cnt, &x, x + 1, 1,
  74                                         __ATOMIC_ACQUIRE, __ATOMIC_RELAXED);
  75         }
  76 }
  77
  78 /**
  79  * @warning
  80  * @b EXPERIMENTAL: this API may change without prior notice.
  81  *
  82  * try to take a read lock.
  83  *
  84  * @param rwl
  85  *   A pointer to a rwlock structure.
  86  * @return
  87  *   - zero if the lock is successfully taken
  88  *   - -EBUSY if lock could not be acquired for reading because a
  89  *     writer holds the lock
  90  */
  91 __rte_experimental
  92 static inline int
  93 rte_rwlock_read_trylock(rte_rwlock_t *rwl)
  94 {
  95         int32_t x;
  96         int success = 0;
  97
  98         while (success == 0) {
  99                 x = __atomic_load_n(&rwl->cnt, __ATOMIC_RELAXED);
 100                 /* write lock is held */
 101                 if (x < 0)
 102                         return -EBUSY;
 103                 success = __atomic_compare_exchange_n(&rwl->cnt, &x, x + 1, 1,
 104                                         __ATOMIC_ACQUIRE, __ATOMIC_RELAXED);
 105         }
 106
 107         return 0;
 108 }
 109
 110 /**
 111  * Release a read lock.
 112  *
 113  * @param rwl
 114  *   A pointer to the rwlock structure.
 115  */
 116 static inline void
 117 rte_rwlock_read_unlock(rte_rwlock_t *rwl)
 118 {
 119         __atomic_fetch_sub(&rwl->cnt, 1, __ATOMIC_RELEASE);
 120 }
 121
 122 /**
 123  * @warning
 124  * @b EXPERIMENTAL: this API may change without prior notice.
 125  *
 126  * try to take a write lock.
 127  *
 128  * @param rwl
 129  *   A pointer to a rwlock structure.
 130  * @return
 131  *   - zero if the lock is successfully taken
 132  *   - -EBUSY if lock could not be acquired for writing because
 133  *     it was already locked for reading or writing
 134  */
 135 __rte_experimental
 136 static inline int
 137 rte_rwlock_write_trylock(rte_rwlock_t *rwl)
 138 {
 139         int32_t x;
 140
 141         x = __atomic_load_n(&rwl->cnt, __ATOMIC_RELAXED);
 142         if (x != 0 || __atomic_compare_exchange_n(&rwl->cnt, &x, -1, 1,
 143                               __ATOMIC_ACQUIRE, __ATOMIC_RELAXED) == 0)
 144                 return -EBUSY;
 145
 146         return 0;
 147 }
 148
 149 /**
 150  * Take a write lock. Loop until the lock is held.
 151  *
 152  * @param rwl
 153  *   A pointer to a rwlock structure.
 154  */
 155 static inline void
 156 rte_rwlock_write_lock(rte_rwlock_t *rwl)
 157 {
 158         int32_t x;
 159         int success = 0;
 160
 161         while (success == 0) {
 162                 x = __atomic_load_n(&rwl->cnt, __ATOMIC_RELAXED);
 163                 /* a lock is held */
 164                 if (x != 0) {
 165                         rte_pause();
 166                         continue;
 167                 }
 168                 success = __atomic_compare_exchange_n(&rwl->cnt, &x, -1, 1,
 169                                         __ATOMIC_ACQUIRE, __ATOMIC_RELAXED);
 170         }
 171 }
 172
 173 /**
 174  * Release a write lock.
 175  *
 176  * @param rwl
 177  *   A pointer to a rwlock structure.
 178  */
 179 static inline void
 180 rte_rwlock_write_unlock(rte_rwlock_t *rwl)
 181 {
 182         __atomic_store_n(&rwl->cnt, 0, __ATOMIC_RELEASE);
 183 }
 184
 185 /**
 186  * Try to execute critical section in a hardware memory transaction, if it
 187  * fails or not available take a read lock
 188  *
 189  * NOTE: An attempt to perform a HW I/O operation inside a hardware memory
 190  * transaction always aborts the transaction since the CPU is not able to
 191  * roll-back should the transaction fail. Therefore, hardware transactional
 192  * locks are not advised to be used around rte_eth_rx_burst() and
 193  * rte_eth_tx_burst() calls.
 194  *
 195  * @param rwl
 196  *   A pointer to a rwlock structure.
 197  */
 198 static inline void
 199 rte_rwlock_read_lock_tm(rte_rwlock_t *rwl);
 200
 201 /**
 202  * Commit hardware memory transaction or release the read lock if the lock is used as a fall-back
 203  *
 204  * @param rwl
 205  *   A pointer to the rwlock structure.
 206  */
 207 static inline void
 208 rte_rwlock_read_unlock_tm(rte_rwlock_t *rwl);
 209
 210 /**
 211  * Try to execute critical section in a hardware memory transaction, if it
 212  * fails or not available take a write lock
 213  *
 214  * NOTE: An attempt to perform a HW I/O operation inside a hardware memory
 215  * transaction always aborts the transaction since the CPU is not able to
 216  * roll-back should the transaction fail. Therefore, hardware transactional
 217  * locks are not advised to be used around rte_eth_rx_burst() and
 218  * rte_eth_tx_burst() calls.
 219  *
 220  * @param rwl
 221  *   A pointer to a rwlock structure.
 222  */
 223 static inline void
 224 rte_rwlock_write_lock_tm(rte_rwlock_t *rwl);
 225
 226 /**
 227  * Commit hardware memory transaction or release the write lock if the lock is used as a fall-back
 228  *
 229  * @param rwl
 230  *   A pointer to a rwlock structure.
 231  */
 232 static inline void
 233 rte_rwlock_write_unlock_tm(rte_rwlock_t *rwl);
 234
 235 #ifdef __cplusplus
 236 }
 237 #endif
 238
 239 #endif /* _RTE_RWLOCK_H_ */