docs/core-api/mm: fix return value descriptions
Subsystems (9)
cover docs/core-api/mm: fix return value descriptions
Many kernel-doc comments referenced by Documentation/core-api/mm-api.rst have the return value descriptions misformatted or lack it completely. This makes kernel-doc script unhappy and produces more than 100 warnings when running
make htmldocs V=1
These patches fix the formatting of present return value descriptions and add some new ones.
As these patches touch lots of mm/ files, I think it's better to merge them via -mm tree.
Side note:
----------
I've noticed that kernel-doc produces
warning: contents before sections
when it is parsing description of a function that has no parameters, but does have a return value, i.e.
unsigned long nr_free_buffer_pages(void)
As far as I can tell, the generated html is ok no matter if the detailed description present before 'the sections', so probably this warning is not really needed?
Mike Rapoport (3):
docs/mm: vmalloc: re-indent kernel-doc comemnts docs/core-api/mm: fix user memory accessors formatting docs/core-api/mm: fix return value descriptions in mm/
arch/x86/include/asm/uaccess.h | 24 +-- arch/x86/lib/usercopy_32.c | 8 +- mm/dmapool.c | 13 +- mm/filemap.c | 73 ++++++-- mm/memory.c | 26 ++- mm/mempool.c | 8 + mm/page-writeback.c | 24 ++- mm/page_alloc.c | 24 ++- mm/readahead.c | 2 + mm/slab.c | 14 ++ mm/slab_common.c | 6 + mm/truncate.c | 6 +- mm/util.c | 37 ++-- mm/vmalloc.c | 394 ++++++++++++++++++++++------------------- 14 files changed, 409 insertions(+), 250 deletions(-)
Signature · 1 line
2.7.4
PATCH RESEND 1/3 docs/mm: vmalloc: re-indent kernel-doc comemnts
Some kernel-doc comments in mm/vmalloc.c have leading tab in indentation. This leads to excessive indentation in the generated HTML and to the inconsistency of its layout ([1] vs [2]).
Besides, multi-line Note: sections are not handled properly with extra indentation.
[1] https://www.kernel.org/doc/html/v4.20/core-api/mm-api.html?#c.vm_map_ram
[2] https://www.kernel.org/doc/html/v4.20/core-api/mm-api.html?#c.vfree
--- mm/vmalloc.c | 367 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 182 insertions(+), 185 deletions(-)
mm/vmalloc.c +182 -185
@@ -1187,6 +1187,7 @@ void *vm_map_ram(struct page **pages, unsigned int count, int node, pgprot_t proEXPORT_SYMBOL (vm_map_ram);static struct vm_struct *vmlist__initdata ; +/** * vm_area_add_early - add vmap area early during boot * @vm: vm_struct to add
@@ -1421,13 +1422,13 @@ struct vm_struct *__get_vm_area_caller(unsigned long size, unsigned long flags, }/** -* get_vm_area - reserve a contiguous kernel virtual area -* @size: size of the area -* @flags: %VM_IOREMAP for I/O mappings or VM_ALLOC +* get_vm_area - reserve a contiguous kernel virtual area +* @size: size of the area +* @flags: %VM_IOREMAP for I/O mappings or VM_ALLOC * -* Search an area of @size in the kernel virtual mapping area, -* and reserved it for out purposes. Returns the area descriptor -* on success or %NULL on failure. +* Search an area of @size in the kernel virtual mapping area, +* and reserved it for out purposes. Returns the area descriptor +* on success or %NULL on failure. */ struct vm_struct *get_vm_area (unsigned long size,unsigned long flags) {
@@ -1444,12 +1445,12 @@ struct vm_struct *get_vm_area_caller(unsigned long size, unsigned long flags, }/** -* find_vm_area - find a continuous kernel virtual area -* @addr: base address +* find_vm_area - find a continuous kernel virtual area +* @addr: base address * -* Search for the kernel VM area starting at @addr, and return it. -* It is up to the caller to do all required locking to keep the returned -* pointer valid. +* Search for the kernel VM area starting at @addr, and return it. +* It is up to the caller to do all required locking to keep the returned +* pointer valid. */ struct vm_struct *find_vm_area (const void *addr) {
@@ -1463,12 +1464,12 @@ struct vm_struct *find_vm_area(const void *addr) }/** -* remove_vm_area - find and remove a continuous kernel virtual area -* @addr: base address +* remove_vm_area - find and remove a continuous kernel virtual area +* @addr: base address * -* Search for the kernel VM area starting at @addr, and remove it. -* This function returns the found VM area, but using it is NOT safe -* on SMP machines, except for its size or flags. +* Search for the kernel VM area starting at @addr, and remove it. +* This function returns the found VM area, but using it is NOT safe +* on SMP machines, except for its size or flags. */ struct vm_struct *remove_vm_area (const void *addr) {
@@ -1548,11 +1549,11 @@ static inline void __vfree_deferred(const void *addr) }/** -* vfree_atomic - release memory allocated by vmalloc() -* @addr: memory base address +* vfree_atomic - release memory allocated by vmalloc() +* @addr: memory base address * -* This one is just like vfree() but can be called in any atomic context -* except NMIs. +* This one is just like vfree() but can be called in any atomic context +* except NMIs. */ void vfree_atomic (const void *addr) {
@@ -1566,20 +1567,20 @@ void vfree_atomic(const void *addr) }/** -* vfree - release memory allocated by vmalloc() -* @addr: memory base address +* vfree - release memory allocated by vmalloc() +* @addr: memory base address * -* Free the virtually continuous memory area starting at @addr, as -* obtained from vmalloc(), vmalloc_32() or __vmalloc(). If @addr is -* NULL, no operation is performed. +* Free the virtually continuous memory area starting at @addr, as +* obtained from vmalloc(), vmalloc_32() or __vmalloc(). If @addr is +* NULL, no operation is performed. * -* Must not be called in NMI context (strictly speaking, only if we don't -* have CONFIG_ARCH_HAVE_NMI_SAFE_CMPXCHG, but making the calling -* conventions for vfree() arch-depenedent would be a really bad idea) +* Must not be called in NMI context (strictly speaking, only if we don't +* have CONFIG_ARCH_HAVE_NMI_SAFE_CMPXCHG, but making the calling +* conventions for vfree() arch-depenedent would be a really bad idea) * -* May sleep if called *not* from interrupt context. +* May sleep if called *not* from interrupt context. * -* NOTE: assumes that the object at @addr has a size >= sizeof(llist_node) +* NOTE: assumes that the object at @addr has a size >= sizeof(llist_node) */ void vfree (const void *addr) {
@@ -1599,13 +1600,13 @@ void vfree(const void *addr)EXPORT_SYMBOL (vfree);/** -* vunmap - release virtual mapping obtained by vmap() -* @addr: memory base address +* vunmap - release virtual mapping obtained by vmap() +* @addr: memory base address * -* Free the virtually contiguous memory area starting at @addr, -* which was created from the page array passed to vmap(). +* Free the virtually contiguous memory area starting at @addr, +* which was created from the page array passed to vmap(). * -* Must not be called in interrupt context. +* Must not be called in interrupt context. */ void vunmap (const void *addr) {
@@ -1617,17 +1618,17 @@ void vunmap(const void *addr)EXPORT_SYMBOL (vunmap);/** -* vmap - map an array of pages into virtually contiguous space -* @pages: array of page pointers -* @count: number of pages to map -* @flags: vm_area->flags -* @prot: page protection for the mapping -* -* Maps @count pages from @pages into contiguous kernel virtual -* space. +* vmap - map an array of pages into virtually contiguous space +* @pages: array of page pointers +* @count: number of pages to map +* @flags: vm_area->flags +* @prot: page protection for the mapping +* +* Maps @count pages from @pages into contiguous kernel virtual +* space. */ void *vmap (struct page **pages,unsigned int count, -unsigned long flags,pgprot_t prot) +unsigned long flags,pgprot_t prot) {struct vm_struct *area;unsigned long size;/* In bytes */
@@ -1714,20 +1715,20 @@ static void *__vmalloc_area_node(struct vm_struct *area, gfp_t gfp_mask, }/** -* __vmalloc_node_range - allocate virtually contiguous memory -* @size: allocation size -* @align: desired alignment -* @start: vm area range start -* @end: vm area range end -* @gfp_mask: flags for the page level allocator -* @prot: protection mask for the allocated pages -* @vm_flags: additional vm area flags (e.g. %VM_NO_GUARD) -* @node: node to use for allocation or NUMA_NO_NODE -* @caller: caller's return address -* -* Allocate enough pages to cover @size from the page level -* allocator with @gfp_mask flags. Map them into contiguous -* kernel virtual space, using a pagetable protection of @prot. +* __vmalloc_node_range - allocate virtually contiguous memory +* @size: allocation size +* @align: desired alignment +* @start: vm area range start +* @end: vm area range end +* @gfp_mask: flags for the page level allocator +* @prot: protection mask for the allocated pages +* @vm_flags: additional vm area flags (e.g. %VM_NO_GUARD) +* @node: node to use for allocation or NUMA_NO_NODE +* @caller: caller's return address +* +* Allocate enough pages to cover @size from the page level +* allocator with @gfp_mask flags. Map them into contiguous +* kernel virtual space, using a pagetable protection of @prot. */ void *__vmalloc_node_range(unsigned long size, unsigned long align, unsigned long start, unsigned long end, gfp_t gfp_mask,
@@ -1769,24 +1770,23 @@ void *__vmalloc_node_range(unsigned long size, unsigned long align, }/** -* __vmalloc_node - allocate virtually contiguous memory -* @size: allocation size -* @align: desired alignment -* @gfp_mask: flags for the page level allocator -* @prot: protection mask for the allocated pages -* @node: node to use for allocation or NUMA_NO_NODE -* @caller: caller's return address -* -* Allocate enough pages to cover @size from the page level -* allocator with @gfp_mask flags. Map them into contiguous -* kernel virtual space, using a pagetable protection of @prot. +* __vmalloc_node - allocate virtually contiguous memory +* @size: allocation size +* @align: desired alignment +* @gfp_mask: flags for the page level allocator +* @prot: protection mask for the allocated pages +* @node: node to use for allocation or NUMA_NO_NODE +* @caller: caller's return address * -* Reclaim modifiers in @gfp_mask - __GFP_NORETRY, __GFP_RETRY_MAYFAIL -* and __GFP_NOFAIL are not supported +* Allocate enough pages to cover @size from the page level +* allocator with @gfp_mask flags. Map them into contiguous +* kernel virtual space, using a pagetable protection of @prot. * -* Any use of gfp flags outside of GFP_KERNEL should be consulted -* with mm people. +* Reclaim modifiers in @gfp_mask - __GFP_NORETRY, __GFP_RETRY_MAYFAIL +* and __GFP_NOFAIL are not supported * +* Any use of gfp flags outside of GFP_KERNEL should be consulted +* with mm people. */ static void *__vmalloc_node(unsigned long size, unsigned long align, gfp_t gfp_mask, pgprot_t prot,
@@ -1818,13 +1818,14 @@ void *__vmalloc_node_flags_caller(unsigned long size, int node, gfp_t flags, }/** -* vmalloc - allocate virtually contiguous memory -* @size: allocation size -* Allocate enough pages to cover @size from the page level -* allocator and map them into contiguous kernel virtual space. +* vmalloc - allocate virtually contiguous memory +* @size: allocation size +* +* Allocate enough pages to cover @size from the page level +* allocator and map them into contiguous kernel virtual space. * -* For tight control over page level allocator and protection flags -* use __vmalloc() instead. +* For tight control over page level allocator and protection flags +* use __vmalloc() instead. */ void *vmalloc (unsigned long size) {
@@ -1834,14 +1835,15 @@ void *vmalloc(unsigned long size)EXPORT_SYMBOL (vmalloc);/** -* vzalloc - allocate virtually contiguous memory with zero fill -* @size: allocation size -* Allocate enough pages to cover @size from the page level -* allocator and map them into contiguous kernel virtual space. -* The memory allocated is set to zero. -* -* For tight control over page level allocator and protection flags -* use __vmalloc() instead. +* vzalloc - allocate virtually contiguous memory with zero fill +* @size: allocation size +* +* Allocate enough pages to cover @size from the page level +* allocator and map them into contiguous kernel virtual space. +* The memory allocated is set to zero. +* +* For tight control over page level allocator and protection flags +* use __vmalloc() instead. */ void *vzalloc (unsigned long size) {
@@ -1875,15 +1877,15 @@ void *vmalloc_user(unsigned long size)EXPORT_SYMBOL (vmalloc_user);/** -* vmalloc_node - allocate memory on a specific node -* @size: allocation size -* @node: numa node +* vmalloc_node - allocate memory on a specific node +* @size: allocation size +* @node: numa node * -* Allocate enough pages to cover @size from the page level -* allocator and map them into contiguous kernel virtual space. +* Allocate enough pages to cover @size from the page level +* allocator and map them into contiguous kernel virtual space. * -* For tight control over page level allocator and protection flags -* use __vmalloc() instead. +* For tight control over page level allocator and protection flags +* use __vmalloc() instead. */ void *vmalloc_node (unsigned long size,int node) {
@@ -1912,17 +1914,16 @@ void *vzalloc_node(unsigned long size, int node)EXPORT_SYMBOL (vzalloc_node);/** -* vmalloc_exec - allocate virtually contiguous, executable memory -* @size: allocation size +* vmalloc_exec - allocate virtually contiguous, executable memory +* @size: allocation size * -* Kernel-internal function to allocate enough pages to cover @size -* the page level allocator and map them into contiguous and -* executable kernel virtual space. +* Kernel-internal function to allocate enough pages to cover @size +* the page level allocator and map them into contiguous and +* executable kernel virtual space. * -* For tight control over page level allocator and protection flags -* use __vmalloc() instead. +* For tight control over page level allocator and protection flags +* use __vmalloc() instead. */ -void *vmalloc_exec (unsigned long size) { return __vmalloc_node(size, 1, GFP_KERNEL, PAGE_KERNEL_EXEC,
@@ -1942,11 +1943,11 @@ void *vmalloc_exec(unsigned long size)#endif /** -* vmalloc_32 - allocate virtually contiguous memory (32bit addressable) -* @size: allocation size +* vmalloc_32 - allocate virtually contiguous memory (32bit addressable) +* @size: allocation size * -* Allocate enough 32bit PA addressable pages to cover @size from the -* page level allocator and map them into contiguous kernel virtual space. +* Allocate enough 32bit PA addressable pages to cover @size from the +* page level allocator and map them into contiguous kernel virtual space. */ void *vmalloc_32 (unsigned long size) {
@@ -1957,7 +1958,7 @@ EXPORT_SYMBOL(vmalloc_32);/** * vmalloc_32_user - allocate zeroed virtually contiguous 32bit memory -* @size: allocation size +* @size: allocation size * * The resulting memory area is 32bit addressable and zeroed so it can be * mapped to userspace without leaking data.
@@ -2059,31 +2060,29 @@ static int aligned_vwrite(char *buf, char *addr, unsigned long count) }/** -* vread() - read vmalloc area in a safe way. -* @buf: buffer for reading data -* @addr: vm address. -* @count: number of bytes to be read. -* -* Returns # of bytes which addr and buf should be increased. -* (same number to @count). Returns 0 if [addr...addr+count) doesn't -* includes any intersect with alive vmalloc area. -* -* This function checks that addr is a valid vmalloc'ed area, and -* copy data from that area to a given buffer. If the given memory range -* of [addr...addr+count) includes some valid address, data is copied to -* proper area of @buf. If there are memory holes, they'll be zero-filled. -* IOREMAP area is treated as memory hole and no copy is done. -* -* If [addr...addr+count) doesn't includes any intersects with alive -* vm_struct area, returns 0. @buf should be kernel's buffer. -* -* Note: In usual ops, vread() is never necessary because the caller -* should know vmalloc() area is valid and can use memcpy(). -* This is for routines which have to access vmalloc area without -* any informaion, as /dev/kmem. -* +* vread() - read vmalloc area in a safe way. +* @buf: buffer for reading data +* @addr: vm address. +* @count: number of bytes to be read. +* +* Returns # of bytes which addr and buf should be increased. +* (same number to @count). Returns 0 if [addr...addr+count) doesn't +* includes any intersect with alive vmalloc area. +* +* This function checks that addr is a valid vmalloc'ed area, and +* copy data from that area to a given buffer. If the given memory range +* of [addr...addr+count) includes some valid address, data is copied to +* proper area of @buf. If there are memory holes, they'll be zero-filled. +* IOREMAP area is treated as memory hole and no copy is done. +* +* If [addr...addr+count) doesn't includes any intersects with alive +* vm_struct area, returns 0. @buf should be kernel's buffer. +* +* Note: In usual ops, vread() is never necessary because the caller +* should know vmalloc() area is valid and can use memcpy(). +* This is for routines which have to access vmalloc area without +* any informaion, as /dev/kmem. */ -long vread (char *buf,char *addr,unsigned long count) {struct vmap_area *va;
@@ -2140,31 +2139,30 @@ long vread(char *buf, char *addr, unsigned long count) }/** -* vwrite() - write vmalloc area in a safe way. -* @buf: buffer for source data -* @addr: vm address. -* @count: number of bytes to be read. -* -* Returns # of bytes which addr and buf should be incresed. -* (same number to @count). -* If [addr...addr+count) doesn't includes any intersect with valid -* vmalloc area, returns 0. -* -* This function checks that addr is a valid vmalloc'ed area, and -* copy data from a buffer to the given addr. If specified range of -* [addr...addr+count) includes some valid address, data is copied from -* proper area of @buf. If there are memory holes, no copy to hole. -* IOREMAP area is treated as memory hole and no copy is done. -* -* If [addr...addr+count) doesn't includes any intersects with alive -* vm_struct area, returns 0. @buf should be kernel's buffer. -* -* Note: In usual ops, vwrite() is never necessary because the caller -* should know vmalloc() area is valid and can use memcpy(). -* This is for routines which have to access vmalloc area without -* any informaion, as /dev/kmem. +* vwrite() - write vmalloc area in a safe way. +* @buf: buffer for source data +* @addr: vm address. +* @count: number of bytes to be read. +* +* Returns # of bytes which addr and buf should be incresed. +* (same number to @count). +* If [addr...addr+count) doesn't includes any intersect with valid +* vmalloc area, returns 0. +* +* This function checks that addr is a valid vmalloc'ed area, and +* copy data from a buffer to the given addr. If specified range of +* [addr...addr+count) includes some valid address, data is copied from +* proper area of @buf. If there are memory holes, no copy to hole. +* IOREMAP area is treated as memory hole and no copy is done. +* +* If [addr...addr+count) doesn't includes any intersects with alive +* vm_struct area, returns 0. @buf should be kernel's buffer. +* +* Note: In usual ops, vwrite() is never necessary because the caller +* should know vmalloc() area is valid and can use memcpy(). +* This is for routines which have to access vmalloc area without +* any informaion, as /dev/kmem. */ -long vwrite (char *buf,char *addr,unsigned long count) {struct vmap_area *va;
@@ -2216,20 +2214,20 @@ long vwrite(char *buf, char *addr, unsigned long count) }/** -* remap_vmalloc_range_partial - map vmalloc pages to userspace -* @vma: vma to cover -* @uaddr: target user address to start at -* @kaddr: virtual address of vmalloc kernel memory -* @size: size of map area +* remap_vmalloc_range_partial - map vmalloc pages to userspace +* @vma: vma to cover +* @uaddr: target user address to start at +* @kaddr: virtual address of vmalloc kernel memory +* @size: size of map area * -* Returns: 0 for success, -Exxx on failure +* Returns: 0 for success, -Exxx on failure * -* This function checks that @kaddr is a valid vmalloc'ed area, -* and that it is big enough to cover the range starting at -* @uaddr in @vma. Will return failure if that criteria isn't -* met. +* This function checks that @kaddr is a valid vmalloc'ed area, +* and that it is big enough to cover the range starting at +* @uaddr in @vma. Will return failure if that criteria isn't +* met. * -* Similar to remap_pfn_range() (see mm/memory.c) +* Similar to remap_pfn_range() (see mm/memory.c) */ int remap_vmalloc_range_partial (struct vm_area_struct *vma,unsigned long uaddr,void *kaddr,unsigned long size)
@@ -2271,18 +2269,18 @@ int remap_vmalloc_range_partial(struct vm_area_struct *vma, unsigned long uaddr,EXPORT_SYMBOL (remap_vmalloc_range_partial);/** -* remap_vmalloc_range - map vmalloc pages to userspace -* @vma: vma to cover (map full range of vma) -* @addr: vmalloc memory -* @pgoff: number of pages into addr before first page to map +* remap_vmalloc_range - map vmalloc pages to userspace +* @vma: vma to cover (map full range of vma) +* @addr: vmalloc memory +* @pgoff: number of pages into addr before first page to map * -* Returns: 0 for success, -Exxx on failure +* Returns: 0 for success, -Exxx on failure * -* This function checks that addr is a valid vmalloc'ed area, and -* that it is big enough to cover the vma. Will return failure if -* that criteria isn't met. +* This function checks that addr is a valid vmalloc'ed area, and +* that it is big enough to cover the vma. Will return failure if +* that criteria isn't met. * -* Similar to remap_pfn_range() (see mm/memory.c) +* Similar to remap_pfn_range() (see mm/memory.c) */ int remap_vmalloc_range (struct vm_area_struct *vma,void *addr,unsigned long pgoff)
@@ -2314,18 +2312,18 @@ static int f(pte_t *pte, pgtable_t table, unsigned long addr, void *data) }/** -* alloc_vm_area - allocate a range of kernel address space -* @size: size of the area -* @ptes: returns the PTEs for the address space +* alloc_vm_area - allocate a range of kernel address space +* @size: size of the area +* @ptes: returns the PTEs for the address space * -* Returns: NULL on failure, vm_struct on success +* Returns: NULL on failure, vm_struct on success * -* This function reserves a range of kernel address space, and -* allocates pagetables to map that range. No actual mappings -* are created. +* This function reserves a range of kernel address space, and +* allocates pagetables to map that range. No actual mappings +* are created. * -* If @ptes is non-NULL, pointers to the PTEs (in init_mm) -* allocated for the VM area are returned. +* If @ptes is non-NULL, pointers to the PTEs (in init_mm) +* allocated for the VM area are returned. */ struct vm_struct *alloc_vm_area (size_t size,pte_t **ptes) {
@@ -2751,4 +2749,3 @@ static int __init proc_vmalloc_init(void)module_init (proc_vmalloc_init);#endif -
Signature · 1 line
2.7.4
PATCH RESEND 2/3 docs/core-api/mm: fix user memory accessors formatting
In reply to Mike RapoportThe descriptions of userspace memory access functions had minor issues with formatting that made kernel-doc unable to properly detect the function/macro names and the return value sections:
./arch/x86/include/asm/uaccess.h:80: info: Scanning doc for ./arch/x86/include/asm/uaccess.h:139: info: Scanning doc for ./arch/x86/include/asm/uaccess.h:231: info: Scanning doc for ./arch/x86/include/asm/uaccess.h:505: info: Scanning doc for ./arch/x86/include/asm/uaccess.h:530: info: Scanning doc for ./arch/x86/lib/usercopy_32.c:58: info: Scanning doc for ./arch/x86/lib/usercopy_32.c:69: warning: No description found for return value of 'clear_user'./arch/x86/lib/usercopy_32.c:78: info: Scanning doc for ./arch/x86/lib/usercopy_32.c:90: warning: No description found for return value of '__clear_user'
Fix the formatting.
--- arch/x86/include/asm/uaccess.h | 24 ++++++++++++------------ arch/x86/lib/usercopy_32.c | 8 ++++---- 2 files changed, 16 insertions(+), 16 deletions(-)
arch/x86/include/asm/uaccess.h +12 -12
@@ -76,7 +76,7 @@ static inline bool __chk_range_not_ok(unsigned long addr, unsigned long size, un#endif /** -* access_ok: - Checks if a user space pointer is valid +* access_ok - Checks if a user space pointer is valid * @addr: User space pointer to start of block to check * @size: Size of block to check *
@@ -85,12 +85,12 @@ static inline bool __chk_range_not_ok(unsigned long addr, unsigned long size, un* * Checks if a pointer to a block of memory in user space is valid. * -* Returns true (nonzero) if the memory block may be valid, false (zero) -* if it is definitely invalid. -* * Note that, depending on architecture, this function probably just * checks that the pointer is in the user space range - after calling * this function, memory access functions may still return -EFAULT. +* +* Return: true (nonzero) if the memory block may be valid, false (zero) +* if it is definitely invalid. */ #define access_ok (addr, size) \ ({ \
@@ -135,7 +135,7 @@ extern int __get_user_bad(void);__typeof__ (__builtin_choose_expr (sizeof (x) >sizeof (0UL ),0ULL ,0UL ))/** -* get_user: - Get a simple variable from user space. +* get_user - Get a simple variable from user space. * @x: Variable to store result. * @ptr: Source address, in user space. *
@@ -149,7 +149,7 @@ __typeof__(__builtin_choose_expr(sizeof(x) > sizeof(0UL), 0ULL, 0UL))* @ptr must have pointer-to-simple-variable type, and the result of * dereferencing @ptr must be assignable to @x without a cast. * -* Returns zero on success, or -EFAULT on error. +* Return: zero on success, or -EFAULT on error. * On error, the variable @x is set to zero. */ /*
@@ -227,7 +227,7 @@ extern void __put_user_4(void);extern void __put_user_8 (void );/** -* put_user: - Write a simple value into user space. +* put_user - Write a simple value into user space. * @x: Value to copy to user space. * @ptr: Destination address, in user space. *
@@ -241,7 +241,7 @@ extern void __put_user_8(void);* @ptr must have pointer-to-simple-variable type, and @x must be assignable * to the result of dereferencing @ptr. * -* Returns zero on success, or -EFAULT on error. +* Return: zero on success, or -EFAULT on error. */ #define put_user (x, ptr) \ ({ \
@@ -501,7 +501,7 @@ struct __large_struct { unsigned long buf[100]; }; }while (0 )/** -* __get_user: - Get a simple variable from user space, with less checking. +* __get_user - Get a simple variable from user space, with less checking. * @x: Variable to store result. * @ptr: Source address, in user space. *
@@ -518,7 +518,7 @@ struct __large_struct { unsigned long buf[100]; };* Caller must check the pointer with access_ok() before calling this * function. * -* Returns zero on success, or -EFAULT on error. +* Return: zero on success, or -EFAULT on error. * On error, the variable @x is set to zero. */
@@ -526,7 +526,7 @@ struct __large_struct { unsigned long buf[100]; };__get_user_nocheck ((x), (ptr),sizeof (*(ptr)))/** -* __put_user: - Write a simple value into user space, with less checking. +* __put_user - Write a simple value into user space, with less checking. * @x: Value to copy to user space. * @ptr: Destination address, in user space. *
@@ -543,7 +543,7 @@ struct __large_struct { unsigned long buf[100]; };* Caller must check the pointer with access_ok() before calling this * function. * -* Returns zero on success, or -EFAULT on error. +* Return: zero on success, or -EFAULT on error. */ #define __put_user (x, ptr) \
arch/x86/lib/usercopy_32.c +4 -4
@@ -54,13 +54,13 @@ do { \ }while (0 )/** -* clear_user: - Zero a block of memory in user space. +* clear_user - Zero a block of memory in user space. * @to: Destination address, in user space. * @n: Number of bytes to zero. * * Zero a block of memory in user space. * -* Returns number of bytes that could not be cleared. +* Return: number of bytes that could not be cleared. * On success, this will be zero. */ unsigned long
@@ -74,14 +74,14 @@ clear_user(void __user *to, unsigned long n)EXPORT_SYMBOL (clear_user);/** -* __clear_user: - Zero a block of memory in user space, with less checking. +* __clear_user - Zero a block of memory in user space, with less checking. * @to: Destination address, in user space. * @n: Number of bytes to zero. * * Zero a block of memory in user space. Caller must check * the specified block with access_ok() before calling this function. * -* Returns number of bytes that could not be cleared. +* Return: number of bytes that could not be cleared. * On success, this will be zero. */ unsigned long
Signature · 1 line
2.7.4
PATCH RESEND 3/3 docs/core-api/mm: fix return value descriptions in mm/
In reply to Mike RapoportMany kernel-doc comments in mm/ have the return value descriptions either misformatted or omitted at all which makes kernel-doc script unhappy:
$ make V=1 htmldocs ... ./mm/util.c:36: info: Scanning doc for kstrdup ./mm/util.c:41: warning: No description found for return value of 'kstrdup' ./mm/util.c:57: info: Scanning doc for kstrdup_const ./mm/util.c:66: warning: No description found for return value of 'kstrdup_const' ./mm/util.c:75: info: Scanning doc for kstrndup ./mm/util.c:83: warning: No description found for return value of 'kstrndup' ...
Fixing the formatting and adding the missing return value descriptions eliminates ~100 such warnings.
--- mm/dmapool.c | 13 +++++++--- mm/filemap.c | 73 +++++++++++++++++++++++++++++++++++++++++++++-------- mm/memory.c | 26 ++++++++++++++----- mm/mempool.c | 8 ++++++ mm/page-writeback.c | 24 ++++++++++++------ mm/page_alloc.c | 24 +++++++++++++----- mm/readahead.c | 2 ++ mm/slab.c | 14 ++++++++++ mm/slab_common.c | 6 +++++ mm/truncate.c | 6 +++-- mm/util.c | 37 +++++++++++++++++++-------- mm/vmalloc.c | 47 ++++++++++++++++++++++++++-------- 12 files changed, 221 insertions(+), 59 deletions(-)
mm/dmapool.c +9 -4
@@ -114,10 +114,9 @@ static DEVICE_ATTR(pools, 0444, show_pools, NULL);* @size: size of the blocks in this pool. * @align: alignment requirement for blocks; must be a power of two * @boundary: returned blocks won't cross this power of two boundary -* Context: !in_interrupt() +* Context: not in_interrupt() * -* Returns a dma allocation pool with the requested characteristics, or -* null if one can't be created. Given one of these pools, dma_pool_alloc() +* Given one of these pools, dma_pool_alloc() * may be used to allocate memory. Such memory will all have "consistent" * DMA mappings, accessible by the device and its driver without using * cache flushing primitives. The actual size of blocks allocated may be
@@ -127,6 +126,9 @@ static DEVICE_ATTR(pools, 0444, show_pools, NULL);* cross that size boundary. This is useful for devices which have * addressing restrictions on individual DMA transfers, such as not crossing * boundaries of 4KBytes. +* +* Return: a dma allocation pool with the requested characteristics, or +* %NULL if one can't be created. */ struct dma_pool *dma_pool_create (const char *name,struct device *dev,size_t size,size_t align,size_t boundary)
@@ -313,7 +315,7 @@ EXPORT_SYMBOL(dma_pool_destroy);* @mem_flags: GFP_* bitmask * @handle: pointer to dma address of block * -* This returns the kernel virtual address of a currently unused block, +* Return: the kernel virtual address of a currently unused block, * and reports its dma address through the handle. * If such a memory block can't be allocated, %NULL is returned. */
@@ -498,6 +500,9 @@ static int dmam_pool_match(struct device *dev, void *res, void *match_data)* * Managed dma_pool_create(). DMA pool created with this function is * automatically destroyed on driver detach. +* +* Return: a managed dma allocation pool with the requested +* characteristics, or %NULL if one can't be created. */ struct dma_pool *dmam_pool_create (const char *name,struct device *dev,size_t size,size_t align,size_t allocation)
mm/filemap.c +62 -11
253 lines not on this page · raw message
mm/memory.c +19 -7
@@ -1503,6 +1503,8 @@ static int insert_page(struct vm_area_struct *vma, unsigned long addr,* under mm->mmap_sem write-lock, so it can change vma->vm_flags. * Caller must set VM_MIXEDMAP on vma if it wants to call this * function from other places, for example from page-fault handler. +* +* Return: %0 on success, negative error code otherwise. */ int vm_insert_page (struct vm_area_struct *vma,unsigned long addr,struct page *page)
@@ -1830,7 +1832,9 @@ static inline int remap_p4d_range(struct mm_struct *mm, pgd_t *pgd,* @size: size of map area * @prot: page protection flags for this mapping * -* Note: this is only safe if the mm semaphore is held when called. +* Note: this is only safe if the mm semaphore is held when called. +* +* Return: %0 on success, negative error code otherwise. */ int remap_pfn_range (struct vm_area_struct *vma,unsigned long addr,unsigned long pfn,unsigned long size,pgprot_t prot)
@@ -1903,6 +1907,8 @@ EXPORT_SYMBOL(remap_pfn_range);* * NOTE! Some drivers might want to tweak vma->vm_page_prot first to get * whatever write-combining details or similar. +* +* Return: %0 on success, negative error code otherwise. */ int vm_iomap_memory (struct vm_area_struct *vma,phys_addr_t start,unsigned long len) {
@@ -2381,12 +2387,13 @@ static vm_fault_t wp_page_copy(struct vm_fault *vmf)* * This function handles all that is needed to finish a write page fault in a * shared mapping due to PTE being read-only once the mapped page is prepared. -* It handles locking of PTE and modifying it. The function returns -* VM_FAULT_WRITE on success, 0 when PTE got changed before we acquired PTE -* lock. +* It handles locking of PTE and modifying it. * * The function expects the page to be locked or other protection against * concurrent faults / writeback (such as DAX radix tree locks). +* +* Return: %VM_FAULT_WRITE on success, %0 when PTE got changed before +* we acquired PTE lock. */ vm_fault_t finish_mkwrite_fault (struct vm_fault *vmf) {
@@ -3179,6 +3186,8 @@ static vm_fault_t do_set_pmd(struct vm_fault *vmf, struct page *page)* * Target users are page handler itself and implementations of * vm_ops->map_pages. +* +* Return: %0 on success, %VM_FAULT_ code in case of error. */ vm_fault_t alloc_set_pte (struct vm_fault *vmf,struct mem_cgroup *memcg,struct page *page)
@@ -3239,11 +3248,12 @@ vm_fault_t alloc_set_pte(struct vm_fault *vmf, struct mem_cgroup *memcg,* This function handles all that is needed to finish a page fault once the * page to fault in is prepared. It handles locking of PTEs, inserts PTE for * given page, adds reverse page mapping, handles memcg charges and LRU -* addition. The function returns 0 on success, VM_FAULT_ code in case of -* error. +* addition. * * The function expects the page to be locked and on success it consumes a * reference of a page being mapped (for the PTE which maps it). +* +* Return: %0 on success, %VM_FAULT_ code in case of error. */ vm_fault_t finish_fault (struct vm_fault *vmf) {
@@ -4128,7 +4138,7 @@ EXPORT_SYMBOL(follow_pte_pmd);* * Only IO mappings and raw PFN mappings are allowed. * -* Returns zero and the pfn at @pfn on success, -ve otherwise. +* Return: zero and the pfn at @pfn on success, -ve otherwise. */ int follow_pfn (struct vm_area_struct *vma,unsigned long address,unsigned long *pfn)
@@ -4278,6 +4288,8 @@ int __access_remote_vm(struct task_struct *tsk, struct mm_struct *mm,* @gup_flags: flags modifying lookup behaviour * * The caller must hold a reference on @mm. +* +* Return: number of bytes copied from source to destination. */ int access_remote_vm (struct mm_struct *mm,unsigned long addr,void *buf,int len,unsigned int gup_flags)
mm/mempool.c +8 -0
@@ -222,6 +222,8 @@ EXPORT_SYMBOL(mempool_init_node);* * Like mempool_create(), but initializes the pool in (i.e. embedded in another * structure). +* +* Return: %0 on success, negative error code otherwise. */ int mempool_init (mempool_t *pool,int min_nr,mempool_alloc_t *alloc_fn,mempool_free_t *free_fn,void *pool_data)
@@ -245,6 +247,8 @@ EXPORT_SYMBOL(mempool_init);* functions. This function might sleep. Both the alloc_fn() and the free_fn() * functions might sleep - as long as the mempool_alloc() function is not called * from IRQ contexts. +* +* Return: pointer to the created memory pool object or %NULL on error. */ mempool_t *mempool_create (int min_nr,mempool_alloc_t *alloc_fn,mempool_free_t *free_fn,void *pool_data)
@@ -289,6 +293,8 @@ EXPORT_SYMBOL(mempool_create_node);* Note, the caller must guarantee that no mempool_destroy is called * while this function is running. mempool_alloc() & mempool_free() * might be called (eg. from IRQ contexts) while this function executes. +* +* Return: %0 on success, negative error code otherwise. */ int mempool_resize (mempool_t *pool,int new_min_nr) {
@@ -363,6 +369,8 @@ EXPORT_SYMBOL(mempool_resize);* *never* fails when called from process contexts. (it might * fail if called from an IRQ context.) * Note: using __GFP_ZERO is not supported. +* +* Return: pointer to the allocated element or %NULL on error. */ void *mempool_alloc (mempool_t *pool,gfp_t gfp_mask) {
mm/page-writeback.c +16 -8
@@ -270,7 +270,7 @@ static void wb_min_max_ratio(struct bdi_writeback *wb,* node_dirtyable_memory - number of dirtyable pages in a node * @pgdat: the node * -* Returns the node's number of pages potentially available for dirty +* Return: the node's number of pages potentially available for dirty * page cache. This is the base value for the per-node dirty limits. */ static unsigned long node_dirtyable_memory (struct pglist_data *pgdat)
@@ -355,7 +355,7 @@ static unsigned long highmem_dirtyable_memory(unsigned long total)/** * global_dirtyable_memory - number of globally dirtyable pages * -* Returns the global number of pages potentially available for dirty +* Return: the global number of pages potentially available for dirty * page cache. This is the base value for the global dirty limits. */ static unsigned long global_dirtyable_memory (void )
@@ -470,7 +470,7 @@ void global_dirty_limits(unsigned long *pbackground, unsigned long *pdirty)* node_dirty_limit - maximum number of dirty pages allowed in a node * @pgdat: the node * -* Returns the maximum number of dirty pages allowed in a node, based +* Return: the maximum number of dirty pages allowed in a node, based * on the node's dirtyable memory. */ static unsigned long node_dirty_limit (struct pglist_data *pgdat)
@@ -495,7 +495,7 @@ static unsigned long node_dirty_limit(struct pglist_data *pgdat)* node_dirty_ok - tells whether a node is within its dirty limits * @pgdat: the node to check * -* Returns %true when the dirty pages in @pgdat are within the node's +* Return: %true when the dirty pages in @pgdat are within the node's * dirty limit, %false if the limit is exceeded. */ bool node_dirty_ok (struct pglist_data *pgdat)
@@ -743,9 +743,6 @@ static void mdtc_calc_avail(struct dirty_throttle_control *mdtc,* __wb_calc_thresh - @wb's share of dirty throttling threshold * @dtc: dirty_throttle_context of interest * -* Returns @wb's dirty limit in pages. The term "dirty" in the context of -* dirty balancing includes all PG_dirty, PG_writeback and NFS unstable pages. -* * Note that balance_dirty_pages() will only seriously take it as a hard limit * when sleeping max_pause per page is not enough to keep the dirty pages under * control. For example, when the device is completely stalled due to some error
@@ -759,6 +756,9 @@ static void mdtc_calc_avail(struct dirty_throttle_control *mdtc,* * The wb's share of dirty limit will be adapting to its throughput and * bounded by the bdi->min_ratio and/or bdi->max_ratio parameters, if set. +* +* Return: @wb's dirty limit in pages. The term "dirty" in the context of +* dirty balancing includes all PG_dirty, PG_writeback and NFS unstable pages. */ static unsigned long __wb_calc_thresh (struct dirty_throttle_control *dtc) {
@@ -1918,7 +1918,9 @@ EXPORT_SYMBOL(balance_dirty_pages_ratelimited);* @wb: bdi_writeback of interest * * Determines whether background writeback should keep writing @wb or it's -* clean enough. Returns %true if writeback should continue. +* clean enough. +* +* Return: %true if writeback should continue. */ bool wb_over_bg_thresh (struct bdi_writeback *wb) {
@@ -2147,6 +2149,8 @@ EXPORT_SYMBOL(tag_pages_for_writeback);* lock/page writeback access order inversion - we should only ever lock * multiple pages in ascending page->index order, and looping back to the start * of the file violates that rule and causes deadlocks. +* +* Return: %0 on success, negative error code otherwise */ int write_cache_pages(struct address_space *mapping, struct writeback_control *wbc, writepage_t writepage,
@@ -2305,6 +2309,8 @@ static int __writepage(struct page *page, struct writeback_control *wbc,* * This is a library function, which implements the writepages() * address_space_operation. +* +* Return: %0 on success, negative error code otherwise */ int generic_writepages (struct address_space *mapping,struct writeback_control *wbc)
@@ -2351,6 +2357,8 @@ int do_writepages(struct address_space *mapping, struct writeback_control *wbc)* * Note that the mapping's AS_EIO/AS_ENOSPC flags will be cleared when this * function returns. +* +* Return: %0 on success, negative error code otherwise */ int write_one_page (struct page *page) {
mm/page_alloc.c +18 -6
@@ -4743,6 +4743,8 @@ static void *make_alloc_exact(unsigned long addr, unsigned int order,* This function is also limited by MAX_ORDER. * * Memory allocated by this function must be released by free_pages_exact(). +* +* Return: pointer to the allocated area or %NULL in case of error. */ void *alloc_pages_exact (size_t size,gfp_t gfp_mask) {
@@ -4763,6 +4765,8 @@ EXPORT_SYMBOL(alloc_pages_exact);* * Like alloc_pages_exact(), but try to allocate on node nid first before falling * back. +* +* Return: pointer to the allocated area or %NULL in case of error. */ void *__meminit alloc_pages_exact_nid (int nid,size_t size,gfp_t gfp_mask) {
@@ -4796,11 +4800,13 @@ EXPORT_SYMBOL(free_pages_exact);* nr_free_zone_pages - count number of pages beyond high watermark * @offset: The zone index of the highest zone * -* nr_free_zone_pages() counts the number of counts pages which are beyond the +* nr_free_zone_pages() counts the number of pages which are beyond the * high watermark within all zones at or below a given zone index. For each * zone, the number of pages is calculated as: * * nr_free_zone_pages = managed_pages - high_pages +* +* Return: number of pages beyond high watermark. */ static unsigned long nr_free_zone_pages (int offset) {
@@ -4827,6 +4833,9 @@ static unsigned long nr_free_zone_pages(int offset)* * nr_free_buffer_pages() counts the number of pages which are beyond the high * watermark within ZONE_DMA and ZONE_NORMAL. +* +* Return: number of pages beyond high watermark within ZONE_DMA and +* ZONE_NORMAL. */ unsigned long nr_free_buffer_pages (void ) {
@@ -4839,6 +4848,8 @@ EXPORT_SYMBOL_GPL(nr_free_buffer_pages);* * nr_free_pagecache_pages() counts the number of pages which are beyond the * high watermark within all zones. +* +* Return: number of pages beyond high watermark within all zones. */ unsigned long nr_free_pagecache_pages (void ) {
@@ -5285,7 +5296,8 @@ static int node_load[MAX_NUMNODES];* from each node to each node in the system), and should also prefer nodes * with no CPUs, since presumably they'll have very little allocation pressure * on them otherwise. -* It returns -1 if no node is found. +* +* Return: node id of the found node or %NUMA_NO_NODE if no node is found. */ static int find_next_best_node (int node,nodemask_t *used_node_mask) {
@@ -6208,7 +6220,7 @@ unsigned long __init __absent_pages_in_range(int nid,* @start_pfn: The start PFN to start searching for holes * @end_pfn: The end PFN to stop searching for holes * -* It returns the number of pages frames in memory holes within a range. +* Return: the number of pages frames in memory holes within a range. */ unsigned long __init absent_pages_in_range (unsigned long start_pfn,unsigned long end_pfn)
@@ -6758,7 +6770,7 @@ void __init setup_nr_node_ids(void)* model has fine enough granularity to avoid incorrect mapping for the * populated node map. * -* Returns the determined alignment in pfn's. 0 if there is no alignment +* Return: the determined alignment in pfn's. 0 if there is no alignment * requirement (single node). */ unsigned long __init node_map_pfn_alignment (void )
@@ -6813,7 +6825,7 @@ static unsigned long __init find_min_pfn_for_node(int nid)/** * find_min_pfn_with_active_regions - Find the minimum PFN registered * -* It returns the minimum PFN based on information provided via +* Return: the minimum PFN based on information provided via * memblock_set_node(). */ unsigned long __init find_min_pfn_with_active_regions (void )
@@ -8106,7 +8118,7 @@ static int __alloc_contig_migrate_range(struct compact_control *cc,* pageblocks in the range. Once isolated, the pageblocks should not * be modified by others. * -* Returns zero on success or negative error code. On success all +* Return: zero on success or negative error code. On success all * pages which PFN is in [start, end) are allocated for the caller and * need to be freed with free_contig_range(). */
mm/readahead.c +2 -0
@@ -81,6 +81,8 @@ static void read_cache_pages_invalidate_pages(struct address_space *mapping,* @data: private data for the callback routine. * * Hides the details of the LRU cache etc from the filesystems. +* +* Returns: %0 on success, error return by @filler otherwise */ int read_cache_pages (struct address_space *mapping,struct list_head *pages,int (*filler)(void *,struct page *),void *data)
mm/slab.c +14 -0
@@ -1725,6 +1725,8 @@ static void slabs_destroy(struct kmem_cache *cachep, struct list_head *list)* This could be made much more intelligent. For now, try to avoid using * high order pages for slabs. When the gfp() functions are more friendly * towards high-order requests, this should be changed. +* +* Return: number of left-over bytes in a slab */ static size_t calculate_slab_order (struct kmem_cache *cachep,size_t size,slab_flags_t flags)
@@ -1973,6 +1975,8 @@ static bool set_on_slab_cache(struct kmem_cache *cachep,* %SLAB_HWCACHE_ALIGN - Align the objects in this cache to a hardware * cacheline. This can be beneficial if you're counting cycles as closely * as davem. +* +* Return: a pointer to the created cache or %NULL in case of error */ int __kmem_cache_create (struct kmem_cache *cachep,slab_flags_t flags) {
@@ -3533,6 +3537,8 @@ void ___cache_free(struct kmem_cache *cachep, void *objp,* * Allocate an object from this cache. The flags are only relevant * if the cache has no available objects. +* +* Return: pointer to the new object or %NULL in case of error */ void *kmem_cache_alloc (struct kmem_cache *cachep,gfp_t flags) {
@@ -3623,6 +3629,8 @@ EXPORT_SYMBOL(kmem_cache_alloc_trace);* node, which can improve the performance for cpu bound structures. * * Fallback to other node is possible if __GFP_THISNODE is not set. +* +* Return: pointer to the new object or %NULL in case of error */ void *kmem_cache_alloc_node (struct kmem_cache *cachep,gfp_t flags,int nodeid) {
@@ -3692,6 +3700,8 @@ EXPORT_SYMBOL(__kmalloc_node_track_caller);* @size: how many bytes of memory are required. * @flags: the type of memory to allocate (see kmalloc). * @caller: function caller for debug tracking of the caller +* +* Return: pointer to the allocated memory or %NULL in case of error */ static __always_inline void *__do_kmalloc(size_t size, gfp_t flags,unsigned long caller)
@@ -4157,6 +4167,8 @@ void slabinfo_show_stats(struct seq_file *m, struct kmem_cache *cachep)* @buffer: user buffer * @count: data length * @ppos: unused +* +* Return: %0 on success, negative error code otherwise. */ ssize_t slabinfo_write (struct file *file,const char __user *buffer,size_t count,loff_t *ppos)
@@ -4448,6 +4460,8 @@ void __check_heap_object(const void *ptr, unsigned long n, struct page *page,* The caller must guarantee that objp points to a valid object previously * allocated with either kmalloc() or kmem_cache_alloc(). The object * must not be freed during the duration of the call. +* +* Return: size of the actual memory used by @objp in bytes */ size_t ksize (const void *objp) {
mm/slab_common.c +6 -0
@@ -939,6 +939,8 @@ EXPORT_SYMBOL(kmem_cache_destroy);* * Releases as many slabs as possible for a cache. * To help debugging, a zero exit status indicates all slabs were released. +* +* Return: %0 if all slabs were released, non-zero otherwise */ int kmem_cache_shrink (struct kmem_cache *cachep) {
@@ -1527,6 +1529,8 @@ static __always_inline void *__do_krealloc(const void *p, size_t new_size,* This function is like krealloc() except it never frees the originally * allocated buffer. Use this if you don't want to free the buffer immediately * like, for example, with RCU. +* +* Return: pointer to the allocated memory or %NULL in case of error */ void *__krealloc (const void *p,size_t new_size,gfp_t flags) {
@@ -1548,6 +1552,8 @@ EXPORT_SYMBOL(__krealloc);* lesser of the new and old sizes. If @p is %NULL, krealloc() * behaves exactly like kmalloc(). If @new_size is 0 and @p is not a * %NULL pointer, the object pointed to is freed. +* +* Return: pointer to the allocated memory or %NULL in case of error */ void *krealloc (const void *p,size_t new_size,gfp_t flags) {
mm/truncate.c +4 -2
@@ -539,6 +539,8 @@ EXPORT_SYMBOL(truncate_inode_pages_final);* invalidate_mapping_pages() will not block on IO activity. It will not * invalidate pages which are dirty, locked, under writeback or mapped into * pagetables. +* +* Return: the number of the pages that were invalidated */ unsigned long invalidate_mapping_pages (struct address_space *mapping,pgoff_t start,pgoff_t end)
@@ -664,7 +666,7 @@ static int do_launder_page(struct address_space *mapping, struct page *page)* Any pages which are found to be mapped into pagetables are unmapped prior to * invalidation. * -* Returns -EBUSY if any pages could not be invalidated. +* Return: -EBUSY if any pages could not be invalidated. */ int invalidate_inode_pages2_range (struct address_space *mapping,pgoff_t start,pgoff_t end)
@@ -761,7 +763,7 @@ EXPORT_SYMBOL_GPL(invalidate_inode_pages2_range);* Any pages which are found to be mapped into pagetables are unmapped prior to * invalidation. * -* Returns -EBUSY if any pages could not be invalidated. +* Return: -EBUSY if any pages could not be invalidated. */ int invalidate_inode_pages2 (struct address_space *mapping) {
mm/util.c +26 -11
@@ -36,6 +36,8 @@ EXPORT_SYMBOL(kfree_const);* kstrdup - allocate space for and copy an existing string * @s: the string to duplicate * @gfp: the GFP mask used in the kmalloc() call when allocating memory +* +* Return: newly allocated copy of @s or %NULL in case of error */ char *kstrdup (const char *s,gfp_t gfp) {
@@ -58,9 +60,10 @@ EXPORT_SYMBOL(kstrdup);* @s: the string to duplicate * @gfp: the GFP mask used in the kmalloc() call when allocating memory * -* Function returns source string if it is in .rodata section otherwise it -* fallbacks to kstrdup. -* Strings allocated by kstrdup_const should be freed by kfree_const. +* Note: Strings allocated by kstrdup_const should be freed by kfree_const. +* +* Return: source string if it is in .rodata section otherwise +* fallback to kstrdup. */ const char *kstrdup_const (const char *s,gfp_t gfp) {
@@ -78,6 +81,8 @@ EXPORT_SYMBOL(kstrdup_const);* @gfp: the GFP mask used in the kmalloc() call when allocating memory * * Note: Use kmemdup_nul() instead if the size is known exactly. +* +* Return: newly allocated copy of @s or %NULL in case of error */ char *kstrndup (const char *s,size_t max,gfp_t gfp) {
@@ -103,6 +108,8 @@ EXPORT_SYMBOL(kstrndup);* @src: memory region to duplicate * @len: memory region length * @gfp: GFP mask to use +* +* Return: newly allocated copy of @src or %NULL in case of error */ void *kmemdup (const void *src,size_t len,gfp_t gfp) {
@@ -120,6 +127,9 @@ EXPORT_SYMBOL(kmemdup);* @s: The data to stringify * @len: The size of the data * @gfp: the GFP mask used in the kmalloc() call when allocating memory +* +* Return: newly allocated copy of @s with NUL-termination or %NULL in +* case of error */ char *kmemdup_nul (const char *s,size_t len,gfp_t gfp) {
@@ -143,7 +153,7 @@ EXPORT_SYMBOL(kmemdup_nul);* @src: source address in user space * @len: number of bytes to copy * -* Returns an ERR_PTR() on failure. Result is physically +* Return: an ERR_PTR() on failure. Result is physically * contiguous, to be freed by kfree(). */ void *memdup_user (const void __user *src,size_t len)
@@ -169,7 +179,7 @@ EXPORT_SYMBOL(memdup_user);* @src: source address in user space * @len: number of bytes to copy * -* Returns an ERR_PTR() on failure. Result may be not +* Return: an ERR_PTR() on failure. Result may be not * physically contiguous. Use kvfree() to free. */ void *vmemdup_user (const void __user *src,size_t len)
@@ -193,6 +203,8 @@ EXPORT_SYMBOL(vmemdup_user);* strndup_user - duplicate an existing string from user space * @s: The string to duplicate * @n: Maximum number of bytes to copy, including the trailing NUL. +* +* Return: newly allocated copy of @s or %NULL in case of error */ char *strndup_user (const char __user *s,long n) {
@@ -224,7 +236,7 @@ EXPORT_SYMBOL(strndup_user);* @src: source address in user space * @len: number of bytes to copy * -* Returns an ERR_PTR() on failure. +* Return: an ERR_PTR() on failure. */ void *memdup_user_nul (const void __user *src,size_t len) {
@@ -310,10 +322,6 @@ EXPORT_SYMBOL_GPL(__get_user_pages_fast);* @pages: array that receives pointers to the pages pinned. * Should be at least nr_pages long. * -* Returns number of pages pinned. This may be fewer than the number -* requested. If nr_pages is 0 or negative, returns 0. If no pages -* were pinned, returns -errno. -* * get_user_pages_fast provides equivalent functionality to get_user_pages, * operating on current and current->mm, with force=0 and vma=NULL. However * unlike get_user_pages, it must be called without mmap_sem held.
@@ -325,6 +333,10 @@ EXPORT_SYMBOL_GPL(__get_user_pages_fast);* pages have to be faulted in, it may turn out to be slightly slower so * callers need to carefully consider what to use. On many architectures, * get_user_pages_fast simply falls back to get_user_pages. +* +* Return: number of pages pinned. This may be fewer than the number +* requested. If nr_pages is 0 or negative, returns 0. If no pages +* were pinned, returns -errno. */ int __weak get_user_pages_fast (unsigned long start,int nr_pages,int write,struct page **pages)
@@ -386,6 +398,8 @@ EXPORT_SYMBOL(vm_mmap);* * Please note that any use of gfp flags outside of GFP_KERNEL is careful to not * fall back to vmalloc. +* +* Return: pointer to the allocated memory of %NULL in case of failure */ void *kvmalloc_node (size_t size,gfp_t flags,int node) {
@@ -729,7 +743,8 @@ int __vm_enough_memory(struct mm_struct *mm, long pages, int cap_sys_admin)* @buffer: the buffer to copy to. * @buflen: the length of the buffer. Larger cmdline values are truncated * to this length. -* Returns the size of the cmdline field copied. Note that the copy does +* +* Return: the size of the cmdline field copied. Note that the copy does * not guarantee an ending NULL byte. */ int get_cmdline (struct task_struct *task,char *buffer,int buflen)
mm/vmalloc.c +37 -10
161 lines not on this page · raw message
Signature · 1 line
2.7.4