ia64/xen-unstable

changeset 9121:e0d8c23acaa7

Add a description of the virtual TPM interface to the interface
document and explain some of the internals of the device driver.

Signed-off-by: Stefan Berger <stefanb@us.ibm.com>
author kaf24@firebug.cl.cam.ac.uk
date Fri Mar 03 10:57:37 2006 +0100 (2006-03-03)
parents 4e7c8eae6775
children 658528fe2b9a
files docs/src/interface.tex
line diff
     1.1 --- a/docs/src/interface.tex	Fri Mar 03 10:56:54 2006 +0100
     1.2 +++ b/docs/src/interface.tex	Fri Mar 03 10:57:37 2006 +0100
     1.3 @@ -1059,6 +1059,21 @@ This path contains:
     1.4        \item[domain] the name of the frontend
     1.5        \end{description}
     1.6      \end{description}
     1.7 +
     1.8 +  \item[vtpm/] a directory containin vtpm backends
     1.9 +    \begin{description}
    1.10 +    \item[$<$domid$>$/] a directory containing vtpm's for domid
    1.11 +      \begin{description}
    1.12 +      \item[$<$vtpm number$>$/] a directory for each vtpm
    1.13 +      \item[frontend-id] the domain id of the frontend
    1.14 +      \item[frontend] the path to the frontend
    1.15 +      \item[instance] the instance of the virtual TPM that is used
    1.16 +      \item[pref{\textunderscore}instance] the instance number as given in the VM configuration file;
    1.17 +           may be different from {\bf instance}
    1.18 +      \item[domain] the name of the domain of the frontend
    1.19 +      \end{description}
    1.20 +    \end{description}
    1.21 +
    1.22    \end{description}
    1.23  
    1.24    \item[device/] a directory containing the frontend devices for the
    1.25 @@ -1094,6 +1109,18 @@ This path contains:
    1.26  	  \item[event-channel] the event channel used for the two ring queues 
    1.27  	  \end{description}
    1.28  	\end{description}
    1.29 +
    1.30 +      \item[vtpm/] a directory containing the vtpm frontend device for the
    1.31 +        domain
    1.32 +        \begin{description}
    1.33 +        \item[$<$id$>$] a directory for vtpm id frontend device for the domain
    1.34 +          \begin{description}
    1.35 +	  \item[backend-id] the backend domain id
    1.36 +          \item[backend] a path to the backend's store entry
    1.37 +          \item[ring-ref] the grant table reference for the tx/rx ring
    1.38 +          \item[event-channel] the event channel used for the ring
    1.39 +          \end{description}
    1.40 +        \end{description}
    1.41  	
    1.42        \item[device-misc/] miscellanous information for devices 
    1.43  	\begin{description}
    1.44 @@ -1450,6 +1477,76 @@ The fields are as follows:
    1.45    value of {\tt first\_sect}.
    1.46  \end{description}
    1.47  
    1.48 +\section{Virtual TPM}
    1.49 +
    1.50 +Virtual TPM (VTPM) support provides TPM functionality to each virtual
    1.51 +machine that requests this functionality in its configuration file.
    1.52 +The interface enables domains to access therr own private TPM like it
    1.53 +was a hardware TPM built into the machine.
    1.54 +
    1.55 +The virtual TPM interface is implemented as a split driver,
    1.56 +similar to the network and block interfaces described above.
    1.57 +The user domain hosting the frontend exports a character device /dev/tpm0
    1.58 +to user-level applications for communicating with the virtual TPM.
    1.59 +This is the same device interface that is also offered if a hardware TPM
    1.60 +is available in the system. The backend provides a single interface
    1.61 +/dev/vtpm where the virtual TPM is waiting for commands from all domains
    1.62 +that have located their backend in a given domain.
    1.63 +
    1.64 +\subsection{Data Transfer}
    1.65 +
    1.66 +A single shared memory ring is used between the frontend and backend
    1.67 +drivers. TPM requests and responses are sent in pages where a pointer
    1.68 +to those pages and other information is placed into the ring such that
    1.69 +the backend can map the pages into its memory space using the grant
    1.70 +table mechanism.
    1.71 +
    1.72 +The backend driver has been implemented to only accept well-formed
    1.73 +TPM requests. To meet this requirement, the length inidicator in the
    1.74 +TPM request must correctly indicate the length of the request.
    1.75 +Otherwise an error message is automatically sent back by the device driver.
    1.76 +
    1.77 +The virtual TPM implementation listenes for TPM request on /dev/vtpm. Since
    1.78 +it must be able to apply the TPM request packet to the virtual TPM instance
    1.79 +associated with the virtual machine, a 4-byte virtual TPM instance
    1.80 +identifier is prepended to each packet by the backend driver (in network
    1.81 +byte order) for internal routing of the request.
    1.82 +
    1.83 +\subsection{Virtual TPM ring interface}
    1.84 +
    1.85 +The TPM protocol is a strict request/response protocol and therefore
    1.86 +only one ring is used to send requests from the frontend to the backend
    1.87 +and responses on the reverse path.
    1.88 +
    1.89 +The request/response structure is defined as follows:
    1.90 +
    1.91 +\scriptsize
    1.92 +\begin{verbatim}
    1.93 +typedef struct {
    1.94 +    unsigned long addr;     /* Machine address of packet.     */
    1.95 +    grant_ref_t ref;        /* grant table access reference.  */
    1.96 +    uint16_t unused;        /* unused                         */
    1.97 +    uint16_t size;          /* Packet size in bytes.          */
    1.98 +} tpmif_tx_request_t;
    1.99 +\end{verbatim}
   1.100 +\normalsize
   1.101 +
   1.102 +The fields are as follows:
   1.103 +
   1.104 +\begin{description}
   1.105 +\item[addr] The machine address of the page asscoiated with the TPM
   1.106 +            request/response; a request/response may span multiple
   1.107 +            pages
   1.108 +\item[ref]  The grant table reference associated with the address.
   1.109 +\item[size] The size of the remaining packet; up to
   1.110 +            PAGE{\textunderscore}SIZE bytes can be found in the
   1.111 +            page referenced by 'addr'
   1.112 +\end{description}
   1.113 +
   1.114 +The frontend initially allocates several pages whose addresses
   1.115 +are stored in the ring. Only these pages are used for exchange of
   1.116 +requests and responses.
   1.117 +
   1.118  
   1.119  \chapter{Further Information}
   1.120