[PATCH 1/2] lsmem: correct the grammar of an error message

[PATCH 1/2] lsmem: correct the grammar of an error message

[Benno Schulenberg]

That is: make the message identical to its twin nine lines back.

(The spello was introduced by commit 92d018a105 from five months ago.)

CC: Sumanth Korikkar <sumanthk@linux.ibm.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 sys-utils/lsmem.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sys-utils/lsmem.c b/sys-utils/lsmem.c
index b74c95d43..aee68a171 100644
--- a/sys-utils/lsmem.c
+++ b/sys-utils/lsmem.c
@@ -819,7 +819,7 @@ int main(int argc, char **argv)
 	/* open /sys/firmware/memory handler (optional) */
 	lsmem->sysmemconfig = ul_new_path(_PATH_SYS_MEMCONFIG);
 	if (!lsmem->sysmemconfig)
-		err(EXIT_FAILURE, _("failed to initialized %s handler"), _PATH_SYS_MEMCONFIG);
+		err(EXIT_FAILURE, _("failed to initialize %s handler"), _PATH_SYS_MEMCONFIG);
 	if (prefix && ul_path_set_prefix(lsmem->sysmemconfig, prefix) != 0)
 		err(EXIT_FAILURE, _("invalid argument to --sysroot"));
 
-- 
2.53.0

[PATCH 2/2] lsmem: (man) correct the markup of column names, and improve some grammar

[Benno Schulenberg]

The column names should be marked in bold and not in italics, as they
are literal values, not placeholders.

Also, indent the list of column names, to make it clearer where the
list ends.  And add the missing markup for "RANGE" and the missing
name "REMOVABLE".

Furthermore, drop the small table, as it held nearly no information
and was confusing: the explicit numbers in the BLOCK column gave the
impression that block 0 can only be online, block 1 only offline but
configured, and block 2 only offline and deconfigured.  The content
of the MEMMAP-ON-MEMORY column being always "yes/no" was useless.
Leaving out those columns left only STATE and CONFIGURED, where the
values implied that memory can only be online when it is configured.
This information can be conveyed in a single sentence.

(The table was added in commit 6f1e4ff054 from five months ago.)

CC: Sumanth Korikkar <sumanthk@linux.ibm.com>
Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 sys-utils/lsmem.1.adoc | 65 +++++++++++++++++++-----------------------
 1 file changed, 29 insertions(+), 36 deletions(-)

diff --git a/sys-utils/lsmem.1.adoc b/sys-utils/lsmem.1.adoc
index 3fcdba625..bbc1bb8e0 100644
--- a/sys-utils/lsmem.1.adoc
+++ b/sys-utils/lsmem.1.adoc
@@ -16,57 +16,50 @@ lsmem - list the ranges of available memory with their online status
 
 == DESCRIPTION
 
-The *lsmem* command lists the ranges of available memory with their online status. The listed memory blocks correspond to the memory block representation in sysfs. The command also shows the memory block size and the amount of memory in online and offline state.
+The *lsmem* command lists the ranges of available memory with their online status. The listed memory blocks correspond to the memory block representation in sysfs. The command also shows the size of a single memory block and the total amounts of memory in online and offline state.
 
-The default output is compatible with original implementation from s390-tools, but it's strongly recommended to avoid using default outputs in your scripts. Always explicitly define expected columns by using the *--output* option together with a columns list in environments where a stable output is required.
+The default output is compatible with the original implementation from s390-tools, but it's strongly recommended to avoid using default outputs in your scripts. Always explicitly define expected columns by using the *--output* option together with a columns list in environments where a stable output is required.
 
-The *lsmem* command lists a new memory range always when the current memory block distinguish from the previous block by some output column. This default behavior is possible to override by the *--split* option (e.g., *lsmem --split=ZONES*). The special word "none" may be used to ignore all differences between memory blocks and to create as large as possible continuous ranges. The opposite semantic is *--all* to list individual memory blocks.
+The *lsmem* command always lists a new memory range when the current memory block differs from the previous block by some output column. This default behavior can be overridden with the *--split* option (for example: *lsmem --split=ZONES*). The special word *none* may be used with *--split* to ignore all differences between memory blocks and to create contiguous ranges that are as large as possible. The opposite semantics has *--all*, which lists all individual memory blocks.
 
