refactor(trng): cleanup the existing TRNG support

This patch adds the following changes to complete the existing
TRNG implementation:

1. Adds a feature specific scope for buildlog generation.
2. Updates the docs on the build flag "TRNG_SUPPORT" and its values.
3. Makefile update and improves the existing comments at few sections
for better understanding of the underlying logic.

Change-Id: I3f72f0ccd5c94005a2df87158cf23199d2160d37
Signed-off-by: Jayanth Dodderi Chidanand <jayanthdodderi.chidanand@arm.com>

diff --git a/Makefile b/Makefile
index a14d4d88c2c06c189352bf25126e2679ff534dce..6d836e8f6a236b1a0f5bb57525a778d8b6c419be 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -1079,6 +1079,7 @@ $(eval $(call assert_booleans,\
         ENABLE_MPMM_FCONF \
         SIMICS_BUILD \
         FEATURE_DETECTION \
+       TRNG_SUPPORT \
 )))
 
 $(eval $(call assert_numerics,\

diff --git a/changelog.yaml b/changelog.yaml
index 8fcb21785988ff8a89b78a0a3faf0db86635d4ee..83be61816629da300ab4224fbc7be98bceac0c4c 100644 (file)
--- a/changelog.yaml
+++ b/changelog.yaml
@@ -595,6 +595,9 @@ subsections:
       - title: DRTM
         scope: drtm
 
+      - title: TRNG
+        scope: trng
+
   - title: Libraries
 
     subsections:

diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index 59800506e582d569d3dcdd81ea7ae5cfacec445b..68ef4cefd16395b920a88852dbca7faaf85f80ab 100644 (file)
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -851,6 +851,9 @@ Common build options
    hardware will limit the effective VL to the maximum physically supported
    VL.
 
+-  ``TRNG_SUPPORT``: Setting this to ``1`` enables support for True
+   Random Number Generator Interface to BL31 image. This defaults to ``0``.
+
 -  ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board
    Boot feature. When set to '1', BL1 and BL2 images include support to load
    and verify the certificates and images in a FIP, and BL1 includes support

diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 6996c17dbacf18992d10d19fdf7ba58b04de7946..668af57142a01e4caa9fb46c5fd91468e3fba8f9 100644 (file)
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -2468,7 +2468,7 @@ value: uuid_t plat_trng_uuid [mandatory]
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This value must be defined to the UUID of the TRNG backend that is specific to
-the hardware after ``plat_trng_setup`` function is called. This value must
+the hardware after ``plat_entropy_setup`` function is called. This value must
 conform to the SMCCC calling convention; The most significant 32 bits of the
 UUID must not equal ``0xffffffff`` or the signed integer ``-1`` as this value in
 w0 indicates failure to get a TRNG source.

diff --git a/include/plat/common/platform.h b/include/plat/common/platform.h
index c90441c678d7f154dc0cd204951f560622200461..c7b7908b53fc3afb0eb1b02b9933eaeae0e2a12e 100644 (file)
--- a/include/plat/common/platform.h
+++ b/include/plat/common/platform.h
@@ -16,10 +16,10 @@
 #if ENABLE_RME
 #include <services/rmm_core_manifest.h>
 #endif
+#include <drivers/fwu/fwu_metadata.h>
 #if TRNG_SUPPORT
 #include "plat_trng.h"
-#endif
-#include <drivers/fwu/fwu_metadata.h>
+#endif /* TRNG_SUPPORT */
 #if DRTM_SUPPORT
 #include "plat_drtm.h"
 #endif /* DRTM_SUPPORT */

diff --git a/include/services/trng_svc.h b/include/services/trng_svc.h
index ed4d557ca5458982a8522ec77c0b368c0584c0d4..92417c22ddcd848d8088872e36257ab40c0fc502 100644 (file)
--- a/include/services/trng_svc.h
+++ b/include/services/trng_svc.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, ARM Limited. All rights reserved.
+ * Copyright (c) 2021-2022, ARM Limited. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -17,7 +17,7 @@
 #define ARM_TRNG_FEATURES      U(0x84000051)
 #define ARM_TRNG_GET_UUID      U(0x84000052)
 #define ARM_TRNG_RND32         U(0x84000053)
-#define ARM_TRNG_RND64         U(0xc4000053)
+#define ARM_TRNG_RND64         U(0xC4000053)
 
 /* TRNG version numbers */
 #define TRNG_VERSION_MAJOR     (0x1)
@@ -30,19 +30,17 @@
 #define TRNG_E_NO_ENTROPY      (-3)
 #define TRNG_E_NOT_IMPLEMENTED (-4)
 
-#if TRNG_SUPPORT
+/* TRNG Entropy Bit Numbers */
+#define TRNG_RND32_ENTROPY_MAXBITS     (96U)
+#define TRNG_RND64_ENTROPY_MAXBITS     (192U)
+
+/* Public API to perform the initial TRNG entropy setup */
 void trng_setup(void);
+
+/* Public API to verify function id is part of TRNG */
 bool is_trng_fid(uint32_t smc_fid);
-#else
-static inline void trng_setup(void)
-{
-}
-
-static inline bool is_trng_fid(uint32_t smc_fid)
-{
-       return false;
-}
-#endif
+
+/* Handler to be called to handle TRNG smc calls */
 uintptr_t trng_smc_handler(
        uint32_t smc_fid,
        u_register_t x1,

diff --git a/make_helpers/defaults.mk b/make_helpers/defaults.mk
index 65ceb7f205d2dde0829e40116ad3b1d9c67232d1..772b28de035889403e3eaaf8f2cd44d5ec935fc4 100644 (file)
--- a/make_helpers/defaults.mk
+++ b/make_helpers/defaults.mk
@@ -270,7 +270,7 @@ SAVE_KEYS                   := 0
 # Software Delegated Exception support
 SDEI_SUPPORT                   := 0
 
-# True Random Number firmware Interface
+# True Random Number firmware Interface support
 TRNG_SUPPORT                   := 0
 
 # SMCCC PCI support

diff --git a/services/std_svc/std_svc_setup.c b/services/std_svc/std_svc_setup.c
index 08d16e21a27074dc901fcffb5aa1658983f6aae4..2884a3b9ebc37dbe2f2b2d72a7fcade026cebf1e 100644 (file)
--- a/services/std_svc/std_svc_setup.c
+++ b/services/std_svc/std_svc_setup.c
@@ -74,7 +74,10 @@ static int32_t std_svc_setup(void)
        sdei_init();
 #endif
 
+#if TRNG_SUPPORT
+       /* TRNG initialisation */
        trng_setup();
+#endif /* TRNG_SUPPORT */
 
 #if DRTM_SUPPORT
        if (drtm_setup() != 0) {
@@ -172,7 +175,8 @@ static uintptr_t std_svc_smc_handler(uint32_t smc_fid,
                return trng_smc_handler(smc_fid, x1, x2, x3, x4, cookie, handle,
                                flags);
        }
-#endif
+#endif /* TRNG_SUPPORT */
+
 #if ENABLE_RME
 
        if (is_rmmd_el3_fid(smc_fid)) {

diff --git a/services/std_svc/trng/trng_entropy_pool.c b/services/std_svc/trng/trng_entropy_pool.c
index ac13b1d7a0f45ecc1116e3c4d0419f93e20a2be2..30105b3a35379be34065428e930a6f8c4868fcc1 100644 (file)
--- a/services/std_svc/trng/trng_entropy_pool.c
+++ b/services/std_svc/trng/trng_entropy_pool.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, ARM Limited. All rights reserved.
+ * Copyright (c) 2021-2022, ARM Limited. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -18,7 +18,7 @@
  * 192 bits of entropy, we don't have to throw out the leftover 1-63 bits of
  * entropy.
  */
-#define WORDS_IN_POOL (4)
+#define WORDS_IN_POOL  (4)
 static uint64_t entropy[WORDS_IN_POOL];
 /* index in bits of the first bit of usable entropy */
 static uint32_t entropy_bit_index;
@@ -27,14 +27,14 @@ static uint32_t entropy_bit_size;
 
 static spinlock_t trng_pool_lock;
 
-#define BITS_PER_WORD (sizeof(entropy[0]) * 8)
-#define BITS_IN_POOL (WORDS_IN_POOL * BITS_PER_WORD)
-#define ENTROPY_MIN_WORD (entropy_bit_index / BITS_PER_WORD)
-#define ENTROPY_FREE_BIT (entropy_bit_size + entropy_bit_index)
-#define _ENTROPY_FREE_WORD (ENTROPY_FREE_BIT / BITS_PER_WORD)
-#define ENTROPY_FREE_INDEX (_ENTROPY_FREE_WORD % WORDS_IN_POOL)
+#define BITS_PER_WORD          (sizeof(entropy[0]) * 8)
+#define BITS_IN_POOL           (WORDS_IN_POOL * BITS_PER_WORD)
+#define ENTROPY_MIN_WORD       (entropy_bit_index / BITS_PER_WORD)
+#define ENTROPY_FREE_BIT       (entropy_bit_size + entropy_bit_index)
+#define _ENTROPY_FREE_WORD     (ENTROPY_FREE_BIT / BITS_PER_WORD)
+#define ENTROPY_FREE_INDEX     (_ENTROPY_FREE_WORD % WORDS_IN_POOL)
 /* ENTROPY_WORD_INDEX(0) includes leftover bits in the lower bits */
-#define ENTROPY_WORD_INDEX(i) ((ENTROPY_MIN_WORD + i) % WORDS_IN_POOL)
+#define ENTROPY_WORD_INDEX(i)  ((ENTROPY_MIN_WORD + i) % WORDS_IN_POOL)
 
 /*
  * Fill the entropy pool until we have at least as many bits as requested.
@@ -65,12 +65,12 @@ static bool trng_fill_entropy(uint32_t nbits)
  */
 bool trng_pack_entropy(uint32_t nbits, uint64_t *out)
 {
-       bool success = true;
+       bool ret = true;
 
        spin_lock(&trng_pool_lock);
 
        if (!trng_fill_entropy(nbits)) {
-               success = false;
+               ret = false;
                goto out;
        }
 
@@ -82,9 +82,8 @@ bool trng_pack_entropy(uint32_t nbits, uint64_t *out)
        for (word_i = 0; word_i < to_fill; word_i++) {
                /*
                 * Repack the entropy from the pool into the passed in out
-                * buffer. This takes the lower bits from the valid upper bits
-                * of word_i and the upper bits from the lower bits of
-                * (word_i + 1).
+                * buffer. This takes lesser bits from the valid upper bits
+                * of word_i and more bits from the lower bits of (word_i + 1).
                 *
                 * I found the following diagram useful. note: `e` represents
                 * valid entropy, ` ` represents invalid bits (not entropy) and
@@ -136,7 +135,7 @@ bool trng_pack_entropy(uint32_t nbits, uint64_t *out)
 out:
        spin_unlock(&trng_pool_lock);
 
-       return success;
+       return ret;
 }
 
 void trng_entropy_pool_setup(void)

diff --git a/services/std_svc/trng/trng_main.c b/services/std_svc/trng/trng_main.c
index 38aa6499733ad054d16d116b5dd453a54af37a68..90098a8f209342bcdcbf6a9efd8b4c13022c5856 100644 (file)
--- a/services/std_svc/trng/trng_main.c
+++ b/services/std_svc/trng/trng_main.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, ARM Limited and Contributors. All rights reserved.
+ * Copyright (c) 2021-2022, ARM Limited and Contributors. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -23,9 +23,9 @@ static const uuid_t uuid_null;
 static uintptr_t trng_rnd32(uint32_t nbits, void *handle)
 {
        uint32_t mask = ~0U;
-       uint64_t ent[2];
+       uint64_t ent[2] = {0};
 
-       if (nbits == 0U || nbits > 96U) {
+       if (nbits == 0U || nbits > TRNG_RND32_ENTROPY_MAXBITS) {
                SMC_RET1(handle, TRNG_E_INVALID_PARAMS);
        }
 
@@ -59,9 +59,9 @@ static uintptr_t trng_rnd32(uint32_t nbits, void *handle)
 static uintptr_t trng_rnd64(uint32_t nbits, void *handle)
 {
        uint64_t mask = ~0ULL;
-       uint64_t ent[3];
+       uint64_t ent[3] = {0};
 
-       if (nbits == 0U || nbits > 192U) {
+       if (nbits == 0U || nbits > TRNG_RND64_ENTROPY_MAXBITS) {
                SMC_RET1(handle, TRNG_E_INVALID_PARAMS);
        }
 
@@ -117,9 +117,9 @@ uintptr_t trng_smc_handler(uint32_t smc_fid, u_register_t x1, u_register_t x2,
        switch (smc_fid) {
        case ARM_TRNG_VERSION:
                SMC_RET1(handle, MAKE_SMCCC_VERSION(
-                       TRNG_VERSION_MAJOR, TRNG_VERSION_MINOR
-               ));
+                       TRNG_VERSION_MAJOR, TRNG_VERSION_MINOR));
                break; /* unreachable */
+
        case ARM_TRNG_FEATURES:
                if (is_trng_fid((uint32_t)x1)) {
                        SMC_RET1(handle, TRNG_E_SUCCESS);
@@ -127,16 +127,19 @@ uintptr_t trng_smc_handler(uint32_t smc_fid, u_register_t x1, u_register_t x2,
                        SMC_RET1(handle, TRNG_E_NOT_SUPPORTED);
                }
                break; /* unreachable */
+
        case ARM_TRNG_GET_UUID:
                SMC_UUID_RET(handle, plat_trng_uuid);
                break; /* unreachable */
+
        case ARM_TRNG_RND32:
                return trng_rnd32((uint32_t)x1, handle);
+
        case ARM_TRNG_RND64:
                return trng_rnd64((uint32_t)x1, handle);
+
        default:
-               WARN("Unimplemented TRNG Service Call: 0x%x\n",
-                       smc_fid);
+               WARN("Unimplemented TRNG Service Call: 0x%x\n", smc_fid);
                SMC_RET1(handle, TRNG_E_NOT_IMPLEMENTED);
                break; /* unreachable */
        }