summaryrefslogtreecommitdiff
path: root/Documentation/hwspinlock.txt
diff options
context:
space:
mode:
authorOhad Ben-Cohen <ohad@wizery.com>2011-09-06 15:39:21 +0300
committerOhad Ben-Cohen <ohad@wizery.com>2011-09-21 19:45:34 +0300
commit300bab9770e2bd10262bcc78e7249fdce2c74b38 (patch)
tree5c23d7dce82b96fa177ea7c854de7f4b36992c80 /Documentation/hwspinlock.txt
parentc536abfdf5227987b8a72ff955b64e62fd58fe91 (diff)
downloadkernel-300bab9770e2bd10262bcc78e7249fdce2c74b38.tar.gz
hwspinlock/core: register a bank of hwspinlocks in a single API call
Hardware Spinlock devices usually contain numerous locks (known devices today support between 32 to 256 locks). Originally hwspinlock core required drivers to register (and later, when needed, unregister) each lock separately. That worked, but required hwspinlocks drivers to do a bit extra work when they were probed/removed. This patch changes hwspin_lock_{un}register() to allow a bank of hwspinlocks to be {un}registered in a single invocation. A new 'struct hwspinlock_device', which contains an array of 'struct hwspinlock's is now being passed to the core upon registration (so instead of wrapping each struct hwspinlock, a priv member has been added to allow drivers to piggyback their private data with each hwspinlock). While at it, several per-lock members were moved to be per-device: 1. struct device *dev 2. struct hwspinlock_ops *ops In addition, now that the array of locks is handled by the core, there's no reason to maintain a per-lock 'int id' member: the id of the lock anyway equals to its index in the bank's array plus the bank's base_id. Remove this per-lock id member too, and instead use a simple pointers arithmetic to derive it. As a result of this change, hwspinlocks drivers are now simpler and smaller (about %20 code reduction) and the memory footprint of the hwspinlock framework is reduced. Signed-off-by: Ohad Ben-Cohen <ohad@wizery.com>
Diffstat (limited to 'Documentation/hwspinlock.txt')
-rw-r--r--Documentation/hwspinlock.txt58
1 files changed, 39 insertions, 19 deletions
diff --git a/Documentation/hwspinlock.txt b/Documentation/hwspinlock.txt
index 9171f9120143..a903ee5e9776 100644
--- a/Documentation/hwspinlock.txt
+++ b/Documentation/hwspinlock.txt
@@ -227,42 +227,62 @@ int hwspinlock_example2(void)
4. API for implementors
- int hwspin_lock_register(struct hwspinlock *hwlock);
+ int hwspin_lock_register(struct hwspinlock_device *bank, struct device *dev,
+ const struct hwspinlock_ops *ops, int base_id, int num_locks);
- to be called from the underlying platform-specific implementation, in
- order to register a new hwspinlock instance. Should be called from
- a process context (this function might sleep).
+ order to register a new hwspinlock device (which is usually a bank of
+ numerous locks). Should be called from a process context (this function
+ might sleep).
Returns 0 on success, or appropriate error code on failure.
- struct hwspinlock *hwspin_lock_unregister(unsigned int id);
+ int hwspin_lock_unregister(struct hwspinlock_device *bank);
- to be called from the underlying vendor-specific implementation, in order
- to unregister an existing (and unused) hwspinlock instance.
+ to unregister an hwspinlock device (which is usually a bank of numerous
+ locks).
Should be called from a process context (this function might sleep).
Returns the address of hwspinlock on success, or NULL on error (e.g.
if the hwspinlock is sill in use).
-5. struct hwspinlock
+5. Important structs
-This struct represents an hwspinlock instance. It is registered by the
-underlying hwspinlock implementation using the hwspin_lock_register() API.
+struct hwspinlock_device is a device which usually contains a bank
+of hardware locks. It is registered by the underlying hwspinlock
+implementation using the hwspin_lock_register() API.
/**
- * struct hwspinlock - vendor-specific hwspinlock implementation
- *
- * @dev: underlying device, will be used with runtime PM api
- * @ops: vendor-specific hwspinlock handlers
- * @id: a global, unique, system-wide, index of the lock.
- * @lock: initialized and used by hwspinlock core
+ * struct hwspinlock_device - a device which usually spans numerous hwspinlocks
+ * @dev: underlying device, will be used to invoke runtime PM api
+ * @ops: platform-specific hwspinlock handlers
+ * @base_id: id index of the first lock in this device
+ * @num_locks: number of locks in this device
+ * @lock: dynamically allocated array of 'struct hwspinlock'
*/
-struct hwspinlock {
+struct hwspinlock_device {
struct device *dev;
const struct hwspinlock_ops *ops;
- int id;
+ int base_id;
+ int num_locks;
+ struct hwspinlock lock[0];
+};
+
+struct hwspinlock_device contains an array of hwspinlock structs, each
+of which represents a single hardware lock:
+
+/**
+ * struct hwspinlock - this struct represents a single hwspinlock instance
+ * @bank: the hwspinlock_device structure which owns this lock
+ * @lock: initialized and used by hwspinlock core
+ * @priv: private data, owned by the underlying platform-specific hwspinlock drv
+ */
+struct hwspinlock {
+ struct hwspinlock_device *bank;
spinlock_t lock;
+ void *priv;
};
-The underlying implementation is responsible to assign the dev, ops and id
-members. The lock member, OTOH, is initialized and used by the hwspinlock
-core.
+When registering a bank of locks, the hwspinlock driver only needs to
+set the priv members of the locks. The rest of the members are set and
+initialized by the hwspinlock core itself.
6. Implementation callbacks