-Note that some output columns may provide inaccurate information if a split policy forces *lsmem* to ignore differences in some attributes. For example if you merge removable and non-removable memory blocks to the one range than all the range will be marked as non-removable on *lsmem* output.
+Note that some output columns may provide inaccurate information if a splitting policy forces *lsmem* to ignore differences in some attributes. For example, if you merge removable and non-removable memory blocks into a single range, then the whole range will be marked as non-removable in *lsmem* output.
 
-The supported columns are RANGE, SIZE, STATE, REMOVABLE, BLOCK, NODE, ZONES, CONFIGURED, MEMMAP-ON-MEMORY.
-RANGE
-The start and end physical address of the memory range.
+The supported columns are *RANGE*, *SIZE*, *STATE*, *REMOVABLE*, *BLOCK*, *NODE*, *ZONES*, *CONFIGURED*, and *MEMMAP-ON-MEMORY*.
+____
+*RANGE*::
+The start and end physical addresses of the memory range.
 
-_SIZE_::
+*SIZE*::
 The size of the memory range, representing the total amount of memory in that range.
 
-_STATE_::
-The current online status of the memory range. Common states include online, offline or transitional states.
+*STATE*::
+The current online status of the memory range. Common states include online, offline, and transitional states.
 
-_BLOCK_::
-The specific memory block number.
+*REMOVABLE*::
+Whether the memory is removable.
 
-_NODE_::
+*BLOCK*::
+The specific memory block number or range.
+
+*NODE*::
 The NUMA (Non-Uniform Memory Access) node to which the memory block belongs.
 
-_ZONES_::
+*ZONES*::
 The memory zones to which the blocks belongs, such as DMA, Normal, Movable.
 
-_CONFIGURED_::
-The configuration state of a memory block. Refer to *chmem* for details on configuring or deconfiguring memory blocks.
+*CONFIGURED*::
+The configuration state of a memory block. Refer to *chmem*(8) for details on configuring or deconfiguring memory blocks.
 
-_MEMMAP-ON-MEMORY_::
+*MEMMAP-ON-MEMORY*::
 The memmap-on-memory state of the memory block at configuration time. This setting indicates where memory hotplug stores its internal metadata (the struct pages array or memmap). If MEMMAP-ON-MEMORY is set to 1, the metadata is allocated directly from the newly added hotplugged memory, enabling hot-add operations even when the system is under high memory pressure. If set to 0, the memmap metadata is allocated from existing system memory.
+____
 
-Possible BLOCK, CONFIGURED, STATE, MEMMAP-ON-MEMORY states::
+Not all columns are supported on all systems. If an unsupported column is specified, *lsmem* prints the column but does not provide any data for it. Additionally, *lsmem* may skip columns like *CONFIGURED* or *MEMMAP-ON-MEMORY* if these states are not relevant to the system's architecture.
 
-[cols="10,10,10,15,60", options="header"]
-|===
-| BLOCK | STATE   | CONFIGURED | MEMMAP-ON-MEMORY | Description
+On systems that can configure/deconfigure memory, memory needs to be configured
+before it can come online.
 
-| 0     | online  | yes        | yes/no           | The memory is configured with memmap-on-memory set to (1 or 0) and memory is currently online.
-
-| 1     | offline | yes        | yes/no           | The memory is configured, but memory is offline.
-
-| 2     | offline | no         | yes/no           | The memory is offline and deconfigured.
-|===
-
-Not all columns are supported on all systems. If an unsupported column is specified, *lsmem* prints the column but does not provide any data for it. Additionally, *lsmem* may skip columns like _CONFIGURED_ or _MEMMAP-ON-MEMORY_ if these states are not relevant to the system's architecture.
-
-Use the *--help* option to see the columns description.
-
-Memmap on memory parameter output displays the globally enabled memmap-on-memory setting for memory_hotplug. This is typically set on the kernel command line via memory_hotplug.memmap_on_memory.
+The "Memmap on memory parameter" summary line shows the global memmap-on-memory setting for memory_hotplug.  This is typically set on the kernel command line via memory_hotplug.memmap_on_memory.
 
 == OPTIONS
 
@@ -95,19 +88,19 @@ Produce output in the form of key="value" pairs. All potentially unsafe value ch
 Produce output in raw format. All potentially unsafe characters are hex-escaped (\x<code>).
 
 *-S*, *--split* _list_::
