[S390] zcrypt: Comments and kernel-doc cleanup

Comments, which suggested to be kernel-doc but were not in the right formatting, have been corrected. Additionally some minor cleanup in the comments has been done. Signed-off-by: Felix Beck <felix.beck@de.ibm.com> Signed-off-by: Martin Schwidefsky <schwidefsky@de.ibm.com> Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>

[S390] zcrypt: Comments and kernel-doc cleanup
Comments, which suggested to be kernel-doc but were not in the right formatting, have been corrected. Additionally some minor cleanup in the comments has been done. Signed-off-by: Felix Beck <felix.beck@de.ibm.com> Signed-off-by: Martin Schwidefsky <schwidefsky@de.ibm.com> Signed-off-by: Heiko Carstens <heiko.carstens@de.ibm.com>
Felix Beck · Heiko Carstens
1 parent 3f12ebce6a
Showing 7 changed files with 184 additions and 95 deletions Side-by-side Diff
drivers/s390/crypto/ap_bus.c
drivers/s390/crypto/ap_bus.h
drivers/s390/crypto/zcrypt_api.c
drivers/s390/crypto/zcrypt_cca_key.h
drivers/s390/crypto/zcrypt_error.h
drivers/s390/crypto/zcrypt_pcicc.c
drivers/s390/crypto/zcrypt_pcixcc.c
@@ -45,7 +45,7 @@
 static void ap_poll_thread_stop(void);
 static void ap_request_timeout(unsigned long);
  
-/**
+/*
  * Module description.
  */
 MODULE_AUTHOR("IBM Corporation");
@@ -53,7 +53,7 @@
 		   "Copyright 2006 IBM Corporation");
 MODULE_LICENSE("GPL");
  
-/**
+/*
  * Module parameter
  */
 int ap_domain_index = -1;	/* Adjunct Processor Domain Index */
@@ -69,7 +69,7 @@
 static DEFINE_SPINLOCK(ap_device_lock);
 static LIST_HEAD(ap_device_list);
  
-/**
+/*
  * Workqueue & timer for bus rescan.
  */
 static struct workqueue_struct *ap_work_queue;
@@ -77,7 +77,7 @@
 static int ap_config_time = AP_CONFIG_TIME;
 static DECLARE_WORK(ap_config_work, ap_scan_bus);
  
-/**
+/*
  * Tasklet & timer for AP request polling.
  */
 static struct timer_list ap_poll_timer = TIMER_INITIALIZER(ap_poll_timeout,0,0);
  
@@ -88,9 +88,9 @@
 static DEFINE_MUTEX(ap_poll_thread_mutex);
  
 /**
- * Test if ap instructions are available.
+ * ap_intructions_available() - Test if AP instructions are available.
  *
- * Returns 0 if the ap instructions are installed.
+ * Returns 0 if the AP instructions are installed.
  */
 static inline int ap_instructions_available(void)
 {
  
@@ -108,12 +108,12 @@
 }
  
 /**
- * Test adjunct processor queue.
- * @qid: the ap queue number
- * @queue_depth: pointer to queue depth value
- * @device_type: pointer to device type value
+ * ap_test_queue(): Test adjunct processor queue.
+ * @qid: The AP queue number
+ * @queue_depth: Pointer to queue depth value
+ * @device_type: Pointer to device type value
  *
- * Returns ap queue status structure.
+ * Returns AP queue status structure.
  */
 static inline struct ap_queue_status
 ap_test_queue(ap_qid_t qid, int *queue_depth, int *device_type)
  
@@ -130,10 +130,10 @@
 }
  
 /**
- * Reset adjunct processor queue.
- * @qid: the ap queue number
+ * ap_reset_queue(): Reset adjunct processor queue.
+ * @qid: The AP queue number
  *
- * Returns ap queue status structure.
+ * Returns AP queue status structure.
  */
 static inline struct ap_queue_status ap_reset_queue(ap_qid_t qid)
 {
  
  
@@ -148,16 +148,14 @@
 }
  
 /**
- * Send message to adjunct processor queue.
- * @qid: the ap queue number
- * @psmid: the program supplied message identifier
- * @msg: the message text
- * @length: the message length
+ * __ap_send(): Send message to adjunct processor queue.
+ * @qid: The AP queue number
+ * @psmid: The program supplied message identifier
+ * @msg: The message text
+ * @length: The message length
  *
- * Returns ap queue status structure.
- *
+ * Returns AP queue status structure.
  * Condition code 1 on NQAP can't happen because the L bit is 1.
- *
  * Condition code 2 on NQAP also means the send is incomplete,
  * because a segment boundary was reached. The NQAP is repeated.
  */
  
  
  
@@ -198,23 +196,20 @@
 }
 EXPORT_SYMBOL(ap_send);
  
-/*
- * Receive message from adjunct processor queue.
- * @qid: the ap queue number
- * @psmid: pointer to program supplied message identifier
- * @msg: the message text
- * @length: the message length
+/**
+ * __ap_recv(): Receive message from adjunct processor queue.
+ * @qid: The AP queue number
+ * @psmid: Pointer to program supplied message identifier
+ * @msg: The message text
+ * @length: The message length
  *
- * Returns ap queue status structure.
- *
+ * Returns AP queue status structure.
  * Condition code 1 on DQAP means the receive has taken place
  * but only partially.	The response is incomplete, hence the
  * DQAP is repeated.
- *
  * Condition code 2 on DQAP also means the receive is incomplete,
  * this time because a segment boundary was reached. Again, the
  * DQAP is repeated.
- *
  * Note that gpr2 is used by the DQAP instruction to keep track of
  * any 'residual' length, in case the instruction gets interrupted.
  * Hence it gets zeroed before the instruction.
@@ -263,11 +258,12 @@
 EXPORT_SYMBOL(ap_recv);
  
 /**
- * Check if an AP queue is available. The test is repeated for
- * AP_MAX_RESET times.
- * @qid: the ap queue number
- * @queue_depth: pointer to queue depth value
- * @device_type: pointer to device type value
+ * ap_query_queue(): Check if an AP queue is available.
+ * @qid: The AP queue number
+ * @queue_depth: Pointer to queue depth value
+ * @device_type: Pointer to device type value
+ *
+ * The test is repeated for AP_MAX_RESET times.
  */
 static int ap_query_queue(ap_qid_t qid, int *queue_depth, int *device_type)
 {
  
@@ -308,8 +304,10 @@
 }
  
 /**
+ * ap_init_queue(): Reset an AP queue.
+ * @qid: The AP queue number
+ *
  * Reset an AP queue and wait for it to become available again.
- * @qid: the ap queue number
  */
 static int ap_init_queue(ap_qid_t qid)
 {
@@ -346,7 +344,10 @@
 }
  
 /**
- * Arm request timeout if a AP device was idle and a new request is submitted.
+ * ap_increase_queue_count(): Arm request timeout.
+ * @ap_dev: Pointer to an AP device.
+ *
+ * Arm request timeout if an AP device was idle and a new request is submitted.
  */
 static void ap_increase_queue_count(struct ap_device *ap_dev)
 {
@@ -360,7 +361,10 @@
 }
  
 /**
- * AP device is still alive, re-schedule request timeout if there are still
+ * ap_decrease_queue_count(): Decrease queue count.
+ * @ap_dev: Pointer to an AP device.
+ *
+ * If AP device is still alive, re-schedule request timeout if there are still
  * pending requests.
  */
 static void ap_decrease_queue_count(struct ap_device *ap_dev)
@@ -371,7 +375,7 @@
 	if (ap_dev->queue_count > 0)
 		mod_timer(&ap_dev->timeout, jiffies + timeout);
 	else
