Skip to contentSkip to conversation

tpm: transition tpm_vtpm_proxy documentation to the Sphinx

PATCH In review Jarkko Sakkinen 3 participants 5 messages Nov 2, 2016 – Nov 3, 2016 1 message not in the archive

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 tpm: transition tpm_vtpm_proxy documentation to the Sphinx

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.

---
 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%)
Documentation/index.rst +1 -0
index e0fc729..0058b65 100644
@@ -19,6 +19,7 @@ Contents:
    media/dvb-drivers/index
    media/v4l-drivers/index
    gpu/index
+   tpm/index
 
 Indices and tables
 ==================
Documentation/tpm/index.rst new file +7 -0
new file mode 100644
index 0000000..316cdbb
@@ -0,0 +1,7 @@
+=================
+TPM documentation
+=================
+
+.. toctree::
+
+   tpm_vtpm_proxy
Documentation/tpm/tpm_vtpm_proxy.rst renamed from Documentation/tpm/tpm_vtpm_proxy.txt +16 -37

87 lines not on this page · raw message

drivers/char/tpm/tpm_vtpm_proxy.c +47 -25

92 lines not on this page · raw message

include/uapi/linux/vtpm_proxy.h +18 -5
index 41e8e22..84c1e0a 100644
@@ -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
+ * @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)
+#define VTPM_PROXY_IOC_NEW_DEV	_IOWR(0xa1, 0x00, struct vtpm_proxy_new_dev)
 
 #endif /* _UAPI_LINUX_VTPM_PROXY_H */
Signature · 1 line
2.9.3

A message that is not in the archive (sent off-list or not yet received): 20161102180207.16583-1-jarkko.sakkinen-VuQAYsv1563Yd54FQh9/[email protected]

#2 lore raw

Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/[email protected]> wrote on 11/02/2016 12:01:56 PM:

Quoted 7 lines

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.

Quoted 5 lines
---
 Documentation/index.rst                            |  1 +
 Documentation/tpm/index.rst                        |  7 +++
 .../tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} | 53 

+++++-----------

Quoted 6 lines
 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%)

Quoted 34 lines
Documentation/index.rst +1 -0
index e0fc729..0058b65 100644
@@ -19,6 +19,7 @@ Contents:
    media/dvb-drivers/index
    media/v4l-drivers/index
    gpu/index
+   tpm/index
 
 Indices and tables
 ==================
Documentation/tpm/index.rst new file +7 -0
new file mode 100644
index 0000000..316cdbb
@@ -0,0 +1,7 @@
+=================
+TPM documentation
+=================
+
+.. toctree::
+
+   tpm_vtpm_proxy
Documentation/ renamed from Documentation/tpm/tpm_vtpm_proxy.txt +0 -0

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

Documentation/tpm/tpm_vtpm_proxy.rst renamed from Documentation/tpm/tpm_vtpm_proxy.txt +0 -0

[...]

Quoted 1 line

To make an emulated software TPM available to each container, the

container

Quoted 1 line

management stack needs to create a device pair consisting of a client

TPM

Documentation/tpm/tpm_vtpm_proxy.rst

Quoted 2 lines
Documentation/tpm/tpm_vtpm_proxy.rst renamed from Documentation/tpm/tpm_vtpm_proxy.txt +1 -1
-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

Quoted 1 line

descriptor. The former is moved into the container by creating a

character

Quoted 1 line

device with the appropriate major and minor numbers while the file

descriptor

Quoted 1 line

is passed to the TPM emulator. Software inside the container can then

send

Quoted 1 line

TPM commands using the character device and the emulator will receive

the

Quoted 3 lines

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

Quoted 4 lines

+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

Quoted 1 line

whether TPM 1.2 or TPM 2 functionality is supported by the TPM

emulator.

Quoted 4 lines

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.

Documentation/tpm/tpm_vtpm_proxy.rst

