1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2020 Intel Corporation. 3 * All rights reserved. 4 */ 5 6 /** \file 7 * Bit pool data structure 8 */ 9 10 #ifndef SPDK_BIT_POOL_H 11 #define SPDK_BIT_POOL_H 12 13 #include "spdk/stdinc.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 struct spdk_bit_pool; 20 struct spdk_bit_array; 21 22 /** 23 * Return the number of bits that a bit pool is currently sized to hold. 24 * 25 * \param pool Bit pool to query. 26 * 27 * \return the number of bits. 28 */ 29 uint32_t spdk_bit_pool_capacity(const struct spdk_bit_pool *pool); 30 31 /** 32 * Create a bit pool. 33 * 34 * All bits in the pool will be available for allocation. 35 * 36 * \param num_bits Number of bits that the bit pool is sized to hold. 37 * 38 * \return a pointer to the new bit pool. 39 */ 40 struct spdk_bit_pool *spdk_bit_pool_create(uint32_t num_bits); 41 42 /** 43 * Create a bit pool from an existing spdk_bit_array. 44 * 45 * The starting state of the bit pool will be specified by the state 46 * of the specified spdk_bit_array. 47 * 48 * The new spdk_bit_pool will consume the spdk_bit_array and assumes 49 * responsibility for freeing it. The caller should not use the 50 * spdk_bit_array after this function returns. 51 * 52 * \param array spdk_bit_array representing the starting state of the new bit pool. 53 * 54 * \return a pointer to the new bit pool, NULL if one could not be created (in which 55 * case the caller maintains responsibility for the spdk_bit_array) 56 */ 57 struct spdk_bit_pool *spdk_bit_pool_create_from_array(struct spdk_bit_array *array); 58 59 /** 60 * Free a bit pool and set the pointer to NULL. 61 * 62 * \param pool Bit pool to free. 63 */ 64 void spdk_bit_pool_free(struct spdk_bit_pool **pool); 65 66 /** 67 * Create or resize a bit pool. 68 * 69 * To create a new bit pool, pass a pointer to a spdk_bit_pool pointer that is 70 * NULL. 71 * 72 * The bit pool will be sized to hold at least num_bits. 73 * 74 * If num_bits is larger than the previous size of the bit pool, 75 * the new bits will all be available for future allocations. 76 * 77 * \param pool Bit pool to create/resize. 78 * \param num_bits Number of bits that the bit pool is sized to hold. 79 * 80 * \return 0 on success, negative errno on failure. 81 */ 82 int spdk_bit_pool_resize(struct spdk_bit_pool **pool, uint32_t num_bits); 83 84 /** 85 * Return whether the specified bit has been allocated from the bit pool. 86 * 87 * If bit_index is beyond the end of the current size of the bit pool, this 88 * function will return false (i.e. bits beyond the end of the pool cannot be allocated). 89 * 90 * \param pool Bit pool to query. 91 * \param bit_index The index of a bit to query. 92 * 93 * \return true if the bit has been allocated, false otherwise 94 */ 95 bool spdk_bit_pool_is_allocated(const struct spdk_bit_pool *pool, uint32_t bit_index); 96 97 /** 98 * Allocate a bit from the bit pool. 99 * 100 * \param pool Bit pool to allocate a bit from 101 * 102 * \return index of the allocated bit, UINT32_MAX if no free bits exist 103 */ 104 uint32_t spdk_bit_pool_allocate_bit(struct spdk_bit_pool *pool); 105 106 /** 107 * Free a bit back to the bit pool. 108 * 109 * Callers must not try to free a bit that has not been allocated, otherwise the 110 * pool may become corrupted without notification. Freeing a bit that has not 111 * been allocated will result in an assert in debug builds. 112 * 113 * \param pool Bit pool to place the freed bit 114 * \param bit_index The index of a bit to free. 115 */ 116 void spdk_bit_pool_free_bit(struct spdk_bit_pool *pool, uint32_t bit_index); 117 118 /** 119 * Count the number of bits allocated from the pool. 120 * 121 * \param pool The bit pool to count. 122 * 123 * \return the number of bits allocated from the pool. 124 */ 125 uint32_t spdk_bit_pool_count_allocated(const struct spdk_bit_pool *pool); 126 127 /** 128 * Count the number of free bits in the pool. 129 * 130 * \param pool The bit pool to count. 131 * 132 * \return the number of free bits in the pool. 133 */ 134 uint32_t spdk_bit_pool_count_free(const struct spdk_bit_pool *pool); 135 136 /** 137 * Store bitmask from bit pool. 138 * 139 * \param pool Bit pool. 140 * \param mask Destination mask. Mask and bit array pool must be equal. 141 */ 142 void spdk_bit_pool_store_mask(const struct spdk_bit_pool *pool, void *mask); 143 144 /** 145 * Load bitmask to bit pool. 146 * 147 * \param pool Bit pool. 148 * \param mask Source mask. Mask and bit array pool must be equal. 149 */ 150 void spdk_bit_pool_load_mask(struct spdk_bit_pool *pool, const void *mask); 151 152 /** 153 * Free all bits back into the bit pool. 154 * 155 * \param pool Bit pool. 156 */ 157 void spdk_bit_pool_free_all_bits(struct spdk_bit_pool *pool); 158 159 #ifdef __cplusplus 160 } 161 #endif 162 163 #endif 164