[mirror_ubuntu-bionic-kernel.git] / include / drm / drm_mm.h

/**************************************************************************
 *
 * Copyright 2006-2008 Tungsten Graphics, Inc., Cedar Park, TX. USA.
 * Copyright 2016 Intel Corporation
 * All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sub license, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice (including the
 * next paragraph) shall be included in all copies or substantial portions
 * of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
 * THE COPYRIGHT HOLDERS, AUTHORS AND/OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM,
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
 * USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 *
 **************************************************************************/
/*
 * Authors:
 * Thomas Hellstrom <thomas-at-tungstengraphics-dot-com>
 */

#ifndef _DRM_MM_H_
#define _DRM_MM_H_

/*
 * Generic range manager structs
 */
#include <linux/bug.h>
#include <linux/rbtree.h>
#include <linux/kernel.h>
#include <linux/list.h>
#include <linux/spinlock.h>
#ifdef CONFIG_DEBUG_FS
#include <linux/seq_file.h>
#endif
#ifdef CONFIG_DRM_DEBUG_MM
#include <linux/stackdepot.h>
#endif

#ifdef CONFIG_DRM_DEBUG_MM
#define DRM_MM_BUG_ON(expr) BUG_ON(expr)
#else
#define DRM_MM_BUG_ON(expr) BUILD_BUG_ON_INVALID(expr)
#endif

enum drm_mm_search_flags {
	DRM_MM_SEARCH_DEFAULT =		0,
	DRM_MM_SEARCH_BEST =		1 << 0,
	DRM_MM_SEARCH_BELOW =		1 << 1,
};

enum drm_mm_allocator_flags {
	DRM_MM_CREATE_DEFAULT =		0,
	DRM_MM_CREATE_TOP =		1 << 0,
};

#define DRM_MM_BOTTOMUP DRM_MM_SEARCH_DEFAULT, DRM_MM_CREATE_DEFAULT
#define DRM_MM_TOPDOWN DRM_MM_SEARCH_BELOW, DRM_MM_CREATE_TOP

struct drm_mm_node {
	struct list_head node_list;
	struct list_head hole_stack;
	struct rb_node rb;
	unsigned hole_follows : 1;
	unsigned allocated : 1;
	bool scanned_block : 1;
	unsigned long color;
	u64 start;
	u64 size;
	u64 __subtree_last;
	struct drm_mm *mm;
#ifdef CONFIG_DRM_DEBUG_MM
	depot_stack_handle_t stack;
#endif
};

struct drm_mm {
	/* List of all memory nodes that immediately precede a free hole. */
	struct list_head hole_stack;
	/* head_node.node_list is the list of all memory nodes, ordered
	 * according to the (increasing) start address of the memory node. */
	struct drm_mm_node head_node;
	/* Keep an interval_tree for fast lookup of drm_mm_nodes by address. */
	struct rb_root interval_tree;

	void (*color_adjust)(const struct drm_mm_node *node,
			     unsigned long color,
			     u64 *start, u64 *end);

	unsigned long scan_active;
};

struct drm_mm_scan {
	struct drm_mm *mm;

	u64 size;
	u64 alignment;
	u64 remainder_mask;

	u64 range_start;
	u64 range_end;

	u64 hit_start;
	u64 hit_end;

	unsigned long color;
	unsigned int flags;
};

/**
 * drm_mm_node_allocated - checks whether a node is allocated
 * @node: drm_mm_node to check
 *
 * Drivers are required to clear a node prior to using it with the
 * drm_mm range manager.
 *
 * Drivers should use this helper for proper encapsulation of drm_mm
 * internals.
 *
 * Returns:
 * True if the @node is allocated.
 */
static inline bool drm_mm_node_allocated(const struct drm_mm_node *node)
{
	return node->allocated;
}

/**
 * drm_mm_initialized - checks whether an allocator is initialized
 * @mm: drm_mm to check
 *
 * Drivers should clear the struct drm_mm prior to initialisation if they
 * want to use this function.
 *
 * Drivers should use this helper for proper encapsulation of drm_mm
 * internals.
 *
 * Returns:
 * True if the @mm is initialized.
 */
static inline bool drm_mm_initialized(const struct drm_mm *mm)
{
	return mm->hole_stack.next;
}

static inline u64 __drm_mm_hole_node_start(const struct drm_mm_node *hole_node)
{
	return hole_node->start + hole_node->size;
}