-Specify which columns are used to split memory blocks to ranges. The supported columns are STATE, REMOVABLE, NODE, ZONES, CONFIGURED, MEMMAP-ON-MEMORY or "none". The other columns are silently ignored. For more details see *DESCRIPTION* above.
+Specify which columns are used to split memory blocks into ranges. The supported columns are *STATE*, *REMOVABLE*, *NODE*, *ZONES*, *CONFIGURED*, *MEMMAP-ON-MEMORY*, and *none*. Other column names are silently ignored. For more details see *DESCRIPTION* above.
 
 *-s*, *--sysroot* _directory_::
 Gather memory data for a Linux instance other than the instance from which the *lsmem* command is issued. The specified _directory_ is the system root of the Linux instance to be inspected.
 
 *--summary*[**=**_when_]::
-This option controls summary lines output. The optional argument _when_ can be *never*, *always* or *only*. If the _when_ argument is omitted, it defaults to *"only"*. The summary output is suppressed for *--raw*, *--pairs* and *--json*.
+This option controls summary lines output. The optional argument _when_ can be *never*, *always* or *only*. If the _when_ argument is omitted, it defaults to *only*. The summary output is suppressed for *--raw*, *--pairs*, and *--json*.
 
 include::man-common/help-version.adoc[]
 
 == ENVIRONMENT
 
-LSMEM_COLUMNS=::
+*LSMEM_COLUMNS*::
 Specifies a comma-separated list of output columns to print. All columns listed in *--help* can be used.
 
 == AUTHORS
-- 
2.53.0

Re: [PATCH 1/2] lsmem: correct the grammar of an error message

[Sumanth Korikkar]

On Sat, Mar 07, 2026 at 12:43:07PM +0100, Benno Schulenberg wrote:
> That is: make the message identical to its twin nine lines back.
> 
> (The spello was introduced by commit 92d018a105 from five months ago.)
> 
> CC: Sumanth Korikkar <sumanthk@linux.ibm.com>
> Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>

Reviewed-by: Sumanth Korikkar <sumanthk@linux.ibm.com>

> ---
>  sys-utils/lsmem.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/sys-utils/lsmem.c b/sys-utils/lsmem.c
> index b74c95d43..aee68a171 100644
> --- a/sys-utils/lsmem.c
> +++ b/sys-utils/lsmem.c
> @@ -819,7 +819,7 @@ int main(int argc, char **argv)
>  	/* open /sys/firmware/memory handler (optional) */
>  	lsmem->sysmemconfig = ul_new_path(_PATH_SYS_MEMCONFIG);
>  	if (!lsmem->sysmemconfig)
> -		err(EXIT_FAILURE, _("failed to initialized %s handler"), _PATH_SYS_MEMCONFIG);
> +		err(EXIT_FAILURE, _("failed to initialize %s handler"), _PATH_SYS_MEMCONFIG);
>  	if (prefix && ul_path_set_prefix(lsmem->sysmemconfig, prefix) != 0)
>  		err(EXIT_FAILURE, _("invalid argument to --sysroot"));
>  
> -- 
> 2.53.0
>

Re: [PATCH 2/2] lsmem: (man) correct the markup of column names, and improve some grammar

[Sumanth Korikkar]

Hi Benno,

On Sat, Mar 07, 2026 at 12:43:08PM +0100, Benno Schulenberg wrote:
> The column names should be marked in bold and not in italics, as they
> are literal values, not placeholders.
> 
> Also, indent the list of column names, to make it clearer where the
> list ends.  And add the missing markup for "RANGE" and the missing
> name "REMOVABLE".

Some of the changes introduced here are independent of commit
6f1e4ff054. But, looks fine to me.

> Furthermore, drop the small table, as it held nearly no information
> and was confusing: the explicit numbers in the BLOCK column gave the
> impression that block 0 can only be online, block 1 only offline but
> configured, and block 2 only offline and deconfigured.  The content
> of the MEMMAP-ON-MEMORY column being always "yes/no" was useless.
> Leaving out those columns left only STATE and CONFIGURED, where the
> values implied that memory can only be online when it is configured.
> This information can be conveyed in a single sentence.
> (The table was added in commit 6f1e4ff054 from five months ago.)

The table is useful because configuration and deconfiguration support on
s390 is still relatively new, and it documents the possible state
combinations. This helps users interpret what they see in lsmem output.

* The intention is to show possible memory block states. If the term
  “BLOCK” is confusing, it can be removed.
* The table illustrates whether a memory block is configured with
  memmap‑on‑memory is enabled (yes/no). This can be explained separately
  if needed.
* Users may configure a memory block with memmap‑on‑memory
  enabled/disabled and bring it online in a separate step.
* Users may bring memory online in a single step, in which case the tool
  performs both configuration (if supported by the architecture) and the
  online action.
* Users may only configure memory and later deconfigure it again.

