linux-stable/include/linux/interval_tree.h
Jason Gunthorpe 5fe937862c interval-tree: Add a utility to iterate over spans in an interval tree
The span iterator travels over the indexes of the interval_tree, not the
nodes, and classifies spans of indexes as either 'used' or 'hole'.

'used' spans are fully covered by nodes in the tree and 'hole' spans have
no node intersecting the span.

This is done greedily such that spans are maximally sized and every
iteration step switches between used/hole.

As an example a trivial allocator can be written as:

	for (interval_tree_span_iter_first(&span, itree, 0, ULONG_MAX);
	     !interval_tree_span_iter_done(&span);
	     interval_tree_span_iter_next(&span))
		if (span.is_hole &&
		    span.last_hole - span.start_hole >= allocation_size - 1)
			return span.start_hole;

With all the tricky boundary conditions handled by the library code.

The following iommufd patches have several algorithms for its overlapping
node interval trees that are significantly simplified with this kind of
iteration primitive. As it seems generally useful, put it into lib/.

Link: https://lore.kernel.org/r/3-v6-a196d26f289e+11787-iommufd_jgg@nvidia.com
Reviewed-by: Kevin Tian <kevin.tian@intel.com>
Reviewed-by: Eric Auger <eric.auger@redhat.com>
Tested-by: Nicolin Chen <nicolinc@nvidia.com>
Tested-by: Yi Liu <yi.l.liu@intel.com>
Tested-by: Lixiao Yang <lixiao.yang@intel.com>
Tested-by: Matthew Rosato <mjrosato@linux.ibm.com>
Signed-off-by: Jason Gunthorpe <jgg@nvidia.com>
2022-11-29 16:34:15 -04:00

88 lines
2.9 KiB
C

/* SPDX-License-Identifier: GPL-2.0 */
#ifndef _LINUX_INTERVAL_TREE_H
#define _LINUX_INTERVAL_TREE_H
#include <linux/rbtree.h>
struct interval_tree_node {
struct rb_node rb;
unsigned long start; /* Start of interval */
unsigned long last; /* Last location _in_ interval */
unsigned long __subtree_last;
};
extern void
interval_tree_insert(struct interval_tree_node *node,
struct rb_root_cached *root);
extern void
interval_tree_remove(struct interval_tree_node *node,
struct rb_root_cached *root);
extern struct interval_tree_node *
interval_tree_iter_first(struct rb_root_cached *root,
unsigned long start, unsigned long last);
extern struct interval_tree_node *
interval_tree_iter_next(struct interval_tree_node *node,
unsigned long start, unsigned long last);
/**
* struct interval_tree_span_iter - Find used and unused spans.
* @start_hole: Start of an interval for a hole when is_hole == 1
* @last_hole: Inclusive end of an interval for a hole when is_hole == 1
* @start_used: Start of a used interval when is_hole == 0
* @last_used: Inclusive end of a used interval when is_hole == 0
* @is_hole: 0 == used, 1 == is_hole, -1 == done iteration
*
* This iterator travels over spans in an interval tree. It does not return
* nodes but classifies each span as either a hole, where no nodes intersect, or
* a used, which is fully covered by nodes. Each iteration step toggles between
* hole and used until the entire range is covered. The returned spans always
* fully cover the requested range.
*
* The iterator is greedy, it always returns the largest hole or used possible,
* consolidating all consecutive nodes.
*
* Use interval_tree_span_iter_done() to detect end of iteration.
*/
struct interval_tree_span_iter {
/* private: not for use by the caller */
struct interval_tree_node *nodes[2];
unsigned long first_index;
unsigned long last_index;
/* public: */
union {
unsigned long start_hole;
unsigned long start_used;
};
union {
unsigned long last_hole;
unsigned long last_used;
};
int is_hole;
};
void interval_tree_span_iter_first(struct interval_tree_span_iter *state,
struct rb_root_cached *itree,
unsigned long first_index,
unsigned long last_index);
void interval_tree_span_iter_advance(struct interval_tree_span_iter *iter,
struct rb_root_cached *itree,
unsigned long new_index);
void interval_tree_span_iter_next(struct interval_tree_span_iter *state);
static inline bool
interval_tree_span_iter_done(struct interval_tree_span_iter *state)
{
return state->is_hole == -1;
}
#define interval_tree_for_each_span(span, itree, first_index, last_index) \
for (interval_tree_span_iter_first(span, itree, \
first_index, last_index); \
!interval_tree_span_iter_done(span); \
interval_tree_span_iter_next(span))
#endif /* _LINUX_INTERVAL_TREE_H */