From nobody Tue Jun 16 11:19:19 2026 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 630EE19DF6A; Sat, 18 Apr 2026 20:50:02 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=217.140.110.172 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776545404; cv=none; b=P2DEahnLEcTFjABOyvRjqSKCqsK5cuJFvAnHsoY6U6iQlRyya4WUJej5iAFJ44YYixoOz3a+SQZHsnm058Z287f6x6E3eB+gLoJgXWgB/nNAnQgGDUHpEv3dGJx8pxLNX9JGDLtsVIPQbXSL2MGFcpP0lNrj9/nYqe+PdBM8KAA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776545404; c=relaxed/simple; bh=H6WgkZZcA/mA2cLpnncZ0V6CejHxgd1bABjG2+xoA64=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=TjSyXqnqWuoz9LBN87c9ZGQH5+rYKcuFrPSfCOIRHygn8aG7fA/s6KxM2+tiAu3P9aWnAuqfp1eePDOwakr44sssH6xfv2LhVRzIs160lkOnuOvevvZU1vOMFzLLKe9XDvRcIEiE5m2GJ6ceuLUa3y+a9jiNEjwQx6k4NBg947M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com; spf=pass smtp.mailfrom=arm.com; dkim=pass (1024-bit key) header.d=arm.com header.i=@arm.com header.b=NcStPSRE; arc=none smtp.client-ip=217.140.110.172 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=arm.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=arm.com header.i=@arm.com header.b="NcStPSRE" Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 97A3C176A; Sat, 18 Apr 2026 13:49:50 -0700 (PDT) Received: from workstation-e142269.cambridge.arm.com (usa-sjc-imap-foss1.foss.arm.com [10.121.207.14]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 72C293F7D8; Sat, 18 Apr 2026 13:49:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=arm.com; s=foss; t=1776545396; bh=H6WgkZZcA/mA2cLpnncZ0V6CejHxgd1bABjG2+xoA64=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=NcStPSRE4v1U9caa4EqTbzTMJOkAW0Q0Emov03fEF4WZ3WSZQaNvpplDjjSqnN7bV F9dLncqqvCwwYWAVrwZTUvG0vWXQOkEb8JGA1tnCOndXcPmiiEYgO9+S9ZklCNEuup JOVj+KgDtFS7/KQHicmvI3m5N14I0D7Py+zSHMmU= From: Wei-Lin Chang To: maple-tree@lists.infradead.org, linux-mm@kvack.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: "Liam R . Howlett" , Alice Ryhl , Andrew Ballance , Jonathan Corbet , Shuah Khan , Wei-Lin Chang Subject: [RFC PATCH 1/2] Documentation: maple_tree: Point out constraint when using xa_{mk, to}_value Date: Sat, 18 Apr 2026 21:47:53 +0100 Message-ID: <20260418204754.120405-2-weilin.chang@arm.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20260418204754.120405-1-weilin.chang@arm.com> References: <20260418204754.120405-1-weilin.chang@arm.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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. Signed-off-by: Wei-Lin Chang --- Documentation/core-api/maple_tree.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Documentation/core-api/maple_tree.rst b/Documentation/core-api= /maple_tree.rst index ccdd1615cf97..15eda6742af8 100644 --- a/Documentation/core-api/maple_tree.rst +++ b/Documentation/core-api/maple_tree.rst @@ -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 con= vert -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 c= an +convert the value when using the :ref:`maple-tree-advanced-api`, but are b= locked +by the normal API. =20 The Maple Tree can also be configured to support searching for a gap of a = given size (or larger). --=20 2.43.0 From nobody Tue Jun 16 11:19:19 2026 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 67065327C0D; Sat, 18 Apr 2026 20:50:04 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=217.140.110.172 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776545406; cv=none; b=HCQjFqK72/EcFxfKxzsSAmUesfCu0Z+LTyfGHShVur1EP0Fy4SXLjraMAKX11L+kmSKA9+Sp+vWDUhRw9B/KSmTEsM2dmnKgAtGmq5qXX6z5sxil5d54NkZSnbb6auKRVUZoo0P1zcPbvH7GOGdesG0SFO6diF0Z+lWS4YoSeBg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776545406; c=relaxed/simple; bh=xqilpVqLK6IYITkPGi7y1Vzf8kCa1LEGL+36lgbutug=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=dF0wHE6QTGQPTN4c5qDy1PaaUaFNJeHRpA0RjW274fytNWSsp9OZ4luqMkT11xrYjkMGu8OqIX3vRslvd/K2z7G0vvTjNwcNPNSIjbs7WyJjVyfSPjfiZJLv7nDXKyQrm8Z56uFyEQ83t6Fs8W4Lq2Yzl8SmxZYj7qcwQLMhxgM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com; spf=pass smtp.mailfrom=arm.com; dkim=pass (1024-bit key) header.d=arm.com header.i=@arm.com header.b=tjzsURev; arc=none smtp.client-ip=217.140.110.172 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=arm.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=arm.com header.i=@arm.com header.b="tjzsURev" Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id B2B79176B; Sat, 18 Apr 2026 13:49:52 -0700 (PDT) Received: from workstation-e142269.cambridge.arm.com (usa-sjc-imap-foss1.foss.arm.com [10.121.207.14]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 8D2F53F7D8; Sat, 18 Apr 2026 13:49:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=arm.com; s=foss; t=1776545398; bh=xqilpVqLK6IYITkPGi7y1Vzf8kCa1LEGL+36lgbutug=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tjzsURevw38siKINXzxI6ayboyU46S4o5GYu4Gdp8Qa1/s3JyBj3jx8Tg3SjTjpRp Rsu3emwxCXROn8BnmKVPkvBOteW77h5brADlX8INLFE08/8RpwdOOTQnJjRtrAm7nS wUnRjdb0HUb5JEgl7+4KCcnosumWyA3LO9ldXFgI= From: Wei-Lin Chang To: maple-tree@lists.infradead.org, linux-mm@kvack.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: "Liam R . Howlett" , Alice Ryhl , Andrew Ballance , Jonathan Corbet , Shuah Khan , Wei-Lin Chang Subject: [RFC PATCH 2/2] Documentation: maple_tree: Clarify behavior when using reserved values Date: Sat, 18 Apr 2026 21:47:54 +0100 Message-ID: <20260418204754.120405-3-weilin.chang@arm.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20260418204754.120405-1-weilin.chang@arm.com> References: <20260418204754.120405-1-weilin.chang@arm.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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. Signed-off-by: Wei-Lin Chang --- Documentation/core-api/maple_tree.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Documentation/core-api/maple_tree.rst b/Documentation/core-api= /maple_tree.rst index 15eda6742af8..54ea99c7bca7 100644 --- a/Documentation/core-api/maple_tree.rst +++ b/Documentation/core-api/maple_tree.rst @@ -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 c= an -convert the value when using the :ref:`maple-tree-advanced-api`, but are b= locked -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`. =20 The Maple Tree can also be configured to support searching for a gap of a = given size (or larger). --=20 2.43.0