[PATCH v2 0/2] docs/core-api: memory-allocation: minor cleanups

[PATCH v2 0/2] docs/core-api: memory-allocation: minor cleanups

[Chris Packham]

Clean up some formatting and add references to helpers for calculating sizes
safely.

Chris Packham (2):
  docs/core-api: memory-allocation: remove uses of c:func:
  docs/core-api: memory-allocation: mention size helpers

 Documentation/core-api/memory-allocation.rst | 50 ++++++++++----------
 1 file changed, 24 insertions(+), 26 deletions(-)

-- 
2.23.0

[PATCH v2 1/2] docs/core-api: memory-allocation: remove uses of c:func:

[Chris Packham]

These are no longer needed as the documentation build will automatically
add the cross references.

Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
---

Notes:
    It should be noted that kvmalloc() and kmem_cache_destroy() lack a
    kerneldoc header, a side-effect of this change is that the :c:func:
    fallback of making them bold is lost. This is probably best fixed by
    adding a kerneldoc header to their source.
    
    Changes in v2:
    - new

 Documentation/core-api/memory-allocation.rst | 49 +++++++++-----------
 1 file changed, 23 insertions(+), 26 deletions(-)

diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
index e59779aa7615..14e22accdee7 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -88,39 +88,36 @@ Selecting memory allocator
 ==========================
 
 The most straightforward way to allocate memory is to use a function
-from the :c:func:`kmalloc` family. And, to be on the safe side it's
-best to use routines that set memory to zero, like
-:c:func:`kzalloc`. If you need to allocate memory for an array, there
-are :c:func:`kmalloc_array` and :c:func:`kcalloc` helpers.
+from the kmalloc() family. And, to be on the safe side it's best to use
+routines that set memory to zero, like kzalloc(). If you need to
+allocate memory for an array, there are kmalloc_array() and kcalloc()
+helpers.
 
 The maximal size of a chunk that can be allocated with `kmalloc` is
 limited. The actual limit depends on the hardware and the kernel
 configuration, but it is a good practice to use `kmalloc` for objects
 smaller than page size.
 
-For large allocations you can use :c:func:`vmalloc` and
-:c:func:`vzalloc`, or directly request pages from the page
-allocator. The memory allocated by `vmalloc` and related functions is
-not physically contiguous.
+For large allocations you can use vmalloc() and vzalloc(), or directly
+request pages from the page allocator. The memory allocated by `vmalloc`
+and related functions is not physically contiguous.
 
 If you are not sure whether the allocation size is too large for
-`kmalloc`, it is possible to use :c:func:`kvmalloc` and its
-derivatives. It will try to allocate memory with `kmalloc` and if the
-allocation fails it will be retried with `vmalloc`. There are
-restrictions on which GFP flags can be used with `kvmalloc`; please
-see :c:func:`kvmalloc_node` reference documentation. Note that
-`kvmalloc` may return memory that is not physically contiguous.
+`kmalloc`, it is possible to use kvmalloc() and its derivatives. It will
+try to allocate memory with `kmalloc` and if the allocation fails it
+will be retried with `vmalloc`. There are restrictions on which GFP
+flags can be used with `kvmalloc`; please see kvmalloc_node() reference
+documentation. Note that `kvmalloc` may return memory that is not
+physically contiguous.
 
 If you need to allocate many identical objects you can use the slab
-cache allocator. The cache should be set up with
-:c:func:`kmem_cache_create` or :c:func:`kmem_cache_create_usercopy`
-before it can be used. The second function should be used if a part of
-the cache might be copied to the userspace.  After the cache is
-created :c:func:`kmem_cache_alloc` and its convenience wrappers can
-allocate memory from that cache.
-
-When the allocated memory is no longer needed it must be freed. You
-can use :c:func:`kvfree` for the memory allocated with `kmalloc`,
-`vmalloc` and `kvmalloc`. The slab caches should be freed with
-:c:func:`kmem_cache_free`. And don't forget to destroy the cache with
-:c:func:`kmem_cache_destroy`.
+cache allocator. The cache should be set up with kmem_cache_create() or
+kmem_cache_create_usercopy() before it can be used. The second function
+should be used if a part of the cache might be copied to the userspace.
+After the cache is created kmem_cache_alloc() and its convenience
+wrappers can allocate memory from that cache.
+
+When the allocated memory is no longer needed it must be freed. You can
+use kvfree() for the memory allocated with `kmalloc`, `vmalloc` and
+`kvmalloc`. The slab caches should be freed with kmem_cache_free(). And
+don't forget to destroy the cache with kmem_cache_destroy().
-- 
2.23.0

[PATCH v2 2/2] docs/core-api: memory-allocation: mention size helpers

[Chris Packham]

