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

Documentation/core-api/idr.rst

0 → 100644

+79 −0

Original line number	Original line	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	Original line	Diff line number	Diff line
	@@ -16,6 +16,7 @@ Core utilities
	atomic_ops		atomic_ops
	refcount-vs-atomic		refcount-vs-atomic
	cpu_hotplug		cpu_hotplug
			idr
	local_ops		local_ops
	workqueue		workqueue
	genericirq		genericirq

Documentation/core-api/kernel-api.rst

+0 −12

Original line number	Original line	Diff line number	Diff line
	@@ -103,18 +103,6 @@ CRC Functions
	.. kernel-doc:: lib/crc-itu-t.c		.. kernel-doc:: lib/crc-itu-t.c
	:export:		: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		Math Functions in Linux
	=======================		=======================

include/linux/idr.h

+75 −99

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

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

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

	#define IDR_INIT \		#define IDR_INIT_BASE(base) { \
	{ \		.idr_rt = RADIX_TREE_INIT(IDR_RT_MARKER), \
	.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		#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);		void idr_preload(gfp_t gfp_mask);

	int idr_alloc_cmn(struct idr idr, void ptr, unsigned long *index,		int idr_alloc(struct idr , void ptr, int start, int end, gfp_t);
	unsigned long start, unsigned long end, gfp_t gfp,		int __must_check idr_alloc_u32(struct idr , void ptr, u32 *id,
	bool ext);		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);
	* idr_alloc - allocate an id		void idr_find(const struct idr , unsigned long 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_for_each(const struct idr *,		int idr_for_each(const struct idr *,
	int (fn)(int id, void p, void data), void data);		int (fn)(int id, void p, void data), void data);
	void idr_get_next(struct idr , int *nextid);		void idr_get_next(struct idr , int *nextid);
	void idr_get_next_ext(struct idr idr, unsigned long *nextid);		void idr_get_next_ul(struct idr , unsigned long *nextid);
	void idr_replace(struct idr , void *, int id);		void idr_replace(struct idr , void *, unsigned long id);
	void idr_replace_ext(struct idr idr, void *ptr, unsigned long id);
	void idr_destroy(struct idr *);		void idr_destroy(struct idr *);

	static inline void idr_remove_ext(struct idr idr, unsigned long id)		/**
	{		* idr_init_base() - Initialise an IDR.
	return radix_tree_delete_item(&idr->idr_rt, id, NULL);		* @idr: IDR handle.
	}		* @base: The base value for the IDR.
			*
	static inline void idr_remove(struct idr idr, int id)		* 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)		static inline void idr_init(struct idr *idr)
	{		{
	INIT_RADIX_TREE(&idr->idr_rt, IDR_RT_MARKER);		idr_init_base(idr, 0);
	idr->idr_next = 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)		static inline bool idr_is_empty(const struct idr *idr)
	{		{
	return radix_tree_empty(&idr->idr_rt) &&		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_for_each_entry() - Iterate over an IDR's elements of a given type.
	* @idr: idr handle		* @idr: IDR handle.
	* @id: lookup key		* @entry: The type * to use as cursor
			* @id: Entry ID.
	*		*
	* Return the pointer given the id it has been registered with. A %NULL		* @entry and @id do not need to be initialized before the loop, and
	* return indicates that @id is not valid or you passed %NULL in		* after normal termination @entry is left with the value NULL. This
	* idr_get_new().		* is convenient for a "not found" value.
	*
	* This function can be called under rcu_read_lock(), given that the leaf
	* pointers lifetimes are correctly managed.
	*/		*/
	static inline void idr_find_ext(const struct idr idr, unsigned long id)		#define idr_for_each_entry(idr, entry, id) \
	{		for (id = 0; ((entry) = idr_get_next(idr, &(id))) != NULL; ++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);
	}

	/**		/**
	* idr_for_each_entry - iterate over an idr's elements of a given type		* idr_for_each_entry_ul() - Iterate over an IDR's elements of a given type.
	* @idr: idr handle		* @idr: IDR handle.
	* @entry: the type * to use as cursor		* @entry: The type * to use as cursor.
	* @id: id entry's key		* @id: Entry ID.
	*		*
	* @entry and @id do not need to be initialized before the loop, and		* @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.		* is convenient for a "not found" value.
	*/		*/
	#define idr_for_each_entry(idr, entry, id) \		#define idr_for_each_entry_ul(idr, entry, id) \
	for (id = 0; ((entry) = idr_get_next(idr, &(id))) != NULL; ++id)		for (id = 0; ((entry) = idr_get_next_ul(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)

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

include/linux/radix-tree.h

+1 −16

Original line number	Original line	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,		int radix_tree_join(struct radix_tree_root *, unsigned long index,
	unsigned new_order, void *);		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,		struct radix_tree_iter *iter, gfp_t gfp,
	unsigned long max);		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 {		enum {
	RADIX_TREE_ITER_TAG_MASK = 0x0f, /* tag index in lower nybble */		RADIX_TREE_ITER_TAG_MASK = 0x0f, /* tag index in lower nybble */