ipc: standardize code comments

IPC commenting style is all over the place, *specially* in util.c.  This
patch orders things a bit.

Signed-off-by: Davidlohr Bueso <davidlohr@hp.com>
Cc: Aswin Chandramouleeswaran <aswin@hp.com>
Cc: Rik van Riel <riel@redhat.com>
Acked-by: Manfred Spraul <manfred@colorfullife.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
This commit is contained in:
Davidlohr Bueso 2014-01-27 17:07:05 -08:00 committed by Linus Torvalds
parent 239521f31d
commit 8001c85810
3 changed files with 122 additions and 136 deletions

View File

@ -225,7 +225,7 @@ static void unmerge_queues(struct sem_array *sma)
} }
/** /**
* merge_queues - Merge single semop queues into global queue * merge_queues - merge single semop queues into global queue
* @sma: semaphore array * @sma: semaphore array
* *
* This function merges all per-semaphore queues into the global queue. * This function merges all per-semaphore queues into the global queue.
@ -474,7 +474,6 @@ static inline void sem_rmid(struct ipc_namespace *ns, struct sem_array *s)
* *
* Called with sem_ids.rwsem held (as a writer) * Called with sem_ids.rwsem held (as a writer)
*/ */
static int newary(struct ipc_namespace *ns, struct ipc_params *params) static int newary(struct ipc_namespace *ns, struct ipc_params *params)
{ {
int id; int id;
@ -682,7 +681,7 @@ static void wake_up_sem_queue_prepare(struct list_head *pt,
} }
/** /**
* wake_up_sem_queue_do(pt) - do the actual wake-up * wake_up_sem_queue_do - do the actual wake-up
* @pt: list of tasks to be woken up * @pt: list of tasks to be woken up
* *
* Do the actual wake-up. * Do the actual wake-up.
@ -748,7 +747,7 @@ static int check_restart(struct sem_array *sma, struct sem_queue *q)
} }
/** /**
* wake_const_ops(sma, semnum, pt) - Wake up non-alter tasks * wake_const_ops - wake up non-alter tasks
* @sma: semaphore array. * @sma: semaphore array.
* @semnum: semaphore that was modified. * @semnum: semaphore that was modified.
* @pt: list head for the tasks that must be woken up. * @pt: list head for the tasks that must be woken up.
@ -798,15 +797,14 @@ static int wake_const_ops(struct sem_array *sma, int semnum,
} }
/** /**
* do_smart_wakeup_zero(sma, sops, nsops, pt) - wakeup all wait for zero tasks * do_smart_wakeup_zero - wakeup all wait for zero tasks
* @sma: semaphore array * @sma: semaphore array
* @sops: operations that were performed * @sops: operations that were performed
* @nsops: number of operations * @nsops: number of operations
* @pt: list head of the tasks that must be woken up. * @pt: list head of the tasks that must be woken up.
* *
* do_smart_wakeup_zero() checks all required queue for wait-for-zero * Checks all required queue for wait-for-zero operations, based
* operations, based on the actual changes that were performed on the * on the actual changes that were performed on the semaphore array.
* semaphore array.
* The function returns 1 if at least one operation was completed successfully. * The function returns 1 if at least one operation was completed successfully.
*/ */
static int do_smart_wakeup_zero(struct sem_array *sma, struct sembuf *sops, static int do_smart_wakeup_zero(struct sem_array *sma, struct sembuf *sops,
@ -850,7 +848,7 @@ static int do_smart_wakeup_zero(struct sem_array *sma, struct sembuf *sops,
/** /**
* update_queue(sma, semnum): Look for tasks that can be completed. * update_queue - look for tasks that can be completed.
* @sma: semaphore array. * @sma: semaphore array.
* @semnum: semaphore that was modified. * @semnum: semaphore that was modified.
* @pt: list head for the tasks that must be woken up. * @pt: list head for the tasks that must be woken up.
@ -920,7 +918,7 @@ again:
} }
/** /**
* set_semotime(sma, sops) - set sem_otime * set_semotime - set sem_otime
* @sma: semaphore array * @sma: semaphore array
* @sops: operations that modified the array, may be NULL * @sops: operations that modified the array, may be NULL
* *
@ -938,7 +936,7 @@ static void set_semotime(struct sem_array *sma, struct sembuf *sops)
} }
/** /**
* do_smart_update(sma, sops, nsops, otime, pt) - optimized update_queue * do_smart_update - optimized update_queue
* @sma: semaphore array * @sma: semaphore array
* @sops: operations that were performed * @sops: operations that were performed
* @nsops: number of operations * @nsops: number of operations
@ -1647,7 +1645,7 @@ static struct sem_undo *lookup_undo(struct sem_undo_list *ulp, int semid)
} }
/** /**
* find_alloc_undo - Lookup (and if not present create) undo array * find_alloc_undo - lookup (and if not present create) undo array
* @ns: namespace * @ns: namespace
* @semid: semaphore array id * @semid: semaphore array id
* *
@ -1737,7 +1735,7 @@ out:
/** /**
* get_queue_result - Retrieve the result code from sem_queue * get_queue_result - retrieve the result code from sem_queue
* @q: Pointer to queue structure * @q: Pointer to queue structure
* *
* Retrieve the return code from the pending queue. If IN_WAKEUP is found in * Retrieve the return code from the pending queue. If IN_WAKEUP is found in

View File

@ -477,7 +477,6 @@ static const struct vm_operations_struct shm_vm_ops = {
* *
* Called with shm_ids.rwsem held as a writer. * Called with shm_ids.rwsem held as a writer.
*/ */
static int newseg(struct ipc_namespace *ns, struct ipc_params *params) static int newseg(struct ipc_namespace *ns, struct ipc_params *params)
{ {
key_t key = params->key; key_t key = params->key;

View File

@ -110,15 +110,15 @@ static struct notifier_block ipc_memory_nb = {
}; };
/** /**
* ipc_init - initialise IPC subsystem * ipc_init - initialise ipc subsystem
*
* The various sysv ipc resources (semaphores, messages and shared
* memory) are initialised.
* *
* The various system5 IPC resources (semaphores, messages and shared
* memory) are initialised
* A callback routine is registered into the memory hotplug notifier * A callback routine is registered into the memory hotplug notifier
* chain: since msgmni scales to lowmem this callback routine will be * chain: since msgmni scales to lowmem this callback routine will be
* called upon successful memory add / remove to recompute msmgni. * called upon successful memory add / remove to recompute msmgni.
*/ */
static int __init ipc_init(void) static int __init ipc_init(void)
{ {
sem_init(); sem_init();
@ -131,13 +131,12 @@ static int __init ipc_init(void)
__initcall(ipc_init); __initcall(ipc_init);
/** /**
* ipc_init_ids - initialise IPC identifiers * ipc_init_ids - initialise ipc identifiers
* @ids: Identifier set * @ids: ipc identifier set
* *
* Set up the sequence range to use for the ipc identifier range (limited * Set up the sequence range to use for the ipc identifier range (limited
* below IPCMNI) then initialise the ids idr. * below IPCMNI) then initialise the ids idr.
*/ */
void ipc_init_ids(struct ipc_ids *ids) void ipc_init_ids(struct ipc_ids *ids)
{ {
init_rwsem(&ids->rwsem); init_rwsem(&ids->rwsem);
@ -159,7 +158,7 @@ void ipc_init_ids(struct ipc_ids *ids)
#ifdef CONFIG_PROC_FS #ifdef CONFIG_PROC_FS
static const struct file_operations sysvipc_proc_fops; static const struct file_operations sysvipc_proc_fops;
/** /**
* ipc_init_proc_interface - Create a proc interface for sysipc types using a seq_file interface. * ipc_init_proc_interface - create a proc interface for sysipc types using a seq_file interface.
* @path: Path in procfs * @path: Path in procfs
* @header: Banner to be printed at the beginning of the file. * @header: Banner to be printed at the beginning of the file.
* @ids: ipc id table to iterate. * @ids: ipc id table to iterate.
@ -192,15 +191,14 @@ void __init ipc_init_proc_interface(const char *path, const char *header,
/** /**
* ipc_findkey - find a key in an ipc identifier set * ipc_findkey - find a key in an ipc identifier set
* @ids: Identifier set * @ids: ipc identifier set
* @key: The key to find * @key: key to find
* *
* Requires ipc_ids.rwsem locked. * Returns the locked pointer to the ipc structure if found or NULL
* Returns the LOCKED pointer to the ipc structure if found or NULL * otherwise. If key is found ipc points to the owning ipc structure
* if not. *
* If key is found ipc points to the owning ipc structure * Called with ipc_ids.rwsem held.
*/ */
static struct kern_ipc_perm *ipc_findkey(struct ipc_ids *ids, key_t key) static struct kern_ipc_perm *ipc_findkey(struct ipc_ids *ids, key_t key)
{ {
struct kern_ipc_perm *ipc; struct kern_ipc_perm *ipc;
@ -228,11 +226,10 @@ static struct kern_ipc_perm *ipc_findkey(struct ipc_ids *ids, key_t key)
/** /**
* ipc_get_maxid - get the last assigned id * ipc_get_maxid - get the last assigned id
* @ids: IPC identifier set * @ids: ipc identifier set
* *
* Called with ipc_ids.rwsem held. * Called with ipc_ids.rwsem held.
*/ */
int ipc_get_maxid(struct ipc_ids *ids) int ipc_get_maxid(struct ipc_ids *ids)
{ {
struct kern_ipc_perm *ipc; struct kern_ipc_perm *ipc;
@ -258,12 +255,12 @@ int ipc_get_maxid(struct ipc_ids *ids)
} }
/** /**
* ipc_addid - add an IPC identifier * ipc_addid - add an ipc identifier
* @ids: IPC identifier set * @ids: ipc identifier set
* @new: new IPC permission set * @new: new ipc permission set
* @size: limit for the number of used ids * @size: limit for the number of used ids
* *
* Add an entry 'new' to the IPC ids idr. The permissions object is * Add an entry 'new' to the ipc ids idr. The permissions object is
* initialised and the first free entry is set up and the id assigned * initialised and the first free entry is set up and the id assigned
* is returned. The 'new' entry is returned in a locked state on success. * 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. * On failure the entry is not locked and a negative err-code is returned.
@ -321,8 +318,8 @@ int ipc_addid(struct ipc_ids *ids, struct kern_ipc_perm *new, int size)
/** /**
* ipcget_new - create a new ipc object * ipcget_new - create a new ipc object
* @ns: namespace * @ns: ipc namespace
* @ids: IPC identifer set * @ids: ipc identifer set
* @ops: the actual creation routine to call * @ops: the actual creation routine to call
* @params: its parameters * @params: its parameters
* *
@ -341,17 +338,17 @@ static int ipcget_new(struct ipc_namespace *ns, struct ipc_ids *ids,
} }
/** /**
* ipc_check_perms - check security and permissions for an IPC * ipc_check_perms - check security and permissions for an ipc object
* @ns: IPC namespace * @ns: ipc namespace
* @ipcp: ipc permission set * @ipcp: ipc permission set
* @ops: the actual security routine to call * @ops: the actual security routine to call
* @params: its parameters * @params: its parameters
* *
* This routine is called by sys_msgget(), sys_semget() and sys_shmget() * This routine is called by sys_msgget(), sys_semget() and sys_shmget()
* when the key is not IPC_PRIVATE and that key already exists in the * when the key is not IPC_PRIVATE and that key already exists in the
* ids IDR. * ds IDR.
* *
* On success, the IPC id is returned. * On success, the ipc id is returned.
* *
* It is called with ipc_ids.rwsem and ipcp->lock held. * It is called with ipc_ids.rwsem and ipcp->lock held.
*/ */
@ -375,8 +372,8 @@ static int ipc_check_perms(struct ipc_namespace *ns,
/** /**
* ipcget_public - get an ipc object or create a new one * ipcget_public - get an ipc object or create a new one
* @ns: namespace * @ns: ipc namespace
* @ids: IPC identifer set * @ids: ipc identifer set
* @ops: the actual creation routine to call * @ops: the actual creation routine to call
* @params: its parameters * @params: its parameters
* *
@ -431,14 +428,13 @@ static int ipcget_public(struct ipc_namespace *ns, struct ipc_ids *ids,
/** /**
* ipc_rmid - remove an IPC identifier * ipc_rmid - remove an ipc identifier
* @ids: IPC identifier set * @ids: ipc identifier set
* @ipcp: ipc perm structure containing the identifier to remove * @ipcp: ipc perm structure containing the identifier to remove
* *
* ipc_ids.rwsem (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. * before this function is called, and remain locked on the exit.
*/ */
void ipc_rmid(struct ipc_ids *ids, struct kern_ipc_perm *ipcp) void ipc_rmid(struct ipc_ids *ids, struct kern_ipc_perm *ipcp)
{ {
int lid = ipcid_to_idx(ipcp->id); int lid = ipcid_to_idx(ipcp->id);
@ -459,7 +455,6 @@ void ipc_rmid(struct ipc_ids *ids, struct kern_ipc_perm *ipcp)
* Allocate memory from the appropriate pools and return a pointer to it. * Allocate memory from the appropriate pools and return a pointer to it.
* NULL is returned if the allocation fails * NULL is returned if the allocation fails
*/ */
void *ipc_alloc(int size) void *ipc_alloc(int size)
{ {
void *out; void *out;
@ -478,7 +473,6 @@ void *ipc_alloc(int size)
* Free a block created with ipc_alloc(). The caller must know the size * Free a block created with ipc_alloc(). The caller must know the size
* used in the allocation call. * used in the allocation call.
*/ */
void ipc_free(void *ptr, int size) void ipc_free(void *ptr, int size)
{ {
if (size > PAGE_SIZE) if (size > PAGE_SIZE)
@ -534,17 +528,16 @@ void ipc_rcu_free(struct rcu_head *head)
} }
/** /**
* ipcperms - check IPC permissions * ipcperms - check ipc permissions
* @ns: IPC namespace * @ns: ipc namespace
* @ipcp: IPC permission set * @ipcp: ipc permission set
* @flag: desired permission set. * @flag: desired permission set
* *
* Check user, group, other permissions for access * Check user, group, other permissions for access
* to ipc resources. return 0 if allowed * to ipc resources. return 0 if allowed
* *
* @flag will most probably be 0 or S_...UGO from <linux/stat.h> * @flag will most probably be 0 or S_...UGO from <linux/stat.h>
*/ */
int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag) int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag)
{ {
kuid_t euid = current_euid(); kuid_t euid = current_euid();
@ -574,13 +567,11 @@ int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag)
/** /**
* kernel_to_ipc64_perm - convert kernel ipc permissions to user * kernel_to_ipc64_perm - convert kernel ipc permissions to user
* @in: kernel permissions * @in: kernel permissions
* @out: new style IPC permissions * @out: new style ipc permissions
* *
* Turn the kernel object @in into a set of permissions descriptions * Turn the kernel object @in into a set of permissions descriptions
* for returning to userspace (@out). * for returning to userspace (@out).
*/ */
void kernel_to_ipc64_perm(struct kern_ipc_perm *in, struct ipc64_perm *out) void kernel_to_ipc64_perm(struct kern_ipc_perm *in, struct ipc64_perm *out)
{ {
out->key = in->key; out->key = in->key;
@ -594,13 +585,12 @@ void kernel_to_ipc64_perm(struct kern_ipc_perm *in, struct ipc64_perm *out)
/** /**
* ipc64_perm_to_ipc_perm - convert new ipc permissions to old * ipc64_perm_to_ipc_perm - convert new ipc permissions to old
* @in: new style IPC permissions * @in: new style ipc permissions
* @out: old style IPC permissions * @out: old style ipc permissions
* *
* Turn the new style permissions object @in into a compatibility * Turn the new style permissions object @in into a compatibility
* object and store it into the @out pointer. * object and store it into the @out pointer.
*/ */
void ipc64_perm_to_ipc_perm(struct ipc64_perm *in, struct ipc_perm *out) void ipc64_perm_to_ipc_perm(struct ipc64_perm *in, struct ipc_perm *out)
{ {
out->key = in->key; out->key = in->key;
@ -635,8 +625,8 @@ struct kern_ipc_perm *ipc_obtain_object(struct ipc_ids *ids, int id)
} }
/** /**
* ipc_lock - Lock an ipc structure without rwsem held * ipc_lock - lock an ipc structure without rwsem held
* @ids: IPC identifier set * @ids: ipc identifier set
* @id: ipc id to look for * @id: ipc id to look for
* *
* Look for an id in the ipc ids idr and lock the associated ipc object. * Look for an id in the ipc ids idr and lock the associated ipc object.
@ -693,11 +683,11 @@ out:
/** /**
* ipcget - Common sys_*get() code * ipcget - Common sys_*get() code
* @ns : namsepace * @ns: namsepace
* @ids : IPC identifier set * @ids: ipc identifier set
* @ops : operations to be called on ipc object creation, permission checks * @ops: operations to be called on ipc object creation, permission checks
* and further checks * and further checks
* @params : the parameters needed by the previous operations. * @params: the parameters needed by the previous operations.
* *
* Common routine called by sys_msgget(), sys_semget() and sys_shmget(). * Common routine called by sys_msgget(), sys_semget() and sys_shmget().
*/ */
@ -711,7 +701,7 @@ int ipcget(struct ipc_namespace *ns, struct ipc_ids *ids,
} }
/** /**
* ipc_update_perm - update the permissions of an IPC. * ipc_update_perm - update the permissions of an ipc object
* @in: the permission given as input. * @in: the permission given as input.
* @out: the permission of the ipc to set. * @out: the permission of the ipc to set.
*/ */
@ -732,7 +722,7 @@ int ipc_update_perm(struct ipc64_perm *in, struct kern_ipc_perm *out)
/** /**
* ipcctl_pre_down_nolock - 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 * @ns: ipc namespace
* @ids: the table of ids where to look for the ipc * @ids: the table of ids where to look for the ipc
* @id: the id of the ipc to retrieve * @id: the id of the ipc to retrieve
* @cmd: the cmd to check * @cmd: the cmd to check
@ -779,14 +769,13 @@ err:
/** /**
* ipc_parse_version - IPC call version * ipc_parse_version - ipc call version
* @cmd: pointer to command * @cmd: pointer to command
* *
* Return IPC_64 for new style IPC and IPC_OLD for old style IPC. * Return IPC_64 for new style IPC and IPC_OLD for old style IPC.
* The @cmd value is turned from an encoding command and version into * The @cmd value is turned from an encoding command and version into
* just the command code. * just the command code.
*/ */
int ipc_parse_version(int *cmd) int ipc_parse_version(int *cmd)
{ {
if (*cmd & IPC_64) { if (*cmd & IPC_64) {