idxres_afl.h (14538B)
1 /* 2 * 3 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 4 * 5 * Copyright 2007-2019 Broadcom Inc. All rights reserved. 6 * 7 * Module: Indexed resource management, using banked lists 8 */ 9 #ifndef _SHR_IDXRES_AFL_ 10 #define _SHR_IDXRES_AFL_ 11 12 #include <sal/types.h> 13 14 typedef uint32 shr_aidxres_element_t; 15 16 struct _shr_aidxres_list_s; 17 18 typedef struct _shr_aidxres_list_s *shr_aidxres_list_handle_t; 19 20 /* 21 * Function 22 * shr_aidxres_list_create 23 * Purpose 24 * Create an aligned/contiguous_blocked banked free list 25 * Parameters 26 * (out) shr_aidxres_list_handle_t *list = place to put list handle 27 * (in) shr_aidxres_element_t first = number of first entry to manage 28 * (in) shr_aidxres_element_t last = number of last entry to manage 29 * (in) shr_aidxres_element_t validLow = low valid entry value 30 * (in) shr_aidxres_element_t validHigh = high valid entry value 31 * (in) shr_aidxres_element_t block_factor = max block power of two 32 * (in) char *name = name for the list (used for sal_alloc) 33 * Returns 34 * bcm_error_t = BCM_E_NONE if list created successfully 35 * BCM_E_* as appropriate otherwise 36 * Notes 37 * The validLow and validHigh values are used to specify the valid range 38 * of entries for querying 'free/used' status of an entry; any value not 39 * in this range is considered an invalid argument, but values that are 40 * not between first and last will be permanently 'used' and not allowed 41 * by the free operation nor ever provided by the allocate operation. 42 * The blocking factor is the actual power of two that is to be used when 43 * computing maximum block size. Blocks will be able to be manipulated up 44 * to 2^blocking_factor, but note that blocking_factor must be less than 45 * or equal to the number of bits used for bank index (so in 8b mode, this 46 * must be 7 or less, in 16b mode it must be 15 or less, and in 32b mode 47 * it must be 31 or less). 48 */ 49 extern int 50 shr_aidxres_list_create(shr_aidxres_list_handle_t *list, 51 shr_aidxres_element_t first, 52 shr_aidxres_element_t last, 53 shr_aidxres_element_t valid_low, 54 shr_aidxres_element_t valid_high, 55 shr_aidxres_element_t block_factor, 56 char *name); 57 58 /* 59 * Function 60 * shr_aidxres_list_destroy 61 * Purpose 62 * Destroy a list 63 * Parameters 64 * (in) shr_aidxres_list_handle_t list = the list handle 65 * Returns 66 * bcm_error_t = BCM_E_NONE if list created successfully 67 * BCM_E_* as appropriate otherwise 68 * Notes 69 * This destroys the list, but does not claim the semaphore first, so the 70 * caller must take care not to destroy the list while it's being used. 71 * It is possible that some OSes will not permit the destruction of a lock 72 * that is in use, so maybe that at least helps. It is also willing to 73 * destroy the list even if there are still allocated entries. 74 */ 75 extern int 76 shr_aidxres_list_destroy(shr_aidxres_list_handle_t list); 77 78 /* 79 * Function 80 * shr_aidxres_list_alloc 81 * Purpose 82 * Allocate the next available single element from a list 83 * Parameters 84 * (in) shr_aidxres_list_handle_t list = list from which to allocate 85 * (out) shr_aidxres_element_t *element = where to put alloced elem num 86 * Returns 87 * bcm_error_t = BCM_E_NONE if element allocated successfully 88 * BCM_E_* as appropriate otherwise 89 * Notes 90 * As for the idxres list alloc call, this returns *one* element. 91 */ 92 extern int 93 shr_aidxres_list_alloc(shr_aidxres_list_handle_t list, 94 shr_aidxres_element_t *element); 95 96 /* 97 * Function 98 * shr_aidxres_list_alloc_set 99 * Purpose 100 * Allocate a set of the next available single elements from a list 101 * Parameters 102 * (in) shr_aidxres_list_handle_t list = list from which to allocate 103 * (in) shr_aidxres_element_t count = number of elements to allocate 104 * (out) shr_aidxres_element_t *elements = ptr to array for alloced elems 105 * (out) shr_aidxres_element_t *done = ptr to number of successful allocs 106 * Returns 107 * bcm_error_t = BCM_E_NONE if element allocated successfully 108 * BCM_E_* as appropriate otherwise 109 * Notes 110 * This uses the same function as shr_idxres_list_alloc, except that it 111 * verifies that there are enough elements free to fulfill the request 112 * before it tries to allocate any of them. It is still possible that an 113 * error prevents completion, however, so if the result is not success, 114 * the done value must be verified (and any elements that were done that 115 * can not be used must be freed). 116 * The set is NOT guaranteed to be contiguous. 117 * The set consists of count *one* element blocks. 118 */ 119 extern int 120 shr_aidxres_list_alloc_set(shr_aidxres_list_handle_t list, 121 shr_aidxres_element_t count, 122 shr_aidxres_element_t *elements, 123 shr_aidxres_element_t *done); 124 125 /* 126 * Function 127 * shr_aidxres_list_alloc_block 128 * Purpose 129 * Allocate a block (of specified count) of elements from a list 130 * Parameters 131 * (in) shr_aidxres_list_handle_t list = list from which to allocate 132 * (in) shr_aidxres_element_t count = size of block, in elements 133 * (out) shr_aidxres_element_t *element = where to put alloced elem num 134 * Returns 135 * bcm_error_t = BCM_E_NONE if element allocated successfully 136 * BCM_E_* as appropriate otherwise 137 * Notes 138 * The block is guaranteed to be aligned to the next power of two into 139 * which it fits, and will be contiguous. 140 */ 141 extern int 142 shr_aidxres_list_alloc_block(shr_aidxres_list_handle_t list, 143 shr_aidxres_element_t count, 144 shr_aidxres_element_t *element); 145 146 /* 147 * Function 148 * shr_aidxres_list_free 149 * Purpose 150 * Free an element or block of elements back to a list 151 * Parameters 152 * (in) shr_aidxres_list_handle_t list = list from which elem was alloced 153 * (in) shr_aidxres_element_t element = element number to free 154 * (or first element in block) 155 * Returns 156 * bcm_error_t = BCM_E_NONE if element freed successfully 157 * BCM_E_* as appropriate otherwise 158 * Notes 159 * Freeing an entry already in the list is checked, as well as freeing an 160 * entry outside of the list-managed range. Elements can be freed using 161 * either free call, no matter which alloc call was used to obtain them. 162 */ 163 extern int 164 shr_aidxres_list_free(shr_aidxres_list_handle_t list, 165 shr_aidxres_element_t element); 166 167 /* 168 * Function 169 * shr_aidxres_list_free_set 170 * Purpose 171 * Free a set of elements back to a list 172 * Parameters 173 * (in) shr_aidxres_list_handle_t list = list to which to free 174 * (in) shr_aidxres_element_t count = number of elements to free 175 * (in) shr_aidxres_element_t *elements = ptr to array for elems to free 176 * (out) shr_aidxres_element_t *done = ptr to number of successful frees 177 * Returns 178 * bcm_error_t = BCM_E_NONE if element allocated successfully 179 * BCM_E_* as appropriate otherwise 180 * Notes 181 * This uses the same function as shr_idxres_list_free. It is possible 182 * that an error prevents completion, so if the result is not success, the 183 * done value must be verified (and any elements that were not done that 184 * can not be reused must still be freed). Elements can be freed using 185 * either free call, no matter which alloc method was used to obtain them. 186 */ 187 extern int 188 shr_aidxres_list_free_set(shr_aidxres_list_handle_t list, 189 shr_aidxres_element_t count, 190 shr_aidxres_element_t *elements, 191 shr_aidxres_element_t *done); 192 193 /* 194 * Function 195 * shr_idxres_list_state 196 * Purpose 197 * Get status of the list itself 198 * Parameters 199 * (in) shr_aidxres_list_handle_t list = list to check 200 * (out) shr_aidxres_element_t *first = buffer for first value 201 * (out) shr_aidxres_element_t *last = buffer for last value 202 * (out) shr_aidxres_element_t *valid_low = buffer for valid_low value 203 * (out) shr_aidxres_element_t *valid_high = buffer for valid_high value 204 * (out) shr_aidxres_element_t *free_count = buffer for free_count value 205 * (out) shr_aidxres_element_t *alloc_count = buffer for alloc_count value 206 * (out) shr_aidxres_element_t *largest_free = buff for largest free value 207 * (out) shr_aidxres_element_t *block_factor = buffer for block factor val 208 * Returns 209 * bcm_error_t = BCM_E_NONE if successful 210 * BCM_E_* as appropriate otherwise 211 * Notes 212 * If you don't want to fetch a specific attribute of the list, pass 213 * NULL for the pointer to that attribute's location. 214 * There is no set function for these items; most are set at creation of 215 * list and the others are current state of list. 216 * Largest free is the largest number of elements that a block can contain 217 * and still have the alloc request fulfilled on this list. 218 */ 219 extern int 220 shr_aidxres_list_state(shr_aidxres_list_handle_t list, 221 shr_aidxres_element_t *first, 222 shr_aidxres_element_t *last, 223 shr_aidxres_element_t *valid_low, 224 shr_aidxres_element_t *valid_high, 225 shr_aidxres_element_t *free_count, 226 shr_aidxres_element_t *alloc_count, 227 shr_aidxres_element_t *largest_free, 228 shr_aidxres_element_t *block_factor); 229 230 /* 231 * Function 232 * shr_aidxres_list_elem_state 233 * Purpose 234 * See if an element is currently in use 235 * Parameters 236 * (in) shr_aidxres_list_handle_t list = list to check 237 * (in) shr_aidxres_element_t element = element number to check 238 * Returns 239 * bcm_error_t = BCM_E_EXISTS if element is in use 240 * BCM_E_NOT_FOUND if element is not in use 241 * BCM_E_* as appropriate otherwise 242 * Notes 243 * This function ALWAYS returns an error (never BCM_E_NONE). 244 */ 245 extern int 246 shr_aidxres_list_elem_state(shr_aidxres_list_handle_t list, 247 shr_aidxres_element_t element); 248 249 /* 250 * Function 251 * shr_aidxres_list_block_state 252 * Purpose 253 * See if an element is currently in use 254 * Parameters 255 * (in) shr_aidxres_list_handle_t list = list to check 256 * (in) shr_aidxres_element_t element = element number to check 257 * (in) shr_aidxres_element_t size = elements in expected block 258 * Returns 259 * BCM_E_EMPTY if none of the elements are in use 260 * BCM_E_FULL if all of the elements are in use 261 * BCM_E_CONFIG if elements are in use but block(s) do not match 262 * BCM_E_EXISTS if some of the elements are in use but not all of them 263 * BCM_E_PARAM if any of the elements is not valid 264 * BCM_E_* as appropriate otherwise 265 * Notes 266 * This function ALWAYS returns an error (never BCM_E_NONE). 267 */ 268 int 269 shr_aidxres_list_block_state(shr_aidxres_list_handle_t list, 270 shr_aidxres_element_t element, 271 shr_aidxres_element_t size); 272 273 /* 274 * Function 275 * shr_aidxres_list_reserve 276 * Purpose 277 * Reserve a range of elements in a list 278 * Parameters 279 * (in) shr_aidxres_list_handle_t list = list handle 280 * (in) shr_aidxres_element_t first = first entry to reserve 281 * (in) shr_aidxres_element_t last = last entry to reserve 282 * Returns 283 * bcm_error_t = BCM_E_NONE if elements reserved successfully 284 * BCM_E_* as appropriate otherwise 285 * Notes 286 * This is truly an inefficient way to manage top and bottom reservations 287 * unless they are not known at list creation time, as this does not do 288 * anything to adjust the physical size of the list's workspace; it merely 289 * takes the requested range out of the available elements. 290 * Elements reserved in this manner can be returned using free; they are 291 * allocated as elements instead of blocks. 292 */ 293 extern int 294 shr_aidxres_list_reserve(shr_aidxres_list_handle_t list, 295 shr_aidxres_element_t first, 296 shr_aidxres_element_t last); 297 298 /* 299 * Function 300 * shr_aidxres_list_reserve_block 301 * Purpose 302 * Reserve a block in a list 303 * Parameters 304 * (in) shr_aidxres_list_handle_t list = list handle 305 * (in) shr_aidxres_element_t first = first element in block to reserve 306 * (in) shr_aidxres_element_t count = number of elements in block 307 * Returns 308 * bcm_error_t = BCM_E_NONE if elements reserved successfully 309 * BCM_E_* as appropriate otherwise 310 * Notes 311 * This is truly an inefficient way to manage top and bottom reservations 312 * unless they are not known at list creation time, as this does not do 313 * anything to adjust the physical size of the list's workspace; it merely 314 * takes the requested range out of the available elements. 315 * Elements reserved in this manner can be returned using free; they are 316 * allocated a a single block. 317 * The block to be reserved must satisfy all allocation rules for blocks 318 * (for example, alignment and size) that apply to the list. 319 */ 320 extern int 321 shr_aidxres_list_reserve_block(shr_aidxres_list_handle_t list, 322 shr_aidxres_element_t first, 323 shr_aidxres_element_t count); 324 325 /* 326 * This variable controls sanity checking behaviour, assuming the feature is 327 * enabled in the idxres_afl.c file. 328 * 329 * Note that CREATE only checks on RETURN; there is no check to perform for 330 * CREATE on ENTRY. There is no point in doing checks before DESTROY. 331 */ 332 extern uint32 _aidxres_sanity_settings; 333 #define _AIDXRES_SANITY_POINT_ENTRY 0x00000001 334 #define _AIDXRES_SANITY_POINT_RETURN 0x00000002 335 #define _AIDXRES_SANITY_FUNC_ALLOC 0x00000010 336 #define _AIDXRES_SANITY_FUNC_FREE 0x00000020 337 #define _AIDXRES_SANITY_FUNC_CREATE 0x00000040 338 #define _AIDXRES_SANITY_DUMP_FAULTS 0x00010000 339 340 #endif /* ndef _SHR_IDXRES_AFL_ */ 341