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.

Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/Documentation/index.rst b/Documentation/index.rst
index e0fc72963e879d11dd70985bb1d1ed500694a9a5..0058b65d361c7faea54f0208316393e3ef66e402 100644 (file)
--- 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 (file)
index 0000000..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.rst b/Documentation/tpm/tpm_vtpm_proxy.rst
new file mode 100644 (file)
index 0000000..ea08e76
--- /dev/null
+++ b/Documentation/tpm/tpm_vtpm_proxy.rst
@@ -0,0 +1,50 @@
+=============================================
+Virtual TPM Proxy Driver for Linux Containers
+=============================================
+
+| Authors:
+| Stefan Berger <stefanb@linux.vnet.ibm.com>
+
+This document describes the virtual Trusted Platform Module (vTPM)
+proxy device driver for Linux containers.
+
+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
+======
+
+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
+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``
+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 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.
+
+UAPI
+====
+
+.. kernel-doc:: include/uapi/linux/vtpm_proxy.h
+
+.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c
+   :functions: vtpmx_ioc_new_dev

diff --git a/Documentation/tpm/tpm_vtpm_proxy.txt b/Documentation/tpm/tpm_vtpm_proxy.txt
deleted file mode 100644 (file)
index 30d1902..0000000
--- a/Documentation/tpm/tpm_vtpm_proxy.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-Virtual TPM Proxy Driver for Linux Containers
-
-Authors: Stefan Berger (IBM)
-
-This document describes the virtual Trusted Platform Module (vTPM)
-proxy device driver for Linux containers.
-
-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
-------
-
-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
-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
-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.
-
-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:
-
-- 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
-
-The TPM device /dev/tpmX will only appear if all of the relevant commands
-were responded to properly.