Commit 56083ab1 authored by Randy Dunlap's avatar Randy Dunlap Committed by Linus Torvalds

docbook: add idr/ida to kernel-api docbook

Add idr/ida to kernel-api docbook.
Fix typos and kernel-doc notation.
Signed-off-by: default avatarRandy Dunlap <randy.dunlap@oracle.com>
Acked-by: default avatarTejun Heo <tj@kernel.org>
Cc: Naohiro Aota <naota@elisp.net>
Cc: Jiri Kosina <jkosina@suse.cz>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent ee2f154a
...@@ -93,6 +93,12 @@ X!Ilib/string.c ...@@ -93,6 +93,12 @@ X!Ilib/string.c
!Elib/crc32.c !Elib/crc32.c
!Elib/crc-ccitt.c !Elib/crc-ccitt.c
</sect1> </sect1>
<sect1 id="idr"><title>idr/ida Functions</title>
!Pinclude/linux/idr.h idr sync
!Plib/idr.c IDA description
!Elib/idr.c
</sect1>
</chapter> </chapter>
<chapter id="mm"> <chapter id="mm">
......
...@@ -81,6 +81,7 @@ struct idr { ...@@ -81,6 +81,7 @@ struct idr {
#define _idr_rc_to_errno(rc) ((rc) == -1 ? -EAGAIN : -ENOSPC) #define _idr_rc_to_errno(rc) ((rc) == -1 ? -EAGAIN : -ENOSPC)
/** /**
* DOC: idr sync
* idr synchronization (stolen from radix-tree.h) * idr synchronization (stolen from radix-tree.h)
* *
* idr_find() is able to be called locklessly, using RCU. The caller must * idr_find() is able to be called locklessly, using RCU. The caller must
......
...@@ -106,7 +106,7 @@ static void idr_mark_full(struct idr_layer **pa, int id) ...@@ -106,7 +106,7 @@ static void idr_mark_full(struct idr_layer **pa, int id)
} }
/** /**
* idr_pre_get - reserver resources for idr allocation * idr_pre_get - reserve resources for idr allocation
* @idp: idr handle * @idp: idr handle
* @gfp_mask: memory allocation flags * @gfp_mask: memory allocation flags
* *
...@@ -115,8 +115,8 @@ static void idr_mark_full(struct idr_layer **pa, int id) ...@@ -115,8 +115,8 @@ static void idr_mark_full(struct idr_layer **pa, int id)
* caller should pass in GFP_KERNEL if possible. This of course requires that * caller should pass in GFP_KERNEL if possible. This of course requires that
* no spinning locks be held. * no spinning locks be held.
* *
* If the system is REALLY out of memory this function returns 0, * If the system is REALLY out of memory this function returns %0,
* otherwise 1. * otherwise %1.
*/ */
int idr_pre_get(struct idr *idp, gfp_t gfp_mask) int idr_pre_get(struct idr *idp, gfp_t gfp_mask)
{ {
...@@ -292,12 +292,12 @@ static int idr_get_new_above_int(struct idr *idp, void *ptr, int starting_id) ...@@ -292,12 +292,12 @@ static int idr_get_new_above_int(struct idr *idp, void *ptr, int starting_id)
* required locks. * required locks.
* *
* If allocation from IDR's private freelist fails, idr_get_new_above() will * If allocation from IDR's private freelist fails, idr_get_new_above() will
* return -EAGAIN. The caller should retry the idr_pre_get() call to refill * return %-EAGAIN. The caller should retry the idr_pre_get() call to refill
* IDR's preallocation and then retry the idr_get_new_above() call. * IDR's preallocation and then retry the idr_get_new_above() call.
* *
* If the idr is full idr_get_new_above() will return -ENOSPC. * If the idr is full idr_get_new_above() will return %-ENOSPC.
* *
* @id returns a value in the range @starting_id ... 0x7fffffff * @id returns a value in the range @starting_id ... %0x7fffffff
*/ */
int idr_get_new_above(struct idr *idp, void *ptr, int starting_id, int *id) int idr_get_new_above(struct idr *idp, void *ptr, int starting_id, int *id)
{ {
...@@ -322,12 +322,12 @@ EXPORT_SYMBOL(idr_get_new_above); ...@@ -322,12 +322,12 @@ EXPORT_SYMBOL(idr_get_new_above);
* @id: pointer to the allocated handle * @id: pointer to the allocated handle
* *
* If allocation from IDR's private freelist fails, idr_get_new_above() will * If allocation from IDR's private freelist fails, idr_get_new_above() will
* return -EAGAIN. The caller should retry the idr_pre_get() call to refill * return %-EAGAIN. The caller should retry the idr_pre_get() call to refill
* IDR's preallocation and then retry the idr_get_new_above() call. * IDR's preallocation and then retry the idr_get_new_above() call.
* *
* If the idr is full idr_get_new_above() will return -ENOSPC. * If the idr is full idr_get_new_above() will return %-ENOSPC.
* *
* @id returns a value in the range 0 ... 0x7fffffff * @id returns a value in the range %0 ... %0x7fffffff
*/ */
int idr_get_new(struct idr *idp, void *ptr, int *id) int idr_get_new(struct idr *idp, void *ptr, int *id)
{ {
...@@ -390,7 +390,7 @@ static void sub_remove(struct idr *idp, int shift, int id) ...@@ -390,7 +390,7 @@ static void sub_remove(struct idr *idp, int shift, int id)
} }
/** /**
* idr_remove - remove the given id and free it's slot * idr_remove - remove the given id and free its slot
* @idp: idr handle * @idp: idr handle
* @id: unique key * @id: unique key
*/ */
...@@ -439,7 +439,7 @@ EXPORT_SYMBOL(idr_remove); ...@@ -439,7 +439,7 @@ EXPORT_SYMBOL(idr_remove);
* function will remove all id mappings and leave all idp_layers * function will remove all id mappings and leave all idp_layers
* unused. * unused.
* *
* A typical clean-up sequence for objects stored in an idr tree, will * A typical clean-up sequence for objects stored in an idr tree will
* use idr_for_each() to free all objects, if necessay, then * use idr_for_each() to free all objects, if necessay, then
* idr_remove_all() to remove all ids, and idr_destroy() to free * idr_remove_all() to remove all ids, and idr_destroy() to free
* up the cached idr_layers. * up the cached idr_layers.
...@@ -544,7 +544,7 @@ EXPORT_SYMBOL(idr_find); ...@@ -544,7 +544,7 @@ EXPORT_SYMBOL(idr_find);
* not allowed. * not allowed.
* *
* We check the return of @fn each time. If it returns anything other * We check the return of @fn each time. If it returns anything other
* than 0, we break out and return that value. * than %0, we break out and return that value.
* *
* The caller must serialize idr_for_each() vs idr_get_new() and idr_remove(). * The caller must serialize idr_for_each() vs idr_get_new() and idr_remove().
*/ */
...@@ -639,8 +639,8 @@ EXPORT_SYMBOL(idr_get_next); ...@@ -639,8 +639,8 @@ EXPORT_SYMBOL(idr_get_next);
* @id: lookup key * @id: lookup key
* *
* Replace the pointer registered with an id and return the old value. * Replace the pointer registered with an id and return the old value.
* A -ENOENT return indicates that @id was not found. * A %-ENOENT return indicates that @id was not found.
* A -EINVAL return indicates that @id was not within valid constraints. * A %-EINVAL return indicates that @id was not within valid constraints.
* *
* The caller must serialize with writers. * The caller must serialize with writers.
*/ */
...@@ -698,10 +698,11 @@ void idr_init(struct idr *idp) ...@@ -698,10 +698,11 @@ void idr_init(struct idr *idp)
EXPORT_SYMBOL(idr_init); EXPORT_SYMBOL(idr_init);
/* /**
* DOC: IDA description
* IDA - IDR based ID allocator * IDA - IDR based ID allocator
* *
* this is id allocator without id -> pointer translation. Memory * This is id allocator without id -> pointer translation. Memory
* usage is much lower than full blown idr because each id only * usage is much lower than full blown idr because each id only
* occupies a bit. ida uses a custom leaf node which contains * occupies a bit. ida uses a custom leaf node which contains
* IDA_BITMAP_BITS slots. * IDA_BITMAP_BITS slots.
...@@ -734,8 +735,8 @@ static void free_bitmap(struct ida *ida, struct ida_bitmap *bitmap) ...@@ -734,8 +735,8 @@ static void free_bitmap(struct ida *ida, struct ida_bitmap *bitmap)
* following function. It preallocates enough memory to satisfy the * following function. It preallocates enough memory to satisfy the
* worst possible allocation. * worst possible allocation.
* *
* If the system is REALLY out of memory this function returns 0, * If the system is REALLY out of memory this function returns %0,
* otherwise 1. * otherwise %1.
*/ */
int ida_pre_get(struct ida *ida, gfp_t gfp_mask) int ida_pre_get(struct ida *ida, gfp_t gfp_mask)
{ {
...@@ -767,11 +768,11 @@ EXPORT_SYMBOL(ida_pre_get); ...@@ -767,11 +768,11 @@ EXPORT_SYMBOL(ida_pre_get);
* Allocate new ID above or equal to @ida. It should be called with * Allocate new ID above or equal to @ida. It should be called with
* any required locks. * any required locks.
* *
* If memory is required, it will return -EAGAIN, you should unlock * If memory is required, it will return %-EAGAIN, you should unlock
* and go back to the ida_pre_get() call. If the ida is full, it will * and go back to the ida_pre_get() call. If the ida is full, it will
* return -ENOSPC. * return %-ENOSPC.
* *
* @p_id returns a value in the range @starting_id ... 0x7fffffff. * @p_id returns a value in the range @starting_id ... %0x7fffffff.
*/ */
int ida_get_new_above(struct ida *ida, int starting_id, int *p_id) int ida_get_new_above(struct ida *ida, int starting_id, int *p_id)
{ {
...@@ -853,11 +854,11 @@ EXPORT_SYMBOL(ida_get_new_above); ...@@ -853,11 +854,11 @@ EXPORT_SYMBOL(ida_get_new_above);
* *
* Allocate new ID. It should be called with any required locks. * Allocate new ID. It should be called with any required locks.
* *
* If memory is required, it will return -EAGAIN, you should unlock * If memory is required, it will return %-EAGAIN, you should unlock
* and go back to the idr_pre_get() call. If the idr is full, it will * and go back to the idr_pre_get() call. If the idr is full, it will
* return -ENOSPC. * return %-ENOSPC.
* *
* @id returns a value in the range 0 ... 0x7fffffff. * @id returns a value in the range %0 ... %0x7fffffff.
*/ */
int ida_get_new(struct ida *ida, int *p_id) int ida_get_new(struct ida *ida, int *p_id)
{ {
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment