Documentation/hwspinlock.txt

   1 ===========================
   2 Hardware Spinlock Framework
   3 ===========================
   4
   5 Introduction
   6 ============
   7
   8 Hardware spinlock modules provide hardware assistance for synchronization
   9 and mutual exclusion between heterogeneous processors and those not operating
  10 under a single, shared operating system.
  11
  12 For example, OMAP4 has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP,
  13 each of which is running a different Operating System (the master, A9,
  14 is usually running Linux and the slave processors, the M3 and the DSP,
  15 are running some flavor of RTOS).
  16
  17 A generic hwspinlock framework allows platform-independent drivers to use
  18 the hwspinlock device in order to access data structures that are shared
  19 between remote processors, that otherwise have no alternative mechanism
  20 to accomplish synchronization and mutual exclusion operations.
  21
  22 This is necessary, for example, for Inter-processor communications:
  23 on OMAP4, cpu-intensive multimedia tasks are offloaded by the host to the
  24 remote M3 and/or C64x+ slave processors (by an IPC subsystem called Syslink).
  25
  26 To achieve fast message-based communications, a minimal kernel support
  27 is needed to deliver messages arriving from a remote processor to the
  28 appropriate user process.
  29
  30 This communication is based on simple data structures that is shared between
  31 the remote processors, and access to it is synchronized using the hwspinlock
  32 module (remote processor directly places new messages in this shared data
  33 structure).
  34
  35 A common hwspinlock interface makes it possible to have generic, platform-
  36 independent, drivers.
  37
  38 User API
  39 ========
  40
  41 ::
  42
  43   struct hwspinlock *hwspin_lock_request(void);
  44
  45 Dynamically assign an hwspinlock and return its address, or NULL
  46 in case an unused hwspinlock isn't available. Users of this
  47 API will usually want to communicate the lock's id to the remote core
  48 before it can be used to achieve synchronization.
  49
  50 Should be called from a process context (might sleep).
  51
  52 ::
  53
  54   struct hwspinlock *hwspin_lock_request_specific(unsigned int id);
  55
  56 Assign a specific hwspinlock id and return its address, or NULL
  57 if that hwspinlock is already in use. Usually board code will
  58 be calling this function in order to reserve specific hwspinlock
  59 ids for predefined purposes.
  60
  61 Should be called from a process context (might sleep).
  62
  63 ::
  64
  65   int of_hwspin_lock_get_id(struct device_node *np, int index);
  66
  67 Retrieve the global lock id for an OF phandle-based specific lock.
  68 This function provides a means for DT users of a hwspinlock module
  69 to get the global lock id of a specific hwspinlock, so that it can
  70 be requested using the normal hwspin_lock_request_specific() API.
  71
  72 The function returns a lock id number on success, -EPROBE_DEFER if
  73 the hwspinlock device is not yet registered with the core, or other
  74 error values.
  75
  76 Should be called from a process context (might sleep).
  77
  78 ::
  79
  80   int hwspin_lock_free(struct hwspinlock *hwlock);
  81
  82 Free a previously-assigned hwspinlock; returns 0 on success, or an
  83 appropriate error code on failure (e.g. -EINVAL if the hwspinlock
  84 is already free).
  85
  86 Should be called from a process context (might sleep).
  87
  88 ::
  89
  90   int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int timeout);
  91
  92 Lock a previously-assigned hwspinlock with a timeout limit (specified in
  93 msecs). If the hwspinlock is already taken, the function will busy loop
  94 waiting for it to be released, but give up when the timeout elapses.
  95 Upon a successful return from this function, preemption is disabled so
  96 the caller must not sleep, and is advised to release the hwspinlock as
  97 soon as possible, in order to minimize remote cores polling on the
  98 hardware interconnect.
  99
 100 Returns 0 when successful and an appropriate error code otherwise (most
 101 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
 102 The function will never sleep.
 103
 104 ::
 105
 106   int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int timeout);
 107
 108 Lock a previously-assigned hwspinlock with a timeout limit (specified in
 109 msecs). If the hwspinlock is already taken, the function will busy loop
 110 waiting for it to be released, but give up when the timeout elapses.
 111 Upon a successful return from this function, preemption and the local
 112 interrupts are disabled, so the caller must not sleep, and is advised to
 113 release the hwspinlock as soon as possible.
 114
 115 Returns 0 when successful and an appropriate error code otherwise (most
 116 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
 117 The function will never sleep.
 118
 119 ::
 120
 121   int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock, unsigned int to,
 122                                   unsigned long *flags);
 123
 124 Lock a previously-assigned hwspinlock with a timeout limit (specified in
 125 msecs). If the hwspinlock is already taken, the function will busy loop
 126 waiting for it to be released, but give up when the timeout elapses.
 127 Upon a successful return from this function, preemption is disabled,
 128 local interrupts are disabled and their previous state is saved at the
 129 given flags placeholder. The caller must not sleep, and is advised to
 130 release the hwspinlock as soon as possible.
 131
 132 Returns 0 when successful and an appropriate error code otherwise (most
 133 notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
 134
 135 The function will never sleep.
 136
 137 ::
 138
 139   int hwspin_trylock(struct hwspinlock *hwlock);
 140
 141
 142 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
 143 it is already taken.
 144
 145 Upon a successful return from this function, preemption is disabled so
 146 caller must not sleep, and is advised to release the hwspinlock as soon as
 147 possible, in order to minimize remote cores polling on the hardware
 148 interconnect.
 149
 150 Returns 0 on success and an appropriate error code otherwise (most
 151 notably -EBUSY if the hwspinlock was already taken).
 152 The function will never sleep.
 153
 154 ::
 155
 156   int hwspin_trylock_irq(struct hwspinlock *hwlock);
 157
 158
 159 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
 160 it is already taken.
 161
 162 Upon a successful return from this function, preemption and the local
 163 interrupts are disabled so caller must not sleep, and is advised to
 164 release the hwspinlock as soon as possible.
 165
 166 Returns 0 on success and an appropriate error code otherwise (most
 167 notably -EBUSY if the hwspinlock was already taken).
 168
 169 The function will never sleep.
 170
 171 ::
 172
 173   int hwspin_trylock_irqsave(struct hwspinlock *hwlock, unsigned long *flags);
 174
 175 Attempt to lock a previously-assigned hwspinlock, but immediately fail if
 176 it is already taken.
 177
 178 Upon a successful return from this function, preemption is disabled,
 179 the local interrupts are disabled and their previous state is saved
 180 at the given flags placeholder. The caller must not sleep, and is advised
 181 to release the hwspinlock as soon as possible.
 182
 183 Returns 0 on success and an appropriate error code otherwise (most
 184 notably -EBUSY if the hwspinlock was already taken).
 185 The function will never sleep.
 186
 187 ::
 188
 189   void hwspin_unlock(struct hwspinlock *hwlock);
 190
 191 Unlock a previously-locked hwspinlock. Always succeed, and can be called
 192 from any context (the function never sleeps).
 193
 194 .. note::
 195
 196   code should **never** unlock an hwspinlock which is already unlocked
 197   (there is no protection against this).
 198
 199 ::
 200
 201   void hwspin_unlock_irq(struct hwspinlock *hwlock);
 202
 203 Unlock a previously-locked hwspinlock and enable local interrupts.
 204 The caller should **never** unlock an hwspinlock which is already unlocked.
 205
 206 Doing so is considered a bug (there is no protection against this).
 207 Upon a successful return from this function, preemption and local
 208 interrupts are enabled. This function will never sleep.
 209
 210 ::
 211
 212   void
 213   hwspin_unlock_irqrestore(struct hwspinlock *hwlock, unsigned long *flags);
 214
 215 Unlock a previously-locked hwspinlock.
 216
 217 The caller should **never** unlock an hwspinlock which is already unlocked.
 218 Doing so is considered a bug (there is no protection against this).
 219 Upon a successful return from this function, preemption is reenabled,
 220 and the state of the local interrupts is restored to the state saved at
 221 the given flags. This function will never sleep.
 222
 223 ::
 224
 225   int hwspin_lock_get_id(struct hwspinlock *hwlock);
 226
 227 Retrieve id number of a given hwspinlock. This is needed when an
 228 hwspinlock is dynamically assigned: before it can be used to achieve
 229 mutual exclusion with a remote cpu, the id number should be communicated
 230 to the remote task with which we want to synchronize.
 231
 232 Returns the hwspinlock id number, or -EINVAL if hwlock is null.
 233
 234 Typical usage
 235 =============
 236
 237 ::
 238
 239         #include <linux/hwspinlock.h>
 240         #include <linux/err.h>
 241
 242         int hwspinlock_example1(void)
 243         {
 244                 struct hwspinlock *hwlock;
 245                 int ret;
 246
 247                 /* dynamically assign a hwspinlock */
 248                 hwlock = hwspin_lock_request();
 249                 if (!hwlock)
 250                         ...
 251
 252                 id = hwspin_lock_get_id(hwlock);
 253                 /* probably need to communicate id to a remote processor now */
 254
 255                 /* take the lock, spin for 1 sec if it's already taken */
 256                 ret = hwspin_lock_timeout(hwlock, 1000);
 257                 if (ret)
 258                         ...
 259
 260                 /*
 261                 * we took the lock, do our thing now, but do NOT sleep
 262                 */
 263
 264                 /* release the lock */
 265                 hwspin_unlock(hwlock);
 266
 267                 /* free the lock */
 268                 ret = hwspin_lock_free(hwlock);
 269                 if (ret)
 270                         ...
 271
 272                 return ret;
 273         }
 274
 275         int hwspinlock_example2(void)
 276         {
 277                 struct hwspinlock *hwlock;
 278                 int ret;
 279
 280                 /*
 281                 * assign a specific hwspinlock id - this should be called early
 282                 * by board init code.
 283                 */
 284                 hwlock = hwspin_lock_request_specific(PREDEFINED_LOCK_ID);
 285                 if (!hwlock)
 286                         ...
 287
 288                 /* try to take it, but don't spin on it */
 289                 ret = hwspin_trylock(hwlock);
 290                 if (!ret) {
 291                         pr_info("lock is already taken\n");
 292                         return -EBUSY;
 293                 }
 294
 295                 /*
 296                 * we took the lock, do our thing now, but do NOT sleep
 297                 */
 298
 299                 /* release the lock */
 300                 hwspin_unlock(hwlock);
 301
 302                 /* free the lock */
 303                 ret = hwspin_lock_free(hwlock);
 304                 if (ret)
 305                         ...
 306
 307                 return ret;
 308         }
 309
 310
 311 API for implementors
 312 ====================
 313
 314 ::
 315
 316   int hwspin_lock_register(struct hwspinlock_device *bank, struct device *dev,
 317                 const struct hwspinlock_ops *ops, int base_id, int num_locks);
 318
 319 To be called from the underlying platform-specific implementation, in
 320 order to register a new hwspinlock device (which is usually a bank of
 321 numerous locks). Should be called from a process context (this function
 322 might sleep).
 323
 324 Returns 0 on success, or appropriate error code on failure.
 325
 326 ::
 327
 328   int hwspin_lock_unregister(struct hwspinlock_device *bank);
 329
 330 To be called from the underlying vendor-specific implementation, in order
 331 to unregister an hwspinlock device (which is usually a bank of numerous
 332 locks).
 333
 334 Should be called from a process context (this function might sleep).
 335
 336 Returns the address of hwspinlock on success, or NULL on error (e.g.
 337 if the hwspinlock is still in use).
 338
 339 Important structs
 340 =================
 341
 342 struct hwspinlock_device is a device which usually contains a bank
 343 of hardware locks. It is registered by the underlying hwspinlock
 344 implementation using the hwspin_lock_register() API.
 345
 346 ::
 347
 348         /**
 349         * struct hwspinlock_device - a device which usually spans numerous hwspinlocks
 350         * @dev: underlying device, will be used to invoke runtime PM api
 351         * @ops: platform-specific hwspinlock handlers
 352         * @base_id: id index of the first lock in this device
 353         * @num_locks: number of locks in this device
 354         * @lock: dynamically allocated array of 'struct hwspinlock'
 355         */
 356         struct hwspinlock_device {
 357                 struct device *dev;
 358                 const struct hwspinlock_ops *ops;
 359                 int base_id;
 360                 int num_locks;
 361                 struct hwspinlock lock[0];
 362         };
 363
 364 struct hwspinlock_device contains an array of hwspinlock structs, each
 365 of which represents a single hardware lock::
 366
 367         /**
 368         * struct hwspinlock - this struct represents a single hwspinlock instance
 369         * @bank: the hwspinlock_device structure which owns this lock
 370         * @lock: initialized and used by hwspinlock core
 371         * @priv: private data, owned by the underlying platform-specific hwspinlock drv
 372         */
 373         struct hwspinlock {
 374                 struct hwspinlock_device *bank;
 375                 spinlock_t lock;
 376                 void *priv;
 377         };
 378
 379 When registering a bank of locks, the hwspinlock driver only needs to
 380 set the priv members of the locks. The rest of the members are set and
 381 initialized by the hwspinlock core itself.
 382
 383 Implementation callbacks
 384 ========================
 385
 386 There are three possible callbacks defined in 'struct hwspinlock_ops'::
 387
 388         struct hwspinlock_ops {
 389                 int (*trylock)(struct hwspinlock *lock);
 390                 void (*unlock)(struct hwspinlock *lock);
 391                 void (*relax)(struct hwspinlock *lock);
 392         };
 393
 394 The first two callbacks are mandatory:
 395
 396 The ->trylock() callback should make a single attempt to take the lock, and
 397 return 0 on failure and 1 on success. This callback may **not** sleep.
 398
 399 The ->unlock() callback releases the lock. It always succeed, and it, too,
 400 may **not** sleep.
 401
 402 The ->relax() callback is optional. It is called by hwspinlock core while
 403 spinning on a lock, and can be used by the underlying implementation to force
 404 a delay between two successive invocations of ->trylock(). It may **not** sleep.