Add doxygen docs to fwTPM and new public headers

Author: dgarske

docs/Doxyfile

@@ -873,6 +873,12 @@ INPUT                  = ./docs/README.md \
                          ./hal/README.md \
                          ./wolftpm/tpm2.h \
                          ./wolftpm/tpm2_wrap.h \
+                         ./wolftpm/tpm2_crypto.h \
+                         ./wolftpm/fwtpm/fwtpm.h \
+                         ./wolftpm/fwtpm/fwtpm_command.h \
+                         ./wolftpm/fwtpm/fwtpm_io.h \
+                         ./wolftpm/fwtpm/fwtpm_tis.h \
+                         ./wolftpm/fwtpm/fwtpm_nv.h \
                          ./hal/tpm_io.h
 
 # This tag can be used to specify the character encoding of the source files

wolftpm/fwtpm/fwtpm.h

@@ -564,14 +564,88 @@ typedef struct FWTPM_CTX {
 #endif
 } FWTPM_CTX;
 
-/* Public API */
+/** @defgroup wolfTPM_fwTPM wolfTPM fwTPM (Firmware TPM)
+ *
+ * Public API for the wolfTPM firmware TPM (fwTPM) software TPM 2.0
+ * implementation. fwTPM is a portable TPM server that speaks the
+ * TCG TPM 2.0 command protocol and can run alongside or in place of
+ * a hardware TPM. Transports are pluggable (sockets, TIS shared memory,
+ * SPI/UART on embedded targets) via HAL callbacks. Storage (NV) and
+ * clock are also pluggable so the same core can run on Linux and
+ * bare-metal microcontrollers.
+ */
+
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Initialize a fwTPM context. Seeds the RNG, clears TPM state,
+    and prepares the context for FWTPM_NV_Init / FWTPM_IO_Init.
+
+    \return 0 on success
+    \return TPM_RC_MEMORY if RNG initialization fails
+
+    \param ctx pointer to caller-allocated FWTPM_CTX (must be zeroed)
+
+    \sa FWTPM_Cleanup
+    \sa FWTPM_NV_SetHAL
+    \sa FWTPM_Clock_SetHAL
+*/
 WOLFTPM_API int FWTPM_Init(FWTPM_CTX* ctx);
+
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Release resources held by a fwTPM context. Zeros all
+    hierarchy seeds, session keys, and sensitive auth values before
+    freeing. Safe to call on a partially-initialized context.
+
+    \return 0 on success
+
+    \param ctx pointer to an initialized FWTPM_CTX
+
+    \sa FWTPM_Init
+*/
 WOLFTPM_API int FWTPM_Cleanup(FWTPM_CTX* ctx);
+
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Return a pointer to the compile-time fwTPM version string
+    (e.g. "0.1.0").
+
+    \return pointer to a static, null-terminated version string
+*/
 WOLFTPM_API const char* FWTPM_GetVersionString(void);
 
-/* Clock HAL API */
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Register a platform clock source for fwTPM. On embedded
+    targets this allows the TPM clock (TPM2_ReadClock / TPM2_ClockSet)
+    to advance from a hardware timer. When no HAL is registered,
+    FWTPM_Clock_GetMs returns ctx->clockOffset only.
+
+    \return 0 on success
+    \return BAD_FUNC_ARG if ctx is NULL
+
+    \param ctx pointer to an initialized FWTPM_CTX
+    \param get_ms callback returning milliseconds-since-boot; may be NULL
+        to clear a previously registered HAL
+    \param halCtx opaque context passed back to get_ms
+
+    \sa FWTPM_Clock_GetMs
+*/
 WOLFTPM_API int FWTPM_Clock_SetHAL(FWTPM_CTX* ctx,
     UINT64 (*get_ms)(void* halCtx), void* halCtx);
+
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Get the current TPM clock value in milliseconds. Returns
+    ctx->clockOffset plus (if registered) the value from the clock HAL.
+
+    \return current clock value in milliseconds
+    \return 0 if ctx is NULL
+
+    \param ctx pointer to an initialized FWTPM_CTX
+
+    \sa FWTPM_Clock_SetHAL
+*/
 WOLFTPM_API UINT64 FWTPM_Clock_GetMs(FWTPM_CTX* ctx);
 
 #ifdef __cplusplus

wolftpm/fwtpm/fwtpm_command.h

