man/InitDeviceTcti.3.in

.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH InitDeviceTcti 3 "JUNE 2017" Intel "TPM2 Software Stack"
.SH NAME
InitDeviceTcti \- Initialization function for the device TCTI library.
.SH SYNOPSIS
.B #include <tcti/tcti_device.h>
.sp
.BI "typedef int (*TCTI_LOG_CALLBACK)( void " "*data" ", printf_type" "type" ", const char " "*format" ", "..." ");"
.sp
.nf
typedef struct {
    const char *device_path;
    TCTI_LOG_CALLBACK logCallback;
    void *logData;
} TCTI_DEVICE_CONF;
.fi
.sp
.BI "TSS2_RC InitDeviceTcti (TSS2_TCTI_CONTEXT " "*tctiContext" ", size_t " "*contextSize" ", const TCTI_DEVICE_CONF " "*config" ");"
.sp
The
.BR  InitDeviceTcti ()
function initializes a TCTI context used to communicate with the TPM device
driver.
.SH DESCRIPTION
.BR InitDeviceTcti ()
attempts to initialize a caller allocated
.I tcti_context
of size
.I size
\&. Since the
.I tcti_context
must be a caller allocated buffer, the caller needs to know the size required
by the TCTI library. The minimum size of this context can be discovered by
providing
.BR NULL
for the
.I tcti_context
and a non-
.BR NULL
.I size
parameter. The initialization function will then populate the
.I size
parameter with the minimum size of the
.I tcti_context
buffer. The caller must then allocate a buffer of this size (or larger) and
call
.B InitDeviceTcti ()
again providing the newly allocated
.I tcti_context
and the size of this context in the
.I size
parameter. This patterm is common to all TCTI initialization functions. We
provide an example of this pattern using the
.BR InitDeviceTcti ()
function in the section titled
.B EXAMPLE.
.sp
The
.I config
parameter is a reference to an instance of the
.B TCTI_DEVICE_CONF
structure. The
.I device_path
member of this structure is a C string that contains the path to the device
node exposed by the TPM device driver.
.sp
The
.I logCallback
parameter is a pointer to a callback function that will be called by the
device TCTI. This is expected to be a
.I printf
like function.
.sp
The
.I logData
member is a void pointer to user data that will be supplied to the
.I logCallback
function on each invocation.
.sp
Once initialized, the TCTI context returned exposes the Trusted Computing
Group (TCG) defined API for the lowest level communication with the TPM.
Using this API the caller can exchange (send / receive) TPM2 command and
respons buffers with the TPM device driver. In nearly all cases however, the
caller will initialize a context using this funnction before passing the
context to a higher level API like the System API (SAPI), and then never touch
it again.
.sp
For a more thorough discussion of the TCTI API see the \*(lqTSS System Level
API and TPM Command Transmission Interface Specification\*(rq as published by
the TCG:
\%https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/
.SH RETURN VALUE
A successful call to
.BR InitDeviceTcti ()
will return
.B TSS2_RC_SUCCESS.
An unsuccessful call will produce a response code described in section
.B ERRORS.
.SH ERRORS
.B TSS2_TCTI_RC_BAD_VALUE
is returned if both the
.I tcti_context
and the
.I size
parameters are NULL, or if the
.I config
parameter is NULL.
.SH EXAMPLE
Logging function:
.sp
.nf
int DebugPrintfCallback( void *data, printf_type type, const char *format, ...)
{
    va_list args;
    int rval = 0;

    va_start( args, format );
    rval = vprintf( format, args );
    va_end (args);

    return rval;
}
.fi
.sp
TCTI initialization fragment:
.sp
.nf
#include <inttypes.h>
#include <stdlib.h>
#include <stdio.h>
#include <tcti/tcti_device.h>

TSS2_RC rc;
TSS2_TCTI_CONTEXT *tcti_context;
size_t size;
TCTI_DEVICE_CONF conf = {
    .device_path = "/dev/tpm0",
    .logCallback = DebugPrintfCallback,
    .logData     = NULL,
};

rc = InitDeviceTcti (NULL, &size, NULL);
if (rc != TSS2_RC_SUCCESS) {
    fprintf (stderr, "Failed to get allocation size for tabrmd TCTI "
             " context: 0x%" PRIx32 "\n", rc);
    exit (EXIT_FAILURE);
}
tcti_context = calloc (1, size);
if (tcti_context == NULL) {
    fprintf (stderr, "Allocation for TCTI context failed: %s\n",
             strerror (errno));
    exit (EXIT_FAILURE);
}
rc = InitDeviceTcti (&tcti_context, &size, &conf);
if (rc != TSS2_RC_SUCCESS) {
    fprintf (stderr, "Failed to initialize tabrmd TCTI context: "
             "0x%" PRIx32 "\n", rc);
    free (tcti_context);
    exit (EXIT_FAILURE);
}
exit (EXIT_SUCCESS);
.fi