-		/**
+		/*
 		 * The timeout timer should to be disabled now - since
 		 * del_timer_sync() is very expensive, we just tell via the
 		 * reset flag to ignore the pending timeout timer.
@@ -379,7 +383,7 @@
 		ap_dev->reset = AP_RESET_IGNORE;
 }
  
-/**
+/*
  * AP device related attributes.
  */
 static ssize_t ap_hwtype_show(struct device *dev,
@@ -433,6 +437,10 @@
 };
  
 /**
+ * ap_bus_match()
+ * @dev: Pointer to device
+ * @drv: Pointer to device_driver
+ *
  * AP bus driver registration/unregistration.
  */
 static int ap_bus_match(struct device *dev, struct device_driver *drv)
@@ -441,7 +449,7 @@
 	struct ap_driver *ap_drv = to_ap_drv(drv);
 	struct ap_device_id *id;
  
-	/**
+	/*
 	 * Compare device type of the device with the list of
 	 * supported types of the device_driver.
 	 */
@@ -455,8 +463,12 @@
 }
  
 /**
- * uevent function for AP devices. It sets up a single environment
- * variable DEV_TYPE which contains the hardware device type.
+ * ap_uevent(): Uevent function for AP devices.
+ * @dev: Pointer to device
+ * @env: Pointer to kobj_uevent_env
+ *
+ * It sets up a single environment variable DEV_TYPE which contains the
+ * hardware device type.
  */
 static int ap_uevent (struct device *dev, struct kobj_uevent_env *env)
 {
  
@@ -500,8 +512,10 @@
 }
  
 /**
+ * __ap_flush_queue(): Flush requests.
+ * @ap_dev: Pointer to the AP device
+ *
  * Flush all requests from the request/pending queue of an AP device.
- * @ap_dev: pointer to the AP device.
  */
 static void __ap_flush_queue(struct ap_device *ap_dev)
 {
@@ -565,7 +579,7 @@
 }
 EXPORT_SYMBOL(ap_driver_unregister);
  
-/**
+/*
  * AP bus attributes.
  */
 static ssize_t ap_domain_show(struct bus_type *bus, char *buf)
  
@@ -630,14 +644,16 @@
 };
  
 /**
- * Pick one of the 16 ap domains.
+ * ap_select_domain(): Select an AP domain.
+ *
+ * Pick one of the 16 AP domains.
  */
 static int ap_select_domain(void)
 {
 	int queue_depth, device_type, count, max_count, best_domain;
 	int rc, i, j;
  
-	/**
+	/*
 	 * We want to use a single domain. Either the one specified with
 	 * the "domain=" parameter or the domain with the maximum number
 	 * of devices.
  
@@ -669,8 +685,10 @@
 }
  
 /**
- * Find the device type if query queue returned a device type of 0.
+ * ap_probe_device_type(): Find the device type of an AP.
  * @ap_dev: pointer to the AP device.
+ *
+ * Find the device type if query queue returned a device type of 0.
  */
 static int ap_probe_device_type(struct ap_device *ap_dev)
 {
@@ -764,7 +782,11 @@
 }
  
 /**
- * Scan the ap bus for new devices.
+ * __ap_scan_bus(): Scan the AP bus.
+ * @dev: Pointer to device
+ * @data: Pointer to data
+ *
+ * Scan the AP bus for new devices.
  */
 static int __ap_scan_bus(struct device *dev, void *data)
 {
@@ -867,6 +889,8 @@
 }
  
 /**
+ * ap_schedule_poll_timer(): Schedule poll timer.
+ *
  * Set up the timer to run the poll tasklet
  */
 static inline void ap_schedule_poll_timer(void)
  
@@ -877,10 +901,11 @@
 }
  
 /**
- * Receive pending reply messages from an AP device.
+ * ap_poll_read(): Receive pending reply messages from an AP device.
  * @ap_dev: pointer to the AP device
  * @flags: pointer to control flags, bit 2^0 is set if another poll is
  *	   required, bit 2^1 is set if the poll timer needs to get armed
+ *
  * Returns 0 if the device is still present, -ENODEV if not.
  */
 static int ap_poll_read(struct ap_device *ap_dev, unsigned long *flags)
  
@@ -925,10 +950,11 @@
 }
  
 /**
- * Send messages from the request queue to an AP device.
+ * ap_poll_write(): Send messages from the request queue to an AP device.
  * @ap_dev: pointer to the AP device
  * @flags: pointer to control flags, bit 2^0 is set if another poll is
  *	   required, bit 2^1 is set if the poll timer needs to get armed
+ *
  * Returns 0 if the device is still present, -ENODEV if not.
  */
 static int ap_poll_write(struct ap_device *ap_dev, unsigned long *flags)
  
@@ -968,11 +994,13 @@
 }
  
 /**
- * Poll AP device for pending replies and send new messages. If either
- * ap_poll_read or ap_poll_write returns -ENODEV unregister the device.
+ * ap_poll_queue(): Poll AP device for pending replies and send new messages.
  * @ap_dev: pointer to the bus device
  * @flags: pointer to control flags, bit 2^0 is set if another poll is
  *	   required, bit 2^1 is set if the poll timer needs to get armed
+ *
+ * Poll AP device for pending replies and send new messages. If either
+ * ap_poll_read or ap_poll_write returns -ENODEV unregister the device.
  * Returns 0.
  */
 static inline int ap_poll_queue(struct ap_device *ap_dev, unsigned long *flags)
  
