[PATCH] docs/admin-guide/mm/concepts.rst: grammar fixups

[PATCH] docs/admin-guide/mm/concepts.rst: grammar fixups

[Mike Rapoport]

From: Mike Rapoport <rppt@linux.vnet.ibm.com>

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
---

There was a couple of grammar fixes Randy suggested a while ago, but it
seems I've never sent them out. 

 Documentation/admin-guide/mm/concepts.rst | 39 ++++++++++++++++---------------
 1 file changed, 20 insertions(+), 19 deletions(-)

diff --git a/Documentation/admin-guide/mm/concepts.rst b/Documentation/admin-guide/mm/concepts.rst
index 291699c..ab7a0f9 100644
--- a/Documentation/admin-guide/mm/concepts.rst
+++ b/Documentation/admin-guide/mm/concepts.rst
@@ -4,13 +4,13 @@
 Concepts overview
 =================
 
-The memory management in Linux is complex system that evolved over the
-years and included more and more functionality to support variety of
+The memory management in Linux is a complex system that evolved over the
+years and included more and more functionality to support a variety of
 systems from MMU-less microcontrollers to supercomputers. The memory
-management for systems without MMU is called ``nommu`` and it
+management for systems without an MMU is called ``nommu`` and it
 definitely deserves a dedicated document, which hopefully will be
 eventually written. Yet, although some of the concepts are the same,
-here we assume that MMU is available and CPU can translate a virtual
+here we assume that an MMU is available and a CPU can translate a virtual
 address to a physical address.
 
 .. contents:: :local:
@@ -21,10 +21,10 @@ Virtual Memory Primer
 The physical memory in a computer system is a limited resource and
 even for systems that support memory hotplug there is a hard limit on
 the amount of memory that can be installed. The physical memory is not
-necessary contiguous, it might be accessible as a set of distinct
+necessary contiguous; it might be accessible as a set of distinct
 address ranges. Besides, different CPU architectures, and even
-different implementations of the same architecture have different view
-how these address ranges defined.
+different implementations of the same architecture have different views
+of how these address ranges defined.
 
 All this makes dealing directly with physical memory quite complex and
 to avoid this complexity a concept of virtual memory was developed.
@@ -48,8 +48,9 @@ appropriate kernel configuration option.
 
 Each physical memory page can be mapped as one or more virtual
 pages. These mappings are described by page tables that allow
-translation from virtual address used by programs to real address in
-the physical memory. The page tables organized hierarchically.
+translation from a virtual address used by programs to the real
+address in the physical memory. The page tables are organized
+hierarchically.
 
 The tables at the lowest level of the hierarchy contain physical
 addresses of actual pages used by the software. The tables at higher
@@ -121,8 +122,8 @@ Nodes
 Many multi-processor machines are NUMA - Non-Uniform Memory Access -
 systems. In such systems the memory is arranged into banks that have
 different access latency depending on the "distance" from the
-processor. Each bank is referred as `node` and for each node Linux
-constructs an independent memory management subsystem. A node has it's
+processor. Each bank is referred as a `node` and for each node Linux
+constructs an independent memory management subsystem. A node has its
 own set of zones, lists of free and used pages and various statistics
 counters. You can find more details about NUMA in
 :ref:`Documentation/vm/numa.rst <numa>` and in
@@ -149,7 +150,7 @@ for program's stack and heap or by explicit calls to mmap(2) system
 call. Usually, the anonymous mappings only define virtual memory areas
 that the program is allowed to access. The read accesses will result
 in creation of a page table entry that references a special physical
-page filled with zeroes. When the program performs a write, regular
+page filled with zeroes. When the program performs a write, a regular
 physical page will be allocated to hold the written data. The page
 will be marked dirty and if the kernel will decide to repurpose it,
 the dirty page will be swapped out.
@@ -181,8 +182,8 @@ pressure.
 The process of freeing the reclaimable physical memory pages and
 repurposing them is called (surprise!) `reclaim`. Linux can reclaim
 pages either asynchronously or synchronously, depending on the state
