This pr fixes#167388 .
## Description
This pr adds new method `GetArchName` to `SBTarget` so that no need to
parse triple to get arch name in client code.
## Testing
### All from `TestTargetAPI.py`
run test with
```
./build/bin/lldb-dotest -v -p TestTargetAPI.py
```
<details>
<summary>existing tests (without newly added)</summary>
<img width="1425" height="804" alt="image"
src="https://github.com/user-attachments/assets/617e4c69-5c6b-44c4-9aeb-b751a47e253c"
/>
</details>
<details>
<summary>existing tests (with newly added)</summary>
<img width="1422" height="778" alt="image"
src="https://github.com/user-attachments/assets/746990a1-df88-4348-a090-224963d3c640"
/>
</details>
### Only `test_get_arch_name`
run test with
```
./build/bin/lldb-dotest -v -p TestTargetAPI.py -f test_get_arch_name_dwarf -f test_get_arch_name_dwo -f test_get_arch_name_dsym lldb/test/API/python_api/target
```
<details>
<summary>only newly added</summary>
<img width="1422" height="778" alt="image"
src="https://github.com/user-attachments/assets/fcaafa5d-2622-4171-acee-e104ecee0652"
/>
</details>
---------
Signed-off-by: Nikita B <n2h9z4@gmail.com>
Co-authored-by: Jonas Devlieghere <jonas@devlieghere.com>
I've been working on some scripts that evaluate the parent and child
frame. It's been very annoying that the parent frame has a property but
not the child. So I've added this to the extensions, I would've
preferred to return None, but because the existing impl returns an
invalid SBFrame, so I'm conforming to that API.
```
(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> lldb.frame
frame #0: 0x0000555555555200 fib.out`main
>>> lldb.frame.parent
frame #1: 0x00007ffff782a610 libc.so.6`__libc_start_call_main + 128
>>> lldb.frame.parent.child
frame #0: 0x0000555555555200 fib.out`main
```
This patch introduces `SBFrameList`, a new SBAPI class that allows
iterating over stack frames lazily without calling
`SBThread::GetFrameAtIndex` in a loop.
The new `SBThread::GetFrames()` method returns an `SBFrameList` that
supports Python iteration (`for frame in frame_list:`), indexing
(`frame_list[0]`, `frame_list[-1]`), and length queries (`len()`).
The implementation uses `StackFrameListSP` as the opaque pointer,
sharing the thread's underlying frame list to ensure frames are
materialized on-demand.
This is particularly useful for ScriptedFrameProviders, where user
scripts will be to iterate, filter, and replace frames lazily without
materializing the entire stack upfront.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
When we restart a process, send an updated 'process' event describing
the newly launched process.
I also updated the `isLocalProcess` value based on if we're on the
'host' platform or not.
Earlier today I was looking at the SBProgress documentation with a
colleague and found another instance where the swig block wasn't
formatting correctly. I've adjusted the docs slightly to fix this. I
don't actually know how to see a preview of our docstrings but I believe
this will fix it.
<img width="829" height="234" alt="image"
src="https://github.com/user-attachments/assets/8ef3a2df-92b9-4157-a452-f5e1ec51aa9a"
/>
* Adds `dynamic` property to automatically convert `SBStructuredData`
instances to the associated Python type (`str`, `int`, `float`, `bool`,
`NoneType`, etc)
* Implements `__getitem__` for Pythonic array and dictionary
subscripting
* Subscripting return the result of the `dynamic` property
* Updates `__iter__` to support dictionary instances (supporting `for`
loops)
* Adds `__str__`, `__int__`, and `__float__`
With these changes, these two expressions are equal:
```py
data["name"] == data.GetValueForKey("name").GetStringValue(1024)
```
**Note**: Unlike the original commit (#155061), this re-commit removes
the `__bool__` implementation, which broke crashlog. Somewhere in the
crashlog execution, it depends on `__bool__` meaning only `IsValid()`.
Additionally did some cleanup in TestStructuredDataAPI.py.
`__str__` was implemented in #155061, however its behavior was limited
to only a some kinds of `SBStructuredData`. That was a breaking change,
and this change removes that implementation of `__str__`, relying on the
existing behavior which calls `GetDescription`.
* Adds `dynamic` property to automatically convert `SBStructuredData`
instances to the associated Python type (`str`, `int`, `float`, `bool`,
`NoneType`, etc)
* Implements `__getitem__` for Pythonic array and dictionary
subscripting
* Subscripting return the result of the `dynamic` property
* Updates `__iter__` to support dictionary instances (supporting `for`
loops)
* Adds conversion to `str`, `int`, and `float`
* Adds Pythonic `bool` conversion
With these changes, these two expressions are equal:
```py
data["name"] == data.GetValueForKey("name").GetStringValue(1024)
```
Additionally did some cleanup in TestStructuredDataAPI.py.
Updated SBMemoryRegionInfo doc strings:
- Added detailed documentation for the GetDescription() method.
- Included information about the overwritten len() and str() functions
for the SBMemoryRegionInfo type, explaining their behavior and usage.
---------
Co-authored-by: Bar Soloveychik <barsolo@fb.com>
### Context
Over a year ago, I landed support for 64b Memory ranges in Minidump
(#95312). In this patch we added the Memory64 list stream, which is
effectively a Linked List on disk. The layout is a sixteen byte header
and then however many Memory descriptors.
### The Bug
This is a classic off-by one error, where I added 8 bytes instead of 16
for the header. This caused the first region to start 8 bytes before the
correct RVA, thus shifting all memory reads by 8 bytes. We are correctly
writing all the regions to disk correctly, with no physical corruption
but the RVA is defined wrong, meaning we were incorrectly reading memory
### Why wasn't this caught?
One problem we've had is forcing Minidump to actually use the 64b mode,
it would be a massive waste of resources to have a test that actually
wrote >4.2gb of IO to validate the 64b regions, and so almost all
validation has been manual. As a weakness of manual testing, this issue
is psuedo non-deterministic, as what regions end up in 64b or 32b is
handled greedily and iterated in the order it's laid out in
/proc/pid/maps. We often validated 64b was written correctly by
hexdumping the Minidump itself, which was not corrupted (other than the
BaseRVA)
### Why is this showing up now?
During internal usage, we had a bug report that the Minidump wasn't
displaying values. I was unable to repro the issue, but during my
investigation I saw the variables were in the 64b regions which resulted
in me identifying the bug.
### How do we prevent future regressions?
To prevent regressions, and honestly to save my sanity for figuring out
where 8 bytes magically came from, I've added a new API to
SBSaveCoreOptions.
```SBSaveCoreOptions::GetMemoryRegionsToSave()```
The ability to get the memory regions that we intend to include in the Coredump. I added this so we can compare what we intended to include versus what was actually included. Traditionally we've always had issues comparing regions because Minidump includes `/proc/pid/maps` and it can be difficult to know what memoryregion read failure was a genuine error or just a page that wasn't meant to be included.
We are also leveraging this API to choose the memory regions to be generated, as well as for testing what regions should be bytewise 1:1.
After much debate with @clayborg, I've moved all non-stack memory to the Memory64 List. This list doesn't incur us any meaningful overhead and Greg originally suggested doing this in the original 64b PR. This also means we're exercising the 64b path every single time we save a Minidump, preventing regressions on this feature from slipping through testing in the future.
Snippet produced by [minidump.py](https://github.com/clayborg/scripts)
```
MINIDUMP_MEMORY_LIST:
NumberOfMemoryRanges = 0x00000002
MemoryRanges[0] = [0x00007f61085ff9f0 - 0x00007f6108601000) @ 0x0003f655
MemoryRanges[1] = [0x00007ffe47e50910 - 0x00007ffe47e52000) @ 0x00040c65
MINIDUMP_MEMORY64_LIST:
NumberOfMemoryRanges = 0x000000000000002e
BaseRva = 0x0000000000042669
MemoryRanges[0] = [0x00005584162d8000 - 0x00005584162d9000)
MemoryRanges[1] = [0x00005584162d9000 - 0x00005584162db000)
MemoryRanges[2] = [0x00005584162db000 - 0x00005584162dd000)
MemoryRanges[3] = [0x00005584162dd000 - 0x00005584162ff000)
MemoryRanges[4] = [0x00007f6100000000 - 0x00007f6100021000)
MemoryRanges[5] = [0x00007f6108800000 - 0x00007f6108828000)
MemoryRanges[6] = [0x00007f6108828000 - 0x00007f610899d000)
MemoryRanges[7] = [0x00007f610899d000 - 0x00007f61089f9000)
MemoryRanges[8] = [0x00007f61089f9000 - 0x00007f6108a08000)
MemoryRanges[9] = [0x00007f6108bf5000 - 0x00007f6108bf7000)
```
### Misc
As a part of this fix I had to look at LLDB logs a lot, you'll notice I added `0x` to many of the PRIx64 `LLDB_LOGF`. This is so the user (or I) can directly copy paste the address in the logs instead of adding the hex prefix themselves.
Added some SBSaveCore tests for the new GetMemoryAPI, and Docstrings.
CC: @DavidSpickett, @da-viper @labath because we've been working together on save-core plugins, review it optional and I didn't tag you but figured you'd want to know
Add a class property for the version string. This allows you to use
access the version string through `lldb.SBDebugger.version` instead of
having to call `lldb.SBDebugger.GetVersionString()`.
My current internal work requires some sensitivity to IO usage. I had a
work around to calculate the expected size of a Minidump, but I've added
this PR so an automated system could look at the expected size of an
LLDB generated Minidump and then choose if it has the space or wants to
generate it.
There are some prerequisites to calculating the correct size, so I have
the API take a reference for an SBError, I originally tried to return an
SBError and instead take a uint64_t reference, but this made the API
very difficult to use in python.
Added a test case as well.
Expose u target API mutex through the SB API. This is motivated by
lldb-dap, which is built on top of the SB API and needs a way to execute
a series of SB API calls in an atomic manner (see #131242).
We can solve this problem by either introducing an additional layer of
locking at the DAP level or by exposing the existing locking at the SB
API level. This patch implements the second approach.
This was discussed in an RFC on Discourse [0]. The original
implementation exposed a move-only lock rather than a mutex [1] which
doesn't work well with SWIG 4.0 [2]. This implement the alternative
solution of exposing the mutex rather than the lock. The SBMutex
conforms to the BasicLockable requirement [3] (which is why the methods
are called `lock` and `unlock` rather than Lock and Unlock) so it can be
used as `std::lock_guard<lldb::SBMutex>` and
`std::unique_lock<lldb::SBMutex>`.
[0]: https://discourse.llvm.org/t/rfc-exposing-the-target-api-lock-through-the-sb-api/85215/6
[1]: https://github.com/llvm/llvm-project/pull/131404
[2]: https://discourse.llvm.org/t/rfc-bumping-the-minimum-swig-version-to-4-1-0/85377/9
[3]: https://en.cppreference.com/w/cpp/named_req/BasicLockable
We recently added an explicit finalize to SBProgress, #128966. I
realized while adding some additional implementations of SBProgress that
we should to add `with` support for ease of use. This patch addresses
adding and `__enter()__` method (which a no-op) and an `__exit()__` to
swig. I also refactor the emitter for the test to leverage `with`
instead of explicitly calling finalize, and I've updated the docstrings.
This patch adds a finalize method which destroys the underlying RAII
SBProgress. My primary motivation for this is so I can write better
tests that are non-flaky, but after discussing with @clayborg in my DAP
message improvement patch (#124648) this is probably an essential API
despite that I originally argued it wasn't.
SBFrame::GetRegisters() (and the .registers / .regs extensions in
Python) returns an array of register-set's, not registers like you might
expect from the API name. Document this.
---------
Co-authored-by: Will Hawkins <whh8b@obs.cr>
My colleague, @lukejriddle made the SBMemoryRegionList object iterable
in #117358. This isn't documented anywhere and so I added a blurb about
it to SBProcess.
In my last attempt at this (#123873), I didn't realize we needed semi
colons! Also fixed the bug that the feature summary didn't have a type
defined.
CC @JDevlieghere hope you get a laugh at needing to revert doc strings
for breaking the build....
Adds a `selected_frame` property to `SBThread`. The setter accepts either a frame index (like `SetSelectedFrame`), or a frame object.
Updates a few tests to make use of the new `selected_frame`. While doing so I noticed some of the usage could be cleaned up, so I did that too.
SBSaveCoreOptions has been around for awhile now, so I decided to draft
up some Docstrings describing the functionality better. Some of my
wording sounded a bit clunky due the optionality of each method call so
I would greatly appreciate feedback.
Includes the new method in #122541 so I will merge this as a follow up.
Recently I've been working on a lot of internal Python tooling, and in
certain cases I want to report async to the script over DAP. Progress.h
already handles this, so I've exposed Progress via the SB API so Python
scripts can also update progress objects.
I actually have no idea how to test this, so I just wrote a [toy command
to test
it](https://gist.github.com/Jlalond/48d85e75a91f7a137e3142e6a13d0947)
I also copied the first section of the extensive Progress.h class
documentation to the docstrings.
Introduces a `member` property to `SBValue`. This property provides pythonic access to a
value's members, by name. The expression `value.member["name"]` will be an alternate
form form of writing `value.GetChildMemberWithName("name")`.
This PR fixes a simple SWIG issue with SBMemoryRegionInfoList not being
iterable out-of-the-box. This is mostly because of limitations to the
`lldb_iter` function, which doesn't allow for specifying arguments to
the size / iter functions passed.
Before:
```
(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> for region in lldb.process.GetMemoryRegions():
... print(region)
...
Traceback (most recent call last):
File "<console>", line 1, in <module>
File "/opt/llvm/stable/Toolchains/llvm-sand.xctoolchain/usr/lib/python3.10/site-packages/lldb/__init__.py", line 114, in lldb_iter
yield elem(i)
TypeError: SBMemoryRegionInfoList.GetMemoryRegionAtIndex() missing 1 required positional argument: 'region_info'
```
After:
```
(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> for region in lldb.process.GetMemoryRegions():
... print(region)
...
[0x0000000000200000-0x00000000002cf000 R--]
[0x00000000002cf000-0x0000000000597000 R-X]
[0x0000000000597000-0x00000000005ad000 R--]
[0x00000000005ad000-0x00000000005b1000 RW-]
[0x00000000005b1000-0x0000000000b68000 RW-]
[0x000000007fff7000-0x000000008fff7000 RW-]
[0x000002008fff7000-0x000010007fff8000 RW-]
[0x0000503000000000-0x0000503000010000 RW-]
[0x0000503e00000000-0x0000503e00010000 RW-]
[0x0000504000000000-0x0000504000010000 RW-]
[0x0000504e00000000-0x0000504e00010000 RW-]
[0x000050d000000000-0x000050d000010000 RW-]
[0x000050de00000000-0x000050de00010000 RW-]
[0x000050e000000000-0x000050e000010000 RW-]
[0x000050ee00000000-0x000050ee00010000 RW-]
[0x0000511000000000-0x0000511000010000 RW-]
[0x0000511e00000000-0x0000511e00010000 RW-]
[0x0000513000000000-0x0000513000010000 RW-]
...
```
First, `SRE_Pattern` does not exist on newer Python's, use
`type(re.compile(''))` like other Python extensions do. The dynamic type
is because some earlier versions of Python 3 do not have `re.Pattern`.
Second, `SBModule` has a `file` property, not a `path` property.
There is no need to support Python 2.7 anymore, Python 3.3+ has
`subprocess.DEVNULL`. This is good practice and also prevents file
handles from
staying open unnecessarily.
Also remove a couple unused or unneeded `__future__` imports.
This PR adds `SBSaveCoreOptions`, which is a container class for options
when LLDB is taking coredumps. For this first iteration this container
just keeps parity with the extant API of `file, style, plugin`. In the
future this options object can be extended to allow users to take a
subset of their core dumps.
from PEP8
(https://peps.python.org/pep-0008/#programming-recommendations):
> Comparisons to singletons like None should always be done with is or
is not, never the equality operators.
Co-authored-by: Eisuke Kawashima <e-kwsm@users.noreply.github.com>
This is useful if you have a transcript of a user session and want to
rerun those commands with RunCommandInterpreter. The same functionality
is also useful in testing.
I'm adding it primarily for the second reason. In a subsequent patch,
I'm adding the ability to Python based commands to provide their
"auto-repeat" command. Among other things, that will allow potentially
state destroying user commands to prevent auto-repeat. Testing this with
Shell or pexpect tests is not nearly as accurate or convenient as using
RunCommandInterpreter, but to use that I need to allow auto-repeat.
I think for consistency's sake, having interactive sessions always do
auto-repeats is the right choice, though that's a lightly held
opinion...
This adds new SB API calls and classes to allow a user of the SB API to obtain an address range from SBFunction and SBBlock. This is a second attempt to land the reverted PR #92014.
I previously added this API via https://reviews.llvm.org/D142792 in
2023, along with changes to the ValueObject class to treat pointer types
as addresses, and to annotate those ValueObjects with the original
uint64_t byte sequence AND the name of the symbol once stripped, if that
points to a symbol.
I did this unconditionally for all pointer type ValueObjects, and it
caused several regressions in the Objective-C data formatters which have
a ValueObject of an object, it has the address of its class -- but with
ObjC, sometimes it is a "tagged pointer" which is metadata, not an
actual pointer. (e.g. a small NSInteger value is stored entirely in the
tagged pointer, instead of a separate object) Treating these
not-addresses as addresses -- clearing the non-addressable-bits -- is
invalid.
The original version of this patch we're using downstream only does this
bits clearing for pointer types that are specifically decorated with the
pointerauth typequal, but not all of those clang changes are upstreamed
to github main yet, so I tried this simpler approach and hit the tagged
pointer issue and bailed on the whole patch.
This patch, however, is simply adding SBValue::GetValueAsAddress so
script writers who know that an SBValue has an address in memory, can
strip off any metadata. It's an important API to have for script writers
when AArch64 ptrauth is in use, so I'm going to put this part of the
patch back on github main now until we can get the rest of that original
patch upstreamed.
The only change is a fix for the "register" iterator test to not rely on
particular register names.
I mistook where the artificial "pc" register is generated. It isn't
added to the register list or the register sets (except on arm where
that's the name of the actual register), so I can't use it in this test.
I instead just assert that the "register" generator produces the same
list as flattening the register sets from "registers".
This reverts commit 9f14914753599f3879e4c273191959e2f1b3632c.
The code returned lldb.SBValue() when you passed in an unrecognized
register name. But referring to "lldb" is apparently not legal within
the module.
I changed this to just return SBValue(), but then this construct:
(lldb) script
>>> for reg_set in lldb.target.process.thread[0].frames[0].register
... print(reg)
Runs forever printing "No Value". The __getitem__(key) gets called with
a monotonically increasing by 1 series of integers. I don't know why
Python decided the class we defined should have a generator that returns
positive integers in order, but we can add a more useful one here by
returning an iterator over the flattened list of registers.
Note, the not very aptly named "SBFrame.registers" is an iterator over
register sets, not registers, so the two are not redundant.
Some of the SB API method description docstrings for swing are annotated
as `%feature("autodoc")` - but `"autodoc"` annotations are only to
substitute a string showing the arguments and return variables - either
in a single line, or in multiple lines. SBMemoryRegionInfo used
`"autodoc"` correctly describing the parameters and return type, but
then it added a description too which is not correct either.
Change all of these that are adding a method description to use
`%feature("docstring")` instead. There were a half dozen instances where
`"autodoc"` was correctly being used and we have overriden the parameter
and return types with a more readable version.
Updates:
- The previous patch changed the default behavior to not load dwos in
`DWARFUnit`
~~`SymbolFileDWARFDwo *GetDwoSymbolFile(bool load_all_debug_info =
false);`~~
`SymbolFileDWARFDwo *GetDwoSymbolFile(bool load_all_debug_info = true);`
- This broke some lldb-shell tests (see
https://green.lab.llvm.org/green/view/LLDB/job/as-lldb-cmake/16273/)
- TestDebugInfoSize.py
- with symbol on-demand, by default statistics dump only reports
skeleton debug info size
- `statistics dump -f` will load all dwos. debug info = skeleton debug
info + all dwo debug info
Currently running `statistics dump` will trigger lldb to load debug info
that's not yet loaded (eg. dwo files). Resulted in a delay in the
command return, which, can be interrupting.
This patch also added a new option `--load-all-debug-info` asking
statistics to dump all possible debug info, which will force loading all
debug info available if not yet loaded.