@@ -986,9 +1014,11 @@
 }
  
 /**
- * Queue a message to a device.
+ * __ap_queue_message(): Queue a message to a device.
  * @ap_dev: pointer to the AP device
  * @ap_msg: the message to be queued
+ *
+ * Queue a message to a device. Returns 0 if successful.
  */
 static int __ap_queue_message(struct ap_device *ap_dev, struct ap_message *ap_msg)
 {
  
  
@@ -1055,12 +1085,14 @@
 EXPORT_SYMBOL(ap_queue_message);
  
 /**
+ * ap_cancel_message(): Cancel a crypto request.
+ * @ap_dev: The AP device that has the message queued
+ * @ap_msg: The message that is to be removed
+ *
  * Cancel a crypto request. This is done by removing the request
- * from the devive pendingq or requestq queue. Note that the
+ * from the device pending or request queue. Note that the
  * request stays on the AP queue. When it finishes the message
  * reply will be discarded because the psmid can't be found.
- * @ap_dev: AP device that has the message queued
- * @ap_msg: the message that is to be removed
  */
 void ap_cancel_message(struct ap_device *ap_dev, struct ap_message *ap_msg)
 {
@@ -1082,7 +1114,10 @@
 EXPORT_SYMBOL(ap_cancel_message);
  
 /**
- * AP receive polling for finished AP requests
+ * ap_poll_timeout(): AP receive polling for finished AP requests.
+ * @unused: Unused variable.
+ *
+ * Schedules the AP tasklet.
  */
 static void ap_poll_timeout(unsigned long unused)
 {
@@ -1090,6 +1125,9 @@
 }
  
 /**
+ * ap_reset(): Reset a not responding AP device.
+ * @ap_dev: Pointer to the AP device
+ *
  * Reset a not responding AP device and move all requests from the
  * pending queue to the request queue.
  */
@@ -1108,11 +1146,6 @@
 		ap_dev->unregistered = 1;
 }
  
-/**
- * Poll all AP devices on the bus in a round robin fashion. Continue
- * polling until bit 2^0 of the control flags is not set. If bit 2^1
- * of the control flags has been set arm the poll timer.
- */
 static int __ap_poll_all(struct ap_device *ap_dev, unsigned long *flags)
 {
 	spin_lock(&ap_dev->lock);
@@ -1126,6 +1159,14 @@
 	return 0;
 }
  
+/**
+ * ap_poll_all(): Poll all AP devices.
+ * @dummy: Unused variable
+ *
+ * Poll all AP devices on the bus in a round robin fashion. Continue
+ * polling until bit 2^0 of the control flags is not set. If bit 2^1
+ * of the control flags has been set arm the poll timer.
+ */
 static void ap_poll_all(unsigned long dummy)
 {
 	unsigned long flags;
@@ -1144,6 +1185,9 @@
 }
  
 /**
+ * ap_poll_thread(): Thread that polls for finished requests.
+ * @data: Unused pointer
+ *
  * AP bus poll thread. The purpose of this thread is to poll for
  * finished requests in a loop if there is a "free" cpu - that is
  * a cpu that doesn't have anything better to do. The polling stops
@@ -1213,7 +1257,10 @@
 }
  
 /**
- * Handling of request timeouts
+ * ap_request_timeout(): Handling of request timeouts
+ * @data: Holds the AP device.
+ *
+ * Handles request timeouts.
  */
 static void ap_request_timeout(unsigned long data)
 {
@@ -1246,7 +1293,9 @@
 };
  
 /**
- * The module initialization code.
+ * ap_module_init(): The module initialization code.
+ *
+ * Initializes the module.
  */
 int __init ap_module_init(void)
 {
@@ -1288,7 +1337,7 @@
 	if (ap_select_domain() == 0)
 		ap_scan_bus(NULL);
  
-	/* Setup the ap bus rescan timer. */
+	/* Setup the AP bus rescan timer. */
 	init_timer(&ap_config_timer);
 	ap_config_timer.function = ap_config_timeout;
 	ap_config_timer.data = 0;
@@ -1325,7 +1374,9 @@
 }
  
 /**
- * The module termination code
+ * ap_modules_exit(): The module termination code
+ *
+ * Terminates the module.
  */
 void ap_module_exit(void)
 {
@@ -50,6 +50,15 @@
 #define AP_QID_QUEUE(_qid) ((_qid) & 15)
  
 /**
+ * structy ap_queue_status - Holds the AP queue status.
+ * @queue_empty: Shows if queue is empty
+ * @replies_waiting: Waiting replies
+ * @queue_full: Is 1 if the queue is full
+ * @pad: A 4 bit pad
+ * @int_enabled: Shows if interrupts are enabled for the AP
+ * @response_conde: Holds the 8 bit response code
+ * @pad2: A 16 bit pad
+ *
  * The ap queue status word is returned by all three AP functions
  * (PQAP, NQAP and DQAP).  There's a set of flags in the first
  * byte, followed by a 1 byte response code.
@@ -75,7 +84,7 @@
 #define AP_RESPONSE_NO_FIRST_PART	0x13
 #define AP_RESPONSE_MESSAGE_TOO_BIG	0x15
  
-/**
+/*
  * Known device types
  */
 #define AP_DEVICE_TYPE_PCICC	3
@@ -84,7 +93,7 @@
 #define AP_DEVICE_TYPE_CEX2A	6
 #define AP_DEVICE_TYPE_CEX2C	7
  
-/**
+/*
  * AP reset flag states
  */
 #define AP_RESET_IGNORE	0	/* request timeout will be ignored */
@@ -152,7 +161,7 @@
 	.dev_type=(dt),					\
 	.match_flags=AP_DEVICE_ID_MATCH_DEVICE_TYPE,
  
-/**
+/*
  * Note: don't use ap_send/ap_recv after using ap_queue_message
  * for the first time. Otherwise the ap message queue will get
  * confused.
@@ -40,7 +40,7 @@
  
 #include "zcrypt_api.h"
  
-/**
+/*
  * Module description.
  */
 MODULE_AUTHOR("IBM Corporation");
@@ -56,7 +56,7 @@
 static int zcrypt_rng_device_add(void);
 static void zcrypt_rng_device_remove(void);
  
-/**
+/*
  * Device attributes common for all crypto devices.
  */
 static ssize_t zcrypt_type_show(struct device *dev,
@@ -103,6 +103,9 @@
 };
  
 /**
+ * __zcrypt_increase_preference(): Increase preference of a crypto device.
+ * @zdev: Pointer the crypto device
+ *
  * Move the device towards the head of the device list.
  * Need to be called while holding the zcrypt device list lock.
  * Note: cards with speed_rating of 0 are kept at the end of the list.
@@ -129,6 +132,9 @@
 }
  
 /**
+ * __zcrypt_decrease_preference(): Decrease preference of a crypto device.
+ * @zdev: Pointer to a crypto device.
+ *
  * Move the device towards the tail of the device list.
  * Need to be called while holding the zcrypt device list lock.
  * Note: cards with speed_rating of 0 are kept at the end of the list.
@@ -202,7 +208,10 @@
 EXPORT_SYMBOL(zcrypt_device_free);
  
 /**
- * Register a crypto device.
+ * zcrypt_device_register() - Register a crypto device.
+ * @zdev: Pointer to a crypto device
+ *
+ * Register a crypto device. Returns 0 if successful.
  */
 int zcrypt_device_register(struct zcrypt_device *zdev)
 {
@@ -242,6 +251,9 @@
 EXPORT_SYMBOL(zcrypt_device_register);
  
 /**
+ * zcrypt_device_unregister(): Unregister a crypto device.
+ * @zdev: Pointer to crypto device
+ *
  * Unregister a crypto device.
  */
 void zcrypt_device_unregister(struct zcrypt_device *zdev)
@@ -260,7 +272,9 @@
 EXPORT_SYMBOL(zcrypt_device_unregister);
  
 /**
- * zcrypt_read is not be supported beyond zcrypt 1.3.1
+ * zcrypt_read (): Not supported beyond zcrypt 1.3.1.
+ *
+ * This function is not supported beyond zcrypt 1.3.1.
  */
 static ssize_t zcrypt_read(struct file *filp, char __user *buf,
 			   size_t count, loff_t *f_pos)
@@ -269,6 +283,8 @@
 }
  
 /**
+ * zcrypt_write(): Not allowed.
+ *
  * Write is is not allowed
  */
 static ssize_t zcrypt_write(struct file *filp, const char __user *buf,
@@ -278,7 +294,9 @@
 }
  
 /**
- * Device open/close functions to count number of users.
+ * zcrypt_open(): Count number of users.
+ *
+ * Device open function to count number of users.
  */
 static int zcrypt_open(struct inode *inode, struct file *filp)
 {
  
@@ -286,13 +304,18 @@
 	return 0;
 }
  
+/**
+ * zcrypt_release(): Count number of users.
+ *
+ * Device close function to count number of users.
+ */
 static int zcrypt_release(struct inode *inode, struct file *filp)
 {
 	atomic_dec(&zcrypt_open_count);
 	return 0;
 }
  
-/**
+/*
  * zcrypt ioctls.
  */
 static long zcrypt_rsa_modexpo(struct ica_rsa_modexpo *mex)
@@ -302,7 +325,7 @@
  
 	if (mex->outputdatalength < mex->inputdatalength)
 		return -EINVAL;
-	/**
+	/*
 	 * As long as outputdatalength is big enough, we can set the
 	 * outputdatalength equal to the inputdatalength, since that is the
 	 * number of bytes we will copy in any case
@@ -348,7 +371,7 @@
 	if (crt->outputdatalength < crt->inputdatalength ||
 	    (crt->inputdatalength & 1))
 		return -EINVAL;
-	/**
+	/*
 	 * As long as outputdatalength is big enough, we can set the
 	 * outputdatalength equal to the inputdatalength, since that is the
 	 * number of bytes we will copy in any case
@@ -365,7 +388,7 @@
 		    zdev->max_mod_size < crt->inputdatalength)
 			continue;
 		if (zdev->short_crt && crt->inputdatalength > 240) {
-			/**
+			/*
 			 * Check inputdata for leading zeros for cards
 			 * that can't handle np_prime, bp_key, or
 			 * u_mult_inv > 128 bytes.
@@ -381,7 +404,7 @@
 				    copy_from_user(&z3, crt->u_mult_inv, len))
 					return -EFAULT;
 				copied = 1;
-				/**
+				/*
 				 * We have to restart device lookup -
 				 * the device list may have changed by now.
 				 */
@@ -567,6 +590,8 @@
 }
  
 /**
+ * zcrypt_ica_status(): Old, depracted combi status call.
+ *
  * Old, deprecated combi status call.
  */
 static long zcrypt_ica_status(struct file *filp, unsigned long arg)
@@ -668,7 +693,7 @@
 				(int __user *) arg);
 	case Z90STAT_DOMAIN_INDEX:
 		return put_user(ap_domain_index, (int __user *) arg);
