* [PATCH v2 1/2] docs/core-api: memory-allocation: remove uses of c:func:
2019-10-22 21:14 [PATCH v2 0/2] docs/core-api: memory-allocation: minor cleanups Chris Packham
@ 2019-10-22 21:14 ` Chris Packham
2019-10-24 18:02 ` Jonathan Corbet
2019-10-22 21:14 ` [PATCH v2 2/2] docs/core-api: memory-allocation: mention size helpers Chris Packham
1 sibling, 1 reply; 6+ messages in thread
From: Chris Packham @ 2019-10-22 21:14 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, linux-kernel, 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
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH v2 2/2] docs/core-api: memory-allocation: mention size helpers
2019-10-22 21:14 [PATCH v2 0/2] docs/core-api: memory-allocation: minor cleanups Chris Packham
2019-10-22 21:14 ` [PATCH v2 1/2] docs/core-api: memory-allocation: remove uses of c:func: Chris Packham
@ 2019-10-22 21:14 ` Chris Packham
1 sibling, 0 replies; 6+ messages in thread
From: Chris Packham @ 2019-10-22 21:14 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, linux-kernel, 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
^ permalink raw reply related [flat|nested] 6+ messages in thread