/**
 * drm_mm_hole_node_start - computes the start of the hole following @node
 * @hole_node: drm_mm_node which implicitly tracks the following hole
 *
 * This is useful for driver-specific debug dumpers. Otherwise drivers should
 * not inspect holes themselves. Drivers must check first whether a hole indeed
 * follows by looking at node->hole_follows.
 *
 * Returns:
 * Start of the subsequent hole.
 */
static inline u64 drm_mm_hole_node_start(const struct drm_mm_node *hole_node)
{
	DRM_MM_BUG_ON(!hole_node->hole_follows);
	return __drm_mm_hole_node_start(hole_node);
}

static inline u64 __drm_mm_hole_node_end(const struct drm_mm_node *hole_node)
{
	return list_next_entry(hole_node, node_list)->start;
}

/**
 * drm_mm_hole_node_end - computes the end of the hole following @node
 * @hole_node: drm_mm_node which implicitly tracks the following hole
 *
 * This is useful for driver-specific debug dumpers. Otherwise drivers should
 * not inspect holes themselves. Drivers must check first whether a hole indeed
 * follows by looking at node->hole_follows.
 *
 * Returns:
 * End of the subsequent hole.
 */
static inline u64 drm_mm_hole_node_end(const struct drm_mm_node *hole_node)
{
	return __drm_mm_hole_node_end(hole_node);
}

/**
 * drm_mm_nodes - list of nodes under the drm_mm range manager
 * @mm: the struct drm_mm range manger
 *
 * As the drm_mm range manager hides its node_list deep with its
 * structure, extracting it looks painful and repetitive. This is
 * not expected to be used outside of the drm_mm_for_each_node()
 * macros and similar internal functions.
 *
 * Returns:
 * The node list, may be empty.
 */
#define drm_mm_nodes(mm) (&(mm)->head_node.node_list)

/**
 * drm_mm_for_each_node - iterator to walk over all allocated nodes
 * @entry: drm_mm_node structure to assign to in each iteration step
 * @mm: drm_mm allocator to walk
 *
 * This iterator walks over all nodes in the range allocator. It is implemented
 * with list_for_each, so not save against removal of elements.
 */
#define drm_mm_for_each_node(entry, mm) \
	list_for_each_entry(entry, drm_mm_nodes(mm), node_list)

/**
 * drm_mm_for_each_node_safe - iterator to walk over all allocated nodes
 * @entry: drm_mm_node structure to assign to in each iteration step
 * @next: drm_mm_node structure to store the next step
 * @mm: drm_mm allocator to walk
 *
 * This iterator walks over all nodes in the range allocator. It is implemented
 * with list_for_each_safe, so save against removal of elements.
 */
#define drm_mm_for_each_node_safe(entry, next, mm) \
	list_for_each_entry_safe(entry, next, drm_mm_nodes(mm), node_list)

#define __drm_mm_for_each_hole(entry, mm, hole_start, hole_end, backwards) \
	for (entry = list_entry((backwards) ? (mm)->hole_stack.prev : (mm)->hole_stack.next, struct drm_mm_node, hole_stack); \
	     &entry->hole_stack != &(mm)->hole_stack ? \
	     hole_start = drm_mm_hole_node_start(entry), \
	     hole_end = drm_mm_hole_node_end(entry), \
	     1 : 0; \
	     entry = list_entry((backwards) ? entry->hole_stack.prev : entry->hole_stack.next, struct drm_mm_node, hole_stack))

/**
 * drm_mm_for_each_hole - iterator to walk over all holes
 * @entry: drm_mm_node used internally to track progress
 * @mm: drm_mm allocator to walk
 * @hole_start: ulong variable to assign the hole start to on each iteration
 * @hole_end: ulong variable to assign the hole end to on each iteration
 *
 * This iterator walks over all holes in the range allocator. It is implemented
 * with list_for_each, so not save against removal of elements. @entry is used
 * internally and will not reflect a real drm_mm_node for the very first hole.
 * Hence users of this iterator may not access it.
 *
 * Implementation Note:
 * We need to inline list_for_each_entry in order to be able to set hole_start
 * and hole_end on each iteration while keeping the macro sane.
 *
 * The __drm_mm_for_each_hole version is similar, but with added support for
 * going backwards.
 */
#define drm_mm_for_each_hole(entry, mm, hole_start, hole_end) \
	__drm_mm_for_each_hole(entry, mm, hole_start, hole_end, 0)

/*
 * Basic range manager support (drm_mm.c)
 */