-of the system. When system is not loaded, most of the memory is free
-and allocation request will be satisfied immediately from the free
+of the system. When the system is not loaded, most of the memory is free
+and allocation requests will be satisfied immediately from the free
 pages supply. As the load increases, the amount of the free pages goes
 down and when it reaches a certain threshold (high watermark), an
 allocation request will awaken the ``kswapd`` daemon. It will
@@ -190,7 +191,7 @@ asynchronously scan memory pages and either just free them if the data
 they contain is available elsewhere, or evict to the backing storage
 device (remember those dirty pages?). As memory usage increases even
 more and reaches another threshold - min watermark - an allocation
-will trigger the `direct reclaim`. In this case allocation is stalled
+will trigger `direct reclaim`. In this case allocation is stalled
 until enough memory pages are reclaimed to satisfy the request.
 
 Compaction
@@ -200,7 +201,7 @@ As the system runs, tasks allocate and free the memory and it becomes
 fragmented. Although with virtual memory it is possible to present
 scattered physical pages as virtually contiguous range, sometimes it is
 necessary to allocate large physically contiguous memory areas. Such
-need may arise, for instance, when a device driver requires large
+need may arise, for instance, when a device driver requires a large
 buffer for DMA, or when THP allocates a huge page. Memory `compaction`
 addresses the fragmentation issue. This mechanism moves occupied pages
 from the lower part of a memory zone to free pages in the upper part
@@ -208,13 +209,13 @@ of the zone. When a compaction scan is finished free pages are grouped
 together at the beginning of the zone and allocations of large
 physically contiguous areas become possible.
 
-Like reclaim, the compaction may happen asynchronously in ``kcompactd``
-daemon or synchronously as a result of memory allocation request.
+Like reclaim, the compaction may happen asynchronously in the ``kcompactd``
+daemon or synchronously as a result of a memory allocation request.
 
 OOM killer
 ==========
 
-It may happen, that on a loaded machine memory will be exhausted. When
+It may happen that on a loaded machine memory will be exhausted. When
 the kernel detects that the system runs out of memory (OOM) it invokes
 `OOM killer`. Its mission is simple: all it has to do is to select a
 task to sacrifice for the sake of the overall system health. The
-- 
2.7.4

Re: [PATCH] docs/admin-guide/mm/concepts.rst: grammar fixups

[Randy Dunlap]

On 11/5/18 11:58 AM, Mike Rapoport wrote:
> From: Mike Rapoport <rppt@linux.vnet.ibm.com>
> 
> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> Cc: Randy Dunlap <rdunlap@infradead.org>
> ---
> 
> There was a couple of grammar fixes Randy suggested a while ago, but it
> seems I've never sent them out. 
> 
>  Documentation/admin-guide/mm/concepts.rst | 39 ++++++++++++++++---------------
>  1 file changed, 20 insertions(+), 19 deletions(-)

Hi Mike,

one nit:

> @@ -121,8 +122,8 @@ Nodes
>  Many multi-processor machines are NUMA - Non-Uniform Memory Access -
>  systems. In such systems the memory is arranged into banks that have
>  different access latency depending on the "distance" from the
> -processor. Each bank is referred as `node` and for each node Linux
> -constructs an independent memory management subsystem. A node has it's
> +processor. Each bank is referred as a `node` and for each node Linux

                        is referred to as a

> +constructs an independent memory management subsystem. A node has its
>  own set of zones, lists of free and used pages and various statistics
>  counters. You can find more details about NUMA in
>  :ref:`Documentation/vm/numa.rst <numa>` and in

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

thanks.
-- 
~Randy

Re: [PATCH] docs/admin-guide/mm/concepts.rst: grammar fixups

[Matthew Wilcox]

On Mon, Nov 05, 2018 at 09:58:15PM +0200, Mike Rapoport wrote:
> @@ -21,10 +21,10 @@ Virtual Memory Primer
>  The physical memory in a computer system is a limited resource and
>  even for systems that support memory hotplug there is a hard limit on
>  the amount of memory that can be installed. The physical memory is not
> -necessary contiguous, it might be accessible as a set of distinct
> +necessary contiguous; it might be accessible as a set of distinct

necessarily

>  address ranges. Besides, different CPU architectures, and even
> -different implementations of the same architecture have different view
> -how these address ranges defined.
> +different implementations of the same architecture have different views
> +of how these address ranges defined.

