From nobody Wed Dec 17 22:42:43 2025 Received: from mail-pg1-f175.google.com (mail-pg1-f175.google.com [209.85.215.175]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 4143A2E1C55 for ; Mon, 13 Oct 2025 09:56:48 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.175 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1760349410; cv=none; b=Jkl3t4kTpZjnWcjO9gIIfdead2MEk3CJBvOALGyMpUSrdn1Qb5PGjA3Nk8QX1UPRRSo3gwhks+TVHjDE6eYHkMuhs0OjOktv5rY5daIcpHQjzxbFbEgXBNznfDnl9MX40SxGOcnGlrN/w8ZKwePYq2EJyY0VJs6VqGlD60uASb0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1760349410; c=relaxed/simple; bh=QYkAwIOd/KIga79O3CPPdGljlVcGsxlNaZNwOjdD1B4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Q5/3JIvB1wvO/URggEq34Yrhci+RjFTx1bunoikkawa4gvm2DAzNOgvQ5CeDLWHBjEWIkAg9WJbzyOnGoxEweu8vi78mI1+2Q+PJarXGiZztpwxP5mdToMFi9ie/PYvPs+/6FTR48Fhe9HWuh9XQCmoAjeWnStHY+zuV9U9T2ws= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=LDksx5L0; arc=none smtp.client-ip=209.85.215.175 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="LDksx5L0" Received: by mail-pg1-f175.google.com with SMTP id 41be03b00d2f7-b609a32a9b6so2411904a12.2 for ; Mon, 13 Oct 2025 02:56:48 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1760349407; x=1760954207; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=hV1yGxvf/xG0262giXqvwiOxgNcwdxbw0KGOncpIBe4=; b=LDksx5L0hC/hKIdsmtmWm4DCdVf3/GPIxN9oUBPM0OnB6S8IPpVvc+RJiU90fJkHAf Ej/NsExAZnaW7XNzn0OHPe5uWQtHiEhsiuVhPhvyeEHgRXYtwLTqEkRALoSfdXl0B4xY rrh5rVGw3ZHQ5sUJpzLt5qduFxYr+3zKP4PTjyzyP0q4ggzJtDCZJ7dCZpOB/24u78yF ed6d305khHX1dEBB26cVFJ98/ZRxKoveDY7Ainv+dS0VCFscHdcANJyRFb96OPhNVhVX v6iA71uNJ2PSL5P5zFbQNqkyNRFZ/gDE1JVFREYPUYDGB5Fj1nskOYzt4JOBnKRx4u59 7mmw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1760349407; x=1760954207; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=hV1yGxvf/xG0262giXqvwiOxgNcwdxbw0KGOncpIBe4=; b=Fxu07Bcc4E6wFWa6oIN8rkjf6FKGjTKE3tsIPRJ5jzycIh+16tGa8buyi9we4uCcNv aUAYehI1JtPRlNqDH2c3L5L7low1WFVvx9bn73OuhGu7m7dtnkyDgiF8WdQzbhUgoFhT 4rMisP40mJikpYPIm2N+hOabHeaijJAp569iHWsD2L31Zuow3CA0aFulycoRu6V5P/9U SFC1JDUleLAQPiK8dRQBZhT9taNEOa1EmvfInTLZuvBGpNDuk29D6C4EO14NGk1C9qQJ X14zpteSIkagtpa/XZT6C/smrDy4rhCjvd6o8Ps3HECPulLc9qq4YSzdcwJYW0UpQJXM +/5A== X-Gm-Message-State: AOJu0YyCTidpY2ekp82tEVzvtgG4MyHjyuT845kcn00W3fEM6DHN4RbJ bnUWkiL9vGiGO6PDDo7muImJF8kYwu9Ri3OIZrb2E6oiRwNAJc37bwHh X-Gm-Gg: ASbGncvq/9zJBvrD7pey9H+9JlZlz7PiH9Wa2kA3GU3ZjrfpgB+q8/rJWUw0iANdvZf xsk9mOGkGwHy7sm/ZFPOYg4CUF0CkePeO5lc579uQ7fJz9DhgD2L6uGr3oJl8O4a0LjBijiKn3Q HCMfUdUFlQlAwDTFIhaZR77/2+YNknmSIvcQypbTUgUv6NdI8058DfZdeiBwgFnsKTmbqUUBzWD VNF7O+jVc47Ofz1xiih/s9rwbvryzYuGA2AIojTzwxu09RUYjZbnzWUAe2DrvQ6SUtlkjzfswT4 CZr3aDIk/jJYP7zVZKaZfZMt59Ek7j574PH2bKanIPrxqbYfnfSVaWk7FMPzneQz9rLkzt0PW9H bZjcJsIfTFQfg9fQ4w6yHMJ76+TUPBzaEVcGuTCKxk1m5j/6LdBLJMbw= X-Google-Smtp-Source: AGHT+IGvdrSa99TF3/wQzeHJ7adq7ztHAAjyGmj1egmOD56d3dAzTtWsV5s26vvkYDZDOE04ecLVaA== X-Received: by 2002:a17:903:384f:b0:267:9aa5:f6a6 with SMTP id d9443c01a7336-29027240de5mr256824285ad.19.1760349407409; Mon, 13 Oct 2025 02:56:47 -0700 (PDT) Received: from archie.me ([103.124.138.155]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-29034e4510bsm127981945ad.56.2025.10.13.02.56.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 Oct 2025 02:56:46 -0700 (PDT) Received: by archie.me (Postfix, from userid 1000) id 65689444B306; Mon, 13 Oct 2025 16:56:43 +0700 (WIB) From: Bagas Sanjaya To: Linux Kernel Mailing List , Linux Documentation Cc: Jonathan Corbet , Bagas Sanjaya , Will Deacon , Markus Heiser , Mauro Carvalho Chehab , Silvio Fricke , Randy Dunlap Subject: [PATCH v2 1/2] Documentation: assoc_array: Indent function explanation text Date: Mon, 13 Oct 2025 16:56:30 +0700 Message-ID: <20251013095630.34235-3-bagasdotme@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20251013095630.34235-2-bagasdotme@gmail.com> References: <20251013095630.34235-2-bagasdotme@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=14552; i=bagasdotme@gmail.com; h=from:subject; bh=QYkAwIOd/KIga79O3CPPdGljlVcGsxlNaZNwOjdD1B4=; b=owGbwMvMwCX2bWenZ2ig32LG02pJDBlvzlR4Lb9qxSP3z95i0fagzF37OTl2XX+o9ddm/wLWp 8trLoapd5SyMIhxMciKKbJMSuRrOr3LSORC+1pHmDmsTCBDGLg4BWAiam8ZGRaKvbDk6f2qu8Vy 7v7ANoezvO/3bzkUc3/x2dIFBkcnzLdkZGjLWHB7XeCK662bnm2TtLjxumvxoSb5mFezLu9wfLC QLYodAA== X-Developer-Key: i=bagasdotme@gmail.com; a=openpgp; fpr=701B806FDCA5D3A58FFB8F7D7C276C64A5E44A1D Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Paragraphs of function explanation are currently not indented following their appropriate numbered list item, which causes only the first paragraph and function prototype code blocks to be indented in the numbered list in htmldocs output. Indent the explanation. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya --- Documentation/core-api/assoc_array.rst | 167 +++++++++++++------------ 1 file changed, 84 insertions(+), 83 deletions(-) diff --git a/Documentation/core-api/assoc_array.rst b/Documentation/core-ap= i/assoc_array.rst index 792bbf9939e133..61c7ba1e7b877f 100644 --- a/Documentation/core-api/assoc_array.rst +++ b/Documentation/core-api/assoc_array.rst @@ -92,18 +92,18 @@ There are two functions for dealing with the script: =20 void assoc_array_apply_edit(struct assoc_array_edit *edit); =20 -This will perform the edit functions, interpolating various write barriers -to permit accesses under the RCU read lock to continue. The edit script -will then be passed to ``call_rcu()`` to free it and any dead stuff it poi= nts -to. + This will perform the edit functions, interpolating various write barri= ers + to permit accesses under the RCU read lock to continue. The edit script + will then be passed to ``call_rcu()`` to free it and any dead stuff it + points to. =20 2. Cancel an edit script:: =20 void assoc_array_cancel_edit(struct assoc_array_edit *edit); =20 -This frees the edit script and all preallocated memory immediately. If -this was for insertion, the new object is _not_ released by this function, -but must rather be released by the caller. + This frees the edit script and all preallocated memory immediately. If + this was for insertion, the new object is *not* released by this functi= on, + but must rather be released by the caller. =20 These functions are guaranteed not to fail. =20 @@ -123,43 +123,43 @@ This points to a number of methods, all of which need= to be provided: =20 unsigned long (*get_key_chunk)(const void *index_key, int level); =20 -This should return a chunk of caller-supplied index key starting at the -*bit* position given by the level argument. The level argument will be a -multiple of ``ASSOC_ARRAY_KEY_CHUNK_SIZE`` and the function should return -``ASSOC_ARRAY_KEY_CHUNK_SIZE bits``. No error is possible. + This should return a chunk of caller-supplied index key starting at the + *bit* position given by the level argument. The level argument will be= a + multiple of ``ASSOC_ARRAY_KEY_CHUNK_SIZE`` and the function should retu= rn + ``ASSOC_ARRAY_KEY_CHUNK_SIZE bits``. No error is possible. =20 =20 2. Get a chunk of an object's index key:: =20 unsigned long (*get_object_key_chunk)(const void *object, int level); =20 -As the previous function, but gets its data from an object in the array -rather than from a caller-supplied index key. + As the previous function, but gets its data from an object in the array + rather than from a caller-supplied index key. =20 =20 3. See if this is the object we're looking for:: =20 bool (*compare_object)(const void *object, const void *index_key); =20 -Compare the object against an index key and return ``true`` if it matches = and -``false`` if it doesn't. + Compare the object against an index key and return ``true`` if it match= es + and ``false`` if it doesn't. =20 =20 4. Diff the index keys of two objects:: =20 int (*diff_objects)(const void *object, const void *index_key); =20 -Return the bit position at which the index key of the specified object -differs from the given index key or -1 if they are the same. + Return the bit position at which the index key of the specified object + differs from the given index key or -1 if they are the same. =20 =20 5. Free an object:: =20 void (*free_object)(void *object); =20 -Free the specified object. Note that this may be called an RCU grace peri= od -after ``assoc_array_apply_edit()`` was called, so ``synchronize_rcu()`` ma= y be -necessary on module unloading. + Free the specified object. Note that this may be called an RCU grace p= eriod + after ``assoc_array_apply_edit()`` was called, so ``synchronize_rcu()``= may + be necessary on module unloading. =20 =20 Manipulation Functions @@ -171,7 +171,7 @@ There are a number of functions for manipulating an ass= ociative array: =20 void assoc_array_init(struct assoc_array *array); =20 -This initialises the base structure for an associative array. It can't fa= il. + This initialises the base structure for an associative array. It can't= fail. =20 =20 2. Insert/replace an object in an associative array:: @@ -182,21 +182,21 @@ This initialises the base structure for an associativ= e array. It can't fail. const void *index_key, void *object); =20 -This inserts the given object into the array. Note that the least -significant bit of the pointer must be zero as it's used to type-mark -pointers internally. + This inserts the given object into the array. Note that the least + significant bit of the pointer must be zero as it's used to type-mark + pointers internally. =20 -If an object already exists for that key then it will be replaced with the -new object and the old one will be freed automatically. + If an object already exists for that key then it will be replaced with = the + new object and the old one will be freed automatically. =20 -The ``index_key`` argument should hold index key information and is -passed to the methods in the ops table when they are called. + The ``index_key`` argument should hold index key information and is + passed to the methods in the ops table when they are called. =20 -This function makes no alteration to the array itself, but rather returns -an edit script that must be applied. ``-ENOMEM`` is returned in the case = of -an out-of-memory error. + This function makes no alteration to the array itself, but rather retur= ns + an edit script that must be applied. ``-ENOMEM`` is returned in the ca= se of + an out-of-memory error. =20 -The caller should lock exclusively against other modifiers of the array. + The caller should lock exclusively against other modifiers of the array. =20 =20 3. Delete an object from an associative array:: @@ -206,15 +206,15 @@ The caller should lock exclusively against other modi= fiers of the array. const struct assoc_array_ops *ops, const void *index_key); =20 -This deletes an object that matches the specified data from the array. + This deletes an object that matches the specified data from the array. =20 -The ``index_key`` argument should hold index key information and is -passed to the methods in the ops table when they are called. + The ``index_key`` argument should hold index key information and is + passed to the methods in the ops table when they are called. =20 -This function makes no alteration to the array itself, but rather returns -an edit script that must be applied. ``-ENOMEM`` is returned in the case = of -an out-of-memory error. ``NULL`` will be returned if the specified object= is -not found within the array. + This function makes no alteration to the array itself, but rather retur= ns + an edit script that must be applied. ``-ENOMEM`` is returned in the ca= se of + an out-of-memory error. ``NULL`` will be returned if the specified obj= ect + is not found within the array. =20 The caller should lock exclusively against other modifiers of the array. =20 @@ -225,14 +225,14 @@ The caller should lock exclusively against other modi= fiers of the array. assoc_array_clear(struct assoc_array *array, const struct assoc_array_ops *ops); =20 -This deletes all the objects from an associative array and leaves it -completely empty. + This deletes all the objects from an associative array and leaves it + completely empty. =20 -This function makes no alteration to the array itself, but rather returns -an edit script that must be applied. ``-ENOMEM`` is returned in the case = of -an out-of-memory error. + This function makes no alteration to the array itself, but rather retur= ns + an edit script that must be applied. ``-ENOMEM`` is returned in the ca= se of + an out-of-memory error. =20 -The caller should lock exclusively against other modifiers of the array. + The caller should lock exclusively against other modifiers of the array. =20 =20 5. Destroy an associative array, deleting all objects:: @@ -240,14 +240,14 @@ The caller should lock exclusively against other modi= fiers of the array. void assoc_array_destroy(struct assoc_array *array, const struct assoc_array_ops *ops); =20 -This destroys the contents of the associative array and leaves it -completely empty. It is not permitted for another thread to be traversing -the array under the RCU read lock at the same time as this function is -destroying it as no RCU deferral is performed on memory release - -something that would require memory to be allocated. + This destroys the contents of the associative array and leaves it + completely empty. It is not permitted for another thread to be travers= ing + the array under the RCU read lock at the same time as this function is + destroying it as no RCU deferral is performed on memory release - + something that would require memory to be allocated. =20 -The caller should lock exclusively against other modifiers and accessors -of the array. + The caller should lock exclusively against other modifiers and accessors + of the array. =20 =20 6. Garbage collect an associative array:: @@ -257,24 +257,24 @@ of the array. bool (*iterator)(void *object, void *iterator_data), void *iterator_data); =20 -This iterates over the objects in an associative array and passes each one= to -``iterator()``. If ``iterator()`` returns ``true``, the object is kept. = If it -returns ``false``, the object will be freed. If the ``iterator()`` functi= on -returns ``true``, it must perform any appropriate refcount incrementing on= the -object before returning. + This iterates over the objects in an associative array and passes each = one + to ``iterator()``. If ``iterator()`` returns ``true``, the object is k= ept. + If it returns ``false``, the object will be freed. If the ``iterator()= `` + function returns ``true``, it must perform any appropriate refcount + incrementing on the object before returning. =20 -The internal tree will be packed down if possible as part of the iteration -to reduce the number of nodes in it. + The internal tree will be packed down if possible as part of the iterat= ion + to reduce the number of nodes in it. =20 -The ``iterator_data`` is passed directly to ``iterator()`` and is otherwise -ignored by the function. + The ``iterator_data`` is passed directly to ``iterator()`` and is other= wise + ignored by the function. =20 -The function will return ``0`` if successful and ``-ENOMEM`` if there wasn= 't -enough memory. + The function will return ``0`` if successful and ``-ENOMEM`` if there w= asn't + enough memory. =20 -It is possible for other threads to iterate over or search the array under -the RCU read lock while this function is in progress. The caller should -lock exclusively against other modifiers of the array. + It is possible for other threads to iterate over or search the array un= der + the RCU read lock while this function is in progress. The caller should + lock exclusively against other modifiers of the array. =20 =20 Access Functions @@ -289,19 +289,19 @@ There are two functions for accessing an associative = array: void *iterator_data), void *iterator_data); =20 -This passes each object in the array to the iterator callback function. -``iterator_data`` is private data for that function. + This passes each object in the array to the iterator callback function. + ``iterator_data`` is private data for that function. =20 -This may be used on an array at the same time as the array is being -modified, provided the RCU read lock is held. Under such circumstances, -it is possible for the iteration function to see some objects twice. If -this is a problem, then modification should be locked against. The -iteration algorithm should not, however, miss any objects. + This may be used on an array at the same time as the array is being + modified, provided the RCU read lock is held. Under such circumstances, + it is possible for the iteration function to see some objects twice. If + this is a problem, then modification should be locked against. The + iteration algorithm should not, however, miss any objects. =20 -The function will return ``0`` if no objects were in the array or else it = will -return the result of the last iterator function called. Iteration stops -immediately if any call to the iteration function results in a non-zero -return. + The function will return ``0`` if no objects were in the array or else = it + will return the result of the last iterator function called. Iteration + stops immediately if any call to the iteration function results in a + non-zero return. =20 =20 2. Find an object in an associative array:: @@ -310,14 +310,15 @@ return. const struct assoc_array_ops *ops, const void *index_key); =20 -This walks through the array's internal tree directly to the object -specified by the index key.. + This walks through the array's internal tree directly to the object + specified by the index key. =20 -This may be used on an array at the same time as the array is being -modified, provided the RCU read lock is held. + This may be used on an array at the same time as the array is being + modified, provided the RCU read lock is held. =20 -The function will return the object if found (and set ``*_type`` to the ob= ject -type) or will return ``NULL`` if the object was not found. + The function will return the object if found (and set ``*_type`` to the + object + type) or will return ``NULL`` if the object was not found. =20 =20 Index Key Form --=20 An old man doll... just what I always wanted! - Clara From nobody Wed Dec 17 22:42:43 2025 Received: from mail-pf1-f178.google.com (mail-pf1-f178.google.com [209.85.210.178]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C33EA26D4EE for ; Mon, 13 Oct 2025 09:56:47 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.178 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1760349409; cv=none; b=SEF4unPFpuIBYDAYlzY22gNhNK9ZYeLY0Pf+IIQl1OvOC/NAO4odOwLQNro1Qcqs00QLpyw//Z1gaPtCA/DdXyJ6KA4qFtZd3Fh3E5Jv65etwJ/I7Drtjt6jKt173jKt0Wj1tBVp6bRVjFh9l5xXfBX8cSWz9ypmbJTIekNjyok= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1760349409; c=relaxed/simple; bh=osO1ANWf/MtQ51cpeQHzFc47cYEE93PJRkuORtoQPk8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=rqvbteCMK25lw8MOIZPseMjhd7FdCMG58/jhTfksFPalRn6Ire+YuPfC6oTnZr+7edUM+fnQVMrL0H+/Og9JiBru6gbSujWmlaMHgaujKOo1GkZc6bdFjjnZfFoe6mC/kgmTWVDQggq9OjVtD3cFIEPvq0+iVpRDHyj1wK86Xug= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=boWZckxU; arc=none smtp.client-ip=209.85.210.178 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="boWZckxU" Received: by mail-pf1-f178.google.com with SMTP id d2e1a72fcca58-796f9a8a088so3789349b3a.1 for ; Mon, 13 Oct 2025 02:56:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1760349407; x=1760954207; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=f+yrBFZp5vtdgalR3uw+8+Z4TKx4WciRTYMlOYaljes=; b=boWZckxUH2gljY9tzOV+4GrH2LnfwzJdL3n89Jvv5NzspiZL6FD3Icr0ZaO2mw8Rf4 0rDbyTYmF02mmGSJapwzZxeTvnInSFeGEFyvk82cY7ECggvZ0pt+x8fHN+bJOAJ91sXx Shr76lOmWvDEpOw5p96kAx+Nm8vSntVCse606O4EPjmV9f1yHD/794zlBbafdqBNHmcJ KDagsUctOVcZXP6iN0BsXveOX4phgNQDsqU4gFXL0bIEjztz6tHBv9dATRadJV4dIS5V nN3tnkehNWPRfygDL/ucg7ZWBTYcG15C8YESMRRBCt9+csfGIrex52d1y7B1wi0Q+esq IBOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1760349407; x=1760954207; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=f+yrBFZp5vtdgalR3uw+8+Z4TKx4WciRTYMlOYaljes=; b=kIZ13aGKU3jJs7VaSb9t/wJ7bvNewzXbYEJFaqE9SMaTgErh2dUtxrUXdHDiTGaQLx +sxxgDyhyhkd3K79eODqPOpl0s4c3xDJvMn2B6lI+cGUeFjmImH9V0Rwym5NTfkjYZeX R22HBQhlE/zjD0YilLU1rOgqRaqkADtaEoTzRRJirFx2CyEaFlzN0fAiAMGzDz8cl6kG EHv+AQBObYuCtiiiDZpnW255lv8VIFEJz5t2FljBJhIluWoxdrEvdKsie92ONzAhuzMr Er2zfVgR74Q9qI5l+aWTBhr3p/Sc7TAegxm2RRQ9+zB48biRgQ545V9AMERo+qNLt28T v5Rw== X-Gm-Message-State: AOJu0Ywe7PB5BWLhC8sUaglq3MGxdVReaUH1z+RLY1ej3CTnQvLIJINZ q53h8dXuxiCkZpMtMD7DNcolc8yFwQP9px6d1igmHxn74bIBNCM8G1sh X-Gm-Gg: ASbGncty8T5TflzdOSfcvo72bTXVcMRPPeWGXb06POBxNAX8MjcRH1K2dRKmO1HeP8m obRNdbivcMNrNUT3d/4Tb5VcqfSnw2XqlhX1DBS5pD4cnyZQk94qcVSHyP7I5PD4GGBb3Jko7z4 H1eVDGDnUEXNnQgpVulFqFY9HW470vloRB7X2MXnyIdJye8z3rrQAAMDbM/Y2ABSSjNjMkxaPEN pTHu/5KiG0M1o5op4yAEPclsTVt8ipNMIIW3Om7Y+5v5HVWb25TNvxgyraRRYW357yhZocoDmuD D4AI7rdN9YfyCAoKugd/i/GEXZ7NoAJhzAvEqjhsZGDDJh1BxmWhWjYmAKsPwH9zP/peGlzPn1R LTRJ5On/jNYONk3xtWscFTxyFECxl3xV4BGGv2RDE5z3ptdOHF3MNt8Y= X-Google-Smtp-Source: AGHT+IG4d0UlItFBg2gSZoAXDMDXxcApwjTaXpPj1vdprQgwuvA01VXZjBH1veLt+SCHWSZCYBY1UA== X-Received: by 2002:a05:6a20:a111:b0:2c9:ff13:bc86 with SMTP id adf61e73a8af0-32da8139429mr27108687637.21.1760349406967; Mon, 13 Oct 2025 02:56:46 -0700 (PDT) Received: from archie.me ([103.124.138.155]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7992b0607e3sm11349871b3a.11.2025.10.13.02.56.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 Oct 2025 02:56:45 -0700 (PDT) Received: by archie.me (Postfix, from userid 1000) id 83F8F45289A7; Mon, 13 Oct 2025 16:56:43 +0700 (WIB) From: Bagas Sanjaya To: Linux Kernel Mailing List , Linux Documentation Cc: Jonathan Corbet , Bagas Sanjaya , Will Deacon , Markus Heiser , Mauro Carvalho Chehab , Silvio Fricke , Randy Dunlap Subject: [PATCH v2 2/2] Documentation: assoc_array: Format internal tree layout tables Date: Mon, 13 Oct 2025 16:56:31 +0700 Message-ID: <20251013095630.34235-4-bagasdotme@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20251013095630.34235-2-bagasdotme@gmail.com> References: <20251013095630.34235-2-bagasdotme@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=3600; i=bagasdotme@gmail.com; h=from:subject; bh=osO1ANWf/MtQ51cpeQHzFc47cYEE93PJRkuORtoQPk8=; b=owGbwMvMwCX2bWenZ2ig32LG02pJDBlvzlSsWrrxLT/D/Dbmh9K59dPnqPrJVLHW++cet1wee L7UZYthRykLgxgXg6yYIsukRL6m07uMRC60r3WEmcPKBDKEgYtTACby2JbhD9/Kieun8z08xl3x LnTed0Wpa7PY8mavmHYyLLT57SIu5zJGhhmbprfrJyRxdB5Zztqaovi+slNcjLNhdvNavh9vM3/ 5cQIA X-Developer-Key: i=bagasdotme@gmail.com; a=openpgp; fpr=701B806FDCA5D3A58FFB8F7D7C276C64A5E44A1D Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Format tables in "Basic internal tree layout" as reST tables. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya --- Documentation/core-api/assoc_array.rst | 33 ++++++++++++++++---------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/Documentation/core-api/assoc_array.rst b/Documentation/core-ap= i/assoc_array.rst index 61c7ba1e7b877f..19d89f92bf8da8 100644 --- a/Documentation/core-api/assoc_array.rst +++ b/Documentation/core-api/assoc_array.rst @@ -317,8 +317,7 @@ There are two functions for accessing an associative ar= ray: modified, provided the RCU read lock is held. =20 The function will return the object if found (and set ``*_type`` to the - object - type) or will return ``NULL`` if the object was not found. + object type) or will return ``NULL`` if the object was not found. =20 =20 Index Key Form @@ -400,10 +399,11 @@ fixed levels. For example:: =20 In the above example, there are 7 nodes (A-G), each with 16 slots (0-f). Assuming no other meta data nodes in the tree, the key space is divided -thusly:: +thusly: =20 + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D KEY PREFIX NODE - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D 137* D 138* E 13[0-69-f]* C @@ -411,10 +411,12 @@ thusly:: e6* G e[0-57-f]* F [02-df]* A + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D =20 So, for instance, keys with the following example index keys will be found= in -the appropriate nodes:: +the appropriate nodes: =20 + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D = =3D=3D=3D=3D INDEX KEY PREFIX NODE =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D = =3D=3D=3D=3D 13694892892489 13 C @@ -423,12 +425,13 @@ the appropriate nodes:: 138bbb89003093 138 E 1394879524789 12 C 1458952489 1 B - 9431809de993ba - A - b4542910809cd - A + 9431809de993ba \- A + b4542910809cd \- A e5284310def98 e F e68428974237 e6 G e7fffcbd443 e F - f3842239082 - A + f3842239082 \- A + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D = =3D=3D=3D=3D =20 To save memory, if a node can hold all the leaves in its portion of keyspa= ce, then the node will have all those leaves in it and will not have any metad= ata @@ -442,8 +445,9 @@ metadata pointer. If the metadata pointer is there, an= y leaf whose key matches the metadata key prefix must be in the subtree that the metadata pointer p= oints to. =20 -In the above example list of index keys, node A will contain:: +In the above example list of index keys, node A will contain: =20 + =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D SLOT CONTENT INDEX KEY (PREFIX) =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 1 PTR TO NODE B 1* @@ -451,11 +455,16 @@ In the above example list of index keys, node A will = contain:: any LEAF b4542910809cd e PTR TO NODE F e* any LEAF f3842239082 + =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -and node B:: +and node B: =20 - 3 PTR TO NODE C 13* - any LEAF 1458952489 + =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + SLOT CONTENT INDEX KEY (PREFIX) + =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + 3 PTR TO NODE C 13* + any LEAF 1458952489 + =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 =20 Shortcuts --=20 An old man doll... just what I always wanted! - Clara