Skip to contentSkip to conversation

Documentation: maple_tree: Improve statements on reserved values

RFC PATCH New Wei-Lin Chang 1 participant 3 messages Apr 18

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

cover Documentation: maple_tree: Improve statements on reserved values

Hi,

While using the maple tree and reading its documentation, I found a few bits confusing, mainly about the reserved values. So here are some changes hoping to make things clearer.

I am not familiar with the implementation, so I might be getting things wrong, hence this being RFC.

While looking at the code I also found that although the doc claims the normal API blocks reserved value stores, the code checks this using xa_is_advanced(), which only blocks values up to 1026, not up to the max maple tree reserved value 4094. For this part I am not sure whether the code needs to be changed or we can also improve the doc.

Any feedback is appreciated, thanks!

Wei-Lin Chang (2):
Documentation: maple_tree: Point out constraint when using xa_{mk,
to}_value
Documentation: maple_tree: Clarify behavior when using reserved values

 Documentation/core-api/maple_tree.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Signature · 1 line
2.43.0
#1 lore raw

RFC PATCH 1/2 Documentation: maple_tree: Point out constraint when using xa_{mk, to}_value

Using xa_{mk, to}_value when storing values loses the information of the top bit from the left shift, point that out in the doc.

---
 Documentation/core-api/maple_tree.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)
Documentation/core-api/maple_tree.rst +5 -4
index ccdd1615cf97..15eda6742af8 100644
@@ -28,10 +28,11 @@ virtual memory areas.
 The Maple Tree can store values between ``0`` and ``ULONG_MAX``.  The Maple
 Tree reserves values with the bottom two bits set to '10' which are below 4096
 (ie 2, 6, 10 .. 4094) for internal use.  If the entries may use reserved
-entries then the users can convert the entries using xa_mk_value() and convert
-them back by calling xa_to_value().  If the user needs to use a reserved
-value, then the user can convert the value when using the
-:ref:`maple-tree-advanced-api`, but are blocked by the normal API.
+entries under the condition that their top bits are never 1, then the user can
+convert the entries using xa_mk_value() and convert them back by calling
+xa_to_value().  If the user needs to use a reserved value, then the user can
+convert the value when using the :ref:`maple-tree-advanced-api`, but are blocked
+by the normal API.
 
 The Maple Tree can also be configured to support searching for a gap of a given
 size (or larger).
Signature · 1 line
2.43.0
#2 lore raw

RFC PATCH 2/2 Documentation: maple_tree: Clarify behavior when using reserved values

In reply to Wei-Lin Chang

It doesn't matter whether the normal or the advanced API is used if the user uses xa_{mk, to}_value when storing and retrieving the values. Just specify that the normal API blocks usages of reserved values while the advanced API does not.

---
 Documentation/core-api/maple_tree.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/core-api/maple_tree.rst +2 -3
index 15eda6742af8..54ea99c7bca7 100644
@@ -30,9 +30,8 @@ Tree reserves values with the bottom two bits set to '10' which are below 4096
 (ie 2, 6, 10 .. 4094) for internal use.  If the entries may use reserved
 entries under the condition that their top bits are never 1, then the user can
 convert the entries using xa_mk_value() and convert them back by calling
-xa_to_value().  If the user needs to use a reserved value, then the user can
-convert the value when using the :ref:`maple-tree-advanced-api`, but are blocked
-by the normal API.
+xa_to_value().  Usage of reserved values is blocked by the normal API, and will
+cause undefined behavior if used with the :ref:`maple-tree-advanced-api`.
 
 The Maple Tree can also be configured to support searching for a gap of a given
 size (or larger).
Signature · 1 line
2.43.0