Subject: Re: [PATCH 2/3] tpm: transition tpm_vtpm_proxy documentation to the
 Sphinx
To: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>,
        tpmdd-devel@lists.sourceforge.net
References: <20161103235752.19256-1-jarkko.sakkinen@linux.intel.com>
 <20161103235752.19256-3-jarkko.sakkinen@linux.intel.com>
 <20161105030115.zbcs3holsjnhlp3g@intel.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
        "open list:DOCUMENTATION" <linux-doc@vger.kernel.org>,
        open list <linux-kernel@vger.kernel.org>
From: Stefan Berger <stefanb@linux.vnet.ibm.com>
Date: Sun, 6 Nov 2016 19:47:30 -0500
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101
 Thunderbird/45.1.1
MIME-Version: 1.0
In-Reply-To: <20161105030115.zbcs3holsjnhlp3g@intel.com>
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 7bit
Message-Id: <e57ee508-60fb-27eb-5460-f83805d2131a@linux.vnet.ibm.com>
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 6083
Lines: 149

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 <jarkko.sakkinen@linux.intel.com>
> Stefan?

Reviewed-by: Stefan Berger <stefanb@linux.vnet.ibm.com>


>
> /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 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.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 <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
>> -- 
>> 2.9.3
>>