ArmPkg: Add FID definitions for Arm TRNG

Bugzilla: 3668 (https://bugzilla.tianocore.org/show_bug.cgi?id=3668)

The Arm True Random Number Generator Firmware, Interface 1.0,
Platform Design Document
(https://developer.arm.com/documentation/den0098/latest/)
defines an interface between an Operating System (OS) executing
at EL1 and Firmware (FW) exposing a conditioned entropy source
that is provided by a TRNG back end.

New function IDs have been defined by the specification for
accessing the TRNG services. Therefore, add these definitions
to the Arm standard SMC header.

Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Reviewed-by: Ard Biesheuvel <ardb@kernel.org>

diff --git a/ArmPkg/Include/IndustryStandard/ArmStdSmc.h b/ArmPkg/Include/IndustryStandard/ArmStdSmc.h
index 78ce77cd734d2bbc0db9e90afb29dc6d78ef171e..374b9ded7f5f5231c5e96f05bc5de1d9bb6f772c 100644 (file)
--- a/ArmPkg/Include/IndustryStandard/ArmStdSmc.h
+++ b/ArmPkg/Include/IndustryStandard/ArmStdSmc.h
@@ -1,13 +1,20 @@
 /** @file\r
 *\r
 *  Copyright (c) 2020, NUVIA Inc. All rights reserved.<BR>\r
-*  Copyright (c) 2012-2017, ARM Limited. All rights reserved.\r
+*  Copyright (c) 2012 - 2022, Arm Limited. All rights reserved.\r
 *\r
 *  SPDX-License-Identifier: BSD-2-Clause-Patent\r
 *\r
 * @par Revision Reference:\r
-*  - SMC Calling Convention version 1.2\r
+*  - [1] SMC Calling Convention version 1.2\r
 *    (https://developer.arm.com/documentation/den0028/c/?lang=en)\r
+*  - [2] Arm True Random Number Generator Firmware, Interface 1.0,\r
+*    Platform Design Document.\r
+*    (https://developer.arm.com/documentation/den0098/latest/)\r
+*\r
+*  @par Glossary:\r
+*    - TRNG - True Random Number Generator\r
+*\r
 **/\r
 \r
 #ifndef ARM_STD_SMC_H_\r
@@ -139,4 +146,102 @@
 /*                                    0xbf00ff02 is reserved */\r
 #define ARM_SMC_ID_TOS_REVISION  0xbf00ff03\r
 \r
+// Firmware TRNG interface Function IDs\r
+\r
+/*\r
+  SMC/HVC call to get the version of the TRNG backend,\r
+  Cf. [2], 2.1 TRNG_VERSION\r
+  Input values:\r
+    W0    0x8400_0050\r
+    W1-W7 Reserved (MBZ)\r
+  Return values:\r
+    Success (W0 > 0) W0[31] MBZ\r
+      W0[30:16] Major revision\r
+      W0[15:0] Minor revision\r
+      W1 - W3 Reserved (MBZ)\r
+    Error (W0 < 0)\r
+      NOT_SUPPORTED Function not implemented\r
+*/\r
+#define ARM_SMC_ID_TRNG_VERSION  0x84000050\r
+\r
+/*\r
+  SMC/HVC call to check if a TRNG function ID is implemented by the backend,\r
+  Cf. [2], Section 2.2 TRNG_FEATURES\r
+  Input Values\r
+    W0    0x8400_0051\r
+    W1    trng_func_id\r
+    W2-W7 Reserved (MBZ)\r
+  Return values:\r
+    Success (W0 >= 0):\r
+      SUCCESS Function is implemented.\r
+        > 0     Function is implemented and\r
+                has specific capabilities,\r
+                see function definition.\r
+    Error (W0 < 0)\r
+      NOT_SUPPORTED Function with FID=trng_func_id\r
+      is not implemented\r
+*/\r
+#define ARM_SMC_ID_TRNG_FEATURES  0x84000051\r
+\r
+/*\r
+  SMC/HVC call to get the UUID of the TRNG backend,\r
+  Cf. [2], Section 2.3 TRNG_GET_UUID\r
+  Input Values:\r
+    W0    0x8400_0052\r
+    W1-W7 Reserved (MBZ)\r
+  Return Values:\r
+    Success (W0 != -1)\r
+        W0 UUID[31:0]\r
+        W1 UUID[63:32]\r
+        W2 UUID[95:64]\r
+        W3 UUID[127:96]\r
+    Error (W0 = -1)\r
+        W0 NOT_SUPPORTED\r
+*/\r
+#define ARM_SMC_ID_TRNG_GET_UUID  0x84000052\r
+\r
+/*\r
+  AARCH32 SMC/HVC call to get entropy bits, Cf. [2], Section 2.4 TRNG_RND.\r
+  Input values:\r
+    W0    0x8400_0053\r
+    W2-W7 Reserved (MBZ)\r
+  Return values:\r
+    Success (W0 = 0):\r
+      W0 MBZ\r
+      W1 Entropy[95:64]\r
+      W2 Entropy[63:32]\r
+      W3 Entropy[31:0]\r
+    Error (W0 < 0)\r
+          W0 NOT_SUPPORTED\r
+          NO_ENTROPY\r
+          INVALID_PARAMETERS\r
+          W1 - W3 Reserved (MBZ)\r
+*/\r
+#define ARM_SMC_ID_TRNG_RND_AARCH32  0x84000053\r
+\r
+/*\r
+  AARCH64 SMC/HVC call to get entropy bits, Cf. [2], Section 2.4 TRNG_RND.\r
+  Input values:\r
+      X0    0xC400_0053\r
+      X2-X7 Reserved (MBZ)\r
+  Return values:\r
+    Success (X0 = 0):\r
+      X0 MBZ\r
+      X1 Entropy[191:128]\r
+      X2 Entropy[127:64]\r
+      X3 Entropy[63:0]\r
+    Error (X0 < 0)\r
+          X0 NOT_SUPPORTED\r
+          NO_ENTROPY\r
+          INVALID_PARAMETERS\r
+          X1 - X3 Reserved (MBZ)\r
+*/\r
+#define ARM_SMC_ID_TRNG_RND_AARCH64  0xC4000053\r
+\r
+// Firmware TRNG status codes\r
+#define TRNG_STATUS_SUCCESS            (INT32)(0)\r
+#define TRNG_STATUS_NOT_SUPPORTED      (INT32)(-1)\r
+#define TRNG_STATUS_INVALID_PARAMETER  (INT32)(-2)\r
+#define TRNG_STATUS_NO_ENTROPY         (INT32)(-3)\r
+\r
 #endif // ARM_STD_SMC_H_\r