[PATCH] Keys: Doc update on locking

The attached patch updates the documentation on the kernel keys to describe
the locking associated with keys and key type operations.
Signed-Off-By: David Howells <dhowells@redhat.com>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>

Documentation/keys.txt

@@ -606,8 +606,12 @@ open call, and the key released upon close. How to deal with conflicting keys
 due to two different users opening the same file is left to the filesystem
 author to solve.
 
-When accessing a key's payload data, the key->lock should be at least read
-locked, or else the data may be changed by update during the access.
+When accessing a key's payload data, key->lock should be at least read locked,
+or else the data may be changed by an update being performed from userspace
+whilst the driver or filesystem is trying to access it. If no update method is
+supplied, then the key's payload may be accessed without holding a lock as
+there is no way to change it, provided it can be guaranteed that the key's
+type definition won't go away.
 
 (*) To search for a key, call:
 
@@ -719,13 +723,19 @@ The structure has a number of fields, some of which are mandatory:
 
  (*) int (*instantiate)(struct key *key, const void *data, size_t datalen);
 
-     This method is called to attach a payload to a key during
-     construction. The payload attached need not bear any relation to the data
-     passed to this function.
+     This method is called to attach a payload to a key during construction.
+     The payload attached need not bear any relation to the data passed to
+     this function.
 
      If the amount of data attached to the key differs from the size in
      keytype->def_datalen, then key_payload_reserve() should be called.
 
+     This method does not have to lock the key in order to attach a payload.
+     The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
+     anything else from gaining access to the key.
+
+     This method may sleep if it wishes.
+
 
  (*) int (*duplicate)(struct key *key, const struct key *source);
 
@@ -734,8 +744,8 @@ The structure has a number of fields, some of which are mandatory:
      the new key. The data length on the new key will have been updated and
      the quota adjusted already.
 
-     The source key will be locked against change on the source->sem, so it is
-     safe to sleep here.
+     This method will be called with the source key's semaphore read-locked to
+     prevent its payload from being changed. It is safe to sleep here.
 
 
  (*) int (*update)(struct key *key, const void *data, size_t datalen);
@@ -749,30 +759,47 @@ The structure has a number of fields, some of which are mandatory:
      type is committed to changing the key because it's already been altered,
      so all memory allocation must be done first.
 
-     The key will be locked against other changers on key->sem, so it is safe
-     to sleep here.
-
      key_payload_reserve() should be called with the key->lock write locked,
      and the changes to the key's attached payload should be made before the
      key is locked.
 
+     The key will have its semaphore write-locked before this method is
+     called. Any changes to the key should be made with the key's rwlock
+     write-locked also. It is safe to sleep here.
+
 
  (*) int (*match)(const struct key *key, const void *desc);
 
      This method is called to match a key against a description. It should
      return non-zero if the two match, zero if they don't.
 
+     This method should not need to lock the key in any way. The type and
+     description can be considered invariant, and the payload should not be
+     accessed (the key may not yet be instantiated).
+
+     It is not safe to sleep in this method; the caller may hold spinlocks.
+
 
  (*) void (*destroy)(struct key *key);
 
      This method is optional. It is called to discard the payload data on a
      key when it is being destroyed.
 
+     This method does not need to lock the key; it can consider the key as
+     being inaccessible. Note that the key's type may have changed before this
+     function is called.
+
+     It is not safe to sleep in this method; the caller may hold spinlocks.
+
 
  (*) void (*describe)(const struct key *key, struct seq_file *p);
 
      This method is optional. It is called during /proc/keys reading to
-     summarise a key in text form.
+     summarise a key's description and payload in text form.
+
+     This method will be called with the key's rwlock read-locked. This will
+     prevent the key's payload and state changing; also the description should
+     not change. This also means it is not safe to sleep in this method.
 
 
  (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen);
@@ -785,6 +812,12 @@ The structure has a number of fields, some of which are mandatory:
      If successful, the blob size that could be produced should be returned
      rather than the size copied.
 
+     This method will be called with the key's semaphore read-locked. This
+     will prevent the key's payload changing. It is not necessary to also
+     read-lock key->lock when accessing the key's payload. It is safe to sleep
+     in this method, such as might happen when the userspace buffer is
+     accessed.
+
 
 ============================
 REQUEST-KEY CALLBACK SERVICE