Merge branch 'idr-2018-02-06' of git://git.infradead.org/users/willy/linux-dax (9d21874d) · Commits · 戴 / test

Documentation/core-api/idr.rst

0 → 100644

+79 −0

Original line number	Diff line number	Diff line
		.. 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

Documentation/core-api/index.rst

+1 −0

Original line number	Diff line number	Diff line
		@@ -16,6 +16,7 @@ Core utilities
		atomic_ops
		refcount-vs-atomic
		cpu_hotplug
		idr
		local_ops
		workqueue
		genericirq

Documentation/core-api/kernel-api.rst

+0 −12

Original line number	Diff line number	Diff line
		@@ -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
		=======================

include/linux/idr.h

+75 −99

Original line number	Diff line number	Diff line
		@@ -15,10 +15,10 @@
		#include <linux/radix-tree.h>
		#include <linux/gfp.h>
		#include <linux/percpu.h>
		#include <linux/bug.h>

		struct idr {
		struct radix_tree_root idr_rt;
		unsigned int idr_base;
		unsigned int idr_next;
		};

		@@ -31,10 +31,26 @@ struct idr {
		/* Set the IDR flag and the IDR_FREE tag */
		#define IDR_RT_MARKER ((__force gfp_t)(3 << __GFP_BITS_SHIFT))

		#define IDR_INIT \
		{ \
		.idr_rt = RADIX_TREE_INIT(IDR_RT_MARKER) \
		#define IDR_INIT_BASE(base) { \
		.idr_rt = RADIX_TREE_INIT(IDR_RT_MARKER), \
		.idr_base = (base), \
		.idr_next = 0, \
		}

		/**
		* IDR_INIT() - Initialise an IDR.
		*
		* A freshly-initialised IDR contains no IDs.
		*/
		#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

		/**
		@@ -82,80 +98,52 @@ static inline void idr_set_cursor(struct idr *idr, unsigned int val)

		void idr_preload(gfp_t gfp_mask);

		int idr_alloc_cmn(struct idr idr, void ptr, unsigned long *index,
		unsigned long start, unsigned long end, gfp_t gfp,
		bool ext);

		/**
		* idr_alloc - allocate an id
		* @idr: idr handle
		* @ptr: pointer to be associated with the new id
		* @start: the minimum id (inclusive)
		* @end: the maximum id (exclusive)
		* @gfp: memory allocation flags
		*
		* Allocates an unused ID in the range [start, end). Returns -ENOSPC
		* if there are no unused IDs in that range.
		*
		* Note that @end is treated as max when <= 0. This is to always allow
		* using @start + N as @end as long as N is inside integer range.
		*
		* Simultaneous modifications to the @idr are not allowed and should be
		* prevented by the user, usually with a lock. idr_alloc() may be called
		* concurrently with read-only accesses to the @idr, such as idr_find() and
		* idr_for_each_entry().
		*/
		static inline int idr_alloc(struct idr idr, void ptr,
		int start, int end, gfp_t gfp)
		{
		unsigned long id;
		int ret;

		if (WARN_ON_ONCE(start < 0))
		return -EINVAL;

		ret = idr_alloc_cmn(idr, ptr, &id, start, end, gfp, false);

		if (ret)
		return ret;

		return id;
		}

		static inline int idr_alloc_ext(struct idr idr, void ptr,
		unsigned long *index,
		unsigned long start,
		unsigned long end,
		gfp_t gfp)
		{
		return idr_alloc_cmn(idr, ptr, index, start, end, gfp, true);
		}

		int idr_alloc_cyclic(struct idr , void entry, int start, int end, gfp_t);
		int idr_alloc(struct idr , void ptr, int start, int end, gfp_t);
		int __must_check idr_alloc_u32(struct idr , void ptr, u32 *id,
		unsigned long max, gfp_t);
		int idr_alloc_cyclic(struct idr , void ptr, int start, int end, gfp_t);
		void idr_remove(struct idr , unsigned long id);
		void idr_find(const struct idr , unsigned long id);
		int idr_for_each(const struct idr *,
		int (fn)(int id, void p, void data), void data);
		void idr_get_next(struct idr , int *nextid);
		void idr_get_next_ext(struct idr idr, unsigned long *nextid);
		void idr_replace(struct idr , void *, int id);
		void idr_replace_ext(struct idr idr, void *ptr, unsigned long id);
		void idr_get_next_ul(struct idr , unsigned long *nextid);
		void idr_replace(struct idr , void *, unsigned long id);
		void idr_destroy(struct idr *);

		static inline void idr_remove_ext(struct idr idr, unsigned long id)
		{
		return radix_tree_delete_item(&idr->idr_rt, id, NULL);
		}

		static inline void idr_remove(struct idr idr, int id)
		/**
		* idr_init_base() - Initialise an IDR.
		* @idr: IDR handle.
		* @base: The base value for the IDR.
		*
		* This variation of idr_init() creates an IDR which will allocate IDs
		* starting at %base.
		*/
		static inline void idr_init_base(struct idr *idr, int base)
		{
		return idr_remove_ext(idr, id);
		INIT_RADIX_TREE(&idr->idr_rt, IDR_RT_MARKER);
		idr->idr_base = base;
		idr->idr_next = 0;
		}

		/**
		* idr_init() - Initialise an IDR.
		* @idr: IDR handle.
		*
		* Initialise a dynamically allocated IDR. To initialise a
		* statically allocated IDR, use DEFINE_IDR().
		*/
		static inline void idr_init(struct idr *idr)
		{
		INIT_RADIX_TREE(&idr->idr_rt, IDR_RT_MARKER);
		idr->idr_next = 0;
		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) &&
		@@ -174,50 +162,38 @@ static inline void idr_preload_end(void)
		}

		/**
		* idr_find - return pointer for given id
		* @idr: idr handle
		* @id: lookup key
		* idr_for_each_entry() - Iterate over an IDR's elements of a given type.
		* @idr: IDR handle.
		* @entry: The type * to use as cursor
		* @id: Entry ID.
		*
		* 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().
		*
		* This function can be called under rcu_read_lock(), given that the leaf
		* pointers lifetimes are correctly managed.
		* @entry and @id do not need to be initialized before the loop, and
		* after normal termination @entry is left with the value NULL. This
		* is convenient for a "not found" value.
		*/
		static inline void idr_find_ext(const struct idr idr, unsigned long id)
		{
		return radix_tree_lookup(&idr->idr_rt, id);
		}

		static inline void idr_find(const struct idr idr, int id)
		{
		return idr_find_ext(idr, id);
		}
		#define idr_for_each_entry(idr, entry, id) \
		for (id = 0; ((entry) = idr_get_next(idr, &(id))) != NULL; ++id)

		/**
		* idr_for_each_entry - iterate over an idr's elements of a given type
		* @idr: idr handle
		* @entry: the type * to use as cursor
		* @id: id entry's key
		* idr_for_each_entry_ul() - Iterate over an IDR's elements of a given type.
		* @idr: IDR handle.
		* @entry: The type * to use as cursor.
		* @id: Entry ID.
		*
		* @entry and @id do not need to be initialized before the loop, and
		* after normal terminatinon @entry is left with the value NULL. This
		* after normal termination @entry is left with the value NULL. This
		* is convenient for a "not found" value.
		*/
		#define idr_for_each_entry(idr, entry, id) \
		for (id = 0; ((entry) = idr_get_next(idr, &(id))) != NULL; ++id)
		#define idr_for_each_entry_ext(idr, entry, id) \
		for (id = 0; ((entry) = idr_get_next_ext(idr, &(id))) != NULL; ++id)
		#define idr_for_each_entry_ul(idr, entry, id) \
		for (id = 0; ((entry) = idr_get_next_ul(idr, &(id))) != NULL; ++id)

		/**
		* idr_for_each_entry_continue - continue iteration over an idr's elements of a given type
		* @idr: idr handle
		* @entry: the type * to use as cursor
		* @id: id entry's key
		* idr_for_each_entry_continue() - Continue iteration over an IDR's elements of a given type
		* @idr: IDR handle.
		* @entry: The type * to use as a cursor.
		* @id: Entry ID.
		*
		* Continue to iterate over list of given type, continuing after
		* the current position.
		* Continue to iterate over entries, continuing after the current position.
		*/
		#define idr_for_each_entry_continue(idr, entry, id) \
		for ((entry) = idr_get_next((idr), &(id)); \

include/linux/radix-tree.h

+1 −16

Original line number	Diff line number	Diff line
		@@ -356,24 +356,9 @@ int radix_tree_split(struct radix_tree_root *, unsigned long index,
		int radix_tree_join(struct radix_tree_root *, unsigned long index,
		unsigned new_order, void *);

		void __rcu *idr_get_free_cmn(struct radix_tree_root root,
		void __rcu *idr_get_free(struct radix_tree_root root,
		struct radix_tree_iter *iter, gfp_t gfp,
		unsigned long max);
		static inline void __rcu *idr_get_free(struct radix_tree_root root,
		struct radix_tree_iter *iter,
		gfp_t gfp,
		int end)
		{
		return idr_get_free_cmn(root, iter, gfp, end > 0 ? end - 1 : INT_MAX);
		}

		static inline void __rcu *idr_get_free_ext(struct radix_tree_root root,
		struct radix_tree_iter *iter,
		gfp_t gfp,
		unsigned long end)
		{
		return idr_get_free_cmn(root, iter, gfp, end - 1);
		}

		enum {
		RADIX_TREE_ITER_TAG_MASK = 0x0f, /* tag index in lower nybble */

Admin message