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