Jarkko Sakkinen <jarkko.sakki...@linux.intel.com> wrote on 11/02/2016
12:01:56 PM:
>
> Transitioned the tpm_vtpm_proxy documentation to the Sphinx
> infrastructure and removed parts from the documentation that are easier
> to pull from the sources. Restructured vtpm_proxy.h and tpm_vtpm_proxy.c
> to be compatible with this approach and wrote associated documentation
> comments.
>
> Signed-off-by: Jarkko Sakkinen <jarkko.sakki...@linux.intel.com>
> ---
> Documentation/index.rst | 1 +
> Documentation/tpm/index.rst | 7 +++
> .../tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} | 53
+++++-----------
> drivers/char/tpm/tpm_vtpm_proxy.c | 72 +++++++++++
> +++--------
> include/uapi/linux/vtpm_proxy.h | 23 +++++--
> 5 files changed, 89 insertions(+), 67 deletions(-)
> create mode 100644 Documentation/tpm/index.rst
> rename Documentation/tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst}
(56%)
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index e0fc729..0058b65 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -19,6 +19,7 @@ Contents:
> media/dvb-drivers/index
> media/v4l-drivers/index
> gpu/index
> + tpm/index
>
> Indices and tables
> ==================
> diff --git a/Documentation/tpm/index.rst b/Documentation/tpm/index.rst
> new file mode 100644
> index 0000000..316cdbb
> --- /dev/null
> +++ b/Documentation/tpm/index.rst
> @@ -0,0 +1,7 @@
> +=================
> +TPM documentation
> +=================
> +
> +.. toctree::
> +
> + tpm_vtpm_proxy
> diff --git a/Documentation/tpm/tpm_vtpm_proxy.txt b/Documentation/
> tpm/tpm_vtpm_proxy.rst
> similarity index 56%
> rename from Documentation/tpm/tpm_vtpm_proxy.txt
> rename to Documentation/tpm/tpm_vtpm_proxy.rst
> index 30d1902..f991aff 100644
> --- a/Documentation/tpm/tpm_vtpm_proxy.txt
> +++ b/Documentation/tpm/tpm_vtpm_proxy.rst
[...]
> To make an emulated software TPM available to each container, the
container
> management stack needs to create a device pair consisting of a client
TPM
> -character device /dev/tpmX (with X=0,1,2...) and a 'server side' file
> +character device ``/dev/tpmX`` (with X=0,1,2...) and a 'server side'
file
> descriptor. The former is moved into the container by creating a
character
> device with the appropriate major and minor numbers while the file
descriptor
> is passed to the TPM emulator. Software inside the container can then
send
> TPM commands using the character device and the emulator will receive
the
> commands via the file descriptor and use it for sending back responses.
>
> -To support this, the virtual TPM proxy driver provides a device
/dev/vtpmx
> +To support this, the virtual TPM proxy driver provides a device ``/
> dev/vtpmx``
> that is used to create device pairs using an ioctl. The ioctl takes as
> an input flags for configuring the device. The flags for example
indicate
> whether TPM 1.2 or TPM 2 functionality is supported by the TPM
emulator.
> The result of the ioctl are the file descriptor for the 'server side'
> as well as the major and minor numbers of the character device that
> was created.
> Besides that the number of the TPM character device is return. If for
Existing typo: return -> returned.
> -example /dev/tpm10 was created, the number (dev_num) 10 is returned.
> -
> -The following is the data structure of the TPM_PROXY_IOC_NEW_DEV ioctl:
> -
> -struct vtpm_proxy_new_dev {
> - __u32 flags; /* input */
> - __u32 tpm_num; /* output */
> - __u32 fd; /* output */
> - __u32 major; /* output */
> - __u32 minor; /* output */
> -};
> -
> -Note that if unsupported flags are passed to the device driver,
theioctl will
> -fail and errno will be set to EOPNOTSUPP. Similarly, if an
> unsupported ioctl is
> -called on the device driver, the ioctl will fail and errno will be set
to
> -ENOTTY.
Users would now have to look into the spec for this.
> -
> -See /usr/include/linux/vtpm_proxy.h for definitions related to the
> public interface
> -of this vTPM device driver.
> +example ``/dev/tpm10`` was created, the number (``dev_num``) 10 is
returned.
>
> Once the device has been created, the driver will immediately try to
talk
> to the TPM. All commands from the driver can be read from the file
descriptor
> returned by the ioctl. The commands should be responded to immediately.
>
> -Depending on the version of TPM the following commands will be sent by
the
> -driver:
> +UAPI
> +====
>
> -- TPM 1.2:
> - - the driver will send a TPM_Startup command to the TPM emulator
> - - the driver will send commands to read the command durations and
> - interface timeouts from the TPM emulator
> -- TPM 2:
> - - the driver will send a TPM2_Startup command to the TPM emulator
> +.. kernel-doc:: include/uapi/linux/vtpm_proxy.h
>
> -The TPM device /dev/tpmX will only appear if all of the relevant
commands
> -were responded to properly.
> +.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c
> + :functions: vtpmx_ioc_new_dev
> diff --git a/drivers/char/tpm/tpm_vtpm_proxy.c b/drivers/char/tpm/
> tpm_vtpm_proxy.c
> index 9a94033..a85d258 100644
> --- a/drivers/char/tpm/tpm_vtpm_proxy.c
> +++ b/drivers/char/tpm/tpm_vtpm_proxy.c
> @@ -1,5 +1,6 @@
> /*
> * Copyright (C) 2015, 2016 IBM Corporation
> + * Copyright (C) 2016 Intel Corporation
> *
> * Author: Stefan Berger <stef...@us.ibm.com>
> *
> @@ -524,6 +525,50 @@ static void vtpm_proxy_delete_device(struct
> proxy_dev *proxy_dev)
> * Code related to the control device /dev/vtpmx
> */
>
> +/**
> + * sgx_ioc_new_dev - handler for the %SGX_IOC_NEW_DEV ioctl
This does not correspond to the actual filename.
> + * @file: /dev/vtpmx
> + * @ioctl: the ioctl number
> + * @arg: pointer to the struct vtpmx_proxy_new_dev
> + *
> + * 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_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 *vtpm_file;
> +
> + 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;
> +
> + 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(vtpm_file);
> + return -EFAULT;
> + }
> +
> + fd_install(vtpm_new_dev.fd, vtpm_file);
> + return 0;
> +}
> +
> /*
> * vtpmx_fops_ioctl: ioctl on /dev/vtpmx
> *
> @@ -531,34 +576,11 @@ static void vtpm_proxy_delete_device(struct
> proxy_dev *proxy_dev)
> * Returns 0 on success, a negative error code otherwise.
> */
> static long vtpmx_fops_ioctl(struct file *f, unsigned int ioctl,
> - unsigned long arg)
> + 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;
> -
> 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);
> - if (copy_to_user(vtpm_new_dev_p, &vtpm_new_dev,
> - sizeof(vtpm_new_dev))) {
> - put_unused_fd(vtpm_new_dev.fd);
> - fput(file);
> - return -EFAULT;
> - }
> -
> - fd_install(vtpm_new_dev.fd, file);
> - return 0;
> -
> + return vtpmx_ioc_new_dev(f, ioctl, arg);
> default:
> return -ENOIOCTLCMD;
> }
> diff --git a/include/uapi/linux/vtpm_proxy.h
b/include/uapi/linux/vtpm_proxy.h
> index 41e8e22..84c1e0a 100644
> --- a/include/uapi/linux/vtpm_proxy.h
> +++ b/include/uapi/linux/vtpm_proxy.h
> @@ -1,6 +1,7 @@
> /*
> * 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 mipi_dsi_dcs_tear_mode - flags for the proxy TPM
mipi_dsi_tcs_tear_mode ?
> + * @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
The indentation for this one could be fixed.
> + * @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)
> +#define VTPM_PROXY_IOC_NEW_DEV _IOWR(0xa1, 0x00, struct
vtpm_proxy_new_dev)
>
> #endif /* _UAPI_LINUX_VTPM_PROXY_H */
> --
> 2.9.3
>
>
>
------------------------------------------------------------------------------
> Developer Access Program for Intel Xeon Phi Processors
> Access to Intel Xeon Phi processor-based developer platforms.
> With one year of Intel Parallel Studio XE.
> Training and support from Colfax.
> Order your platform today. http://sdm.link/xeonphi
> _______________________________________________
> tpmdd-devel mailing list
> tpmdd-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/tpmdd-devel
>
------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today. http://sdm.link/xeonphi
_______________________________________________
tpmdd-devel mailing list
tpmdd-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/tpmdd-devel
