PrmPkg/Application/PrmInfo: Add initial application

Adds a new UEFI application called "PrmInfo" that allows a user
to display and test Platform Runtime Mechanism (PRM) modules.

Execute the application help command for detailed usage
instructions and examples of how to use the application:
  "PrmInfo -?"

This application is intended to be helpful during PRM enabling
by allowing the user to:

1. Confirm that their firmware port of the PRM infrastructure
   implemented in this package is functioning correctly.

2. Quickly get information about what PRM modules and handlers
   are present on a given system.

3. Quickly test PRM handlers without booting to a fully featured
   operating system.

4. Develop and exercise PRM handlers prior to the availability of
   an operating system that is PRM aware.

Adds a brief section to Readme.md about the PrmInfo UEFI application
with a link to allow the reader to find more information about the
application if interested.

Cc: Andrew Fish <afish@apple.com>
Cc: Kang Gao <kang.gao@intel.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Michael Kubacki <michael.kubacki@microsoft.com>
Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Benjamin You <benjamin.you@intel.com>
Cc: Liu Yun <yun.y.liu@intel.com>
Cc: Ankit Sinha <ankit.sinha@intel.com>
Cc: Nate DeSimone <nathaniel.l.desimone@intel.com>
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
Acked-by: Michael D Kinney <michael.d.kinney@intel.com>
Acked-by: Liming Gao <gaoliming@byosoft.com.cn>
Acked-by: Leif Lindholm <quic_llindhol@quicinc.com>
Reviewed-by: Ankit Sinha <ankit.sinha@intel.com>

1 files changed, 132 insertions, 0 deletions

diff --git a/PrmPkg/Application/PrmInfo/PrmInfoStrings.uni b/PrmPkg/Application/PrmInfo/PrmInfoStrings.uni
new file mode 100644
index 0000000000..9385fd8483
--- /dev/null
+++ b/PrmPkg/Application/PrmInfo/PrmInfoStrings.uni
@@ -0,0 +1,132 @@
+/** @file

+  String definitions for the PRM Information UEFI shell application.

+

+  Copyright (C) Microsoft Corporation. All rights reserved.

+  SPDX-License-Identifier: BSD-2-Clause-Patent

+

+*/

+

+#langdef en-US "English"

+

+//

+// Parameter error messages

+//

+#string STR_PRMINFO_DISCOVERY_FAILED  #language en-US "%H%s%N: PRM module discovery failed.\r\n"

+#string STR_PRMINFO_GEN_PROBLEM       #language en-US "%H%s%N: Unknown flag - '%H%s%N'\r\n"

+#string STR_PRMINFO_GUID_INV          #language en-US "%H%s%N: Invalid GUID - '%H%s%N'\r\n"

+#string STR_PRMINFO_HANDLER_NOT_FOUND #language en-US "%H%s%N: PRM Handler not found - '%H{%g}%N'\r\n"

+#string STR_PRMINFO_MISSING_OPTION    #language en-US "%H%s%N: Missing option '%H%s%N' required by flag - '%H%s%N'\r\n"

+#string STR_PRMINFO_NO_ARG            #language en-US "%H%s%N: An argument must be provided, try "-?" for help.\n"

+#string STR_PRMINFO_NO_VALUE          #language en-US "%H%s%N: Missing argument for flag - '%H%s%N'\r\n"

+#string STR_PRMINFO_PARAM_INV         #language en-US "%H%s%N: Invalid argument - '%H%s%N', try "-?" for help.\r\n"

+#string STR_PRMINFO_TOO_MANY          #language en-US "%H%s%N: Too many arguments.\r\n"

+

+//

+// Application informational messages

+//

+#string STR_PRMINFO_HANDLER_COUNT       #language en-US "  Handler Count: %d\r\n"

+#string STR_PRMINFO_HANDLER_EXEC_TIME   #language en-US "  Execution Time: "

+#string STR_PRMINFO_HANDLER_GUID        #language en-US "  Handler GUID: %g\r\n"

+#string STR_PRMINFO_HANDLER_NAME        #language en-US "  Handler Name: %a\r\n"

+#string STR_PRMINFO_HANDLER_NAME_HL     #language en-US "  Handler Name: %H%a%N\r\n"

+#string STR_PRMINFO_HANDLER_PA          #language en-US "    Handler Physical Address: 0x%016x\r\n"

+#string STR_PRMINFO_HANDLER_ERR_STATUS  #language en-US "  Return Status: %E%r%N\r\n"

+#string STR_PRMINFO_HANDLER_SUCC_STATUS #language en-US "  Return Status: %V%r%N\r\n"

+#string STR_PRMINFO_HANDLERS_FOUND      #language en-US "  %d PRM handlers found.\r\n"

+#string STR_PRMINFO_LINE_BREAK          #language en-US "\r\n"

+#string STR_PRMINFO_LIST_TITLE          #language en-US "PRM Modules and Handlers:\r\n"

+#string STR_PRMINFO_MODULE_GUID         #language en-US "Module GUID: %g\r\n"

+#string STR_PRMINFO_MODULE_NAME         #language en-US "Module Name: %a\r\n"

+#string STR_PRMINFO_MODULE_VERSION      #language en-US "Module Version: %02d.%02d\r\n\r\n"

+#string STR_PRMINFO_MODULES_FOUND       #language en-US "  %d PRM modules found.\r\n"

+#string STR_PRMINFO_NO_MMIO_RANGES      #language en-US "  No runtime MMIO ranges used by this module.\r\n"

