.nr HAVE_DEVICE_TCTI 1
.nr HAVE_SOCKET_TCTI 1
.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH TSS2_TCTI_TABRMD_INIT 3 "MAY 2017" Intel "TPM2 Software Stack"
.SH NAME
tss2_tcti_tabrmd_init, tss2_tcti_tabrmd_init_full \- Initialization functions
for the tpm2-abrmd TCTI library.
.SH SYNOPSIS
The
.BR tss2_tcti_tabrmd_init ()
and
.BR tss2_tcti_tabrmd_init_full ()
functions are used to initialize a TCTI context for communication with the
.BR tpm2-abrmd (8).
.sp
.B #include <tcti/tcti-tabrmd.h>
.sp
.BI "TSS2_RC tss2_tcti_tabrmd_init (TSS2_TCTI_CONTEXT " "*tcti_context" ", size_t " "*size" );
.sp
.BI "TSS2_RC tss2_tcti_tabrmd_init_full (TSS2_TCTI_CONTEXT " "*tcti_context" ", size_t " "*size" ", GBusType" "bus_type" ", const char" "*bus_name" );
.sp
.SH DESCRIPTION
.BR tss2_tcti_tabrmd_init ()
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 my then allocate a buffer of this size (or larger) and
call
.B tss2_tcti_tabrmd_init ()
again providing the newly allocated
.I tcti_context
and the size of this context in the
.I size
parameter.
.sp
This patterm is common to all TCTI initialization functions. We provide an
example of this pattern using the
.BR tss2_tcti_tabrmd_init ()
function in the section titled
.B EXAMPLE.
.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
.B tpm2-abrmd (8).
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 specification
as published by the TCG:
\%https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/
.sp
.B tss2_tcti_tabrmd_init_full ()
behaves in the same way as
.B tss2_tcti_tabrmd_init ()
but allows for greater flexibility through two additional parameters: The
.I bus_type
and
.I bus_name
parameters may be used to select which D-Bus bus type and name used to connect
to an instance of the
.B tpm2-abrmd (8)
daemon.

.SH RETURN VALUE
A successful call to
.BR tss2_tcti_tabrmd_init ()
and
.BR tss2_tcti_tabrmd_init_full ()
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 the
.I bus_name
is NULL, or the
.I bus_type
is not a supported type (G_BUS_TYPE_SYSTEM OR G_BUS_TYPE_SESSION).
.sp
All errors caused by communication failures with the
.B tpm2-abrmd (8)
are treated as fatal errors and will call the calling application to terminate.

.SH EXAMPLE
.nf
#include <inttypes.h>
#include <stdlib.h>
#include <stdio.h>
#include <tcti/tcti-tabrmd.h>

TSS2_RC rc;
TSS2_TCTI_CONTEXT *tcti_context;
size_t size;

rc = tss2_tcti_tabrmd_init (NULL, &size);
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 = tss2_tcti_tabrmd_init (tcti_context, &size);
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
.SH AUTHOR
Philip Tricca <philip.b.tricca@intel.com>
.SH "SEE ALSO"
.BR tcti-tabrmd (7),
.BR tpm2-abrmd (8)
.SH COLOPHON
This page is part of the 1.3.1 release of Intel's TPM2 Access Broker &
Resource Management Daemon. A description of the project, information about
reporting bugs, and the latest version of this page can be found at
\%https://github.com/01org/tpm2\-abrmd/.