idxres_fl.h (12707B)
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_FL_ 10 #define _SHR_IDXRES_FL_ 11 12 #include <sal/types.h> 13 14 typedef uint32 shr_idxres_element_t; 15 16 struct _shr_idxres_list_s; 17 18 typedef struct _shr_idxres_list_s *shr_idxres_list_handle_t; 19 20 /* 21 * Function 22 * shr_idxres_list_create_scaled 23 * Purpose 24 * Create a banked free list (with element scaling) 25 * Parameters 26 * (out) shr_idxres_list_handle_t *list = place to put list handle 27 * (in) shr_idxres_element_t first = number of first entry to manage 28 * (in) shr_idxres_element_t last = number of last entry to manage 29 * (in) shr_idxres_element_t validLow = low valid entry value 30 * (in) shr_idxres_element_t validHigh = high valid entry value 31 * (in) shr_idxres_element_t scale = scaling factor 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 * Zero for scale disables scaling function. Scaling factor applies to 43 * all parameters if it is enabled. Caller must ensure the size of the 44 * range is an integral multiple of scaling factor. 45 */ 46 extern int 47 shr_idxres_list_create_scaled(shr_idxres_list_handle_t *list, 48 shr_idxres_element_t first, 49 shr_idxres_element_t last, 50 shr_idxres_element_t valid_low, 51 shr_idxres_element_t valid_high, 52 shr_idxres_element_t scale, 53 char *name); 54 55 /* 56 * Function 57 * shr_idxres_list_create 58 * Purpose 59 * Create a banked free list 60 * Parameters 61 * (out) shr_idxres_list_handle_t *list = place to put list handle 62 * (in) shr_idxres_element_t first = number of first entry to manage 63 * (in) shr_idxres_element_t last = number of last entry to manage 64 * (in) shr_idxres_element_t validLow = low valid entry value 65 * (in) shr_idxres_element_t validHigh = high valid entry value 66 * (in) char *name = name for the list (used for sal_alloc) 67 * Returns 68 * bcm_error_t = BCM_E_NONE if list created successfully 69 * BCM_E_* as appropriate otherwise 70 * Notes 71 * The validLow and validHigh values are used to specify the valid range 72 * of entries for querying 'free/used' status of an entry; any value not 73 * in this range is considered an invalid argument, but values that are 74 * not between first and last will be permanently 'used' and not allowed 75 * by the free operation nor ever provided by the allocate operation. 76 */ 77 extern int 78 shr_idxres_list_create(shr_idxres_list_handle_t *list, 79 shr_idxres_element_t first, 80 shr_idxres_element_t last, 81 shr_idxres_element_t valid_low, 82 shr_idxres_element_t valid_high, 83 char *name); 84 85 /* 86 * Function 87 * shr_idxres_list_destroy 88 * Purpose 89 * Destroy a list 90 * Parameters 91 * (in) shr_idxres_list_handle_t list = the list handle 92 * Returns 93 * bcm_error_t = BCM_E_NONE if list created successfully 94 * BCM_E_* as appropriate otherwise 95 * Notes 96 * This destroys the list, but does not claim the semaphore first, so the 97 * caller must take care not to destroy the list while it's being used. 98 * It is possible that some OSes will not permit the destruction of a lock 99 * that is in use, so maybe that at least helps. It is also willing to 100 * destroy the list even if there are still allocated entries. 101 */ 102 extern int 103 shr_idxres_list_destroy(shr_idxres_list_handle_t list); 104 105 /* 106 * Function 107 * shr_idxres_list_alloc 108 * Purpose 109 * Allocate the next available element from a list 110 * Parameters 111 * (in) shr_idxres_list_handle_t list = list from which to allocate 112 * (out) shr_idxres_element_t *element = where to put alloced elem num 113 * Returns 114 * bcm_error_t = BCM_E_NONE if element allocated successfully 115 * BCM_E_* as appropriate otherwise 116 * Notes 117 */ 118 extern int 119 shr_idxres_list_alloc(shr_idxres_list_handle_t list, 120 shr_idxres_element_t *element); 121 122 /* 123 * Function 124 * shr_idxres_list_alloc_set 125 * Purpose 126 * Allocate the next available element from a list 127 * Parameters 128 * (in) shr_idxres_list_handle_t list = list from which to allocate 129 * (in) shr_idxres_element_t count = number of elements to allocate 130 * (out) shr_idxres_element_t *elements = ptr to array for alloced elems 131 * (out) shr_idxres_element_t *done = ptr for number of successful allocs 132 * Returns 133 * bcm_error_t = BCM_E_NONE if element allocated successfully 134 * BCM_E_* as appropriate otherwise 135 * Notes 136 * This uses the same function as shr_idxres_list_alloc, except that it 137 * verifies that there are enough elements free to fulfill the request 138 * before it tries to allocate any of them. It is still possible that an 139 * error prevents completion, however, so if the result is not success, 140 * the done value must be verified (and any elements that were done that 141 * can not be used must be freed). 142 * The set is NOT guaranteed to be contiguous. 143 */ 144 extern int 145 shr_idxres_list_alloc_set(shr_idxres_list_handle_t list, 146 shr_idxres_element_t count, 147 shr_idxres_element_t *elements, 148 shr_idxres_element_t *done); 149 150 /* 151 * Function 152 * shr_idxres_list_free 153 * Purpose 154 * Free an element back to a list 155 * Parameters 156 * (in) shr_idxres_list_handle_t list = list from which elem was alloced 157 * (in) shr_idxres_element_t entry = element number to free 158 * Returns 159 * bcm_error_t = BCM_E_NONE if element freed successfully 160 * BCM_E_* as appropriate otherwise 161 * Notes 162 * Freeing an entry already in the list is checked, as well as freeing an 163 * entry outside of the list-managed range. 164 */ 165 extern int 166 shr_idxres_list_free(shr_idxres_list_handle_t list, 167 shr_idxres_element_t element); 168 169 /* 170 * Function 171 * shr_idxres_list_free_set 172 * Purpose 173 * Free a set of elements back to a list 174 * Parameters 175 * (in) shr_idxres_list_handle_t list = list to which to free 176 * (in) shr_idxres_element_t count = number of elements to free 177 * (in) shr_idxres_element_t *elements = ptr to array for elems to free 178 * (out) shr_idxres_element_t *done = ptr for number of successful frees 179 * Returns 180 * bcm_error_t = BCM_E_NONE if element allocated successfully 181 * BCM_E_* as appropriate otherwise 182 * Notes 183 * This uses the same function as shr_idxres_list_free. It is possible 184 * that an error prevents completion, so if the result is not success, the 185 * done value must be verified (and any elements that were not done that 186 * can not be reused must still be freed). Elements can be freed using 187 * either free call, no matter which alloc method was used to obtain them. 188 */ 189 extern int 190 shr_idxres_list_free_set(shr_idxres_list_handle_t list, 191 shr_idxres_element_t count, 192 shr_idxres_element_t *elements, 193 shr_idxres_element_t *done); 194 195 /* 196 * Function 197 * shr_idxres_list_state 198 * Purpose 199 * Get status of the list itself 200 * Parameters 201 * (in) shr_idxres_list_handle_t list = list to check 202 * (out) shr_idxres_element_t *first = buffer for first value 203 * (out) shr_idxres_element_t *last = buffer for last value 204 * (out) shr_idxres_element_t *valid_low = buffer for valid_low value 205 * (out) shr_idxres_element_t *valid_high = buffer for valid_high value 206 * (out) shr_idxres_element_t *free_count = buffer for free_count value 207 * (out) shr_idxres_element_t *alloc_count = buffer for alloc_count value 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 */ 217 extern int 218 shr_idxres_list_state(shr_idxres_list_handle_t list, 219 shr_idxres_element_t *first, 220 shr_idxres_element_t *last, 221 shr_idxres_element_t *valid_low, 222 shr_idxres_element_t *valid_high, 223 shr_idxres_element_t *free_count, 224 shr_idxres_element_t *alloc_count); 225 226 /* 227 * Function 228 * shr_idxres_list_state_scaled 229 * Purpose 230 * Get status of the list itself 231 * Parameters 232 * (in) shr_idxres_list_handle_t list = list to check 233 * (out) shr_idxres_element_t *first = buffer for first value 234 * (out) shr_idxres_element_t *last = buffer for last value 235 * (out) shr_idxres_element_t *valid_low = buffer for valid_low value 236 * (out) shr_idxres_element_t *valid_high = buffer for valid_high value 237 * (out) shr_idxres_element_t *free_count = buffer for free_count value 238 * (out) shr_idxres_element_t *alloc_count = buffer for alloc_count value 239 * (out) shr_idxres_element_t *scale = buffer for scale value 240 * Returns 241 * BCM_E_NONE if successful 242 * BCM_E_* as appropriate otherwise 243 * Notes 244 * If you don't want to fetch a specific attribute of the list, pass 245 * NULL for the pointer to that attribute's location. 246 * There is no set function for these items; most are set at creation of 247 * list and the others are current state of list. 248 */ 249 extern int 250 shr_idxres_list_state_scaled(shr_idxres_list_handle_t list, 251 shr_idxres_element_t *first, 252 shr_idxres_element_t *last, 253 shr_idxres_element_t *valid_low, 254 shr_idxres_element_t *valid_high, 255 shr_idxres_element_t *free_count, 256 shr_idxres_element_t *alloc_count, 257 shr_idxres_element_t *scale); 258 259 /* 260 * Function 261 * shr_idxres_list_elem_state 262 * Purpose 263 * See if an element is currently in use 264 * Parameters 265 * (in) shr_idxres_list_handle_t list = list to check 266 * (in) shr_idxres_element_t entry = element number to check 267 * Returns 268 * bcm_error_t = BCM_E_EXISTS if element is in use 269 * BCM_E_NOT_FOUND if element is not in use 270 * BCM_E_* as appropriate otherwise 271 * Notes 272 * This function ALWAYS returns an error (never BCM_E_NONE). 273 */ 274 extern int 275 shr_idxres_list_elem_state(shr_idxres_list_handle_t list, 276 shr_idxres_element_t element); 277 278 /* 279 * Function 280 * shr_idxres_list_reserve 281 * Purpose 282 * Reserve a range of elements in a list 283 * Parameters 284 * (in) shr_idxres_list_handle_t list = list handle 285 * (in) shr_idxres_element_t first = first entry to reserve 286 * (in) shr_idxres_element_t last = last entry to reserve 287 * Returns 288 * bcm_error_t = BCM_E_NONE if elements reserved successfully 289 * BCM_E_* as appropriate otherwise 290 * Notes 291 * This is truly an inefficient way to manage top and bottom reservations 292 * unless they are not known at list creation time, as this does not do 293 * anything to adjust the physical size of the list's workspace; it merely 294 * takes the requested range out of the available elements. 295 * Elements reserved in this manner can be returned using free. 296 */ 297 extern int 298 shr_idxres_list_reserve(shr_idxres_list_handle_t list, 299 shr_idxres_element_t first, 300 shr_idxres_element_t last); 301 302 #endif /* ndef _SHR_IDXRES_FL_ */ 303