tpm, tpm_vtpm_proxy: add kdoc comments for VTPM_PROXY_IOC_NEW_DEV

Added kdoc comments for VTPM_PROXY_IOC_NEW_DEV so that these can be
imported to the kernel documentation written with rst markup and
generated with Sphinx.
Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
Reviewed-by: Stefan Berger <stefanb@linux.vnet.ibm.com>

drivers/char/tpm/tpm_vtpm_proxy.c

 /*
  * Copyright (C) 2015, 2016 IBM Corporation
+ * Copyright (C) 2016 Intel Corporation
  *
  * Author: Stefan Berger <stefanb@us.ibm.com>
  *
@@ -524,41 +525,62 @@ static void vtpm_proxy_delete_device(struct proxy_dev *proxy_dev)
  * Code related to the control device /dev/vtpmx
  */
 
-/*
- * vtpmx_fops_ioctl: ioctl on /dev/vtpmx
+/**
+ * vtpmx_ioc_new_dev - handler for the %VTPM_PROXY_IOC_NEW_DEV ioctl
+ * @file:	/dev/vtpmx
+ * @ioctl:	the ioctl number
+ * @arg:	pointer to the struct vtpmx_proxy_new_dev
  *
- * Return value:
- *      Returns 0 on success, a negative error code otherwise.
+ * Creates an anonymous file that is used by the process acting as a TPM to
+ * communicate with the client processes. The function will also add a new TPM
+ * device through which data is proxied to this TPM acting process. The caller
+ * will be provided with a file descriptor to communicate with the clients and
+ * major and minor numbers for the TPM device.
  */
-static long vtpmx_fops_ioctl(struct file *f, unsigned int ioctl,
+static long vtpmx_ioc_new_dev(struct file *file, unsigned int ioctl,
 			      unsigned long arg)
 {
 	void __user *argp = (void __user *)arg;
 	struct vtpm_proxy_new_dev __user *vtpm_new_dev_p;
 	struct vtpm_proxy_new_dev vtpm_new_dev;
-	struct file *file;
+	struct file *vtpm_file;
 
-	switch (ioctl) {
-	case VTPM_PROXY_IOC_NEW_DEV:
 	if (!capable(CAP_SYS_ADMIN))
 		return -EPERM;
+
 	vtpm_new_dev_p = argp;
+
 	if (copy_from_user(&vtpm_new_dev, vtpm_new_dev_p,
 			   sizeof(vtpm_new_dev)))
 		return -EFAULT;
-		file = vtpm_proxy_create_device(&vtpm_new_dev);
-		if (IS_ERR(file))
-			return PTR_ERR(file);
+
+	vtpm_file = vtpm_proxy_create_device(&vtpm_new_dev);
+	if (IS_ERR(vtpm_file))
+		return PTR_ERR(vtpm_file);
+
 	if (copy_to_user(vtpm_new_dev_p, &vtpm_new_dev,
 			 sizeof(vtpm_new_dev))) {
 		put_unused_fd(vtpm_new_dev.fd);
-			fput(file);
+		fput(vtpm_file);
 		return -EFAULT;
 	}
 
-		fd_install(vtpm_new_dev.fd, file);
+	fd_install(vtpm_new_dev.fd, vtpm_file);
 	return 0;
+}
 
+/*
+ * vtpmx_fops_ioctl: ioctl on /dev/vtpmx
+ *
+ * Return value:
+ *      Returns 0 on success, a negative error code otherwise.
+ */
+static long vtpmx_fops_ioctl(struct file *f, unsigned int ioctl,
+			     unsigned long arg)
+{
+	switch (ioctl) {
+	case VTPM_PROXY_IOC_NEW_DEV:
+		return vtpmx_ioc_new_dev(f, ioctl, arg);
 	default:
 		return -ENOIOCTLCMD;
 	}

include/uapi/linux/vtpm_proxy.h

 /*
  * Definitions for the VTPM proxy driver
  * Copyright (c) 2015, 2016, IBM Corporation
+ * Copyright (C) 2016 Intel Corporation
  *
  * This program is free software; you can redistribute it and/or modify it
  * under the terms and conditions of the GNU General Public License,
@@ -18,8 +19,23 @@
 #include <linux/types.h>
 #include <linux/ioctl.h>
 
-/* ioctls */
+/**
+ * enum vtpm_proxy_flags - flags for the proxy TPM
+ * @VTPM_PROXY_FLAG_TPM2:	the proxy TPM uses TPM 2.0 protocol
+ */
+enum vtpm_proxy_flags {
+	VTPM_PROXY_FLAG_TPM2	= 1,
+};
 
+/**
+ * struct vtpm_proxy_new_dev - parameter structure for the
+ *                             %VTPM_PROXY_IOC_NEW_DEV ioctl
+ * @flags:	flags for the proxy TPM
+ * @tpm_num:	index of the TPM device
+ * @fd:		the file descriptor used by the proxy TPM
+ * @major:	the major number of the TPM device
+ * @minor:	the minor number of the TPM device
+ */
 struct vtpm_proxy_new_dev {
 	__u32 flags;         /* input */
 	__u32 tpm_num;       /* output */
@@ -28,9 +44,6 @@ struct vtpm_proxy_new_dev {
 	__u32 minor;         /* output */
 };
 
-/* above flags */
-#define VTPM_PROXY_FLAG_TPM2  1  /* emulator is TPM 2 */
-
 #define VTPM_PROXY_IOC_NEW_DEV	_IOWR(0xa1, 0x00, struct vtpm_proxy_new_dev)
 
 #endif /* _UAPI_LINUX_VTPM_PROXY_H */