int drm_mm_reserve_node(struct drm_mm *mm, struct drm_mm_node *node);

int drm_mm_insert_node_generic(struct drm_mm *mm,
			       struct drm_mm_node *node,
			       u64 size,
			       u64 alignment,
			       unsigned long color,
			       enum drm_mm_search_flags sflags,
			       enum drm_mm_allocator_flags aflags);
/**
 * drm_mm_insert_node - search for space and insert @node
 * @mm: drm_mm to allocate from
 * @node: preallocate node to insert
 * @size: size of the allocation
 * @alignment: alignment of the allocation
 * @flags: flags to fine-tune the allocation
 *
 * This is a simplified version of drm_mm_insert_node_generic() with @color set
 * to 0.
 *
 * The preallocated node must be cleared to 0.
 *
 * Returns:
 * 0 on success, -ENOSPC if there's no suitable hole.
 */
static inline int drm_mm_insert_node(struct drm_mm *mm,
				     struct drm_mm_node *node,
				     u64 size,
				     u64 alignment,
				     enum drm_mm_search_flags flags)
{
	return drm_mm_insert_node_generic(mm, node, size, alignment, 0, flags,
					  DRM_MM_CREATE_DEFAULT);
}

int drm_mm_insert_node_in_range_generic(struct drm_mm *mm,
					struct drm_mm_node *node,
					u64 size,
					u64 alignment,
					unsigned long color,
					u64 start,
					u64 end,
					enum drm_mm_search_flags sflags,
					enum drm_mm_allocator_flags aflags);
/**
 * drm_mm_insert_node_in_range - ranged search for space and insert @node
 * @mm: drm_mm to allocate from
 * @node: preallocate node to insert
 * @size: size of the allocation
 * @alignment: alignment of the allocation
 * @start: start of the allowed range for this node
 * @end: end of the allowed range for this node
 * @flags: flags to fine-tune the allocation
 *
 * This is a simplified version of drm_mm_insert_node_in_range_generic() with
 * @color set to 0.
 *
 * The preallocated node must be cleared to 0.
 *
 * Returns:
 * 0 on success, -ENOSPC if there's no suitable hole.
 */
static inline int drm_mm_insert_node_in_range(struct drm_mm *mm,
					      struct drm_mm_node *node,
					      u64 size,
					      u64 alignment,
					      u64 start,
					      u64 end,
					      enum drm_mm_search_flags flags)
{
	return drm_mm_insert_node_in_range_generic(mm, node, size, alignment,
						   0, start, end, flags,
						   DRM_MM_CREATE_DEFAULT);
}

void drm_mm_remove_node(struct drm_mm_node *node);
void drm_mm_replace_node(struct drm_mm_node *old, struct drm_mm_node *new);
void drm_mm_init(struct drm_mm *mm, u64 start, u64 size);
void drm_mm_takedown(struct drm_mm *mm);

/**
 * drm_mm_clean - checks whether an allocator is clean
 * @mm: drm_mm allocator to check
 *
 * Returns:
 * True if the allocator is completely free, false if there's still a node
 * allocated in it.
 */
static inline bool drm_mm_clean(const struct drm_mm *mm)
{
	return list_empty(drm_mm_nodes(mm));
}

struct drm_mm_node *
__drm_mm_interval_first(const struct drm_mm *mm, u64 start, u64 last);

/**
 * drm_mm_for_each_node_in_range - iterator to walk over a range of
 * allocated nodes
 * @node__: drm_mm_node structure to assign to in each iteration step
 * @mm__: drm_mm allocator to walk
 * @start__: starting offset, the first node will overlap this
 * @end__: ending offset, the last node will start before this (but may overlap)
 *
 * This iterator walks over all nodes in the range allocator that lie
 * between @start and @end. It is implemented similarly to list_for_each(),
 * but using the internal interval tree to accelerate the search for the
 * starting node, and so not safe against removal of elements. It assumes
 * that @end is within (or is the upper limit of) the drm_mm allocator.
 */
#define drm_mm_for_each_node_in_range(node__, mm__, start__, end__)	\
	for (node__ = __drm_mm_interval_first((mm__), (start__), (end__)-1); \
	     node__ && node__->start < (end__);				\
	     node__ = list_next_entry(node__, node_list))

void drm_mm_scan_init_with_range(struct drm_mm_scan *scan,
				 struct drm_mm *mm,
				 u64 size, u64 alignment, unsigned long color,
				 u64 start, u64 end,
				 unsigned int flags);