This is the main reason for providing the table to make these
transitions clearer to the end user.

How about the following?
Example STATE, CONFIGURED, MEMMAP-ON-MEMORY states:
STATE   | CONFIGURED | MEMMAP-ON-MEMORY | Description
online  | yes        | yes              | Memory block is configured with memmap-on-memory enabled and online.
online  | yes        | no               | Memory block is configured with memmap-on-memory disabled and online.
offline | yes        | yes              | Memory block is configured but currently offline.
offline | no         | yes              | Memory block is deconfigured and was previously configured with memmap-on-memory.
offline | no         | no               | Memory block is deconfigured and was not previously configured with memmap-on-memory.

Thanks
Sumanth

Re: [PATCH 2/2] lsmem: (man) correct the markup of column names, and improve some grammar

[Benno Schulenberg]

[-- Attachment #1.1: Type: text/plain, Size: 2727 bytes --]


Op 09-03-2026 om 13:36 schreef Sumanth Korikkar:
> The table is useful because configuration and deconfiguration support on
> s390 is still relatively new, and it documents the possible state
> combinations. This helps users interpret what they see in lsmem output.

I don't think so.  The information that the table contains is expressed
easily in the single sentence that I replaced it with.

> * The intention is to show possible memory block states.

All state combinations are possible, except that blocks cannot be online
when they are deconfigured (when the system supports deconfiguration).
That is what my replacement sentence says.

> * The table illustrates whether a memory block is configured with
>    memmap‑on‑memory is enabled (yes/no).

This makes no sense to me.

> * Users may configure a memory block with memmap‑on‑memory
>    enabled/disabled and bring it online in a separate step.

If that needs explaining explicitly, then propose an additional sentence.
No need for a table.

> * Users may bring memory online in a single step, in which case the tool
>    performs both configuration (if supported by the architecture) and the
>    online action.

The table does not make this clear at all.  The `lsmem` command does not
bring memory online or offline, so its man page is the wrong place for
trying to explain that.

> * Users may only configure memory and later deconfigure it again.

The table does not help to explain this at all.

> How about the following?
> Example STATE, CONFIGURED, MEMMAP-ON-MEMORY states:
> STATE   | CONFIGURED | MEMMAP-ON-MEMORY | Description
> online  | yes        | yes              | Memory block is configured with memmap-on-memory enabled and online.
> online  | yes        | no               | Memory block is configured with memmap-on-memory disabled and online.
> offline | yes        | yes              | Memory block is configured but currently offline.
> offline | no         | yes              | Memory block is deconfigured and was previously configured with memmap-on-memory.
> offline | no         | no               | Memory block is deconfigured and was not previously configured with memmap-on-memory.

Above table gives the impression that the following line is not possible:

offline | yes        | no              | Memory block is configured but 
currently offline.

But it is possible, right?

Again, I think any table is just a clumsy way of stating what can be said
in one or two sentences.  Also, a table gives the impression that it is
important information, and thus draws attention, making the user waste
time trying to understand what is so important about it.


Benno


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

Re: [PATCH 2/2] lsmem: (man) correct the markup of column names, and improve some grammar

[Karel Zak]

On Mon, Mar 09, 2026 at 01:36:32PM +0100, Sumanth Korikkar wrote:
> How about the following?
> Example STATE, CONFIGURED, MEMMAP-ON-MEMORY states:
> STATE   | CONFIGURED | MEMMAP-ON-MEMORY | Description
> online  | yes        | yes              | Memory block is configured with memmap-on-memory enabled and online.
> online  | yes        | no               | Memory block is configured with memmap-on-memory disabled and online.
> offline | yes        | yes              | Memory block is configured but currently offline.
> offline | no         | yes              | Memory block is deconfigured and was previously configured with memmap-on-memory.
> offline | no         | no               | Memory block is deconfigured and was not previously configured with memmap-on-memory.

I personally prefer structured information like lists or tables and
dislike large text blocks ;-) 

However, in this case, I'm not sure if the description adds anything,
as it repeats what is obvious from STATE, CONFIGURED, MEMMAP-ON-MEMORY
columns.

What I find relevant is "previously configured." Maybe add a sentence
stating that CONFIGURED and MEMMAP-ON-MEMORY for _offline_ blocks show
the previous setup.

Benno, what do you think?

    Karel
-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 2/2] lsmem: (man) correct the markup of column names, and improve some grammar

[Sumanth Korikkar]

