This is a (rough) port of architecture/varformats.html page that got
lost during the migration to RST in edb874b. I'm not sure how much of
its content is still relevant today. However, the page is pretty
extensive and seems like it's worth preserving.
Neither actually linked anywhere, but I did find a good target for the
introduction.
For the architecture side I don't see a page that would fit, so I've
just removed the sentence.
The testing page already has some page about debugging failures.
I'm not linking directly to that section because:
* The earlier sections about running single tests and such
are just as useful for debugging in general.
* The new theme has a nice sidebar on the right that makes
it really easy to find what you want once on the page.
* We'll probably add more content to the testing page later.
In the LDDB documentation you have the following sentence:
"The --format (which you can shorten to -f) option accepts a format name."
The link points to the wrong place.
I pointed it to the table that precedes the Type summary section.
Reviewed By: DavidSpickett
Differential Revision: https://reviews.llvm.org/D151668
The issues link as it was was including PRs, so I've made that
issues only and only those in an open state.
Code review is now on Gtihub so same thing, PRs only, open state,
label lldb.
Adds the following:
* A note that you can use attaching to debug the right lldb-server
process, though there are drawbacks.
* A section on debugging the remote protocol.
* Reducing bugs, including reducing ptrace bugs to remove the need for
LLDB.
I've added a standlone ptrace program to the examples folder because:
* There's no better place to put it.
* Adding it to the page seems like wasting space, and would be harder to
update.
* I link to Eli Bendersky's classic blog on the subject, but we are
safer with our own example as well.
* Eli's example is for 32 bit Intel, AArch64 is more common these days.
* It's easier to show the software breakpoint steps in code than explain
it (though I still do that in the text).
* It was living on my laptop not helping anyone so I think it's good to
have it upstream for others, including future me.
We have docs about how to use lldb on other programs, this tells you how
to use lldb on ldlb and lldb-server.
Lacking any Mac experience I've not included any debugserver information
apart from stating it will be similar but not the same.
I plan for this page to include sections on debugging tests and other
things but this initial commit is purely about the two main binaries
involved.
The main way I cross build lldb is to point CMake at an existing host
build to get the native tablegen tools. This is what we had documented
before.
There is another option where you start from scratch and the host tools
are built for you. This patch documents that and explains which one to
choose.
Added another arm64 example which uses this. So the frst one is the
"automatic" build and the second is the traditional approach.
For ease of copy paste and understanding, I've kept the full command in
each section and noted the one difference between them.
Along the way I updated some of the preamble to explain the two
approaches and updated some language e.g. removing "just ...". Eveyone's
"just" is different, doubly so when cross-compiling.
This patch re-lands f0731d5b61ba with more fixes and improvements.
First, this patch removes `__eq__` implementations from classes that
didn't implemented `operator!=` on the C++ implementation.
This patch removes sphinx document generation for special members such
as `__len__`, since there is no straightforward way to skip class that
don't implement them. We also don't want to introduce a change in
behavior by implementing artifical special members for classes that are
missing them.
Finally, this patch improve the ergonomics of some classes by
implementing special members where it makes sense, i.e. `hex(SBFrame)`
is equivalent to `SBFrame.GetPC()`.
Differential Revision: https://reviews.llvm.org/D159017
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This reverts 3 commit:
- f0731d5b61ba798e6d5a63a92d9228010e5a3b50.
- 8e0a087571a31057bb98939e3ada73227bed83c7.
- f2f5d6fb8d53bc4bd93a3d4e110134ed017b636f.
This changes were introduced to silence the warnings that are printed
when generating the lldb module documentation for the website but it
changed the python bindings and causes test failures on the macos bot:
https://green.lab.llvm.org/green/job/lldb-cmake/59438/
We will have to consider other options to silence these warnings.
This reverts commit 18f1c1ace7a6099f3e8e56cf4b81aa0f64a7dd23 and fix the
build failure issues introduced because of the `STRING_EXTENSION_OUTSIDE`
swig macros.
Differential Revision: https://reviews.llvm.org/D159017
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch does various things to silence the warnings that show up when
generating the website documentation.
First, this patch adds the missing definition for special member methods
in every SBAPI class. If the class cannot implement one of the special
member method, we just define it as a null operation (pass).
This should fix the following warnings:
```
WARNING: missing attribute __int__ in object lldb.SB*
WARNING: missing attribute __len__ in object lldb.SB*
WARNING: missing attribute __hex__ in object lldb.SB*
WARNING: missing attribute __oct__ in object lldb.SB*
WARNING: missing attribute __iter__ in object lldb.SB*
```
Then, it un-skips the various `static` methods that we didn't generate
the methods for, since it's not necessary thanks to the automod-api module.
Finally, this comments out the `_static` directory in the sphinx config,
since we don't need it anymore.
Differential Revision: https://reviews.llvm.org/D159017
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch reverts the lldb website revamp (eea8874) since the `furo` theme
that we use is not installed on the publisher bot. The prevents other
website from getting there documentation updated.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
To address https://github.com/llvm/llvm-project/issues/64616, this change
does the following:
* Links back to the "Optional Dependencies" section from the cross
compilation instructions where we talk about removing libraries.
In the reported issue, the host libXML was found by CMAke somehow and
disabling libXML fixed it, so this link should encourage users
to try as many of those options as needed.
* Removes the use of CMAKE_CROSS_COMPILING. In older CMake versions
it seems you could set this manually but now the advice is to set
CMAKE_SYSTEM_NAME and CMAKE_SYSTEM_PROCESSOR then let CMake figure
it out.
There is also CMAKE_SYSTEM_VERSION which the docs say you have to
set too, but I can only find examples of Windows and Android builds
using this. It might be needed to "cross" compile from one version
of AArch64 Linux to another, but I can't confirm that.
* Removes the tablegen tools paths in favour of DLLVM_NATIVE_TOOL_DIR.
This one setting deals with all build tools in llvm that must be host
versions.
* Updates the explanations of the common options and orders them
in some rough order of relevance with the "might be needed" later.
Reviewed By: JDevlieghere, bulbazord
Differential Revision: https://reviews.llvm.org/D158085
Feedback I hear regularly is that the LLDB website is hard to navigate.
This patch is an attempt to simplify things by breaking the website up
in 3 major areas: "Using LLDB", "Scripting LLDB" and "Developing LLDB".
- The majority of the "project" pages were eliminated. The projects
page was moved under "Developing LLDB". The releases page was
replaced with a link under "External links". The other pages (goals,
features and status) were pretty outdated and while they probably
made sense in the past, they don't feel all that relevant anymore
now that LLDB is an established debugger.
- "USE & EXTENSION" was renamed to "Using LLDB". Besides that, this
section remained mostly unchanged. The exception are the Python
pages which were moved under "Scripting LLDB".
- "Development" was renamed to "Developing LLDB" and now houses all the
resources for LLDB developers. The old "Design" section (which only
contained two pages) was moved back under here too.
Differential revision: https://reviews.llvm.org/D158023
Add support for the `low_mem_addressing_bits` and
`high_mem_addressing_bits` keys in the stop reply packet,
in addition to the existing `addressing_bits`. Same
behavior as in the qHostInfo packet.
Clean up AddressableBits so we don't need to check if
any values have been set in the object before using it
to potentially update the Process address masks.
Differential Revision: https://reviews.llvm.org/D158041
On AArch64 systems, we may have different page table setups for
low memory and high memory, and therefore a different number of
bits used for addressing depending on which half of memory the
address is in.
This patch extends the qHostInfo and LC_NOTE "addrable bits" so
that it can specify the number of addressing bits in high memory
and in low memory separately. It builds on the patch I added in
https://reviews.llvm.org/D151292 where Process tracks the separate
address masks, and there is a user setting to set them manually.
Differential Revision: https://reviews.llvm.org/D157667
rdar://113225907
These were useful primarily for the Python 2 to 3 transition. Python 2
is no longer supported so these are no longer necessary.
Differential Revision: https://reviews.llvm.org/D157759
SWIG 4 was released in 2019 and has been the de-facto standard for a
while now. All bots are running SWIG 4.0 or later.
This was motivated by #64279 which discovered that 662548c broke the
LLDB build with SWIG 3 on Windows.
Differential revision: https://reviews.llvm.org/D156804
This patch should allow the user to set specific auto-completion type
for their custom commands.
To do so, we had to hoist the `CompletionType` enum so the user can
access it and add a new completion type flag to the CommandScriptAdd
Command Object.
So now, the user can specify which completion type will be used with
their custom command, when they register it.
This also makes the `crashlog` custom commands use disk-file completion
type, to browse through the user file system and load the report.
Differential Revision: https://reviews.llvm.org/D152011
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This is an ongoing series of commits that are reformatting our Python
code. Reformatting is done with `black` (23.1.0).
If you end up having problems merging this commit because you have made
changes to a python file, the best way to handle that is to run `git
checkout --ours <yourfile>` and then reformat it with black.
RFC: https://discourse.llvm.org/t/rfc-document-and-standardize-python-code-style
Differential revision: https://reviews.llvm.org/D151460
LLDB should guarantee that the strings returned by SBAPI methods
live forever. I went through every method that returns a string and made
sure that it was added to the ConstString StringPool before returning if
it wasn't obvious that it was already doing so.
I've also updated the docs to document this behavior.
Differential Revision: https://reviews.llvm.org/D150804
The documentation should have been updated in 662548c82683.
This updates it to be more accurate with the current design.
Differential Revision: https://reviews.llvm.org/D150630
Whether assertions are enabled or not is orthogonal to the build type
which could lead to surprising behavior for lldbassert. Previously, when
doing a debug build with assertions disabled, lldbassert would become a
NOOP, rather than printing an error like it does in a release build. By
definining lldbassert in terms of NDEBUG, it behaves like a regular
assert when assertions are enabled, and like a soft assert.
Differential revision: https://reviews.llvm.org/D150639
Update the documentation to reference lldbassert rather than
lldb_assert. The latter is the implementation, which shouldn't be used
directly. Instead, users should use lldbassert which is the macro that
expands to assert or lldb_assert depending on the build type.
jGetLoadedDynamicLibrariesInfos has a mode where it will list
every binary in the process - the load address and filepath from dyld
SPI, and the mach-o header and load commands from a scan by debugserver
for perf reasons. With a large enough number of libraries, creating
that StructuredData representation of all of this, and formatting it
into an ascii string to send up to lldb, can grow debugserver's heap
size too large for some environments.
This patch adds a new report_load_commands:false boolean to the
jGetLoadedDynamicLibrariesInfos packet, where debugserver will now
only report the dyld SPI load address and filepath for all of the
binaries. lldb can then ask for the detailed information on
the process binaries in smaller chunks, and avoid debugserver
having ever growing heap use as the number of binaries inevitably
increases.
This patch also removes a version of jGetLoadedDynamicLibrariesInfos
for pre-iOS 10 and pre-macOS 10.12 systems where we did not use
dyld SPI. We can't back compile to those OS builds any longer
with modern Xcode.
Finally, it removes a requirement in DynamicLoaderMacOS that the
JSON reply from jGetLoadedDynamicLibrariesInfos include the
mod_date field for each binary. This has always been reported as
0 in modern dyld, and is another reason for packet growth in
the reply. debugserver still puts the mod_date field in its replies
for interop with existing lldb's, but we will be able to remove it
the field from debugserver's output after the next release cycle
when this patch has had time to circulate.
I'll add lldb support for requesting the load addresses only
and splitting the request up into chunks in a separate patch.
Differential Revision: https://reviews.llvm.org/D150158
rdar://107848326
Modular just announced a new language called Mojo. This patch adds an entry in the language list in LLDB for minimal support (e.g. being able to create a TypeSystem for this language). We will later add debug info entries when the language matures.
If a remote stub provides the addressing_bits kv pair in
the stop reply packet, update the Process address masks with
that value as it possibly changes during the process runtime.
This is an unusual situation, most likely a JTAG remote stub
and some very early startup code that is setting up the page
tables. Nearly all debug sessions will have a single address
mask that cannot change during the lifetime of a Process.
Differential Revision: https://reviews.llvm.org/D149803
rdar://61900565
They don't convey any useful information and make the documentation
unnecessarily hard to read.
Differential Revision: https://reviews.llvm.org/D149641
Watchpoints from lldb-server are sent in the stop info packet
as a `reason:watchpoint` and `description:asciihex` keys; the
latter's asciihex has one to three integer values. This patch
documents the purpose of those three different numbers, and
clarifies the behavior on MIPS with the third number which is
outside the range of any watched memory range means to silently
skip the watchpoint.
lldb was previously using this silently skip watchpoint behavior
for AArch64 as well, but in the case of AArch64 we see a watchpoint
address outside of a watched memory range when the write BEGINS
before the watched memory range, but extends in to it. We don't
want to silently skip these.
Differential Revision: https://reviews.llvm.org/D147816
rdar://83996471