/**
 * drm_mm_scan_init - initialize lru scanning
 * @scan: scan state
 * @mm: drm_mm to scan
 * @size: size of the allocation
 * @alignment: alignment of the allocation
 * @color: opaque tag value to use for the allocation
 * @flags: flags to specify how the allocation will be performed afterwards
 *
 * This simply sets up the scanning routines with the parameters for the desired
 * hole.
 *
 * Warning:
 * As long as the scan list is non-empty, no other operations than
 * adding/removing nodes to/from the scan list are allowed.
 */
static inline void drm_mm_scan_init(struct drm_mm_scan *scan,
				    struct drm_mm *mm,
				    u64 size,
				    u64 alignment,
				    unsigned long color,
				    unsigned int flags)
{
	drm_mm_scan_init_with_range(scan, mm,
				    size, alignment, color,
				    0, U64_MAX,
				    flags);
}

bool drm_mm_scan_add_block(struct drm_mm_scan *scan,
			   struct drm_mm_node *node);
bool drm_mm_scan_remove_block(struct drm_mm_scan *scan,
			      struct drm_mm_node *node);
struct drm_mm_node *drm_mm_scan_color_evict(struct drm_mm_scan *scan);

void drm_mm_debug_table(const struct drm_mm *mm, const char *prefix);
#ifdef CONFIG_DEBUG_FS
int drm_mm_dump_table(struct seq_file *m, const struct drm_mm *mm);
#endif

#endif
Commit	Line	Data
249d6048 JG	1	/**************************************************************************
	2	*
	3	* Copyright 2006-2008 Tungsten Graphics, Inc., Cedar Park, TX. USA.
ba004e39	4	* Copyright 2016 Intel Corporation
249d6048 JG	5	* All Rights Reserved.
	6	*
	7	* Permission is hereby granted, free of charge, to any person obtaining a
	8	* copy of this software and associated documentation files (the
	9	* "Software"), to deal in the Software without restriction, including
	10	* without limitation the rights to use, copy, modify, merge, publish,
	11	* distribute, sub license, and/or sell copies of the Software, and to
	12	* permit persons to whom the Software is furnished to do so, subject to
	13	* the following conditions:
	14	*
	15	* The above copyright notice and this permission notice (including the
	16	* next paragraph) shall be included in all copies or substantial portions
	17	* of the Software.
	18	*
	19	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	20	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	21	* FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
	22	* THE COPYRIGHT HOLDERS, AUTHORS AND/OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM,
	23	* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
	24	* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
	25	* USE OR OTHER DEALINGS IN THE SOFTWARE.
	26	*
	27	*
	28	**************************************************************************/
	29	/*
	30	* Authors:
	31	* Thomas Hellstrom <thomas-at-tungstengraphics-dot-com>
	32	*/
	33
	34	#ifndef _DRM_MM_H_
	35	#define _DRM_MM_H_
	36
	37	/*
	38	* Generic range manager structs
	39	*/
86e81f0e	40	#include <linux/bug.h>
202b52b7	41	#include <linux/rbtree.h>
86e81f0e	42	#include <linux/kernel.h>
249d6048	43	#include <linux/list.h>
86e81f0e	44	#include <linux/spinlock.h>
f1938cd6 DA	45	#ifdef CONFIG_DEBUG_FS
	46	#include <linux/seq_file.h>
	47	#endif
5705670d CW	48	#ifdef CONFIG_DRM_DEBUG_MM
	49	#include <linux/stackdepot.h>
	50	#endif
249d6048	51
b3ee963f CW	52	#ifdef CONFIG_DRM_DEBUG_MM
	53	#define DRM_MM_BUG_ON(expr) BUG_ON(expr)
	54	#else
	55	#define DRM_MM_BUG_ON(expr) BUILD_BUG_ON_INVALID(expr)
	56	#endif
	57
31e5d7c6 DH	58	enum drm_mm_search_flags {
	59	DRM_MM_SEARCH_DEFAULT = 0,
	60	DRM_MM_SEARCH_BEST = 1 << 0,
62347f9e	61	DRM_MM_SEARCH_BELOW = 1 << 1,
31e5d7c6 DH	62	};
31e5d7c6 DH	63
62347f9e LK	64	enum drm_mm_allocator_flags {
	65	DRM_MM_CREATE_DEFAULT = 0,
	66	DRM_MM_CREATE_TOP = 1 << 0,
	67	};
	68
	69	#define DRM_MM_BOTTOMUP DRM_MM_SEARCH_DEFAULT, DRM_MM_CREATE_DEFAULT
	70	#define DRM_MM_TOPDOWN DRM_MM_SEARCH_BELOW, DRM_MM_CREATE_TOP
	71
