[Lldb-commits] [lldb] [LLDB] Update SBMemoryRegionInfo doc strings to document len and str (PR #149903)
via lldb-commits
lldb-commits at lists.llvm.org
Tue Jul 22 11:44:18 PDT 2025
https://github.com/barsolo2000 updated https://github.com/llvm/llvm-project/pull/149903
>From e9fdc0a001823db1df26158845301aec94cd2b8a Mon Sep 17 00:00:00 2001
From: Bar Soloveychik <barsolo at fb.com>
Date: Mon, 21 Jul 2025 13:29:58 -0700
Subject: [PATCH 1/8] added documenatation on GetDescription
---
.../interface/SBMemoryRegionInfoDocstrings.i | 52 ++++++++++++-------
1 file changed, 32 insertions(+), 20 deletions(-)
diff --git a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
index d7c68baf100e2..dd578f53c828c 100644
--- a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
+++ b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
@@ -1,31 +1,43 @@
-%feature("docstring",
-"API clients can get information about memory regions in processes."
-) lldb::SBMemoryRegionInfo;
+% feature("docstring",
+ "API clients can get information about memory regions in processes.")
+ lldb::SBMemoryRegionInfo;
%feature("docstring", "
Returns whether this memory region has a list of modified (dirty)
pages available or not. When calling GetNumDirtyPages(), you will
- have 0 returned for both \"dirty page list is not known\" and
+ have 0 returned for both \"dirty page list is not known\" and
\"empty dirty page list\" (that is, no modified pages in this
memory region). You must use this method to disambiguate."
) lldb::SBMemoryRegionInfo::HasDirtyMemoryPageList;
-%feature("docstring", "
- Return the number of dirty (modified) memory pages in this
- memory region, if available. You must use the
- SBMemoryRegionInfo::HasDirtyMemoryPageList() method to
- determine if a dirty memory list is available; it will depend
- on the target system can provide this information."
-) lldb::SBMemoryRegionInfo::GetNumDirtyPages;
+% feature(
+ "docstring",
+ "
+ Return the number of dirty(modified) memory pages in this memory region,
+ if available.You must use the SBMemoryRegionInfo::HasDirtyMemoryPageList()
+ method to determine if a dirty memory list is available;
+ it will depend on the target system can provide this information."
+ ) lldb::SBMemoryRegionInfo::GetNumDirtyPages;
-%feature("docstring", "
- Return the address of a modified, or dirty, page of memory.
- If the provided index is out of range, or this memory region
- does not have dirty page information, LLDB_INVALID_ADDRESS
- is returned."
-) lldb::SBMemoryRegionInfo::GetDirtyPageAddressAtIndex;
+% feature("docstring",
+ "
+ Return the address of a modified,
+ or dirty, page of memory.If the provided index is out of range,
+ or this memory region does not have dirty page information,
+ LLDB_INVALID_ADDRESS is returned."
+ ) lldb::SBMemoryRegionInfo::GetDirtyPageAddressAtIndex;
+
+% feature("docstring", "
+ Return the size of pages in this memory region .0 will be
+ returned if this information was unavailable."
+ ) lldb::SBMemoryRegionInfo::GetPageSize();
%feature("docstring", "
- Return the size of pages in this memory region. 0 will be returned
- if this information was unavailable."
-) lldb::SBMemoryRegionInfo::GetPageSize();
+ takes a SBStream parameter 'description' where it will write the output to.
+ it formats the memory region information into a string with Memory region info
+ [Hex start - Hex End) and premission flags R/W/X
+ returns a boolean value indicating success or failure
+
+ alternative to using this method to find out the size of the memory region
+ is to use the len() function on the SBMemoryRegionInfo object"
+) lldb::SBMemoryRegionInfo::GetDescription;
>From 17f46d31903ab451a5944d4097ae1ef62bd631cc Mon Sep 17 00:00:00 2001
From: Bar Soloveychik <barsolo at fb.com>
Date: Mon, 21 Jul 2025 14:08:01 -0700
Subject: [PATCH 2/8] added doc on str/len overwritten functions
---
.../interface/SBMemoryRegionInfoDocstrings.i | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)
diff --git a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
index dd578f53c828c..6b7f4a32ed17e 100644
--- a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
+++ b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
@@ -1,5 +1,8 @@
% feature("docstring",
- "API clients can get information about memory regions in processes.")
+ "API clients can get information about memory regions in processes.
+
+ When printed using str(), the memory region info is formatted as:
+ '[Hex start - Hex End] RWX' ")
lldb::SBMemoryRegionInfo;
%feature("docstring", "
@@ -34,10 +37,11 @@
%feature("docstring", "
takes a SBStream parameter 'description' where it will write the output to.
- it formats the memory region information into a string with Memory region info
- [Hex start - Hex End) and premission flags R/W/X
- returns a boolean value indicating success or failure
+ The function will formats the memory region information into a string with Memory region info
+ [Hex start - Hex End) and premission flags R/W/X.
+ Returns a boolean value indicating success or failure.
- alternative to using this method to find out the size of the memory region
- is to use the len() function on the SBMemoryRegionInfo object"
+ alternatively, to get the size of the memory region is to use
+ the len() function on the SBMemoryRegionInfo object.
+ The function function will return the size of the memory region"
) lldb::SBMemoryRegionInfo::GetDescription;
>From 248082579858ea58235d2946d27e9f25e879e05f Mon Sep 17 00:00:00 2001
From: Bar Soloveychik <barsolo at fb.com>
Date: Mon, 21 Jul 2025 14:48:24 -0700
Subject: [PATCH 3/8] fixed comments from previous commit
---
.../interface/SBMemoryRegionInfoDocstrings.i | 64 +++++++++----------
1 file changed, 31 insertions(+), 33 deletions(-)
diff --git a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
index 6b7f4a32ed17e..1bb1433e2046d 100644
--- a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
+++ b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
@@ -1,9 +1,8 @@
-% feature("docstring",
- "API clients can get information about memory regions in processes.
+%feature("docstring",
+ "API clients can get information about memory regions in processes.
- When printed using str(), the memory region info is formatted as:
- '[Hex start - Hex End] RWX' ")
- lldb::SBMemoryRegionInfo;
+ For Python users, `len()` is overriden to output the size of the memory region in bytes."
+ ) lldb::SBMemoryRegionInfo;
%feature("docstring", "
Returns whether this memory region has a list of modified (dirty)
@@ -11,37 +10,36 @@
have 0 returned for both \"dirty page list is not known\" and
\"empty dirty page list\" (that is, no modified pages in this
memory region). You must use this method to disambiguate."
-) lldb::SBMemoryRegionInfo::HasDirtyMemoryPageList;
+ ) lldb::SBMemoryRegionInfo::HasDirtyMemoryPageList;
-% feature(
- "docstring",
- "
- Return the number of dirty(modified) memory pages in this memory region,
- if available.You must use the SBMemoryRegionInfo::HasDirtyMemoryPageList()
- method to determine if a dirty memory list is available;
- it will depend on the target system can provide this information."
- ) lldb::SBMemoryRegionInfo::GetNumDirtyPages;
+%feature(
+ "docstring",
+ "
+ Return the number of dirty(modified) memory pages in this memory region,
+ if available.You must use the SBMemoryRegionInfo::HasDirtyMemoryPageList()
+ method to determine if a dirty memory list is available;
+ it will depend on the target system can provide this information."
+ ) lldb::SBMemoryRegionInfo::GetNumDirtyPages;
-% feature("docstring",
- "
- Return the address of a modified,
- or dirty, page of memory.If the provided index is out of range,
- or this memory region does not have dirty page information,
- LLDB_INVALID_ADDRESS is returned."
- ) lldb::SBMemoryRegionInfo::GetDirtyPageAddressAtIndex;
+%feature("docstring",
+ "
+ Return the address of a modified,
+ or dirty, page of memory.If the provided index is out of range,
+ or this memory region does not have dirty page information,
+ LLDB_INVALID_ADDRESS is returned."
+ ) lldb::SBMemoryRegionInfo::GetDirtyPageAddressAtIndex;
-% feature("docstring", "
- Return the size of pages in this memory region .0 will be
- returned if this information was unavailable."
- ) lldb::SBMemoryRegionInfo::GetPageSize();
+%feature("docstring", "
+ Return the size of pages in this memory region .0 will be
+ returned if this information was unavailable."
+ ) lldb::SBMemoryRegionInfo::GetPageSize;
%feature("docstring", "
- takes a SBStream parameter 'description' where it will write the output to.
- The function will formats the memory region information into a string with Memory region info
- [Hex start - Hex End) and premission flags R/W/X.
- Returns a boolean value indicating success or failure.
+ Takes an SBStream parameter to write output to,
+ formatted [Hex start - Hex End) with associated permissions (RWX).
+ If the function results false, no output will be written.
+ If results true, the output will be written to the stream.
- alternatively, to get the size of the memory region is to use
- the len() function on the SBMemoryRegionInfo object.
- The function function will return the size of the memory region"
-) lldb::SBMemoryRegionInfo::GetDescription;
+ For Python users, `str()` is overriden with the results of this function.
+ "
+ ) lldb::SBMemoryRegionInfo::GetDescription;
>From 770547ed2bc6b32d831c0b2477325e91d2e8bf50 Mon Sep 17 00:00:00 2001
From: Bar Soloveychik <barsolo at fb.com>
Date: Mon, 21 Jul 2025 14:56:00 -0700
Subject: [PATCH 4/8] format change
---
.../interface/SBMemoryRegionInfoDocstrings.i | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
index 1bb1433e2046d..805032725ed6e 100644
--- a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
+++ b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
@@ -2,7 +2,7 @@
"API clients can get information about memory regions in processes.
For Python users, `len()` is overriden to output the size of the memory region in bytes."
- ) lldb::SBMemoryRegionInfo;
+) lldb::SBMemoryRegionInfo;
%feature("docstring", "
Returns whether this memory region has a list of modified (dirty)
@@ -10,7 +10,7 @@
have 0 returned for both \"dirty page list is not known\" and
\"empty dirty page list\" (that is, no modified pages in this
memory region). You must use this method to disambiguate."
- ) lldb::SBMemoryRegionInfo::HasDirtyMemoryPageList;
+) lldb::SBMemoryRegionInfo::HasDirtyMemoryPageList;
%feature(
"docstring",
@@ -19,7 +19,7 @@
if available.You must use the SBMemoryRegionInfo::HasDirtyMemoryPageList()
method to determine if a dirty memory list is available;
it will depend on the target system can provide this information."
- ) lldb::SBMemoryRegionInfo::GetNumDirtyPages;
+) lldb::SBMemoryRegionInfo::GetNumDirtyPages;
%feature("docstring",
"
@@ -27,12 +27,12 @@
or dirty, page of memory.If the provided index is out of range,
or this memory region does not have dirty page information,
LLDB_INVALID_ADDRESS is returned."
- ) lldb::SBMemoryRegionInfo::GetDirtyPageAddressAtIndex;
+) lldb::SBMemoryRegionInfo::GetDirtyPageAddressAtIndex;
%feature("docstring", "
Return the size of pages in this memory region .0 will be
returned if this information was unavailable."
- ) lldb::SBMemoryRegionInfo::GetPageSize;
+) lldb::SBMemoryRegionInfo::GetPageSize;
%feature("docstring", "
Takes an SBStream parameter to write output to,
@@ -42,4 +42,4 @@
For Python users, `str()` is overriden with the results of this function.
"
- ) lldb::SBMemoryRegionInfo::GetDescription;
+) lldb::SBMemoryRegionInfo::GetDescription;
>From ef0687ddd73fd8246a706b1f6050ccf45221069c Mon Sep 17 00:00:00 2001
From: Bar Soloveychik <barsolo at fb.com>
Date: Mon, 21 Jul 2025 15:29:36 -0700
Subject: [PATCH 5/8] added doxygen comments
---
lldb/include/lldb/API/SBMemoryRegionInfo.h | 13 +++++++++++++
1 file changed, 13 insertions(+)
diff --git a/lldb/include/lldb/API/SBMemoryRegionInfo.h b/lldb/include/lldb/API/SBMemoryRegionInfo.h
index f9a5dc993d7cb..7033921b10770 100644
--- a/lldb/include/lldb/API/SBMemoryRegionInfo.h
+++ b/lldb/include/lldb/API/SBMemoryRegionInfo.h
@@ -115,6 +115,19 @@ class LLDB_API SBMemoryRegionInfo {
bool operator!=(const lldb::SBMemoryRegionInfo &rhs) const;
+ /// writes a description of the memory region to a SBStream.
+ ///
+ /// \param[in,out] description
+ /// A stream object where the description will be written.
+ ///
+ /// \return
+ /// Returns true if the description was successfully written,
+ /// false otherwise.
+ ///
+ /// The description format is: [Hex start - Hex End) with associated permissions (RWX)
+ ///
+ /// In Python bindings, this method is used by the __str__ implementation,
+ /// allowing memory regions to be printed directly.
bool GetDescription(lldb::SBStream &description);
private:
>From c68d9dcb84723a6e5a6a5a127fa6a578537e4b03 Mon Sep 17 00:00:00 2001
From: Bar Soloveychik <barsolo at fb.com>
Date: Mon, 21 Jul 2025 15:38:11 -0700
Subject: [PATCH 6/8] fixed formatting auto-save changes
---
.../interface/SBMemoryRegionInfoDocstrings.i | 20 +++++++++----------
1 file changed, 9 insertions(+), 11 deletions(-)
diff --git a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
index 805032725ed6e..187f005496320 100644
--- a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
+++ b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
@@ -7,22 +7,20 @@
%feature("docstring", "
Returns whether this memory region has a list of modified (dirty)
pages available or not. When calling GetNumDirtyPages(), you will
- have 0 returned for both \"dirty page list is not known\" and
+ have 0 returned for both \"dirty page list is not known\" and
\"empty dirty page list\" (that is, no modified pages in this
memory region). You must use this method to disambiguate."
) lldb::SBMemoryRegionInfo::HasDirtyMemoryPageList;
-%feature(
- "docstring",
- "
- Return the number of dirty(modified) memory pages in this memory region,
- if available.You must use the SBMemoryRegionInfo::HasDirtyMemoryPageList()
- method to determine if a dirty memory list is available;
- it will depend on the target system can provide this information."
+%feature("docstring", "
+ Return the number of dirty (modified) memory pages in this
+ memory region, if available. You must use the
+ SBMemoryRegionInfo::HasDirtyMemoryPageList() method to
+ determine if a dirty memory list is available; it will depend
+ on the target system can provide this information."
) lldb::SBMemoryRegionInfo::GetNumDirtyPages;
-%feature("docstring",
- "
+%feature("docstring", "
Return the address of a modified,
or dirty, page of memory.If the provided index is out of range,
or this memory region does not have dirty page information,
@@ -31,7 +29,7 @@
%feature("docstring", "
Return the size of pages in this memory region .0 will be
- returned if this information was unavailable."
+ returned if this information was unavailable."
) lldb::SBMemoryRegionInfo::GetPageSize;
%feature("docstring", "
>From 026e51d1aa43e3d55ee076b6eeee1c498f58cab3 Mon Sep 17 00:00:00 2001
From: Bar Soloveychik <barsolo at fb.com>
Date: Mon, 21 Jul 2025 15:47:23 -0700
Subject: [PATCH 7/8] formatting
---
.../interface/SBMemoryRegionInfoDocstrings.i | 20 +++++++++----------
1 file changed, 10 insertions(+), 10 deletions(-)
diff --git a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
index 187f005496320..be6fa40ed7446 100644
--- a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
+++ b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
@@ -1,7 +1,7 @@
%feature("docstring",
- "API clients can get information about memory regions in processes.
+"API clients can get information about memory regions in processes.
- For Python users, `len()` is overriden to output the size of the memory region in bytes."
+For Python users, `len()` is overriden to output the size of the memory region in bytes."
) lldb::SBMemoryRegionInfo;
%feature("docstring", "
@@ -21,16 +21,16 @@
) lldb::SBMemoryRegionInfo::GetNumDirtyPages;
%feature("docstring", "
- Return the address of a modified,
- or dirty, page of memory.If the provided index is out of range,
- or this memory region does not have dirty page information,
- LLDB_INVALID_ADDRESS is returned."
+ Return the address of a modified, or dirty, page of memory.
+ If the provided index is out of range, or this memory region
+ does not have dirty page information, LLDB_INVALID_ADDRESS
+ is returned."
) lldb::SBMemoryRegionInfo::GetDirtyPageAddressAtIndex;
%feature("docstring", "
- Return the size of pages in this memory region .0 will be
- returned if this information was unavailable."
-) lldb::SBMemoryRegionInfo::GetPageSize;
+ Return the size of pages in this memory region. 0 will be returned
+ if this information was unavailable."
+) lldb::SBMemoryRegionInfo::GetPageSize();
%feature("docstring", "
Takes an SBStream parameter to write output to,
@@ -40,4 +40,4 @@
For Python users, `str()` is overriden with the results of this function.
"
-) lldb::SBMemoryRegionInfo::GetDescription;
+) lldb::SBMemoryRegionInfo::GetDescription;
\ No newline at end of file
>From 8a56e76eabd4c10c75d01afef022d07e09cd37c1 Mon Sep 17 00:00:00 2001
From: Bar Soloveychik <barsolo at fb.com>
Date: Tue, 22 Jul 2025 11:43:48 -0700
Subject: [PATCH 8/8] made final changes to documentation
---
lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i | 7 ++++---
lldb/include/lldb/API/SBMemoryRegionInfo.h | 3 ---
2 files changed, 4 insertions(+), 6 deletions(-)
diff --git a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
index be6fa40ed7446..99fe91b4558a4 100644
--- a/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
+++ b/lldb/bindings/interface/SBMemoryRegionInfoDocstrings.i
@@ -1,7 +1,10 @@
%feature("docstring",
"API clients can get information about memory regions in processes.
-For Python users, `len()` is overriden to output the size of the memory region in bytes."
+For Python users, `len()` is overriden to output the size of the memory region in bytes.
+For Python users, `str()` is overriden with the results of the GetDescription function-
+ produces a formatted string that describes a memory range in the form:
+ [Hex start - Hex End) with associated permissions (RWX)"
) lldb::SBMemoryRegionInfo;
%feature("docstring", "
@@ -37,7 +40,5 @@ For Python users, `len()` is overriden to output the size of the memory region i
formatted [Hex start - Hex End) with associated permissions (RWX).
If the function results false, no output will be written.
If results true, the output will be written to the stream.
-
- For Python users, `str()` is overriden with the results of this function.
"
) lldb::SBMemoryRegionInfo::GetDescription;
\ No newline at end of file
diff --git a/lldb/include/lldb/API/SBMemoryRegionInfo.h b/lldb/include/lldb/API/SBMemoryRegionInfo.h
index 7033921b10770..5a68945bb5fd9 100644
--- a/lldb/include/lldb/API/SBMemoryRegionInfo.h
+++ b/lldb/include/lldb/API/SBMemoryRegionInfo.h
@@ -125,9 +125,6 @@ class LLDB_API SBMemoryRegionInfo {
/// false otherwise.
///
/// The description format is: [Hex start - Hex End) with associated permissions (RWX)
- ///
- /// In Python bindings, this method is used by the __str__ implementation,
- /// allowing memory regions to be printed directly.
bool GetDescription(lldb::SBStream &description);
private:
More information about the lldb-commits
mailing list