[lldb][ELF] Read symbols from .gnu_debugdata sect.

[kwk]

Summary

If the .symtab section is stripped from the binary it might be that
there's a .gnu_debugdata section which contains a smaller .symtab in
order to provide enough information to create a backtrace with function
names or to set and hit a breakpoint on a function name.

This change looks for a .gnu_debugdata section in the ELF object file.
The .gnu_debugdata section contains a xz-compressed ELF file with a
.symtab section inside. Symbols from that compressed .symtab section
are merged with the main object file's .dynsym symbols (if any).
In addition we always load the .dynsym even if there's a .symtab
section.

For example, the Fedora and RHEL operating systems strip their binaries
but keep a .gnu_debugdata section. While gdb already can read this
section, LLDB until this patch couldn't. To test this patch on a
Fedora or RHEL operating system, try to set a breakpoint on the "help"
symbol in the "zip" binary. Before this patch, only GDB can set this
breakpoint; now LLDB also can do so without installing extra debug
symbols:

lldb /usr/bin/zip -b -o "b help" -o "r" -o "bt" -- -h

The above line runs LLDB in batch mode and on the "/usr/bin/zip -h"
target:

(lldb) target create "/usr/bin/zip"
Current executable set to '/usr/bin/zip' (x86_64).
(lldb) settings set -- target.run-args  "-h"

Before the program starts, we set a breakpoint on the "help" symbol:

(lldb) b help
Breakpoint 1: where = zip`help, address = 0x00000000004093b0

Once the program is run and has hit the breakpoint we ask for a
backtrace:

(lldb) r
Process 10073 stopped
* thread #1, name = 'zip', stop reason = breakpoint 1.1
    frame #0: 0x00000000004093b0 zip`help
zip`help:
->  0x4093b0 <+0>:  pushq  %r12
    0x4093b2 <+2>:  movq   0x2af5f(%rip), %rsi       ;  + 4056
    0x4093b9 <+9>:  movl   $0x1, %edi
    0x4093be <+14>: xorl   %eax, %eax

Process 10073 launched: '/usr/bin/zip' (x86_64)
(lldb) bt
* thread #1, name = 'zip', stop reason = breakpoint 1.1
  * frame #0: 0x00000000004093b0 zip`help
    frame #1: 0x0000000000403970 zip`main + 3248
    frame #2: 0x00007ffff7d8bf33 libc.so.6`__libc_start_main + 243
    frame #3: 0x0000000000408cee zip`_start + 46

In order to support the .gnu_debugdata section, one has to have LZMA
development headers installed. The CMake section, that controls this
part looks for the LZMA headers and enables .gnu_debugdata support by
default if they are found; otherwise or if explicitly requested, the
minidebuginfo support is disabled.

GDB supports the "mini debuginfo" section .gnu_debugdata since v7.6
(2013).

[kwk]

lldb/source/Plugins/SymbolVendor/ELF/SymbolVendorELF.cpp

79 ↗