249d6048	72	struct drm_mm_node {
d1024ce9	73	struct list_head node_list;
ea7b1dd4	74	struct list_head hole_stack;
202b52b7	75	struct rb_node rb;
ea7b1dd4	76	unsigned hole_follows : 1;
b0b7af18	77	unsigned allocated : 1;
f29051f1	78	bool scanned_block : 1;
6b9d89b4	79	unsigned long color;
440fd528 TR	80	u64 start;
440fd528 TR	81	u64 size;
202b52b7	82	u64 __subtree_last;
249d6048	83	struct drm_mm *mm;
5705670d CW	84	#ifdef CONFIG_DRM_DEBUG_MM
	85	depot_stack_handle_t stack;
	86	#endif
249d6048 JG	87	};
	88
	89	struct drm_mm {
25985edc	90	/* List of all memory nodes that immediately precede a free hole. */
ea7b1dd4 DV	91	struct list_head hole_stack;
	92	/* head_node.node_list is the list of all memory nodes, ordered
	93	* according to the (increasing) start address of the memory node. */
	94	struct drm_mm_node head_node;
202b52b7 CW	95	/* Keep an interval_tree for fast lookup of drm_mm_nodes by address. */
	96	struct rb_root interval_tree;
	97
45b186f1 CW	98	void (color_adjust)(const struct drm_mm_node node,
45b186f1 CW	99	unsigned long color,
440fd528	100	u64 start, u64 end);
9a71e277 CW	101
	102	unsigned long scan_active;
	103	};
	104
	105	struct drm_mm_scan {
	106	struct drm_mm *mm;
	107
	108	u64 size;
	109	u64 alignment;
9a956b15	110	u64 remainder_mask;
9a71e277 CW	111
	112	u64 range_start;
	113	u64 range_end;
	114
	115	u64 hit_start;
	116	u64 hit_end;
	117
9a71e277	118	unsigned long color;
0b04d474	119	unsigned int flags;
249d6048 JG	120	};
249d6048 JG	121
e18c0412 DV	122	/**
	123	* drm_mm_node_allocated - checks whether a node is allocated
	124	* @node: drm_mm_node to check
	125	*
ba004e39 CW	126	* Drivers are required to clear a node prior to using it with the
	127	* drm_mm range manager.
	128	*
	129	* Drivers should use this helper for proper encapsulation of drm_mm
e18c0412 DV	130	* internals.
	131	*
	132	* Returns:
	133	* True if the @node is allocated.
	134	*/
45b186f1	135	static inline bool drm_mm_node_allocated(const struct drm_mm_node *node)
b0b7af18 DV	136	{
	137	return node->allocated;
	138	}
	139
e18c0412 DV	140	/**
	141	* drm_mm_initialized - checks whether an allocator is initialized
	142	* @mm: drm_mm to check
	143	*
ba004e39 CW	144	* Drivers should clear the struct drm_mm prior to initialisation if they
	145	* want to use this function.
	146	*
	147	* Drivers should use this helper for proper encapsulation of drm_mm
e18c0412 DV	148	* internals.
	149	*
	150	* Returns:
	151	* True if the @mm is initialized.
	152	*/
45b186f1	153	static inline bool drm_mm_initialized(const struct drm_mm *mm)
31a5b8ce	154	{
ea7b1dd4	155	return mm->hole_stack.next;
31a5b8ce	156	}
9e8944ab	157
45b186f1	158	static inline u64 __drm_mm_hole_node_start(const struct drm_mm_node *hole_node)
9e8944ab CW	159	{
	160	return hole_node->start + hole_node->size;
	161	}
	162
e18c0412 DV	163	/**
	164	* drm_mm_hole_node_start - computes the start of the hole following @node
	165	* @hole_node: drm_mm_node which implicitly tracks the following hole
	166	*
ba004e39 CW	167	* This is useful for driver-specific debug dumpers. Otherwise drivers should
ba004e39 CW	168	* not inspect holes themselves. Drivers must check first whether a hole indeed
e18c0412 DV	169	* follows by looking at node->hole_follows.
	170	*
	171	* Returns:
	172	* Start of the subsequent hole.
	173	*/
