ipc: document general ipc locking scheme

[mirror_ubuntu-zesty-kernel.git] / ipc / util.c

diff --git a/ipc/util.c b/ipc/util.c
index 4704223bfad48e41258e018266feb9f5ed4b860e..1ddadcf9a2abdc6c3928d9fed415b81cab104baf 100644 (file)
--- a/ipc/util.c
+++ b/ipc/util.c
@@ -15,6 +15,14 @@
  * Jun 2006 - namespaces ssupport
  *            OpenVZ, SWsoft Inc.
  *            Pavel Emelianov <xemul@openvz.org>
+ *
+ * General sysv ipc locking scheme:
+ *  when doing ipc id lookups, take the ids->rwsem
+ *      rcu_read_lock()
+ *          obtain the ipc object (kern_ipc_perm)
+ *          perform security, capabilities, auditing and permission checks, etc.
+ *          acquire the ipc lock (kern_ipc_perm.lock) throught ipc_lock_object()
+ *             perform data updates (ie: SET, RMID, LOCK/UNLOCK commands)
  */
 
 #include <linux/mm.h>
@@ -119,7 +127,7 @@ __initcall(ipc_init);
  
 void ipc_init_ids(struct ipc_ids *ids)
 {
-       init_rwsem(&ids->rw_mutex);
+       init_rwsem(&ids->rwsem);
 
        ids->in_use = 0;
        ids->seq = 0;
@@ -174,7 +182,7 @@ void __init ipc_init_proc_interface(const char *path, const char *header,
  *     @ids: Identifier set
  *     @key: The key to find
  *     
- *     Requires ipc_ids.rw_mutex locked.
+ *     Requires ipc_ids.rwsem locked.
  *     Returns the LOCKED pointer to the ipc structure if found or NULL
  *     if not.
  *     If key is found ipc points to the owning ipc structure
@@ -208,7 +216,7 @@ static struct kern_ipc_perm *ipc_findkey(struct ipc_ids *ids, key_t key)
  *     ipc_get_maxid   -       get the last assigned id
  *     @ids: IPC identifier set
  *
- *     Called with ipc_ids.rw_mutex held.
+ *     Called with ipc_ids.rwsem held.
  */
 
 int ipc_get_maxid(struct ipc_ids *ids)
@@ -246,7 +254,7 @@ int ipc_get_maxid(struct ipc_ids *ids)
  *     is returned. The 'new' entry is returned in a locked state on success.
  *     On failure the entry is not locked and a negative err-code is returned.
  *
- *     Called with writer ipc_ids.rw_mutex held.
+ *     Called with writer ipc_ids.rwsem held.
  */
 int ipc_addid(struct ipc_ids* ids, struct kern_ipc_perm* new, int size)
 {
@@ -312,9 +320,9 @@ static int ipcget_new(struct ipc_namespace *ns, struct ipc_ids *ids,
 {
        int err;
 
-       down_write(&ids->rw_mutex);
+       down_write(&ids->rwsem);
        err = ops->getnew(ns, params);
-       up_write(&ids->rw_mutex);
+       up_write(&ids->rwsem);
        return err;
 }
 
@@ -331,7 +339,7 @@ static int ipcget_new(struct ipc_namespace *ns, struct ipc_ids *ids,
  *
  *     On success, the IPC id is returned.
  *
- *     It is called with ipc_ids.rw_mutex and ipcp->lock held.
+ *     It is called with ipc_ids.rwsem and ipcp->lock held.
  */
 static int ipc_check_perms(struct ipc_namespace *ns,
                           struct kern_ipc_perm *ipcp,
@@ -376,7 +384,7 @@ static int ipcget_public(struct ipc_namespace *ns, struct ipc_ids *ids,
         * Take the lock as a writer since we are potentially going to add
         * a new entry + read locks are not "upgradable"
         */
-       down_write(&ids->rw_mutex);
+       down_write(&ids->rwsem);
        ipcp = ipc_findkey(ids, params->key);
        if (ipcp == NULL) {
                /* key not used */
@@ -402,7 +410,7 @@ static int ipcget_public(struct ipc_namespace *ns, struct ipc_ids *ids,
                }
                ipc_unlock(ipcp);
        }
-       up_write(&ids->rw_mutex);
+       up_write(&ids->rwsem);
 
        return err;
 }
@@ -413,7 +421,7 @@ static int ipcget_public(struct ipc_namespace *ns, struct ipc_ids *ids,
  *     @ids: IPC identifier set
  *     @ipcp: ipc perm structure containing the identifier to remove
  *
- *     ipc_ids.rw_mutex (as a writer) and the spinlock for this ID are held
+ *     ipc_ids.rwsem (as a writer) and the spinlock for this ID are held
  *     before this function is called, and remain locked on the exit.
  */
  
@@ -621,7 +629,7 @@ struct kern_ipc_perm *ipc_obtain_object(struct ipc_ids *ids, int id)
 }
 
 /**
- * ipc_lock - Lock an ipc structure without rw_mutex held
+ * ipc_lock - Lock an ipc structure without rwsem held
  * @ids: IPC identifier set
  * @id: ipc id to look for
  *
@@ -733,7 +741,7 @@ int ipc_update_perm(struct ipc64_perm *in, struct kern_ipc_perm *out)
 }
 
 /**
- * ipcctl_pre_down - retrieve an ipc and check permissions for some IPC_XXX cmd
+ * ipcctl_pre_down_nolock - retrieve an ipc and check permissions for some IPC_XXX cmd
  * @ns:  the ipc namespace
  * @ids:  the table of ids where to look for the ipc
  * @id:   the id of the ipc to retrieve
@@ -746,29 +754,13 @@ int ipc_update_perm(struct ipc64_perm *in, struct kern_ipc_perm *out)
  * It must be called without any lock held and
  *  - retrieves the ipc with the given id in the given table.
  *  - performs some audit and permission check, depending on the given cmd
- *  - returns the ipc with the ipc lock held in case of success
- *    or an err-code without any lock held otherwise.
+ *  - returns a pointer to the ipc object or otherwise, the corresponding error.
  *
- * Call holding the both the rw_mutex and the rcu read lock.
+ * Call holding the both the rwsem and the rcu read lock.
  */
-struct kern_ipc_perm *ipcctl_pre_down(struct ipc_namespace *ns,
-                                     struct ipc_ids *ids, int id, int cmd,
-                                     struct ipc64_perm *perm, int extra_perm)
-{
-       struct kern_ipc_perm *ipcp;
-
-       ipcp = ipcctl_pre_down_nolock(ns, ids, id, cmd, perm, extra_perm);
-       if (IS_ERR(ipcp))
-               goto out;
-
-       spin_lock(&ipcp->lock);
-out:
-       return ipcp;
-}
-
 struct kern_ipc_perm *ipcctl_pre_down_nolock(struct ipc_namespace *ns,
-                                            struct ipc_ids *ids, int id, int cmd,
-                                            struct ipc64_perm *perm, int extra_perm)
+                                       struct ipc_ids *ids, int id, int cmd,
+                                       struct ipc64_perm *perm, int extra_perm)
 {
        kuid_t euid;
        int err = -EPERM;
@@ -884,7 +876,7 @@ static void *sysvipc_proc_start(struct seq_file *s, loff_t *pos)
         * Take the lock - this will be released by the corresponding
         * call to stop().
         */
-       down_read(&ids->rw_mutex);
+       down_read(&ids->rwsem);
 
        /* pos < 0 is invalid */
        if (*pos < 0)
@@ -911,7 +903,7 @@ static void sysvipc_proc_stop(struct seq_file *s, void *it)
 
        ids = &iter->ns->ids[iface->ids];
        /* Release the lock we took in start() */
-       up_read(&ids->rw_mutex);
+       up_read(&ids->rwsem);
 }
 
 static int sysvipc_proc_show(struct seq_file *s, void *it)