1 /******************************************************************************
2  * rangeset.h
3  *
4  * Creation, maintenance and automatic destruction of per-domain sets of
5  * numeric ranges.
6  *
7  * Copyright (c) 2005, K A Fraser
8  */
9 
10 #ifndef __XEN_RANGESET_H__
11 #define __XEN_RANGESET_H__
12 
13 #include <xen/types.h>
14 
15 struct domain;
16 struct rangeset;
17 
18 /*
19  * Initialise/destroy per-domain rangeset information.
20  *
21  * It is invalid to create or destroy a rangeset belonging to a domain @d
22  * before rangeset_domain_initialise(d) returns or after calling
23  * rangeset_domain_destroy(d).
24  */
25 void rangeset_domain_initialise(
26     struct domain *d);
27 void rangeset_domain_destroy(
28     struct domain *d);
29 
30 /*
31  * Create/destroy a rangeset. Optionally attach to specified domain @d for
32  * auto-destruction when the domain dies. A name may be specified, for use
33  * in debug pretty-printing, and various RANGESETF flags (defined below).
34  *
35  * It is invalid to perform any operation on a rangeset @r after calling
36  * rangeset_destroy(r).
37  */
38 struct rangeset *rangeset_new(
39     struct domain *d, const char *name, unsigned int flags);
40 void rangeset_destroy(
41     struct rangeset *r);
42 
43 /*
44  * Set a limit on the number of ranges that may exist in set @r.
45  * NOTE: This must be called while @r is empty.
46  */
47 void rangeset_limit(
48     struct rangeset *r, unsigned int limit);
49 
50 /* Flags for passing to rangeset_new(). */
51  /* Pretty-print range limits in hexadecimal. */
52 #define RANGESETF_prettyprint_hex   (1U << 0)
53  /* Do not print entries marked with this flag. */
54 #define RANGESETF_no_print          (1U << 1)
55 
56 bool __must_check rangeset_is_empty(
57     const struct rangeset *r);
58 
59 /* Add/claim/remove/query/purge a numeric range. */
60 int __must_check rangeset_add_range(
61     struct rangeset *r, unsigned long s, unsigned long e);
62 int __must_check rangeset_claim_range(struct rangeset *r, unsigned long size,
63                                       unsigned long *s);
64 int __must_check rangeset_remove_range(
65     struct rangeset *r, unsigned long s, unsigned long e);
66 bool __must_check rangeset_contains_range(
67     struct rangeset *r, unsigned long s, unsigned long e);
68 bool __must_check rangeset_overlaps_range(
69     struct rangeset *r, unsigned long s, unsigned long e);
70 int rangeset_report_ranges(
71     struct rangeset *r, unsigned long s, unsigned long e,
72     int (*cb)(unsigned long s, unsigned long e, void *data), void *ctxt);
73 void rangeset_purge(struct rangeset *r);
74 
75 /*
76  * Note that the consume function can return an error value apart from
77  * -ERESTART, and that no cleanup is performed (ie: the user should call
78  * rangeset_destroy if needed).
79  */
80 int rangeset_consume_ranges(struct rangeset *r,
81                             int (*cb)(unsigned long s, unsigned long e,
82                                       void *ctxt, unsigned long *c),
83                             void *ctxt);
84 
85 /* Merge rangeset r2 into rangeset r1. */
86 int __must_check rangeset_merge(struct rangeset *r1, struct rangeset *r2);
87 
88 /* Subtract rangeset r2 from rangeset r1. */
89 int __must_check rangeset_subtract(struct rangeset *r1, struct rangeset *r2);
90 
91 /* Add/remove/query a single number. */
92 int __must_check rangeset_add_singleton(
93     struct rangeset *r, unsigned long s);
94 int __must_check rangeset_remove_singleton(
95     struct rangeset *r, unsigned long s);
96 bool __must_check rangeset_contains_singleton(
97     struct rangeset *r, unsigned long s);
98 
99 /* swap contents */
100 void rangeset_swap(struct rangeset *a, struct rangeset *b);
101 
102 /* Rangeset pretty printing. */
103 void rangeset_domain_printk(
104     struct domain *d);
105 
106 #endif /* __XEN_RANGESET_H__ */
107 
108 /*
109  * Local variables:
110  * mode: C
111  * c-file-style: "BSD"
112  * c-basic-offset: 4
113  * tab-width: 4
114  * indent-tabs-mode: nil
115  * End:
116  */
117