45b186f1	174	static inline u64 drm_mm_hole_node_start(const struct drm_mm_node *hole_node)
9e8944ab	175	{
b3ee963f	176	DRM_MM_BUG_ON(!hole_node->hole_follows);
9e8944ab CW	177	return __drm_mm_hole_node_start(hole_node);
	178	}
	179
45b186f1	180	static inline u64 __drm_mm_hole_node_end(const struct drm_mm_node *hole_node)
9e8944ab	181	{
87069f44	182	return list_next_entry(hole_node, node_list)->start;
9e8944ab CW	183	}
9e8944ab CW	184
e18c0412 DV	185	/**
	186	* drm_mm_hole_node_end - computes the end of the hole following @node
	187	* @hole_node: drm_mm_node which implicitly tracks the following hole
	188	*
ba004e39 CW	189	* This is useful for driver-specific debug dumpers. Otherwise drivers should
ba004e39 CW	190	* not inspect holes themselves. Drivers must check first whether a hole indeed
e18c0412 DV	191	* follows by looking at node->hole_follows.
	192	*
	193	* Returns:
	194	* End of the subsequent hole.
	195	*/
45b186f1	196	static inline u64 drm_mm_hole_node_end(const struct drm_mm_node *hole_node)
9e8944ab CW	197	{
	198	return __drm_mm_hole_node_end(hole_node);
	199	}
	200
2bc98c86 CW	201	/**
	202	* drm_mm_nodes - list of nodes under the drm_mm range manager
	203	* @mm: the struct drm_mm range manger
	204	*
	205	* As the drm_mm range manager hides its node_list deep with its
	206	* structure, extracting it looks painful and repetitive. This is
	207	* not expected to be used outside of the drm_mm_for_each_node()
	208	* macros and similar internal functions.
	209	*
	210	* Returns:
	211	* The node list, may be empty.
	212	*/
	213	#define drm_mm_nodes(mm) (&(mm)->head_node.node_list)
ad579002	214
e18c0412 DV	215	/**
	216	* drm_mm_for_each_node - iterator to walk over all allocated nodes
	217	* @entry: drm_mm_node structure to assign to in each iteration step
	218	* @mm: drm_mm allocator to walk
	219	*
	220	* This iterator walks over all nodes in the range allocator. It is implemented
	221	* with list_for_each, so not save against removal of elements.
	222	*/
ad579002	223	#define drm_mm_for_each_node(entry, mm) \
2bc98c86	224	list_for_each_entry(entry, drm_mm_nodes(mm), node_list)
ad579002 CW	225
	226	/**
	227	* drm_mm_for_each_node_safe - iterator to walk over all allocated nodes
	228	* @entry: drm_mm_node structure to assign to in each iteration step
	229	* @next: drm_mm_node structure to store the next step
	230	* @mm: drm_mm allocator to walk
	231	*
	232	* This iterator walks over all nodes in the range allocator. It is implemented
	233	* with list_for_each_safe, so save against removal of elements.
	234	*/
	235	#define drm_mm_for_each_node_safe(entry, next, mm) \
2bc98c86	236	list_for_each_entry_safe(entry, next, drm_mm_nodes(mm), node_list)
9e8944ab	237
18b40c58 GT	238	#define __drm_mm_for_each_hole(entry, mm, hole_start, hole_end, backwards) \
	239	for (entry = list_entry((backwards) ? (mm)->hole_stack.prev : (mm)->hole_stack.next, struct drm_mm_node, hole_stack); \
	240	&entry->hole_stack != &(mm)->hole_stack ? \
	241	hole_start = drm_mm_hole_node_start(entry), \
	242	hole_end = drm_mm_hole_node_end(entry), \
	243	1 : 0; \
	244	entry = list_entry((backwards) ? entry->hole_stack.prev : entry->hole_stack.next, struct drm_mm_node, hole_stack))
	245
