doc: Add manpage for the device TCTI initialization function.
This gives some brief documentation of the function but most importantly
it has an EXAMPLES section with code fragments to demonstrate the use of
the function.
Signed-off-by: Philip Tricca <philip.b.tricca@intel.com>
diff --git a/Makefile.am b/Makefile.am
index f372cba..721a8ab 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -54,6 +54,7 @@
TESTS = $(check_PROGRAMS)
CLEANFILES = \
$(nodist_pkgconfig_DATA) \
+ $(man3_MANS) \
$(man7_MANS)
# headers and where to install them
@@ -65,9 +66,13 @@
pkgconfigdir = $(libdir)/pkgconfig
nodist_pkgconfig_DATA = lib/sapi.pc lib/tcti-device.pc lib/tcti-socket.pc
# man pages / documentation
+man3_MANS = man/man3/InitDeviceTcti.3
man7_MANS = man/man7/tcti-device.7 man/man7/tcti-socket.7
-EXTRA_DIST = man/tcti-device.7.in man/tcti-socket.7.in
+EXTRA_DIST = \
+ man/InitDeviceTcti.3.in \
+ man/tcti-device.7.in \
+ man/tcti-socket.7.in
if UNIT
test_tcti_device_CFLAGS = $(CMOCKA_CFLAGS) -I$(srcdir)/include -I$(srcdir)/sysapi/include
@@ -186,10 +191,11 @@
sed -e "s,[@]VERSION[@],$(PACKAGE_VERSION),g; \
s,[@]includedir[@],$(includedir),g;" $^ > $@
+man/man3/%.3 : man/%.3.in $(srcdir)/man/man-postlude.troff
+ $(call make_man,$@,$<,$(srcdir)/man/man-postlude.troff)
+
man/man7/%.7 : man/%.7.in $(srcdir)/man/man-postlude.troff
- $(call make_parent_dir,$@)
- cat $^ $(srcdir)/man/man-postlude.troff > $@
- sed -i -e "s,[@]VERSION[@],$(PACKAGE_VERSION),g;" $@
+ $(call make_man,$@,$<,$(srcdir)/man/man-postlude.troff)
LIBRARY_LDFLAGS = -fPIC -Wl,--no-undefined
@@ -240,3 +246,12 @@
define make_parent_dir
if [ ! -d $(dir $1) ]; then mkdir -p $(dir $1); fi
endef
+# function to transform man .in files to man pages
+# $1: target
+# $2: .in file
+# $3: man postlude file
+define make_man
+ $(call make_parent_dir,$1)
+ cat $2 $3 > $1
+ sed -i -e "s,[@]VERSION[@],$(PACKAGE_VERSION),g;" $1
+endef
diff --git a/man/InitDeviceTcti.3.in b/man/InitDeviceTcti.3.in
new file mode 100644
index 0000000..6474b2f
--- /dev/null
+++ b/man/InitDeviceTcti.3.in
@@ -0,0 +1,164 @@
+.\" 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
diff --git a/man/man-postlude.troff b/man/man-postlude.troff
index 07589a6..c1076cf 100644
--- a/man/man-postlude.troff
+++ b/man/man-postlude.troff
@@ -1,6 +1,7 @@
.SH AUTHOR
Philip Tricca <philip.b.tricca@intel.com>
.SH "SEE ALSO"
+.BR InitDeviceTcti (3),
.BR tcti-device (7),
.BR tcti-socket (7),
.BR tcti-tabrmd (7),