tf-psa-crypto: cmake: Add build of documentation

Signed-off-by: Ronald Cron <ronald.cron@arm.com>

tf-psa-crypto/CMakeLists.txt

@@ -57,15 +57,18 @@ endif()
 
 else(NOT (CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR))
 
+set(TF_PSA_CRYPTO_VERSION 0.1.0)
+set(TF_PSA_CRYPTO_SOVERSION 0)
+
 if(TEST_CPP)
     project("TF-PSA-Crypto"
         LANGUAGES C CXX
-        VERSION 0.1.0
+        VERSION ${TF_PSA_CRYPTO_VERSION}
     )
 else()
     project("TF-PSA-Crypto"
         LANGUAGES C
-        VERSION 0.1.0
+        VERSION ${TF_PSA_CRYPTO_VERSION}
     )
 endif()
 

tf-psa-crypto/TF-PSA-Crypto.cmake

@@ -13,6 +13,19 @@ set(TF_PSA_CRYPTO_DIR ${CMAKE_CURRENT_SOURCE_DIR})
 set(MBEDTLS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/..)
 set(MBEDTLS_FRAMEWORK_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../framework)
 
+# Put the version numbers into relevant files
+set(version_number_files
+        doxygen/input/doc_mainpage.h
+        doxygen/tfpsacrypto.doxyfile)
+foreach(file ${version_number_files})
+    configure_file(${file}.in
+                   ${TF_PSA_CRYPTO_DIR}/${file})
+endforeach(file)
+
+ADD_CUSTOM_TARGET(${TF_PSA_CRYPTO_TARGET_PREFIX}apidoc
+    COMMAND doxygen tfpsacrypto.doxyfile
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/doxygen)
+
 option(ENABLE_PROGRAMS "Build TF-PSA-Crypto programs." ON)
 
 option(UNSAFE_BUILD "Allow unsafe builds. These builds ARE NOT SECURE." OFF)

tf-psa-crypto/doxygen/.gitignore

@@ -0,0 +1 @@
+tfpsacrypto.doxyfile

tf-psa-crypto/doxygen/input/.gitignore

@@ -0,0 +1 @@
+doc_mainpage.h

tf-psa-crypto/doxygen/input/doc_mainpage.h.in

@@ -0,0 +1,19 @@
+/**
+ * \file doc_mainpage.h
+ *
+ * \brief Main page documentation file.
+ */
+/*
+ *
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
+ */
+
+/**
+ * @mainpage TF-PSA-Crypto v@TF-PSA-Crypto_VERSION@ source code documentation
+ *
+ * This documentation describes the internal structure of the TF-PSA-Crypto
+ * library. It was automatically generated from specially formatted comment
+ * blocks in TF-PSA-Crypto source code using Doxygen (see
+ * http://www.stack.nl/~dimitri/doxygen/ for more information on Doxygen).
+ */

tf-psa-crypto/doxygen/tfpsacrypto.doxyfile.in

@@ -0,0 +1,54 @@
+PROJECT_NAME           = "TF-PSA-Crypto v@TF-PSA-Crypto_VERSION@"
+OUTPUT_DIRECTORY       = ../apidoc/
+FULL_PATH_NAMES        = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+CASE_SENSE_NAMES       = NO
+INPUT                  = ../include input
+FILE_PATTERNS          = *.h
+EXCLUDE                = ../include/psa/crypto_se_driver.h
+RECURSIVE              = YES
+EXCLUDE_SYMLINKS       = YES
+SOURCE_BROWSER         = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+ALPHABETICAL_INDEX     = NO
+HTML_OUTPUT            = .
+HTML_TIMESTAMP         = YES
+SEARCHENGINE           = YES
+GENERATE_LATEX         = NO
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+INCLUDE_PATH           = ../include
+EXPAND_AS_DEFINED      = MBEDTLS_PRIVATE
+CLASS_DIAGRAMS         = NO
+HAVE_DOT               = YES
+DOT_GRAPH_MAX_NODES    = 200
+MAX_DOT_GRAPH_DEPTH    = 1000
+DOT_TRANSPARENT        = YES
+
+# We mostly use \retval declarations to document which error codes a function
+# can return. The reader can follow the hyperlink to the definition of the
+# constant to get the generic documentation of that error code. If we don't
+# have anything to say about the specific error code for the specific
+# function, we can leave the description part of the \retval command blank.
+# This is perfectly valid as far as Doxygen is concerned. However, with
+# Clang >=15, the -Wdocumentation option emits a warning for empty
+# descriptions.
+#   https://github.com/Mbed-TLS/mbedtls/issues/6960
+#   https://github.com/llvm/llvm-project/issues/60315
+# As a workaround, you can write something like
+#     \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
+# This avoids writing redundant text and keeps Clang happy.
+ALIASES += emptydescription=""
+
+# Define away macros that make parsing definitions difficult.
+# MBEDTLS_DEPRECATED is not included in this list as it's important to
+# display deprecated status in the documentation.
+PREDEFINED             = "MBEDTLS_CHECK_RETURN_CRITICAL="   \
+                         "MBEDTLS_CHECK_RETURN_TYPICAL="    \
+                         "MBEDTLS_CHECK_RETURN_OPTIONAL="   \
+                         "MBEDTLS_PRINTF_ATTRIBUTE(a,b)="   \
+                         "__DOXYGEN__"                      \