"are defined"?

>  Each physical memory page can be mapped as one or more virtual
>  pages. These mappings are described by page tables that allow
> -translation from virtual address used by programs to real address in
> -the physical memory. The page tables organized hierarchically.
> +translation from a virtual address used by programs to the real
> +address in the physical memory. The page tables are organized
> +hierarchically.

I don't like the term "real address".  Can we say "physical address in memory" here, or "address of physical memory" or something?

> -page filled with zeroes. When the program performs a write, regular
> +page filled with zeroes. When the program performs a write, a regular
>  physical page will be allocated to hold the written data. The page
>  will be marked dirty and if the kernel will decide to repurpose it,
>  the dirty page will be swapped out.

"if the kernel will decide to repurpose it" is awkward.  How about

if the kernel decides to repurpose it"?

>  OOM killer
>  ==========
>  
> -It may happen, that on a loaded machine memory will be exhausted. When
> +It may happen that on a loaded machine memory will be exhausted. When
>  the kernel detects that the system runs out of memory (OOM) it invokes
>  `OOM killer`.
> Its mission is simple: all it has to do is to select a
>  task to sacrifice for the sake of the overall system health. The

It is possible for the kernel to be unable to reclaim enough memory to
continue to operate.  In order to save the rest of the system, it invokes
the `OOM killer` to sacrifice one task.

Re: [PATCH] docs/admin-guide/mm/concepts.rst: grammar fixups

[Mike Rapoport]

On Mon, Nov 05, 2018 at 01:12:40PM -0800, Matthew Wilcox wrote:
> On Mon, Nov 05, 2018 at 09:58:15PM +0200, Mike Rapoport wrote:
> > @@ -21,10 +21,10 @@ Virtual Memory Primer
> >  The physical memory in a computer system is a limited resource and
> >  even for systems that support memory hotplug there is a hard limit on
> >  the amount of memory that can be installed. The physical memory is not
> > -necessary contiguous, it might be accessible as a set of distinct
> > +necessary contiguous; it might be accessible as a set of distinct
> 
> necessarily
> 
> >  address ranges. Besides, different CPU architectures, and even
> > -different implementations of the same architecture have different view
> > -how these address ranges defined.
> > +different implementations of the same architecture have different views
> > +of how these address ranges defined.
> 
> "are defined"?
> 
> >  Each physical memory page can be mapped as one or more virtual
> >  pages. These mappings are described by page tables that allow
> > -translation from virtual address used by programs to real address in
> > -the physical memory. The page tables organized hierarchically.
> > +translation from a virtual address used by programs to the real
> > +address in the physical memory. The page tables are organized
> > +hierarchically.
> 
> I don't like the term "real address".  Can we say "physical address in memory" here, or "address of physical memory" or something?
 
I didn't really like it as well, but I couldn't think of any better
adjective to emphasize that address in the physical memory is "the real
thing".

Maybe the best would be to drop "real" and make it 

"translation from a virtual address used by programs to the 
address in the physical memory"


> > -page filled with zeroes. When the program performs a write, regular
> > +page filled with zeroes. When the program performs a write, a regular
> >  physical page will be allocated to hold the written data. The page
> >  will be marked dirty and if the kernel will decide to repurpose it,
> >  the dirty page will be swapped out.
> 
> "if the kernel will decide to repurpose it" is awkward.  How about
> 
> if the kernel decides to repurpose it"?
> 
> >  OOM killer
> >  ==========
> >  
> > -It may happen, that on a loaded machine memory will be exhausted. When
> > +It may happen that on a loaded machine memory will be exhausted. When
> >  the kernel detects that the system runs out of memory (OOM) it invokes
> >  `OOM killer`.
> > Its mission is simple: all it has to do is to select a
> >  task to sacrifice for the sake of the overall system health. The
> 
> It is possible for the kernel to be unable to reclaim enough memory to
> continue to operate.  In order to save the rest of the system, it invokes
> the `OOM killer` to sacrifice one task.

How about:

It is possible that on a loaded machine memory will be exhausted and the
kernel will be unable to reclaim enough memory to continue to operate. In
order to save the rest of the system, it invokes the `OOM killer`.