(On Diff #217329)

Fixed in f509e547ab793068e8b822317b93060077623b74

llvm/CMakeLists.txt

53–361 ↗

(On Diff #217933)

Fixed in d4236447e75a882ab61bd369cb8253f2a908368f

[kwk]

• Moved and renamed m_gnu_debug_data_object_file

[kwk]

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.h

391

Fixed in 0427898acf4a292f9737a33059e985239cc0e640

[labath]

lldb/cmake/modules/LLDBConfig.cmake

389

This looks like a really useful macro. I'll be sure to remember it.

390

It doesn't look like this is used anywhere.

393

Please put this into Config.h.cmake. I know a lot of code in this file does not do that, but that's because we didn't have a Config.h back then.

396

Is this code actually reachable? My understanding is that LLDB_ENABLE_LZMA should be automatically false if LIBLZMA_FOUND is not true...

lldb/source/Host/common/LZMA.cpp

82–83

printf format string here.

92

This is a valid printf string, but I am not sure if you intended it to come out like {lzma error: LZMA_MEMLIMIT_ERROR}

93

Calling .data() on a StringRef and expecting to get a c string is ill-advised. convertLZMACodeToString is a local static function, you could just make it return a const char *...

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

1965

No, I think you should just delete this bit of code completely (as the containing object file will call SetModulesArchitecture on its own).

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.h

157–164

This doesn't need to be public now, right?

lldb/source/Plugins/SymbolVendor/ELF/SymbolVendorELF.cpp

70 ↗

(On Diff #218300)

Using a unique_ptr is not a bad idea, but as right now this patch does not need to touch this file, it shouldn't be done as a part of this patch. Feel free to submit the unique_ptr thingy as a separate patch. No need to go through the review process...

lldb/test/CMakeLists.txt

119–121 ↗

(On Diff #218300)

I'd just make this unconditional, and add the tools to the big lldb-test-deps block.

[labath]

lldb/cmake/modules/LLDBConfig.cmake

393

(Among other things, this helps with incremental rebuilds, as only the files which include Config.h need to be recompiled)

[kwk]

• Remove left-over variable in CMake
• Move LLDB_ENABLE_LZMA into Config.h.cmake
• Remove unused code
• Change signature of lldb_private::lzma::uncompress
• Fixup
• Fixup
• When using the ObjectFile's own GetArchitecture(), no debug symbols are found
• Make GetGnuDebugDataObjectFile private
• Cleanup
• moved llvm-nm llvm-strip as test dependencies

[kwk]

@labath I did go over a lot of your comments. Thank you for helping me in becoming in a better contributor. I'm still not done with the python/make -> lit test transition but the rest is mostly covered.

lldb/cmake/modules/LLDBConfig.cmake

389

Make sure to include include(CMakeDependentOption)

390

Right, that was a left-over. Removed in 7dc045e67bb.

393

Addressed in a6277c07451

396

The logic is as follows:

LLDB_ENABLE_LZMA is ON if LIBLZMA_FOUND is ON.

Until now I though that can always go ahead and manually toggle on the option LLDB_ENABLE_LZMA by hand. And if you do this when LZMA is not available, then you get the fatal error. But as I understand [1] after reading it more than once, I think you're right: "This macro presents an option to the user only if a set of other conditions are true."

Let me verify this with a small example... yes, you're right. Even if you specify cmake . -DLLVM_ENABLE_LZMA it will not enable the option. Awesome! Fixed in 156f0af8c29980139ff1a2a8e51a768050564898

[1]: https://cmake.org/cmake/help/v3.0/module/CMakeDependentOption.html

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

1965

Let me try if it works how you suggested it. No, it doesn't work as no breakpoint from the embedded .gnu_debugdata section will be hit anymore. This section was inspired by ObjectFileELF::CreateInstance as you suggested to look at once.

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.h

157–164

Right, now that it is only called from CreateSections, it can be made private again. Fixed in bb1f3f0b5bd.

lldb/source/Plugins/SymbolVendor/ELF/SymbolVendorELF.cpp

70 ↗

(On Diff #218300)

It wasn't an idea but a necessity back when the whole minidebuginfo stuff was here. It still is a left-over that I have remove this change.

lldb/test/CMakeLists.txt

119–121 ↗

(On Diff #218300)

Done 1d731e225a243bb2afb66eb1f06cd010ee094208

[labath]

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

1965

I'd be very surprised if this makes a difference as calling SetModulesArchitecture just invokes Module::SetArchitecture, which is actually a no-op if the module architecture has already been set.

However, I see now that SetArchitecture also acts as a check, which ensures that the architecture of the (nested) object file is compatible with the module architecture. This bit sounds like a useful check against someone accidentally (however unlikely) embedding a different object file into the gnu_debugdata section, so I guess we can keep that.

[kwk]

• add lit test for minidebuginfo
• Fixup
• test
• Fiddle with the lit test
• Fix binary in lit test
• Working lit test - still need to only run it when minidebuginfo is available (LZMA)
• Make FileCheck less verbose
• Only run minidebuginfo lit test when lzma is available
• fix mylib.so not found problem
• Removed old python based minidebuginfo test
• Remove changes that were only necessary for the old python based test for minidebuginfo

[kwk]

• remove not needed <vector> include

[kwk]

squashed and rebased on top of master

[labath]

I think we're getting pretty close. I have a couple of extra comments inline, but they're all pretty minor, I hope. I'd just like to add some more tests, per our discussion on the IRC, and I have some doubts about what exactly is the test you've written actually testing, which I'd like to clarify...

lldb/CMakeLists.txt

101 ↗

(On Diff #218618)

It looks like you're already adding these in lldb/lit/CMakeLists.txt. Does it need to be in both?

lldb/include/lldb/Host/LZMA.h

25–26

Now that the vector is auto-resized, do you think it's still useful to expose the getUncompressedSize function as public api? If yes, then please change it to return Expected<uint64_t>. (returning Expected would be nice even for a private api, but there it's less important...)

lldb/lit/Breakpoint/Inputs/minidebuginfo-lib.h

1 ↗

(On Diff #218623)

Hmm... so, what is the exact scenario you want to test here? This function will end up in the dynsym section of the main executable, but it will be an *undefined* symbol there. Undefined symbols are ignored in the gnu_debugdata logic. The symbol will be *defined* in the dynsym section of the shared library, but you're not debugdata-ing that one.

While this scenario might be interesting to test, I am not sure if that's the one you actually intended...

PS: If you want to create a file with both dynsym, and non-dynsym defined symbols, you don't have to resort to using shared libraries to achieve that. A suitable combination of -rdynamic and visibility("hidden") will achieve that too. For example the following line:

clang -x c - <<<'__attribute__((visibility("hidden"))) int in_symtab() { return 42; } int in_dynsym() { return 47; } int main() { return in_symtab()+in_dynsym(); }' -rdynamic

will generate a file where the in_symtab function will only be present in the symtab, and in_dynsym will be in the dynsym section (until you apply the debug-data magic, it will be in the symtab too)...

lldb/lit/Breakpoint/minidebuginfo.test

32 ↗

(On Diff #218623)

Shouldn't this be %t.keep_symbols? Typo ?

lldb/lit/lit.cfg.py

103

you should apply llvm_canonicalize_cmake_booleans to the value of LLDB_ENABLE_LZMA at the cmake level. Otherwise, this will blow up if someone types -DLLDB_ENABLE_LZMA=On

lldb/source/Host/common/LZMA.cpp

73–83

too much auto

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

1886

You don't need the temporary ArrayRef. You can just pass data.GetData() directly..

[kwk]

• Fixup
• Test for minidebuginfo image dump symtab
• Fixed test for corrupted xz blob
• Fix test
• Added test that runs when no LZMA is configured

[kwk]

• Fixup
• Test for minidebuginfo image dump symtab
• Fixed test for corrupted xz blob
• Fix test
• Added test that runs when no LZMA is configured

[kwk]

• Better names for minidebuginfo files

[kwk]

• Better names for minidebuginfo files

[kwk]

• Fix spelling error

[labath]

Thank you for adding the tests, and for adding the xz detection to lit in particular. We're getting _reaally_ close now. I have a bunch more comments, including highlighting some you seems to have missed from earlier, but they are all just about polishing. The only somewhat larger comment is about the minidebuginfo-set-and-hit-breakpoint.test test. I'd like to understand what exactly is the scenario you are intending to test there, because I have a feeling it's not testing what you want it to test...

lldb/CMakeLists.txt

101 ↗

(On Diff #218618)

What about this?

lldb/include/lldb/Host/LZMA.h

25–26

What about this?

lldb/lit/Breakpoint/minidebuginfo-corrupt-xz.yaml

1 ↗

(On Diff #219038)

These tests should go to lit/Modules/ELF, as they have nothing to do with breakpoints, and everything to do with ELF files. The minidebuginfo-set-and-hit-breakpoint.test might stay here as it actually does deal with breakpoints, but it would also make sense to put it next to the ELF tests. I'll leave it up to you to decide where to place that one.

13 ↗

(On Diff #219038)

You shouldn't need an explicit -x in these tests as %lldb adds --no-use-colors already.

lldb/lit/Breakpoint/minidebuginfo-find-symbols.yaml

15 ↗

(On Diff #219038)

Could you add a symbol or two to the dynsym section of the outer file? I'd like to test that we get symbols from .dynsym *and* .symtab sections.

lldb/lit/Breakpoint/minidebuginfo-no-lzma.yaml

22 ↗

(On Diff #219038)

Nit: You most likely don't need such a gigantic blob to test this bit of functionality, as you can't read the data anyway...

lldb/lit/Breakpoint/minidebuginfo-set-and-hit-breakpoint.test

50 ↗

(On Diff #219038)

Instead of messing with the environment, it might be better to just set the rpath (-Wl,-rpath) of the executable appropriately (but I would still like to know what you're exactly trying to test with that extra shared library).

lldb/lit/lit.cfg.py

103

What about this?

lldb/source/Host/common/LZMA.cpp

73–83

What about this? (I think both of the autos here are unnecessary).

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

1850

I didn't notice this before, but you shouln't be calling module->GetSectionList() here. The unified_section_list you got as an argument *is* the module's section list.

1886

What about this?

[labath]

lldb/lit/Breakpoint/minidebuginfo-corrupt-xz.yaml

13 ↗

(On Diff #219038)

Actually, I take this back. It seems %lldb does not pass this automatically. I am not sure why, but since colors aren't a problem you here, you probably don't have to explicitly disable them anyway...

[kwk]

• Removed not needed test dependencies
• Changed return type of lzma::getUncompressedSize
• Moved minidebuginfo to subtree that deals with ELF
• Apply review comments

[kwk]

I've tackled the easy comments now and will come back to the more detailed ones as well. I'm not ignoring them.

lldb/CMakeLists.txt

101 ↗

(On Diff #218618)

You're right. one place is enough.

[kwk]

lldb/include/lldb/Host/LZMA.h

25–26

I've changed the syntax as you suggested. I kept the function there because I find it easier to maintain this way.

lldb/lit/Breakpoint/minidebuginfo-corrupt-xz.yaml

1 ↗

(On Diff #219038)

I've move all to lit/Modules/ELF.

13 ↗

(On Diff #219038)

I use -x and not -X. See lldb --help:

-x Alias for --no-lldbinit
-X Alias for --no-use-color

lldb/lit/Breakpoint/minidebuginfo-no-lzma.yaml

22 ↗

(On Diff #219038)

I kept it the same for the like the other files so you can text-diff it to find out that only one byte was modified. I thought this is a neat idea in order to actually error out upon decompression and not on file header for example. That being said what do you think about adding tests for the different errors that can occur during the whole inspection (e.g. in getUncompressedSize).

lldb/source/Host/common/LZMA.cpp

82–83

All done now.

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

1850

Done.

1886

Sorry for missing this. Done now.

[labath]

lldb/include/lldb/Host/LZMA.h

25–26

Ok. I am fine with that.

lldb/lit/Breakpoint/minidebuginfo-corrupt-xz.yaml

13 ↗

(On Diff #219038)

Ah, my bad. In that case you definitely *can* remove it because %lldb does add --no-lldbinit.

lldb/lit/Breakpoint/minidebuginfo-no-lzma.yaml

22 ↗

(On Diff #219038)

Ok. That's fine with me.
I am definitely not *against* adding more tests. :) I am not going to ask you to put more in because this patch already has more tests than most lldb patches, but I you want to do that, then by all means, go ahead. Things like these would be probably better off as a (c++) unit test, as they're really testing the details of the lzma handling code. The elf code doesn't really care about these details -- it just wants to know whether the decompression was successful or not.

[kwk]

labath, please see my answer to your question and maybe help me out why you think I don't test what I want to test.

lldb/lit/Breakpoint/minidebuginfo-set-and-hit-breakpoint.test

50 ↗

(On Diff #219038)

labath, I'd like to test the following scenario: Set a breakpoint on a symbol (multiplyByThree) in the .dynsym section and one on a symbol (multiplyByFour) from the .symtab that's embedded within the .gnu_debugdata section. I have no clue how to get those symbols without using a shared lib. Do you?

[kwk]

lldb/lit/Breakpoint/minidebuginfo-set-and-hit-breakpoint.test

50 ↗

(On Diff #219038)

I found a better and simpler way thanks to the help from @jankratochvil . Will implement it soon.

[MaskRay]

lldb/source/Host/common/LZMA.cpp

125

empty

130

if (auto err = ...)

return err;

137

is more common

139

stray inpos = 0;

[kwk]

• Remove -x from %lldb because that expands to the command which already includes it
• Improve and fix the minidebuginfo-set-and-hit-breakpoint.test

[kwk]

@labath I have greatly improved the set and hit breakpoint test. Thank you again @jankratochvil for bringing my attention to -Wl,--dynamic-list. That helped to put one symbol in .dynsym explicitly. I will see if I can utilize that knowledge to separate out the patch this comment of yours @labath :

Let's put this bit into a separate patch. As I said over IRC, I view this bit as functionally independent of the debugdata stuff (it's definitely independent in it's current form, as it will kick in for non-debugdata files too, which I think is fine).

[kwk]

Rebased on master to include changes from D67390

[kwk]

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

2715–2740

Done in D67390.

[labath]

This looks great now. Thank you for your patience. Just make sure to deal with the breakages from the other patch first. If the fix is non trivial, or if it's going to take a while, then please revert to unbreak the bots.

lldb/lit/Modules/ELF/minidebuginfo-corrupt-xz.yaml

2

system-linux shouldn't be required here. One of the reasons I wanted to have these tests is that they can run on any system, not just on linux.

lldb/lit/Modules/ELF/minidebuginfo-find-symbols.yaml

2

No system-linux

lldb/lit/Modules/ELF/minidebuginfo-no-lzma.yaml

2

no system-linux

lldb/source/Host/common/LZMA.cpp

130

I have a feeling this pattern is actually more common in lldb. I tend to use this one, but I am fine with either.

[kwk]

• Addressed review comments

[kwk]

This comment was removed by kwk.

lldb/source/Host/common/LZMA.cpp

130

So what now? I had getCompressedSize return an error before and changed it upon request to expected. I can live with both but like the expected thing a bit better in terms of: this goes in and this comes out mentality.

[kwk]

lldb/lit/Modules/ELF/minidebuginfo-corrupt-xz.yaml

2

@labath what about the other file minidebuginfo-set-and-hit-breakpoint.test. Remove system-linux from there as well?

[labath]

lldb/lit/Modules/ELF/minidebuginfo-corrupt-xz.yaml

2

You need to restrict that test somehow, because it only has a chance for working on elf platforms (as you're compiling binaries for the host and running them). It probably *should* work on all elf platforms, but we currently don't have a good way of expressing that and we're just restricting to system-linux currently.

If you feel adventurous you can try introducing a system-elf feature (or something), and then changing this test (and possibly others) to use that instead, but please do that as a separate patch.

lldb/source/Host/common/LZMA.cpp

130

My interpretation of @MaskRay's comment was that he wanted you do write something like

if (auto err = uncompressedSize.takeError())
  return err;

That is orthogonal to what type is returned by getCompressedSize, and is indeed a more common pattern in at least some parts of llvm. I am personally fine with both.

[kwk]

• Change logic and comment for when .dynsym is parsed
• Use different pattern for error checking
• use less auto
• Remove required system-linux test feature from LZMA tests

[kwk]

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

2715–2740

We agreed to not have this other patch. See D67390#1691424.

[kwk]

Tests did pass so this change is ready for review @labath @jankratochvil .

[jankratochvil]

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

1854

I miss here comparing that the sections inside .gnu_debugdata file match sections in the outer file:

jankratochvil: "hm.... I was under the impression that section number should remain the same in regular and split debug files" - maybe you are right but then we could just also compare the two section tables and if they differ then reject whole .gnu_debugdata.  And then we do not have to compare section names but it is enough to compare section indexes.
labath: "right but then we could just also compare the two section tables and if they differ then reject whole .gnu_debugdata."
labath: I would like that ^

Also I do not see here handling .strtab, why does it work without moving also .strtab?

[labath]

Ok, let's try this once more. I took another look at the patch, and I have some more tiny comments, but nothing too major.

I'm sorry this took so long. When the topic of parsing both symbol sections came up, I was happy that it was implemented in a way that applies outside of minidebuginfo too, because it seemed like it could be a useful source of additional information. However, that turned into a huge rabbit hole, which isn't really relevant for the thing you're trying to accomplish. If we've managed to come this far without needing to consult both symbol tables, I think we'll manage to wait a couple years longer.

lldb/lit/Modules/ELF/minidebuginfo-no-lzma.yaml

5

s/a. /a ./

lldb/source/Host/common/LZMA.cpp

2

Fix header.

70–73

This is redundant, as you're comparing the size against LZMA_STREAM_HEADER_SIZE anyway.

85

Maybe InputBuffer.take_back(LZMA_STREAM_HEADER_SIZE).data() ?

105–106

same here.

126–129

This is redundant, as getUncompressedSize checks that anyway.

138

= UINT64_MAX;. This looks too much like a function declaration, and is not consistent with the code below.

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

1854

I'd leave that out for now. This is similar stuff to what is already being done in SymbolVendorELF, which should also probably check for section matches, and would be best handled together.

The reason that this works without moving .strtab is because the parsing is still done within the context of the owning object file. This whole section merging business is a pretty big mess, and in dire need of some TLC, but @kwk is not making that worse, so I wouldn't want to deal with that here...

2725

You can add that this is because minidebuginfo normally removes the symtab symbols which have their matching dynsym counterparts.

[kwk]

• Fix typo: s/a. /a ./
• Fix comment header
• Remove redundant input buffer check
• Remove another redundant input buffer check
• Change variable initialization to assign
• added comment about minidebuginfo

[kwk]

@labath I've addressed all you comments. Thank you for answering @jankratochvil's question as well. If this patch is good to go now, please give a thumbs up.

lldb/source/Host/common/LZMA.cpp

85

take_back:

Return a copy of *this with only the last \p N elements.

I mean LZMA_STREAM_HEADER_SIZE is only 12 but do we really need it?

105–106

Same answer here.

[kwk]

@labath ah, I've just seen that you did accept the revision already. Will merge it then after running tests once more.

[kwk]

Rebased onto current master

[kwk]

@labath as much as I would love to merge this patch I get errors from these tests that I didn't see before. They only appear after rebasing onto master:

Failing Tests (4):
    lldb-Suite :: commands/process/attach/TestProcessAttach.py
    lldb-Suite :: python_api/hello_world/TestHelloWorld.py
    lldb-Suite :: tools/lldb-server/libraries-svr4/TestGdbRemoteLibrariesSvr4Support.py
    lldb-Suite :: tools/lldb-vscode/attach/TestVSCode_attach.py

I also get the same errors on current master .(revision 8815be04ec1f333564591d9593735f22efa9bee5) without my patch applied. But before I merrge my patch I'd like to see master in a better shape, no?

[jankratochvil]

In D66791#1696340, @kwk wrote:

lldb-Suite :: commands/process/attach/TestProcessAttach.py
lldb-Suite :: tools/lldb-vscode/attach/TestVSCode_attach.py

These are by: D68289

lldb-Suite :: python_api/hello_world/TestHelloWorld.py
lldb-Suite :: tools/lldb-server/libraries-svr4/TestGdbRemoteLibrariesSvr4Support.py

The Fedora buildbot shows different two ones:

lldb-Suite :: commands/gui/basic/TestGuiBasic.py
lldb-Suite :: python_api/hello_world/TestHelloWorld.py

Although I do not have those reproducible on my local Fedora 30 host.

[kwk]

rebased

[kwk]

Closed by 2c082b48274fcba62bf9b3acb63075aedcc7a976.

[labath]

lldb/source/Host/common/LZMA.cpp

85

Yeah, that documentation is somewhat misleading. If you look at the implementation you'll see that there's no copying involved (ArrayRefs never copy anything -- that's their whole point of existence). So, I still think that this is better/more readable with take_back.

lldb/cmake/modules/LLDBConfig.cmake

 include(CheckCXXSymbolExists)
 include(CheckTypeSize)
+include(CMakeDependentOption)
 
 set(LLDB_PROJECT_ROOT ${CMAKE_CURRENT_SOURCE_DIR})
 set(LLDB_SOURCE_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/source")
 set(LLDB_INCLUDE_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/include")
 
 set(LLDB_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
 set(LLDB_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR})
 
if(NOT DEFINED LLDB_VERSION_PATCH)
   set(LLDB_VERSION_PATCH ${LLVM_VERSION_PATCH})
 endif()
 if(NOT DEFINED LLDB_VERSION_SUFFIX)
   set(LLDB_VERSION_SUFFIX ${LLVM_VERSION_SUFFIX})
 endif()
 set(LLDB_VERSION "${LLDB_VERSION_MAJOR}.${LLDB_VERSION_MINOR}.${LLDB_VERSION_PATCH}${LLDB_VERSION_SUFFIX}")
 message(STATUS "LLDB version: ${LLDB_VERSION}")
 
+find_package(LibLZMA)
+cmake_dependent_option(LLDB_ENABLE_LZMA "Support LZMA compression" ON "LIBLZMA_FOUND" OFF)
+if (LLDB_ENABLE_LZMA)
+  include_directories(${LIBLZMA_INCLUDE_DIRS})
+endif()
+llvm_canonicalize_cmake_booleans(LLDB_ENABLE_LZMA)
+
 include_directories(BEFORE
   ${CMAKE_CURRENT_BINARY_DIR}/include
   ${CMAKE_CURRENT_SOURCE_DIR}/include
   )
 
 if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
   install(DIRECTORY include/
     COMPONENT lldb-headers
     DESTINATION include
     FILES_MATCHING

lldb/include/lldb/Host/Config.h.cmake

 #cmakedefine01 HAVE_PROCESS_VM_READV
 
 #cmakedefine01 HAVE_NR_PROCESS_VM_READV
 
 #ifndef HAVE_LIBCOMPRESSION
 #cmakedefine HAVE_LIBCOMPRESSION
 #endif
 
+#cmakedefine01 LLDB_ENABLE_LZMA
+
 #endif // #ifndef LLDB_HOST_CONFIG_H

lldb/include/lldb/Host/LZMA.h

+//===-- LZMA.h --------------------------------------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef liblldb_Host_LZMA_h_
+#define liblldb_Host_LZMA_h_
+
+#include "llvm/ADT/ArrayRef.h"
+
+namespace llvm {
+class Error;
+} // End of namespace llvm
+
+namespace lldb_private {
+
+namespace lzma {
+  
+bool isAvailable();
+
+llvm::Expected<uint64_t>
+getUncompressedSize(llvm::ArrayRef<uint8_t> InputBuffer);
+
+llvm::Error uncompress(llvm::ArrayRef<uint8_t> InputBuffer,
+                       llvm::SmallVectorImpl<uint8_t> &Uncompressed);
+
+} // End of namespace lzma
+
+} // End of namespace lldb_private
+
+#endif // liblldb_Host_LZMA_h_

lldb/lit/CMakeLists.txt

list(APPEND LLDB_TEST_DEPS
   dsymutil
   lit-cpuid
   llc
   lldb
   lldb-test
   lli
   llvm-config
   llvm-dwarfdump
+  llvm-nm
   llvm-mc
   llvm-objcopy
   llvm-readobj
+  llvm-strip
   )
 
 if(TARGET lld)
   list(APPEND LLDB_TEST_DEPS lld)
 endif()
 
 # the value is not canonicalized within LLVM
 llvm_canonicalize_cmake_booleans(

lldb/lit/Modules/ELF/Inputs/minidebuginfo-main.c

+// This function will be embedded within the .symtab section of the
+// .gnu_debugdata section.
+int multiplyByFour(int num) { return num * 4; }
+
+// This function will be embedded within the .dynsym section of the main binary.
+int multiplyByThree(int num) { return num * 3; }
+
+int main(int argc, char *argv[]) {
+  int x = multiplyByThree(argc);
+  int y = multiplyByFour(x);
+  return y;
+}

lldb/lit/Modules/ELF/minidebuginfo-corrupt-xz.yaml

+# REQUIRES: lzma
+
+# This test checks that an error occurs when a corrupted
+# .gnu_debugdata section is trying to be xz uncompressed.
+
+# RUN: yaml2obj %s > %t.obj
+
+# TODO(kwk): once yaml2obj doesn't auto-generate a .symtab section
+# when there's none in YAML, remove the following line:
+
+# RUN: llvm-objcopy --remove-section=.symtab %t.obj
+
+# RUN: %lldb -b -o 'image dump symtab' %t.obj 2>&1 | FileCheck %s
+
+# CHECK: warning: (x86_64) {{.*}}.obj An error occurred while decompression the section .gnu_debugdata: lzma_stream_buffer_decode()=lzma error: LZMA_DATA_ERROR
+
+--- !ELF
+FileHeader:
+  Class:           ELFCLASS64
+  Data:            ELFDATA2LSB
+  Type:            ET_EXEC
+  Machine:         EM_X86_64
+  Entry:           0x00000000004004C0
+Sections:
+  - Name:            .gnu_debugdata
+    Type:            SHT_PROGBITS
+    AddressAlign:    0x0000000000000001
+    Content:         FD377A585A000004E6D6B4460200210116000000742FE5A3E0180F05BA5D003F914584683D89A6DA8ACC93E24ED90802EC1FE2A7102958F4A42B6A7134F23922F6F35F529E133A8B5588025CFAC876C68510A157DBBCF8CA75E9854DED10FDD5CE0CDC136F6459B13B9847AEF79E9B1C7CD70EF4F3AF709F5DA0C1F40780154D72120A6A62A3F1A216E20DC597CE55BB23B48785957321A15FEE48808C1428B925DBC8022541CC594BD0AF2B51C6BE2854C81611017704DF6E509D21013B80BEC27D8919ACD3157E89353A08F4C86781ED708E89AB322D010F0F1605DAD9B9CE2B13C387769C83F5F85C647FD9C551E0E9C7D4A5CBE297970E486CB94AC283F98A7C6412A57F9C37952327549EEC4634D2CFA55B0F99923A14992D4293E0D87CEEF7FB6160C45928DE25074EEBF5329B5579AF01DB23DF22CBD48C8037B68FFFBE5CEA6CD26A936DD07D9B2E6006B7C6E5CC751072185EFE995D3F3C8DACF9039D4BEFB1F376B491568F6F00DB50FF477F36B90413E4FA30AE7C561A1249FD45FDFF884F70247FC21E57195A764151D8E341267E724D856C512BD243CDB33AB313758443877B2CB58F7F8F0461DE9766647F333A3531BDC4A26E9537EB314708D31212FCF4C21E9CB139F4DBFD21BB16A126C35E2BB3F7E30BF5A54961CECD4DD4D91A3757356F618754B21533C34F2BD97D70A02B1F338588BDBA9CDF5FC9FBE973E550194F07EC7A1E8E3C005FD60F8853223427628987E82E701CA7E2FDFA1B0ED564C37D115A72C3EC01E29C85C3630D8A385C4AE12F4F75F9F0BC12F2698345DD62A1F546A5953AF5CF3C0F22C7DA510F6739EB8CDB0E8A5A3BC13CFC31C1875C313908EFF23678869B76A6E1C10FE699E43BFFDE8F0752ED994A4A84BC0AD9D7381131D457C4917C4F6656F5C95D3221A79166C802D5F5A7C68554E54C42CA535465D224C7B641CF3417C3EAFD03CE5709BEA33DC7C9155CAC9D3C8033AF7CDA622020606A7C139D77FF85BC19323BF956C9C4662F60079BC7FE5F67B46211716A1A6CE4AB8AAB307D6444310CBC101071703EECC0B4622D91D705F5DA2932DA8BCEDA8E1CB0CDB20AAD652B8F86A521D3421287F1C175AE3BE6458AE6F8F3FB6FB7ED97B616B580D791E5FE0B74973F8604F419039B5B9D9A14397EE509F2B33AE404FF96DD0551472C5302E67910F0794B15CFE837351C6AF89B2FE88488B557BE8ACFFA331FB7AD553D35CAEB7D8BCEFB6CFF4A58E91355FE931408CF4CAFA9B97518B9E5C02078F64CE81279801B090348213DCAA7D12DC098BFF58C5A3202EFC38F64AD894379747B54AB5A9843F82E5FF1F394C8B78344A8F1655DDEF8D5FE09EBB3E703853ABD716743507000696FB6B35216B088E499F53880375521442ED45DCDD1B31AAEBDAD3C7DA958593425206C4B2A0BC6CADE3B0B1598499E08016E84F33E3EB9D7B03B9C9DFA91B8CE5C74DEF2BC97FEE9982B0AEC16C75EEB7AE9A858A9C37F6C12B040C68A49111DCF0F3A4780F3879E93D904676BE908FDC66373D34AA715A39EFBC2795C6C8F058CA24392FB2591AD06ACD6AED8746F926886180C2B007ED58C9884A8BEF6CCA1F549F5C4FB411A3FF78770D1147363AC80B98B5A8FDB3DEC4E61709F66A622BDA835B1FD67B7C7CB166ABB163FB7C5204AE200C71C6A18B532C407647323B8F2FAC7ECB68C250877FC8DD5FE05B2B39E66F687EBB6EEFB7D5209E22F451B76F57D90BB6641DFFDE1A1821C4D783E4756F3CEE7F63B9BA284F8E114B0D9A086D83233BED4A8F5B60933DC16AF4DDE19C9FC59BCC1646343ECE7007B1C4DC65C4A939CDD47F6ED8855913183149BECE66D8FE7793AE607EB8E28513749B9548252764110D3B58D1D8B348DB18F7F24F8CA0C7D9CB515D90F7F1848FF58472B2EF52EBAB123AFC7F87890CE9FC55B31160014294A9B7F81638A27335E29E15A10B1068D5E049B1C239814DBBCC1BB30E11EEBAD5ACF8FB1B986C4F48D73FEA6129D9708A0B5AC435402BEC8C79C71DB94394811B9A604141A125A4669F9A139A0264E93E822117BE8E0D93A1487C51214E9FBF5763A3FBE9DA700B9C9B435472AF9F0B4446B000000003239307DD8B645100001D60B90300000CA1EC9E9B1C467FB020000000004595A
+...

lldb/lit/Modules/ELF/minidebuginfo-find-symbols.yaml

+# REQUIRES: lzma
+
+# RUN: yaml2obj %s > %t.obj
+
+# TODO(kwk): once yaml2obj doesn't auto-generate a .symtab section
+# when there's none in YAML, remove the following line:
+
+# RUN: llvm-objcopy --remove-section=.symtab %t.obj
+
+# RUN: %lldb -b -o 'image dump symtab' %t.obj | FileCheck %s
+
+# CHECK: [ 0] 1 X Code 0x00000000004005b0 0x000000000000000f 0x00000012 multiplyByFour
+
+--- !ELF
+FileHeader:
+  Class:           ELFCLASS64
+  Data:            ELFDATA2LSB
+  Type:            ET_EXEC
+  Machine:         EM_X86_64
+  Entry:           0x00000000004004C0
+Sections:
+  - Name:            .gnu_debugdata
+    Type:            SHT_PROGBITS
+    AddressAlign:    0x0000000000000001
+    Content:         FD377A585A000004E6D6B4460200210116000000742FE5A3E0180F05BA5D003F914584683D89A6DA8ACC93E24ED90802EC1FE2A7102958F4A42B6A7134F23922F6F35F529E133A8B5588025CFAC876C68510A157DBBCF8CA75E9854DED10FDD5CE0CDC136F6459B13B9847AEF79E9B1C7CD70EF4F3AF709F5DA0C1F40780154D72120A6A62A3F1A216E20DC597CE55BB23B48785957321A15FEE48808C1428B925DBC8022541CC594BD0AF2B51C6BE2854C81611017704DF6E509D21013B80BEC27D8919ACD3157E89353A08F4C86781ED708E89AB322D010F0F1605DAD9B9CE2B13C387769C83F5F85C647FD9C551E0E9C7D4A5CBE297970E486CB94AC283F98A7C6412A57F9C37952327549EEC4634D2CFA55B0F99923A14992D4293E0D87CEEF7FB6160C45928DE25074EEBF5329B5579AF01DB23DF22CBD48C8037B68FFFBE5CEA6CD26A936DD07D9B2E6006B7C6E5CC751072185EFE995D3F3C8DACF9039D4BEFB1F376B491568F6F00DB50FF477F36B90413E4FA30AE7C561A1249FD45FDFF884F70247FC21E57195A764151D8E341267E724D856C512BD243CDB33AB313758443877B2CB58F7F8F0461DE9766647F333A3531BDC4A26E9537EB314708D31212FCF4C21E9CB139F4DBFD21BB16A126C35E2BB3F7E30BF5A54961CECD4DD4D91A3757356F618754B21533C34F2BD97D70A02B1F338588BDBA9CDF5FC9FBE973E550194F07EC7A1E8E3C005FD60F8853223427628987E82E701CA7E2FDFA1B0ED564C37D115A72C3EC01E29C85C3630D8A385C4AE12F4F75F9F0BC12F2698345DD62A1F546A5953AF5CF3C0F22C7DA510F6739EB8CDB0E8A5A3BC13CFC31C1875C313908EFF23678869B76A6E1C10FE699E43BFFDE8F0752ED994A4A84BC0AD9D7381131D457C4917C4F6656F5C95D3221A79166C802D5F5A7C68554E54C42CA535465D224C7B641CF3417C3EAFD03CE5709BEA33DC7C9155CAC9D3C8033AF7CDA622020606A7C139D77FF85BC19323BF956C9C4662F60079BC7FE5F67B46211716A1A6CE4AB8AAB307D6444310CBC101071703EECC0B4622D91D705F5DA2932DA8BCEDA8E1CB0CDB20AAD652B8F86A521D3421287F1C175AE3BE6458AE6F8F3FB6FB7ED97B616B580D791E5FE0B74973F8604F419039B5B9D9A14397EE509F2B33AE404FF96DD0551472C5302E67910F0794B15CFE837351C6AF89B2FE88488B557BE8ACFFA331FB7AD553D35CAEB7D8BCEFB6CFF4A58E91355FE931408CF4CAFA9B97518B9E5C02078F64CE81279801B090348213DCAA7D12DC098BFF58C5A3202EFC38F64AD894379747B54AB5A9843F82E5FF1F394C8B783C3A8F1655DDEF8D5FE09EBB3E703853ABD716743507000696FB6B35216B088E499F53880375521442ED45DCDD1B31AAEBDAD3C7DA958593425206C4B2A0BC6CADE3B0B1598499E08016E84F33E3EB9D7B03B9C9DFA91B8CE5C74DEF2BC97FEE9982B0AEC16C75EEB7AE9A858A9C37F6C12B040C68A49111DCF0F3A4780F3879E93D904676BE908FDC66373D34AA715A39EFBC2795C6C8F058CA24392FB2591AD06ACD6AED8746F926886180C2B007ED58C9884A8BEF6CCA1F549F5C4FB411A3FF78770D1147363AC80B98B5A8FDB3DEC4E61709F66A622BDA835B1FD67B7C7CB166ABB163FB7C5204AE200C71C6A18B532C407647323B8F2FAC7ECB68C250877FC8DD5FE05B2B39E66F687EBB6EEFB7D5209E22F451B76F57D90BB6641DFFDE1A1821C4D783E4756F3CEE7F63B9BA284F8E114B0D9A086D83233BED4A8F5B60933DC16AF4DDE19C9FC59BCC1646343ECE7007B1C4DC65C4A939CDD47F6ED8855913183149BECE66D8FE7793AE607EB8E28513749B9548252764110D3B58D1D8B348DB18F7F24F8CA0C7D9CB515D90F7F1848FF58472B2EF52EBAB123AFC7F87890CE9FC55B31160014294A9B7F81638A27335E29E15A10B1068D5E049B1C239814DBBCC1BB30E11EEBAD5ACF8FB1B986C4F48D73FEA6129D9708A0B5AC435402BEC8C79C71DB94394811B9A604141A125A4669F9A139A0264E93E822117BE8E0D93A1487C51214E9FBF5763A3FBE9DA700B9C9B435472AF9F0B4446B000000003239307DD8B645100001D60B90300000CA1EC9E9B1C467FB020000000004595A
+...

lldb/lit/Modules/ELF/minidebuginfo-no-lzma.yaml

+# REQUIRES: !lzma
+
+# This test checks that a warning is printed when we're trying
+# to decompress a .gnu_debugdata section when no LZMA support was compiled in.
+
+# RUN: yaml2obj %s > %t.obj
+
+# TODO(kwk): once yaml2obj doesn't auto-generate a .symtab section
+# when there's none in YAML, remove the following line:
+
+# RUN: llvm-objcopy --remove-section=.symtab %t.obj
+
+# RUN: %lldb -b -o 'image dump symtab' %t.obj 2>&1 | FileCheck %s
+
+# CHECK: warning: (x86_64) {{.*}}.obj No LZMA support found for reading .gnu_debugdata section
+
+--- !ELF
+FileHeader:
+  Class:           ELFCLASS64
+  Data:            ELFDATA2LSB
+  Type:            ET_EXEC
+  Machine:         EM_X86_64
+  Entry:           0x00000000004004C0
+Sections:
+  - Name:            .gnu_debugdata
+    Type:            SHT_PROGBITS
+    AddressAlign:    0x0000000000000001
+    Content:         FD377A585A000004E6D6B4460200210116000000742FE5A3E0180F05BA5D003F914584683D89A6DA8ACC93E24ED90802EC1FE2A7102958F4A42B6A7134F23922F6F35F529E133A8B5588025CFAC876C68510A157DBBCF8CA75E9854DED10FDD5CE0CDC136F6459B13B9847AEF79E9B1C7CD70EF4F3AF709F5DA0C1F40780154D72120A6A62A3F1A216E20DC597CE55BB23B48785957321A15FEE48808C1428B925DBC8022541CC594BD0AF2B51C6BE2854C81611017704DF6E509D21013B80BEC27D8919ACD3157E89353A08F4C86781ED708E89AB322D010F0F1605DAD9B9CE2B13C387769C83F5F85C647FD9C551E0E9C7D4A5CBE297970E486CB94AC283F98A7C6412A57F9C37952327549EEC4634D2CFA55B0F99923A14992D4293E0D87CEEF7FB6160C45928DE25074EEBF5329B5579AF01DB23DF22CBD48C8037B68FFFBE5CEA6CD26A936DD07D9B2E6006B7C6E5CC751072185EFE995D3F3C8DACF9039D4BEFB1F376B491568F6F00DB50FF477F36B90413E4FA30AE7C561A1249FD45FDFF884F70247FC21E57195A764151D8E341267E724D856C512BD243CDB33AB313758443877B2CB58F7F8F0461DE9766647F333A3531BDC4A26E9537EB314708D31212FCF4C21E9CB139F4DBFD21BB16A126C35E2BB3F7E30BF5A54961CECD4DD4D91A3757356F618754B21533C34F2BD97D70A02B1F338588BDBA9CDF5FC9FBE973E550194F07EC7A1E8E3C005FD60F8853223427628987E82E701CA7E2FDFA1B0ED564C37D115A72C3EC01E29C85C3630D8A385C4AE12F4F75F9F0BC12F2698345DD62A1F546A5953AF5CF3C0F22C7DA510F6739EB8CDB0E8A5A3BC13CFC31C1875C313908EFF23678869B76A6E1C10FE699E43BFFDE8F0752ED994A4A84BC0AD9D7381131D457C4917C4F6656F5C95D3221A79166C802D5F5A7C68554E54C42CA535465D224C7B641CF3417C3EAFD03CE5709BEA33DC7C9155CAC9D3C8033AF7CDA622020606A7C139D77FF85BC19323BF956C9C4662F60079BC7FE5F67B46211716A1A6CE4AB8AAB307D6444310CBC101071703EECC0B4622D91D705F5DA2932DA8BCEDA8E1CB0CDB20AAD652B8F86A521D3421287F1C175AE3BE6458AE6F8F3FB6FB7ED97B616B580D791E5FE0B74973F8604F419039B5B9D9A14397EE509F2B33AE404FF96DD0551472C5302E67910F0794B15CFE837351C6AF89B2FE88488B557BE8ACFFA331FB7AD553D35CAEB7D8BCEFB6CFF4A58E91355FE931408CF4CAFA9B97518B9E5C02078F64CE81279801B090348213DCAA7D12DC098BFF58C5A3202EFC38F64AD894379747B54AB5A9843F82E5FF1F394C8B783C3A8F1655DDEF8D5FE09EBB3E703853ABD716743507000696FB6B35216B088E499F53880375521442ED45DCDD1B31AAEBDAD3C7DA958593425206C4B2A0BC6CADE3B0B1598499E08016E84F33E3EB9D7B03B9C9DFA91B8CE5C74DEF2BC97FEE9982B0AEC16C75EEB7AE9A858A9C37F6C12B040C68A49111DCF0F3A4780F3879E93D904676BE908FDC66373D34AA715A39EFBC2795C6C8F058CA24392FB2591AD06ACD6AED8746F926886180C2B007ED58C9884A8BEF6CCA1F549F5C4FB411A3FF78770D1147363AC80B98B5A8FDB3DEC4E61709F66A622BDA835B1FD67B7C7CB166ABB163FB7C5204AE200C71C6A18B532C407647323B8F2FAC7ECB68C250877FC8DD5FE05B2B39E66F687EBB6EEFB7D5209E22F451B76F57D90BB6641DFFDE1A1821C4D783E4756F3CEE7F63B9BA284F8E114B0D9A086D83233BED4A8F5B60933DC16AF4DDE19C9FC59BCC1646343ECE7007B1C4DC65C4A939CDD47F6ED8855913183149BECE66D8FE7793AE607EB8E28513749B9548252764110D3B58D1D8B348DB18F7F24F8CA0C7D9CB515D90F7F1848FF58472B2EF52EBAB123AFC7F87890CE9FC55B31160014294A9B7F81638A27335E29E15A10B1068D5E049B1C239814DBBCC1BB30E11EEBAD5ACF8FB1B986C4F48D73FEA6129D9708A0B5AC435402BEC8C79C71DB94394811B9A604141A125A4669F9A139A0264E93E822117BE8E0D93A1487C51214E9FBF5763A3FBE9DA700B9C9B435472AF9F0B4446B000000003239307DD8B645100001D60B90300000CA1EC9E9B1C467FB020000000004595A
+...

lldb/lit/Modules/ELF/minidebuginfo-set-and-hit-breakpoint.test

+# REQUIRES: system-linux, lzma, xz
+
+# We want to keep the symbol "multiplyByThree" in the .dynamic section and not
+# have it put the default .symtab section.
+# RUN: echo "{multiplyByThree;};" > %T/dynmic-symbols.txt
+# RUN: %clang -Wl,--dynamic-list=%T/dynmic-symbols.txt -g -o %t.binary %p/Inputs/minidebuginfo-main.c
+
+# The following section is adapted from GDB's official documentation:
+# http://sourceware.org/gdb/current/onlinedocs/gdb/MiniDebugInfo.html#MiniDebugInfo
+
+# Extract the dynamic symbols from the main binary, there is no need
+# to also have these in the normal symbol table.
+
+# IGNORE: llvm-nm -D %t.binary --format=posix --defined-only | awk '{ print $1 }' | sort > %t.dynsyms
+
+# Extract all the text (i.e. function) symbols from the debuginfo.
+# (Note that we actually also accept "D" symbols, for the benefit
+# of platforms like PowerPC64 that use function descriptors.)
+
+# IGNORE: llvm-nm %t.binary --format=posix --defined-only | awk '{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 }' | sort > %t.funcsyms
+
+# Keep all the function symbols not already in the dynamic symbol
+# table.
+
+# IGNORE: comm -13 %t.dynsyms %t.funcsyms > %t.keep_symbols
+# The result of the preceeding command can be preprocessed in %p/Inputs/minidebuginfo.keep_symbols
+# because we know what symbol to keep.
+# RUN: echo "multiplyByFour" > %p/Inputs/minidebuginfo.keep_symbols
+
+# Separate full debug info into debug binary.
+
+# RUN: llvm-objcopy --only-keep-debug %t.binary %t.debug
+
+# Copy the full debuginfo, keeping only a minimal set of symbols and
+# removing some unnecessary sections.
+
+# RUN: llvm-objcopy -S --remove-section .gdb_index --remove-section .comment --keep-symbols=%p/Inputs/minidebuginfo.keep_symbols %t.debug %t.mini_debuginfo
+
+# This command is not from the GDB manual but it slims down embedded minidebug
+# info. On top if that, it ensures that we only have the multiplyByThree symbol
+# in the .dynsym section of the main binary.
+# RUN: llvm-objcopy --remove-section=.rela.dyn --remove-section=.gnu.version --remove-section=.gnu.hash --remove-section=.dynsym %t.mini_debuginfo
+
+# Drop the full debug info from the original binary.
+
+# RUN: llvm-strip --strip-all -R .comment %t.binary
+
+# Inject the compressed data into the .gnu_debugdata section of the
+# original binary.
+
+# RUN: xz --force --keep %t.mini_debuginfo
+
+# RUN: llvm-objcopy --add-section .gnu_debugdata=%t.mini_debuginfo.xz %t.binary
+
+# Now run the binary and see that we can set and hit a breakpoint
+# from within the .dynsym section (multiplyByThree) and one from
+# the .symtab section embedded in the .gnu_debugdata section (multiplyByFour).
+
+# RUN: %lldb -b -o 'b multiplyByThree' -o 'b multiplyByFour' -o 'run' -o 'continue' -o 'breakpoint list -v' %t.binary | FileCheck %s
+
+# CHECK: (lldb) b multiplyByThree
+# CHECK-NEXT: Breakpoint 1: where = minidebuginfo-set-and-hit-breakpoint.test.tmp.binary`multiplyByThree, address = 0x{{.*}}
+
+# CHECK: (lldb) b multiplyByFour
+# CHECK-NEXT: Breakpoint 2: where = minidebuginfo-set-and-hit-breakpoint.test.tmp.binary`multiplyByFour, address = 0x{{.*}}
+
+# CHECK: * thread #1, name = 'minidebuginfo-s', stop reason = breakpoint 1.1
+# CHECK: * thread #1, name = 'minidebuginfo-s', stop reason = breakpoint 2.1
+
+# CHECK: (lldb) breakpoint list -v
+# CHECK-NEXT: Current breakpoints:
+# CHECK-NEXT: 1: name = 'multiplyByThree'
+# CHECK-NEXT:  1.1: 
+# CHECK-NEXT:  module = {{.*}}/minidebuginfo-set-and-hit-breakpoint.test.tmp.binary
+# CHECK-NEXT:  symbol = multiplyByThree
+# CHECK-NEXT:  address = 0x{{.*}}
+# CHECK-NEXT:  resolved = true
+# CHECK-NEXT:  hit count = 1 
+
+# CHECK: 2: name = 'multiplyByFour'
+# CHECK-NEXT:  2.1: 
+# CHECK-NEXT:  module = {{.*}}/minidebuginfo-set-and-hit-breakpoint.test.tmp.binary
+# CHECK-NEXT:  symbol = multiplyByFour
+# CHECK-NEXT:  address = 0x{{.*}}
+# CHECK-NEXT:  resolved = true
+# CHECK-NEXT:  hit count = 1 

lldb/lit/lit.cfg.py

 # -*- Python -*-
 
 import os
 import platform
 import re
 import shutil
 import site
 import sys
 
 import lit.formats
 from lit.llvm import llvm_config
 from lit.llvm.subst import FindTool
 from lit.llvm.subst import ToolSubst
+from distutils.spawn import find_executable
 
 site.addsitedir(os.path.dirname(__file__))
 from helper import toolchain
 
 # name: The name of this test suite.
 config.name = 'LLDB'
 
 # testFormat: The test format to use to interpret tests.
else:
         if exitcode == 0:
             for x in out.split():
                 config.available_features.add('native-cpu-%s' % x)
         else:
             lit_config.warning("lit-cpuid failed: %s" % err)
 
 if not config.lldb_disable_python:
     config.available_features.add('python')
+
+if config.lldb_enable_lzma:
+    config.available_features.add('lzma')
+
+if find_executable('xz') != None:
+    config.available_features.add('xz')

lldb/lit/lit.site.cfg.py.in

 config.lldb_libs_dir = "@LLDB_LIBS_DIR@"
 config.lldb_tools_dir = "@LLDB_TOOLS_DIR@"
 # Since it comes from the command line, it may have backslashes which
 # should not need to be escaped.
 config.lldb_lit_tools_dir = r"@LLDB_LIT_TOOLS_DIR@"
 config.target_triple = "@TARGET_TRIPLE@"
 config.python_executable = "@PYTHON_EXECUTABLE@"
 config.have_zlib = @LLVM_ENABLE_ZLIB@
+config.lldb_enable_lzma = @LLDB_ENABLE_LZMA@
 config.host_triple = "@LLVM_HOST_TRIPLE@"
 config.lldb_bitness = 64 if @LLDB_IS_64_BITS@ else 32
 config.lldb_disable_python = @LLDB_DISABLE_PYTHON@
 config.lldb_build_directory = "@LLDB_TEST_BUILD_DIRECTORY@"
 config.lldb_module_cache = "@LLDB_TEST_MODULE_CACHE_LLDB@"
 config.clang_module_cache = "@LLDB_TEST_MODULE_CACHE_CLANG@"
 
 # Support substitution of the tools and libs dirs with user parameters. This is

lldb/source/Host/CMakeLists.txt

add_host_subdirectory(common
   common/FileSystem.cpp
   common/GetOptInc.cpp
   common/Host.cpp
   common/HostInfoBase.cpp
   common/HostNativeThreadBase.cpp
   common/HostProcess.cpp
   common/HostThread.cpp
   common/LockFileBase.cpp
+  common/LZMA.cpp
   common/MainLoop.cpp
   common/MonitoringProcessLauncher.cpp
   common/NativeProcessProtocol.cpp
   common/NativeRegisterContext.cpp
   common/NativeThreadProtocol.cpp
   common/NativeWatchpointList.cpp
   common/OptionParser.cpp
   common/PipeBase.cpp
else ()
   endif()
 endif ()
 if (HAVE_LIBDL)
   list(APPEND EXTRA_LIBS ${CMAKE_DL_LIBS})
 endif()
 if (NOT LLDB_DISABLE_LIBEDIT)
   list(APPEND EXTRA_LIBS ${libedit_LIBRARIES})
 endif()
+if (LLDB_ENABLE_LZMA)
+  list(APPEND EXTRA_LIBS ${LIBLZMA_LIBRARIES})
+endif()
 
 if (NOT LLDB_DISABLE_LIBEDIT)
   list(APPEND LLDB_LIBEDIT_LIBS ${libedit_LIBRARIES})
   if (LLVM_BUILD_STATIC)
     list(APPEND LLDB_SYSTEM_LIBS gpm)
   endif()
 endif()
 

lldb/source/Host/common/LZMA.cpp

+//===-- LZMA.cpp ------------------------------------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "lldb/Host/Config.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/Error.h"
+
+#if LLDB_ENABLE_LZMA
+#include <lzma.h>
+#endif // LLDB_ENABLE_LZMA
+
+namespace lldb_private {
+
+namespace lzma {
+
+#if !LLDB_ENABLE_LZMA
+bool isAvailable() { return false; }
+llvm::Expected<uint64_t>
+getUncompressedSize(llvm::ArrayRef<uint8_t> InputBuffer) {
+  llvm_unreachable("lzma::getUncompressedSize is unavailable");
+}
+
+llvm::Error uncompress(llvm::ArrayRef<uint8_t> InputBuffer,
+                       llvm::SmallVectorImpl<uint8_t> &Uncompressed) {
+  llvm_unreachable("lzma::uncompress is unavailable");
+}
+
+#else // LLDB_ENABLE_LZMA
+
+bool isAvailable() { return true; }
+
+static const char *convertLZMACodeToString(lzma_ret Code) {
+  switch (Code) {
+  case LZMA_STREAM_END:
+    return "lzma error: LZMA_STREAM_END";
+  case LZMA_NO_CHECK:
+    return "lzma error: LZMA_NO_CHECK";
+  case LZMA_UNSUPPORTED_CHECK:
+    return "lzma error: LZMA_UNSUPPORTED_CHECK";
+  case LZMA_GET_CHECK:
+    return "lzma error: LZMA_GET_CHECK";
+  case LZMA_MEM_ERROR:
+    return "lzma error: LZMA_MEM_ERROR";
+  case LZMA_MEMLIMIT_ERROR:
+    return "lzma error: LZMA_MEMLIMIT_ERROR";
+  case LZMA_FORMAT_ERROR:
+    return "lzma error: LZMA_FORMAT_ERROR";
+  case LZMA_OPTIONS_ERROR:
+    return "lzma error: LZMA_OPTIONS_ERROR";
+  case LZMA_DATA_ERROR:
+    return "lzma error: LZMA_DATA_ERROR";
+  case LZMA_BUF_ERROR:
+    return "lzma error: LZMA_BUF_ERROR";
+  case LZMA_PROG_ERROR:
+    return "lzma error: LZMA_PROG_ERROR";
+  default:
+    llvm_unreachable("unknown or unexpected lzma status code");
+  }
+}
+
+llvm::Expected<uint64_t>
+getUncompressedSize(llvm::ArrayRef<uint8_t> InputBuffer) {
+  lzma_stream_flags opts{};
+  if (InputBuffer.size() < LZMA_STREAM_HEADER_SIZE) {
+    return llvm::createStringError(
+        llvm::inconvertibleErrorCode(),
+        "size of xz-compressed blob (%lu bytes) is smaller than the "
+        "LZMA_STREAM_HEADER_SIZE (%lu bytes)",
+        InputBuffer.size(), LZMA_STREAM_HEADER_SIZE);
+  }
+
+  // Decode xz footer.
+  lzma_ret xzerr = lzma_stream_footer_decode(
+      &opts, InputBuffer.data() + InputBuffer.size() - LZMA_STREAM_HEADER_SIZE);
+  if (xzerr != LZMA_OK) {
+    return llvm::createStringError(llvm::inconvertibleErrorCode(),
+                                   "lzma_stream_footer_decode()=%s",
+                                   convertLZMACodeToString(xzerr));
+  }
+  if (InputBuffer.size() < (opts.backward_size + LZMA_STREAM_HEADER_SIZE)) {
+    return llvm::createStringError(
+        llvm::inconvertibleErrorCode(),
+        "xz-compressed buffer size (%lu bytes) too small (required at "
+        "least %lu bytes) ",
+        InputBuffer.size(), (opts.backward_size + LZMA_STREAM_HEADER_SIZE));
+  }
+
+  // Decode xz index.
+  lzma_index *xzindex;
+  uint64_t memlimit(UINT64_MAX);
+  size_t inpos = 0;
+  xzerr =
+      lzma_index_buffer_decode(&xzindex, &memlimit, nullptr,
+                               InputBuffer.data() + InputBuffer.size() -
+                                   LZMA_STREAM_HEADER_SIZE - opts.backward_size,
+                               &inpos, InputBuffer.size());
+  if (xzerr != LZMA_OK) {
+    return llvm::createStringError(llvm::inconvertibleErrorCode(),
+                                   "lzma_index_buffer_decode()=%s",
+                                   convertLZMACodeToString(xzerr));
+  }
+
+  // Get size of uncompressed file to construct an in-memory buffer of the
+  // same size on the calling end (if needed).
+  uint64_t uncompressedSize = lzma_index_uncompressed_size(xzindex);
+
+  // Deallocate xz index as it is no longer needed.
+  lzma_index_end(xzindex, nullptr);
+
+  return uncompressedSize;
+}
+
+llvm::Error uncompress(llvm::ArrayRef<uint8_t> InputBuffer,
+                       llvm::SmallVectorImpl<uint8_t> &Uncompressed) {
+  llvm::Expected<uint64_t> uncompressedSize = getUncompressedSize(InputBuffer);
+
+  if (auto err = uncompressedSize.takeError())
+    return err;
+
+  Uncompressed.resize(*uncompressedSize);
+
+  // Decompress xz buffer to buffer.
+  uint64_t memlimit = UINT64_MAX;
+  size_t inpos = 0;
+  size_t outpos = 0;
+  lzma_ret ret = lzma_stream_buffer_decode(
+      &memlimit, 0, nullptr, InputBuffer.data(), &inpos, InputBuffer.size(),
+      Uncompressed.data(), &outpos, Uncompressed.size());
+  if (ret != LZMA_OK) {
+    return llvm::createStringError(llvm::inconvertibleErrorCode(),
+                                   "lzma_stream_buffer_decode()=%s",
+                                   convertLZMACodeToString(ret));
+  }
+
+  return llvm::Error::success();
+}
+
+#endif // LLDB_ENABLE_LZMA
+
+} // end of namespace lzma
+} // namespace lldb_private

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.h

public:
   llvm::ArrayRef<elf::ELFProgramHeader> ProgramHeaders();
   lldb_private::DataExtractor GetSegmentData(const elf::ELFProgramHeader &H);
 
   llvm::StringRef
   StripLinkerSymbolAnnotations(llvm::StringRef symbol_name) const override;
 
   void RelocateSection(lldb_private::Section *section) override;
 
 protected:
 
   std::vector<LoadableData>
   GetLoadableData(lldb_private::Target &target) override;
 
 private:
   ObjectFileELF(const lldb::ModuleSP &module_sp, lldb::DataBufferSP &data_sp,
                 lldb::offset_t data_offset, const lldb_private::FileSpec *file,
                 lldb::offset_t offset, lldb::offset_t length);
 
   ObjectFileELF(const lldb::ModuleSP &module_sp,
                 lldb::DataBufferSP &header_data_sp,
                 const lldb::ProcessSP &process_sp, lldb::addr_t header_addr);
 
   typedef std::vector<elf::ELFProgramHeader> ProgramHeaderColl;
 
private:
   ProgramHeaderColl m_program_headers;
 
   /// Collection of section headers.
   SectionHeaderColl m_section_headers;
 
   /// Collection of symbols from the dynamic table.
   DynamicSymbolColl m_dynamic_symbols;
 
+  /// Object file parsed from .gnu_debugdata section (\sa
+  /// GetGnuDebugDataObjectFile())
+  std::shared_ptr<ObjectFileELF> m_gnu_debug_data_object_file;
+
   /// List of file specifications corresponding to the modules (shared
   /// libraries) on which this object file depends.
   mutable std::unique_ptr<lldb_private::FileSpecList> m_filespec_up;
 
   /// Cached value of the entry point for this module.
   lldb_private::Address m_entry_point_address;
 
   /// The architecture detected from parsing elf file contents.
private:
   unsigned PLTRelocationType();
 
   static lldb_private::Status
   RefineModuleDetailsFromNote(lldb_private::DataExtractor &data,
                               lldb_private::ArchSpec &arch_spec,
                               lldb_private::UUID &uuid);
 
   bool AnySegmentHasPhysicalAddress();
+  
+  /// Takes the .gnu_debugdata and returns the decompressed object file that is
+  /// stored within that section.
+  ///
+  /// \returns either the decompressed object file stored within the
+  /// .gnu_debugdata section or \c nullptr if an error occured or if there's no
+  /// section with that name.
+  std::shared_ptr<ObjectFileELF> GetGnuDebugDataObjectFile();
 };
 
 #endif // liblldb_ObjectFileELF_h_

lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp

 #include <unordered_map>
 
 #include "lldb/Core/FileSpecList.h"
 #include "lldb/Core/Module.h"
 #include "lldb/Core/ModuleSpec.h"
 #include "lldb/Core/PluginManager.h"
 #include "lldb/Core/Section.h"
 #include "lldb/Host/FileSystem.h"
+#include "lldb/Host/LZMA.h"
 #include "lldb/Symbol/DWARFCallFrameInfo.h"
 #include "lldb/Symbol/SymbolContext.h"
 #include "lldb/Target/SectionLoadList.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Utility/ArchSpec.h"
 #include "lldb/Utility/DataBufferHeap.h"
 #include "lldb/Utility/Log.h"
 #include "lldb/Utility/RangeMap.h"
(InfoOr->Segment ? InfoOr->Segment->GetChildren() : *m_sections_up)
         .AddSection(section_sp);
     provider.AddSection(std::move(*InfoOr), std::move(section_sp));
   }
 
   // For eTypeDebugInfo files, the Symbol Vendor will take care of updating the
   // unified section list.
   if (GetType() != eTypeDebugInfo)
     unified_section_list = *m_sections_up;
+  
+  // If there's a .gnu_debugdata section, we'll try to read the .symtab that's
+  // embedded in there and replace the one in the original object file (if any).
+  // If there's none in the orignal object file, we add it to it.
+  if (auto gdd_obj_file = GetGnuDebugDataObjectFile()) {
+    if (auto gdd_objfile_section_list = gdd_obj_file->GetSectionList()) {
+      if (SectionSP symtab_section_sp =
+              gdd_objfile_section_list->FindSectionByType(
+                  eSectionTypeELFSymbolTable, true)) {
+        SectionSP module_section_sp = unified_section_list.FindSectionByType(
+            eSectionTypeELFSymbolTable, true);
+        if (module_section_sp)
+          unified_section_list.ReplaceSection(module_section_sp->GetID(),
+                                              symtab_section_sp);
+        else
+          unified_section_list.AddSection(symtab_section_sp);
+      }
+    }
+  }  
+}
+
+std::shared_ptr<ObjectFileELF> ObjectFileELF::GetGnuDebugDataObjectFile() {
+  if (m_gnu_debug_data_object_file != nullptr)
+    return m_gnu_debug_data_object_file;
+
+  SectionSP section =
+      GetSectionList()->FindSectionByName(ConstString(".gnu_debugdata"));
+  if (!section)
+    return nullptr;
+
+  if (!lldb_private::lzma::isAvailable()) {
+    GetModule()->ReportWarning(
+        "No LZMA support found for reading .gnu_debugdata section");
+    return nullptr;
+  }
+
+  // Uncompress the data
+  DataExtractor data;
+  section->GetSectionData(data);
+  llvm::SmallVector<uint8_t, 0> uncompressedData;
+  auto err = lldb_private::lzma::uncompress(data.GetData(), uncompressedData);
+  if (err) {
+    GetModule()->ReportWarning(
+        "An error occurred while decompression the section %s: %s",
+        section->GetName().AsCString(), llvm::toString(std::move(err)).c_str());
+    return nullptr;
+  }
+
+  // Construct ObjectFileELF object from decompressed buffer
+  DataBufferSP gdd_data_buf(
+      new DataBufferHeap(uncompressedData.data(), uncompressedData.size()));
+  auto fspec = GetFileSpec().CopyByAppendingPathComponent(
+      llvm::StringRef("gnu_debugdata"));
+  m_gnu_debug_data_object_file.reset(new ObjectFileELF(
+      GetModule(), gdd_data_buf, 0, &fspec, 0, gdd_data_buf->GetByteSize()));
+
+  // This line is essential; otherwise a breakpoint can be set but not hit.
+  m_gnu_debug_data_object_file->SetType(ObjectFile::eTypeDebugInfo);
+
+  ArchSpec spec = m_gnu_debug_data_object_file->GetArchitecture();
+  if (spec && m_gnu_debug_data_object_file->SetModulesArchitecture(spec))
+    return m_gnu_debug_data_object_file;
+  
+  return nullptr;
 }
 
 // Find the arm/aarch64 mapping symbol character in the given symbol name.
 // Mapping symbols have the form of "$<char>[.<any>]*". Additionally we
 // recognize cases when the mapping symbol prefixed by an arbitrary string
 // because if a symbol prefix added to each symbol in the object file with
 // objcopy then the mapping symbols are also prefixed.
 static char FindArmAarch64MappingSymbol(const char *symbol_name) {
   if (!symbol_name)
     return '\0';
 
   const char *dollar_pos = ::strchr(symbol_name, '$');
   if (!dollar_pos || dollar_pos[1] == '\0')
     return '\0';
 
   if (dollar_pos[2] == '\0' || dollar_pos[2] == '.')
     return dollar_pos[1];
   return '\0';
 }
 
 #define STO_MIPS_ISA (3 << 6)
 #define STO_MICROMIPS (2 << 6)
 #define IS_MICROMIPS(ST_OTHER) (((ST_OTHER)&STO_MIPS_ISA) == STO_MICROMIPS)
 
 // private
 unsigned ObjectFileELF::ParseSymbols(Symtab *symtab, user_id_t start_id,
                                      SectionList *section_list,
                                      const size_t num_symbols,
                                      const DataExtractor &symtab_data,
                                      const DataExtractor &strtab_data) {
   ELFSymbol symbol;
   lldb::offset_t offset = 0;
 
   static ConstString text_section_name(".text");
   static ConstString init_section_name(".init");
   static ConstString fini_section_name(".fini");
   static ConstString ctors_section_name(".ctors");
   static ConstString dtors_section_name(".dtors");
 
   static ConstString data_section_name(".data");
   static ConstString rodata_section_name(".rodata");
   static ConstString rodata1_section_name(".rodata1");
   static ConstString data2_section_name(".data1");
   static ConstString bss_section_name(".bss");
   static ConstString opd_section_name(".opd"); // For ppc64
 
   // On Android the oatdata and the oatexec symbols in the oat and odex files
   // covers the full .text section what causes issues with displaying unusable
   // symbol name to the user and very slow unwinding speed because the
   // instruction emulation based unwind plans try to emulate all instructions
   // in these symbols. Don't add these symbols to the symbol list as they have
   // no use for the debugger and they are causing a lot of trouble. Filtering
   // can't be restricted to Android because this special object file don't
   // contain the note section specifying the environment to Android but the
   // custom extension and file name makes it highly unlikely that this will
   // collide with anything else.
   ConstString file_extension = m_file.GetFileNameExtension();
   bool skip_oatdata_oatexec =
       file_extension == ".oat" || file_extension == ".odex";
 
   ArchSpec arch = GetArchitecture();
   ModuleSP module_sp(GetModule());
   SectionList *module_section_list =
       module_sp ? module_sp->GetSectionList() : nullptr;
if (m_symtab_up == nullptr) {
     uint64_t symbol_id = 0;
     std::lock_guard<std::recursive_mutex> guard(module_sp->GetMutex());
 
     // Sharable objects and dynamic executables usually have 2 distinct symbol
     // tables, one named ".symtab", and the other ".dynsym". The dynsym is a
     // smaller version of the symtab that only contains global symbols. The
     // information found in the dynsym is therefore also found in the symtab,
     // while the reverse is not necessarily true.
     Section *symtab =
         section_list->FindSectionByType(eSectionTypeELFSymbolTable, true).get();
-    if (!symtab) {
-      // The symtab section is non-allocable and can be stripped, so if it
-      // doesn't exist then use the dynsym section which should always be
-      // there.
-      symtab =
-          section_list->FindSectionByType(eSectionTypeELFDynamicSymbols, true)
-              .get();
-    }
     if (symtab) {
       m_symtab_up.reset(new Symtab(symtab->GetObjectFile()));
       symbol_id += ParseSymbolTable(m_symtab_up.get(), symbol_id, symtab);
     }
 
+    // The symtab section is non-allocable and can be stripped, while the
+    // .dynsym section which should always be always be there. To support the
+    // minidebuginfo case we parse .dynsym when there's a .gnu_debuginfo
+    // section, nomatter if .symtab was already parsed or not. This is because
+    // minidebuginfo normally removes the .symtab symbols which have their
+    // matching .dynsym counterparts.
+    if (!symtab ||
+        GetSectionList()->FindSectionByName(ConstString(".gnu_debugdata"))) {
+      Section *dynsym =
+          section_list->FindSectionByType(eSectionTypeELFDynamicSymbols, true)
+              .get();
+      if (dynsym) {
+        if (!m_symtab_up)
+          m_symtab_up.reset(new Symtab(dynsym->GetObjectFile()));
+        symbol_id += ParseSymbolTable(m_symtab_up.get(), symbol_id, dynsym);
+      }
+    }
+
     // DT_JMPREL
     //      If present, this entry's d_ptr member holds the address of
     //      relocation
     //      entries associated solely with the procedure linkage table.
     //      Separating
     //      these relocation entries lets the dynamic linker ignore them during
     //      process initialization, if lazy binding is enabled. If this entry is
     //      present, the related entries of types DT_PLTRELSZ and DT_PLTREL must
     //      also be present.