Mention struct_size(), array_size() and array3_size() in the same place
as kmalloc() and friends.

Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
---

Notes:
    Changes in v2:
    - Drop use of c:func:

 Documentation/core-api/memory-allocation.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
index 14e22accdee7..5c9dd70b0115 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -91,7 +91,8 @@ The most straightforward way to allocate memory is to use a function
 from the kmalloc() family. And, to be on the safe side it's best to use
 routines that set memory to zero, like kzalloc(). If you need to
 allocate memory for an array, there are kmalloc_array() and kcalloc()
-helpers.
+helpers. The helpers struct_size(), array_size() and array3_size() can
+be used to safely calculate object sizes without overflowing.
 
 The maximal size of a chunk that can be allocated with `kmalloc` is
 limited. The actual limit depends on the hardware and the kernel
-- 
2.23.0

Re: [PATCH v2 1/2] docs/core-api: memory-allocation: remove uses of c:func:

[Jonathan Corbet]

On Wed, 23 Oct 2019 10:14:37 +1300
Chris Packham <chris.packham@alliedtelesis.co.nz> wrote:

> These are no longer needed as the documentation build will automatically
> add the cross references.
> 
> Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
> ---
> 
> Notes:
>     It should be noted that kvmalloc() and kmem_cache_destroy() lack a
>     kerneldoc header, a side-effect of this change is that the :c:func:
>     fallback of making them bold is lost. This is probably best fixed by
>     adding a kerneldoc header to their source.
>     
>     Changes in v2:
>     - new
> 
>  Documentation/core-api/memory-allocation.rst | 49 +++++++++-----------
>  1 file changed, 23 insertions(+), 26 deletions(-)

So I can't get this patch to apply, and I can't even figure out why.  If
you take the patch from the list, can you apply it to a docs-next (or
mainline) branch?

Thanks,

jon

Re: [PATCH v2 1/2] docs/core-api: memory-allocation: remove uses of c:func:

[Chris Packham]

Hi Jon,

On Thu, 2019-10-24 at 12:02 -0600, Jonathan Corbet wrote:
> On Wed, 23 Oct 2019 10:14:37 +1300
> Chris Packham <chris.packham@alliedtelesis.co.nz> wrote:
> 
> > These are no longer needed as the documentation build will automatically
> > add the cross references.
> > 
> > Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
> > ---
> > 
> > Notes:
> >     It should be noted that kvmalloc() and kmem_cache_destroy() lack a
> >     kerneldoc header, a side-effect of this change is that the :c:func:
> >     fallback of making them bold is lost. This is probably best fixed by
> >     adding a kerneldoc header to their source.
> >     
> >     Changes in v2:
> >     - new
> > 
> >  Documentation/core-api/memory-allocation.rst | 49 +++++++++-----------
> >  1 file changed, 23 insertions(+), 26 deletions(-)
> 
> So I can't get this patch to apply, and I can't even figure out why.  If
> you take the patch from the list, can you apply it to a docs-next (or
> mainline) branch?
> 

I think it might be dependent on my other typo fix patch[1]. I'll
rebase to v5.4-rc4 and send as a series of 3. Sorry for the hassle.

--
[1] 
https://lore.kernel.org/lkml/20191021003833.15704-1-chris.packham@alliedtelesis.co.nz/


> Thanks,
> 
> jon

Re: [PATCH v2 1/2] docs/core-api: memory-allocation: remove uses of c:func:

[Randy Dunlap]

On 10/24/19 12:39 PM, Chris Packham wrote:
> Hi Jon,
> 
> On Thu, 2019-10-24 at 12:02 -0600, Jonathan Corbet wrote:
>> On Wed, 23 Oct 2019 10:14:37 +1300
>> Chris Packham <chris.packham@alliedtelesis.co.nz> wrote:
>>
>>> These are no longer needed as the documentation build will automatically
>>> add the cross references.
>>>
>>> Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
>>> ---
>>>
>>>  Documentation/core-api/memory-allocation.rst | 49 +++++++++-----------
>>>  1 file changed, 23 insertions(+), 26 deletions(-)
>>
>> So I can't get this patch to apply, and I can't even figure out why.  If
>> you take the patch from the list, can you apply it to a docs-next (or
>> mainline) branch?
>>
> 
> I think it might be dependent on my other typo fix patch[1]. I'll
> rebase to v5.4-rc4 and send as a series of 3. Sorry for the hassle.
> 
> --
> [1] 
> https://lore.kernel.org/lkml/20191021003833.15704-1-chris.packham@alliedtelesis.co.nz/
> 
> 
>> Thanks,
>>
>> jon

patch tells me:
patch: **** malformed patch at line 84: -:c:func:`kmem_cache_destroy`.

-- 
~Randy