ShellPkg: Support finding help message embedded in resource section.

UEFI Shell scandalizes the help message in spec level so that a standalone
UEFI shell application can never get "-?" switch, instead the Shell core
(interpreter) detects the "-?" and finds .MAN file for that shell
application in certain spec defined paths, then show the help extracted
from that .MAN file.

But it means distributing a UEFI shell application not only means
distributing a .EFI file but also distributing a .MAN file. If the text
formatted .MAN file is corrupted (edited by user by mistake), or is
missing (deleted by user by mistake), no help will be shown to user.

So this patch enhance the Shell to make it support finding help message
imbedded in resource section of application image.

Cc: Jaben Carsey <jaben.carsey@intel.com>
Cc: Ruiyu Ni <ruiyu.ni@intel.com>
Cc: Liming Gao <liming.gao@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Qiu Shumin <shumin.qiu@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>
Reviewed-by: Ruiyu Ni <ruiyu.ni@intel.com>

diff --git a/ShellPkg/Application/Shell/Shell.h b/ShellPkg/Application/Shell/Shell.h
index 351b94188eab9707834eed990f62c0eb4ab51cdf..a1b72765c0991ee4d8220ef6b806ba5ddb37eab8 100644 (file)
--- a/ShellPkg/Application/Shell/Shell.h
+++ b/ShellPkg/Application/Shell/Shell.h
@@ -2,7 +2,7 @@
   function definitions for internal to shell functions.\r
 \r
   (C) Copyright 2014 Hewlett-Packard Development Company, L.P.<BR>\r
-  Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>\r
+  Copyright (c) 2009 - 2016, 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
@@ -29,6 +29,7 @@
 #include <Protocol/EfiShellEnvironment2.h>\r
 #include <Protocol/EfiShellParameters.h>\r
 #include <Protocol/BlockIo.h>\r
+#include <Protocol/HiiPackageList.h>\r
 \r
 #include <Library/BaseLib.h>\r
 #include <Library/UefiApplicationEntryPoint.h>\r
@@ -47,6 +48,7 @@
 #include <Library/PrintLib.h>\r
 #include <Library/HandleParsingLib.h>\r
 #include <Library/FileHandleLib.h>\r
+#include <Library/UefiHiiServicesLib.h>\r
 \r
 #include "ShellParametersProtocol.h"\r
 #include "ShellProtocol.h"\r
@@ -122,6 +124,16 @@ typedef struct {
   BOOLEAN                       HaltOutput;           ///< TRUE to start a CTRL-S halt.\r
 } SHELL_INFO;\r
 \r
