doc: Add a manpage for the TctiSocketInit 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 721a8ab..18b5c6c 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -66,7 +66,7 @@
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
+man3_MANS = man/man3/InitDeviceTcti.3 man/man3/InitSocketTcti.3
man7_MANS = man/man7/tcti-device.7 man/man7/tcti-socket.7
EXTRA_DIST = \
diff --git a/man/InitSocketTcti.3.in b/man/InitSocketTcti.3.in
new file mode 100644
index 0000000..9176e8a
--- /dev/null
+++ b/man/InitSocketTcti.3.in
@@ -0,0 +1,198 @@
+.\" Process this file with
+.\" groff -man -Tascii foo.1
+.\"
+.TH InitSocketTcti 3 "JUNE 2017" Intel "TPM2 Software Stack"
+.SH NAME
+InitSocketTcti \- Initialization function for the Microsoft TPM simulator TCTI library.
+.SH SYNOPSIS
+.B #include <tcti/tcti_socket.h>
+.sp
+.BI "typedef int (*TCTI_LOG_CALLBACK)( void " "*data" ", printf_type" "type" ", const char " "*format" ", "..." ");"
+.sp
+.nf
+typedef struct {
+ const char *hostname;
+ uint16_t port;
+ TCTI_LOG_CALLBACK logCallback;
+ TCTI_LOG_BUFFER_CALLBACK logBufferCallback;
+ void *logData;
+} TCTI_SOCKET_CONF;
+.fi
+.sp
+.BI "TSS2_RC InitSocketTcti (TSS2_TCTI_CONTEXT " "*tctiContext" ", size_t " "*contextSize" ", const TCTI_SOCKET_CONF " "*config" ", const uint8_t " "serverSockets" ");"
+
+.sp
+The
+.BR InitSocketTcti ()
+function initializes a TCTI context used to communicate with the Microsoft TPM
+simulator.
+.SH DESCRIPTION
+.BR InitSocketTcti ()
+attempts to initialize a caller allocated
+.I tcti_context
+of size
+.I size
+using caller provided configuration information from
+.I config
+\&. 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 InitSocketTcti ()
+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 InitSocketTcti ()
+function in the section titled
+.B EXAMPLE.
+.sp
+The
+.I config
+parameter is a reference to an instance of the
+.B TCTI_SOCKET_CONF
+structure. The
+.I hostname
+member of this structure is a C string that contains the hostname or IPv4
+address of the Microsoft TPM simulator. The
+.I port
+member is an unsigned 16 bit integer containing the port number for the
+simulator command / response port. The simulator listens for \*(lqplatform
+commands\*(rq on
+.I port+1
+and so an additional connection will be made to this port. The
+.I logCallback
+member is a pointer to a callback function that will be called by the
+socket TCTI. This is expected to be a
+.I printf
+like function. The
+.I logBufferCallback
+mamber is a pointer to a call back function that will be invoked by the
+socket TCTI before a command buffer is transmitted or after a resposne buffer
+is received. This is expected to be a
+.I printf
+like function. The
+.I logData
+member is a void pointer that may be used to pass user data to the
+.I logCallback
+and
+.I logBufferCallback
+functions on each invocation.
+.sp
+The
+.I serverSockets
+parameter should always be 0 for client code.
+.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 Microsoft TPM simulator. 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 InitSocketTcti ()
+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 functions:
+.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;
+}
+void DebugPrintBuffer (printf_type type, UINT8 *buffer, UINT32 length)
+{
+ UINT32 i;
+
+ for( i = 0; i < length; i++ )
+ {
+ if( ( i % 16 ) == 0 ) {
+ printf ("\n");
+ }
+
+ printf ("%2.2x ", buffer[i] );
+ }
+ printf ("\n\n");
+}
+.fi
+.sp
+TCTI initialization fragment:
+.sp
+.nf
+#include <inttypes.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <tcti/tcti_socket.h>
+
+TSS2_RC rc;
+TSS2_TCTI_CONTEXT *tcti_context;
+size_t size;
+TCTI_SOCKET_CONF conf = {
+ .hostname = "127.0.0.1",
+ .port = 2321,
+ .logCallback = DebugPrintfCallback,
+ .logBufferCallback = DebugPrintBuffer,
+ .logData = NULL,
+};
+
+rc = InitSocketTcti (NULL, &size, NULL, 0);
+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 = InitSocketTcti (&tcti_context, &size, &conf, 0);
+if (rc != TSS2_RC_SUCCESS) {
+ fprintf (stderr, "Failed to initialize tabrmd TCTI context: "
+ "0x%" PRIx32 "\n", rc);
+ free (tcti_context);
+ exit (EXIT_FAILURE);
+}
+.fi
diff --git a/man/man-postlude.troff b/man/man-postlude.troff
index c1076cf..9176dae 100644
--- a/man/man-postlude.troff
+++ b/man/man-postlude.troff
@@ -2,6 +2,7 @@
Philip Tricca <philip.b.tricca@intel.com>
.SH "SEE ALSO"
.BR InitDeviceTcti (3),
+.BR InitSocketTcti (3),
.BR tcti-device (7),
.BR tcti-socket (7),
.BR tcti-tabrmd (7),