kmemleak: Add DocBook style comments to kmemleak.c

The description and parameters of the kmemleak API weren't obvious. This
patch adds comments clarifying the API usage.

Signed-off-by: Catalin Marinas <catalin.marinas@arm.com>
Acked-by: Pekka Enberg <penberg@cs.helsinki.fi>
This commit is contained in:
Catalin Marinas 2010-07-19 11:54:17 +01:00
parent ab0155a22a
commit a2b6bf63cb

View File

@ -843,10 +843,19 @@ static void early_alloc(struct early_log *log)
rcu_read_unlock();
}
/*
* Memory allocation function callback. This function is called from the
* kernel allocators when a new block is allocated (kmem_cache_alloc, kmalloc,
* vmalloc etc.).
/**
* kmemleak_alloc - register a newly allocated object
* @ptr: pointer to beginning of the object
* @size: size of the object
* @min_count: minimum number of references to this object. If during memory
* scanning a number of references less than @min_count is found,
* the object is reported as a memory leak. If @min_count is 0,
* the object is never reported as a leak. If @min_count is -1,
* the object is ignored (not scanned and not reported as a leak)
* @gfp: kmalloc() flags used for kmemleak internal memory allocations
*
* This function is called from the kernel allocators when a new object
* (memory block) is allocated (kmem_cache_alloc, kmalloc, vmalloc etc.).
*/
void __ref kmemleak_alloc(const void *ptr, size_t size, int min_count,
gfp_t gfp)
@ -860,9 +869,12 @@ void __ref kmemleak_alloc(const void *ptr, size_t size, int min_count,
}
EXPORT_SYMBOL_GPL(kmemleak_alloc);
/*
* Memory freeing function callback. This function is called from the kernel
* allocators when a block is freed (kmem_cache_free, kfree, vfree etc.).
/**
* kmemleak_free - unregister a previously registered object
* @ptr: pointer to beginning of the object
*
* This function is called from the kernel allocators when an object (memory
* block) is freed (kmem_cache_free, kfree, vfree etc.).
*/
void __ref kmemleak_free(const void *ptr)
{
@ -875,9 +887,14 @@ void __ref kmemleak_free(const void *ptr)
}
EXPORT_SYMBOL_GPL(kmemleak_free);
/*
* Partial memory freeing function callback. This function is usually called
* from bootmem allocator when (part of) a memory block is freed.
/**
* kmemleak_free_part - partially unregister a previously registered object
* @ptr: pointer to the beginning or inside the object. This also
* represents the start of the range to be freed
* @size: size to be unregistered
*
* This function is called when only a part of a memory block is freed
* (usually from the bootmem allocator).
*/
void __ref kmemleak_free_part(const void *ptr, size_t size)
{
@ -890,9 +907,12 @@ void __ref kmemleak_free_part(const void *ptr, size_t size)
}
EXPORT_SYMBOL_GPL(kmemleak_free_part);
/*
* Mark an already allocated memory block as a false positive. This will cause
* the block to no longer be reported as leak and always be scanned.
/**
* kmemleak_not_leak - mark an allocated object as false positive
* @ptr: pointer to beginning of the object
*
* Calling this function on an object will cause the memory block to no longer
* be reported as leak and always be scanned.
*/
void __ref kmemleak_not_leak(const void *ptr)
{
@ -905,10 +925,14 @@ void __ref kmemleak_not_leak(const void *ptr)
}
EXPORT_SYMBOL(kmemleak_not_leak);
/*
* Ignore a memory block. This is usually done when it is known that the
* corresponding block is not a leak and does not contain any references to
* other allocated memory blocks.
/**
* kmemleak_ignore - ignore an allocated object
* @ptr: pointer to beginning of the object
*
* Calling this function on an object will cause the memory block to be
* ignored (not scanned and not reported as a leak). This is usually done when
* it is known that the corresponding block is not a leak and does not contain
* any references to other allocated memory blocks.
*/
void __ref kmemleak_ignore(const void *ptr)
{
@ -921,8 +945,16 @@ void __ref kmemleak_ignore(const void *ptr)
}
EXPORT_SYMBOL(kmemleak_ignore);
/*
* Limit the range to be scanned in an allocated memory block.
/**
* kmemleak_scan_area - limit the range to be scanned in an allocated object
* @ptr: pointer to beginning or inside the object. This also
* represents the start of the scan area
* @size: size of the scan area
* @gfp: kmalloc() flags used for kmemleak internal memory allocations
*
* This function is used when it is known that only certain parts of an object
* contain references to other objects. Kmemleak will only scan these areas
* reducing the number false negatives.
*/
void __ref kmemleak_scan_area(const void *ptr, size_t size, gfp_t gfp)
{
@ -935,8 +967,14 @@ void __ref kmemleak_scan_area(const void *ptr, size_t size, gfp_t gfp)
}
EXPORT_SYMBOL(kmemleak_scan_area);
/*
* Inform kmemleak not to scan the given memory block.
/**
* kmemleak_no_scan - do not scan an allocated object
* @ptr: pointer to beginning of the object
*
* This function notifies kmemleak not to scan the given memory block. Useful
* in situations where it is known that the given object does not contain any
* references to other objects. Kmemleak will not scan such objects reducing
* the number of false negatives.
*/
void __ref kmemleak_no_scan(const void *ptr)
{