@@ -30,12 +30,28 @@
     extern "C" {
 #endif
 
-/* Process a TPM command buffer and produce a response buffer.
- * cmdBuf/cmdSize: input command (big-endian TPM packet)
- * rspBuf/rspSize: output response buffer and resulting size
- * locality: the locality from the transport layer
- * Returns TPM_RC_SUCCESS on successful processing (response may contain error RC)
- */
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Process one TPM 2.0 command. Parses the header from cmdBuf,
+    dispatches the command, and writes a wire-format response into
+    rspBuf. The return value signals transport-level success: a failure
+    at the TPM command level (e.g. TPM_RC_AUTH_FAIL) is encoded inside
+    the response and still returns TPM_RC_SUCCESS here.
+
+    \return TPM_RC_SUCCESS on successful processing (inspect response
+        header for the TPM-level return code)
+    \return negative on fatal transport/parse error
+
+    \param ctx pointer to an initialized FWTPM_CTX
+    \param cmdBuf input command buffer (big-endian TPM packet)
+    \param cmdSize size of cmdBuf in bytes
+    \param rspBuf output response buffer (caller-allocated)
+    \param rspSize in: capacity of rspBuf; out: bytes written
+    \param locality TPM locality (0-4) reported by the transport
+
+    \sa FWTPM_IO_ServerLoop
+    \sa FWTPM_TIS_ServerLoop
+*/
 WOLFTPM_API int FWTPM_ProcessCommand(FWTPM_CTX* ctx,
     const byte* cmdBuf, int cmdSize,
     byte* rspBuf, int* rspSize, int locality);

wolftpm/fwtpm/fwtpm_io.h

@@ -49,22 +49,71 @@
 /* FWTPM_IO_CTX is defined in fwtpm.h (included above) */
 
 #ifndef WOLFTPM_FWTPM_TIS
-/* Set IO HAL callbacks (optional - socket transport only) */
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Register a custom socket-transport HAL. Call before
+    FWTPM_IO_Init to replace the default POSIX socket implementation
+    (e.g. for a mocked or in-process transport).
+
+    \return 0 on success
+    \return BAD_FUNC_ARG if ctx or hal is NULL
+
+    \param ctx pointer to an initialized FWTPM_CTX
+    \param hal pointer to a caller-populated FWTPM_IO_HAL
+
+    \sa FWTPM_IO_Init
+*/
 WOLFTPM_API int FWTPM_IO_SetHAL(FWTPM_CTX* ctx, FWTPM_IO_HAL* hal);
 #endif
 
-/* Initialize transport (sockets by default, or custom HAL) */
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Initialize the fwTPM transport. When no HAL has been
+    registered, binds default TCP sockets on ctx->cmdPort and
+    ctx->platPort.
+
+    \return 0 on success
+    \return negative on socket/bind error
+
+    \param ctx pointer to an initialized FWTPM_CTX
+
+    \sa FWTPM_IO_Cleanup
+    \sa FWTPM_IO_ServerLoop
+*/
 WOLFTPM_API int FWTPM_IO_Init(FWTPM_CTX* ctx);
 
-/* Cleanup sockets */
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Release transport resources (close sockets / release HAL).
+
+    \param ctx pointer to an initialized FWTPM_CTX
+
+    \sa FWTPM_IO_Init
+*/
 WOLFTPM_API void FWTPM_IO_Cleanup(FWTPM_CTX* ctx);
 
-/* Main server loop - blocks until ctx->running is cleared or stop requested */
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Run the main fwTPM server loop. Blocks until ctx->running
+    is cleared (by FWTPM_IO_RequestStop or a signal handler).
+
+    \return 0 on clean shutdown
+    \return negative on fatal transport error
+
+    \param ctx pointer to an initialized FWTPM_CTX
+
+    \sa FWTPM_IO_RequestStop
+*/
 WOLFTPM_API int FWTPM_IO_ServerLoop(FWTPM_CTX* ctx);
 
-/* Async-signal-safe: request the server loop to exit. Safe to call from
- * a signal handler — only sets a volatile sig_atomic_t flag that the
- * main loop polls. */
+/*!
+    \ingroup wolfTPM_fwTPM
+    \brief Request the server loop to exit. Async-signal-safe: only
+    sets a volatile sig_atomic_t flag that the loop polls, so this is
+    safe to call from a signal handler.
+
+    \sa FWTPM_IO_ServerLoop
+*/
 WOLFTPM_API void FWTPM_IO_RequestStop(void);
 
 #ifdef __cplusplus