Re: [PATCH 2/3] tpm: transition tpm_vtpm_proxy documentation to the Sphinx

[Stefan Berger]

On 11/04/2016 11:01 PM, Jarkko Sakkinen wrote:

On Thu, Nov 03, 2016 at 05:57:51PM -0600, Jarkko Sakkinen wrote:

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 

Stefan?


Reviewed-by: Stefan Berger 




/Jarkko


---
  Documentation/index.rst|  1 +
  Documentation/tpm/index.rst|  7 +++
  .../tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} | 55 +++---
  3 files changed, 25 insertions(+), 38 deletions(-)
  create mode 100644 Documentation/tpm/index.rst
  rename Documentation/tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} (53%)

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 000..af77a7b
--- /dev/null
+++ b/Documentation/tpm/index.rst
@@ -0,0 +1,7 @@
+=
+Trusted Platform Module documentation
+=
+
+.. toctree::
+
+   tpm_vtpm_proxy
diff --git a/Documentation/tpm/tpm_vtpm_proxy.txt 
b/Documentation/tpm/tpm_vtpm_proxy.rst
similarity index 53%
rename from Documentation/tpm/tpm_vtpm_proxy.txt
rename to Documentation/tpm/tpm_vtpm_proxy.rst
index 30d1902..ea08e76 100644
--- a/Documentation/tpm/tpm_vtpm_proxy.txt
+++ b/Documentation/tpm/tpm_vtpm_proxy.rst
@@ -1,71 +1,50 @@
+=
  Virtual TPM Proxy Driver for Linux Containers
+=
  
-Authors: Stefan Berger (IBM)

+| Authors:
+| Stefan Berger 
  
  This document describes the virtual Trusted Platform Module (vTPM)

  proxy device driver for Linux containers.
  
-INTRODUCTION

-
+Introduction
+
  
  The goal of this work is to provide TPM functionality to each Linux

  container. This allows programs to interact with a TPM in a container
  the same way they interact with a TPM on the physical system. Each
  container gets its own unique, emulated, software TPM.
  
-

-DESIGN
---
+Design
+==
  
  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
-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, the ioctl 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.
-
-See /usr/include/linux/vtpm_proxy.h for definitions related to the public 
interface
-of this vTPM device driver.
+Besides that the number of the TPM character device is returned. If for
+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 

Re: [PATCH 2/3] tpm: transition tpm_vtpm_proxy documentation to the Sphinx

[Jarkko Sakkinen]

On Thu, Nov 03, 2016 at 05:57:51PM -0600, Jarkko Sakkinen wrote:
> 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 

Stefan?

/Jarkko

> ---
>  Documentation/index.rst|  1 +
>  Documentation/tpm/index.rst|  7 +++
>  .../tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} | 55 
> +++---
>  3 files changed, 25 insertions(+), 38 deletions(-)
>  create mode 100644 Documentation/tpm/index.rst
>  rename Documentation/tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} (53%)
> 
> 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 000..af77a7b
> --- /dev/null
> +++ b/Documentation/tpm/index.rst
> @@ -0,0 +1,7 @@
> +=
> +Trusted Platform Module documentation
> +=
> +
> +.. toctree::
> +
> +   tpm_vtpm_proxy
> diff --git a/Documentation/tpm/tpm_vtpm_proxy.txt 
> b/Documentation/tpm/tpm_vtpm_proxy.rst
> similarity index 53%
> rename from Documentation/tpm/tpm_vtpm_proxy.txt
> rename to Documentation/tpm/tpm_vtpm_proxy.rst
> index 30d1902..ea08e76 100644
> --- a/Documentation/tpm/tpm_vtpm_proxy.txt
> +++ b/Documentation/tpm/tpm_vtpm_proxy.rst
> @@ -1,71 +1,50 @@
> +=
>  Virtual TPM Proxy Driver for Linux Containers
> +=
>  
> -Authors: Stefan Berger (IBM)
> +| Authors:
> +| Stefan Berger 
>  
>  This document describes the virtual Trusted Platform Module (vTPM)
>  proxy device driver for Linux containers.
>  
> -INTRODUCTION
> -
> +Introduction
> +
>  
>  The goal of this work is to provide TPM functionality to each Linux
>  container. This allows programs to interact with a TPM in a container
>  the same way they interact with a TPM on the physical system. Each
>  container gets its own unique, emulated, software TPM.
>  
> -
> -DESIGN
> ---
> +Design
> +==
>  
>  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
> -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, the ioctl 
> 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.
> -
> -See /usr/include/linux/vtpm_proxy.h for definitions related to the public 
> interface
> -of this vTPM device driver.
> +Besides that the number of the TPM character device is returned. If for
> +example ``/dev/tpm10`` was created, the number (``dev_num``) 10 is returned.
>  
>  Once the device has been created, the driver will immediately try 

[PATCH 2/3] tpm: transition tpm_vtpm_proxy documentation to the Sphinx

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

Signed-off-by: Jarkko Sakkinen 
---
 Documentation/index.rst|  1 +
 Documentation/tpm/index.rst|  7 +++
 .../tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} | 55 +++---
 3 files changed, 25 insertions(+), 38 deletions(-)
 create mode 100644 Documentation/tpm/index.rst
 rename Documentation/tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} (53%)

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 000..af77a7b
--- /dev/null
+++ b/Documentation/tpm/index.rst
@@ -0,0 +1,7 @@
+=
+Trusted Platform Module documentation
+=
+
+.. toctree::
+
+   tpm_vtpm_proxy
diff --git a/Documentation/tpm/tpm_vtpm_proxy.txt 
b/Documentation/tpm/tpm_vtpm_proxy.rst
similarity index 53%
rename from Documentation/tpm/tpm_vtpm_proxy.txt
rename to Documentation/tpm/tpm_vtpm_proxy.rst
index 30d1902..ea08e76 100644
--- a/Documentation/tpm/tpm_vtpm_proxy.txt
+++ b/Documentation/tpm/tpm_vtpm_proxy.rst
@@ -1,71 +1,50 @@
+=
 Virtual TPM Proxy Driver for Linux Containers
+=
 
-Authors: Stefan Berger (IBM)
+| Authors:
+| Stefan Berger 
 
 This document describes the virtual Trusted Platform Module (vTPM)
 proxy device driver for Linux containers.
 
-INTRODUCTION
-
+Introduction
+
 
 The goal of this work is to provide TPM functionality to each Linux
 container. This allows programs to interact with a TPM in a container
 the same way they interact with a TPM on the physical system. Each
 container gets its own unique, emulated, software TPM.
 
-
-DESIGN
---
+Design
+==
 
 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
-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, the ioctl 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.
-
-See /usr/include/linux/vtpm_proxy.h for definitions related to the public 
interface
-of this vTPM device driver.
+Besides that the number of the TPM character device is returned. If for
+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