Help.c@ 99396

Last change on this file since 99396 was 80721, checked in by vboxsync, 6 years ago
Devices/EFI/FirmwareNew: Start upgrade process to edk2-stable201908 (compiles on Windows and works to some extent), bugref:4643
Property svn:eol-style set to `native`
File size: 15.5 KB

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

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/ShellPkg/Library/UefiShellLevel3CommandsLib/Help.c@ 99396

Download in other formats: