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