e18c0412 DV	246	/**
	247	* drm_mm_for_each_hole - iterator to walk over all holes
	248	* @entry: drm_mm_node used internally to track progress
	249	* @mm: drm_mm allocator to walk
	250	* @hole_start: ulong variable to assign the hole start to on each iteration
	251	* @hole_end: ulong variable to assign the hole end to on each iteration
	252	*
	253	* This iterator walks over all holes in the range allocator. It is implemented
	254	* with list_for_each, so not save against removal of elements. @entry is used
	255	* internally and will not reflect a real drm_mm_node for the very first hole.
	256	* Hence users of this iterator may not access it.
	257	*
	258	* Implementation Note:
	259	* We need to inline list_for_each_entry in order to be able to set hole_start
	260	* and hole_end on each iteration while keeping the macro sane.
62347f9e LK	261	*
	262	* The __drm_mm_for_each_hole version is similar, but with added support for
	263	* going backwards.
9e8944ab CW	264	*/
9e8944ab CW	265	#define drm_mm_for_each_hole(entry, mm, hole_start, hole_end) \
18b40c58	266	__drm_mm_for_each_hole(entry, mm, hole_start, hole_end, 0)
62347f9e	267
249d6048 JG	268	/*
	269	* Basic range manager support (drm_mm.c)
	270	*/
e18c0412 DV	271	int drm_mm_reserve_node(struct drm_mm mm, struct drm_mm_node node);
	272
	273	int drm_mm_insert_node_generic(struct drm_mm *mm,
	274	struct drm_mm_node *node,
440fd528	275	u64 size,
71733207	276	u64 alignment,
e18c0412	277	unsigned long color,
62347f9e LK	278	enum drm_mm_search_flags sflags,
62347f9e LK	279	enum drm_mm_allocator_flags aflags);
e18c0412 DV	280	/**
	281	* drm_mm_insert_node - search for space and insert @node
	282	* @mm: drm_mm to allocate from
	283	* @node: preallocate node to insert
	284	* @size: size of the allocation
	285	* @alignment: alignment of the allocation
	286	* @flags: flags to fine-tune the allocation
	287	*
	288	* This is a simplified version of drm_mm_insert_node_generic() with @color set
	289	* to 0.
	290	*
	291	* The preallocated node must be cleared to 0.
	292	*
	293	* Returns:
	294	* 0 on success, -ENOSPC if there's no suitable hole.
	295	*/
31e5d7c6 DH	296	static inline int drm_mm_insert_node(struct drm_mm *mm,
31e5d7c6 DH	297	struct drm_mm_node *node,
440fd528	298	u64 size,
71733207	299	u64 alignment,
31e5d7c6 DH	300	enum drm_mm_search_flags flags)
31e5d7c6 DH	301	{
62347f9e LK	302	return drm_mm_insert_node_generic(mm, node, size, alignment, 0, flags,
62347f9e LK	303	DRM_MM_CREATE_DEFAULT);
31e5d7c6 DH	304	}
31e5d7c6 DH	305
e18c0412 DV	306	int drm_mm_insert_node_in_range_generic(struct drm_mm *mm,
e18c0412 DV	307	struct drm_mm_node *node,
440fd528	308	u64 size,
71733207	309	u64 alignment,
e18c0412	310	unsigned long color,
440fd528 TR	311	u64 start,
440fd528 TR	312	u64 end,
62347f9e LK	313	enum drm_mm_search_flags sflags,
62347f9e LK	314	enum drm_mm_allocator_flags aflags);
e18c0412 DV	315	/**
	316	* drm_mm_insert_node_in_range - ranged search for space and insert @node
	317	* @mm: drm_mm to allocate from
	318	* @node: preallocate node to insert
	319	* @size: size of the allocation
	320	* @alignment: alignment of the allocation
	321	* @start: start of the allowed range for this node
	322	* @end: end of the allowed range for this node
	323	* @flags: flags to fine-tune the allocation
	324	*
	325	* This is a simplified version of drm_mm_insert_node_in_range_generic() with
	326	* @color set to 0.
	327	*
	328	* The preallocated node must be cleared to 0.
	329	*
	330	* Returns:
	331	* 0 on success, -ENOSPC if there's no suitable hole.
	332	*/
