Proposed documentation patch to security.h

gregat_private

Hi all,

Here's my latest try at converting a tiny portion of the security.h
comments to the proper kernel-doc format.  This time, there can't be any
discussion that "our format is better" as it is not in proper kernel-doc
style.

This patch only converts the struct module_security_ops to the new
format.  An example of what the converted output looks like can be found
at http://lsm.immunix.org/~greg/module_security_ops.html
It was generated by typing:
	perl scripts/kernel-doc -html include/linux/security.h > module_security_ops.html

Let me know if anyone has any problems with this.  And if so,
constructive counter proposals are encouraged :)

thanks,

greg k-h

p.s. yes, I know I deleted the "called:" comments, as these are pretty
useless for anyone with 'grep' or 'cscope' or 'lxr' and are already
start to fall out of sync with the rest of the kernel tree.


diff --minimal -Nru a/include/linux/security.h b/include/linux/security.h

--- a/include/linux/security.h	Wed Oct 31 15:35:56 2001
+++ b/include/linux/security.h	Wed Oct 31 15:35:56 2001
@@ -1645,48 +1645,28 @@
 
 /**
  * struct module_security_ops - Security hooks for kernel module operations.
+ * @create_module:
+ *	Check the permission before allocating space for a module.
+ *	name contains the module name.
+ *	size contains the module size.
+ *	Return 0 if permission is granted.
+ * @init_module:
+ * 	Check permission before initializing a module.
+ * 	mod contains a pointer to the module being initialized.
+ *	Return 0 if permission is granted.
+ * @delete_module:
+ *	Check permission before removing a module.
+ *	mod contains a pointer to the module being deleted.
+ *	Return 0 if permission is granted.
+ * 
+ * These are the hooks for kernel module operations.  All hooks are called with
+ * the big kernel lock held, and @delete_module is also called with the
+ * unload_lock held.
  */
 struct module_security_ops {
-	/**
-	 * create_module - check permission when allocating space for a module
-	 * @name: module name
-	 * @size: module size
-	 *
-	 * called: sys_create_module <kernel/module.c>
-	 *
-	 * lock:  The big kernel lock is held.
-	 *
-	 * Check permission before allocating space for a kernel module.
-	 * Return 0 if permission is granted.
-	 */
- 	int  (* create_module) (const char *name, size_t size);
-
-	/**
-	 * init_module - check permission when initializing a module
-	 * @mod: the module
-	 *
-	 * called: sys_init_module <kernel/module.c>
-	 *
-	 * lock:  The big kernel lock is held.
-	 *
-	 * Check permission before initializing a kernel module.
-	 * Return 0 if permission is granted.
-	 */
- 	int  (* init_module) (struct module *mod);
-
-	/**
-	 * delete_module - check permission when removing a module
-	 * @mod: module being deleted
-	 *
-	 * called: sys_delete_module <kernel/module.c>
-	 *
-	 * lock:  The big kernel lock is held.
-	 * lock:  unload_lock is held.
-	 *
-	 * Check permission before removing a kernel module.
-	 * Return 0 if permission is granted.
-	 */
- 	int  (* delete_module) (const struct module *mod);
+ 	int  (*create_module) (const char *name, size_t size);
+ 	int  (*init_module) (struct module *mod);
+ 	int  (*delete_module) (const struct module *mod);
 };
 
 /**

_______________________________________________
linux-security-module mailing list
linux-security-moduleat_private
http://mail.wirex.com/mailman/listinfo/linux-security-module
