MdePkg: Add RngLib into MdePkg

Add one library class (RngLib.h) with three GetRandomNumber16/32/64
APIs to provide random number generator services, and one library
instance (BaseRngLib), based on Intel RdRand instruction access,
to provide high-quality random numbers generator.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Qin Long <qin.long@intel.com>
Reviewed-by: Michael Kinney <michael.d.kinney@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@18519 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/MdePkg/Include/Library/RngLib.h b/MdePkg/Include/Library/RngLib.h
new file mode 100644 (file)
index 0000000..157a931
--- /dev/null
+++ b/MdePkg/Include/Library/RngLib.h
@@ -0,0 +1,69 @@
+/** @file\r
+  Provides random number generator services.\r
+\r
+Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>\r
+This program and the accompanying materials\r
+are licensed and made available under the terms and conditions of the BSD License\r
+which accompanies this distribution.  The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php\r
+\r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+\r
+#ifndef __RNG_LIB_H__\r
+#define __RNG_LIB_H__\r
+\r
+/**\r
+  Generates a 16-bit random number.\r
+\r
+  if Rand is NULL, then ASSERT().\r
+\r
+  @param[out] Rand     Buffer pointer to store the 16-bit random value.\r
+\r
+  @retval TRUE         Random number generated successfully.\r
+  @retval FALSE        Failed to generate the random number.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+GetRandomNumber16 (\r
+  OUT     UINT16                    *Rand\r
+  );\r
+\r
+/**\r
+  Generates a 32-bit random number.\r
+\r
+  if Rand is NULL, then ASSERT().\r
+\r
+  @param[out] Rand     Buffer pointer to store the 32-bit random value.\r
+\r
+  @retval TRUE         Random number generated successfully.\r
+  @retval FALSE        Failed to generate the random number.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+GetRandomNumber32 (\r
+  OUT     UINT32                    *Rand\r
+  );\r
+\r
+/**\r
+  Generates a 64-bit random number.\r
+\r
+  if Rand is NULL, then ASSERT().\r
+\r
+  @param[out] Rand     Buffer pointer to store the 64-bit random value.\r
+\r
+  @retval TRUE         Random number generated successfully.\r
+  @retval FALSE        Failed to generate the random number.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+GetRandomNumber64 (\r
+  OUT     UINT64                    *Rand\r
+  );\r
+\r
+#endif  // __RNG_LIB_H__\r

diff --git a/MdePkg/Library/BaseRngLib/BaseRng.c b/MdePkg/Library/BaseRngLib/BaseRng.c
new file mode 100644 (file)
index 0000000..279df30
--- /dev/null
+++ b/MdePkg/Library/BaseRngLib/BaseRng.c
@@ -0,0 +1,157 @@
+/** @file\r
+  Random number generator services that uses RdRand instruction access\r
+  to provide high-quality random numbers.\r
+\r
+Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>\r
+This program and the accompanying materials\r
+are licensed and made available under the terms and conditions of the BSD License\r
+which accompanies this distribution.  The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php\r
+\r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+\r
+#include <Library/BaseLib.h>\r
+#include <Library/DebugLib.h>\r
+\r
+//\r
+// Bit mask used to determine if RdRand instruction is supported.\r
+//\r
+#define RDRAND_MASK                  BIT30\r
+\r
+//\r
+// Limited retry number when valid random data is returned.\r
+// Uses the recommended value defined in Section 7.3.17 of "Intel 64 and IA-32\r
+// Architectures Software Developer's Mannual".\r
+//\r
+#define RDRAND_RETRY_LIMIT           10\r
+\r
+/**\r
+  The constructor function checks whether or not RDRAND instruction is supported\r
+  by the host hardware.\r
+\r
+  The constructor function checks whether or not RDRAND instruction is supported.\r
+  It will ASSERT() if RDRAND instruction is not supported.\r
+  It will always return RETURN_SUCCESS.\r
+\r
+  @retval RETURN_SUCCESS   The constructor always returns EFI_SUCCESS.\r
+\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+BaseRngLibConstructor (\r
+  VOID\r
+  )\r
+{\r
+  UINT32  RegEcx;\r
+\r
+  //\r
+  // Determine RDRAND support by examining bit 30 of the ECX register returned by\r
+  // CPUID. A value of 1 indicates that processor support RDRAND instruction.\r
+  //\r
+  AsmCpuid (1, 0, 0, &RegEcx, 0);\r
+  ASSERT ((RegEcx & RDRAND_MASK) == RDRAND_MASK);\r
+\r
+  return RETURN_SUCCESS;\r
+}\r
+\r
+/**\r
+  Generates a 16-bit random number.\r
+\r
+  if Rand is NULL, then ASSERT().\r
+\r
+  @param[out] Rand     Buffer pointer to store the 16-bit random value.\r
+\r
+  @retval TRUE         Random number generated successfully.\r
+  @retval FALSE        Failed to generate the random number.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+GetRandomNumber16 (\r
+  OUT     UINT16                    *Rand\r
+  )\r
+{\r
+  UINT32  Index;\r
+\r
+  ASSERT (Rand != NULL);\r
+\r
+  //\r
+  // A loop to fetch a 16 bit random value with a retry count limit.\r
+  //\r
+  for (Index = 0; Index < RDRAND_RETRY_LIMIT; Index++) {\r
+    if (AsmRdRand16 (Rand)) {\r
+      return TRUE;\r
+    }\r
+  }\r
+\r
+  return FALSE;\r
+}\r
+\r
+/**\r
+  Generates a 32-bit random number.\r
+\r
+  if Rand is NULL, then ASSERT().\r
+\r
+  @param[out] Rand     Buffer pointer to store the 32-bit random value.\r
+\r
+  @retval TRUE         Random number generated successfully.\r
+  @retval FALSE        Failed to generate the random number.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+GetRandomNumber32 (\r
+  OUT     UINT32                    *Rand\r
+  )\r
+{\r
+  UINT32  Index;\r
+\r
+  ASSERT (Rand != NULL);\r
+\r
+  //\r
+  // A loop to fetch a 32 bit random value with a retry count limit.\r
+  //\r
+  for (Index = 0; Index < RDRAND_RETRY_LIMIT; Index++) {\r
+    if (AsmRdRand32 (Rand)) {\r
+      return TRUE;\r
+    }\r
+  }\r
+\r
+  return FALSE;\r
+}\r
+\r
+/**\r
+  Generates a 64-bit random number.\r
+\r
+  if Rand is NULL, then ASSERT().\r
+\r
+  @param[out] Rand     Buffer pointer to store the 64-bit random value.\r
+\r
+  @retval TRUE         Random number generated successfully.\r
+  @retval FALSE        Failed to generate the random number.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+GetRandomNumber64 (\r
+  OUT     UINT64                    *Rand\r
+  )\r
+{\r
+  UINT32  Index;\r
+\r
+  ASSERT (Rand != NULL);\r
+\r
+  //\r
+  // A loop to fetch a 64 bit random value with a retry count limit.\r
+  //\r
+  for (Index = 0; Index < RDRAND_RETRY_LIMIT; Index++) {\r
+    if (AsmRdRand64 (Rand)) {\r
+      return TRUE;\r
+    }\r
+  }\r
+\r
+  return FALSE;\r
+}\r

diff --git a/MdePkg/Library/BaseRngLib/BaseRngLib.inf b/MdePkg/Library/BaseRngLib/BaseRngLib.inf
new file mode 100644 (file)
index 0000000..05a5b77
--- /dev/null
+++ b/MdePkg/Library/BaseRngLib/BaseRngLib.inf
@@ -0,0 +1,41 @@
+## @file\r
+#  Instance of RNG (Random Number Generator) Library.\r
+#\r
+#  BaseRng Library that uses CPU RdRand instruction access to provide\r
+#  high-quality random numbers.\r
+#\r
+#  Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>\r
+#\r
+#  This program and the accompanying materials\r
+#  are licensed and made available under the terms and conditions of the BSD License\r
+#  which accompanies this distribution. The full text of the license may be found at\r
+#  http://opensource.org/licenses/bsd-license.php.\r
+#  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+#  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+#\r
+#\r
+##\r
+\r
+[Defines]\r
+  INF_VERSION                    = 0x00010005\r
+  BASE_NAME                      = BaseRngLib\r
+  MODULE_UNI_FILE                = BaseRngLib.uni\r
+  FILE_GUID                      = 626440D8-1971-41D9-9AB2-FB25F4AE79BC\r
+  MODULE_TYPE                    = BASE\r
+  VERSION_STRING                 = 1.0\r
+  LIBRARY_CLASS                  = RngLib\r
+  CONSTRUCTOR                    = BaseRngLibConstructor\r
+\r
+#\r
+#  VALID_ARCHITECTURES           = IA32 X64\r
+#\r
+\r
+[Sources.Ia32, Sources.X64]\r
+  BaseRng.c\r
+\r
+[Packages]\r
+  MdePkg/MdePkg.dec\r
+\r
+[LibraryClasses]\r
+  BaseLib\r
+  DebugLib\r

diff --git a/MdePkg/Library/BaseRngLib/BaseRngLib.uni b/MdePkg/Library/BaseRngLib/BaseRngLib.uni
new file mode 100644 (file)
index 0000000..3d6e905
Binary files /dev/null and b/MdePkg/Library/BaseRngLib/BaseRngLib.uni differ

diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index 60549afaaafc87febbd1d32cd628b778455e09f1..337059a6a60254dea3cb8e6d1b11017a5d1f461e 100644 (file)
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -249,6 +249,10 @@
   #\r
   SmmPeriodicSmiLib|Include/Library/SmmPeriodicSmiLib.h\r
 \r
+  ##  @libraryclass  Provides services to generate random number.\r
+  #\r
+  RngLib|Include/Library/RngLib.h\r
+\r
 [LibraryClasses.IPF]\r
   ##  @libraryclass  The SAL Library provides a service to make a SAL CALL.\r
   SalLib|Include/Library/SalLib.h\r

diff --git a/MdePkg/MdePkg.dsc b/MdePkg/MdePkg.dsc
index 00c46d44fe36e9da6e67662e32578d0d7e77dc4a..4ea367ccc070fe51cd66e284bc377233b7d09a8b 100644 (file)
--- a/MdePkg/MdePkg.dsc
+++ b/MdePkg/MdePkg.dsc
@@ -152,6 +152,7 @@
   MdePkg/Library/BaseS3SmbusLib/BaseS3SmbusLib.inf\r
   MdePkg/Library/BaseS3StallLib/BaseS3StallLib.inf\r
   MdePkg/Library/SmmMemLib/SmmMemLib.inf\r
+  MdePkg/Library/BaseRngLib/BaseRngLib.inf\r
 \r
 [Components.IPF]\r
   MdePkg/Library/BaseIoLibIntrinsic/BaseIoLibIntrinsic.inf\r