31e5d7c6 DH	333	static inline int drm_mm_insert_node_in_range(struct drm_mm *mm,
31e5d7c6 DH	334	struct drm_mm_node *node,
440fd528	335	u64 size,
71733207	336	u64 alignment,
440fd528 TR	337	u64 start,
440fd528 TR	338	u64 end,
31e5d7c6 DH	339	enum drm_mm_search_flags flags)
	340	{
	341	return drm_mm_insert_node_in_range_generic(mm, node, size, alignment,
62347f9e LK	342	0, start, end, flags,
62347f9e LK	343	DRM_MM_CREATE_DEFAULT);
31e5d7c6 DH	344	}
31e5d7c6 DH	345
e18c0412 DV	346	void drm_mm_remove_node(struct drm_mm_node *node);
e18c0412 DV	347	void drm_mm_replace_node(struct drm_mm_node old, struct drm_mm_node new);
45b186f1	348	void drm_mm_init(struct drm_mm *mm, u64 start, u64 size);
e18c0412	349	void drm_mm_takedown(struct drm_mm *mm);
ac9bb7b7 CW	350
	351	/**
	352	* drm_mm_clean - checks whether an allocator is clean
	353	* @mm: drm_mm allocator to check
	354	*
	355	* Returns:
	356	* True if the allocator is completely free, false if there's still a node
	357	* allocated in it.
	358	*/
	359	static inline bool drm_mm_clean(const struct drm_mm *mm)
	360	{
	361	return list_empty(drm_mm_nodes(mm));
	362	}
249d6048	363
202b52b7	364	struct drm_mm_node *
45b186f1	365	__drm_mm_interval_first(const struct drm_mm *mm, u64 start, u64 last);
202b52b7	366
522e85dd CW	367	/**
	368	* drm_mm_for_each_node_in_range - iterator to walk over a range of
	369	* allocated nodes
8b2fb7b6 CW	370	* @node__: drm_mm_node structure to assign to in each iteration step
	371	* @mm__: drm_mm allocator to walk
	372	* @start__: starting offset, the first node will overlap this
	373	* @end__: ending offset, the last node will start before this (but may overlap)
522e85dd CW	374	*
	375	* This iterator walks over all nodes in the range allocator that lie
	376	* between @start and @end. It is implemented similarly to list_for_each(),
	377	* but using the internal interval tree to accelerate the search for the
	378	* starting node, and so not safe against removal of elements. It assumes
	379	* that @end is within (or is the upper limit of) the drm_mm allocator.
	380	*/
8b2fb7b6 CW	381	#define drm_mm_for_each_node_in_range(node__, mm__, start__, end__) \
	382	for (node__ = __drm_mm_interval_first((mm__), (start__), (end__)-1); \
	383	node__ && node__->start < (end__); \
	384	node__ = list_next_entry(node__, node_list))
202b52b7	385
9a71e277 CW	386	void drm_mm_scan_init_with_range(struct drm_mm_scan *scan,
9a71e277 CW	387	struct drm_mm *mm,
0b04d474 CW	388	u64 size, u64 alignment, unsigned long color,
	389	u64 start, u64 end,
	390	unsigned int flags);
2c4b3895 CW	391
	392	/**
	393	* drm_mm_scan_init - initialize lru scanning
	394	* @scan: scan state
	395	* @mm: drm_mm to scan
	396	* @size: size of the allocation
	397	* @alignment: alignment of the allocation
	398	* @color: opaque tag value to use for the allocation
0b04d474	399	* @flags: flags to specify how the allocation will be performed afterwards
2c4b3895 CW	400	*
2c4b3895 CW	401	* This simply sets up the scanning routines with the parameters for the desired
0b04d474	402	* hole.
2c4b3895 CW	403	*
	404	* Warning:
	405	* As long as the scan list is non-empty, no other operations than
	406	* adding/removing nodes to/from the scan list are allowed.
	407	*/
	408	static inline void drm_mm_scan_init(struct drm_mm_scan *scan,
	409	struct drm_mm *mm,
	410	u64 size,
	411	u64 alignment,
0b04d474 CW	412	unsigned long color,
0b04d474 CW	413	unsigned int flags)
2c4b3895	414	{
0b04d474 CW	415	drm_mm_scan_init_with_range(scan, mm,
	416	size, alignment, color,
	417	0, U64_MAX,
	418	flags);
2c4b3895 CW	419	}
2c4b3895 CW	420
9a71e277 CW	421	bool drm_mm_scan_add_block(struct drm_mm_scan *scan,
	422	struct drm_mm_node *node);
	423	bool drm_mm_scan_remove_block(struct drm_mm_scan *scan,
	424	struct drm_mm_node *node);
3fa489da	425	struct drm_mm_node drm_mm_scan_color_evict(struct drm_mm_scan scan);
709ea971	426
45b186f1	427	void drm_mm_debug_table(const struct drm_mm mm, const char prefix);
fa8a1238	428	#ifdef CONFIG_DEBUG_FS
45b186f1	429	int drm_mm_dump_table(struct seq_file m, const struct drm_mm mm);
fa8a1238 DA	430	#endif
fa8a1238 DA	431
249d6048	432	#endif