The `OOM killer` selects a task to sacrifice for the sake of the overall
system health. The selected task is killed in a hope that after it exits
enough memory will be freed to continue normal operation.


-- 
Sincerely yours, Mike.

Re: [PATCH] docs/admin-guide/mm/concepts.rst: grammar fixups

[Randy Dunlap]

On 11/5/18 10:35 PM, Mike Rapoport wrote:
> On Mon, Nov 05, 2018 at 01:12:40PM -0800, Matthew Wilcox wrote:
>> On Mon, Nov 05, 2018 at 09:58:15PM +0200, Mike Rapoport wrote:
>>> @@ -21,10 +21,10 @@ Virtual Memory Primer
>>>  The physical memory in a computer system is a limited resource and
>>>  even for systems that support memory hotplug there is a hard limit on
>>>  the amount of memory that can be installed. The physical memory is not
>>> -necessary contiguous, it might be accessible as a set of distinct
>>> +necessary contiguous; it might be accessible as a set of distinct
>>
>> necessarily
>>
>>>  address ranges. Besides, different CPU architectures, and even
>>> -different implementations of the same architecture have different view
>>> -how these address ranges defined.
>>> +different implementations of the same architecture have different views
>>> +of how these address ranges defined.
>>
>> "are defined"?
>>
>>>  Each physical memory page can be mapped as one or more virtual
>>>  pages. These mappings are described by page tables that allow
>>> -translation from virtual address used by programs to real address in
>>> -the physical memory. The page tables organized hierarchically.
>>> +translation from a virtual address used by programs to the real
>>> +address in the physical memory. The page tables are organized
>>> +hierarchically.
>>
>> I don't like the term "real address".  Can we say "physical address in memory" here, or "address of physical memory" or something?
>  
> I didn't really like it as well, but I couldn't think of any better
> adjective to emphasize that address in the physical memory is "the real
> thing".
> 
> Maybe the best would be to drop "real" and make it 
> 
> "translation from a virtual address used by programs to the 
> address in the physical memory"

physical memory address ?


-- 
~Randy

Re: [PATCH] docs/admin-guide/mm/concepts.rst: grammar fixups

[Mike Rapoport]

On Mon, Nov 05, 2018 at 11:29:27PM -0800, Randy Dunlap wrote:
> On 11/5/18 10:35 PM, Mike Rapoport wrote:
> > On Mon, Nov 05, 2018 at 01:12:40PM -0800, Matthew Wilcox wrote:
> >> On Mon, Nov 05, 2018 at 09:58:15PM +0200, Mike Rapoport wrote:
> >>> @@ -21,10 +21,10 @@ Virtual Memory Primer
> >>>  The physical memory in a computer system is a limited resource and
> >>>  even for systems that support memory hotplug there is a hard limit on
> >>>  the amount of memory that can be installed. The physical memory is not
> >>> -necessary contiguous, it might be accessible as a set of distinct
> >>> +necessary contiguous; it might be accessible as a set of distinct
> >>
> >> necessarily
> >>
> >>>  address ranges. Besides, different CPU architectures, and even
> >>> -different implementations of the same architecture have different view
> >>> -how these address ranges defined.
> >>> +different implementations of the same architecture have different views
> >>> +of how these address ranges defined.
> >>
> >> "are defined"?
> >>
> >>>  Each physical memory page can be mapped as one or more virtual
> >>>  pages. These mappings are described by page tables that allow
> >>> -translation from virtual address used by programs to real address in
> >>> -the physical memory. The page tables organized hierarchically.
> >>> +translation from a virtual address used by programs to the real
> >>> +address in the physical memory. The page tables are organized
> >>> +hierarchically.
> >>
> >> I don't like the term "real address".  Can we say "physical address in memory" here, or "address of physical memory" or something?
> >  
> > I didn't really like it as well, but I couldn't think of any better
> > adjective to emphasize that address in the physical memory is "the real
> > thing".
> > 
> > Maybe the best would be to drop "real" and make it 
> > 
> > "translation from a virtual address used by programs to the 
> > address in the physical memory"
> 
> physical memory address ?

Works for me, thanks!
 
> 
> -- 
> ~Randy
> 

-- 
Sincerely yours,
Mike.