On Wed, Mar 11, 2026 at 01:27:03PM +0100, Karel Zak wrote:
> On Mon, Mar 09, 2026 at 01:36:32PM +0100, Sumanth Korikkar wrote:
> > How about the following?
> > Example STATE, CONFIGURED, MEMMAP-ON-MEMORY states:
> > STATE   | CONFIGURED | MEMMAP-ON-MEMORY | Description
> > online  | yes        | yes              | Memory block is configured with memmap-on-memory enabled and online.
> > online  | yes        | no               | Memory block is configured with memmap-on-memory disabled and online.
> > offline | yes        | yes              | Memory block is configured but currently offline.
> > offline | no         | yes              | Memory block is deconfigured and was previously configured with memmap-on-memory.
> > offline | no         | no               | Memory block is deconfigured and was not previously configured with memmap-on-memory.

Hi Karel,

> I personally prefer structured information like lists or tables and
> dislike large text blocks ;-) 

I chose a table because I felt it would show the state combinations more
clearly. But I understand it does make the text heavier.

> However, in this case, I'm not sure if the description adds anything,
> as it repeats what is obvious from STATE, CONFIGURED, MEMMAP-ON-MEMORY
> columns.

Thanks for the feedback. In that case, we can drop the
table and keep the sentence which was proposed earlier.

> What I find relevant is "previously configured." Maybe add a sentence
> stating that CONFIGURED and MEMMAP-ON-MEMORY for _offline_ blocks show
> the previous setup.

For offline blocks, only the MEMMAP‑ON‑MEMORY value reflects the
previous setup or the initial default.  If this value isn’t changed
during the next configuration, it will simply be carried forward and
used again.

An offline but configured block is possible.
chmem -c -b <blockno> -m 1

Thanks & Regards,
Sumanth

Re: [PATCH 1/2] lsmem: correct the grammar of an error message

[Karel Zak]

On Sat, Mar 07, 2026 at 12:43:07PM +0100, Benno Schulenberg wrote:
>  sys-utils/lsmem.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied this one, thanks.

For the second lsmem patch, I'm not sure if it needs an update to
provide more information about online/offline status and
configuration.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 2/2] lsmem: (man) correct the markup of column names, and improve some grammar

[Benno Schulenberg]

[-- Attachment #1.1: Type: text/plain, Size: 480 bytes --]


Op 11-03-2026 om 14:24 schreef Sumanth Korikkar:
> On Wed, Mar 11, 2026 at 01:27:03PM +0100, Karel Zak wrote:
>> However, in this case, I'm not sure if the description adds anything,
>> as it repeats what is obvious from STATE, CONFIGURED, MEMMAP-ON-MEMORY
>> columns.
> 
> Thanks for the feedback. In that case, we can drop the
> table and keep the sentence which was proposed earlier.

So... you're saying the original 2/2 lsmem patch is fine as it is?


Benno


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

Re: [PATCH 2/2] lsmem: (man) correct the markup of column names, and improve some grammar

[Benno Schulenberg]

[-- Attachment #1.1: Type: text/plain, Size: 343 bytes --]


Op 11-03-2026 om 13:27 schreef Karel Zak:
> What I find relevant is "previously configured." Maybe add a sentence
> stating that CONFIGURED and MEMMAP-ON-MEMORY for _offline_ blocks show
> the previous setup.
> 
> Benno, what do you think?

I think Sumanth has agreed that my original 2/2 lsmem patch is fine
with him.


Benno


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

Re: [PATCH 2/2] lsmem: (man) correct the markup of column names, and improve some grammar

[Sumanth Korikkar]

On Thu, Mar 12, 2026 at 04:59:29PM +0100, Benno Schulenberg wrote:
> 
> Op 11-03-2026 om 13:27 schreef Karel Zak:
> > What I find relevant is "previously configured." Maybe add a sentence
> > stating that CONFIGURED and MEMMAP-ON-MEMORY for _offline_ blocks show
> > the previous setup.
> > 
> > Benno, what do you think?
> 
> I think Sumanth has agreed that my original 2/2 lsmem patch is fine
> with him.

Fine with me. 

Thanks,
Sumanth

Re: [PATCH 2/2] lsmem: (man) correct the markup of column names, and improve some grammar

[Karel Zak]

On Sat, Mar 07, 2026 at 12:43:08PM +0100, Benno Schulenberg wrote:
>  sys-utils/lsmem.1.adoc | 65 +++++++++++++++++++-----------------------
>  1 file changed, 29 insertions(+), 36 deletions(-)

Applied, thanks.

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com