+#string STR_PRMINFO_NO_STATIC_BUFFER    #language en-US "      This handler does not define a static data buffer.\r\n\r\n"

+#string STR_PRMINFO_RUNTIME_MMIO_COUNT  #language en-US "  Runtime MMIO Range Count: %d\r\n"

+#string STR_PRMINFO_RUNTIME_MMIO_INFO   #language en-US "    [%d]: Physical Base Address = 0x%016x\r\n          Virtual Base Address = 0x%016x\r\n          Length = 0x%x\r\n"

+#string STR_PRMINFO_STATIC_DATA_BUFFER  #language en-US "    Static Data Buffer: 0x%016x\r\n"

+#string STR_PRMINFO_UNKNOWN             #language en-US "Unknown"

+#string STR_PRMINFO_USECS               #language en-US "%H%ld.%ld microseconds%N"

+#string STR_PRMINFO_NANO_SECS           #language en-US "%H%ld nanoseconds%N"

+#string STR_PRMINFO_SECS                #language en-US "%H%ld.%ld%ld%ld seconds%N"

+#string STR_PRMINFO_MILLI_SECS          #language en-US "%H%ld.%ld%ld milliseconds%N"

+

+//

+// Application error messages

+//

+#string STR_PRMINFO_HANDLER_PA_ERROR    #language en-US "    An ERROR (%r) occurred determining the handler physical address.\r\n"

+

+#string STR_PRMINFO_HELP                  #language en-US ""

+".TH PrmInfo 0 "Display and test Platform Runtime Mechanism (PRM) modules."\r\n"

+".SH NAME:\r\n"

+"Display and test Platform Runtime Mechanism (PRM) modules.\r\n"

+".SH SYNOPSIS\r\n"

+"\r\n"

+"PRMINFO [[-?] | [-b] [-l] [-r] [-t (guid | all)]]\r\n"

+".SH OPTIONS\r\n"

+" \r\n"

+"  -? - Show help.\r\n"

+"  -b - Displays one screen of output at a time.\r\n"

+"  -l - Display a list of installed PRM modules and handlers.\r\n"

+"  -t - Call a given PRM handler by the specified GUID.\r\n"

+"         guid - A 32 digit GUID string with hyphen separation with no enclosing\r\n"

+"                character such as braces.\r\n"

+"           Example: 00000000-0000-0000-0000-000000000000\r\n"

+"         all - The string 'all' indicating all PRM handlers should be called\r\n"

+"               in order discovered.\r\n"

+".SH DESCRIPTION\r\n"

+" \r\n"

+"  This program is provided to allow examination of the Platform Runtime\r\n"

+"  Mechanism (PRM) configuration present on the current system. In addition,\r\n"

+"  the application contains some lightweight tests to verify that the firmware\r\n"

+"  set up the PRM  information that will be conveyed to the loaded operating\r\n"

+"  system correctly.\r\n"

+" \r\n"

+"  Default behavior is to display the content of all the PRM modules and\r\n"

+"  handlers currently installed (equivalent to the -l argument). To facilitate\r\n"

+"  debugging and verifying correct implementation of the PRM infrastructure\r\n"

+"  and PRM modules in a given firmware, the application can also call a\r\n"

+"  given PRM handler and perform basic validation of the PRMT ACPI table\r\n"

+"  to confirm it satisfies the basic constraints required for the table\r\n"

+"  in the PRM Specification.\r\n"

+" \r\n"

+"NOTES:\r\n"

+"  1. Calling PRM handlers from this application:\r\n"

+"     -  The user should exercise caution when calling PRM handlers in the\r\n"

+"        pre-OS environment. The PRM author may have only considered\r\n"

+"        execution within the context of OS runtime."

+"\r\n"

+"     -  The application will not perform any manipulation of PRM handler\r\n"

+"        parameter buffers prior to calling the handler.\r\n"

+"\r\n"

+"     -  This feature is intended to provide a quick method to exercise\r\n"

+"        PRM code without loading a full OS that is PRM aware and to perform\r\n"

+"        testing of PRM code that is aware it will be executed in such an\r\n"

+"        environment. It is not recommended to call PRM handlers on a\r\n"

+"        production system if you are not fully aware of how the PRM handler\r\n"

+"        behaves and any side effect(s) it might have on the system.\r\n"

+".SH STANDARDS\r\n"

+" \r\n"

+"STANDARDS:\r\n"

+"  Platform Runtime Mechanism (PRM) is currently in a draft state and the\r\n"

+"  specification is not yet publicly available. A reference to the publicly\r\n"

+"  available document will replace this text when it is available.\r\n"

+".SH EXAMPLES\r\n"

+" \r\n"

+"EXAMPLES:\r\n"

+"  * To display a list of the installed PRM modules and PRM handlers:\r\n"

+"    fs0:\> prminfo -l\r\n"

+" \r\n"

+"  * To validate the installed PRMT ACPI table:\r\n"

+"    fs0:\> prminfo -r\r\n"

+" \r\n"

+"  * To call a PRM handler by GUID:\r\n"

+"    fs0:\> prminfo -t e1466081-7562-430f-896b-b0e523dc335a\r\n"

+" \r\n"

+"  * To call all of the PRM handlers discovered on the system:\r\n"

+"    fs0:\> prminfo -t all\r\n"

+".SH RETURNVALUES\r\n"

+" \r\n"

+"RETURN VALUES:\r\n"

+"  SHELL_SUCCESS             Data was displayed as requested.\r\n"

+"  SHELL_INVALID_PARAMETER   The operation failed.\r\n"

+" \r\n"