idr: Add documentation
Move the idr kernel-doc to its own idr.rst file and add a few paragraphs about how to use it. Also add some more kernel-doc. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
This commit is contained in:
parent
6ce711f275
commit
ac665d9423
79
Documentation/core-api/idr.rst
Normal file
79
Documentation/core-api/idr.rst
Normal file
|
@ -0,0 +1,79 @@
|
|||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
=============
|
||||
ID Allocation
|
||||
=============
|
||||
|
||||
:Author: Matthew Wilcox
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
A common problem to solve is allocating identifiers (IDs); generally
|
||||
small numbers which identify a thing. Examples include file descriptors,
|
||||
process IDs, packet identifiers in networking protocols, SCSI tags
|
||||
and device instance numbers. The IDR and the IDA provide a reasonable
|
||||
solution to the problem to avoid everybody inventing their own. The IDR
|
||||
provides the ability to map an ID to a pointer, while the IDA provides
|
||||
only ID allocation, and as a result is much more memory-efficient.
|
||||
|
||||
IDR usage
|
||||
=========
|
||||
|
||||
Start by initialising an IDR, either with :c:func:`DEFINE_IDR`
|
||||
for statically allocated IDRs or :c:func:`idr_init` for dynamically
|
||||
allocated IDRs.
|
||||
|
||||
You can call :c:func:`idr_alloc` to allocate an unused ID. Look up
|
||||
the pointer you associated with the ID by calling :c:func:`idr_find`
|
||||
and free the ID by calling :c:func:`idr_remove`.
|
||||
|
||||
If you need to change the pointer associated with an ID, you can call
|
||||
:c:func:`idr_replace`. One common reason to do this is to reserve an
|
||||
ID by passing a ``NULL`` pointer to the allocation function; initialise the
|
||||
object with the reserved ID and finally insert the initialised object
|
||||
into the IDR.
|
||||
|
||||
Some users need to allocate IDs larger than ``INT_MAX``. So far all of
|
||||
these users have been content with a ``UINT_MAX`` limit, and they use
|
||||
:c:func:`idr_alloc_u32`. If you need IDs that will not fit in a u32,
|
||||
we will work with you to address your needs.
|
||||
|
||||
If you need to allocate IDs sequentially, you can use
|
||||
:c:func:`idr_alloc_cyclic`. The IDR becomes less efficient when dealing
|
||||
with larger IDs, so using this function comes at a slight cost.
|
||||
|
||||
To perform an action on all pointers used by the IDR, you can
|
||||
either use the callback-based :c:func:`idr_for_each` or the
|
||||
iterator-style :c:func:`idr_for_each_entry`. You may need to use
|
||||
:c:func:`idr_for_each_entry_continue` to continue an iteration. You can
|
||||
also use :c:func:`idr_get_next` if the iterator doesn't fit your needs.
|
||||
|
||||
When you have finished using an IDR, you can call :c:func:`idr_destroy`
|
||||
to release the memory used by the IDR. This will not free the objects
|
||||
pointed to from the IDR; if you want to do that, use one of the iterators
|
||||
to do it.
|
||||
|
||||
You can use :c:func:`idr_is_empty` to find out whether there are any
|
||||
IDs currently allocated.
|
||||
|
||||
If you need to take a lock while allocating a new ID from the IDR,
|
||||
you may need to pass a restrictive set of GFP flags, which can lead
|
||||
to the IDR being unable to allocate memory. To work around this,
|
||||
you can call :c:func:`idr_preload` before taking the lock, and then
|
||||
:c:func:`idr_preload_end` after the allocation.
|
||||
|
||||
.. kernel-doc:: include/linux/idr.h
|
||||
:doc: idr sync
|
||||
|
||||
IDA usage
|
||||
=========
|
||||
|
||||
.. kernel-doc:: lib/idr.c
|
||||
:doc: IDA description
|
||||
|
||||
Functions and structures
|
||||
========================
|
||||
|
||||
.. kernel-doc:: include/linux/idr.h
|
||||
.. kernel-doc:: lib/idr.c
|
|
@ -16,6 +16,7 @@ Core utilities
|
|||
atomic_ops
|
||||
refcount-vs-atomic
|
||||
cpu_hotplug
|
||||
idr
|
||||
local_ops
|
||||
workqueue
|
||||
genericirq
|
||||
|
|
|
@ -103,18 +103,6 @@ CRC Functions
|
|||
.. kernel-doc:: lib/crc-itu-t.c
|
||||
:export:
|
||||
|
||||
idr/ida Functions
|
||||
-----------------
|
||||
|
||||
.. kernel-doc:: include/linux/idr.h
|
||||
:doc: idr sync
|
||||
|
||||
.. kernel-doc:: lib/idr.c
|
||||
:doc: IDA description
|
||||
|
||||
.. kernel-doc:: lib/idr.c
|
||||
:export:
|
||||
|
||||
Math Functions in Linux
|
||||
=======================
|
||||
|
||||
|
|
|
@ -36,7 +36,6 @@ struct idr {
|
|||
.idr_base = (base), \
|
||||
.idr_next = 0, \
|
||||
}
|
||||
#define DEFINE_IDR(name) struct idr name = IDR_INIT
|
||||
|
||||
/**
|
||||
* IDR_INIT() - Initialise an IDR.
|
||||
|
@ -45,6 +44,15 @@ struct idr {
|
|||
*/
|
||||
#define IDR_INIT IDR_INIT_BASE(0)
|
||||
|
||||
/**
|
||||
* DEFINE_IDR() - Define a statically-allocated IDR
|
||||
* @name: Name of IDR
|
||||
*
|
||||
* An IDR defined using this macro is ready for use with no additional
|
||||
* initialisation required. It contains no IDs.
|
||||
*/
|
||||
#define DEFINE_IDR(name) struct idr name = IDR_INIT
|
||||
|
||||
/**
|
||||
* idr_get_cursor - Return the current position of the cyclic allocator
|
||||
* @idr: idr handle
|
||||
|
@ -130,6 +138,12 @@ static inline void idr_init(struct idr *idr)
|
|||
idr_init_base(idr, 0);
|
||||
}
|
||||
|
||||
/**
|
||||
* idr_is_empty() - Are there any IDs allocated?
|
||||
* @idr: IDR handle.
|
||||
*
|
||||
* Return: %true if any IDs have been allocated from this IDR.
|
||||
*/
|
||||
static inline bool idr_is_empty(const struct idr *idr)
|
||||
{
|
||||
return radix_tree_empty(&idr->idr_rt) &&
|
||||
|
|
Loading…
Reference in a new issue