Quoted 13 lines
Documentation/tpm/tpm_vtpm_proxy.rst renamed from Documentation/tpm/tpm_vtpm_proxy.txt +0 -13
-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

Quoted 3 lines

-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

Quoted 1 line

-ENOTTY.

Users would now have to look into the spec for this.

Documentation/tpm/tpm_vtpm_proxy.rst

Quoted 5 lines
Documentation/tpm/tpm_vtpm_proxy.rst renamed from Documentation/tpm/tpm_vtpm_proxy.txt +0 -2
-
-See /usr/include/linux/vtpm_proxy.h for definitions related to the 

public interface

Documentation/tpm/tpm_vtpm_proxy.rst renamed from Documentation/tpm/tpm_vtpm_proxy.txt +1 -1
-of this vTPM device driver.
+example ``/dev/tpm10`` was created, the number (``dev_num``) 10 is 

returned.

Quoted 2 lines

Once the device has been created, the driver will immediately try to

talk

Quoted 1 line

to the TPM. All commands from the driver can be read from the file

descriptor

Quoted 3 lines

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

Documentation/tpm/tpm_vtpm_proxy.rst

Quoted 13 lines
Documentation/tpm/tpm_vtpm_proxy.rst renamed from Documentation/tpm/tpm_vtpm_proxy.txt +3 -8
-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

Quoted 16 lines
Documentation/tpm/tpm_vtpm_proxy.rst renamed from Documentation/tpm/tpm_vtpm_proxy.txt +2 -1
-were responded to properly.
+.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c
+   :functions: vtpmx_ioc_new_dev
drivers/char/tpm/ renamed from drivers/char/tpm/tpm_vtpm_proxy.c +0 -0

tpm_vtpm_proxy.c
index 9a94033..a85d258 100644

drivers/char/tpm/tpm_vtpm_proxy.c +1 -0
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2015, 2016 IBM Corporation
+ * Copyright (C) 2016 Intel Corporation
  *
  * Author: Stefan Berger <stefanb-r/[email protected]>
  *

drivers/char/tpm/tpm_vtpm_proxy.c static void vtpm_proxy_delete_device(struct · line 530

Quoted 6 lines
drivers/char/tpm/tpm_vtpm_proxy.c +2 -0
@@ -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.

drivers/char/tpm/tpm_vtpm_proxy.c static void vtpm_proxy_delete_device(struct proxy_dev *proxy_dev)

Quoted 5 lines
drivers/char/tpm/tpm_vtpm_proxy.c +5 -0
+ * @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

Quoted 3 lines
drivers/char/tpm/tpm_vtpm_proxy.c +1 -0
+ * 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

Quoted 77 lines

+ * will be provided with a file descriptor to communicate with the clients and
+ * major and minor numbers for the TPM device.
+ */

drivers/char/tpm/tpm_vtpm_proxy.c +34 -25
+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;
    }

Review

Quoted 1 line
(quoted diff) +0 -0

b/include/uapi/linux/vtpm_proxy.h

include/uapi/linux/vtpm_proxy.h line 6

Quoted 10 lines

index 41e8e22..84c1e0a 100644

include/uapi/linux/vtpm_proxy.h +1 -0
@@ -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

include/uapi/linux/vtpm_proxy.h line 23

Quoted 8 lines
include/uapi/linux/vtpm_proxy.h +2 -1
  * 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 ?

include/uapi/linux/vtpm_proxy.h line 34

Quoted 11 lines
include/uapi/linux/vtpm_proxy.h +10 -0
+ * @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.

Quoted 8 lines
include/uapi/linux/vtpm_proxy.h +4 -0
+ * @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 */

include/uapi/linux/vtpm_proxy.h struct vtpm_proxy_new_dev { · line 34

Quoted 7 lines
include/uapi/linux/vtpm_proxy.h +0 -4
@@ -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)

