Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 8001c858 authored by Davidlohr Bueso's avatar Davidlohr Bueso Committed by Linus Torvalds
Browse files

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: default avatarDavidlohr Bueso <davidlohr@hp.com>
Cc: Aswin Chandramouleeswaran <aswin@hp.com>
Cc: Rik van Riel <riel@redhat.com>
Acked-by: default avatarManfred Spraul <manfred@colorfullife.com>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 239521f3

ipc/sem.c

+11 −13
Original line number Diff line number Diff line
@@ -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

 *

 * 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)

 */



static int newary(struct ipc_namespace *ns, struct ipc_params *params)

{

	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

 *

 * 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.

 * @semnum: semaphore that was modified.

 * @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

 * @sops: operations that were performed

 * @nsops: number of operations

 * @pt: list head of the tasks that must be woken up.

 *

 * do_smart_wakeup_zero() checks all required queue for wait-for-zero

 * operations, based on the actual changes that were performed on the

 * semaphore array.

 * Checks all required queue for wait-for-zero operations, based

 * on the actual changes that were performed on the semaphore array.

 * 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,
@@ -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.

 * @semnum: semaphore that was modified.

 * @pt: list head for the tasks that must be woken up.
@@ -920,7 +918,7 @@ static int update_queue(struct sem_array *sma, int semnum, struct list_head *pt) 
}



/**

 * set_semotime(sma, sops) - set sem_otime

 * set_semotime - set sem_otime

 * @sma: semaphore array

 * @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

 * @sops: operations that were performed

 * @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

 * @semid: semaphore array id

 *
@@ -1737,7 +1735,7 @@ static struct sem_undo *find_alloc_undo(struct ipc_namespace *ns, int semid) 




/**

 * 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

 *

 * Retrieve the return code from the pending queue. If IN_WAKEUP is found in

ipc/shm.c

+0 −1
Original line number Diff line number Diff line
@@ -477,7 +477,6 @@ static const struct vm_operations_struct shm_vm_ops = { 
 *

 * Called with shm_ids.rwsem held as a writer.

 */



static int newseg(struct ipc_namespace *ns, struct ipc_params *params)

