4 # Copyright 2014 Apple Inc. All righes reserved.
6 # SPDX-License-Identifier: BSD-2-Clause-Patent
20 def EFI_GUID_TypeSummary (valobj
,internal_dict
):
21 """ Type summary for EFI GUID, print C Name if known
29 SBError
= lldb
.SBError()
31 data1_val
= valobj
.GetChildMemberWithName('Data1')
32 data1
= data1_val
.GetValueAsUnsigned(0)
33 data2_val
= valobj
.GetChildMemberWithName('Data2')
34 data2
= data2_val
.GetValueAsUnsigned(0)
35 data3_val
= valobj
.GetChildMemberWithName('Data3')
36 data3
= data3_val
.GetValueAsUnsigned(0)
37 str = "%x-%x-%x-" % (data1
, data2
, data3
)
39 data4_val
= valobj
.GetChildMemberWithName('Data4')
40 for i
in range (data4_val
.num_children
):
43 str += "%02x" % data4_val
.GetChildAtIndex(i
).data
.GetUnsignedInt8(SBError
, 0)
45 return guid_dict
.get (str.upper(), '')
50 (0x8000000000000000 |
1): "Load Error",
51 (0x8000000000000000 |
2): "Invalid Parameter",
52 (0x8000000000000000 |
3): "Unsupported",
53 (0x8000000000000000 |
4): "Bad Buffer Size",
54 (0x8000000000000000 |
5): "Buffer Too Small",
55 (0x8000000000000000 |
6): "Not Ready",
56 (0x8000000000000000 |
7): "Device Error",
57 (0x8000000000000000 |
8): "Write Protected",
58 (0x8000000000000000 |
9): "Out of Resources",
59 (0x8000000000000000 |
10): "Volume Corrupt",
60 (0x8000000000000000 |
11): "Volume Full",
61 (0x8000000000000000 |
12): "No Media",
62 (0x8000000000000000 |
13): "Media changed",
63 (0x8000000000000000 |
14): "Not Found",
64 (0x8000000000000000 |
15): "Access Denied",
65 (0x8000000000000000 |
16): "No Response",
66 (0x8000000000000000 |
17): "No mapping",
67 (0x8000000000000000 |
18): "Time out",
68 (0x8000000000000000 |
19): "Not started",
69 (0x8000000000000000 |
20): "Already started",
70 (0x8000000000000000 |
21): "Aborted",
71 (0x8000000000000000 |
22): "ICMP Error",
72 (0x8000000000000000 |
23): "TFTP Error",
73 (0x8000000000000000 |
24): "Protocol Error",
76 1 : "Warning Unknown Glyph",
77 2 : "Warning Delete Failure",
78 3 : "Warning Write Failure",
79 4 : "Warning Buffer Too Small",
81 (0x80000000 |
1): "Load Error",
82 (0x80000000 |
2): "Invalid Parameter",
83 (0x80000000 |
3): "Unsupported",
84 (0x80000000 |
4): "Bad Buffer Size",
85 (0x80000000 |
5): "Buffer Too Small",
86 (0x80000000 |
6): "Not Ready",
87 (0x80000000 |
7): "Device Error",
88 (0x80000000 |
8): "Write Protected",
89 (0x80000000 |
9): "Out of Resources",
90 (0x80000000 |
10): "Volume Corrupt",
91 (0x80000000 |
11): "Volume Full",
92 (0x80000000 |
12): "No Media",
93 (0x80000000 |
13): "Media changed",
94 (0x80000000 |
14): "Not Found",
95 (0x80000000 |
15): "Access Denied",
96 (0x80000000 |
16): "No Response",
97 (0x80000000 |
17): "No mapping",
98 (0x80000000 |
18): "Time out",
99 (0x80000000 |
19): "Not started",
100 (0x80000000 |
20): "Already started",
101 (0x80000000 |
21): "Aborted",
102 (0x80000000 |
22): "ICMP Error",
103 (0x80000000 |
23): "TFTP Error",
104 (0x80000000 |
24): "Protocol Error",
107 def EFI_STATUS_TypeSummary (valobj
,internal_dict
):
109 # Return summary string for EFI_STATUS from dictionary
111 Status
= valobj
.GetValueAsUnsigned(0)
112 return EFI_STATUS_Dict
.get (Status
, '')
115 def EFI_TPL_TypeSummary (valobj
,internal_dict
):
120 if valobj
.TypeIsPointerType():
123 Tpl
= valobj
.GetValueAsUnsigned(0)
127 Str
= "TPL_DRIVER (Obsolete Concept in edk2)"
129 Str
= "TPL_APPLICATION"
131 Str
+= " + " + "%d" % (Tpl
- 4)
135 Str
+= " + " + "%d" % (Tpl
- 4)
139 Str
+= " + " + "%d" % (Tpl
- 4)
141 Str
= "TPL_HIGH_LEVEL"
148 def CHAR16_TypeSummary (valobj
,internal_dict
):
150 # Display EFI CHAR16 'unsigned short' as string
152 SBError
= lldb
.SBError()
154 if valobj
.TypeIsPointerType():
155 if valobj
.GetValueAsUnsigned () == 0:
158 # CHAR16 * max string size 1024
159 for i
in range (1024):
160 Char
= valobj
.GetPointeeData(i
,1).GetUnsignedInt16(SBError
, 0)
161 if SBError
.fail
or Char
== 0:
164 Str
= 'L"' + Str
+ '"'
165 return Str
.encode ('utf-8', 'replace')
167 if valobj
.num_children
== 0:
169 if chr (valobj
.unsigned
) in string
.printable
:
170 Str
= "L'" + unichr (valobj
.unsigned
) + "'"
171 return Str
.encode ('utf-8', 'replace')
174 for i
in range (valobj
.num_children
):
175 Char
= valobj
.GetChildAtIndex(i
).data
.GetUnsignedInt16(SBError
, 0)
179 Str
= 'L"' + Str
+ '"'
180 return Str
.encode ('utf-8', 'replace')
184 def CHAR8_TypeSummary (valobj
,internal_dict
):
186 # Display EFI CHAR8 'signed char' as string
187 # unichr() is used as a junk string can produce an error message like this:
188 # UnicodeEncodeError: 'ascii' codec can't encode character u'\x90' in position 1: ordinal not in range(128)
190 SBError
= lldb
.SBError()
192 if valobj
.TypeIsPointerType():
193 if valobj
.GetValueAsUnsigned () == 0:
196 # CHAR8 * max string size 1024
197 for i
in range (1024):
198 Char
= valobj
.GetPointeeData(i
,1).GetUnsignedInt8(SBError
, 0)
199 if SBError
.fail
or Char
== 0:
202 Str
= '"' + Str
+ '"'
203 return Str
.encode ('utf-8', 'replace')
205 if valobj
.num_children
== 0:
207 if chr (valobj
.unsigned
) in string
.printable
:
208 Str
= '"' + unichr (valobj
.unsigned
) + '"'
209 return Str
.encode ('utf-8', 'replace')
212 for i
in range (valobj
.num_children
):
213 Char
= valobj
.GetChildAtIndex(i
).data
.GetUnsignedInt8(SBError
, 0)
217 Str
= '"' + Str
+ '"'
218 return Str
.encode ('utf-8', 'replace')
223 (0x01, 0x01): "PCI_DEVICE_PATH",
224 (0x01, 0x02): "PCCARD_DEVICE_PATH",
225 (0x01, 0x03): "MEMMAP_DEVICE_PATH",
226 (0x01, 0x04): "VENDOR_DEVICE_PATH",
227 (0x01, 0x05): "CONTROLLER_DEVICE_PATH",
228 (0x02, 0x01): "ACPI_HID_DEVICE_PATH",
229 (0x02, 0x02): "ACPI_EXTENDED_HID_DEVICE_PATH",
230 (0x02, 0x03): "ACPI_ADR_DEVICE_PATH",
231 (0x03, 0x01): "ATAPI_DEVICE_PATH",
232 (0x03, 0x12): "SATA_DEVICE_PATH",
233 (0x03, 0x02): "SCSI_DEVICE_PATH",
234 (0x03, 0x03): "FIBRECHANNEL_DEVICE_PATH",
235 (0x03, 0x04): "F1394_DEVICE_PATH",
236 (0x03, 0x05): "USB_DEVICE_PATH",
237 (0x03, 0x0f): "USB_CLASS_DEVICE_PATH",
238 (0x03, 0x10): "FW_SBP2_UNIT_LUN_DEVICE_PATH",
239 (0x03, 0x11): "DEVICE_LOGICAL_UNIT_DEVICE_PATH",
240 (0x03, 0x06): "I2O_DEVICE_PATH",
241 (0x03, 0x0b): "MAC_ADDR_DEVICE_PATH",
242 (0x03, 0x0c): "IPv4_DEVICE_PATH",
243 (0x03, 0x09): "INFINIBAND_DEVICE_PATH",
244 (0x03, 0x0e): "UART_DEVICE_PATH",
245 (0x03, 0x0a): "VENDOR_DEVICE_PATH",
246 (0x03, 0x13): "ISCSI_DEVICE_PATH",
247 (0x04, 0x01): "HARDDRIVE_DEVICE_PATH",
248 (0x04, 0x02): "CDROM_DEVICE_PATH",
249 (0x04, 0x03): "VENDOR_DEVICE_PATH",
250 (0x04, 0x04): "FILEPATH_DEVICE_PATH",
251 (0x04, 0x05): "MEDIA_PROTOCOL_DEVICE_PATH",
252 (0x05, 0x01): "BBS_BBS_DEVICE_PATH",
253 (0x7F, 0xFF): "EFI_DEVICE_PATH_PROTOCOL",
254 (0xFF, 0xFF): "EFI_DEVICE_PATH_PROTOCOL",
257 def EFI_DEVICE_PATH_PROTOCOL_TypeSummary (valobj
,internal_dict
):
261 if valobj
.TypeIsPointerType():
262 # EFI_DEVICE_PATH_PROTOCOL *
266 if valobj
.num_children
== 3:
267 # EFI_DEVICE_PATH_PROTOCOL
268 Type
= valobj
.GetChildMemberWithName('Type').unsigned
269 SubType
= valobj
.GetChildMemberWithName('SubType').unsigned
270 if (Type
, SubType
) in device_path_dict
:
271 TypeStr
= device_path_dict
[Type
, SubType
]
275 LenLow
= valobj
.GetChildMemberWithName('Length').GetChildAtIndex(0).unsigned
276 LenHigh
= valobj
.GetChildMemberWithName('Length').GetChildAtIndex(1).unsigned
277 Len
= LenLow
+ (LenHigh
>> 8)
279 Address
= long ("%d" % valobj
.addr
)
280 if (Address
== lldb
.LLDB_INVALID_ADDRESS
):
281 # Need to reserach this, it seems to be the nested struct case
283 elif (Type
& 0x7f == 0x7f):
284 ExprStr
= "End Device Path" if SubType
== 0xff else "End This Instance"
286 ExprStr
= "expr *(%s *)0x%08x" % (TypeStr
, Address
)
289 Str
+= " (UINT8) Type = 0x%02x // %s\n" % (Type
, "END" if (Type
& 0x7f == 0x7f) else "")
290 Str
+= " (UINT8) SubType = 0x%02x // %s\n" % (SubType
, ExprStr
)
291 Str
+= " (UINT8 [2]) Length = { // 0x%04x (%d) bytes\n" % (Len
, Len
)
292 Str
+= " (UINT8) [0] = 0x%02x\n" % LenLow
293 Str
+= " (UINT8) [1] = 0x%02x\n" % LenHigh
295 if (Type
& 0x7f == 0x7f) and (SubType
== 0xff):
298 NextNode
= Address
+ Len
299 Str
+= "// Next node 'expr *(EFI_DEVICE_PATH_PROTOCOL *)0x%08x'\n" % NextNode
305 def TypePrintFormating(debugger
):
307 # Set the default print formating for EFI types in lldb.
308 # seems lldb defaults to decimal.
310 category
= debugger
.GetDefaultCategory()
311 FormatBool
= lldb
.SBTypeFormat(lldb
.eFormatBoolean
)
312 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("BOOLEAN"), FormatBool
)
314 FormatHex
= lldb
.SBTypeFormat(lldb
.eFormatHex
)
315 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("UINT64"), FormatHex
)
316 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("INT64"), FormatHex
)
317 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("UINT32"), FormatHex
)
318 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("INT32"), FormatHex
)
319 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("UINT16"), FormatHex
)
320 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("INT16"), FormatHex
)
321 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("UINT8"), FormatHex
)
322 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("INT8"), FormatHex
)
323 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("UINTN"), FormatHex
)
324 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("INTN"), FormatHex
)
325 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("CHAR8"), FormatHex
)
326 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("CHAR16"), FormatHex
)
328 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("EFI_PHYSICAL_ADDRESS"), FormatHex
)
329 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("PHYSICAL_ADDRESS"), FormatHex
)
330 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("EFI_STATUS"), FormatHex
)
331 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("EFI_TPL"), FormatHex
)
332 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("EFI_LBA"), FormatHex
)
333 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("EFI_BOOT_MODE"), FormatHex
)
334 category
.AddTypeFormat(lldb
.SBTypeNameSpecifier("EFI_FV_FILETYPE"), FormatHex
)
337 # Smart type printing for EFI
339 debugger
.HandleCommand("type summary add EFI_GUID --python-function lldbefi.EFI_GUID_TypeSummary")
340 debugger
.HandleCommand("type summary add EFI_STATUS --python-function lldbefi.EFI_STATUS_TypeSummary")
341 debugger
.HandleCommand("type summary add EFI_TPL --python-function lldbefi.EFI_TPL_TypeSummary")
342 debugger
.HandleCommand("type summary add EFI_DEVICE_PATH_PROTOCOL --python-function lldbefi.EFI_DEVICE_PATH_PROTOCOL_TypeSummary")
344 debugger
.HandleCommand("type summary add CHAR16 --python-function lldbefi.CHAR16_TypeSummary")
345 debugger
.HandleCommand('type summary add --regex "CHAR16 \[[0-9]+\]" --python-function lldbefi.CHAR16_TypeSummary')
346 debugger
.HandleCommand("type summary add CHAR8 --python-function lldbefi.CHAR8_TypeSummary")
347 debugger
.HandleCommand('type summary add --regex "CHAR8 \[[0-9]+\]" --python-function lldbefi.CHAR8_TypeSummary')
350 gEmulatorBreakWorkaroundNeeded
= True
352 def LoadEmulatorEfiSymbols(frame
, bp_loc
, internal_dict
):
354 # This is an lldb breakpoint script, and assumes the breakpoint is on a
355 # function with the same prototype as SecGdbScriptBreak(). The
356 # argument names are important as lldb looks them up.
359 # SecGdbScriptBreak (
361 # int FileNameLength,
362 # long unsigned int LoadAddress,
369 # When the emulator loads a PE/COFF image, it calls the stub function with
370 # the filename of the symbol file, the length of the FileName, the
371 # load address and a flag to indicate if this is a load or unload operation
373 global gEmulatorBreakWorkaroundNeeded
375 if gEmulatorBreakWorkaroundNeeded
:
376 # turn off lldb debug prints on SIGALRM (EFI timer tick)
377 frame
.thread
.process
.target
.debugger
.HandleCommand("process handle SIGALRM -n false")
378 gEmulatorBreakWorkaroundNeeded
= False
380 # Convert C string to Python string
381 Error
= lldb
.SBError()
382 FileNamePtr
= frame
.FindVariable ("FileName").GetValueAsUnsigned()
383 FileNameLen
= frame
.FindVariable ("FileNameLength").GetValueAsUnsigned()
384 FileName
= frame
.thread
.process
.ReadCStringFromMemory (FileNamePtr
, FileNameLen
, Error
)
385 if not Error
.Success():
386 print "!ReadCStringFromMemory() did not find a %d byte C string at %x" % (FileNameLen
, FileNamePtr
)
387 # make breakpoint command contiue
388 frame
.GetThread().GetProcess().Continue()
390 debugger
= frame
.thread
.process
.target
.debugger
391 if frame
.FindVariable ("AddSymbolFlag").GetValueAsUnsigned() == 1:
392 LoadAddress
= frame
.FindVariable ("LoadAddress").GetValueAsUnsigned()
394 debugger
.HandleCommand ("target modules add %s" % FileName
)
395 print "target modules load --slid 0x%x %s" % (LoadAddress
, FileName
)
396 debugger
.HandleCommand ("target modules load --slide 0x%x --file %s" % (LoadAddress
, FileName
))
398 target
= debugger
.GetSelectedTarget()
399 for SBModule
in target
.module_iter():
400 ModuleName
= SBModule
.GetFileSpec().GetDirectory() + '/'
401 ModuleName
+= SBModule
.GetFileSpec().GetFilename()
402 if FileName
== ModuleName
or FileName
== SBModule
.GetFileSpec().GetFilename():
403 target
.ClearModuleLoadAddress (SBModule
)
404 if not target
.RemoveModule (SBModule
):
405 print "!lldb.target.RemoveModule (%s) FAILED" % SBModule
407 # make breakpoint command contiue
408 frame
.thread
.process
.Continue()
410 def GuidToCStructStr (guid
, Name
=False):
412 # Convert a 16-byte bytesarry (or bytearray compat object) to C guid string
413 # { 0xB402621F, 0xA940, 0x1E4A, { 0x86, 0x6B, 0x4D, 0xC9, 0x16, 0x2B, 0x34, 0x7C } }
415 # Name=True means lookup name in GuidNameDict and us it if you find it
418 if not isinstance (guid
, bytearray
):
419 # convert guid object to UUID, and UUID to bytearray
420 Uuid
= uuid
.UUID(guid
)
421 guid
= bytearray (Uuid
.bytes_le
)
423 return "{ 0x%02.2X%02.2X%02.2X%02.2X, 0x%02.2X%02.2X, 0x%02.2X%02.2X, { 0x%02.2X, 0x%02.2X, 0x%02.2X, 0x%02.2X, 0x%02.2X, 0x%02.2X, 0x%02.2X, 0x%02.2X } }" % \
424 (guid
[3], guid
[2], guid
[1], guid
[0], guid
[5], guid
[4], guid
[7], guid
[6], guid
[8], guid
[9], guid
[10], guid
[11], guid
[12], guid
[13], guid
[14], guid
[15])
426 def ParseGuidString(GuidStr
):
428 # Error check and convert C Guid init to string
429 # ParseGuidString("49152E77-1ADA-4764-B7A2-7AFEFED95E8B")
430 # ParseGuidString("{ 0xBA24B391, 0x73FD, 0xC54C, { 0x9E, 0xAF, 0x0C, 0xA7, 0x8A, 0x35, 0x46, 0xD1 } }")
434 # convert C form "{ 0xBA24B391, 0x73FD, 0xC54C, { 0x9E, 0xAF, 0x0C, 0xA7, 0x8A, 0x35, 0x46, 0xD1 } }"
435 # to string form BA24B391-73FD-C54C-9EAF-0CA78A3546D1
436 # make a list of Hex numbers like: ['0xBA24B391', '0x73FD', '0xC54C', '0x9E', '0xAF', '0x0C', '0xA7', '0x8A', '0x35', '0x46', '0xD1']
437 Hex
= ''.join(x
for x
in GuidStr
if x
not in '{,}').split()
438 Str
= "%08X-%04X-%04X-%02.2X%02.2X-%02.2X%02.2X%02.2X%02.2X%02.2X%02.2X" % \
439 (int(Hex
[0], 0), int(Hex
[1], 0), int(Hex
[2], 0), int(Hex
[3], 0), int(Hex
[4], 0), \
440 int(Hex
[5], 0), int(Hex
[6], 0), int(Hex
[7], 0), int(Hex
[8], 0), int(Hex
[9], 0), int(Hex
[10], 0))
441 elif GuidStr
.count('-') == 4:
442 # validate "49152E77-1ADA-4764-B7A2-7AFEFED95E8B" form
443 Check
= "%s" % str(uuid
.UUID(GuidStr
)).upper()
444 if GuidStr
.upper() == Check
:
445 Str
= GuidStr
.upper()
454 def create_guid_options():
455 usage
= "usage: %prog [data]"
456 description
='''lookup EFI_GUID by CName, C struct, or GUID string and print out all three.
458 parser
= optparse
.OptionParser(description
=description
, prog
='guid',usage
=usage
)
461 def efi_guid_command(debugger
, command
, result
, dict):
462 # Use the Shell Lexer to properly parse up command options just like a
464 command_args
= shlex
.split(command
)
465 parser
= create_guid_options()
467 (options
, args
) = parser
.parse_args(command_args
)
470 # caller forgot to quote the string"
471 # mark arg[0] a string containing all args[n]
472 args
[0] = ' '.join(args
)
473 GuidStr
= ParseGuidString (args
[0])
475 # return Key of GuidNameDict for value args[0]
476 GuidStr
= [Key
for Key
, Value
in guid_dict
.iteritems() if Value
== args
[0]][0]
477 GuidStr
= GuidStr
.upper()
479 # if you don't handle exceptions, passing an incorrect argument to the OptionParser will cause LLDB to exit
480 # (courtesy of OptParse dealing with argument errors by throwing SystemExit)
481 result
.SetError ("option parsing failed")
486 if GuidStr
in guid_dict
:
487 print "%s = %s" % (guid_dict
[GuidStr
], GuidStr
)
488 print "%s = %s" % (guid_dict
[GuidStr
], GuidToCStructStr (GuidStr
))
492 # dump entire dictionary
493 width
= max(len(v
) for k
,v
in guid_dict
.iteritems())
494 for value
in sorted(guid_dict
, key
=guid_dict
.get
):
495 print '%-*s %s %s' % (width
, guid_dict
[value
], value
, GuidToCStructStr(value
))
501 ########## Code that runs when this script is imported into LLDB ###########
503 def __lldb_init_module (debugger
, internal_dict
):
504 # This initializer is being run from LLDB in the embedded command interpreter
505 # Make the options so we can generate the help text for the new LLDB
506 # command line command prior to registering it with LLDB below
510 # Source Guid.xref file if we can find it
511 inputfile
= os
.getcwd()
512 inputfile
+= os
.sep
+ os
.pardir
+ os
.sep
+ 'FV' + os
.sep
+ 'Guid.xref'
513 with
open(inputfile
) as f
:
515 data
= line
.split(' ')
517 guid_dict
[data
[0].upper()] = data
[1].strip('\n')
519 # init EFI specific type formaters
520 TypePrintFormating (debugger
)
524 parser
= create_guid_options()
525 efi_guid_command
.__doc
__ = parser
.format_help()
526 debugger
.HandleCommand('command script add -f lldbefi.efi_guid_command guid')
529 Target
= debugger
.GetTargetAtIndex(0)
531 Breakpoint
= Target
.BreakpointCreateByName('SecGdbScriptBreak')
532 if Breakpoint
.GetNumLocations() == 1:
533 # Set the emulator breakpoints, if we are in the emulator
534 debugger
.HandleCommand("breakpoint command add -s python -F lldbefi.LoadEmulatorEfiSymbols {id}".format(id=Breakpoint
.GetID()))
535 print 'Type r to run emulator. SecLldbScriptBreak armed. EFI modules should now get source level debugging in the emulator.'