| .\" Process this file with |
| .\" groff -man -Tascii foo.1 |
| .\" |
| .TH Tss2_TctiLdr_Initialize 3 "MARCH 2019" "TPM2 Software Stack" |
| .SH NAME |
| Tss2_TctiLdr_Initialize, Tss2_TctiLdr_Initialize_Ex \- Instantiate and |
| initialize a TCTI context. |
| .SH SYNOPSIS |
| .B #include <tss2/tss2_tctildr.h> |
| .sp |
| .sp |
| .BI "TSS2_RC Tss2_TctiLdr_Initialize (const char " "*nameConf" ", TSS2_TCTI_CONTEXT " "**context" ");" |
| .sp |
| .BI "TSS2_RC Tss2_TctiLdr_Initialize_Ex (const char " "*name" ", const char " "*conf" ", TSS2_TCTI_CONTEXT " "**context" ");" |
| .sp |
| .SH DESCRIPTION |
| The |
| .BR Tss2_TctiLdr_Initialize () |
| and |
| .BR Tss2_TctiLdr_Initialize_Ex () |
| functions initialize a TCTI context used to communicate with the TPM2 or |
| some intermediate component in the TCG TPM2 software stack. |
| .sp |
| .BR Tss2_TctiLdr_Initialize () |
| takes a single string that encodes both the name of the TCTI library the |
| caller wishes to instantiate and its desired configuration in the |
| .I nameConf |
| parameter. |
| .I nameConf |
| is a string comprised of two substrings: |
| .I name |
| and |
| .I conf |
| parameters respectively. |
| These substrings are combined with |
| .I name |
| first, separated by a single ':' / colon character: 'name:conf'. Consult |
| the section titled TCTI CONFIG for information about the encoding of these |
| strings. |
| The |
| .I context |
| parameter is used to return a reference to the TCTI context created by |
| the function. |
| .sp |
| .BR Tss2_TctiLdr_Initialize_Ex () |
| behaves identically to the |
| .BR Tss2_TctiLdr_Initialize () |
| function with the exception that the TCTI name and configuration are passed |
| as separate strings. The encoding of these strings is described in section |
| TCTI_CONFIG. |
| .SH TCTI CONFIG |
| If the |
| .I name |
| string is NULL or the emptry string then the initialization functions will |
| select a default TCTI appropriate for the platform. On Linux this means |
| first trying to load a library named |
| .I libtss2-tcti-default.so. |
| This is a placeholder for distros to provide a distro specific default. It |
| is recommended that this be a symlink to another installed TCTI library. |
| If attempts to load this shared object fails the implementation will |
| attempt known TCTIs in the following order: |
| .IP \[bu] 2 |
| libtss2-tcti-tabrmd.so.0 |
| .IP \[bu] |
| libtss2-tcti-device.so.0 |
| .IP \[bu] |
| libtss2-tcti-mssim.so.0 |
| .LP |
| When the |
| .I name |
| string is neither NULL nor the empty string the implementation will attempt |
| to |
| .I dlopen |
| a library with the given name. If this fails then the implementation assumes |
| it has been passed a shortened name and will attempt to load libraries by |
| name with the following permutations: |
| .IP \[bu] 2 |
| <name> |
| .IP \[bu] |
| libtss2-tcti-<name>.so.0 |
| .IP \[bu] |
| libtss2-tcti-<name>.so |
| .LP |
| The |
| .I config |
| string is not interpreted by the TctiLdr init functions and is passed |
| unaltered to the initialization function for the selected TCTI. The |
| format for this string is TCTI specific. |
| .sp |
| The |
| .BR Tss2_TctiLdr_Initialize |
| function is passed the |
| .I name |
| and |
| .I conf |
| strings as a single parameter. In this case the |
| .I name |
| and |
| .I conf |
| strings are concatinated with a single ':' / colon character separating them. |
| .sp |
| For a more thorough discussion of the TCTILDR API see the \*(lqTCG TSS 2.0 TPM Command |
| Transmission Interface (TCTI) API Specification\*(rq. |
| .SH RETURN VALUE |
| A successful call to this function 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_MEMORY |
| is returned if memory allocation fails |
| .sp |
| .B TSS2_TCTI_RC_NOT_SUPPORTED |
| is returned when the loader is unable to locate a TCTI library with the |
| provided |
| .I name |
| .sp |
| .B TSS2_TCTI_RC_IO_ERROR |
| is returned if a failure occurs in the underlying library loading mechanism |
| .sp |
| .B TSS2_TCTI_RC_BAD_REFERENCE |
| is returned if the |
| .I tctiContext |
| parameter is NULL |
| .sp |
| .SH EXAMPLE |
| Example code. |
| .sp |
| .nf |
| #include <inttypes.h> |
| #include <stdlib.h> |
| #include <stdio.h> |
| #include <tss2/tss2_tctildr.h> |
| |
| TSS2_TCTI_CONTEXT *ctx = NULL; |
| TSS2_RC rc = Tss2_TctiLdr_Initialize (NULL, &ctx); |
| if (rc != TSS2_RC_SUCCESS) { |
| fprintf (stderr, "Initialization of default TCTI context failed with " |
| "response code: 0x%" PRIx32 "\n", rc); |
| exit (EXIT_FAILURE); |
| } |
| exit (EXIT_SUCCESS); |
| .fi |