[go: nahoru, domu]
Google Git
Sign in
android / platform / external / tpm2-tss / refs/tags/aml_uwb_331410010 / . / man / Tss2_Tcti_Device_Init.3.in
blob: d08bcfa4a185f08fb545711d5f9856734efea6f4 [file] [log] [blame]
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]1.\" Process this file with
2.\" groff -man -Tascii foo.1
3.\"
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]4.TH Tss2_Tcti_Device_Init 3 "MARCH 2018" Intel "TPM2 Software Stack"
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]5.SH NAME
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]6Tss2_Tcti_Device_init \- Initialization function for the device TCTI library.
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]7.SH SYNOPSIS
8.B #include <tcti/tcti_device.h>
9.sp
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]10.sp
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]11.BI "TSS2_RC Tss2_Tcti_Device_Init (TSS2_TCTI_CONTEXT " "*tctiContext" ", size_t " "*size" ", const char " "*conf" ");"
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]12.sp
13The
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]14.BR Tss2_Tcti_Device_Init ()
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]15function initializes a TCTI context used to communicate with the TPM device
16driver.
17.SH DESCRIPTION
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]18.BR Tss2_Tcti_Device_Init ()
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]19attempts to initialize a caller allocated
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]20.I tctiContext
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]21of size
22.I size
23\&. Since the
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]24.I tctiContext
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]25must be a caller allocated buffer, the caller needs to know the size required
26by the TCTI library. The minimum size of this context can be discovered by
27providing
28.BR NULL
29for the
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]30.I tctiContext
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]31and a non-
32.BR NULL
33.I size
34parameter. The initialization function will then populate the
35.I size
36parameter with the minimum size of the
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]37.I tctiContext
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]38buffer. The caller must then allocate a buffer of this size (or larger) and
39call
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]40.B Tss2_Tcti_Device_Init ()
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]41again providing the newly allocated
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]42.I tctiContext
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]43and the size of this context in the
44.I size
dantpm1edd1112018-04-06 15:26:05 -0700[diff] [blame]45parameter. This pattern is common to all TCTI initialization functions. We
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]46provide an example of this pattern using the
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]47.BR Tss2_Tcti_Device_Init ()
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]48function in the section titled
49.B EXAMPLE.
50.sp
51The
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]52.I conf
53parameter is a C string. If this string is
54.BR NULL
55then the library will use a default configuration string for the caller.
56Alternatively, the caller may provide a configuration string that must
57contain the path to the device node exposed by the TPM device driver.
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]58.sp
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]59Once initialized, the TCTI context returned exposes the Trusted Computing
60Group (TCG) defined API for the lowest level communication with the TPM.
61Using this API the caller can exchange (send / receive) TPM2 command and
dantpm1edd1112018-04-06 15:26:05 -0700[diff] [blame]62response buffers with the TPM device driver. In nearly all cases however, the
63caller will initialize a context using this function before passing the
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]64context to a higher level API like the System API (SAPI), and then never touch
65it again.
66.sp
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]67TCG TSS 2.0 TPM Command
68Transmission Interface (TCTI) API
69Specification
70
71For a more thorough discussion of the TCTI API see the \*(lqTCG TSS 2.0 TPM Command
72Transmission Interface (TCTI) API Specification\*(rq as published by
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]73the TCG:
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]74\%https://trustedcomputinggroup.org/wp-content/uploads/TSS_TCTI_Version-1.0_Revision-05_Review_END030918.pdf
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]75.SH RETURN VALUE
76A successful call to
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]77.BR Tss2_Tcti_Device_Init ()
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]78will return
79.B TSS2_RC_SUCCESS.
80An unsuccessful call will produce a response code described in section
81.B ERRORS.
82.SH ERRORS
83.B TSS2_TCTI_RC_BAD_VALUE
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]84is returned if any parameters contain unexpected values.
85.B TSS2_TCTI_RC_BAD_REFERENCE
86is returned if any parameters are NULL when they should not be.
87.B TSS2_TCTI_RC_BAD_CONTEXT
88is returned if the size of the provided
89.i tctiContext
90is insufficient.
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]91.SH EXAMPLE
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]92TCTI initialization fragment:
93.sp
94.nf
95#include <inttypes.h>
96#include <stdlib.h>
97#include <stdio.h>
98#include <tcti/tcti_device.h>
99
100TSS2_RC rc;
101TSS2_TCTI_CONTEXT *tcti_context;
102size_t size;
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]103char *conf = "/dev/tpm0",
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]104
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]105rc = Tss2_Tcti_Device_Init (NULL, &size, NULL);
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]106if (rc != TSS2_RC_SUCCESS) {
Doug Goldstein71b24732017-08-02 18:00:41 -0500[diff] [blame]107 fprintf (stderr, "Failed to get allocation size for device TCTI "
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]108 " context: 0x%" PRIx32 "\n", rc);
109 exit (EXIT_FAILURE);
110}
111tcti_context = calloc (1, size);
112if (tcti_context == NULL) {
113 fprintf (stderr, "Allocation for TCTI context failed: %s\n",
114 strerror (errno));
115 exit (EXIT_FAILURE);
116}
Philip Tricca5a235282018-02-27 14:59:49 -0800[diff] [blame]117rc = Tss2_Tcti_Device_Init (&tcti_context, &size, &conf);
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]118if (rc != TSS2_RC_SUCCESS) {
Doug Goldstein71b24732017-08-02 18:00:41 -0500[diff] [blame]119 fprintf (stderr, "Failed to initialize device TCTI context: "
Philip Triccafe671682017-06-04 19:14:31 -0700[diff] [blame]120 "0x%" PRIx32 "\n", rc);
121 free (tcti_context);
122 exit (EXIT_FAILURE);
123}
124exit (EXIT_SUCCESS);
125.fi