+#pragma pack(1)\r
+///\r
+/// HII specific Vendor Device Path definition.\r
+///\r
+typedef struct {\r
+  VENDOR_DEVICE_PATH             VendorDevicePath;\r
+  EFI_DEVICE_PATH_PROTOCOL       End;\r
+} SHELL_MAN_HII_VENDOR_DEVICE_PATH;\r
+#pragma pack()\r
+\r
 extern SHELL_INFO ShellInfoObject;\r
 \r
 /**\r

diff --git a/ShellPkg/Application/Shell/Shell.inf b/ShellPkg/Application/Shell/Shell.inf
index 253bfdbb224e9ed622dfe0be0a847a51ad340925..1b8b9ee7024024dcd59ef07e021cfeb0ee47b91f 100644 (file)
--- a/ShellPkg/Application/Shell/Shell.inf
+++ b/ShellPkg/Application/Shell/Shell.inf
@@ -2,7 +2,7 @@
 #  This is the shell application\r
 #\r
 #  (C) Copyright 2013 Hewlett-Packard Development Company, L.P.<BR>\r
-#  Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>\r
+#  Copyright (c) 2009 - 2016, 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
@@ -70,6 +70,7 @@
   HiiLib\r
   SortLib\r
   HandleParsingLib\r
+  UefiHiiServicesLib\r
 \r
 [Guids]\r
   gShellVariableGuid                                      ## CONSUMES ## GUID\r
@@ -93,6 +94,7 @@
   gEfiComponentName2ProtocolGuid                          ## CONSUMES\r
   gEfiUnicodeCollation2ProtocolGuid                       ## CONSUMES\r
   gEfiDevicePathProtocolGuid                              ## CONSUMES\r
+  gEfiHiiPackageListProtocolGuid                          ## SOMETIMES_PRODUCES\r
 \r
 [Pcd]\r
   gEfiShellPkgTokenSpaceGuid.PcdShellSupportLevel           ## CONSUMES\r

diff --git a/ShellPkg/Application/Shell/ShellManParser.c b/ShellPkg/Application/Shell/ShellManParser.c
index 222cdafd6ebe71c7bb5d89684d4c140604928621..948759fe46c89d7ad331bd5480ffc7e83eba63db 100644 (file)
--- a/ShellPkg/Application/Shell/ShellManParser.c
+++ b/ShellPkg/Application/Shell/ShellManParser.c
@@ -1,7 +1,7 @@
 /** @file\r
   Provides interface to shell MAN file parser.\r
 \r
-  Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>\r
+  Copyright (c) 2009 - 2016, Intel Corporation. All rights reserved.<BR>\r
   Copyright 2015 Dell Inc.\r
   This program and the accompanying materials\r
   are licensed and made available under the terms and conditions of the BSD License\r
@@ -15,6 +15,38 @@
 \r
 #include "Shell.h"\r
 \r
+#define SHELL_MAN_HII_GUID \\r
+{ \\r
+  0xf62ccd0c, 0x2449, 0x453c, { 0x8a, 0xcb, 0x8c, 0xc5, 0x7c, 0xf0, 0x2a, 0x97 } \\r
+}\r
+\r
+EFI_HII_HANDLE  mShellManHiiHandle    = NULL;\r
+EFI_HANDLE      mShellManDriverHandle = NULL;\r
+\r
+\r
+SHELL_MAN_HII_VENDOR_DEVICE_PATH  mShellManHiiDevicePath = {\r
+  {\r
+    {\r
+      HARDWARE_DEVICE_PATH,\r
+      HW_VENDOR_DP,\r
+      {\r
+        (UINT8) (sizeof (VENDOR_DEVICE_PATH)),\r
+        (UINT8) ((sizeof (VENDOR_DEVICE_PATH)) >> 8)\r
+      }\r
+    },\r
+    SHELL_MAN_HII_GUID\r
+  },\r
+  {\r
+    END_DEVICE_PATH_TYPE,\r
+    END_ENTIRE_DEVICE_PATH_SUBTYPE,\r
+    {\r
+      (UINT8) (END_DEVICE_PATH_LENGTH),\r
+      (UINT8) ((END_DEVICE_PATH_LENGTH) >> 8)\r
+    }\r
+  }\r
+};\r
+\r
+\r
 /**\r
   Convert a Unicode character to upper case only if\r
   it maps to a valid small-case ASCII character.\r
@@ -36,6 +68,58 @@ InternalShellCharToUpper (
   IN CHAR16  Char\r
   );\r
 \r
+/**\r
+  Verifies that the filename has .EFI on the end.\r
+\r
+  allocates a new buffer and copies the name (appending .EFI if necessary).\r
+  Caller to free the buffer.\r
+\r
+  @param[in] NameString            original name string\r
+\r
+  @return                          the new filename with .efi as the extension.\r
+**/\r
+CHAR16 *\r
+EFIAPI\r
+GetExecuatableFileName (\r
+  IN CONST CHAR16    *NameString\r
+  )\r
+{\r
+  CHAR16  *Buffer;\r
+  CHAR16  *SuffixStr;\r
+  if (NameString == NULL) {\r
+    return (NULL);\r
+  }\r
+\r
+  //\r
+  // Fix the file name\r
+  //\r
+  if (StrnCmp(NameString+StrLen(NameString)-StrLen(L".efi"), L".efi", StrLen(L".efi"))==0) {\r
+    Buffer = AllocateCopyPool(StrSize(NameString), NameString);\r
+  } else if (StrnCmp(NameString+StrLen(NameString)-StrLen(L".man"), L".man", StrLen(L".man"))==0) {\r
+    Buffer = AllocateCopyPool(StrSize(NameString), NameString);\r
+    if (Buffer != NULL) {\r
+      SuffixStr = Buffer+StrLen(Buffer)-StrLen(L".man");\r
+      StrnCpyS (SuffixStr, StrSize(L".man")/sizeof(CHAR16), L".efi", StrLen(L".efi"));\r
+    }\r
+  } else {\r
+    Buffer = AllocateZeroPool(StrSize(NameString) + StrLen(L".efi")*sizeof(CHAR16));\r
+    if (Buffer != NULL) {\r
+      StrnCpyS( Buffer,\r
+                (StrSize(NameString) + StrLen(L".efi")*sizeof(CHAR16))/sizeof(CHAR16),\r
+                NameString,\r
+                StrLen(NameString)\r
+                );\r
+      StrnCatS( Buffer,\r
+                (StrSize(NameString) + StrLen(L".efi")*sizeof(CHAR16))/sizeof(CHAR16),\r
+                L".efi",\r
+                StrLen(L".efi")\r
+                );\r
+    }\r
+  }\r
+  return (Buffer);\r
+\r
+}\r
+\r
 /**\r
   Verifies that the filename has .MAN on the end.\r
 \r
@@ -381,7 +465,7 @@ ManFileFindSections(
 \r
   Upon a sucessful return the caller is responsible to free the memory in *BriefDesc\r
 \r
-  @param[in] Handle             Buffer to read from\r
+  @param[in] Buffer             Buffer to read from\r
   @param[in] Command            name of command's section to find\r
   @param[in] BriefDesc          pointer to pointer to string where description goes.\r
   @param[in] BriefSize          pointer to size of allocated BriefDesc\r
@@ -404,6 +488,7 @@ ManBufferFindTitleSection(
   CHAR16        *TitleEnd;\r
   CHAR16        *CurrentLocation;\r
   UINTN         TitleLength;\r
+  UINTN         Start;\r
   CONST CHAR16  StartString[] = L".TH ";\r
   CONST CHAR16  EndString[]   = L" 0 ";\r
 \r
@@ -416,16 +501,27 @@ ManBufferFindTitleSection(
 \r
   Status    = EFI_SUCCESS;\r
 \r
+  //\r
+  // Do not pass any leading path information that may be present to IsTitleHeader().\r
+  //\r
+  Start = StrLen(Command);\r
+  while ((Start != 0)\r
+         && (*(Command + Start - 1) != L'\\')\r
+         && (*(Command + Start - 1) != L'/')\r
+         && (*(Command + Start - 1) != L':')) {\r
+    --Start;\r
+  }\r
+\r
   //\r
   // more characters for StartString and EndString\r
   //\r
-  TitleLength = StrSize(Command) + (StrLen(StartString) + StrLen(EndString)) * sizeof(CHAR16);\r
+  TitleLength = StrSize(Command + Start) + (StrLen(StartString) + StrLen(EndString)) * sizeof(CHAR16);\r
   TitleString = AllocateZeroPool(TitleLength);\r
   if (TitleString == NULL) {\r
     return (EFI_OUT_OF_RESOURCES);\r
   }\r
   StrCpyS(TitleString, TitleLength/sizeof(CHAR16), StartString);\r
-  StrCatS(TitleString, TitleLength/sizeof(CHAR16), Command);\r
+  StrCatS(TitleString, TitleLength/sizeof(CHAR16), Command + Start);\r
   StrCatS(TitleString, TitleLength/sizeof(CHAR16), EndString);\r
 \r
   CurrentLocation = StrStr(*Buffer, TitleString);\r
@@ -720,13 +816,19 @@ ProcessManFile(
 {\r
   CHAR16            *TempString;\r
   SHELL_FILE_HANDLE FileHandle;\r
+  EFI_HANDLE        CmdFileImgHandle;\r
   EFI_STATUS        Status;\r
   UINTN             HelpSize;\r
   UINTN             BriefSize;\r
+  UINTN             StringIdWalker;\r
   BOOLEAN           Ascii;\r
   CHAR16            *TempString2;\r
-  EFI_DEVICE_PATH_PROTOCOL  *FileDevPath;\r
-  EFI_DEVICE_PATH_PROTOCOL  *DevPath;\r
+  CHAR16            *CmdFileName;\r
+  CHAR16            *CmdFilePathName;\r
+  CHAR16            *StringBuff;\r
+  EFI_DEVICE_PATH_PROTOCOL      *FileDevPath;\r
+  EFI_DEVICE_PATH_PROTOCOL      *DevPath;\r
+  EFI_HII_PACKAGE_LIST_HEADER   *PackageListHeader;\r
 \r
   if ( ManFileName == NULL\r
     || Command     == NULL\r
@@ -735,10 +837,19 @@ ProcessManFile(
     return (EFI_INVALID_PARAMETER);\r
   }\r
 \r
-  HelpSize    = 0;\r
-  BriefSize   = 0;\r
-  TempString  = NULL;\r
-  Ascii       = FALSE;\r
+  HelpSize          = 0;\r
+  BriefSize         = 0;\r
+  StringIdWalker    = 0;\r
+  TempString        = NULL;\r
+  Ascii             = FALSE;\r
+  CmdFileName       = NULL;\r
+  CmdFilePathName   = NULL;\r
+  CmdFileImgHandle  = NULL;\r
+  StringBuff        = NULL;\r
+  PackageListHeader = NULL;\r
+  FileDevPath       = NULL;\r
+  DevPath           = NULL;\r
+\r
   //\r
   // See if it's in HII first\r
   //\r
@@ -750,6 +861,9 @@ ProcessManFile(
       Status = ManBufferFindSections(TempString2, Sections, HelpText, &HelpSize);\r
     }\r
   } else {\r
+    //\r
+    // If the image is a external app, check .MAN file first.\r
+    //\r
     FileHandle    = NULL;\r
     TempString  = GetManFileName(ManFileName);\r
     if (TempString == NULL) {\r
@@ -761,8 +875,8 @@ ProcessManFile(
       FileDevPath = FileDevicePath(NULL, TempString);\r
       DevPath = AppendDevicePath (ShellInfoObject.ImageDevPath, FileDevPath);\r
       Status = InternalOpenFileDevicePath(DevPath, &FileHandle, EFI_FILE_MODE_READ, 0);\r
-      FreePool(FileDevPath);\r
-      FreePool(DevPath);\r
+      SHELL_FREE_NON_NULL(FileDevPath);\r
+      SHELL_FREE_NON_NULL(DevPath);\r
     }\r
 \r
     if (!EFI_ERROR(Status)) {\r
@@ -773,13 +887,127 @@ ProcessManFile(
         Status = ManFileFindSections(FileHandle, Sections, HelpText, &HelpSize, Ascii);\r
       }\r
       ShellInfoObject.NewEfiShellProtocol->CloseFile(FileHandle);\r
-    } else {\r
+      if (!EFI_ERROR(Status)) {\r
+        //\r
+        // Get help text from .MAN file success.\r
+        //\r
+        goto Done;\r
+      }\r
+    }\r
+\r
+    //\r
+    // Load the app image to check  EFI_HII_PACKAGE_LIST_PROTOCOL.\r
+    //\r
+    CmdFileName     = GetExecuatableFileName(TempString);\r
+    if (CmdFileName == NULL) {\r
+      Status = EFI_OUT_OF_RESOURCES;\r
+      goto Done;\r
+    }\r
+    //\r
+    // If the file in CWD then use the file name, else use the full\r
+    // path name.\r
+    //\r
+    CmdFilePathName = ShellFindFilePath(CmdFileName);\r
+    if (CmdFilePathName == NULL) {\r
+      Status = EFI_NOT_FOUND;\r
+      goto Done;\r
+    }\r
+    DevPath = ShellInfoObject.NewEfiShellProtocol->GetDevicePathFromFilePath(CmdFilePathName);\r
+    Status      = gBS->LoadImage(FALSE, gImageHandle, DevPath, NULL, 0, &CmdFileImgHandle);\r
+    if(EFI_ERROR(Status)) {\r
       *HelpText = NULL;\r
+      goto Done;\r
+    }\r
+    Status = gBS->OpenProtocol(\r
+                    CmdFileImgHandle,\r
+                    &gEfiHiiPackageListProtocolGuid,\r
+                    (VOID**)&PackageListHeader,\r
+                    gImageHandle,\r
+                    NULL,\r
+                    EFI_OPEN_PROTOCOL_GET_PROTOCOL\r
+                    );\r
+    if(EFI_ERROR(Status)) {\r
+      *HelpText = NULL;\r
+      goto Done;\r
+    }\r
+\r
+    //\r
+    // If get package list on image handle, install it on HiiDatabase.\r
+    //\r
+    Status = gBS->InstallProtocolInterface (\r
+                    &mShellManDriverHandle,\r
+                    &gEfiDevicePathProtocolGuid,\r
+                    EFI_NATIVE_INTERFACE,\r
+                    &mShellManHiiDevicePath\r
+                    );\r
+    if (EFI_ERROR(Status)) {\r
+      goto Done;\r
+    }\r
+\r
+    Status = gHiiDatabase->NewPackageList (\r
+                            gHiiDatabase,\r
+                            PackageListHeader,\r
+                            mShellManDriverHandle,\r
+                            &mShellManHiiHandle\r
+                            );\r
+    if (EFI_ERROR (Status)) {\r
+      goto Done;\r
     }\r
+\r
+    StringIdWalker = 1;\r
+    do {\r
+        SHELL_FREE_NON_NULL(StringBuff);\r
+        if (BriefDesc != NULL) {\r
+          SHELL_FREE_NON_NULL(*BriefDesc);\r
+        }\r
+        StringBuff = HiiGetString (mShellManHiiHandle, (EFI_STRING_ID)StringIdWalker, NULL);\r
+        if (StringBuff == NULL) {\r
+          Status = EFI_NOT_FOUND;\r
+          goto Done;\r
+        }\r
+        TempString2 = StringBuff;\r
+        Status = ManBufferFindTitleSection(&TempString2, Command, BriefDesc, &BriefSize);\r
+        if (!EFI_ERROR(Status) && HelpText != NULL){\r
+          Status = ManBufferFindSections(TempString2, Sections, HelpText, &HelpSize);\r
+        }\r
+        if (!EFI_ERROR(Status)){\r
+          //\r
+          // Found what we need and return\r
+          //\r
+          goto Done;\r
+        }\r
+\r
+        StringIdWalker += 1;\r
+    } while (StringIdWalker < 0xFFFF && StringBuff != NULL);\r
+\r
   }\r
-  if (TempString != NULL) {\r
-    FreePool(TempString);\r
+\r
+Done:\r
+  if (mShellManDriverHandle != NULL) {\r
+    gBS->UninstallProtocolInterface (\r
+            mShellManDriverHandle,\r
+            &gEfiDevicePathProtocolGuid,\r
+            &mShellManHiiDevicePath\r
+           );\r
+    mShellManDriverHandle = NULL;\r
+  }\r
+\r
+  if (mShellManHiiHandle != NULL) {\r
+    HiiRemovePackages (mShellManHiiHandle);\r
+    mShellManHiiHandle = NULL;\r
   }\r
 \r
+  if (CmdFileImgHandle != NULL) {\r
+    Status = gBS->UnloadImage (CmdFileImgHandle);\r
+  }\r
+\r
+  SHELL_FREE_NON_NULL(StringBuff);\r
+  SHELL_FREE_NON_NULL(TempString);\r
+  SHELL_FREE_NON_NULL(CmdFileName);\r
+  SHELL_FREE_NON_NULL(CmdFilePathName);\r
+  SHELL_FREE_NON_NULL(FileDevPath);\r
+  SHELL_FREE_NON_NULL(DevPath);\r
+\r
   return (Status);\r
 }\r
+\r