]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
4 | * Copyright (c) Intel Corporation. | |
5 | * All rights reserved. | |
6 | * | |
7 | * Redistribution and use in source and binary forms, with or without | |
8 | * modification, are permitted provided that the following conditions | |
9 | * are met: | |
10 | * | |
11 | * * Redistributions of source code must retain the above copyright | |
12 | * notice, this list of conditions and the following disclaimer. | |
13 | * * Redistributions in binary form must reproduce the above copyright | |
14 | * notice, this list of conditions and the following disclaimer in | |
15 | * the documentation and/or other materials provided with the | |
16 | * distribution. | |
17 | * * Neither the name of Intel Corporation nor the names of its | |
18 | * contributors may be used to endorse or promote products derived | |
19 | * from this software without specific prior written permission. | |
20 | * | |
21 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
22 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
23 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
24 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
25 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
26 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
27 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
28 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
29 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
30 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
31 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
32 | */ | |
33 | ||
34 | /** \file | |
35 | * Bit array data structure | |
36 | */ | |
37 | ||
38 | #ifndef SPDK_BIT_ARRAY_H | |
39 | #define SPDK_BIT_ARRAY_H | |
40 | ||
11fdf7f2 TL |
41 | #include "spdk/stdinc.h" |
42 | ||
7c673cae FG |
43 | #ifdef __cplusplus |
44 | extern "C" { | |
45 | #endif | |
46 | ||
7c673cae FG |
47 | /** |
48 | * Variable-length bit array. | |
49 | */ | |
50 | struct spdk_bit_array; | |
51 | ||
52 | /** | |
11fdf7f2 TL |
53 | * Return the number of bits that a bit array is currently sized to hold. |
54 | * | |
55 | * \param ba Bit array to query. | |
56 | * | |
57 | * \return the number of bits. | |
7c673cae FG |
58 | */ |
59 | uint32_t spdk_bit_array_capacity(const struct spdk_bit_array *ba); | |
60 | ||
61 | /** | |
62 | * Create a bit array. | |
11fdf7f2 TL |
63 | * |
64 | * \param num_bits Number of bits that the bit array is sized to hold. | |
65 | * | |
66 | * All bits in the array will be cleared. | |
67 | * | |
68 | * \return a pointer to the new bit array. | |
7c673cae FG |
69 | */ |
70 | struct spdk_bit_array *spdk_bit_array_create(uint32_t num_bits); | |
71 | ||
72 | /** | |
73 | * Free a bit array and set the pointer to NULL. | |
11fdf7f2 TL |
74 | * |
75 | * \param bap Bit array to free. | |
7c673cae FG |
76 | */ |
77 | void spdk_bit_array_free(struct spdk_bit_array **bap); | |
78 | ||
79 | /** | |
80 | * Create or resize a bit array. | |
81 | * | |
11fdf7f2 TL |
82 | * To create a new bit array, pass a pointer to a spdk_bit_array pointer that is |
83 | * NULL for bap. | |
7c673cae FG |
84 | * |
85 | * The bit array will be sized to hold at least num_bits. | |
86 | * | |
87 | * If num_bits is smaller than the previous size of the bit array, | |
88 | * any data beyond the new num_bits size will be cleared. | |
89 | * | |
90 | * If num_bits is larger than the previous size of the bit array, | |
91 | * any data beyond the old num_bits size will be cleared. | |
11fdf7f2 TL |
92 | * |
93 | * \param bap Bit array to create/resize. | |
94 | * \param num_bits Number of bits that the bit array is sized to hold. | |
95 | * | |
96 | * \return 0 on success, negative errno on failure. | |
7c673cae FG |
97 | */ |
98 | int spdk_bit_array_resize(struct spdk_bit_array **bap, uint32_t num_bits); | |
99 | ||
100 | /** | |
101 | * Get the value of a bit from the bit array. | |
102 | * | |
11fdf7f2 TL |
103 | * If bit_index is beyond the end of the current size of the bit array, this |
104 | * function will return false (i.e. bits beyond the end of the array are implicitly 0). | |
105 | * | |
106 | * \param ba Bit array to query. | |
107 | * \param bit_index The index of a bit to query. | |
108 | * | |
109 | * \return the value of a bit from the bit array on success, or false on failure. | |
7c673cae FG |
110 | */ |
111 | bool spdk_bit_array_get(const struct spdk_bit_array *ba, uint32_t bit_index); | |
112 | ||
113 | /** | |
114 | * Set (to 1) a bit in the bit array. | |
115 | * | |
116 | * If bit_index is beyond the end of the bit array, this function will return -EINVAL. | |
11fdf7f2 TL |
117 | * |
118 | * \param ba Bit array to set a bit. | |
119 | * \param bit_index The index of a bit to set. | |
120 | * | |
121 | * \return 0 on success, negative errno on failure. | |
7c673cae FG |
122 | */ |
123 | int spdk_bit_array_set(struct spdk_bit_array *ba, uint32_t bit_index); | |
124 | ||
125 | /** | |
126 | * Clear (to 0) a bit in the bit array. | |
127 | * | |
11fdf7f2 TL |
128 | * If bit_index is beyond the end of the bit array, no action is taken. Bits |
129 | * beyond the end of the bit array are implicitly 0. | |
130 | * | |
131 | * \param ba Bit array to clear a bit. | |
132 | * \param bit_index The index of a bit to clear. | |
7c673cae FG |
133 | */ |
134 | void spdk_bit_array_clear(struct spdk_bit_array *ba, uint32_t bit_index); | |
135 | ||
136 | /** | |
137 | * Find the index of the first set bit in the array. | |
138 | * | |
139 | * \param ba The bit array to search. | |
11fdf7f2 TL |
140 | * \param start_bit_index The bit index from which to start searching (0 to start |
141 | * from the beginning of the array). | |
7c673cae | 142 | * |
11fdf7f2 | 143 | * \return the index of the first set bit. If no bits are set, returns UINT32_MAX. |
7c673cae FG |
144 | */ |
145 | uint32_t spdk_bit_array_find_first_set(const struct spdk_bit_array *ba, uint32_t start_bit_index); | |
146 | ||
147 | /** | |
148 | * Find the index of the first cleared bit in the array. | |
149 | * | |
150 | * \param ba The bit array to search. | |
11fdf7f2 TL |
151 | * \param start_bit_index The bit index from which to start searching (0 to start |
152 | * from the beginning of the array). | |
7c673cae | 153 | * |
11fdf7f2 | 154 | * \return the index of the first cleared bit. If no bits are cleared, returns UINT32_MAX. |
7c673cae FG |
155 | */ |
156 | uint32_t spdk_bit_array_find_first_clear(const struct spdk_bit_array *ba, uint32_t start_bit_index); | |
157 | ||
11fdf7f2 TL |
158 | /** |
159 | * Count the number of set bits in the array. | |
160 | * | |
161 | * \param ba The bit array to search. | |
162 | * | |
163 | * \return the number of bits set in the array. | |
164 | */ | |
165 | uint32_t spdk_bit_array_count_set(const struct spdk_bit_array *ba); | |
166 | ||
167 | /** | |
168 | * Count the number of cleared bits in the array. | |
169 | * | |
170 | * \param ba The bit array to search. | |
171 | * | |
172 | * \return the number of bits cleared in the array. | |
173 | */ | |
174 | uint32_t spdk_bit_array_count_clear(const struct spdk_bit_array *ba); | |
175 | ||
7c673cae FG |
176 | #ifdef __cplusplus |
177 | } | |
178 | #endif | |
179 | ||
180 | #endif |