Blame - man/InitDeviceTcti.3.in - platform/external/tpm2-tss

blob: be113a9b6a0a260408c1ca348d016c17fd7ab54c [file] [log] [blame]

Philip Tricca	fe67168	2017-06-04 19:14:31 -0700	[diff] [blame]	1	.\" Process this file with
				2	.\" groff -man -Tascii foo.1
				3	.\"
				4	.TH InitDeviceTcti 3 "JUNE 2017" Intel "TPM2 Software Stack"
				5	.SH NAME
				6	InitDeviceTcti \- Initialization function for the device TCTI library.
				7	.SH SYNOPSIS
				8	.B #include <tcti/tcti_device.h>
				9	.sp
				10	.BI "typedef int (TCTI_LOG_CALLBACK)( void " "data" ", printf_type" "type" ", const char " "*format" ", "..." ");"
				11	.sp
				12	.nf
				13	typedef struct {
				14	const char *device_path;
				15	TCTI_LOG_CALLBACK logCallback;
				16	void *logData;
				17	} TCTI_DEVICE_CONF;
				18	.fi
				19	.sp
				20	.BI "TSS2_RC InitDeviceTcti (TSS2_TCTI_CONTEXT " "tctiContext" ", size_t " "contextSize" ", const TCTI_DEVICE_CONF " "*config" ");"
				21	.sp
				22	The
				23	.BR InitDeviceTcti ()
				24	function initializes a TCTI context used to communicate with the TPM device
				25	driver.
				26	.SH DESCRIPTION
				27	.BR InitDeviceTcti ()
				28	attempts to initialize a caller allocated
				29	.I tcti_context
				30	of size
				31	.I size
				32	\&. Since the
				33	.I tcti_context
				34	must be a caller allocated buffer, the caller needs to know the size required
				35	by the TCTI library. The minimum size of this context can be discovered by
				36	providing
				37	.BR NULL
				38	for the
				39	.I tcti_context
				40	and a non-
				41	.BR NULL
				42	.I size
				43	parameter. The initialization function will then populate the
				44	.I size
				45	parameter with the minimum size of the
				46	.I tcti_context
				47	buffer. The caller must then allocate a buffer of this size (or larger) and
				48	call
				49	.B InitDeviceTcti ()
				50	again providing the newly allocated
				51	.I tcti_context
				52	and the size of this context in the
				53	.I size
				54	parameter. This patterm is common to all TCTI initialization functions. We
				55	provide an example of this pattern using the
				56	.BR InitDeviceTcti ()
				57	function in the section titled
				58	.B EXAMPLE.
				59	.sp
				60	The
				61	.I config
				62	parameter is a reference to an instance of the
				63	.B TCTI_DEVICE_CONF
				64	structure. The
				65	.I device_path
				66	member of this structure is a C string that contains the path to the device
				67	node exposed by the TPM device driver.
				68	.sp
				69	The
				70	.I logCallback
				71	parameter is a pointer to a callback function that will be called by the
				72	device TCTI. This is expected to be a
				73	.I printf
				74	like function.
				75	.sp
				76	The
				77	.I logData
				78	member is a void pointer to user data that will be supplied to the
				79	.I logCallback
				80	function on each invocation.
				81	.sp
				82	Once initialized, the TCTI context returned exposes the Trusted Computing
				83	Group (TCG) defined API for the lowest level communication with the TPM.
				84	Using this API the caller can exchange (send / receive) TPM2 command and
				85	respons buffers with the TPM device driver. In nearly all cases however, the
				86	caller will initialize a context using this funnction before passing the
				87	context to a higher level API like the System API (SAPI), and then never touch
				88	it again.
				89	.sp
				90	For a more thorough discussion of the TCTI API see the \*(lqTSS System Level
				91	API and TPM Command Transmission Interface Specification\*(rq as published by
				92	the TCG:
				93	\%https://trustedcomputinggroup.org/tss-system-level-api-tpm-command-transmission-interface-specification/
				94	.SH RETURN VALUE
				95	A successful call to
				96	.BR InitDeviceTcti ()
				97	will return
				98	.B TSS2_RC_SUCCESS.
				99	An unsuccessful call will produce a response code described in section
				100	.B ERRORS.
				101	.SH ERRORS
				102	.B TSS2_TCTI_RC_BAD_VALUE
				103	is returned if both the
				104	.I tcti_context
				105	and the
				106	.I size
				107	parameters are NULL, or if the
				108	.I config
				109	parameter is NULL.
				110	.SH EXAMPLE
				111	Logging function:
				112	.sp
				113	.nf
				114	int DebugPrintfCallback( void data, printf_type type, const char format, ...)
				115	{
				116	va_list args;
				117	int rval = 0;
				118
				119	va_start( args, format );
				120	rval = vprintf( format, args );
				121	va_end (args);
				122
				123	return rval;
				124	}
				125	.fi
				126	.sp
				127	TCTI initialization fragment:
				128	.sp
				129	.nf
				130	#include <inttypes.h>
				131	#include <stdlib.h>
				132	#include <stdio.h>
				133	#include <tcti/tcti_device.h>
				134
				135	TSS2_RC rc;
				136	TSS2_TCTI_CONTEXT *tcti_context;
				137	size_t size;
				138	TCTI_DEVICE_CONF conf = {
				139	.device_path = "/dev/tpm0",
				140	.logCallback = DebugPrintfCallback,
				141	.logData = NULL,
				142	};
				143
				144	rc = InitDeviceTcti (NULL, &size, NULL);
				145	if (rc != TSS2_RC_SUCCESS) {
Doug Goldstein	71b2473	2017-08-02 18:00:41 -0500	[diff] [blame^]	146	fprintf (stderr, "Failed to get allocation size for device TCTI "
Philip Tricca	fe67168	2017-06-04 19:14:31 -0700	[diff] [blame]	147	" context: 0x%" PRIx32 "\n", rc);
				148	exit (EXIT_FAILURE);
				149	}
				150	tcti_context = calloc (1, size);
				151	if (tcti_context == NULL) {
				152	fprintf (stderr, "Allocation for TCTI context failed: %s\n",
				153	strerror (errno));
				154	exit (EXIT_FAILURE);
				155	}
				156	rc = InitDeviceTcti (&tcti_context, &size, &conf);
				157	if (rc != TSS2_RC_SUCCESS) {
Doug Goldstein	71b2473	2017-08-02 18:00:41 -0500	[diff] [blame^]	158	fprintf (stderr, "Failed to initialize device TCTI context: "
Philip Tricca	fe67168	2017-06-04 19:14:31 -0700	[diff] [blame]	159	"0x%" PRIx32 "\n", rc);
				160	free (tcti_context);
				161	exit (EXIT_FAILURE);
				162	}
				163	exit (EXIT_SUCCESS);
				164	.fi