-	/**
+	/*
 	 * Deprecated ioctls. Don't add another device count ioctl,
 	 * you can count them yourself in the user space with the
 	 * output of the Z90STAT_STATUS_MASK ioctl.
@@ -706,7 +731,7 @@
 }
  
 #ifdef CONFIG_COMPAT
-/**
+/*
  * ioctl32 conversion routines
  */
 struct compat_ica_rsa_modexpo {
@@ -857,7 +882,7 @@
 }
 #endif
  
-/**
+/*
  * Misc device file operations.
  */
 static const struct file_operations zcrypt_fops = {
@@ -872,7 +897,7 @@
 	.release	= zcrypt_release
 };
  
-/**
+/*
  * Misc device.
  */
 static struct miscdevice zcrypt_misc_device = {
@@ -881,7 +906,7 @@
 	.fops	    = &zcrypt_fops,
 };
  
-/**
+/*
  * Deprecated /proc entry support.
  */
 static struct proc_dir_entry *zcrypt_entry;
@@ -1075,7 +1100,7 @@
 	}
  
 	for (j = 0; j < 64 && *ptr; ptr++) {
-		/**
+		/*
 		 * '0' for no device, '1' for PCICA, '2' for PCICC,
 		 * '3' for PCIXCC_MCL2, '4' for PCIXCC_MCL3,
 		 * '5' for CEX2C and '6' for CEX2A'
@@ -1103,7 +1128,7 @@
 {
 	int rc;
  
-	/**
+	/*
 	 * We don't need locking here because the RNG API guarantees serialized
 	 * read method calls.
 	 */
@@ -1162,6 +1187,8 @@
 }
  
 /**
+ * zcrypt_api_init(): Module initialization.
+ *
  * The module initialization code.
  */
 int __init zcrypt_api_init(void)
@@ -1196,6 +1223,8 @@
 }
  
 /**
+ * zcrypt_api_exit(): Module termination.
+ *
  * The module termination code.
  */
 void zcrypt_api_exit(void)
@@ -174,7 +174,7 @@
 	key->pvtMeHdr = static_pvt_me_hdr;
 	key->pvtMeSec = static_pvt_me_sec;
 	key->pubMeSec = static_pub_me_sec;
-	/**
+	/*
 	 * In a private key, the modulus doesn't appear in the public
 	 * section. So, an arbitrary public exponent of 0x010001 will be
 	 * used.
@@ -338,7 +338,7 @@
 	pub = (struct cca_public_sec *)(key->key_parts + key_len);
 	*pub = static_cca_pub_sec;
 	pub->modulus_bit_len = 8 * crt->inputdatalength;
-	/**
+	/*
 	 * In a private key, the modulus doesn't appear in the public
 	 * section. So, an arbitrary public exponent of 0x010001 will be
 	 * used.
@@ -108,7 +108,7 @@
 		return -EINVAL;
 	case REP82_ERROR_MESSAGE_TYPE:
 	//   REP88_ERROR_MESSAGE_TYPE		// '20' CEX2A
-		/**
+		/*
 		 * To sent a message of the wrong type is a bug in the
 		 * device driver. Warn about it, disable the device
 		 * and then repeat the request.
@@ -42,7 +42,7 @@
 #define PCICC_MAX_MOD_SIZE_OLD	128	/* 1024 bits */
 #define PCICC_MAX_MOD_SIZE	256	/* 2048 bits */
  
