[Lldb-commits] [lldb] [lldb][NFC] Add documentation for SBFrame::GetRegisters (PR #125969)
Jason Molenda via lldb-commits
lldb-commits at lists.llvm.org
Wed Feb 5 21:54:26 PST 2025
https://github.com/jasonmolenda updated https://github.com/llvm/llvm-project/pull/125969
>From 7418a7074cba0ad4e28232d08b48d6d7a31c8cdb Mon Sep 17 00:00:00 2001
From: Jason Molenda <jmolenda at apple.com>
Date: Wed, 5 Feb 2025 16:12:17 -0800
Subject: [PATCH 1/4] [lldb][NFC] Add documentation for SBFrame::GetRegisters
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.
---
lldb/bindings/interface/SBFrameDocstrings.i | 16 ++++++++++++++++
lldb/bindings/interface/SBFrameExtensions.i | 4 ++--
2 files changed, 18 insertions(+), 2 deletions(-)
diff --git a/lldb/bindings/interface/SBFrameDocstrings.i b/lldb/bindings/interface/SBFrameDocstrings.i
index 05a876a685a9127..5823d332c4cdd63 100644
--- a/lldb/bindings/interface/SBFrameDocstrings.i
+++ b/lldb/bindings/interface/SBFrameDocstrings.i
@@ -78,6 +78,22 @@ See also SBThread."
See also GetFunctionName()."
) lldb::SBFrame::IsInlined;
+%feature("docstring", "
+ Returns an SBValueList which is an array of one or more register
+ sets that exist for this thread.
+ Each SBValue in the SBValueList represents one register-set.
+ The first register-set will be the general purpose registers --
+ the registers printed by the `register read` command-line lldb, with
+ no additional arguments.
+ The register-set SBValue will have a name, e.g.
+ SBFrame::GetRegisters().GetValueAtIndex(0).GetName()
+ may be 'General Purpose Registers', but the general purpose
+ register-set may not use that exact name, it is only a convention
+ used by some stubs.
+ A register-set SBValue will have children, one child per register
+ in the register-set."
+) lldb::SBFrame::GetRegisters;
+
%feature("docstring", "
Return true if this frame is artificial (e.g a frame synthesized to
capture a tail call). Local variables may not be available in an artificial
diff --git a/lldb/bindings/interface/SBFrameExtensions.i b/lldb/bindings/interface/SBFrameExtensions.i
index e0472280666ab9c..5c7a63ac53b3ec1 100644
--- a/lldb/bindings/interface/SBFrameExtensions.i
+++ b/lldb/bindings/interface/SBFrameExtensions.i
@@ -87,8 +87,8 @@ STRING_EXTENSION_OUTSIDE(SBFrame)
args = property(get_arguments, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the argument variables in this stack frame.''')
arguments = property(get_arguments, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the argument variables in this stack frame.''')
statics = property(get_statics, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the static variables in this stack frame.''')
- registers = property(GetRegisters, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the CPU registers for this stack frame.''')
- regs = property(GetRegisters, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the CPU registers for this stack frame.''')
+ registers = property(GetRegisters, None, doc='''A read only property that returns a list() of register sets for this thread. See SBFrame::GetRegisters() for details.''')
+ regs = property(GetRegisters, None, doc='''A read only property that returns a list() of register sets for this thread. See SBFrame::GetRegisters() for details.''')
register = property(get_registers_access, None, doc='''A read only property that returns an helper object providing a flattened indexable view of the CPU registers for this stack frame.''')
reg = property(get_registers_access, None, doc='''A read only property that returns an helper object providing a flattened indexable view of the CPU registers for this stack frame''')
parent = property(get_parent_frame, None, doc='''A read only property that returns the parent (caller) frame of the current frame.''')
>From 9d3668ad77a877d32bb3eb0066143ed9a3b34b91 Mon Sep 17 00:00:00 2001
From: Jason Molenda <jmolenda at apple.com>
Date: Wed, 5 Feb 2025 19:01:05 -0800
Subject: [PATCH 2/4] update the registers/regs extension text as per Jim's
suggestion
---
lldb/bindings/interface/SBFrameExtensions.i | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/lldb/bindings/interface/SBFrameExtensions.i b/lldb/bindings/interface/SBFrameExtensions.i
index 5c7a63ac53b3ec1..38d03abaee8f09e 100644
--- a/lldb/bindings/interface/SBFrameExtensions.i
+++ b/lldb/bindings/interface/SBFrameExtensions.i
@@ -87,8 +87,8 @@ STRING_EXTENSION_OUTSIDE(SBFrame)
args = property(get_arguments, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the argument variables in this stack frame.''')
arguments = property(get_arguments, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the argument variables in this stack frame.''')
statics = property(get_statics, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the static variables in this stack frame.''')
- registers = property(GetRegisters, None, doc='''A read only property that returns a list() of register sets for this thread. See SBFrame::GetRegisters() for details.''')
- regs = property(GetRegisters, None, doc='''A read only property that returns a list() of register sets for this thread. See SBFrame::GetRegisters() for details.''')
+ registers = property(GetRegisters, None, doc='''Returns the register sets for this thread as a list(). See SBFrame::GetRegisters() for details.''')
+ regs = property(GetRegisters, None, doc='''Returns the register sets for this thread as a list(). See SBFrame::GetRegisters() for details.''')
register = property(get_registers_access, None, doc='''A read only property that returns an helper object providing a flattened indexable view of the CPU registers for this stack frame.''')
reg = property(get_registers_access, None, doc='''A read only property that returns an helper object providing a flattened indexable view of the CPU registers for this stack frame''')
parent = property(get_parent_frame, None, doc='''A read only property that returns the parent (caller) frame of the current frame.''')
>From 02fef73e22c9d662c7a43ba1839cd08f301a0fcb Mon Sep 17 00:00:00 2001
From: Jason Molenda <github-mail at molenda.com>
Date: Wed, 5 Feb 2025 21:52:48 -0800
Subject: [PATCH 3/4] Update lldb/bindings/interface/SBFrameDocstrings.i
Co-authored-by: Will Hawkins <whh8b at obs.cr>
---
lldb/bindings/interface/SBFrameDocstrings.i | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/lldb/bindings/interface/SBFrameDocstrings.i b/lldb/bindings/interface/SBFrameDocstrings.i
index 5823d332c4cdd63..38d10974a4d20c9 100644
--- a/lldb/bindings/interface/SBFrameDocstrings.i
+++ b/lldb/bindings/interface/SBFrameDocstrings.i
@@ -87,7 +87,7 @@ See also SBThread."
no additional arguments.
The register-set SBValue will have a name, e.g.
SBFrame::GetRegisters().GetValueAtIndex(0).GetName()
- may be 'General Purpose Registers', but the general purpose
+By convention, certain stubs choose to name their general-purpose register-set the 'General Purpose Registers', but that is not required.
register-set may not use that exact name, it is only a convention
used by some stubs.
A register-set SBValue will have children, one child per register
>From 51b217c66fc4f8c68d232e1f218bfc86f8d7fa83 Mon Sep 17 00:00:00 2001
From: Jason Molenda <github-mail at molenda.com>
Date: Wed, 5 Feb 2025 21:54:16 -0800
Subject: [PATCH 4/4] Update lldb/bindings/interface/SBFrameDocstrings.i
Co-authored-by: Will Hawkins <whh8b at obs.cr>
---
lldb/bindings/interface/SBFrameDocstrings.i | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/lldb/bindings/interface/SBFrameDocstrings.i b/lldb/bindings/interface/SBFrameDocstrings.i
index 38d10974a4d20c9..723c1da7c26e2dc 100644
--- a/lldb/bindings/interface/SBFrameDocstrings.i
+++ b/lldb/bindings/interface/SBFrameDocstrings.i
@@ -83,7 +83,7 @@ See also SBThread."
sets that exist for this thread.
Each SBValue in the SBValueList represents one register-set.
The first register-set will be the general purpose registers --
- the registers printed by the `register read` command-line lldb, with
+ the registers printed by the `register read` command-line in lldb, with
no additional arguments.
The register-set SBValue will have a name, e.g.
SBFrame::GetRegisters().GetValueAtIndex(0).GetName()
More information about the lldb-commits
mailing list