linux/include/linux/hwspinlock.h
<<
>>
Prefs
   1/*
   2 * Hardware spinlock public header
   3 *
   4 * Copyright (C) 2010 Texas Instruments Incorporated - http://www.ti.com
   5 *
   6 * Contact: Ohad Ben-Cohen <ohad@wizery.com>
   7 *
   8 * This program is free software; you can redistribute it and/or modify it
   9 * under the terms of the GNU General Public License version 2 as published
  10 * by the Free Software Foundation.
  11 *
  12 * This program is distributed in the hope that it will be useful,
  13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 * GNU General Public License for more details.
  16 */
  17
  18#ifndef __LINUX_HWSPINLOCK_H
  19#define __LINUX_HWSPINLOCK_H
  20
  21#include <linux/err.h>
  22#include <linux/sched.h>
  23
  24/* hwspinlock mode argument */
  25#define HWLOCK_IRQSTATE 0x01    /* Disable interrupts, save state */
  26#define HWLOCK_IRQ      0x02    /* Disable interrupts, don't save state */
  27
  28struct device;
  29struct hwspinlock;
  30struct hwspinlock_device;
  31struct hwspinlock_ops;
  32
  33/**
  34 * struct hwspinlock_pdata - platform data for hwspinlock drivers
  35 * @base_id: base id for this hwspinlock device
  36 *
  37 * hwspinlock devices provide system-wide hardware locks that are used
  38 * by remote processors that have no other way to achieve synchronization.
  39 *
  40 * To achieve that, each physical lock must have a system-wide id number
  41 * that is agreed upon, otherwise remote processors can't possibly assume
  42 * they're using the same hardware lock.
  43 *
  44 * Usually boards have a single hwspinlock device, which provides several
  45 * hwspinlocks, and in this case, they can be trivially numbered 0 to
  46 * (num-of-locks - 1).
  47 *
  48 * In case boards have several hwspinlocks devices, a different base id
  49 * should be used for each hwspinlock device (they can't all use 0 as
  50 * a starting id!).
  51 *
  52 * This platform data structure should be used to provide the base id
  53 * for each device (which is trivially 0 when only a single hwspinlock
  54 * device exists). It can be shared between different platforms, hence
  55 * its location.
  56 */
  57struct hwspinlock_pdata {
  58        int base_id;
  59};
  60
  61#if defined(CONFIG_HWSPINLOCK) || defined(CONFIG_HWSPINLOCK_MODULE)
  62
  63int hwspin_lock_register(struct hwspinlock_device *bank, struct device *dev,
  64                const struct hwspinlock_ops *ops, int base_id, int num_locks);
  65int hwspin_lock_unregister(struct hwspinlock_device *bank);
  66struct hwspinlock *hwspin_lock_request(void);
  67struct hwspinlock *hwspin_lock_request_specific(unsigned int id);
  68int hwspin_lock_free(struct hwspinlock *hwlock);
  69int hwspin_lock_get_id(struct hwspinlock *hwlock);
  70int __hwspin_lock_timeout(struct hwspinlock *, unsigned int, int,
  71                                                        unsigned long *);
  72int __hwspin_trylock(struct hwspinlock *, int, unsigned long *);
  73void __hwspin_unlock(struct hwspinlock *, int, unsigned long *);
  74
  75#else /* !CONFIG_HWSPINLOCK */
  76
  77/*
  78 * We don't want these functions to fail if CONFIG_HWSPINLOCK is not
  79 * enabled. We prefer to silently succeed in this case, and let the
  80 * code path get compiled away. This way, if CONFIG_HWSPINLOCK is not
  81 * required on a given setup, users will still work.
  82 *
  83 * The only exception is hwspin_lock_register/hwspin_lock_unregister, with which
  84 * we _do_ want users to fail (no point in registering hwspinlock instances if
  85 * the framework is not available).
  86 *
  87 * Note: ERR_PTR(-ENODEV) will still be considered a success for NULL-checking
  88 * users. Others, which care, can still check this with IS_ERR.
  89 */
  90static inline struct hwspinlock *hwspin_lock_request(void)
  91{
  92        return ERR_PTR(-ENODEV);
  93}
  94
  95static inline struct hwspinlock *hwspin_lock_request_specific(unsigned int id)
  96{
  97        return ERR_PTR(-ENODEV);
  98}
  99
 100static inline int hwspin_lock_free(struct hwspinlock *hwlock)
 101{
 102        return 0;
 103}
 104
 105static inline
 106int __hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int to,
 107                                        int mode, unsigned long *flags)
 108{
 109        return 0;
 110}
 111
 112static inline
 113int __hwspin_trylock(struct hwspinlock *hwlock, int mode, unsigned long *flags)
 114{
 115        return 0;
 116}
 117
 118static inline
 119void __hwspin_unlock(struct hwspinlock *hwlock, int mode, unsigned long *flags)
 120{
 121}
 122
 123static inline int hwspin_lock_get_id(struct hwspinlock *hwlock)
 124{
 125        return 0;
 126}
 127
 128#endif /* !CONFIG_HWSPINLOCK */
 129
 130/**
 131 * hwspin_trylock_irqsave() - try to lock an hwspinlock, disable interrupts
 132 * @hwlock: an hwspinlock which we want to trylock
 133 * @flags: a pointer to where the caller's interrupt state will be saved at
 134 *
 135 * This function attempts to lock the underlying hwspinlock, and will
 136 * immediately fail if the hwspinlock is already locked.
 137 *
 138 * Upon a successful return from this function, preemption and local
 139 * interrupts are disabled (previous interrupts state is saved at @flags),
 140 * so the caller must not sleep, and is advised to release the hwspinlock
 141 * as soon as possible.
 142 *
 143 * Returns 0 if we successfully locked the hwspinlock, -EBUSY if
 144 * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid.
 145 */
 146static inline
 147int hwspin_trylock_irqsave(struct hwspinlock *hwlock, unsigned long *flags)
 148{
 149        return __hwspin_trylock(hwlock, HWLOCK_IRQSTATE, flags);
 150}
 151
 152/**
 153 * hwspin_trylock_irq() - try to lock an hwspinlock, disable interrupts
 154 * @hwlock: an hwspinlock which we want to trylock
 155 *
 156 * This function attempts to lock the underlying hwspinlock, and will
 157 * immediately fail if the hwspinlock is already locked.
 158 *
 159 * Upon a successful return from this function, preemption and local
 160 * interrupts are disabled, so the caller must not sleep, and is advised
 161 * to release the hwspinlock as soon as possible.
 162 *
 163 * Returns 0 if we successfully locked the hwspinlock, -EBUSY if
 164 * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid.
 165 */
 166static inline int hwspin_trylock_irq(struct hwspinlock *hwlock)
 167{
 168        return __hwspin_trylock(hwlock, HWLOCK_IRQ, NULL);
 169}
 170
 171/**
 172 * hwspin_trylock() - attempt to lock a specific hwspinlock
 173 * @hwlock: an hwspinlock which we want to trylock
 174 *
 175 * This function attempts to lock an hwspinlock, and will immediately fail
 176 * if the hwspinlock is already taken.
 177 *
 178 * Upon a successful return from this function, preemption is disabled,
 179 * so the caller must not sleep, and is advised to release the hwspinlock
 180 * as soon as possible. This is required in order to minimize remote cores
 181 * polling on the hardware interconnect.
 182 *
 183 * Returns 0 if we successfully locked the hwspinlock, -EBUSY if
 184 * the hwspinlock was already taken, and -EINVAL if @hwlock is invalid.
 185 */
 186static inline int hwspin_trylock(struct hwspinlock *hwlock)
 187{
 188        return __hwspin_trylock(hwlock, 0, NULL);
 189}
 190
 191/**
 192 * hwspin_lock_timeout_irqsave() - lock hwspinlock, with timeout, disable irqs
 193 * @hwlock: the hwspinlock to be locked
 194 * @to: timeout value in msecs
 195 * @flags: a pointer to where the caller's interrupt state will be saved at
 196 *
 197 * This function locks the underlying @hwlock. If the @hwlock
 198 * is already taken, the function will busy loop waiting for it to
 199 * be released, but give up when @timeout msecs have elapsed.
 200 *
 201 * Upon a successful return from this function, preemption and local interrupts
 202 * are disabled (plus previous interrupt state is saved), so the caller must
 203 * not sleep, and is advised to release the hwspinlock as soon as possible.
 204 *
 205 * Returns 0 when the @hwlock was successfully taken, and an appropriate
 206 * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still
 207 * busy after @timeout msecs). The function will never sleep.
 208 */
 209static inline int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock,
 210                                unsigned int to, unsigned long *flags)
 211{
 212        return __hwspin_lock_timeout(hwlock, to, HWLOCK_IRQSTATE, flags);
 213}
 214
 215/**
 216 * hwspin_lock_timeout_irq() - lock hwspinlock, with timeout, disable irqs
 217 * @hwlock: the hwspinlock to be locked
 218 * @to: timeout value in msecs
 219 *
 220 * This function locks the underlying @hwlock. If the @hwlock
 221 * is already taken, the function will busy loop waiting for it to
 222 * be released, but give up when @timeout msecs have elapsed.
 223 *
 224 * Upon a successful return from this function, preemption and local interrupts
 225 * are disabled so the caller must not sleep, and is advised to release the
 226 * hwspinlock as soon as possible.
 227 *
 228 * Returns 0 when the @hwlock was successfully taken, and an appropriate
 229 * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still
 230 * busy after @timeout msecs). The function will never sleep.
 231 */
 232static inline
 233int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int to)
 234{
 235        return __hwspin_lock_timeout(hwlock, to, HWLOCK_IRQ, NULL);
 236}
 237
 238/**
 239 * hwspin_lock_timeout() - lock an hwspinlock with timeout limit
 240 * @hwlock: the hwspinlock to be locked
 241 * @to: timeout value in msecs
 242 *
 243 * This function locks the underlying @hwlock. If the @hwlock
 244 * is already taken, the function will busy loop waiting for it to
 245 * be released, but give up when @timeout msecs have elapsed.
 246 *
 247 * Upon a successful return from this function, preemption is disabled
 248 * so the caller must not sleep, and is advised to release the hwspinlock
 249 * as soon as possible.
 250 * This is required in order to minimize remote cores polling on the
 251 * hardware interconnect.
 252 *
 253 * Returns 0 when the @hwlock was successfully taken, and an appropriate
 254 * error code otherwise (most notably an -ETIMEDOUT if the @hwlock is still
 255 * busy after @timeout msecs). The function will never sleep.
 256 */
 257static inline
 258int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int to)
 259{
 260        return __hwspin_lock_timeout(hwlock, to, 0, NULL);
 261}
 262
 263/**
 264 * hwspin_unlock_irqrestore() - unlock hwspinlock, restore irq state
 265 * @hwlock: a previously-acquired hwspinlock which we want to unlock
 266 * @flags: previous caller's interrupt state to restore
 267 *
 268 * This function will unlock a specific hwspinlock, enable preemption and
 269 * restore the previous state of the local interrupts. It should be used
 270 * to undo, e.g., hwspin_trylock_irqsave().
 271 *
 272 * @hwlock must be already locked before calling this function: it is a bug
 273 * to call unlock on a @hwlock that is already unlocked.
 274 */
 275static inline void hwspin_unlock_irqrestore(struct hwspinlock *hwlock,
 276                                                        unsigned long *flags)
 277{
 278        __hwspin_unlock(hwlock, HWLOCK_IRQSTATE, flags);
 279}
 280
 281/**
 282 * hwspin_unlock_irq() - unlock hwspinlock, enable interrupts
 283 * @hwlock: a previously-acquired hwspinlock which we want to unlock
 284 *
 285 * This function will unlock a specific hwspinlock, enable preemption and
 286 * enable local interrupts. Should be used to undo hwspin_lock_irq().
 287 *
 288 * @hwlock must be already locked (e.g. by hwspin_trylock_irq()) before
 289 * calling this function: it is a bug to call unlock on a @hwlock that is
 290 * already unlocked.
 291 */
 292static inline void hwspin_unlock_irq(struct hwspinlock *hwlock)
 293{
 294        __hwspin_unlock(hwlock, HWLOCK_IRQ, NULL);
 295}
 296
 297/**
 298 * hwspin_unlock() - unlock hwspinlock
 299 * @hwlock: a previously-acquired hwspinlock which we want to unlock
 300 *
 301 * This function will unlock a specific hwspinlock and enable preemption
 302 * back.
 303 *
 304 * @hwlock must be already locked (e.g. by hwspin_trylock()) before calling
 305 * this function: it is a bug to call unlock on a @hwlock that is already
 306 * unlocked.
 307 */
 308static inline void hwspin_unlock(struct hwspinlock *hwlock)
 309{
 310        __hwspin_unlock(hwlock, 0, NULL);
 311}
 312
 313#endif /* __LINUX_HWSPINLOCK_H */
 314
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.