From: Christoph Hellwig <hch@lst.de>
Update idr.c comments, now uses doc-book style API documentation.
Signed-off-by: Andrew Morton <akpm@osdl.org>
---
25-akpm/lib/idr.c | 136 +++++++++++++++++++++++++++---------------------------
1 files changed, 70 insertions(+), 66 deletions(-)
diff -puN lib/idr.c~idr-comments-updates lib/idr.c
--- 25/lib/idr.c~idr-comments-updates Wed Jul 7 14:09:47 2004
+++ 25-akpm/lib/idr.c Wed Jul 7 14:09:47 2004
@@ -1,21 +1,17 @@
/*
- * linux/kernel/id.c
- *
* 2002-10-18 written by Jim Houston jim.houston@ccur.com
* Copyright (C) 2002 by Concurrent Computer Corporation
* Distributed under the GNU GPL license version 2.
*
+ * Modified by George Anzinger to reuse immediately and to use
+ * find bit instructions. Also removed _irq on spinlocks.
+ *
* Small id to pointer translation service.
*
* It uses a radix tree like structure as a sparse array indexed
* by the id to obtain the pointer. The bitmap makes allocating
* a new id quick.
-
- * Modified by George Anzinger to reuse immediately and to use
- * find bit instructions. Also removed _irq on spinlocks.
-
- * So here is what this bit of code does:
-
+ *
* You call it to allocate an id (an int) an associate with that id a
* pointer or what ever, we treat it as a (void *). You can pass this
* id to a user for him to pass back at a later time. You then pass
@@ -26,62 +22,8 @@
* don't need to go to the memory "store" during an id allocate, just
* so you don't need to be too concerned about locking and conflicts
* with the slab allocator.
-
- * So here are the complete details:
-
- * include <linux/idr.h>
-
- * void idr_init(struct idr *idp)
-
- * This function is use to set up the handle (idp) that you will pass
- * to the rest of the functions. The structure is defined in the
- * header.
-
- * int idr_pre_get(struct idr *idp, unsigned gfp_mask)
-
- * This function should be called prior to locking and calling the
- * following function. It pre allocates enough memory to satisfy the
- * worst possible allocation. Unless gfp_mask is GFP_ATOMIC, it can
- * sleep, so must not be called with any spinlocks held. If the system is
- * REALLY out of memory this function returns 0, other wise 1.
-
- * int idr_get_new(struct idr *idp, void *ptr, int *id);
-
- * This is the allocate id function. It should be called with any
- * required locks. In fact, in the SMP case, you MUST lock prior to
- * calling this function to avoid possible out of memory problems.
- * 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 return a -ENOSPC. ptr is the pointer you want associated
- * with the id. The value is returned in the "id" field. idr_get_new()
- * returns a value in the range 0 ... 0x7fffffff
-
- * int idr_get_new_above(struct idr *idp, void *ptr, int start_id, int *id);
-
- * Like idr_get_new(), but the returned id is guaranteed to be at or
- * above start_id.
-
- * void *idr_find(struct idr *idp, int id);
-
- * returns the "ptr", given the id. A NULL return indicates that the
- * id is not valid (or you passed NULL in the idr_get_new(), shame on
- * you). This function must be called with a spinlock that prevents
- * calling either idr_get_new() or idr_remove() or idr_find() while it
- * is working.
-
- * void idr_remove(struct idr *idp, int id);
-
- * removes the given id, freeing that slot and any memory that may
- * now be unused. See idr_find() for locking restrictions.
-
- * int idr_full(struct idr *idp);
-
- * Returns true if the idr is full and false if not.
-
*/
-
-
#ifndef TEST // to test in user space...
#include <linux/slab.h>
#include <linux/init.h>
@@ -90,11 +32,8 @@
#include <linux/string.h>
#include <linux/idr.h>
-
static kmem_cache_t *idr_layer_cache;
-
-
static struct idr_layer *alloc_layer(struct idr *idp)
{
struct idr_layer *p;
@@ -121,6 +60,18 @@ static void free_layer(struct idr *idp,
spin_unlock(&idp->lock);
}
+/**
+ * idr_pre_get - reserver resources for idr allocation
+ * @idp: idr handle
+ * @gfp_mask: memory allocation flags
+ *
+ * This function should be called prior to locking and calling the
+ * following function. It preallocates enough memory to satisfy
+ * the worst possible allocation.
+ *
+ * If the system is REALLY out of memory this function returns 0,
+ * otherwise 1.
+ */
int idr_pre_get(struct idr *idp, unsigned gfp_mask)
{
while (idp->id_free_cnt < IDR_FREE_MAX) {
@@ -255,6 +206,22 @@ build_up:
return(v);
}
+/**
+ * idr_get_new_above - allocate new idr entry above a start id
+ * @idp: idr handle
+ * @ptr: pointer you want associated with the ide
+ * @start_id: id to start search at
+ * @id: pointer to the allocated handle
+ *
+ * This is the allocate id function. It should be called with any
+ * required locks.
+ *
+ * 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
+ * return -ENOSPC.
+ *
+ * @id returns a value in the range 0 ... 0x7fffffff
+ */
int idr_get_new_above(struct idr *idp, void *ptr, int starting_id, int *id)
{
int rv;
@@ -274,6 +241,21 @@ int idr_get_new_above(struct idr *idp, v
}
EXPORT_SYMBOL(idr_get_new_above);
+/**
+ * idr_get_new - allocate new idr entry
+ * @idp: idr handle
+ * @ptr: pointer you want associated with the ide
+ * @id: pointer to the allocated handle
+ *
+ * This is the allocate id function. It should be called with any
+ * required locks.
+ *
+ * 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
+ * return -ENOSPC.
+ *
+ * @id returns a value in the range 0 ... 0x7fffffff
+ */
int idr_get_new(struct idr *idp, void *ptr, int *id)
{
int rv;
@@ -322,6 +304,11 @@ static void sub_remove(struct idr *idp,
}
}
+/**
+ * idr_remove - remove the given id and free it's slot
+ * idp: idr handle
+ * id: uniqueue key
+ */
void idr_remove(struct idr *idp, int id)
{
struct idr_layer *p;
@@ -349,6 +336,17 @@ void idr_remove(struct idr *idp, int id)
}
EXPORT_SYMBOL(idr_remove);
+/**
+ * idr_find - return pointer for given id
+ * @idp: idr handle
+ * @id: lookup key
+ *
+ * Return the pointer given the id it has been registered with. A %NULL
+ * return indicates that @id is not valid or you passed %NULL in
+ * idr_get_new().
+ *
+ * The caller must serialize idr_find() vs idr_get_new() and idr_remove().
+ */
void *idr_find(struct idr *idp, int id)
{
int n;
@@ -385,6 +383,13 @@ static int init_id_cache(void)
return 0;
}
+/**
+ * idr_init - initialize idr handle
+ * @idp: idr handle
+ *
+ * This function is use to set up the handle (@idp) that you will pass
+ * to the rest of the functions.
+ */
void idr_init(struct idr *idp)
{
init_id_cache();
@@ -392,4 +397,3 @@ void idr_init(struct idr *idp)
spin_lock_init(&idp->lock);
}
EXPORT_SYMBOL(idr_init);
-
_