1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2016 Intel Corporation. 3 * All rights reserved. 4 */ 5 6 /** \file 7 * Bit array data structure 8 */ 9 10 #ifndef SPDK_BIT_ARRAY_H 11 #define SPDK_BIT_ARRAY_H 12 13 #include "spdk/stdinc.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * Variable-length bit array. 21 */ 22 struct spdk_bit_array; 23 24 /** 25 * Return the number of bits that a bit array is currently sized to hold. 26 * 27 * \param ba Bit array to query. 28 * 29 * \return the number of bits. 30 */ 31 uint32_t spdk_bit_array_capacity(const struct spdk_bit_array *ba); 32 33 /** 34 * Create a bit array. 35 * 36 * \param num_bits Number of bits that the bit array is sized to hold. 37 * 38 * All bits in the array will be cleared. 39 * 40 * \return a pointer to the new bit array. 41 */ 42 struct spdk_bit_array *spdk_bit_array_create(uint32_t num_bits); 43 44 /** 45 * Free a bit array and set the pointer to NULL. 46 * 47 * \param bap Bit array to free. 48 */ 49 void spdk_bit_array_free(struct spdk_bit_array **bap); 50 51 /** 52 * Create or resize a bit array. 53 * 54 * To create a new bit array, pass a pointer to a spdk_bit_array pointer that is 55 * NULL for bap. 56 * 57 * The bit array will be sized to hold at least num_bits. 58 * 59 * If num_bits is smaller than the previous size of the bit array, 60 * any data beyond the new num_bits size will be cleared. 61 * 62 * If num_bits is larger than the previous size of the bit array, 63 * any data beyond the old num_bits size will be cleared. 64 * 65 * \param bap Bit array to create/resize. 66 * \param num_bits Number of bits that the bit array is sized to hold. 67 * 68 * \return 0 on success, negative errno on failure. 69 */ 70 int spdk_bit_array_resize(struct spdk_bit_array **bap, uint32_t num_bits); 71 72 /** 73 * Get the value of a bit from the bit array. 74 * 75 * If bit_index is beyond the end of the current size of the bit array, this 76 * function will return false (i.e. bits beyond the end of the array are implicitly 0). 77 * 78 * \param ba Bit array to query. 79 * \param bit_index The index of a bit to query. 80 * 81 * \return the value of a bit from the bit array on success, or false on failure. 82 */ 83 bool spdk_bit_array_get(const struct spdk_bit_array *ba, uint32_t bit_index); 84 85 /** 86 * Set (to 1) a bit in the bit array. 87 * 88 * If bit_index is beyond the end of the bit array, this function will return -EINVAL. 89 * 90 * \param ba Bit array to set a bit. 91 * \param bit_index The index of a bit to set. 92 * 93 * \return 0 on success, negative errno on failure. 94 */ 95 int spdk_bit_array_set(struct spdk_bit_array *ba, uint32_t bit_index); 96 97 /** 98 * Clear (to 0) a bit in the bit array. 99 * 100 * If bit_index is beyond the end of the bit array, no action is taken. Bits 101 * beyond the end of the bit array are implicitly 0. 102 * 103 * \param ba Bit array to clear a bit. 104 * \param bit_index The index of a bit to clear. 105 */ 106 void spdk_bit_array_clear(struct spdk_bit_array *ba, uint32_t bit_index); 107 108 /** 109 * Find the index of the first set bit in the array. 110 * 111 * \param ba The bit array to search. 112 * \param start_bit_index The bit index from which to start searching (0 to start 113 * from the beginning of the array). 114 * 115 * \return the index of the first set bit. If no bits are set, returns UINT32_MAX. 116 */ 117 uint32_t spdk_bit_array_find_first_set(const struct spdk_bit_array *ba, uint32_t start_bit_index); 118 119 /** 120 * Find the index of the first cleared bit in the array. 121 * 122 * \param ba The bit array to search. 123 * \param start_bit_index The bit index from which to start searching (0 to start 124 * from the beginning of the array). 125 * 126 * \return the index of the first cleared bit. If no bits are cleared, returns UINT32_MAX. 127 */ 128 uint32_t spdk_bit_array_find_first_clear(const struct spdk_bit_array *ba, uint32_t start_bit_index); 129 130 /** 131 * Count the number of set bits in the array. 132 * 133 * \param ba The bit array to search. 134 * 135 * \return the number of bits set in the array. 136 */ 137 uint32_t spdk_bit_array_count_set(const struct spdk_bit_array *ba); 138 139 /** 140 * Count the number of cleared bits in the array. 141 * 142 * \param ba The bit array to search. 143 * 144 * \return the number of bits cleared in the array. 145 */ 146 uint32_t spdk_bit_array_count_clear(const struct spdk_bit_array *ba); 147 148 /** 149 * Store bitmask from bit array. 150 * 151 * \param ba Bit array. 152 * \param mask Destination mask. Mask and bit array capacity must be equal. 153 */ 154 void spdk_bit_array_store_mask(const struct spdk_bit_array *ba, void *mask); 155 156 /** 157 * Load bitmask to bit array. 158 * 159 * \param ba Bit array. 160 * \param mask Source mask. Mask and bit array capacity must be equal. 161 */ 162 void spdk_bit_array_load_mask(struct spdk_bit_array *ba, const void *mask); 163 164 /** 165 * Clear (to 0) bit array bitmask. 166 * 167 * \param ba Bit array. 168 */ 169 void spdk_bit_array_clear_mask(struct spdk_bit_array *ba); 170 171 #ifdef __cplusplus 172 } 173 #endif 174 175 #endif 176