ShellPkg/Library/UefiShellLevel3CommandsLib/Help.c

   1 /** @file
   2   Main file for Help shell level 3 function.
   3
   4   Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved. <BR>
   5   Copyright (c) 2014, ARM Limited. All rights reserved. <BR>
   6   (C) Copyright 2015 Hewlett-Packard Development Company, L.P.<BR>
   7
   8   This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #include "UefiShellLevel3CommandsLib.h"
  19
  20 #include <Library/ShellLib.h>
  21 #include <Library/HandleParsingLib.h>
  22
  23 #include <Protocol/EfiShellDynamicCommand.h>
  24
  25 /**
  26    function to insert string items into a list in the correct alphabetical place
  27
  28    the resultant list is a double NULL terminated list of NULL terminated strings.
  29
  30    upon successful return the memory must be caller freed (unless passed back in
  31    via a loop where it will get reallocated).
  32
  33    @param[in,out] DestList    double pointer to the list. may be NULL.
  34    @param[in,out] DestSize    pointer to the size of list. may be 0, if DestList is NULL.
  35    @param[in]     Item        the item to insert.
  36
  37    @retval EFI_SUCCESS        the operation was successful.
  38 **/
  39 EFI_STATUS
  40 EFIAPI
  41 LexicalInsertIntoList(
  42   IN OUT   CHAR16 **DestList,
  43   IN OUT   UINTN  *DestSize,
  44   IN CONST CHAR16 *Item
  45   )
  46 {
  47   CHAR16                              *NewList;
  48   INTN                                LexicalMatchValue;
  49   CHAR16                              *LexicalSpot;
  50   UINTN                               SizeOfAddedNameInBytes;
  51
  52   //
  53   // If there are none, then just return with success
  54   //
  55   if (Item == NULL || *Item == CHAR_NULL || StrLen(Item)==0) {
  56     return (EFI_SUCCESS);
  57   }
  58
  59   NewList = *DestList;
  60
  61   SizeOfAddedNameInBytes = StrSize(Item);
  62   NewList = ReallocatePool(*DestSize, (*DestSize) + SizeOfAddedNameInBytes, NewList);
  63   (*DestSize) = (*DestSize) + SizeOfAddedNameInBytes;
  64
  65   //
  66   // Find the correct spot in the list
  67   //
  68   for (LexicalSpot = NewList
  69     ; LexicalSpot != NULL && LexicalSpot < NewList + (*DestSize)
  70     ; LexicalSpot += StrLen(LexicalSpot) + 1
  71     ) {
  72     //
  73     // Get Lexical Comparison Value between PrevCommand and Command list entry
  74     //
  75     LexicalMatchValue = gUnicodeCollation->StriColl (
  76                                               gUnicodeCollation,
  77                                               (CHAR16 *)LexicalSpot,
  78                                               (CHAR16 *)Item
  79                                               );
  80     //
  81     // The new item goes before this one.
  82     //
  83     if (LexicalMatchValue > 0 || StrLen(LexicalSpot) == 0) {
  84       if (StrLen(LexicalSpot) != 0) {
  85         //
  86         // Move this and all other items out of the way
  87         //
  88         CopyMem(
  89           LexicalSpot + (SizeOfAddedNameInBytes/sizeof(CHAR16)),
  90           LexicalSpot,
  91           (*DestSize) - SizeOfAddedNameInBytes - ((LexicalSpot - NewList) * sizeof(CHAR16))
  92           );
  93       }
  94
  95       //
  96       // Stick this one in place
  97       //
  98       StrCpyS(LexicalSpot, SizeOfAddedNameInBytes/sizeof(CHAR16), Item);
  99       break;
 100     }
 101   }
 102
 103   *DestList = NewList;
 104   return (EFI_SUCCESS);
 105 }
 106
 107 /**
 108    function to add each command name from the linked list to the string list.
 109
 110    the resultant list is a double NULL terminated list of NULL terminated strings.
 111
 112    @param[in,out] DestList    double pointer to the list. may be NULL.
 113    @param[in,out] DestSize    pointer to the size of list. may be 0, if DestList is NULL.
 114    @param[in]     SourceList  the double linked list of commands.
 115
 116    @retval EFI_SUCCESS        the operation was successful.
 117 **/
 118 EFI_STATUS
 119 EFIAPI
 120 CopyListOfCommandNames(
 121   IN OUT   CHAR16       **DestList,
 122   IN OUT   UINTN        *DestSize,
 123   IN CONST COMMAND_LIST *SourceList
 124   )
 125 {
 126   CONST COMMAND_LIST  *Node;
 127
 128   for ( Node = (COMMAND_LIST*)GetFirstNode(&SourceList->Link)
 129       ; SourceList != NULL && !IsListEmpty(&SourceList->Link) && !IsNull(&SourceList->Link, &Node->Link)
 130       ; Node = (COMMAND_LIST*)GetNextNode(&SourceList->Link, &Node->Link)
 131     ) {
 132     LexicalInsertIntoList(DestList, DestSize, Node->CommandString);
 133   }
 134   return (EFI_SUCCESS);
 135 }
 136
 137 /**
 138    function to add each dynamic command name to the string list.
 139
 140    the resultant list is a double NULL terminated list of NULL terminated strings.
 141
 142    @param[in,out] DestList    double pointer to the list. may be NULL.
 143    @param[in,out] DestSize    pointer to the size of list. may be 0, if DestList is NULL.
 144
 145    @retval EFI_SUCCESS        the operation was successful.
 146    @return an error from HandleProtocol
 147 **/
 148 STATIC
 149 EFI_STATUS
 150 EFIAPI
 151 CopyListOfCommandNamesWithDynamic(
 152   IN OUT  CHAR16** DestList,
 153   IN OUT  UINTN    *DestSize
 154   )
 155 {
 156   EFI_HANDLE                          *CommandHandleList;
 157   CONST EFI_HANDLE                    *NextCommand;
 158   EFI_SHELL_DYNAMIC_COMMAND_PROTOCOL  *DynamicCommand;
 159   EFI_STATUS                          Status;
 160
 161   CommandHandleList = GetHandleListByProtocol(&gEfiShellDynamicCommandProtocolGuid);
 162
 163   //
 164   // If there are none, then just return with success
 165   //
 166   if (CommandHandleList == NULL) {
 167     return (EFI_SUCCESS);
 168   }
 169
 170   Status = EFI_SUCCESS;
 171
 172   //
 173   // Append those to the list.
 174   //
 175   for (NextCommand = CommandHandleList ; *NextCommand != NULL && !EFI_ERROR(Status) ; NextCommand++) {
 176     Status = gBS->HandleProtocol(
 177       *NextCommand,
 178       &gEfiShellDynamicCommandProtocolGuid,
 179       (VOID **)&DynamicCommand
 180       );
 181
 182     if (EFI_ERROR(Status)) {
 183       continue;
 184     }
 185
 186     Status = LexicalInsertIntoList(DestList, DestSize, DynamicCommand->CommandName);
 187   }
 188
 189   SHELL_FREE_NON_NULL(CommandHandleList);
 190   return (Status);
 191 }
 192
 193
 194 /**
 195   Attempt to print help from a dynamically added command.
 196
 197   @param[in]  CommandToGetHelpOn  The unicode name of the command that help is
 198                                   requested on.
 199   @param[in]  SectionToGetHelpOn  Pointer to the section specifier(s).
 200   @param[in]  PrintCommandText    Print the command followed by the help content
 201                                   or just help.
 202
 203   @retval EFI_SUCCESS             The help was displayed
 204   @retval EFI_NOT_FOUND           The command name could not be found
 205   @retval EFI_DEVICE_ERROR        The help data format was incorrect.
 206 **/
 207 EFI_STATUS
 208 EFIAPI
 209 PrintDynamicCommandHelp(
 210   IN CONST CHAR16  *CommandToGetHelpOn,
 211   IN CONST CHAR16  *SectionToGetHelpOn,
 212   IN BOOLEAN       PrintCommandText
 213  )
 214 {
 215   EFI_STATUS                          Status;
 216   BOOLEAN                             Found;
 217   EFI_HANDLE                          *CommandHandleList;
 218   EFI_HANDLE                          *NextCommand;
 219   EFI_SHELL_DYNAMIC_COMMAND_PROTOCOL  *DynamicCommand;
 220
 221   Status = EFI_NOT_FOUND;
 222   Found = FALSE;
 223   CommandHandleList = NULL;
 224
 225   CommandHandleList = GetHandleListByProtocol(&gEfiShellDynamicCommandProtocolGuid);
 226
 227   if (CommandHandleList == NULL) {
 228     //
 229     // not found or out of resources
 230     //
 231     return Status;
 232   }
 233
 234   for (NextCommand = CommandHandleList; *NextCommand != NULL; NextCommand++) {
 235     Status = gBS->HandleProtocol(
 236       *NextCommand,
 237       &gEfiShellDynamicCommandProtocolGuid,
 238       (VOID **)&DynamicCommand
 239       );
 240
 241     if (EFI_ERROR(Status)) {
 242       continue;
 243     }
 244
 245     //
 246     // Check execution break flag when printing multiple command help information.
 247     //
 248     if (ShellGetExecutionBreakFlag ()) {
 249       break;
 250     }
 251
 252     if ((gUnicodeCollation->MetaiMatch (gUnicodeCollation, (CHAR16 *)DynamicCommand->CommandName, (CHAR16*)CommandToGetHelpOn)) ||
 253       (gEfiShellProtocol->GetAlias (CommandToGetHelpOn, NULL) != NULL && (gUnicodeCollation->MetaiMatch (gUnicodeCollation, (CHAR16 *)DynamicCommand->CommandName, (CHAR16*)(gEfiShellProtocol->GetAlias(CommandToGetHelpOn, NULL)))))) {
 254       // Print as Shell Help if in ManPage format.
 255       Status = ShellPrintHelp (DynamicCommand->CommandName, SectionToGetHelpOn,
 256                               PrintCommandText);
 257       if (Status == EFI_DEVICE_ERROR) {
 258         ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_INV),
 259                         gShellLevel3HiiHandle, DynamicCommand->CommandName);
 260       } else if (EFI_ERROR(Status)) {
 261         ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_NF),
 262                         gShellLevel3HiiHandle, DynamicCommand->CommandName);
 263       } else {
 264         Found = TRUE;
 265       }
 266     }
 267   }
 268
 269   SHELL_FREE_NON_NULL(CommandHandleList);
 270
 271   return (Found ? EFI_SUCCESS : Status);
 272
 273 }
 274
 275 STATIC CONST SHELL_PARAM_ITEM ParamList[] = {
 276   {L"-usage", TypeFlag},
 277   {L"-section", TypeMaxValue},
 278   {L"-verbose", TypeFlag},
 279   {L"-v", TypeFlag},
 280   {NULL, TypeMax}
 281   };
 282
 283 /**
 284   Function for 'help' command.
 285
 286   @param[in] ImageHandle  Handle to the Image (NULL if Internal).
 287   @param[in] SystemTable  Pointer to the System Table (NULL if Internal).
 288 **/
 289 SHELL_STATUS
 290 EFIAPI
 291 ShellCommandRunHelp (
 292   IN EFI_HANDLE        ImageHandle,
 293   IN EFI_SYSTEM_TABLE  *SystemTable
 294   )
 295 {
 296   EFI_STATUS          Status;
 297   LIST_ENTRY          *Package;
 298   CHAR16              *ProblemParam;
 299   SHELL_STATUS        ShellStatus;
 300   CHAR16              *SortedCommandList;
 301   CONST CHAR16        *CurrentCommand;
 302   CHAR16              *CommandToGetHelpOn;
 303   CHAR16              *SectionToGetHelpOn;
 304   CHAR16              *HiiString;
 305   BOOLEAN             Found;
 306   BOOLEAN             PrintCommandText;
 307   UINTN               SortedCommandListSize;
 308
 309   PrintCommandText    = TRUE;
 310   ProblemParam        = NULL;
 311   ShellStatus         = SHELL_SUCCESS;
 312   CommandToGetHelpOn  = NULL;
 313   SectionToGetHelpOn  = NULL;
 314   SortedCommandList   = NULL;
 315   Found               = FALSE;
 316
 317   //
 318   // initialize the shell lib (we must be in non-auto-init...)
 319   //
 320   Status = ShellInitialize();
 321   ASSERT_EFI_ERROR(Status);
 322
 323   Status = CommandInit();
 324   ASSERT_EFI_ERROR(Status);
 325
 326   //
 327   // parse the command line
 328   //
 329   Status = ShellCommandLineParse (ParamList, &Package, &ProblemParam, TRUE);
 330   if (EFI_ERROR(Status)) {
 331     if (Status == EFI_VOLUME_CORRUPTED && ProblemParam != NULL) {
 332       ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_GEN_PROBLEM), gShellLevel3HiiHandle, L"help", ProblemParam);
 333       FreePool(ProblemParam);
 334       ShellStatus = SHELL_INVALID_PARAMETER;
 335     } else {
 336       ASSERT(FALSE);
 337     }
 338   } else {
 339     //
 340     // Check for conflicting parameters.
 341     //
 342     if (ShellCommandLineGetFlag(Package, L"-usage")
 343       &&ShellCommandLineGetFlag(Package, L"-section")
 344       &&(ShellCommandLineGetFlag(Package, L"-verbose") || ShellCommandLineGetFlag(Package, L"-v"))
 345      ){
 346       ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_GEN_PARAM_CON), gShellLevel3HiiHandle, L"help");
 347       ShellStatus = SHELL_INVALID_PARAMETER;
 348     } else if (ShellCommandLineGetRawValue(Package, 2) != NULL) {
 349       ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_GEN_TOO_MANY), gShellLevel3HiiHandle, L"help");
 350       ShellStatus = SHELL_INVALID_PARAMETER;
 351     } else {
 352       //
 353       // Get the command name we are getting help on
 354       //
 355       ASSERT(CommandToGetHelpOn == NULL);
 356       StrnCatGrow(&CommandToGetHelpOn, NULL, ShellCommandLineGetRawValue(Package, 1), 0);
 357       if (CommandToGetHelpOn == NULL && ShellCommandLineGetFlag(Package, L"-?")) {
 358         //
 359         // If we dont have a command and we got a simple -?
 360         // we are looking for help on help command.
 361         //
 362         StrnCatGrow(&CommandToGetHelpOn, NULL, L"help", 0);
 363       }
 364
 365       if (CommandToGetHelpOn == NULL) {
 366         StrnCatGrow(&CommandToGetHelpOn, NULL, L"*", 0);
 367         ASSERT(SectionToGetHelpOn == NULL);
 368         StrnCatGrow(&SectionToGetHelpOn, NULL, L"NAME", 0);
 369       } else {
 370         PrintCommandText = FALSE;
 371         ASSERT(SectionToGetHelpOn == NULL);
 372         //
 373         // Get the section name for the given command name
 374         //
 375         if (ShellCommandLineGetFlag(Package, L"-section")) {
 376           StrnCatGrow(&SectionToGetHelpOn, NULL, ShellCommandLineGetValue(Package, L"-section"), 0);
 377         } else if (ShellCommandLineGetFlag(Package, L"-usage")) {
 378           StrnCatGrow(&SectionToGetHelpOn, NULL, L"NAME,SYNOPSIS", 0);
 379         } else if (ShellCommandLineGetFlag(Package, L"-verbose") || ShellCommandLineGetFlag(Package, L"-v")) {
 380         } else {
 381           //
 382           // The output of help <command> will display NAME, SYNOPSIS, OPTIONS, DESCRIPTION, and EXAMPLES sections.
 383           //
 384           StrnCatGrow (&SectionToGetHelpOn, NULL, L"NAME,SYNOPSIS,OPTIONS,DESCRIPTION,EXAMPLES", 0);
 385         }
 386       }
 387
 388       if (gUnicodeCollation->StriColl(gUnicodeCollation, CommandToGetHelpOn, L"special") == 0) {
 389         //
 390         // we need info on the special characters
 391         //
 392         ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_SC_HEADER), gShellLevel3HiiHandle);
 393         HiiString = HiiGetString(gShellLevel3HiiHandle, STRING_TOKEN(STR_HELP_SC_DATA), NULL);
 394         ShellPrintEx(-1, -1, L"%s", HiiString);
 395         FreePool(HiiString);
 396         Found = TRUE;
 397       } else {
 398         SortedCommandList = NULL;
 399         SortedCommandListSize = 0;
 400         CopyListOfCommandNames(&SortedCommandList, &SortedCommandListSize, ShellCommandGetCommandList(TRUE));
 401         CopyListOfCommandNamesWithDynamic(&SortedCommandList, &SortedCommandListSize);
 402
 403         for (CurrentCommand = SortedCommandList
 404           ; CurrentCommand != NULL && *CurrentCommand != CHAR_NULL && CurrentCommand < SortedCommandList + SortedCommandListSize/sizeof(CHAR16)
 405           ; CurrentCommand += StrLen(CurrentCommand) + 1
 406           ) {
 407           //
 408           // Checking execution break flag when print multiple command help information.
 409           //
 410           if (ShellGetExecutionBreakFlag ()) {
 411             break;
 412           }
 413
 414           if ((gUnicodeCollation->MetaiMatch(gUnicodeCollation, (CHAR16*)CurrentCommand, CommandToGetHelpOn)) ||
 415              (gEfiShellProtocol->GetAlias(CommandToGetHelpOn, NULL) != NULL && (gUnicodeCollation->MetaiMatch(gUnicodeCollation, (CHAR16*)CurrentCommand, (CHAR16*)(gEfiShellProtocol->GetAlias(CommandToGetHelpOn, NULL)))))) {
 416             //
 417             // We have a command to look for help on.
 418             //
 419             Status = ShellPrintHelp(CurrentCommand, SectionToGetHelpOn, PrintCommandText);
 420             if (EFI_ERROR(Status)) {
 421               //
 422               // now try to match against the dynamic command list and print help
 423               //
 424               Status = PrintDynamicCommandHelp (CurrentCommand, SectionToGetHelpOn, PrintCommandText);
 425             }
 426             if (Status == EFI_DEVICE_ERROR) {
 427                 ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_INV), gShellLevel3HiiHandle, CurrentCommand);
 428             } else if (EFI_ERROR(Status)) {
 429                 ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_NF), gShellLevel3HiiHandle, CurrentCommand);
 430             } else {
 431                 Found = TRUE;
 432             }
 433           }
 434         }
 435
 436         //
 437         // Search the .man file for Shell applications (Shell external commands).
 438         //
 439         if (!Found) {
 440           Status = ShellPrintHelp(CommandToGetHelpOn, SectionToGetHelpOn, FALSE);
 441           if (Status == EFI_DEVICE_ERROR) {
 442               ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_INV), gShellLevel3HiiHandle, CommandToGetHelpOn);
 443           } else if (EFI_ERROR(Status)) {
 444               ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_NF), gShellLevel3HiiHandle, CommandToGetHelpOn);
 445           } else {
 446             Found = TRUE;
 447           }
 448         }
 449       }
 450
 451       if (!Found) {
 452         ShellStatus = SHELL_NOT_FOUND;
 453       }
 454
 455       //
 456       // free the command line package
 457       //
 458       ShellCommandLineFreeVarList (Package);
 459     }
 460   }
 461
 462   if (CommandToGetHelpOn != NULL && StrCmp(CommandToGetHelpOn, L"*") == 0){
 463     //
 464     // If '*' then the command entered was 'Help' without qualifiers, This footer
 465     // provides additional info on help switches
 466     //
 467     ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_FOOTER), gShellLevel3HiiHandle);
 468   }
 469   if (CommandToGetHelpOn != NULL) {
 470     FreePool(CommandToGetHelpOn);
 471   }
 472   if (SectionToGetHelpOn != NULL) {
 473     FreePool(SectionToGetHelpOn);
 474   }
 475   SHELL_FREE_NON_NULL(SortedCommandList);
 476
 477   return (ShellStatus);
 478 }