include/linux/hwspinlock.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * Hardware spinlock public header
   4  *
   5  * Copyright (C) 2010 Texas Instruments Incorporated - http://www.ti.com
   6  *
   7  * Contact: Ohad Ben-Cohen <ohad@wizery.com>
   8  */
   9
  10 #ifndef __LINUX_HWSPINLOCK_H
  11 #define __LINUX_HWSPINLOCK_H
  12
  13 #include <linux/err.h>
  14 #include <linux/sched.h>
  15
  16 /* hwspinlock mode argument */
  17 #define HWLOCK_IRQSTATE 0x01    /* Disable interrupts, save state */
  18 #define HWLOCK_IRQ      0x02    /* Disable interrupts, don't save state */
  19 #define HWLOCK_RAW      0x03
  20
  21 struct device;
  22 struct device_node;
  23 struct hwspinlock;
  24 struct hwspinlock_device;
  25 struct hwspinlock_ops;
  26
  27 /**
  28  * struct hwspinlock_pdata - platform data for hwspinlock drivers
  29  * @base_id: base id for this hwspinlock device
  30  *
  31  * hwspinlock devices provide system-wide hardware locks that are used
  32  * by remote processors that have no other way to achieve synchronization.
  33  *
  34  * To achieve that, each physical lock must have a system-wide id number
  35  * that is agreed upon, otherwise remote processors can't possibly assume
  36  * they're using the same hardware lock.
  37  *
  38  * Usually boards have a single hwspinlock device, which provides several
  39  * hwspinlocks, and in this case, they can be trivially numbered 0 to
  40  * (num-of-locks - 1).
  41  *
  42  * In case boards have several hwspinlocks devices, a different base id
  43  * should be used for each hwspinlock device (they can't all use 0 as
  44  * a starting id!).
  45  *
  46  * This platform data structure should be used to provide the base id
  47  * for each device (which is trivially 0 when only a single hwspinlock
  48  * device exists). It can be shared between different platforms, hence
  49  * its location.
  50  */
  51 struct hwspinlock_pdata {
  52         int base_id;
  53 };
  54
  55 #ifdef CONFIG_HWSPINLOCK
  56
  57 int hwspin_lock_register(struct hwspinlock_device *bank, struct device *dev,
  58                 const struct hwspinlock_ops *ops, int base_id, int num_locks);
  59 int hwspin_lock_unregister(struct hwspinlock_device *bank);
  60 struct hwspinlock *hwspin_lock_request(void);
  61 struct hwspinlock *hwspin_lock_request_specific(unsigned int id);
  62 int hwspin_lock_free(struct hwspinlock *hwlock);
  63 int of_hwspin_lock_get_id(struct device_node *np, int index);
  64 int hwspin_lock_get_id(struct hwspinlock *hwlock);
  65 int __hwspin_lock_timeout(struct hwspinlock *, unsigned int, int,
  66                                                         unsigned long *);
  67 int __hwspin_trylock(struct hwspinlock *, int, unsigned long *);
  68 void __hwspin_unlock(struct hwspinlock *, int, unsigned long *);
  69 int of_hwspin_lock_get_id_byname(struct device_node *np, const char *name);
  70 int devm_hwspin_lock_free(struct device *dev, struct hwspinlock *hwlock);
  71 struct hwspinlock *devm_hwspin_lock_request(struct device *dev);
  72 struct hwspinlock *devm_hwspin_lock_request_specific(struct device *dev,
  73                                                      unsigned int id);
  74 int devm_hwspin_lock_unregister(struct device *dev,
  75                                 struct hwspinlock_device *bank);
  76 int devm_hwspin_lock_register(struct device *dev,
  77                               struct hwspinlock_device *bank,
  78                               const struct hwspinlock_ops *ops,
  79                               int base_id, int num_locks);
  80
  81 #else /* !CONFIG_HWSPINLOCK */
  82
  83 /*
  84  * We don't want these functions to fail if CONFIG_HWSPINLOCK is not
  85  * enabled. We prefer to silently succeed in this case, and let the
  86  * code path get compiled away. This way, if CONFIG_HWSPINLOCK is not
  87  * required on a given setup, users will still work.
  88  *
  89  * The only exception is hwspin_lock_register/hwspin_lock_unregister, with which
  90  * we _do_ want users to fail (no point in registering hwspinlock instances if
  91  * the framework is not available).
  92  *
  93  * Note: ERR_PTR(-ENODEV) will still be considered a success for NULL-checking
  94  * users. Others, which care, can still check this with IS_ERR.
  95  */
  96 static inline struct hwspinlock *hwspin_lock_request(void)
  97 {
  98         return ERR_PTR(-ENODEV);
  99 }
 100
 101 static inline struct hwspinlock *hwspin_lock_request_specific(unsigned int id)
 102 {
 103         return ERR_PTR(-ENODEV);
 104 }
 105
 106 static inline int hwspin_lock_free(struct hwspinlock *hwlock)
 107 {
 108         return 0;
 109 }
 110
 111 static inline
 112 int __hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int to,
 113                                         int mode, unsigned long *flags)
 114 {
 115         return 0;
 116 }
 117
 118 static inline
 119 int __hwspin_trylock(struct hwspinlock *hwlock, int mode, unsigned long *flags)
 120 {
 121         return 0;
 122 }
 123
 124 static inline
 125 void __hwspin_unlock(struct hwspinlock *hwlock, int mode, unsigned long *flags)
 126 {
 127 }
 128
 129 static inline int of_hwspin_lock_get_id(struct device_node *np, int index)
 130 {
 131         return 0;
 132 }
 133
 134 static inline int hwspin_lock_get_id(struct hwspinlock *hwlock)
 135 {
 136         return 0;
 137 }
 138
 139 static inline
 140 int of_hwspin_lock_get_id_byname(struct device_node *np, const char *name)
 141 {
 142         return 0;
 143 }
 144
 145 static inline
 146 int devm_hwspin_lock_free(struct device *dev, struct hwspinlock *hwlock)
 147 {
 148         return 0;
 149 }
 150
 151 static inline struct hwspinlock *devm_hwspin_lock_request(struct device *dev)
 152 {
 153         return ERR_PTR(-ENODEV);
 154 }
 155
 156 static inline
 157 struct hwspinlock *devm_hwspin_lock_request_specific(struct device *dev,
 158                                                      unsigned int id)
 159 {
 160         return ERR_PTR(-ENODEV);
 161 }
 162
 163 #endif /* !CONFIG_HWSPINLOCK */
 164
 165 /**
 166  * hwspin_trylock_irqsave() - try to lock an hwspinlock, disable interrupts
 167  * @hwlock: an hwspinlock which we want to trylock
 168  * @flags: a pointer to where the caller's interrupt state will be saved at
 169  *
 170  * This function attempts to lock the underlying hwspinlock, and will
 171  * immediately fail if the hwspinlock is already locked.
 172  *
 173  * Upon a successful return from this function, preemption and local
 174  * interrupts are disabled (previous interrupts state is saved at @flags),
 175  * so the caller must not sleep, and is advised to release the hwspinlock
 176  * as soon as possible.
 177  *
 178  * Returns 0 if we successfully locked the hwspinlock, -EBUSY if
 179  * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid.
 180  */
 181 static inline
 182 int hwspin_trylock_irqsave(struct hwspinlock *hwlock, unsigned long *flags)
 183 {
 184         return __hwspin_trylock(hwlock, HWLOCK_IRQSTATE, flags);
 185 }
 186
 187 /**
 188  * hwspin_trylock_irq() - try to lock an hwspinlock, disable interrupts
 189  * @hwlock: an hwspinlock which we want to trylock
 190  *
 191  * This function attempts to lock the underlying hwspinlock, and will
 192  * immediately fail if the hwspinlock is already locked.
 193  *
 194  * Upon a successful return from this function, preemption and local
 195  * interrupts are disabled, so the caller must not sleep, and is advised
 196  * to release the hwspinlock as soon as possible.
 197  *
 198  * Returns 0 if we successfully locked the hwspinlock, -EBUSY if
 199  * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid.
 200  */
 201 static inline int hwspin_trylock_irq(struct hwspinlock *hwlock)
 202 {
 203         return __hwspin_trylock(hwlock, HWLOCK_IRQ, NULL);
 204 }
 205
 206 /**
 207  * hwspin_trylock_raw() - attempt to lock a specific hwspinlock
 208  * @hwlock: an hwspinlock which we want to trylock
 209  *
 210  * This function attempts to lock an hwspinlock, and will immediately fail
 211  * if the hwspinlock is already taken.
 212  *
 213  * Caution: User must protect the routine of getting hardware lock with mutex
 214  * or spinlock to avoid dead-lock, that will let user can do some time-consuming
 215  * or sleepable operations under the hardware lock.
 216  *
 217  * Returns 0 if we successfully locked the hwspinlock, -EBUSY if
 218  * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid.
 219  */
 220 static inline int hwspin_trylock_raw(struct hwspinlock *hwlock)
 221 {
 222         return __hwspin_trylock(hwlock, HWLOCK_RAW, NULL);
 223 }
 224
 225 /**
 226  * hwspin_trylock() - attempt to lock a specific hwspinlock
 227  * @hwlock: an hwspinlock which we want to trylock
 228  *
 229  * This function attempts to lock an hwspinlock, and will immediately fail
 230  * if the hwspinlock is already taken.
 231  *
 232  * Upon a successful return from this function, preemption is disabled,
 233  * so the caller must not sleep, and is advised to release the hwspinlock
 234  * as soon as possible. This is required in order to minimize remote cores
 235  * polling on the hardware interconnect.
 236  *
 237  * Returns 0 if we successfully locked the hwspinlock, -EBUSY if
 238  * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid.
 239  */
 240 static inline int hwspin_trylock(struct hwspinlock *hwlock)
 241 {
 242         return __hwspin_trylock(hwlock, 0, NULL);
 243 }
 244
 245 /**
 246  * hwspin_lock_timeout_irqsave() - lock hwspinlock, with timeout, disable irqs
 247  * @hwlock: the hwspinlock to be locked
 248  * @to: timeout value in msecs
 249  * @flags: a pointer to where the caller's interrupt state will be saved at
 250  *
 251  * This function locks the underlying @hwlock. If the @hwlock
 252  * is already taken, the function will busy loop waiting for it to
 253  * be released, but give up when @timeout msecs have elapsed.
 254  *
 255  * Upon a successful return from this function, preemption and local interrupts
 256  * are disabled (plus previous interrupt state is saved), so the caller must
 257  * not sleep, and is advised to release the hwspinlock as soon as possible.
 258  *
 259  * Returns 0 when the @hwlock was successfully taken, and an appropriate
 260  * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still
 261  * busy after @timeout msecs). The function will never sleep.
 262  */
 263 static inline int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock,
 264                                 unsigned int to, unsigned long *flags)
 265 {
 266         return __hwspin_lock_timeout(hwlock, to, HWLOCK_IRQSTATE, flags);
 267 }
 268
 269 /**
 270  * hwspin_lock_timeout_irq() - lock hwspinlock, with timeout, disable irqs
 271  * @hwlock: the hwspinlock to be locked
 272  * @to: timeout value in msecs
 273  *
 274  * This function locks the underlying @hwlock. If the @hwlock
 275  * is already taken, the function will busy loop waiting for it to
 276  * be released, but give up when @timeout msecs have elapsed.
 277  *
 278  * Upon a successful return from this function, preemption and local interrupts
 279  * are disabled so the caller must not sleep, and is advised to release the
 280  * hwspinlock as soon as possible.
 281  *
 282  * Returns 0 when the @hwlock was successfully taken, and an appropriate
 283  * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still
 284  * busy after @timeout msecs). The function will never sleep.
 285  */
 286 static inline
 287 int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int to)
 288 {
 289         return __hwspin_lock_timeout(hwlock, to, HWLOCK_IRQ, NULL);
 290 }
 291
 292 /**
 293  * hwspin_lock_timeout_raw() - lock an hwspinlock with timeout limit
 294  * @hwlock: the hwspinlock to be locked
 295  * @to: timeout value in msecs
 296  *
 297  * This function locks the underlying @hwlock. If the @hwlock
 298  * is already taken, the function will busy loop waiting for it to
 299  * be released, but give up when @timeout msecs have elapsed.
 300  *
 301  * Caution: User must protect the routine of getting hardware lock with mutex
 302  * or spinlock to avoid dead-lock, that will let user can do some time-consuming
 303  * or sleepable operations under the hardware lock.
 304  *
 305  * Returns 0 when the @hwlock was successfully taken, and an appropriate
 306  * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still
 307  * busy after @timeout msecs). The function will never sleep.
 308  */
 309 static inline
 310 int hwspin_lock_timeout_raw(struct hwspinlock *hwlock, unsigned int to)
 311 {
 312         return __hwspin_lock_timeout(hwlock, to, HWLOCK_RAW, NULL);
 313 }
 314
 315 /**
 316  * hwspin_lock_timeout() - lock an hwspinlock with timeout limit
 317  * @hwlock: the hwspinlock to be locked
 318  * @to: timeout value in msecs
 319  *
 320  * This function locks the underlying @hwlock. If the @hwlock
 321  * is already taken, the function will busy loop waiting for it to
 322  * be released, but give up when @timeout msecs have elapsed.
 323  *
 324  * Upon a successful return from this function, preemption is disabled
 325  * so the caller must not sleep, and is advised to release the hwspinlock
 326  * as soon as possible.
 327  * This is required in order to minimize remote cores polling on the
 328  * hardware interconnect.
 329  *
 330  * Returns 0 when the @hwlock was successfully taken, and an appropriate
 331  * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still
 332  * busy after @timeout msecs). The function will never sleep.
 333  */
 334 static inline
 335 int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int to)
 336 {
 337         return __hwspin_lock_timeout(hwlock, to, 0, NULL);
 338 }
 339
 340 /**
 341  * hwspin_unlock_irqrestore() - unlock hwspinlock, restore irq state
 342  * @hwlock: a previously-acquired hwspinlock which we want to unlock
 343  * @flags: previous caller's interrupt state to restore
 344  *
 345  * This function will unlock a specific hwspinlock, enable preemption and
 346  * restore the previous state of the local interrupts. It should be used
 347  * to undo, e.g., hwspin_trylock_irqsave().
 348  *
 349  * @hwlock must be already locked before calling this function: it is a bug
 350  * to call unlock on a @hwlock that is already unlocked.
 351  */
 352 static inline void hwspin_unlock_irqrestore(struct hwspinlock *hwlock,
 353                                                         unsigned long *flags)
 354 {
 355         __hwspin_unlock(hwlock, HWLOCK_IRQSTATE, flags);
 356 }
 357
 358 /**
 359  * hwspin_unlock_irq() - unlock hwspinlock, enable interrupts
 360  * @hwlock: a previously-acquired hwspinlock which we want to unlock
 361  *
 362  * This function will unlock a specific hwspinlock, enable preemption and
 363  * enable local interrupts. Should be used to undo hwspin_lock_irq().
 364  *
 365  * @hwlock must be already locked (e.g. by hwspin_trylock_irq()) before
 366  * calling this function: it is a bug to call unlock on a @hwlock that is
 367  * already unlocked.
 368  */
 369 static inline void hwspin_unlock_irq(struct hwspinlock *hwlock)
 370 {
 371         __hwspin_unlock(hwlock, HWLOCK_IRQ, NULL);
 372 }
 373
 374 /**
 375  * hwspin_unlock_raw() - unlock hwspinlock
 376  * @hwlock: a previously-acquired hwspinlock which we want to unlock
 377  *
 378  * This function will unlock a specific hwspinlock.
 379  *
 380  * @hwlock must be already locked (e.g. by hwspin_trylock()) before calling
 381  * this function: it is a bug to call unlock on a @hwlock that is already
 382  * unlocked.
 383  */
 384 static inline void hwspin_unlock_raw(struct hwspinlock *hwlock)
 385 {
 386         __hwspin_unlock(hwlock, HWLOCK_RAW, NULL);
 387 }
 388
 389 /**
 390  * hwspin_unlock() - unlock hwspinlock
 391  * @hwlock: a previously-acquired hwspinlock which we want to unlock
 392  *
 393  * This function will unlock a specific hwspinlock and enable preemption
 394  * back.
 395  *
 396  * @hwlock must be already locked (e.g. by hwspin_trylock()) before calling
 397  * this function: it is a bug to call unlock on a @hwlock that is already
 398  * unlocked.
 399  */
 400 static inline void hwspin_unlock(struct hwspinlock *hwlock)
 401 {
 402         __hwspin_unlock(hwlock, 0, NULL);
 403 }
 404
 405 #endif /* __LINUX_HWSPINLOCK_H */