Re: [RFC PATCH 2/2] XArray: Remove literal markup from known constants

From: Mauro Carvalho Chehab
Date: Wed Jun 09 2021 - 03:50:51 EST


Em Tue, 8 Jun 2021 22:43:08 -0300
Nícolas F. R. A. Prado <n@xxxxxxxxxxxxx> escreveu:

> Remove literal markup from known constants, instead relying on
> automarkup.py to make them into literals.
>
> Suggested-by: Matthew Wilcox <willy@xxxxxxxxxxxxx>
> Signed-off-by: Nícolas F. R. A. Prado <n@xxxxxxxxxxxxx>

Once we implement automarkup.py support, this patch seems OK on my eyes.
you can add my reviewed by: here on a series with the automarkup
logic.

> ---
> Documentation/core-api/xarray.rst | 48 +++++++++++++++----------------
> 1 file changed, 24 insertions(+), 24 deletions(-)
>
> diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst
> index a137a0e6d068..6e608e2e8e5b 100644
> --- a/Documentation/core-api/xarray.rst
> +++ b/Documentation/core-api/xarray.rst
> @@ -22,7 +22,7 @@ The XArray implementation is efficient when the indices used are densely
> clustered; hashing the object and using the hash as the index will not
> perform well. The XArray is optimised for small indices, but still has
> good performance with large indices. If your index can be larger than
> -``ULONG_MAX`` then the XArray is not the data type for you. The most
> +ULONG_MAX then the XArray is not the data type for you. The most
> important user of the XArray is the page cache.
>
> Normal pointers may be stored in the XArray directly. They must be 4-byte
> @@ -31,7 +31,7 @@ alloc_page(). It isn't true for arbitrary user-space pointers,
> nor for function pointers. You can store pointers to statically allocated
> objects, as long as those objects have an alignment of at least 4.
>
> -You can also store integers between 0 and ``LONG_MAX`` in the XArray.
> +You can also store integers between 0 and LONG_MAX in the XArray.
> You must first convert it into an entry using xa_mk_value().
> When you retrieve an entry from the XArray, you can check whether it is
> a value entry by calling xa_is_value(), and convert it back to
> @@ -52,7 +52,7 @@ An unusual feature of the XArray is the ability to create entries which
> occupy a range of indices. Once stored to, looking up any index in
> the range will return the same entry as looking up any other index in
> the range. Storing to any index will store to all of them. Multi-index
> -entries can be explicitly split into smaller entries, or storing ``NULL``
> +entries can be explicitly split into smaller entries, or storing NULL
> into any entry will cause the XArray to forget about the range.
>
> Normal API
> @@ -60,16 +60,16 @@ Normal API
>
> Start by initialising an XArray, either with DEFINE_XARRAY()
> for statically allocated XArrays or xa_init() for dynamically
> -allocated ones. A freshly-initialised XArray contains a ``NULL``
> +allocated ones. A freshly-initialised XArray contains a NULL
> pointer at every index.
>
> You can then set entries using xa_store() and get entries
> using xa_load(). xa_store will overwrite any entry with the
> new entry and return the previous entry stored at that index. You can
> use xa_erase() instead of calling xa_store() with a
> -``NULL`` entry. There is no difference between an entry that has never
> +NULL a entry. There is no difference between an entry that has never
> been stored to, one that has been erased and one that has most recently
> -had ``NULL`` stored to it.
> +had NULL stored to it.
>
> You can conditionally replace an entry at an index by using
> xa_cmpxchg(). Like cmpxchg(), it will only succeed if
> @@ -78,8 +78,8 @@ which was at that index; if it returns the same entry which was passed as
> 'old', then xa_cmpxchg() succeeded.
>
> If you want to only store a new entry to an index if the current entry
> -at that index is ``NULL``, you can use xa_insert() which
> -returns ``-EBUSY`` if the entry is not empty.
> +at that index is NULL, you can use xa_insert() which
> +returns -EBUSY if the entry is not empty.
>
> You can copy entries out of the XArray into a plain array by calling
> xa_extract(). Or you can iterate over the present entries in the XArray
> @@ -97,14 +97,14 @@ some, but not all of the other indices changing.
> Sometimes you need to ensure that a subsequent call to xa_store()
> will not need to allocate memory. The xa_reserve() function
> will store a reserved entry at the indicated index. Users of the
> -normal API will see this entry as containing ``NULL``. If you do
> +normal API will see this entry as containing NULL. If you do
> not need to use the reserved entry, you can call xa_release()
> to remove the unused entry. If another user has stored to the entry
> in the meantime, xa_release() will do nothing; if instead you
> -want the entry to become ``NULL``, you should use xa_erase().
> +want the entry to become NULL, you should use xa_erase().
> Using xa_insert() on a reserved entry will fail.
>
> -If all entries in the array are ``NULL``, the xa_empty() function
> +If all entries in the array are NULL, the xa_empty() function
> will return ``true``.
>
> Finally, you can remove all entries from an XArray by calling
> @@ -120,7 +120,7 @@ Each mark may be set or cleared independently of the others. You can
> iterate over marked entries by using the xa_for_each_marked() iterator.
>
> You can enquire whether a mark is set on an entry by using
> -xa_get_mark(). If the entry is not ``NULL``, you can set a mark on it
> +xa_get_mark(). If the entry is not NULL, you can set a mark on it
> by using xa_set_mark() and remove the mark from an entry by calling
> xa_clear_mark(). You can ask whether any entry in the XArray has a
> particular mark set by calling xa_marked(). Erasing an entry from the
> @@ -151,9 +151,9 @@ interrupts while allocating the ID.
>
> Using xa_store(), xa_cmpxchg() or xa_insert() will
> also mark the entry as being allocated. Unlike a normal XArray, storing
> -``NULL`` will mark the entry as being in use, like xa_reserve().
> +NULL will mark the entry as being in use, like xa_reserve().
> To free an entry, use xa_erase() (or xa_release() if
> -you only want to free the entry if it's ``NULL``).
> +you only want to free the entry if it's NULL).
>
> By default, the lowest free entry is allocated starting from 0. If you
> want to allocate entries starting at 1, it is more efficient to use
> @@ -326,11 +326,11 @@ xas_error() to retrieve the error. All operations check whether
> the xa_state is in an error state before proceeding, so there's no need
> for you to check for an error after each call; you can make multiple
> calls in succession and only check at a convenient point. The only
> -errors currently generated by the XArray code itself are ``ENOMEM`` and
> -``EINVAL``, but it supports arbitrary errors in case you want to call
> +errors currently generated by the XArray code itself are ENOMEM and
> +EINVAL, but it supports arbitrary errors in case you want to call
> xas_set_err() yourself.
>
> -If the xa_state is holding an ``ENOMEM`` error, calling xas_nomem()
> +If the xa_state is holding an ENOMEM error, calling xas_nomem()
> will attempt to allocate more memory using the specified gfp flags and
> cache it in the xa_state for the next attempt. The idea is that you take
> the xa_lock, attempt the operation and drop the lock. The operation
> @@ -340,7 +340,7 @@ can try harder to allocate more memory. It will return ``true`` if it
> is worth retrying the operation (i.e. that there was a memory error *and*
> more memory was allocated). If it has previously allocated memory, and
> that memory wasn't used, and there is no error (or some error that isn't
> -``ENOMEM``), then it will free the memory previously allocated.
> +ENOMEM), then it will free the memory previously allocated.
>
> Internal Entries
> ----------------
> @@ -375,10 +375,10 @@ to xas_retry(), and retry the operation if it returns ``true``.
>
> * - Zero
> - xa_is_zero()
> - - Zero entries appear as ``NULL`` through the Normal API, but occupy
> + - Zero entries appear as NULL through the Normal API, but occupy
> an entry in the XArray which can be used to reserve the index for
> future use. This is used by allocating XArrays for allocated entries
> - which are ``NULL``.
> + which are NULL.
>
> Other internal entries may be added in the future. As far as possible, they
> will be handled by xas_retry().
> @@ -461,9 +461,9 @@ You can create a multi-index entry by using XA_STATE_ORDER()
> or xas_set_order() followed by a call to xas_store().
> Calling xas_load() with a multi-index xa_state will walk the
> xa_state to the right location in the tree, but the return value is not
> -meaningful, potentially being an internal entry or ``NULL`` even when there
> +meaningful, potentially being an internal entry or NULL even when there
> is an entry stored within the range. Calling xas_find_conflict()
> -will return the first entry within the range or ``NULL`` if there are no
> +will return the first entry within the range or NULL if there are no
> entries in the range. The xas_for_each_conflict() iterator will
> iterate over every entry which overlaps the specified range.
>
> @@ -479,8 +479,8 @@ Using xas_next() or xas_prev() with a multi-index xa_state is not
> supported. Using either of these functions on a multi-index entry will
> reveal sibling entries; these should be skipped over by the caller.
>
> -Storing ``NULL`` into any index of a multi-index entry will set the
> -entry at every index to ``NULL`` and dissolve the tie. A multi-index
> +Storing NULL into any index of a multi-index entry will set the
> +entry at every index to NULL and dissolve the tie. A multi-index
> entry can be split into entries occupying smaller ranges by calling
> xas_split_alloc() without the xa_lock held, followed by taking the lock
> and calling xas_split().



Thanks,
Mauro