include/uapi/linux/vtpm_proxy.h struct vtpm_proxy_new_dev { · line 47

Quoted 1 line
include/uapi/linux/vtpm_proxy.h +1 -0
+#define VTPM_PROXY_IOC_NEW_DEV   _IOWR(0xa1, 0x00, struct 

vtpm_proxy_new_dev)

Quoted 7 lines
include/uapi/linux/vtpm_proxy.h +0 -0
 #endif /* _UAPI_LINUX_VTPM_PROXY_H */
Signature · 1 line
2.9.3

------------------------------------------------------------------------------

Quoted 10 lines

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 [email protected]
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 [email protected]
https://lists.sourceforge.net/lists/listinfo/tpmdd-devel

#3 lore raw

Thanks for the comments. I'll revise this.

/Jarkko

Quoted 327 lines · Stefan Berger
   Jarkko Sakkinen <[email protected]> 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 <[email protected]>
   > ---
   >  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 <[email protected]>
   >   *
   > @@ -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
   > [email protected]
   > https://lists.sourceforge.net/lists/listinfo/tpmdd-devel
   >
#4 lore raw
In reply to Jarkko Sakkinen
Quoted 6 lines · Jarkko Sakkinen

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.

Quoted 7 lines
---
 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 +++++--

I'm not sure it's a good idea to combine this much code change with the documentation change. Perhaps split up, at least the function movement/abstraction bits?

Quoted 22 lines
 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%)
Documentation/index.rst +1 -0
index e0fc729..0058b65 100644
@@ -19,6 +19,7 @@ Contents:
    media/dvb-drivers/index
    media/v4l-drivers/index
    gpu/index
+   tpm/index
 
 Indices and tables
 ==================
Documentation/tpm/index.rst new file +0 -0
new file mode 100644
index 0000000..316cdbb

Documentation/tpm/index.rst line 3

Quoted 3 lines
Documentation/tpm/index.rst new file +3 -0
@@ -0,0 +1,7 @@
+=================
+TPM documentation
+=================

This will pop up at the top level of the documentation. I'm not saying that's necessarily wrong per se, but IMO you should spell out Trusted Platform Module here instead of just using the acronym.

(Sure we have "GPU" at the top level, but I think that's a better known acronym. And we might change that to "Graphics" anyway.)

BR,
Jani.

Signature · 1 line
Jani Nikula, Intel Open Source Technology Center
#5 lore raw
Quoted 15 lines · Jani Nikula
Quoted 6 lines · Jarkko Sakkinen

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.

Quoted 7 lines
---
 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 +++++--
Quoted 3 lines

I'm not sure it's a good idea to combine this much code change with the documentation change. Perhaps split up, at least the function movement/abstraction bits?

Sure. I scraped this up quickly to get some feedback whether I'm doing this right at all :-)

Quoted 31 lines
Quoted 23 lines
 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%)
Documentation/index.rst +1 -0
index e0fc729..0058b65 100644
@@ -19,6 +19,7 @@ Contents:
    media/dvb-drivers/index
    media/v4l-drivers/index
    gpu/index
+   tpm/index
 
 Indices and tables
 ==================
Documentation/tpm/index.rst new file +0 -0
new file mode 100644
index 0000000..316cdbb

Documentation/tpm/index.rst line 3

Quoted 3 lines
Documentation/tpm/index.rst new file +3 -0
@@ -0,0 +1,7 @@
+=================
+TPM documentation
+=================

This will pop up at the top level of the documentation. I'm not saying that's necessarily wrong per se, but IMO you should spell out Trusted Platform Module here instead of just using the acronym.

Quoted 2 lines

(Sure we have "GPU" at the top level, but I think that's a better known acronym. And we might change that to "Graphics" anyway.)

Got you. I'll change it to Trusted Platform Module.

Quoted 6 lines

BR,
Jani.

Signature · 1 line
Jani Nikula, Intel Open Source Technology Center

/Jarkko

------------------------------------------------------------------------------
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