-/**
+/*
  * PCICC cards need a speed rating of 0. This keeps them at the end of
  * the zcrypt device list (see zcrypt_api.c). PCICC cards are only
  * used if no other cards are present because they are slow and can only
@@ -388,7 +388,7 @@
 	reply_len = le16_to_cpu(msg->length) - 2;
 	if (reply_len > outputdatalength)
 		return -EINVAL;
-	/**
+	/*
 	 * For all encipher requests, the length of the ciphertext (reply_len)
 	 * will always equal the modulus length. For MEX decipher requests
 	 * the output needs to get padded. Minimum pad size is 10.
@@ -501,7 +501,7 @@
 	reply_len = msg->length - 2;
 	if (reply_len > outputdatalength)
 		return -EINVAL;
-	/**
+	/*
 	 * For all encipher requests, the length of the ciphertext (reply_len)
 	 * will always equal the modulus length. For MEX decipher requests
 	 * the output needs to get padded. Minimum pad size is 10.
...	...	@@ -45,7 +45,7 @@
45	45	static void ap_poll_thread_stop(void);
46	46	static void ap_request_timeout(unsigned long);
47	47
48		-/**
	48	+/*
49	49	* Module description.
50	50	*/
51	51	MODULE_AUTHOR("IBM Corporation");
...	...	@@ -53,7 +53,7 @@
53	53	"Copyright 2006 IBM Corporation");
54	54	MODULE_LICENSE("GPL");
55	55
56		-/**
	56	+/*
57	57	* Module parameter
58	58	*/
59	59	int ap_domain_index = -1; /* Adjunct Processor Domain Index */
...	...	@@ -69,7 +69,7 @@
69	69	static DEFINE_SPINLOCK(ap_device_lock);
70	70	static LIST_HEAD(ap_device_list);
71	71
72		-/**
	72	+/*
73	73	* Workqueue & timer for bus rescan.
74	74	*/
75	75	static struct workqueue_struct *ap_work_queue;
...	...	@@ -77,7 +77,7 @@
77	77	static int ap_config_time = AP_CONFIG_TIME;
78	78	static DECLARE_WORK(ap_config_work, ap_scan_bus);
79	79
80		-/**
	80	+/*
81	81	* Tasklet & timer for AP request polling.
82	82	*/
83	83	static struct timer_list ap_poll_timer = TIMER_INITIALIZER(ap_poll_timeout,0,0);
84	84
...	...	@@ -88,9 +88,9 @@
88	88	static DEFINE_MUTEX(ap_poll_thread_mutex);
89	89
90	90	/**
91		- * Test if ap instructions are available.
	91	+ * ap_intructions_available() - Test if AP instructions are available.
92	92	*
93		- * Returns 0 if the ap instructions are installed.
	93	+ * Returns 0 if the AP instructions are installed.
94	94	*/
95	95	static inline int ap_instructions_available(void)
96	96	{
97	97
...	...	@@ -108,12 +108,12 @@
108	108	}
109	109
110	110	/**
111		- * Test adjunct processor queue.
112		- * @qid: the ap queue number
113		- * @queue_depth: pointer to queue depth value
114		- * @device_type: pointer to device type value
	111	+ * ap_test_queue(): Test adjunct processor queue.
	112	+ * @qid: The AP queue number
	113	+ * @queue_depth: Pointer to queue depth value
	114	+ * @device_type: Pointer to device type value
115	115	*
116		- * Returns ap queue status structure.
	116	+ * Returns AP queue status structure.
117	117	*/
118	118	static inline struct ap_queue_status
119	119	ap_test_queue(ap_qid_t qid, int queue_depth, int device_type)
120	120
...	...	@@ -130,10 +130,10 @@
130	130	}
131	131
132	132	/**
133		- * Reset adjunct processor queue.
134		- * @qid: the ap queue number
	133	+ * ap_reset_queue(): Reset adjunct processor queue.
	134	+ * @qid: The AP queue number
135	135	*
136		- * Returns ap queue status structure.
	136	+ * Returns AP queue status structure.
137	137	*/
138	138	static inline struct ap_queue_status ap_reset_queue(ap_qid_t qid)
139	139	{
140	140
141	141
...	...	@@ -148,16 +148,14 @@
148	148	}
149	149
150	150	/**
151		- * Send message to adjunct processor queue.
152		- * @qid: the ap queue number
153		- * @psmid: the program supplied message identifier
154		- * @msg: the message text
155		- * @length: the message length
	151	+ * __ap_send(): Send message to adjunct processor queue.
	152	+ * @qid: The AP queue number
	153	+ * @psmid: The program supplied message identifier
	154	+ * @msg: The message text
	155	+ * @length: The message length
156	156	*
157		- * Returns ap queue status structure.
158		- *
	157	+ * Returns AP queue status structure.
159	158	* Condition code 1 on NQAP can't happen because the L bit is 1.
160		- *
161	159	* Condition code 2 on NQAP also means the send is incomplete,
162	160	* because a segment boundary was reached. The NQAP is repeated.
163	161	*/
164	162
165	163
166	164
...	...	@@ -198,23 +196,20 @@
198	196	}
199	197	EXPORT_SYMBOL(ap_send);
200	198
201		-/*
202		- * Receive message from adjunct processor queue.
203		- * @qid: the ap queue number
204		- * @psmid: pointer to program supplied message identifier
205		- * @msg: the message text
206		- * @length: the message length
	199	+/**
	200	+ * __ap_recv(): Receive message from adjunct processor queue.
	201	+ * @qid: The AP queue number
	202	+ * @psmid: Pointer to program supplied message identifier
	203	+ * @msg: The message text
	204	+ * @length: The message length
207	205	*
208		- * Returns ap queue status structure.
209		- *
	206	+ * Returns AP queue status structure.
210	207	* Condition code 1 on DQAP means the receive has taken place
211	208	* but only partially. The response is incomplete, hence the
212	209	* DQAP is repeated.
213		- *
214	210	* Condition code 2 on DQAP also means the receive is incomplete,
215	211	* this time because a segment boundary was reached. Again, the
216	212	* DQAP is repeated.
217		- *
218	213	* Note that gpr2 is used by the DQAP instruction to keep track of
219	214	* any 'residual' length, in case the instruction gets interrupted.
220	215	* Hence it gets zeroed before the instruction.
...	...	@@ -263,11 +258,12 @@
263	258	EXPORT_SYMBOL(ap_recv);
264	259
265	260	/**
266		- * Check if an AP queue is available. The test is repeated for
267		- * AP_MAX_RESET times.
268		- * @qid: the ap queue number
269		- * @queue_depth: pointer to queue depth value
270		- * @device_type: pointer to device type value
	261	+ * ap_query_queue(): Check if an AP queue is available.
	262	+ * @qid: The AP queue number
	263	+ * @queue_depth: Pointer to queue depth value
	264	+ * @device_type: Pointer to device type value
	265	+ *
	266	+ * The test is repeated for AP_MAX_RESET times.
271	267	*/
272	268	static int ap_query_queue(ap_qid_t qid, int queue_depth, int device_type)
273	269	{
274	270
...	...	@@ -308,8 +304,10 @@
308	304	}
309	305
310	306	/**
	307	+ * ap_init_queue(): Reset an AP queue.
	308	+ * @qid: The AP queue number
	309	+ *
311	310	* Reset an AP queue and wait for it to become available again.
312		- * @qid: the ap queue number
313	311	*/
314	312	static int ap_init_queue(ap_qid_t qid)
315	313	{
...	...	@@ -346,7 +344,10 @@
346	344	}
347	345
348	346	/**
349		- * Arm request timeout if a AP device was idle and a new request is submitted.
	347	+ * ap_increase_queue_count(): Arm request timeout.
	348	+ * @ap_dev: Pointer to an AP device.
	349	+ *
	350	+ * Arm request timeout if an AP device was idle and a new request is submitted.
350	351	*/
351	352	static void ap_increase_queue_count(struct ap_device *ap_dev)
352	353	{
...	...	@@ -360,7 +361,10 @@
360	361	}
361	362
362	363	/**
363		- * AP device is still alive, re-schedule request timeout if there are still
	364	+ * ap_decrease_queue_count(): Decrease queue count.
	365	+ * @ap_dev: Pointer to an AP device.
	366	+ *
	367	+ * If AP device is still alive, re-schedule request timeout if there are still
364	368	* pending requests.
365	369	*/
366	370	static void ap_decrease_queue_count(struct ap_device *ap_dev)
...	...	@@ -371,7 +375,7 @@
371	375	if (ap_dev->queue_count > 0)
372	376	mod_timer(&ap_dev->timeout, jiffies + timeout);
373	377	else
374		- /**
	378	+ /*
375	379	* The timeout timer should to be disabled now - since
376	380	* del_timer_sync() is very expensive, we just tell via the
377	381	* reset flag to ignore the pending timeout timer.
...	...	@@ -379,7 +383,7 @@
379	383	ap_dev->reset = AP_RESET_IGNORE;
380	384	}
381	385
382		-/**
	386	+/*
383	387	* AP device related attributes.
384	388	*/
385	389	static ssize_t ap_hwtype_show(struct device *dev,
...	...	@@ -433,6 +437,10 @@
433	437	};
434	438
435	439	/**
	440	+ * ap_bus_match()
	441	+ * @dev: Pointer to device
	442	+ * @drv: Pointer to device_driver
	443	+ *
436	444	* AP bus driver registration/unregistration.
437	445	*/
438	446	static int ap_bus_match(struct device dev, struct device_driver drv)
...	...	@@ -441,7 +449,7 @@
441	449	struct ap_driver *ap_drv = to_ap_drv(drv);
442	450	struct ap_device_id *id;
443	451
444		- /**
	452	+ /*
445	453	* Compare device type of the device with the list of
446	454	* supported types of the device_driver.
447	455	*/
...	...	@@ -455,8 +463,12 @@
455	463	}
456	464
457	465	/**
458		- * uevent function for AP devices. It sets up a single environment
459		- * variable DEV_TYPE which contains the hardware device type.
	466	+ * ap_uevent(): Uevent function for AP devices.
	467	+ * @dev: Pointer to device
	468	+ * @env: Pointer to kobj_uevent_env
	469	+ *
	470	+ * It sets up a single environment variable DEV_TYPE which contains the
	471	+ * hardware device type.
460	472	*/
461	473	static int ap_uevent (struct device dev, struct kobj_uevent_env env)
462	474	{
463	475
...	...	@@ -500,8 +512,10 @@
500	512	}
501	513
502	514	/**
	515	+ * __ap_flush_queue(): Flush requests.
	516	+ * @ap_dev: Pointer to the AP device
	517	+ *
503	518	* Flush all requests from the request/pending queue of an AP device.
504		- * @ap_dev: pointer to the AP device.
505	519	*/
506	520	static void __ap_flush_queue(struct ap_device *ap_dev)
507	521	{
...	...	@@ -565,7 +579,7 @@
565	579	}
566	580	EXPORT_SYMBOL(ap_driver_unregister);
567	581
568		-/**
	582	+/*
569	583	* AP bus attributes.
570	584	*/
571	585	static ssize_t ap_domain_show(struct bus_type bus, char buf)
572	586
...	...	@@ -630,14 +644,16 @@
630	644	};
631	645
632	646	/**
633		- * Pick one of the 16 ap domains.
	647	+ * ap_select_domain(): Select an AP domain.
	648	+ *
	649	+ * Pick one of the 16 AP domains.
634	650	*/
635	651	static int ap_select_domain(void)
636	652	{
637	653	int queue_depth, device_type, count, max_count, best_domain;
638	654	int rc, i, j;
639	655
640		- /**
	656	+ /*
641	657	* We want to use a single domain. Either the one specified with
642	658	* the "domain=" parameter or the domain with the maximum number
643	659	* of devices.
644	660
...	...	@@ -669,8 +685,10 @@
669	685	}
670	686
671	687	/**
672		- * Find the device type if query queue returned a device type of 0.
	688	+ * ap_probe_device_type(): Find the device type of an AP.
673	689	* @ap_dev: pointer to the AP device.
	690	+ *
	691	+ * Find the device type if query queue returned a device type of 0.
674	692	*/
675	693	static int ap_probe_device_type(struct ap_device *ap_dev)
676	694	{
...	...	@@ -764,7 +782,11 @@
764	782	}
765	783
766	784	/**
767		- * Scan the ap bus for new devices.
	785	+ * __ap_scan_bus(): Scan the AP bus.
	786	+ * @dev: Pointer to device
	787	+ * @data: Pointer to data
	788	+ *
	789	+ * Scan the AP bus for new devices.
768	790	*/
769	791	static int __ap_scan_bus(struct device dev, void data)
770	792	{
...	...	@@ -867,6 +889,8 @@
867	889	}
868	890
869	891	/**
	892	+ * ap_schedule_poll_timer(): Schedule poll timer.
	893	+ *
870	894	* Set up the timer to run the poll tasklet
871	895	*/
872	896	static inline void ap_schedule_poll_timer(void)
873	897
...	...	@@ -877,10 +901,11 @@
877	901	}
878	902
879	903	/**
880		- * Receive pending reply messages from an AP device.
	904	+ * ap_poll_read(): Receive pending reply messages from an AP device.
881	905	* @ap_dev: pointer to the AP device
882	906	* @flags: pointer to control flags, bit 2^0 is set if another poll is
883	907	* required, bit 2^1 is set if the poll timer needs to get armed
	908	+ *
884	909	* Returns 0 if the device is still present, -ENODEV if not.
885	910	*/
886	911	static int ap_poll_read(struct ap_device ap_dev, unsigned long flags)
887	912
...	...	@@ -925,10 +950,11 @@
925	950	}
926	951
927	952	/**
928		- * Send messages from the request queue to an AP device.
	953	+ * ap_poll_write(): Send messages from the request queue to an AP device.
929	954	* @ap_dev: pointer to the AP device
930	955	* @flags: pointer to control flags, bit 2^0 is set if another poll is
931	956	* required, bit 2^1 is set if the poll timer needs to get armed
	957	+ *
932	958	* Returns 0 if the device is still present, -ENODEV if not.
933	959	*/
934	960	static int ap_poll_write(struct ap_device ap_dev, unsigned long flags)
935	961
...	...	@@ -968,11 +994,13 @@
968	994	}
969	995
970	996	/**
971		- * Poll AP device for pending replies and send new messages. If either
972		- * ap_poll_read or ap_poll_write returns -ENODEV unregister the device.
	997	+ * ap_poll_queue(): Poll AP device for pending replies and send new messages.
973	998	* @ap_dev: pointer to the bus device
974	999	* @flags: pointer to control flags, bit 2^0 is set if another poll is
975	1000	* required, bit 2^1 is set if the poll timer needs to get armed
	1001	+ *
	1002	+ * Poll AP device for pending replies and send new messages. If either
	1003	+ * ap_poll_read or ap_poll_write returns -ENODEV unregister the device.
976	1004	* Returns 0.
977	1005	*/
978	1006	static inline int ap_poll_queue(struct ap_device ap_dev, unsigned long flags)
979	1007
...	...	@@ -986,9 +1014,11 @@
986	1014	}
987	1015
988	1016	/**
989		- * Queue a message to a device.
	1017	+ * __ap_queue_message(): Queue a message to a device.
990	1018	* @ap_dev: pointer to the AP device
991	1019	* @ap_msg: the message to be queued
	1020	+ *
	1021	+ * Queue a message to a device. Returns 0 if successful.
992	1022	*/
993	1023	static int __ap_queue_message(struct ap_device ap_dev, struct ap_message ap_msg)
994	1024	{
995	1025
996	1026
...	...	@@ -1055,12 +1085,14 @@
1055	1085	EXPORT_SYMBOL(ap_queue_message);
1056	1086
1057	1087	/**
	1088	+ * ap_cancel_message(): Cancel a crypto request.
	1089	+ * @ap_dev: The AP device that has the message queued
	1090	+ * @ap_msg: The message that is to be removed
	1091	+ *
1058	1092	* Cancel a crypto request. This is done by removing the request
1059		- * from the devive pendingq or requestq queue. Note that the
	1093	+ * from the device pending or request queue. Note that the
1060	1094	* request stays on the AP queue. When it finishes the message
1061	1095	* reply will be discarded because the psmid can't be found.
1062		- * @ap_dev: AP device that has the message queued
1063		- * @ap_msg: the message that is to be removed
1064	1096	*/
1065	1097	void ap_cancel_message(struct ap_device ap_dev, struct ap_message ap_msg)
1066	1098	{
...	...	@@ -1082,7 +1114,10 @@
1082	1114	EXPORT_SYMBOL(ap_cancel_message);
1083	1115
1084	1116	/**
1085		- * AP receive polling for finished AP requests
	1117	+ * ap_poll_timeout(): AP receive polling for finished AP requests.
	1118	+ * @unused: Unused variable.
	1119	+ *
	1120	+ * Schedules the AP tasklet.
1086	1121	*/
1087	1122	static void ap_poll_timeout(unsigned long unused)
1088	1123	{
...	...	@@ -1090,6 +1125,9 @@
1090	1125	}
1091	1126
1092	1127	/**
	1128	+ * ap_reset(): Reset a not responding AP device.
	1129	+ * @ap_dev: Pointer to the AP device
	1130	+ *
1093	1131	* Reset a not responding AP device and move all requests from the
1094	1132	* pending queue to the request queue.
1095	1133	*/
...	...	@@ -1108,11 +1146,6 @@
1108	1146	ap_dev->unregistered = 1;
1109	1147	}
1110	1148
1111		-/**
1112		- * Poll all AP devices on the bus in a round robin fashion. Continue
1113		- * polling until bit 2^0 of the control flags is not set. If bit 2^1
1114		- * of the control flags has been set arm the poll timer.
1115		- */
1116	1149	static int __ap_poll_all(struct ap_device ap_dev, unsigned long flags)
1117	1150	{
1118	1151	spin_lock(&ap_dev->lock);
...	...	@@ -1126,6 +1159,14 @@
1126	1159	return 0;
1127	1160	}
1128	1161
	1162	+/**
	1163	+ * ap_poll_all(): Poll all AP devices.
	1164	+ * @dummy: Unused variable
	1165	+ *
	1166	+ * Poll all AP devices on the bus in a round robin fashion. Continue
	1167	+ * polling until bit 2^0 of the control flags is not set. If bit 2^1
	1168	+ * of the control flags has been set arm the poll timer.
	1169	+ */
1129	1170	static void ap_poll_all(unsigned long dummy)
1130	1171	{
1131	1172	unsigned long flags;
...	...	@@ -1144,6 +1185,9 @@
1144	1185	}
1145	1186
1146	1187	/**
	1188	+ * ap_poll_thread(): Thread that polls for finished requests.
	1189	+ * @data: Unused pointer
	1190	+ *
1147	1191	* AP bus poll thread. The purpose of this thread is to poll for
1148	1192	* finished requests in a loop if there is a "free" cpu - that is
1149	1193	* a cpu that doesn't have anything better to do. The polling stops
...	...	@@ -1213,7 +1257,10 @@
1213	1257	}
1214	1258
1215	1259	/**
1216		- * Handling of request timeouts
	1260	+ * ap_request_timeout(): Handling of request timeouts
	1261	+ * @data: Holds the AP device.
	1262	+ *
	1263	+ * Handles request timeouts.
1217	1264	*/
1218	1265	static void ap_request_timeout(unsigned long data)
1219	1266	{
...	...	@@ -1246,7 +1293,9 @@
1246	1293	};
1247	1294
1248	1295	/**
1249		- * The module initialization code.
	1296	+ * ap_module_init(): The module initialization code.
	1297	+ *
	1298	+ * Initializes the module.
1250	1299	*/
1251	1300	int __init ap_module_init(void)
1252	1301	{
...	...	@@ -1288,7 +1337,7 @@
1288	1337	if (ap_select_domain() == 0)
1289	1338	ap_scan_bus(NULL);
1290	1339
1291		- /* Setup the ap bus rescan timer. */
	1340	+ /* Setup the AP bus rescan timer. */
1292	1341	init_timer(&ap_config_timer);
1293	1342	ap_config_timer.function = ap_config_timeout;
1294	1343	ap_config_timer.data = 0;
...	...	@@ -1325,7 +1374,9 @@
1325	1374	}
1326	1375
1327	1376	/**
1328		- * The module termination code
	1377	+ * ap_modules_exit(): The module termination code
	1378	+ *
	1379	+ * Terminates the module.
1329	1380	*/
1330	1381	void ap_module_exit(void)
1331	1382	{
...	...	@@ -50,6 +50,15 @@
50	50	#define AP_QID_QUEUE(_qid) ((_qid) & 15)
51	51
52	52	/**
	53	+ * structy ap_queue_status - Holds the AP queue status.
	54	+ * @queue_empty: Shows if queue is empty
	55	+ * @replies_waiting: Waiting replies
	56	+ * @queue_full: Is 1 if the queue is full
	57	+ * @pad: A 4 bit pad
	58	+ * @int_enabled: Shows if interrupts are enabled for the AP
	59	+ * @response_conde: Holds the 8 bit response code
	60	+ * @pad2: A 16 bit pad
	61	+ *
53	62	* The ap queue status word is returned by all three AP functions
54	63	* (PQAP, NQAP and DQAP). There's a set of flags in the first
55	64	* byte, followed by a 1 byte response code.
...	...	@@ -75,7 +84,7 @@
75	84	#define AP_RESPONSE_NO_FIRST_PART 0x13
76	85	#define AP_RESPONSE_MESSAGE_TOO_BIG 0x15
77	86
78		-/**
	87	+/*
79	88	* Known device types
80	89	*/
81	90	#define AP_DEVICE_TYPE_PCICC 3
...	...	@@ -84,7 +93,7 @@
84	93	#define AP_DEVICE_TYPE_CEX2A 6
85	94	#define AP_DEVICE_TYPE_CEX2C 7
86	95
87		-/**
	96	+/*
88	97	* AP reset flag states
89	98	*/
90	99	#define AP_RESET_IGNORE 0 /* request timeout will be ignored */
...	...	@@ -152,7 +161,7 @@
152	161	.dev_type=(dt), \
153	162	.match_flags=AP_DEVICE_ID_MATCH_DEVICE_TYPE,
154	163
155		-/**
	164	+/*
156	165	* Note: don't use ap_send/ap_recv after using ap_queue_message
157	166	* for the first time. Otherwise the ap message queue will get
158	167	* confused.
...	...	@@ -40,7 +40,7 @@
40	40
41	41	#include "zcrypt_api.h"
42	42
43		-/**
	43	+/*
44	44	* Module description.
45	45	*/
46	46	MODULE_AUTHOR("IBM Corporation");
...	...	@@ -56,7 +56,7 @@
56	56	static int zcrypt_rng_device_add(void);
57	57	static void zcrypt_rng_device_remove(void);
58	58
59		-/**
	59	+/*
60	60	* Device attributes common for all crypto devices.
61	61	*/
62	62	static ssize_t zcrypt_type_show(struct device *dev,
...	...	@@ -103,6 +103,9 @@
103	103	};
104	104
105	105	/**
	106	+ * __zcrypt_increase_preference(): Increase preference of a crypto device.
	107	+ * @zdev: Pointer the crypto device
	108	+ *
106	109	* Move the device towards the head of the device list.
107	110	* Need to be called while holding the zcrypt device list lock.
108	111	* Note: cards with speed_rating of 0 are kept at the end of the list.
...	...	@@ -129,6 +132,9 @@
129	132	}
130	133
131	134	/**
	135	+ * __zcrypt_decrease_preference(): Decrease preference of a crypto device.
	136	+ * @zdev: Pointer to a crypto device.
	137	+ *
132	138	* Move the device towards the tail of the device list.
133	139	* Need to be called while holding the zcrypt device list lock.
134	140	* Note: cards with speed_rating of 0 are kept at the end of the list.
...	...	@@ -202,7 +208,10 @@
202	208	EXPORT_SYMBOL(zcrypt_device_free);
203	209
204	210	/**
205		- * Register a crypto device.
	211	+ * zcrypt_device_register() - Register a crypto device.
	212	+ * @zdev: Pointer to a crypto device
	213	+ *
	214	+ * Register a crypto device. Returns 0 if successful.
206	215	*/
207	216	int zcrypt_device_register(struct zcrypt_device *zdev)
208	217	{
...	...	@@ -242,6 +251,9 @@
242	251	EXPORT_SYMBOL(zcrypt_device_register);
243	252
244	253	/**
	254	+ * zcrypt_device_unregister(): Unregister a crypto device.
	255	+ * @zdev: Pointer to crypto device
	256	+ *
245	257	* Unregister a crypto device.
246	258	*/
247	259	void zcrypt_device_unregister(struct zcrypt_device *zdev)
...	...	@@ -260,7 +272,9 @@
260	272	EXPORT_SYMBOL(zcrypt_device_unregister);
261	273
262	274	/**
263		- * zcrypt_read is not be supported beyond zcrypt 1.3.1
	275	+ * zcrypt_read (): Not supported beyond zcrypt 1.3.1.
	276	+ *
	277	+ * This function is not supported beyond zcrypt 1.3.1.
264	278	*/
265	279	static ssize_t zcrypt_read(struct file filp, char __user buf,
266	280	size_t count, loff_t *f_pos)
...	...	@@ -269,6 +283,8 @@
269	283	}
270	284
271	285	/**
	286	+ * zcrypt_write(): Not allowed.
	287	+ *
272	288	* Write is is not allowed
273	289	*/
274	290	static ssize_t zcrypt_write(struct file filp, const char __user buf,
...	...	@@ -278,7 +294,9 @@
278	294	}
279	295
280	296	/**
281		- * Device open/close functions to count number of users.
	297	+ * zcrypt_open(): Count number of users.
	298	+ *
	299	+ * Device open function to count number of users.
282	300	*/
283	301	static int zcrypt_open(struct inode inode, struct file filp)
284	302	{
285	303
...	...	@@ -286,13 +304,18 @@
286	304	return 0;
287	305	}
288	306
	307	+/**
	308	+ * zcrypt_release(): Count number of users.
	309	+ *
	310	+ * Device close function to count number of users.
	311	+ */
289	312	static int zcrypt_release(struct inode inode, struct file filp)
290	313	{
291	314	atomic_dec(&zcrypt_open_count);
292	315	return 0;
293	316	}
294	317
295		-/**
	318	+/*
296	319	* zcrypt ioctls.
297	320	*/
298	321	static long zcrypt_rsa_modexpo(struct ica_rsa_modexpo *mex)
...	...	@@ -302,7 +325,7 @@
302	325
303	326	if (mex->outputdatalength < mex->inputdatalength)
304	327	return -EINVAL;
305		- /**
	328	+ /*
306	329	* As long as outputdatalength is big enough, we can set the
307	330	* outputdatalength equal to the inputdatalength, since that is the
308	331	* number of bytes we will copy in any case
...	...	@@ -348,7 +371,7 @@
348	371	if (crt->outputdatalength < crt->inputdatalength \|\|
349	372	(crt->inputdatalength & 1))
350	373	return -EINVAL;
351		- /**
	374	+ /*
352	375	* As long as outputdatalength is big enough, we can set the
353	376	* outputdatalength equal to the inputdatalength, since that is the
354	377	* number of bytes we will copy in any case
...	...	@@ -365,7 +388,7 @@
365	388	zdev->max_mod_size < crt->inputdatalength)
366	389	continue;
367	390	if (zdev->short_crt && crt->inputdatalength > 240) {
368		- /**
	391	+ /*
369	392	* Check inputdata for leading zeros for cards
370	393	* that can't handle np_prime, bp_key, or
371	394	* u_mult_inv > 128 bytes.
...	...	@@ -381,7 +404,7 @@
381	404	copy_from_user(&z3, crt->u_mult_inv, len))
382	405	return -EFAULT;
383	406	copied = 1;
384		- /**
	407	+ /*
385	408	* We have to restart device lookup -
386	409	* the device list may have changed by now.
387	410	*/
...	...	@@ -567,6 +590,8 @@
567	590	}
568	591
569	592	/**
	593	+ * zcrypt_ica_status(): Old, depracted combi status call.
	594	+ *
570	595	* Old, deprecated combi status call.
571	596	*/
572	597	static long zcrypt_ica_status(struct file *filp, unsigned long arg)
...	...	@@ -668,7 +693,7 @@
668	693	(int __user *) arg);
669	694	case Z90STAT_DOMAIN_INDEX:
670	695	return put_user(ap_domain_index, (int __user *) arg);
671		- /**
	696	+ /*
672	697	* Deprecated ioctls. Don't add another device count ioctl,
673	698	* you can count them yourself in the user space with the
674	699	* output of the Z90STAT_STATUS_MASK ioctl.
...	...	@@ -706,7 +731,7 @@
706	731	}
707	732
708	733	#ifdef CONFIG_COMPAT
709		-/**
	734	+/*
710	735	* ioctl32 conversion routines
711	736	*/
712	737	struct compat_ica_rsa_modexpo {
...	...	@@ -857,7 +882,7 @@
857	882	}
858	883	#endif
859	884
860		-/**
	885	+/*
861	886	* Misc device file operations.
862	887	*/
863	888	static const struct file_operations zcrypt_fops = {
...	...	@@ -872,7 +897,7 @@
872	897	.release = zcrypt_release
873	898	};
874	899
875		-/**
	900	+/*
876	901	* Misc device.
877	902	*/
878	903	static struct miscdevice zcrypt_misc_device = {
...	...	@@ -881,7 +906,7 @@
881	906	.fops = &zcrypt_fops,
882	907	};
883	908
884		-/**
	909	+/*
885	910	* Deprecated /proc entry support.
886	911	*/
887	912	static struct proc_dir_entry *zcrypt_entry;
...	...	@@ -1075,7 +1100,7 @@
1075	1100	}
1076	1101
1077	1102	for (j = 0; j < 64 && *ptr; ptr++) {
1078		- /**
	1103	+ /*
1079	1104	* '0' for no device, '1' for PCICA, '2' for PCICC,
1080	1105	* '3' for PCIXCC_MCL2, '4' for PCIXCC_MCL3,
1081	1106	* '5' for CEX2C and '6' for CEX2A'
...	...	@@ -1103,7 +1128,7 @@
1103	1128	{
1104	1129	int rc;
1105	1130
1106		- /**
	1131	+ /*
1107	1132	* We don't need locking here because the RNG API guarantees serialized
1108	1133	* read method calls.
1109	1134	*/
...	...	@@ -1162,6 +1187,8 @@
1162	1187	}
1163	1188
1164	1189	/**
	1190	+ * zcrypt_api_init(): Module initialization.
	1191	+ *
1165	1192	* The module initialization code.
1166	1193	*/
1167	1194	int __init zcrypt_api_init(void)
...	...	@@ -1196,6 +1223,8 @@
1196	1223	}
1197	1224
1198	1225	/**
	1226	+ * zcrypt_api_exit(): Module termination.
	1227	+ *
1199	1228	* The module termination code.
1200	1229	*/
1201	1230	void zcrypt_api_exit(void)
...	...	@@ -174,7 +174,7 @@
174	174	key->pvtMeHdr = static_pvt_me_hdr;
175	175	key->pvtMeSec = static_pvt_me_sec;
176	176	key->pubMeSec = static_pub_me_sec;
177		- /**
	177	+ /*
178	178	* In a private key, the modulus doesn't appear in the public
179	179	* section. So, an arbitrary public exponent of 0x010001 will be
180	180	* used.
...	...	@@ -338,7 +338,7 @@
338	338	pub = (struct cca_public_sec *)(key->key_parts + key_len);
339	339	*pub = static_cca_pub_sec;
340	340	pub->modulus_bit_len = 8 * crt->inputdatalength;
341		- /**
	341	+ /*
342	342	* In a private key, the modulus doesn't appear in the public
343	343	* section. So, an arbitrary public exponent of 0x010001 will be
344	344	* used.
...	...	@@ -108,7 +108,7 @@
108	108	return -EINVAL;
109	109	case REP82_ERROR_MESSAGE_TYPE:
110	110	// REP88_ERROR_MESSAGE_TYPE // '20' CEX2A
111		- /**
	111	+ /*
112	112	* To sent a message of the wrong type is a bug in the
113	113	* device driver. Warn about it, disable the device
114	114	* and then repeat the request.
...	...	@@ -42,7 +42,7 @@
42	42	#define PCICC_MAX_MOD_SIZE_OLD 128 /* 1024 bits */
43	43	#define PCICC_MAX_MOD_SIZE 256 /* 2048 bits */
44	44
45		-/**
	45	+/*
46	46	* PCICC cards need a speed rating of 0. This keeps them at the end of
47	47	* the zcrypt device list (see zcrypt_api.c). PCICC cards are only
48	48	* used if no other cards are present because they are slow and can only
...	...	@@ -388,7 +388,7 @@
388	388	reply_len = le16_to_cpu(msg->length) - 2;
389	389	if (reply_len > outputdatalength)
390	390	return -EINVAL;
391		- /**
	391	+ /*
392	392	* For all encipher requests, the length of the ciphertext (reply_len)
393	393	* will always equal the modulus length. For MEX decipher requests
394	394	* the output needs to get padded. Minimum pad size is 10.
...	...	@@ -501,7 +501,7 @@
501	501	reply_len = msg->length - 2;
502	502	if (reply_len > outputdatalength)
503	503	return -EINVAL;
504		- /**
	504	+ /*
505	505	* For all encipher requests, the length of the ciphertext (reply_len)
506	506	* will always equal the modulus length. For MEX decipher requests
507	507	* the output needs to get padded. Minimum pad size is 10.