summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJarkko Sakkinen <jarkko.sakkinen@linux.intel.com>2016-11-03 17:57:51 -0600
committerJonathan Corbet <corbet@lwn.net>2016-11-07 18:56:38 -0700
commit9e355ba76455d6d44f5cf888eee820ae9a06b3ec (patch)
treef2e8a6fa58562b117a9455aff265973d6d9c1703
parentc8d2bc9bc39ebea8437fd974fdbc21847bb897a3 (diff)
downloadlinux-stable-9e355ba76455d6d44f5cf888eee820ae9a06b3ec.tar.gz
linux-stable-9e355ba76455d6d44f5cf888eee820ae9a06b3ec.tar.bz2
linux-stable-9e355ba76455d6d44f5cf888eee820ae9a06b3ec.zip
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>
-rw-r--r--Documentation/index.rst1
-rw-r--r--Documentation/tpm/index.rst7
-rw-r--r--Documentation/tpm/tpm_vtpm_proxy.rst (renamed from Documentation/tpm/tpm_vtpm_proxy.txt)55
3 files changed, 25 insertions, 38 deletions
diff --git a/Documentation/index.rst b/Documentation/index.rst
index e0fc72963e87..0058b65d361c 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 000000000000..af77a7bbb070
--- /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
index 30d19022f869..ea08e76b17f5 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 <stefanb@linux.vnet.ibm.com>
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 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