TF-PSA-Crypto version macro

[gilles-peskine-arm]

TF-PSA-Crypto should define version number macros, similar to what Mbed TLS has as MBEDTLS_VERSION_MAJOR, MBEDTLS_VERSION_MINOR, MBEDTLS_VERSION_PATCH. We should also provide strings similar to MBEDTLS_VERSION_NUMBER, MBEDTLS_VERSION_STRING, MBEDTLS_VERSION_STRING_FULL.

TBD: what header provides these macros? In Mbed TLS, the macros are defined in mbedlts/build_info.h so that they are always available, but the historical interface and the one that's still kind of intended is mbedtls/version.h. I think we should make it official that the TF-PSA-Crypto macros are exposed through #include <tf-psa-crypto/version.h>, regardless of where they are defined (presumably tf-psa-crypto/build_info.h).

(Note that this is different from PSA_CRYPTO_API_VERSION_MAJOR and PSA_CRYPTO_API_VERSION_MINOR, which indicate support for API versions.)

Related, but out of scope here: how projects can know the version of Mbed TLS or TF-PSA-Crypto, if they want crypto and support both Mbed TLS 3.6 and TF-PSA-Crypto 1.x.

Actions here:

• Define the macros.
• Document the macros and how to access them.

Follow-ups:

• Make sure that the release process includes updating the TF-PSA-Crypto version.

[davidhorstmann-arm]

This header can be populated from the version number in CMake like so:

Create tfc_version.h.in with the following (modulo exact naming of things):

#define TFPSACRYPTO_VERSION_MAJOR @TF-PSA-Crypto_VERSION_MAJOR@
#define TFPSACRYPTO_VERSION_MINOR @TF-PSA-Crypto_VERSION_MINOR@
#define TFPSACRYPTO_VERSION_PATCH @TF-PSA-Crypto_VERSION_PATCH@

#define TFPSACRYPTO_VERSION_NUMBER \
    ((TFPSACRYPTO_VERSION_MAJOR << 24) | \
    (TFPSACRYPTO_VERSION_MINOR << 16) | \
    (TFPSACRYPTO_VERSION_PATCH << 8))

#define TFPSACRYPTO_VERSION_STRING "@TF-PSA-Crypto_VERSION@"
#define TFPSACRYPTO_VERSION_STRING_FULL "TF-PSA-Crypto @TF-PSA-Crypto_VERSION@"

Then we add tfc_version.h.in to the list version_number_files in CMakeLists.txt as follows:

 set(version_number_files
+        tfc_version.h
         doxygen/input/doc_mainpage.h
         doxygen/tfpsacrypto.doxyfile)

 foreach(file ${version_number_files})
     configure_file(${file}.in
                    ${TF_PSA_CRYPTO_DIR}/${file})
 endforeach(file)

Currently we do this already with some doxygen files and it was how version.h worked it was moved back to Mbed TLS. It enables us to keep a single version number in CMakeLists.txt which simplifies the version-bumping process.

[gilles-peskine-arm]

Relying on CMake would make CMake the only possible build system. Currently, it's the only supported build system, in the sense that we won't help you if you use other build systems. But:

1. We currently use make and Visual Studio on our CI. If we want to rely on CMake, we have to either stop using make and VS on the CI (huge), or use CMake just for that part (shouldn't be hard except maybe on Windows).
2. What about users who just grab all the C files and compile them? We don't help with that, but so far we hadn't planned to make it impossible, either.

[ronald-cron-arm]

I think it makes sense to cover all version numbers and strings in CMakeLists.txt files and doxygen files with CMake variables, but less in build_info.h or tf_psa_crypto_version.h.

Currently if a user does not want to use our build systems, to get all the library files she can use a release tarball or clone the repo and run make_generated_files.py. With the header containing the version macros generated by CMake we would lose that.

For TF_PSA_CRYPTO_VERSION_xyz macros I would do exactly the same as in Mbed TLS with a tf_psa_crypto_version.h and a version.c file.