{

	key_t key = params->key;

ipc/util.c

+114 −125
Original line number Diff line number Diff line
@@ -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

 * chain: since msgmni scales to lowmem this callback routine will be

 * called upon successful memory add / remove to recompute msmgni.

 */

 

static int __init ipc_init(void)

{

	sem_init();
@@ -131,13 +131,12 @@ static int __init ipc_init(void) 
__initcall(ipc_init);



/**

 *	ipc_init_ids		-	initialise IPC identifiers

 *	@ids: Identifier set

 * ipc_init_ids	- initialise ipc identifiers

 * @ids: ipc identifier set

 *

 * Set up the sequence range to use for the ipc identifier range (limited

 * below IPCMNI) then initialise the ids idr.

 */

 

void ipc_init_ids(struct ipc_ids *ids)

{

	init_rwsem(&ids->rwsem);
@@ -159,7 +158,7 @@ void ipc_init_ids(struct ipc_ids *ids) 
#ifdef CONFIG_PROC_FS

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

 * @header: Banner to be printed at the beginning of the file.

 * @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

 *	@ids: Identifier set

 *	@key: The key to find

 * @ids: ipc identifier set

 * @key: key to find

 *	

 * Returns the locked pointer to the ipc structure if found or NULL

 * otherwise. If key is found ipc points to the owning ipc structure

 *

 *	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

 * Called with ipc_ids.rwsem held.

 */

 

static struct kern_ipc_perm *ipc_findkey(struct ipc_ids *ids, key_t key)

{

	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

 *	@ids: IPC identifier set

 * @ids: ipc identifier set

 *

 * Called with ipc_ids.rwsem held.

 */



int ipc_get_maxid(struct ipc_ids *ids)

{

	struct kern_ipc_perm *ipc;
@@ -258,12 +255,12 @@ int ipc_get_maxid(struct ipc_ids *ids) 
}



/**

 *	ipc_addid	-	add an IPC identifier

 *	@ids: IPC identifier set

 *	@new: new IPC permission set

 * ipc_addid - add an ipc identifier

 * @ids: ipc identifier set

 * @new: new ipc permission set

 * @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

 * 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.
@@ -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

 *	@ns: namespace

 *	@ids: IPC identifer set

 * @ns: ipc namespace

 * @ids: ipc identifer set

 * @ops: the actual creation routine to call

 * @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

 *	@ns: IPC namespace

 * ipc_check_perms - check security and permissions for an ipc object

 * @ns: ipc namespace

 * @ipcp: ipc permission set

 * @ops: the actual security routine to call

 * @params: its parameters

 *

 * 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

 *      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.

 */
@@ -375,8 +372,8 @@ static int ipc_check_perms(struct ipc_namespace *ns, 


/**

 * ipcget_public - get an ipc object or create a new one

 *	@ns: namespace

 *	@ids: IPC identifer set

 * @ns: ipc namespace

 * @ids: ipc identifer set

 * @ops: the actual creation routine to call

 * @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

 *	@ids: IPC identifier set

 * ipc_rmid - remove an ipc identifier

 * @ids: ipc identifier set

 * @ipcp: ipc perm structure containing the identifier to remove

 *

 * 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.

 */

 

void ipc_rmid(struct ipc_ids *ids, struct kern_ipc_perm *ipcp)

{

	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.

 * NULL is returned if the allocation fails

 */

 

void *ipc_alloc(int size)

{

	void *out;
@@ -478,7 +473,6 @@ void *ipc_alloc(int size) 
 * Free a block created with ipc_alloc(). The caller must know the size

 * used in the allocation call.

 */



void ipc_free(void *ptr, int size)

{

	if (size > PAGE_SIZE)
@@ -534,17 +528,16 @@ void ipc_rcu_free(struct rcu_head *head) 
}



/**

 *	ipcperms	-	check IPC permissions

 *	@ns: IPC namespace

 *	@ipcp: IPC permission set

 *	@flag: desired permission set.

 * ipcperms - check ipc permissions

 * @ns: ipc namespace

 * @ipcp: ipc permission set

 * @flag: desired permission set

 *

 * Check user, group, other permissions for access

 * to ipc resources. return 0 if allowed

 *

 * @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)

{

	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

 * @in: kernel permissions

 *	@out: new style IPC permissions

 * @out: new style ipc permissions

 *

 * Turn the kernel object @in into a set of permissions descriptions

 * for returning to userspace (@out).

 */

 



void kernel_to_ipc64_perm(struct kern_ipc_perm *in, struct ipc64_perm *out)

{

	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

 *	@in: new style IPC permissions

 *	@out: old style IPC permissions

 * @in: new style ipc permissions

 * @out: old style ipc permissions

 *

 * Turn the new style permissions object @in into a compatibility

 * object and store it into the @out pointer.

 */

 

void ipc64_perm_to_ipc_perm(struct ipc64_perm *in, struct ipc_perm *out)

{

	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

 * @ids: IPC identifier set

 * ipc_lock - lock an ipc structure without rwsem held

 * @ids: ipc identifier set

 * @id: ipc id to look for

 *

 * Look for an id in the ipc ids idr and lock the associated ipc object.
@@ -694,7 +684,7 @@ struct kern_ipc_perm *ipc_obtain_object_check(struct ipc_ids *ids, int id) 
/**

 * ipcget - Common sys_*get() code

 * @ns: namsepace

 * @ids : IPC identifier set

 * @ids: ipc identifier set

 * @ops: operations to be called on ipc object creation, permission checks

 *       and further checks

 * @params: the parameters needed by the previous operations.
@@ -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.

 * @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

 * @ns:  the ipc namespace

 * @ns:  ipc namespace

 * @ids:  the table of ids where to look for the ipc

 * @id:   the id of the ipc to retrieve

 * @cmd:  the cmd to check
@@ -779,14 +769,13 @@ struct kern_ipc_perm *ipcctl_pre_down_nolock(struct ipc_namespace *ns, 




/**

 *	ipc_parse_version	-	IPC call version

 * ipc_parse_version - ipc call version

 * @cmd: pointer to command

 *

 * 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

 * just the command code.

 */

 

int ipc_parse_version(int *cmd)

{

	if (*cmd & IPC_64) {