static void ap_poll_thread_stop(void);
static void ap_request_timeout(unsigned long);
-/**
+/*
* Module description.
*/
MODULE_AUTHOR("IBM Corporation");
"Copyright 2006 IBM Corporation");
MODULE_LICENSE("GPL");
-/**
+/*
* Module parameter
*/
int ap_domain_index = -1; /* Adjunct Processor Domain Index */
static DEFINE_SPINLOCK(ap_device_lock);
static LIST_HEAD(ap_device_list);
-/**
+/*
* Workqueue & timer for bus rescan.
*/
static struct workqueue_struct *ap_work_queue;
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);
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)
{
}
/**
- * 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)
}
/**
- * 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)
{
}
/**
- * 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.
+ * __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.
* 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.
*/
}
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
- *
- * Returns ap queue status structure.
+/**
+ * __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.
* 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.
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)
{
}
/**
+ * 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)
{
}
/**
- * 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)
{
}
/**
- * 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)
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.
ap_dev->reset = AP_RESET_IGNORE;
}
-/**
+/*
* AP device related attributes.
*/
static ssize_t ap_hwtype_show(struct device *dev,
};
/**
+ * 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)
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.
*/
}
/**
- * 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)
{
}
/**
+ * __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)
{
}
EXPORT_SYMBOL(ap_driver_unregister);
-/**
+/*
* AP bus attributes.
*/
static ssize_t ap_domain_show(struct bus_type *bus, char *buf)
};
/**
- * 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.
}
/**
- * 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)
{
}
/**
- * 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)
{
}
/**
+ * ap_schedule_poll_timer(): Schedule poll timer.
+ *
* Set up the timer to run the poll tasklet
*/
static inline void ap_schedule_poll_timer(void)
}
/**
- * 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)
}
/**
- * 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)
}
/**
- * 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)
}
/**
- * 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)
{
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)
{
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)
{
}
/**
+ * 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.
*/
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);
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;
}
/**
+ * 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
}
/**
- * 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)
{
};
/**
- * The module initialization code.
+ * ap_module_init(): The module initialization code.
+ *
+ * Initializes the module.
*/
int __init ap_module_init(void)
{
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;
}
/**
- * The module termination code
+ * ap_modules_exit(): The module termination code
+ *
+ * Terminates the module.
*/
void ap_module_exit(void)
{
#include "zcrypt_api.h"
-/**
+/*
* Module description.
*/
MODULE_AUTHOR("IBM Corporation");
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,
};
/**
+ * __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.
}
/**
+ * __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.
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)
{
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)
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)
}
/**
+ * zcrypt_write(): Not allowed.
+ *
* Write is is not allowed
*/
static ssize_t zcrypt_write(struct file *filp, const char __user *buf,
}
/**
- * 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)
{
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)
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
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
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.
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.
*/
}
/**
+ * zcrypt_ica_status(): Old, depracted combi status call.
+ *
* Old, deprecated combi status call.
*/
static long zcrypt_ica_status(struct file *filp, unsigned long arg)
(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.
}
#ifdef CONFIG_COMPAT
-/**
+/*
* ioctl32 conversion routines
*/
struct compat_ica_rsa_modexpo {
}
#endif
-/**
+/*
* Misc device file operations.
*/
static const struct file_operations zcrypt_fops = {
.release = zcrypt_release
};
-/**
+/*
* Misc device.
*/
static struct miscdevice zcrypt_misc_device = {
.fops = &zcrypt_fops,
};
-/**
+/*
* Deprecated /proc entry support.
*/
static struct proc_dir_entry *zcrypt_entry;
}
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'
{
int rc;
- /**
+ /*
* We don't need locking here because the RNG API guarantees serialized
* read method calls.
*/
}
/**
+ * zcrypt_api_init(): Module initialization.
+ *
* The module initialization code.
*/
int __init zcrypt_api_init(void)
}
/**
+ * zcrypt_api_exit(): Module termination.
+ *
* The module termination code.
*/
void zcrypt_api_exit(void)
Code Review / linux-2.6.git / commitdiff