shr_resmgr.h (102794B)
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 * File: allocator.h 8 * Purpose: Internal routines to the BCM library for allocating 9 * gu2 resources. 10 */ 11 12 #ifndef _SHR_RESMGR_H_ 13 #define _SHR_RESMGR_H_ 14 15 #include <sal/types.h> 16 #include <shared/idxres_afl.h> 17 #include <shared/idxres_fl.h> 18 #include <shared/idxres_mdb.h> 19 #include <shared/shr_res_bitmap.h> 20 #include <shared/shr_res_tag_bitmap.h> 21 #include <bcm/types.h> 22 23 /* 24 * WARNING: No locking is performed here (unless it is implied by the 25 * underlying allocator) for any of the shr_mres_* calls. The caller must 26 * ensure that it is not possible for calls using a specific resource instance 27 * to occur in parallel or timesliced with other calls against the same 28 * specific resource instance. 29 * 30 * WARNING: No locking is performed here (unless it is implied by the 31 * underlying allocator) for any of the shr_res_* calls, except for the case 32 * of shr_res_init and shr_res_detach. For other shr_res_* calls, the caller 33 * must ensure that it is not possible for calls against a specific unit to 34 * occur in parallel or timesliced with other calls against the same unit. 35 * 36 * NOTE: The actual mutual exclusion requirement is at the pool granularity, 37 * but since it is possible to have different types share the same pool, and 38 * the caller is not required to know the exact mapping, it can be dangerous 39 * for the caller to assume locking by type is sufficient. Since allocation 40 * is managed by type, which is mapped internally to pool, the general 41 * assumption of complete exclusivity is safer. 42 * 43 * Other than the *_dump calls, the shr_mres_* calls and the shr_res_* calls 44 * are designed to function in parallel or timesliced as long as there are no 45 * multiple concurrent invocations against the same unit or handle. The 46 * *_dump calls use bsl_print, and suffer from any threading or timeslicing 47 * issues that might imply about concurrent dumps. 48 */ 49 50 /* 51 * Flags supported by the allocation system for each allocation. If any of 52 * these are provided as group flags, they are automatically applied to the 53 * entire group, whether the individual flags include them or not. 54 * 55 * SHR_RES_ALLOC_WITH_ID indicates that the element ID is provided by the 56 * caller, and that specific element (or the specified block starting at that 57 * element) is being requested. The allocation must fail if the requested 58 * element/block is invalid or already in use. 59 * 60 * SHR_RES_ALLOC_ALIGN_ZERO indicates that the _align_ allocators should align 61 * the block of elements with respect to zero, and not relative to the 62 * lowest element in the underlying pool. 63 * 64 * SHR_RES_ALLOC_REPLACE is used with SHR_RES_ALLOC_WITH_ID to indicate that 65 * the intent is to replace an existing block. Note the blocks must be of the 66 * same size (and tag if applicable) -- this does not 'realloc' a block; it 67 * only verifies that the block already exists as per the alloc request. 68 */ 69 #define SHR_RES_ALLOC_SINGLE_FLAGS 0x00000007 70 #define SHR_RES_ALLOC_WITH_ID 0x00000001 71 #define SHR_RES_ALLOC_ALIGN_ZERO 0x00000002 72 #define SHR_RES_ALLOC_REPLACE 0x00000004 73 74 /* 75 * Flags supported by the allocation system for group allocation. Note these 76 * are specifically for the group call itself, not the individual blocks 77 * within the group call. 78 * 79 * SHR_RES_ALLOC_GROUP_ATOMIC indicates that the allocation is to be 80 * considered atomic -- if there is any failure, back out all of it rather 81 * than stopping at the failure point. This can only be applied to the 82 * allocation call. There is no support to undo frees and aborting a check 83 * based upon the result being other than BCM_E_NONE makes no sense because 84 * check should always return some other result code. 85 */ 86 #define SHR_RES_ALLOC_GROUP_FLAGS 0x00010000 87 #define SHR_RES_ALLOC_GROUP_ATOMIC 0x00010000 88 89 /* 90 * For optimisation, there is a version of free that returns whether the last 91 * element of a type or pool has been freed by that free. 92 * 93 * SHR_RES_FREED_TYPE_LAST_ELEM indicates that the last in-use element of a 94 * type was freed by the free call (or if the free call failed, that there 95 * were no elements of that type in use). 96 * 97 * SHR_RES_FREED_POOL_LAST_ELEM indicates that the last in-use element of a 98 * pool was freed by the free call (or if the free call failed, that there 99 * were no elements of that pool in use). 100 */ 101 #define SHR_RES_FREED_TYPE_LAST_ELEM 0x00000001 102 #define SHR_RES_FREED_POOL_LAST_ELEM 0x00000002 103 104 /* 105 * This enum defines the supported allocation mechanisms. Each one has some 106 * of its own advantages and disadvantages. See the notes for each one if you 107 * need details to choose which might be best for a particular resource pool. 108 */ 109 typedef enum shr_res_allocator_e { 110 SHR_RES_ALLOCATOR_BITMAP = 0, /* bitmap based allocator */ 111 SHR_RES_ALLOCATOR_TAGGED_BITMAP, /* bitmap based allocator with tags */ 112 SHR_RES_ALLOCATOR_IDXRES, /* indexed resource, freelist */ 113 SHR_RES_ALLOCATOR_AIDXRES, /* indexed resource, aligned freelist */ 114 SHR_RES_ALLOCATOR_MDB, /* indexed resource, mdb */ 115 SHR_RES_ALLOCATOR_COUNT /* last one indicates how many, not valid item */ 116 } shr_res_allocator_t; 117 118 /* 119 * This struct contains the extra arguments needed to configure a resource 120 * pool to be managed by the idxres manager. 121 * 122 * The scaling factor is the number of elements of the resource that make up 123 * the smallest usable grain of the resources. Normally it would be 1. 124 */ 125 typedef struct shr_res_idxres_extras_s { 126 int scaling_factor; /* scaling factor for the resource */ 127 } shr_res_idxres_extras_t; 128 129 /* 130 * This struct contains the extra arguments needed to configure a resource 131 * pool to be managed by the aidxres manager. 132 */ 133 typedef struct shr_res_aidxres_extras_s { 134 int blocking_factor; /* power of two for largest block to support */ 135 } shr_res_aidxres_extras_t; 136 137 /* 138 * This struct contains the extra arguments needed to configure a resource 139 * pool to be managed by the mdb manager. Note that many features of the mdb 140 * manager are not exposed through this abstraction. 141 * 142 * Note that all of the rules for mdb must also be followed, inclduing the 143 * free lists include an implied free list of block size 1, and all of the 144 * other free lists must be of increasing block size. User lists are not 145 * exposed through this abstraction (and so will not be allocated), and the 146 * assumption is non-locking so the caller must provide access exclusion. 147 */ 148 typedef struct shr_res_mdb_extras_s { 149 shr_mdb_elem_bank_index_t bank_size; /* elements in a single bank */ 150 shr_mdb_elem_bank_index_t free_lists; /* additional free lists */ 151 shr_mdb_elem_bank_index_t free_counts[15]; /* free elem per blk per list */ 152 } shr_res_mdb_extras_t; 153 154 /* 155 * This struct contains the extra arguments needed to configure a resource 156 * pool to be managed by the tagged_bitmap allocator. 157 */ 158 typedef struct shr_res_tagged_bitmap_extras_s { 159 int tag_length; /* tag length in bytes */ 160 int grain_size; /* number of elements per grain */ 161 } shr_res_tagged_bitmap_extras_t; 162 163 /* 164 * When fetching additional data about a pool (not available with 'pool_get'), 165 * the caller provides one of this structure to be filled in. 166 */ 167 typedef struct shr_res_pool_info_s { 168 int used; 169 int free; 170 } shr_res_pool_info_t; 171 172 /* 173 * When fetching additional data about a pool (not available with 'pool_get'), 174 * the caller provides one of this structure to be filled in. 175 * 176 * Since more than one type can be using a single pool, and each type can use 177 * a different number of elements of the underlying pool per each of its own 178 * elements, a value for 'free' would require some possibly considerable 179 * effort to figure out how many nonoverlapping requests could be made for the 180 * number of pool elements that one type element represents. It is simpler 181 * and reasonably consistent to not include it. 182 */ 183 typedef struct shr_res_type_info_s { 184 int used; 185 } shr_res_type_info_t; 186 187 /* 188 * This describes how a single resource maps to an underlying pool. 189 * 190 * resPoolId is the ID of the resource pool on this unit from which this 191 * resource is drawn. 192 * 193 * resElemSize is the number of elements in the specified resource pool that 194 * must be taken to make a single element of this resource. Basically, any 195 * alloc/free of this resource will multiply the number of elements by this 196 * value to determine how many to alloc/free of the underlying pool. 197 * 198 * name is a string that names this resource. It is used only for diagnostic 199 * purposes. Internally, the provided name will be copied to the same cell as 200 * the structure, so the name array is really variable length. 201 */ 202 typedef struct _shr_res_type_desc_s { 203 int resPoolId; /* unit specific resource pool ID */ 204 int resElemSize; /* how many elems of this pool per this res */ 205 int refCount; /* number of elements allocated currently */ 206 char name[1]; /* descriptive name (for diagnostics) */ 207 } _shr_res_type_desc_t; 208 209 /* 210 * This describes a single resource pool on a unit. 211 * 212 * resManagerType is the ID of the reousrce manager that will be used to 213 * manage this resource pool on this unit. 214 * 215 * low is the minimum valid element of this resource. 216 * 217 * count is the number of valid elements of this resource. 218 * 219 * extras points to a struct (which will be appended to this during setup of 220 * this pool) that provides additional arguments to how the pool needs to be 221 * managed. This is provided because some of the supported allocation 222 * managers require more information than just the range of valid IDs. 223 * 224 * name is a string that names this resource. It is used only for diagnostic 225 * purposes. Internally, the provided name will be copied to the same cell as 226 * the structure, so the name array is really variable length. 227 * 228 * Note that the extras struct will be appended to the same memory cell as 229 * this struct, after the name, and so the pointer will not need to be freed 230 * when this is destroyed. 231 */ 232 typedef struct _shr_res_pool_desc_s { 233 shr_res_allocator_t resManagerType; /* which resoource manager to use */ 234 int low; /* minimum available element */ 235 int count; /* number of available elements */ 236 int refCount; /* number of types using this pool */ 237 int inuse; /* number of active elems this pool */ 238 void *resHandle; /* handle for this resource */ 239 void *extras; /* additional config per resmgr type */ 240 char name[1]; /* descriptive name for diagnostics */ 241 } _shr_res_pool_desc_t; 242 243 244 /* 245 * This structure describes attributes about the unit, and includes lists 246 * that are applicable to the unit. Note that while resource IDs and resource 247 * types are unit-specific, the resource managers themselves are globally 248 * available to all units. 249 * 250 * resTypeCount indicates how many different resources on this unit are being 251 * managed through this system. It is possible for more than one resource to 252 * use the same resource pool, but it is not possible for one resource to use 253 * more than one resource pool. 254 * 255 * resPoolCount indicates how many different resource pools are being managed 256 * on this unit. 257 * 258 * res points to an array of resource descriptors, Each descriptor will map a 259 * single resource on the unit to its underlying resource pool. 260 * 261 * pool points to an array of resource pool descriptors. Each of these will 262 * describe a single resource pool on the unit and map to the manager that 263 * will be used for that particular pool. 264 */ 265 typedef struct _shr_res_unit_desc_s { 266 uint16 resTypeCount; /* maximum presented resource ID */ 267 uint16 resPoolCount; /* maximum resource pool ID */ 268 _shr_res_type_desc_t **res; /* array of type -> pool map pointers */ 269 _shr_res_pool_desc_t **pool; /* array of pool description pointers */ 270 } _shr_res_unit_desc_t; 271 272 /* A handle for a non-unit-based resource manager instance */ 273 typedef _shr_res_unit_desc_t *shr_mres_handle_t; 274 275 extern _shr_res_unit_desc_t *_g_unitResDesc[BCM_LOCAL_UNITS_MAX]; 276 277 /****************************************************************************** 278 * 279 * Handle based resource management (private/common based upon handle usage) 280 * 281 * These functions are intended to use when a specific module needs its own 282 * private resources, or if a module may need to share resources across units 283 * (this is accomplished by sharing the handle). 284 */ 285 286 /* 287 * Function 288 * shr_mres_create 289 * Purpose 290 * Create a resource manager instance and provide a handle for it 291 * Parameters 292 * (OUT) handle : where to put the instance handle 293 * (IN) num_res_types : number of resource types for the unit 294 * (IN) num_res_pools : number of resource pools for the unit 295 * Returns 296 * BCM_E_NONE if successful 297 * BCM_E_* as appropriate otherwise 298 * Notes 299 * Resource types map to resource pools, from which the actual elements of 300 * the resources are drawn, and more than one type can pull elements from 301 * the same pool, so there should always be at least as many types as 302 * there are pools. 303 * 304 * The instance will be limited to the number of types and pools specified 305 * here, as the descriptor space will be allocated and cleared by this 306 * function. See below for how to configure types and pools. 307 */ 308 extern int 309 shr_mres_create(shr_mres_handle_t *handle, 310 int num_res_types, 311 int num_res_pools); 312 313 /* 314 * Function 315 * shr_mres_get 316 * Purpose 317 * Get number of resource pools and types configured for a handle 318 * Parameters 319 * (IN) handle : handle for the instance to query 320 * (OUT) num_res_types : where to put number of resource types for unit 321 * (OUT) num_res_pools : where to put number of resource pools for unit 322 * Returns 323 * BCM_E_NONE if successful 324 * BCM_E_* as appropriate otherwise 325 * Notes 326 * Outbound arguments may be NULL for this call; any NULL outbound 327 * argument(s) will simply not be filled in. 328 */ 329 extern int 330 shr_mres_get(shr_mres_handle_t handle, 331 int *num_res_types, 332 int *num_res_pools); 333 334 /* 335 * Function 336 * shr_mres_pool_set 337 * Purpose 338 * Configure a resource pool for the handle 339 * Parameters 340 * (IN) handle : handle for the instance to access 341 * (IN) pool_id : which pool to configure (0..max_res_pools-1) 342 * (IN) manager : which manager to use for this pool 343 * (IN) low_id : lowest valid resource element ID in this pool 344 * (IN) count : number of valid resource elements in this pool 345 * (IN) extras : pointer to extra information for the manager type 346 * (IN) name : pointer to string naming the pool 347 * Returns 348 * BCM_E_NONE if successful 349 * BCM_E_* as appropriate otherwise 350 * Notes 351 * A resource pool must be configured before any resources can point to 352 * it, and can not be changed after resources point to it. 353 * 354 * The underlying resource management information will be created during 355 * this call. If this call is made again for the same resource pool, and 356 * there are no resources using this pool, the old information will be 357 * destroyed and the new will be created in its stead, but if resources 358 * are already using this pool, the call will fail. 359 * 360 * Most of the allocation managers require some extra arguments, so the 361 * extras argument is likely obligatory. Each allocation manager has its 362 * own addiitonal arguments, for specific behavioural control or 363 * optimisation, and the correct extras type must be used accordingly. 364 * 365 * This must be called after create, and before a pool can be used, even 366 * before a resource can be assigned to the pool. 367 * 368 * Note that name and extras will be copied internally, and so the memory 369 * underlying those can be reused by the caller once this call completes. 370 */ 371 extern int 372 shr_mres_pool_set(shr_mres_handle_t handle, 373 int pool_id, 374 shr_res_allocator_t manager, 375 int low_id, 376 int count, 377 const void *extras, 378 const char *name); 379 380 /* 381 * Function 382 * shr_mres_pool_unset 383 * Purpose 384 * Destroy a resource pool for the handle 385 * Parameters 386 * (IN) handle : handle for the instance to access 387 * (IN) pool_id : which pool to configure (0..max_res_pools-1) 388 * Returns 389 * BCM_E_NONE if successful 390 * BCM_E_* as appropriate otherwise 391 * Notes 392 * Destroys the resource pool only if there are no types using the pool. 393 * 394 * It will report an error (though the pool will be destroyed) if there 395 * appear to be elements in use but no types using the pool. 396 */ 397 extern int 398 shr_mres_pool_unset(shr_mres_handle_t handle, 399 int pool_id); 400 401 /* 402 * Function 403 * shr_mres_pool_get 404 * Purpose 405 * Get configuration for a resource pool on a particular handle 406 * Parameters 407 * (IN) handle : handle for the instance to access 408 * (IN) pool_id : which pool to query (0..max_res_pools-1) 409 * (OUT) manager : where to put manager that is used for this pool 410 * (OUT) low_id : where to put low ID value for this pool 411 * (OUT) count : where to put count value for this pool 412 * (OUT) extras : where to put pointer to extras for this pool 413 * (OUT) name : where to put pointer to name for this pool 414 * Returns 415 * BCM_E_NONE if successful 416 * BCM_E_* as appropriate otherwise 417 * Notes 418 * Both extras and name will point to internal data for the pool and MUST 419 * NOT BE MODIFIED by the caller. If the caller wants to change these 420 * data, the pool will have to be reconfigured with shr_mres_pool_set. If 421 * the caller wants to use the data in a destructive manner, the caller 422 * must copy the data to a local buffer first and use that buffer. 423 * 424 * Outbound arguments may be NULL for this call; any NULL outbound 425 * argument(s) will simply not be filled in. 426 */ 427 extern int 428 shr_mres_pool_get(shr_mres_handle_t handle, 429 int pool_id, 430 shr_res_allocator_t *manger, 431 int *low_id, 432 int *count, 433 const void **extras, 434 const char **name); 435 436 /* 437 * Function 438 * shr_mres_pool_info_get 439 * Purpose 440 * Get status information for a resource pool on a particular handle 441 * Parameters 442 * (IN) handle : handle for the instance to access 443 * (IN) pool_id : which pool to query (0..max_res_pools-1) 444 * (OUT) info : where to put information about this pool 445 * Returns 446 * BCM_E_NONE if successful 447 * BCM_E_* as appropriate otherwise 448 * Notes 449 * Outbound arguments may be NULL for this call; any NULL outbound 450 * argument(s) will simply not be filled in. 451 */ 452 extern int 453 shr_mres_pool_info_get(shr_mres_handle_t handle, 454 int pool_id, 455 shr_res_pool_info_t *info); 456 457 /* 458 * Function 459 * shr_mres_type_set 460 * Purpose 461 * Configure a resource type 462 * Parameters 463 * (IN) handle : handle for the instance to access 464 * (IN) res_id : which resource to configure (0..max_res_types-1) 465 * (IN) pool_id : which pool this resource uses (0..max_res_pools-1) 466 * (IN) elem_size : number of pool elements per element of this resource 467 * (IN) name : pointer to string naming the type 468 * Returns 469 * BCM_E_NONE if successful 470 * BCM_E_* as appropriate otherwise 471 * Notes 472 * More than one resource can use the same pool, but a single resource can 473 * only use one pool. 474 * 475 * If this is called after a resource has elements allocated, it will 476 * fail. If it is called before a resource has elements allocated, it 477 * will map the resource so it uses the specified pool. 478 * 479 * This must be called after init and after the pool it uses has been 480 * configured, and before the associted resource can be used. 481 * 482 * elem_size indicates how many of the underlying pool elements are 483 * required to make a single element of this resource. Some allocators do 484 * not support more than a single element being allocated at a time, and 485 * so the resource manager will try to allocate contiguous blocks of the 486 * specified number of pool elements, but it is possible this will fail. 487 * 488 * Note that name will be copied internally, and so the underlying memory 489 * can be reused by the caller once this call completes. 490 */ 491 extern int 492 shr_mres_type_set(shr_mres_handle_t handle, 493 int res_id, 494 int pool_id, 495 int elem_size, 496 const char *name); 497 498 /* 499 * Function 500 * shr_mres_type_unset 501 * Purpose 502 * Destroy a resource type 503 * Parameters 504 * (IN) handle : handle for the instance to access 505 * (IN) res_id : which resource to configure (0..max_res_types-1) 506 * Returns 507 * BCM_E_NONE if successful 508 * BCM_E_* as appropriate otherwise 509 * Notes 510 * Will not destroy a resource type if elements of that resource are still 511 * in use. 512 */ 513 extern int 514 shr_mres_type_unset(shr_mres_handle_t handle, 515 int res_id); 516 517 /* 518 * Function 519 * shr_mres_type_get 520 * Purpose 521 * Get information about a resource type 522 * Parameters 523 * (IN) handle : handle for the instance to access 524 * (IN) res_id : which resource to query (0..max_res_types-1) 525 * (OUT) pool_id : where to put pool ID 526 * (OUT) elem_size : where to put element size 527 * (OUT) name : where to put name pointer 528 * Returns 529 * BCM_E_NONE if successful 530 * BCM_E_* as appropriate otherwise 531 * Notes 532 * Name will point to internal data for the type and MUST NOT BE MODIFIED 533 * by the caller. If the caller wants to change the name, the type will 534 * have to be reconfigured with shr_res_type_set. If the caller wants to 535 * use the name in a destructive manner, the caller must copy the name to 536 * a local buffer first and use that buffer. 537 * 538 * Outbound arguments may be NULL for this call; any NULL outbound 539 * argument(s) will simply not be filled in. 540 */ 541 extern int 542 shr_mres_type_get(shr_mres_handle_t handle, 543 int res_id, 544 int *pool_id, 545 int *elem_size, 546 const char **name); 547 548 /* 549 * Function 550 * shr_mres_type_info_get 551 * Purpose 552 * Get status information for a resource type on a particular handle 553 * Parameters 554 * (IN) handle : handle for the instance to access 555 * (IN) res_id : which resource to query (0..max_res_types-1) 556 * (OUT) info : where to put information about this type 557 * Returns 558 * BCM_E_NONE if successful 559 * BCM_E_* as appropriate otherwise 560 * Notes 561 * Outbound arguments may be NULL for this call; any NULL outbound 562 * argument(s) will simply not be filled in. 563 */ 564 extern int 565 shr_mres_type_info_get(shr_mres_handle_t handle, 566 int res_id, 567 shr_res_type_info_t *info); 568 569 /* 570 * Function 571 * shr_mres_destroy 572 * Purpose 573 * Destroy a resource instance handle and its associated information 574 * Parameters 575 * (IN) handle : handle for the instance to access 576 * Returns 577 * BCM_E_NONE if successful 578 * BCM_E_* as appropriate otherwise 579 * Notes 580 * This will destroy all of the resource pools, then tear down the rest of 581 * the resource management for the instance. 582 */ 583 extern int 584 shr_mres_destroy(shr_mres_handle_t handle); 585 586 /* 587 * Function 588 * shr_mres_alloc 589 * Purpose 590 * Allocate an element or block of elements of a particular resource 591 * Parameters 592 * (IN) handle : handle for the instance to access 593 * (IN) res_id : which resource to allocate 594 * (IN) flags : flags providing specifics of what/how to allocate 595 * (IN) count : elements to allocate in this block 596 * (IN/OUT) elem : where to put the allocated element (block base) 597 * Returns 598 * BCM_E_NONE if successful 599 * BCM_E_* as appropriate otherwise 600 * Notes 601 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 602 * the WITH_ID flag is not specified. 603 * 604 * This will allocate a single block of the requested number of elements 605 * of this resource (each of which may be a number of elements taken from 606 * the underlying pool). Some underlying managers do not support more 607 * than single element blocks, and while the manager will try to allocate 608 * a contiguous block in such case, it is possible that it will fail even 609 * if there are enough underlying elements available for the request. 610 * 611 * Partial blocks will not be allocated. 612 * 613 * The caller must track how many elements were requested and provide that 614 * number when freeing the block. 615 */ 616 extern int 617 shr_mres_alloc(shr_mres_handle_t handle, 618 int res_id, 619 uint32 flags, 620 int count, 621 int *elem); 622 623 /* 624 * Function 625 * shr_mres_alloc_tag 626 * Purpose 627 * Allocate an element or block of elements of a particular resource, 628 * assuring all of the elements have the same tag. 629 * Parameters 630 * (IN) handle : handle for the instance to access 631 * (IN) res_id : which resource to allocate 632 * (IN) flags : flags providing specifics of what/how to allocate 633 * (IN) tag : pointer to tag value to use 634 * (IN) count : elements to allocate in this block 635 * (IN/OUT) elem : where to put the allocated element (block base) 636 * Returns 637 * BCM_E_NONE if successful 638 * BCM_E_* as appropriate otherwise 639 * Notes 640 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 641 * the WITH_ID flag is not specified. 642 * 643 * The tag pointer is a pointer to the value that will be used for tagging 644 * the requested block of elements. Note that since tags are a number of 645 * bytes starting at the pointer, the tag must already be masked as needed 646 * and should be stored in something no larger than the number of bytes 647 * that was specified as tag size when setting up the pool. 648 * 649 * This will allocate a single block of the requested number of elements 650 * of this resource (each of which may be a number of elements taken from 651 * the underlying pool). Some underlying managers do not support more 652 * than single element blocks, and while the manager will try to allocate 653 * a contiguous block in such case, it is possible that it will fail even 654 * if there are enough underlying elements available for the request. 655 * 656 * Some allocators do not support tagged mode. If allocating elements 657 * from a resource that has tagging, either this call or the alloc_tag 658 * call must be used so the tag can be specified. If neither this nor the 659 * alloc_tag call is used, the tag will be assumed to be all zeroes. 660 * 661 * Partial blocks will not be allocated. 662 * 663 * The caller must track how many elements were requested and provide that 664 * number when freeing the block. 665 */ 666 extern int 667 shr_mres_alloc_tag(shr_mres_handle_t handle, 668 int res_id, 669 uint32 flags, 670 const void *tag, 671 int count, 672 int *elem); 673 674 /* 675 * Function 676 * shr_mres_alloc_align 677 * Purpose 678 * Allocate an element or block of elements of a particular resource, 679 * using a base alignment and an offset. 680 * Parameters 681 * (IN) handle : handle for the instance to access 682 * (IN) res_id : which resource to allocate 683 * (IN) flags : flags providing specifics of what/how to allocate 684 * (IN) align : base alignment 685 * (IN) offset : offest from base alignment for first element 686 * (IN) count : elements to allocate in this block 687 * (IN/OUT) elem : where to put the allocated element (block base) 688 * Returns 689 * BCM_E_NONE if successful 690 * BCM_E_* as appropriate otherwise 691 * Notes 692 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 693 * the WITH_ID flag is not specified. If WITH_ID is specified, and the 694 * requested base element does not comply with the indicated alignment, 695 * BCM_E_PARAM will be returned. 696 * 697 * This will allocate a single block of the requested number of elements 698 * of this resource (each of which may be a number of elements taken from 699 * the underlying pool). Some underlying managers do not support more 700 * than single element blocks, and while the manager will try to allocate 701 * a contiguous block in such case, it is possible that it will fail even 702 * if there are enough underlying elements available for the request. 703 * 704 * The first element of the returned block will be at ((n * align) + 705 * offset), where n is some integer. If it is not possible to allocate a 706 * block with the requested constraints, the call will fail. Note that 707 * the alignment is within the specified range of the resource, and not 708 * specifically aligned against the absolute value zero; to request the 709 * alignment be against zero, specify the ALIGN_ZERO flag. 710 * 711 * If offset >= align, BCM_E_PARAM. If align is zero or negative, it will 712 * be treated as if it were 1. 713 * 714 * Some allocators may not support this feature; some may place 715 * restrictions, such as the base alignment being a power of two, or not 716 * supporting the ALIGN_ZERO flag. 717 * 718 * Partial blocks will not be allocated. 719 * 720 * The caller must track how many elements were requested and provide that 721 * number when freeing the block. 722 */ 723 extern int 724 shr_mres_alloc_align(shr_mres_handle_t handle, 725 int res_id, 726 uint32 flags, 727 int align, 728 int offset, 729 int count, 730 int *elem); 731 732 /* 733 * Function 734 * shr_mres_alloc_align_sparse 735 * Purpose 736 * Allocate a sparse block of elements of a particular resource, using a 737 * base alignment, an offset, a pattern, length, and repeat count. 738 * Parameters 739 * (IN) handle : handle for the instance to access 740 * (IN) res_id : which resource to allocate 741 * (IN) flags : flags providing specifics of what/how to allocate 742 * (IN) align : base alignment 743 * (IN) offset : offest from base alignment for first element 744 * (IN) pattern : bitmap pattern of elements to include 745 * (IN) length : length of pattern 746 * (IN) repeats : number of time pattern repeats 747 * (IN/OUT) elem : where to put the allocated element (block base) 748 * Returns 749 * BCM_E_NONE if successful 750 * BCM_E_* as appropriate otherwise 751 * Notes 752 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 753 * the WITH_ID flag is not specified. If WITH_ID is specified, and the 754 * requested base element does not comply with the indicated alignment, 755 * BCM_E_PARAM will be returned. 756 * 757 * This will allocate a single block of the requested number of elements 758 * of this resource. 759 * 760 * This function can not be used with a 'scaled' allocator. 761 * 762 * The first element of the returned block will be at ((n * align) + 763 * offset), where n is some integer. If it is not possible to allocate a 764 * block with the requested constraints, the call will fail. Note that 765 * the alignment is within the specified range of the resource, and not 766 * specifically aligned against the absolute value zero; to request the 767 * alignment be against zero, specify the ALIGN_ZERO flag. 768 * 769 * If offset >= align, BCM_E_PARAM. If align is zero or negative, it will 770 * be treated as if it were 1. 771 * 772 * Some allocators may not support this feature; some may place 773 * restrictions, such as the base alignment being a power of two, or not 774 * supporting the ALIGN_ZERO flag. 775 * 776 * Partial blocks will not be allocated. 777 * 778 * The pattern argument is a bitmap of the elements that are of interest 779 * in a single iteration of the pattern (and only the least significant 780 * 'length' bits are used; higher bits are ignored). The bit with value 781 * (1 << k) set indicates the element at (elem + k) must be in the block; 782 * clear it indicates the element at (elem + k) is not in the block. This 783 * repeats for as many iterations as indicated by 'repeats'. 784 * 785 * For example: 786 * align = 4, offs = 0, pattern = 0x7, length = 8, repeats = 2 would 787 * request a block of three elements, a gap of one element, and then 788 * another block of three elements, with the first allocated element 789 * aligned to a multiple of four. 790 * 791 * align = 8, offs = 1, pattern = 0x1, length = 2, repeats = 4 would 792 * request four oddly numbered elements with the first one allocated at 793 * (8 * n) + 1 where n is some arbitrary number. 794 * 795 * Note the bitmap is considered based at the requested alignment+offset, 796 * even if the least significant bit is not set, so it is probably 797 * simplest to ensure the LSb of pattern is set. 798 * 799 * For example: 800 * align = 4, offs = 0, pattern = 0xA, length = 4, repeats = 1 would 801 * request two elements, but the returned base element number would be 802 * (4 * n), while the actually allocated elements would be (4 * n) + 1 803 * and (4 * n) + 3. 804 * 805 * The caller must track the pattern, length and repeats values and 806 * provide these values along with the elem value when freeing the block. 807 * 808 * Any allocation made through this function must be freed using the 809 * shr_mres_free_sparse function. 810 * 811 * Sparse functions do not work with scaled resources. 812 */ 813 extern int 814 shr_mres_alloc_align_sparse(shr_mres_handle_t handle, 815 int res_id, 816 uint32 flags, 817 int align, 818 int offset, 819 uint32 pattern, 820 int length, 821 int repeats, 822 int *elem); 823 824 /* 825 * Function 826 * shr_mres_alloc_align_tag 827 * Purpose 828 * Allocate an element or block of elements of a particular resource, 829 * using a base alignment and an offset, and assuring the elements all 830 * have the same tag. 831 * Parameters 832 * (IN) handle : handle for the instance to access 833 * (IN) res_id : which resource to allocate 834 * (IN) flags : flags providing specifics of what/how to allocate 835 * (IN) align : base alignment 836 * (IN) offset : offest from base alignment for first element 837 * (IN) tag : pointer to tag value to use 838 * (IN) count : elements to allocate in this block 839 * (IN/OUT) elem : where to put the allocated element (block base) 840 * Returns 841 * BCM_E_NONE if successful 842 * BCM_E_* as appropriate otherwise 843 * Notes 844 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 845 * the WITH_ID flag is not specified. If WITH_ID is specified, and the 846 * requested base element does not comply with the indicated alignment, 847 * BCM_E_PARAM will be returned. 848 * 849 * The tag pointer is a pointer to the value that will be used for tagging 850 * the requested block of elements. Note that since tags are a number of 851 * bytes starting at the pointer, the tag must already be masked as needed 852 * and should be stored in something no larger than the number of bytes 853 * that was specified as tag size when setting up the pool. 854 * 855 * This will allocate a single block of the requested number of elements 856 * of this resource (each of which may be a number of elements taken from 857 * the underlying pool), and ensuring all have the same tag (elements can 858 * be within the same grain as elements from other blocks only if the tag 859 * of the partial grain is equal to the tag for the new elements). Some 860 * underlying managers do not support more than single element blocks, and 861 * while the manager will try to allocate a contiguous block in such case, 862 * it is possible that it will fail even if there are enough underlying 863 * elements available for the request. 864 * 865 * The first element of the returned block will be at ((n * align) + 866 * offset), where n is some integer. If it is not possible to allocate a 867 * block with the requested constraints, the call will fail. Note that 868 * the alignment is within the specified range of the resource, and not 869 * specifically aligned against the absolute value zero; to request the 870 * alignment be against zero, specify the ALIGN_ZERO flag. 871 * 872 * If offset >= align, BCM_E_PARAM. If align is zero or negative, it will 873 * be treated as if it were 1. 874 * 875 * Some allocators may not support this feature; some may place 876 * restrictions, such as the base alignment being a power of two, or not 877 * supporting the ALIGN_ZERO flag. 878 * 879 * Some allocators do not support tagged mode. If allocating elements 880 * from a resource that has tagging, either this call or the alloc_tag 881 * call must be used so the tag can be specified. If neither this nor the 882 * alloc_tag call is used, the tag will be assumed to be all zeroes. 883 * 884 * Partial blocks will not be allocated. 885 * 886 * The caller must track how many elements were requested and provide that 887 * number when freeing the block. 888 */ 889 extern int 890 shr_mres_alloc_align_tag(shr_mres_handle_t handle, 891 int res_id, 892 uint32 flags, 893 int align, 894 int offset, 895 const void *tag, 896 int count, 897 int *elem); 898 899 /* 900 * Function 901 * shr_mres_free 902 * Purpose 903 * Free an element or block of elements of a particular resource 904 * Parameters 905 * (IN) handle : handle for the instance to access 906 * (IN) res_id : which resource to free 907 * (IN) count : elements in the block to free 908 * (IN) elem : the element to free (or base of the block to free) 909 * Returns 910 * BCM_E_NONE if successful 911 * BCM_E_* as appropriate otherwise 912 * Notes 913 * This will free a single block of the requested number of elements, 914 * starting at the specified element. Some of the allocators do not deal 915 * with blocks and so must be told how large a block was, so it is 916 * obligatory that the caller be able to provide such information. 917 * 918 * This should only be called with valid data (base element and element 919 * count) against known allocated blocks. Trying to free a block that is 920 * not in use or trying to free something that spans multiple allocated 921 * blocks may not work. 922 * 923 * Must not be used to free sparse blocks. 924 */ 925 extern int 926 shr_mres_free(shr_mres_handle_t handle, 927 int res_id, 928 int count, 929 int elem); 930 931 /* 932 * Function 933 * shr_mres_free_and_status 934 * Purpose 935 * Free an element or block of elements of a particular resource, then get 936 * flags about that resource. 937 * Parameters 938 * (IN) handle : handle for the instance to access 939 * (IN) res_id : which resource to free 940 * (IN) count : elements in the block to free 941 * (IN) elem : the element to free (or base of the block to free) 942 * (OUT) flags : where to put the flags 943 * Returns 944 * BCM_E_NONE if successful 945 * BCM_E_* as appropriate otherwise 946 * Notes 947 * This will free a single block of the requested number of elements, 948 * starting at the specified element. Some of the allocators do not deal 949 * with blocks and so must be told how large a block was, so it is 950 * obligatory that the caller be able to provide such information. 951 * 952 * This should only be called with valid data (base element and element 953 * count) against known allocated blocks. Trying to free a block that is 954 * not in use or trying to free something that spans multiple allocated 955 * blocks may not work. 956 * 957 * The value at status will generally be updated to reflect the proper 958 * status unless the type is not defined at the time of the call. The 959 * values for the individual flags are of the SHR_RES_FREED_* form. 960 * 961 * Must not be used to free sparse blocks. 962 */ 963 extern int 964 shr_mres_free_and_status(shr_mres_handle_t handle, 965 int res_id, 966 int count, 967 int elem, 968 uint32 *status); 969 970 /* 971 * Function 972 * shr_mres_free_sparse 973 * Purpose 974 * Free a sparse block of elements of a particular resource 975 * Parameters 976 * (IN) handle : handle for the instance to access 977 * (IN) res_id : which resource to free 978 * (IN) pattern: pattern of elements 979 * (IN) length : length of pattern 980 * (IN) repeats: number of iterations of the pattern 981 * (IN) elem : the element to free (or base of the block to free) 982 * Returns 983 * BCM_E_NONE if successful 984 * BCM_E_* as appropriate otherwise 985 * Notes 986 * This will free a sparse block of elements, starting at the specified 987 * element and proceeding as specified. 988 * 989 * This function can not be used with a 'scaled' allocator. 990 * 991 * This should only be called with valid data (base element, pattern, 992 * length, repeats). Trying to free a block that is not in use or trying 993 * to free something that spans multiple allocated blocks may not work. 994 * 995 * Anything allocated with shr_mres_alloc_align_sparse must be freed using 996 * this function. While it is possible to use this function to free 997 * blocks allocated with other functions, it is not advised. 998 * 999 * Sparse functions do not work with scaled resources. 1000 * 1001 * While this can be used to free non-sparse blocks, it is probably best 1002 * to use the non-sparse free functions for that purpose. 1003 */ 1004 extern int 1005 shr_mres_free_sparse(shr_mres_handle_t handle, 1006 int res_id, 1007 uint32 pattern, 1008 int length, 1009 int repeats, 1010 int elem); 1011 1012 /* 1013 * Function 1014 * shr_mres_free_sparse 1015 * Purpose 1016 * Free a sparse block of elements of a particular resource and request 1017 * status flags from the free. 1018 * Parameters 1019 * (IN) handle : handle for the instance to access 1020 * (IN) res_id : which resource to free 1021 * (IN) pattern: pattern of elements 1022 * (IN) length : length of pattern 1023 * (IN) repeats: number of iterations of the pattern 1024 * (IN) elem : the element to free (or base of the block to free) 1025 * (OUT) status: where to put the status flags 1026 * Returns 1027 * BCM_E_NONE if successful 1028 * BCM_E_* as appropriate otherwise 1029 * Notes 1030 * This will free a sparse block of elements, starting at the specified 1031 * element and proceeding as specified. 1032 * 1033 * This function can not be used with a 'scaled' allocator. 1034 * 1035 * This should only be called with valid data (base element, pattern, 1036 * length, repeats). Trying to free a block that is not in use or trying 1037 * to free something that spans multiple allocated blocks may not work. 1038 * 1039 * Anything allocated with shr_mres_alloc_align_sparse must be freed using 1040 * this function. While it is possible to use this function to free 1041 * blocks allocated with other functions, it is not advised. 1042 * 1043 * Sparse functions do not work with scaled resources. 1044 * 1045 * While this can be used to free non-sparse blocks, it is probably best 1046 * to use the non-sparse free functions for that purpose. 1047 */ 1048 extern int 1049 shr_mres_free_sparse_and_status(shr_mres_handle_t handle, 1050 int res_id, 1051 uint32 pattern, 1052 int length, 1053 int repeats, 1054 int elem, 1055 uint32 *status); 1056 1057 /* 1058 * Function 1059 * shr_mres_check 1060 * Purpose 1061 * Check the status of a specific element 1062 * Parameters 1063 * (IN) handle : handle for the instance to access 1064 * (IN) res_id : which resource to check 1065 * (IN) count : elements in the block to check 1066 * (IN) elem : the element to check (or base of the block to check) 1067 * Returns 1068 * BCM_E_NOT_FOUND if the element is not in use 1069 * BCM_E_EXISTS if the element is in use 1070 * BCM_E_PARAM if the element is not valid 1071 * BCM_E_* as appropriate otherwise 1072 * Notes 1073 * This will check whether the requested block of the resource is 1074 * allocated. Note that if any element of the resource in the range of 1075 * [elem..(elem+count-1)] (inclusive) is not free, it returns 1076 * BCM_E_EXISTS; it will only return BCM_E_NOT_FOUND if all elements 1077 * within the specified block are free. 1078 * 1079 * Normally this should be called to check on a specific block (one that 1080 * is thought to exist or in preparation for allocating it WITH_ID. 1081 * 1082 * Unlike shr_mres_check_all, this considers the whole set of elements in 1083 * use if any of them is in use. 1084 */ 1085 extern int 1086 shr_mres_check(shr_mres_handle_t handle, 1087 int res_id, 1088 int count, 1089 int elem); 1090 1091 /* 1092 * Function 1093 * shr_mres_check_all 1094 * Purpose 1095 * Check the status of a group of elements 1096 * Parameters 1097 * (IN) handle : handle for the instance to access 1098 * (IN) res_id : which resource to check 1099 * (IN) count : elements in the block to check 1100 * (IN) elem : the element to check (or base of the block to check) 1101 * Returns 1102 * BCM_E_EMPTY if none of the elements are in use 1103 * BCM_E_FULL if all of the elements are in use 1104 * BCM_E_CONFIG if elements are in use but block(s) do not match 1105 * BCM_E_EXISTS if some of the elements are in use but not all of them 1106 * BCM_E_PARAM if any of the elements is not valid 1107 * BCM_E_* as appropriate otherwise 1108 * Notes 1109 * This will check all of the elements (and blocks, on those allocators 1110 * supporting block tracking) in the specified range, and return a result 1111 * based upon that examination. 1112 * 1113 * Normally, this would be called in case of intent to directly replace a 1114 * possibly existing block of elements with a new one. 1115 * 1116 * Unlike shr_mres_check, this does not immediately return if it finds an 1117 * in-use element. Instead, it continues through the specified range and 1118 * returns a more detailed result, considering the requested range as if 1119 * it were intended for immediate direct reuse (such as WITH_ID+REPLACE). 1120 * 1121 * For TAGGED resources, this assumes the tag to be used is the tag 1122 * already associated with the first element in the block. If the default 1123 * tag behaviour is desired instead, use shr_mres_check_all_tag with the 1124 * tag pointer set to NULL. 1125 */ 1126 extern int 1127 shr_mres_check_all(shr_mres_handle_t handle, 1128 int res_id, 1129 int count, 1130 int elem); 1131 1132 /* 1133 * Function 1134 * shr_mres_check_all_sparse 1135 * Purpose 1136 * Check the status of a sparse group of elements 1137 * Parameters 1138 * (IN) handle : handle for the instance to access 1139 * (IN) res_id : which resource to check 1140 * (IN) pattern: pattern of elements to check 1141 * (IN) length : length of the pattern 1142 * (IN) repeats: number of times the pattern repeats 1143 * (IN) elem : the element to check (or base of the block to check) 1144 * Returns 1145 * BCM_E_EMPTY if none of the elements are in use 1146 * BCM_E_FULL if all of the elements are in use 1147 * BCM_E_CONFIG if elements are in use but block(s) do not match 1148 * BCM_E_EXISTS if some of the elements are in use but not all of them 1149 * BCM_E_PARAM if any of the elements is not valid 1150 * BCM_E_* as appropriate otherwise 1151 * Notes 1152 * This will check whether the requested sparse block of the resource is 1153 * allocated. If all of the specified elements are allocated, it will 1154 * return BCM_E_FULL; if all of the specified elements are free, it will 1155 * return BCM_E_EMPTY; if some of the specified elements are allocated and 1156 * some are free, it will return BCM_E_EXISTS. 1157 * 1158 * See shr_res_bitmap_sparse_alloc_align_sparse for information about 1159 * how sparse patterns are specified. 1160 * 1161 * Normally, this would be called in case of intent to directly replace a 1162 * possibly existing block of elements with a new one. 1163 * 1164 * Unlike shr_mres_check, this does not immediately return if it finds an 1165 * in-use element. Instead, it continues through the specified range and 1166 * returns a more detailed result, considering the requested range as if 1167 * it were intended for immediate direct reuse (such as WITH_ID+REPLACE). 1168 * 1169 * For TAGGED resources, this assumes the tag to be used is the tag 1170 * already associated with the first element in the block. If the default 1171 * tag behaviour is desired instead, use shr_mres_check_all_tag with the 1172 * tag pointer set to NULL. 1173 * 1174 * Sparse functions do not work with scaled resources. 1175 */ 1176 extern int 1177 shr_mres_check_all_sparse(shr_mres_handle_t handle, 1178 int res_id, 1179 uint32 pattern, 1180 int length, 1181 int repeats, 1182 int elem); 1183 1184 /* 1185 * Function 1186 * shr_mres_check_all_tag 1187 * Purpose 1188 * Check the status of a group of elements 1189 * Parameters 1190 * (IN) handle : handle for the instance to access 1191 * (IN) res_id : which resource to check 1192 * (IN) tag : the tag to consider during the check 1193 * (IN) count : elements in the block to check 1194 * (IN) elem : the element to check (or base of the block to check) 1195 * Returns 1196 * BCM_E_EMPTY if none of the elements are in use 1197 * BCM_E_FULL if all of the elements are in use 1198 * BCM_E_CONFIG if elements are in use but block(s)/tag(s) do not match 1199 * BCM_E_EXISTS if some of the elements are in use but not all of them 1200 * BCM_E_PARAM if any of the elements is not valid 1201 * BCM_E_* as appropriate otherwise 1202 * Notes 1203 * This will check all of the elements (and blocks, on those allocators 1204 * supporting block tracking) in the specified range, and return a result 1205 * based upon that examination. 1206 * 1207 * Normally, this would be called in case of intent to directly replace a 1208 * possibly existing block of elements with a new one. 1209 * 1210 * Unlike shr_mres_check, this does not immediately return if it finds an 1211 * in-use element. Instead, it continues through the specified range and 1212 * returns a more detailed result, considering the requested range as if 1213 * it were intended for immediate direct reuse (such as WITH_ID+REPLACE). 1214 */ 1215 extern int 1216 shr_mres_check_all_tag(shr_mres_handle_t handle, 1217 int res_id, 1218 const void *tag, 1219 int count, 1220 int elem); 1221 1222 /* 1223 * Function 1224 * shr_mres_alloc_group 1225 * Purpose 1226 * Allocate an group of elements or blocks of elements of a particular 1227 * resource 1228 * Parameters 1229 * (IN) handle : handle for the instance to access 1230 * (IN) res_id : which resource to allocate 1231 * (IN) grp_flags : flags to apply to the whole group 1232 * (IN) grp_size : number of members of the group 1233 * (OUT) grp_done : where to put how many members were completed 1234 * (IN) *flags : flags providing specifics of what/how to allocate 1235 * (IN) *count : elements to allocate in this block 1236 * (IN/OUT) *elem : where to put the allocated element (block base) 1237 * Returns 1238 * BCM_E_NONE if successful 1239 * BCM_E_* as appropriate otherwise 1240 * Notes 1241 * The flags, count, and elem all point to arrays. This function will act 1242 * as if shr_mres_alloc were called exactly once with each member from 1243 * these arrays as its arguments, including the behaviour for elem. 1244 * 1245 * If all goes well, grp_done will be set equal to grp_size; if something 1246 * goes wrong, grp_done will indicate how many of the members were 1247 * successfully allocated before the failure. 1248 * 1249 * If the SHR_RES_ALLOC_GROUP_ATOMIC flag is set in the group flags, any 1250 * failure will be taken as complete, and all elements/blocks allocated up 1251 * to that point will be freed before the error is returned. If it is not 1252 * set in the group flags, any failure will stop further allocations, but 1253 * will leave existing allocations alone. 1254 * 1255 * This function is essentially a wrapper around shr_mres_alloc. 1256 */ 1257 extern int 1258 shr_mres_alloc_group(shr_mres_handle_t handle, 1259 int res_id, 1260 uint32 grp_flags, 1261 int grp_size, 1262 int *grp_done, 1263 const uint32 *flags, 1264 const int *count, 1265 int *elem); 1266 1267 /* 1268 * Function 1269 * shr_mres_alloc_tag_group 1270 * Purpose 1271 * Allocate an group of elements or blocks of elements of a particular 1272 * resource 1273 * Parameters 1274 * (IN) handle : handle for the instance to access 1275 * (IN) res_id : which resource to allocate 1276 * (IN) grp_flags : flags to apply to the whole group 1277 * (IN) grp_size : number of members of the group 1278 * (OUT) grp_done : where to put how many members were completed 1279 * (IN) *flags : flags providing specifics of what/how to allocate 1280 * (IN) *tag : tags to use for each block 1281 * (IN) *count : elements to allocate in each block 1282 * (IN/OUT) *elem : where to put the allocated element (block base) 1283 * Returns 1284 * BCM_E_NONE if successful 1285 * BCM_E_* as appropriate otherwise 1286 * Notes 1287 * The flags, count, and elem all point to arrays. This function will act 1288 * as if shr_mres_alloc were called exactly once with each member from 1289 * these arrays as its arguments, including the behaviour for elem. 1290 * 1291 * If all goes well, grp_done will be set equal to grp_size; if something 1292 * goes wrong, grp_done will indicate how many of the members were 1293 * successfully allocated before the failure. 1294 * 1295 * If the SHR_RES_ALLOC_GROUP_ATOMIC flag is set in the group flags, any 1296 * failure will be taken as complete, and all elements/blocks allocated up 1297 * to that point will be freed before the error is returned. If it is not 1298 * set in the group flags, any failure will stop further allocations, but 1299 * will leave existing allocations alone. 1300 * 1301 * This function is essentially a wrapper around shr_mres_alloc. 1302 */ 1303 extern int 1304 shr_mres_alloc_tag_group(shr_mres_handle_t handle, 1305 int res_id, 1306 uint32 grp_flags, 1307 int grp_size, 1308 int *grp_done, 1309 const uint32 *flags, 1310 const void** tag, 1311 const int *count, 1312 int *elem); 1313 1314 /* 1315 * Function 1316 * shr_mres_alloc_align_group 1317 * Purpose 1318 * Allocate an group of elements or blocks of elements of a particular 1319 * resource, with specified alignment and offset 1320 * Parameters 1321 * (IN) handle : handle for the instance to access 1322 * (IN) res_id : which resource to allocate 1323 * (IN) grp_flags : flags to apply to the whole group 1324 * (IN) grp_size : number of members of the group 1325 * (OUT) grp_done : where to put how many members were completed 1326 * (IN) *flags : flags providing specifics of what/how to allocate 1327 * (IN) *align : base alignment in this block 1328 * (IN) *offset : offest from base alignment for first elem in this blk 1329 * (IN) *count : elements to allocate in this block 1330 * (IN/OUT) *elem : where to put the allocated element (block base) 1331 * Returns 1332 * BCM_E_NONE if successful 1333 * BCM_E_* as appropriate otherwise 1334 * Notes 1335 * The flags, align, offset, count, and elem all point to arrays. This 1336 * function will act as if shr_mres_alloc_align were called exactly once 1337 * with each member from these arrays as its arguments, including the 1338 * behaviour for elem. 1339 * 1340 * If all goes well, grp_done will be set equal to grp_size; if something 1341 * goes wrong, grp_done will indicate how many of the members were 1342 * successfully allocated before the failure. 1343 * 1344 * If the SHR_RES_ALLOC_GROUP_ATOMIC flag is set in the group flags, any 1345 * failure will be taken as complete, and all elements/blocks allocated up 1346 * to that point will be freed before the error is returned. If it is not 1347 * set in the group flags, any failure will stop further allocations, but 1348 * will leave existing allocations alone. 1349 * 1350 * This function is essentially a wrapper around shr_mres_alloc_align. 1351 */ 1352 extern int 1353 shr_mres_alloc_align_group(shr_mres_handle_t handle, 1354 int res_id, 1355 uint32 grp_flags, 1356 int grp_size, 1357 int *grp_done, 1358 const uint32 *flags, 1359 const int *align, 1360 const int *offset, 1361 const int *count, 1362 int *elem); 1363 1364 /* 1365 * Function 1366 * shr_mres_alloc_align_tag_group 1367 * Purpose 1368 * Allocate an group of elements or blocks of elements of a particular 1369 * resource, with specified alignment and offset 1370 * Parameters 1371 * (IN) handle : handle for the instance to access 1372 * (IN) res_id : which resource to allocate 1373 * (IN) grp_flags : flags to apply to the whole group 1374 * (IN) grp_size : number of members of the group 1375 * (OUT) grp_done : where to put how many members were completed 1376 * (IN) *flags : flags providing specifics of what/how to allocate 1377 * (IN) *align : base alignment in this block 1378 * (IN) *offset : offest from base alignment for first elem in this blk 1379 * (IN) *tag : pointers to the tags for each block 1380 * (IN) *count : elements to allocate in this block 1381 * (IN/OUT) *elem : where to put the allocated element (block base) 1382 * Returns 1383 * BCM_E_NONE if successful 1384 * BCM_E_* as appropriate otherwise 1385 * Notes 1386 * The flags, align, offset, count, and elem all point to arrays. This 1387 * function will act as if shr_mres_alloc_align were called exactly once 1388 * with each member from these arrays as its arguments, including the 1389 * behaviour for elem. 1390 * 1391 * If all goes well, grp_done will be set equal to grp_size; if something 1392 * goes wrong, grp_done will indicate how many of the members were 1393 * successfully allocated before the failure. 1394 * 1395 * If the SHR_RES_ALLOC_GROUP_ATOMIC flag is set in the group flags, any 1396 * failure will be taken as complete, and all elements/blocks allocated up 1397 * to that point will be freed before the error is returned. If it is not 1398 * set in the group flags, any failure will stop further allocations, but 1399 * will leave existing allocations alone. 1400 * 1401 * This function is essentially a wrapper around shr_mres_alloc_align. 1402 */ 1403 extern int 1404 shr_mres_alloc_align_tag_group(shr_mres_handle_t handle, 1405 int res_id, 1406 uint32 grp_flags, 1407 int grp_size, 1408 int *grp_done, 1409 const uint32 *flags, 1410 const int *align, 1411 const int *offset, 1412 const void **tag, 1413 const int *count, 1414 int *elem); 1415 1416 /* 1417 * Function 1418 * shr_mres_free_group 1419 * Purpose 1420 * Free a group of elements or blocks of elements of a particular resource 1421 * Parameters 1422 * (IN) handle : handle for the instance to access 1423 * (IN) res_id : which resource to free 1424 * (IN) grp_flags : flags to apply to the whole group 1425 * (IN) grp_size : number of members this group 1426 * (OUT) grp_done : where to put how many members were completed 1427 * (IN) *count : elements in the block to free 1428 * (IN) *elem : the element to free (or base of the block to free) 1429 * Returns 1430 * BCM_E_NONE if successful 1431 * BCM_E_* as appropriate otherwise 1432 * Notes 1433 * The flags, count, and elem all point to arrays. This function will act 1434 * as if shr_mres_free were called exactly once with each member from 1435 * these arrays as its arguments, including the behaviour for elem. 1436 * 1437 * If all goes well, grp_done will be set equal to grp_size; if something 1438 * goes wrong, grp_done will indicate how many of the members were 1439 * successfully freed before the failure. 1440 * 1441 * This function is essentially a wrapper around shr_mres_free. 1442 */ 1443 extern int 1444 shr_mres_free_group(shr_mres_handle_t handle, 1445 int res_id, 1446 uint32 grp_flags, 1447 int grp_size, 1448 int *grp_done, 1449 const int *count, 1450 const int *elem); 1451 1452 /* 1453 * Function 1454 * shr_mres_free_group_and_status 1455 * Purpose 1456 * Free a group of elements or blocks of elements of a particular resource 1457 * and then get status flags 1458 * Parameters 1459 * (IN) handle : handle for the instance to access 1460 * (IN) res_id : which resource to free 1461 * (IN) grp_flags : flags to apply to the whole group 1462 * (IN) grp_size : number of members this group 1463 * (OUT) grp_done : where to put how many members were completed 1464 * (IN) *count : elements in the block to free 1465 * (IN) *elem : the element to free (or base of the block to free) 1466 * (OUT) status : where to put the status flags 1467 * Returns 1468 * BCM_E_NONE if successful 1469 * BCM_E_* as appropriate otherwise 1470 * Notes 1471 * The flags, count, and elem all point to arrays. This function will act 1472 * as if shr_mres_free were called exactly once with each member from 1473 * these arrays as its arguments, including the behaviour for elem. 1474 * 1475 * If all goes well, grp_done will be set equal to grp_size; if something 1476 * goes wrong, grp_done will indicate how many of the members were 1477 * successfully freed before the failure. 1478 * 1479 * This function is essentially a wrapper around shr_mres_free_and_status. 1480 * 1481 * The value at status will generally be updated to reflect the proper 1482 * status unless the type is not defined at the time of the call. The 1483 * values for the individual flags are of the SHR_RES_FREED_* form. 1484 */ 1485 extern int 1486 shr_mres_free_group_and_status(shr_mres_handle_t handle, 1487 int res_id, 1488 uint32 grp_flags, 1489 int grp_size, 1490 int *grp_done, 1491 const int *count, 1492 const int *elem, 1493 uint32 *status); 1494 1495 /* 1496 * Function 1497 * shr_mres_check_group 1498 * Purpose 1499 * Check the status of a group of specific elements 1500 * Parameters 1501 * (IN) handle : handle for the instance to access 1502 * (IN) res_id : which resource to check 1503 * (IN) grp_flags : flags to apply to the whole group 1504 * (IN) grp_size : number of members this group 1505 * (OUT) grp_done : where to put how many members were completed 1506 * (IN) *count : elements in the block to check 1507 * (IN) *elem : the element to check (or base of the block to check) 1508 * (OUT) *status : where to put the check results 1509 * Returns 1510 * BCM_E_NONE if successful 1511 * BCM_E_* as appropriate otherwise 1512 * Notes 1513 * This behaves similarly to calling shr_mres_check, except that it places 1514 * the result in the provided status array rather than returning the 1515 * status for exactly one element. 1516 * 1517 * The result code from this function should be BCM_E_NONE unless there is 1518 * something obviously wrong with the arguments or an unexpected result is 1519 * encountered. Normally, grp_done would be set equal to grp_size, but if 1520 * there is an unexpected failure, grp_done will indicate how many 1521 * elements were checked before the failure. 1522 * 1523 * If the SHR_RES_ALLOC_GROUP_ATOMIC is set, this function will continue 1524 * to the end of the provided list despite any errors that occur once it 1525 * starts to check the provided list, and will return BCM_E_NONE if it 1526 * gets that far, but it will still return an appropriate error if it is 1527 * unable to begin checking the list due to some error. 1528 * 1529 * This function is essentially a wrapper around shr_mres_check. 1530 */ 1531 extern int 1532 shr_mres_check_group(shr_mres_handle_t handle, 1533 int res_id, 1534 uint32 grp_flags, 1535 int grp_size, 1536 int *grp_done, 1537 const int *count, 1538 const int *elem, 1539 int *status); 1540 1541 /* 1542 * Function 1543 * shr_mres_check_all_group 1544 * Purpose 1545 * Check the status of a group of specific elements 1546 * Parameters 1547 * (IN) handle : handle for the instance to access 1548 * (IN) res_id : which resource to check 1549 * (IN) grp_flags : flags to apply to the whole group 1550 * (IN) grp_size : number of members this group 1551 * (OUT) grp_done : where to put how many members were completed 1552 * (IN) *count : elements in the block to check 1553 * (IN) *elem : the element to check (or base of the block to check) 1554 * (OUT) *status : where to put the check results 1555 * Returns 1556 * BCM_E_NONE if successful 1557 * BCM_E_* as appropriate otherwise 1558 * Notes 1559 * This behaves similarly to calling shr_mres_check, except that it places 1560 * the result in the provided status array rather than returning the 1561 * status for exactly one element. 1562 * 1563 * The result code from this function should be BCM_E_NONE unless there is 1564 * something obviously wrong with the arguments or an unexpected result is 1565 * encountered. Normally, grp_done would be set equal to grp_size, but if 1566 * there is an unexpected failure, grp_done will indicate how many 1567 * elements were checked before the failure. 1568 * 1569 * If the SHR_RES_ALLOC_GROUP_ATOMIC is set, this function will continue 1570 * to the end of the provided list despite any errors that occur once it 1571 * starts to check the provided list, and will return BCM_E_NONE if it 1572 * gets that far, but it will still return an appropriate error if it is 1573 * unable to begin checking the list due to some error. 1574 * 1575 * This function is essentially a wrapper around shr_mres_check_all. 1576 */ 1577 extern int 1578 shr_mres_check_all_group(shr_mres_handle_t handle, 1579 int res_id, 1580 uint32 grp_flags, 1581 int grp_size, 1582 int *grp_done, 1583 const int *count, 1584 const int *elem, 1585 int *status); 1586 1587 /* 1588 * Function 1589 * shr_mres_check_all_tag_group 1590 * Purpose 1591 * Check the status of a group of specific elements 1592 * Parameters 1593 * (IN) handle : handle for the instance to access 1594 * (IN) res_id : which resource to check 1595 * (IN) grp_flags : flags to apply to the whole group 1596 * (IN) grp_size : number of members this group 1597 * (OUT) grp_done : where to put how many members were completed 1598 * (IN) **tag : the tags to be used in the check 1599 * (IN) *count : elements in the block to check 1600 * (IN) *elem : the element to check (or base of the block to check) 1601 * (OUT) *status : where to put the check results 1602 * Returns 1603 * BCM_E_NONE if successful 1604 * BCM_E_* as appropriate otherwise 1605 * Notes 1606 * This behaves similarly to calling shr_mres_check, except that it places 1607 * the result in the provided status array rather than returning the 1608 * status for exactly one element. 1609 * 1610 * The result code from this function should be BCM_E_NONE unless there is 1611 * something obviously wrong with the arguments or an unexpected result is 1612 * encountered. Normally, grp_done would be set equal to grp_size, but if 1613 * there is an unexpected failure, grp_done will indicate how many 1614 * elements were checked before the failure. 1615 * 1616 * If the SHR_RES_ALLOC_GROUP_ATOMIC is set, this function will continue 1617 * to the end of the provided list despite any errors that occur once it 1618 * starts to check the provided list, and will return BCM_E_NONE if it 1619 * gets that far, but it will still return an appropriate error if it is 1620 * unable to begin checking the list due to some error. 1621 * 1622 * This function is essentially a wrapper around shr_mres_check_all_tag. 1623 */ 1624 extern int 1625 shr_mres_check_all_tag_group(shr_mres_handle_t handle, 1626 int res_id, 1627 uint32 grp_flags, 1628 int grp_size, 1629 int *grp_done, 1630 const void **tag, 1631 const int *count, 1632 const int *elem, 1633 int *status); 1634 1635 /* 1636 * Function 1637 * shr_mres_dump 1638 * Purpose 1639 * Diagnostic dump of a unit's resource management information 1640 * Parameters 1641 * (IN) handle : handle for the instance to access 1642 * Returns 1643 * BCM_E_NONE if successful 1644 * BCM_E_* as appropriate otherwise 1645 */ 1646 extern int 1647 shr_mres_dump(shr_mres_handle_t handle); 1648 1649 /****************************************************************************** 1650 * 1651 * Unit based shared resource management (global within a unit) 1652 * 1653 * These functions are intended for use when resources are common between 1654 * multiple modules on a single unit, or can be used in that way. 1655 */ 1656 1657 /* 1658 * Function 1659 * shr_res_init 1660 * Purpose 1661 * Initialize the resource manager for the unit 1662 * Parameters 1663 * (IN) unit : unit number of the device 1664 * (IN) num_res_types : number of resource types for the unit 1665 * (IN) num_res_pools : number of resource pools for the unit 1666 * Returns 1667 * BCM_E_NONE if successful 1668 * BCM_E_* as appropriate otherwise 1669 * Notes 1670 * Invokes shr_mres_create for the unit global resource intance. 1671 */ 1672 extern int 1673 shr_res_init(int unit, 1674 int num_res_types, 1675 int num_res_pools); 1676 1677 /* 1678 * Function 1679 * shr_res_get 1680 * Purpose 1681 * Get number of resource pools and types configured for a unit 1682 * Parameters 1683 * (IN) unit : unit number of the device 1684 * (OUT) num_res_types : where to put number of resource types for unit 1685 * (OUT) num_res_pools : where to put number of resource pools for unit 1686 * Returns 1687 * BCM_E_NONE if successful 1688 * BCM_E_* as appropriate otherwise 1689 * Notes 1690 * Invokes shr_mres_get against the unit global resource instance. 1691 */ 1692 extern int 1693 shr_res_get(int unit, 1694 int *num_res_types, 1695 int *num_res_pools); 1696 1697 /* 1698 * Function 1699 * shr_res_pool_set 1700 * Purpose 1701 * Configure a resource pool for the unit 1702 * Parameters 1703 * (IN) unit : unit number of the device 1704 * (IN) pool_id : which pool to configure (0..max_res_pools-1) 1705 * (IN) manager : which manager to use for this pool 1706 * (IN) low_id : lowest valid resource element ID in this pool 1707 * (IN) count : number of valid resource elements in this pool 1708 * (IN) extras : pointer to extra information for the manager type 1709 * (IN) name : pointer to string naming the pool 1710 * Returns 1711 * BCM_E_NONE if successful 1712 * BCM_E_* as appropriate otherwise 1713 * Notes 1714 * Invokes shr_mres_pool_set against the unit global resource instance. 1715 */ 1716 extern int 1717 shr_res_pool_set(int unit, 1718 int pool_id, 1719 shr_res_allocator_t manager, 1720 int low_id, 1721 int count, 1722 const void *extras, 1723 const char *name); 1724 1725 /* 1726 * Function 1727 * shr_res_pool_unset 1728 * Purpose 1729 * Destroy a resource pool for the unit 1730 * Parameters 1731 * (IN) unit : unit number of the device 1732 * (IN) pool_id : which pool to configure (0..max_res_pools-1) 1733 * Returns 1734 * BCM_E_NONE if successful 1735 * BCM_E_* as appropriate otherwise 1736 * Notes 1737 * Invokes shr_mres_pool_unset against the unit global resource instance. 1738 */ 1739 extern int 1740 shr_res_pool_unset(int unit, 1741 int pool_id); 1742 1743 /* 1744 * Function 1745 * shr_res_pool_get 1746 * Purpose 1747 * Get configuration for a resource pool on a particular unit 1748 * Parameters 1749 * (IN) unit : unit number of the device 1750 * (IN) pool_id : which pool to query (0..max_res_pools-1) 1751 * (OUT) manager : where to put manager that is used for this pool 1752 * (OUT) low_id : where to put low ID value for this pool 1753 * (OUT) count : where to put count value for this pool 1754 * (OUT) extras : where to put pointer to extras for this pool 1755 * (OUT) name : where to put pointer to name for this pool 1756 * Returns 1757 * BCM_E_NONE if successful 1758 * BCM_E_* as appropriate otherwise 1759 * Notes 1760 * Invokes shr_mres_pool_get against the unit global resource instance. 1761 */ 1762 extern int 1763 shr_res_pool_get(int unit, 1764 int pool_id, 1765 shr_res_allocator_t *manger, 1766 int *low_id, 1767 int *count, 1768 const void **extras, 1769 const char **name); 1770 1771 /* 1772 * Function 1773 * shr_res_pool_info_get 1774 * Purpose 1775 * Get status information for a resource pool 1776 * Parameters 1777 * (IN) unit : unit number of the device 1778 * (IN) pool_id : which pool to query (0..max_res_pools-1) 1779 * (OUT) info : where to put information about this pool 1780 * Returns 1781 * BCM_E_NONE if successful 1782 * BCM_E_* as appropriate otherwise 1783 * Notes 1784 * Outbound arguments may be NULL for this call; any NULL outbound 1785 * argument(s) will simply not be filled in. 1786 */ 1787 extern int 1788 shr_res_pool_info_get(int unit, 1789 int pool_id, 1790 shr_res_pool_info_t *info); 1791 1792 /* 1793 * Function 1794 * shr_res_type_set 1795 * Purpose 1796 * Configure a resource type 1797 * Parameters 1798 * (IN) unit : unit number of the device 1799 * (IN) res_id : which resource to configure (0..max_res_types-1) 1800 * (IN) pool_id : which pool this resource uses (0..max_res_pools-1) 1801 * (IN) elem_size : number of pool elements per element of this resource 1802 * (IN) name : pointer to string naming the type 1803 * Returns 1804 * BCM_E_NONE if successful 1805 * BCM_E_* as appropriate otherwise 1806 * Notes 1807 * Invokes shr_mres_type_set against the unit global resource instance. 1808 */ 1809 extern int 1810 shr_res_type_set(int unit, 1811 int res_id, 1812 int pool_id, 1813 int elem_size, 1814 const char *name); 1815 1816 /* 1817 * Function 1818 * shr_res_type_unset 1819 * Purpose 1820 * Destroy a resource type 1821 * Parameters 1822 * (IN) unit : unit number of the device 1823 * (IN) res_id : which resource to configure (0..max_res_types-1) 1824 * Returns 1825 * BCM_E_NONE if successful 1826 * BCM_E_* as appropriate otherwise 1827 * Notes 1828 * Invokes shr_mres_type_unset against the unit global resource instance. 1829 */ 1830 extern int 1831 shr_res_type_unset(int unit, 1832 int res_id); 1833 1834 /* 1835 * Function 1836 * shr_res_type_get 1837 * Purpose 1838 * Get information about a resource type 1839 * Parameters 1840 * (IN) unit : unit number of the device 1841 * (IN) res_id : which resource to query (0..max_res_types-1) 1842 * (OUT) pool_id : where to put pool ID 1843 * (OUT) elem_size : where to put element size 1844 * (OUT) name : where to put name pointer 1845 * Returns 1846 * BCM_E_NONE if successful 1847 * BCM_E_* as appropriate otherwise 1848 * Notes 1849 * Invokes shr_mres_type_get against the unit global resource instance. 1850 */ 1851 extern int 1852 shr_res_type_get(int unit, 1853 int res_id, 1854 int *pool_id, 1855 int *elem_size, 1856 const char **name); 1857 1858 /* 1859 * Function 1860 * shr_res_type_info_get 1861 * Purpose 1862 * Get status information for a resource type 1863 * Parameters 1864 * (IN) unit : unit number of the device 1865 * (IN) res_id : which resource to query (0..max_res_types-1) 1866 * (OUT) info : where to put information about this type 1867 * Returns 1868 * BCM_E_NONE if successful 1869 * BCM_E_* as appropriate otherwise 1870 * Notes 1871 * Outbound arguments may be NULL for this call; any NULL outbound 1872 * argument(s) will simply not be filled in. 1873 */ 1874 extern int 1875 shr_res_type_info_get(int unit, 1876 int res_id, 1877 shr_res_type_info_t *info); 1878 1879 /* 1880 * Function 1881 * shr_res_detach 1882 * Purpose 1883 * Remove all resource management for a unit 1884 * Parameters 1885 * (IN) unit : unit number of the device 1886 * Returns 1887 * BCM_E_NONE if successful 1888 * BCM_E_* as appropriate otherwise 1889 * Notes 1890 * Invokes shr_mres_destroy against the unit global resource instance, and 1891 * then overwrites the handle with NULL. 1892 */ 1893 extern int 1894 shr_res_detach(int unit); 1895 1896 /* 1897 * Function 1898 * shr_res_alloc 1899 * Purpose 1900 * Allocate an element or block of elements of a particular resource 1901 * Parameters 1902 * (IN) unit : unit number of the device 1903 * (IN) res_id : which resource to allocate 1904 * (IN) flags : flags providing specifics of what/how to allocate 1905 * (IN) count : elements to allocate in this block 1906 * (IN/OUT) elem : where to put the allocated element (block base) 1907 * Returns 1908 * BCM_E_NONE if successful 1909 * BCM_E_* as appropriate otherwise 1910 * Notes 1911 * Invokes shr_mres_alloc against the unit global resource instance. 1912 */ 1913 extern int 1914 shr_res_alloc(int unit, 1915 int res_id, 1916 uint32 flags, 1917 int count, 1918 int *elem); 1919 1920 /* 1921 * Function 1922 * shr_res_alloc_tag 1923 * Purpose 1924 * Allocate an element or block of elements of a particular resource, 1925 * assuring all of the elements have the same tag. 1926 * Parameters 1927 * (IN) unit : unit number of the device 1928 * (IN) res_id : which resource to allocate 1929 * (IN) flags : flags providing specifics of what/how to allocate 1930 * (IN) tag : pointer to the tag for the elements 1931 * (IN) count : elements to allocate in this block 1932 * (IN/OUT) elem : where to put the allocated element (block base) 1933 * Returns 1934 * BCM_E_NONE if successful 1935 * BCM_E_* as appropriate otherwise 1936 * Notes 1937 * Invokes shr_mres_alloc_tag against the unit global resource instance. 1938 */ 1939 extern int 1940 shr_res_alloc_tag(int unit, 1941 int res_id, 1942 uint32 flags, 1943 const void *tag, 1944 int count, 1945 int *elem); 1946 1947 /* 1948 * Function 1949 * shr_res_alloc_align 1950 * Purpose 1951 * Allocate an element or block of elements of a particular resource, 1952 * using a base alignment and an offset. 1953 * Parameters 1954 * (IN) unit : unit number of the device 1955 * (IN) res_id : which resource to allocate 1956 * (IN) flags : flags providing specifics of what/how to allocate 1957 * (IN) align : base alignment 1958 * (IN) offset : offest from base alignment for first element 1959 * (IN) count : elements to allocate in this block 1960 * (IN/OUT) elem : where to put the allocated element (block base) 1961 * Returns 1962 * BCM_E_NONE if successful 1963 * BCM_E_* as appropriate otherwise 1964 * Notes 1965 * Invokes shr_mres_alloc_align against the unit global resource instance. 1966 */ 1967 extern int 1968 shr_res_alloc_align(int unit, 1969 int res_id, 1970 uint32 flags, 1971 int align, 1972 int offset, 1973 int count, 1974 int *elem); 1975 1976 /* 1977 * Function 1978 * shr_res_alloc_align_sparse 1979 * Purpose 1980 * Allocate a sparse block of elements of a particular resource, using a 1981 * base alignment and an offset. 1982 * Parameters 1983 * (IN) unit : unit number of the device 1984 * (IN) res_id : which resource to allocate 1985 * (IN) flags : flags providing specifics of what/how to allocate 1986 * (IN) align : base alignment 1987 * (IN) offset : offest from base alignment for first element 1988 * (IN) pattern : pattern of elements to allocate 1989 * (IN) length : length of pattern 1990 * (IN) repeats : number of iterations of the pattern 1991 * (IN/OUT) elem : where to put the allocated element (block base) 1992 * Returns 1993 * BCM_E_NONE if successful 1994 * BCM_E_* as appropriate otherwise 1995 * Notes 1996 * Invokes shr_mres_alloc_align_sparse against the unit global resource 1997 * instance. 1998 */ 1999 extern int 2000 shr_res_alloc_align_sparse(int unit, 2001 int res_id, 2002 uint32 flags, 2003 int align, 2004 int offset, 2005 uint32 pattern, 2006 int length, 2007 int repeats, 2008 int *elem); 2009 2010 /* 2011 * Function 2012 * shr_res_alloc_align_tag 2013 * Purpose 2014 * Allocate an element or block of elements of a particular resource, 2015 * using a base alignment and an offset, and assuring the elements all 2016 * have the same tag. 2017 * Parameters 2018 * (IN) unit : unit number of the device 2019 * (IN) res_id : which resource to allocate 2020 * (IN) flags : flags providing specifics of what/how to allocate 2021 * (IN) align : base alignment 2022 * (IN) offset : offest from base alignment for first element 2023 * (IN) tag : pointer to the tag for the elements 2024 * (IN) count : elements to allocate in this block 2025 * (IN/OUT) elem : where to put the allocated element (block base) 2026 * Returns 2027 * BCM_E_NONE if successful 2028 * BCM_E_* as appropriate otherwise 2029 * Notes 2030 * Invokes shr_mres_alloc_align_tag against the unit global resource 2031 * instance. 2032 */ 2033 extern int 2034 shr_res_alloc_align_tag(int unit, 2035 int res_id, 2036 uint32 flags, 2037 int align, 2038 int offset, 2039 const void *tag, 2040 int count, 2041 int *elem); 2042 2043 /* 2044 * Function 2045 * shr_res_free 2046 * Purpose 2047 * Free an element or block of elements of a particular resource 2048 * Parameters 2049 * (IN) unit : unit number of the device 2050 * (IN) res_id : which resource to free 2051 * (IN) count : elements in the block to free 2052 * (IN) elem : the element to free (or base of the block to free) 2053 * Returns 2054 * BCM_E_NONE if successful 2055 * BCM_E_* as appropriate otherwise 2056 * Notes 2057 * Invokes shr_mres_free against the unit global resource instance. 2058 */ 2059 extern int 2060 shr_res_free(int unit, 2061 int res_id, 2062 int count, 2063 int elem); 2064 2065 /* 2066 * Function 2067 * shr_res_free 2068 * Purpose 2069 * Free an element or block of elements of a particular resource, then get 2070 * flags about that resource. 2071 * Parameters 2072 * (IN) unit : unit number of the device 2073 * (IN) res_id : which resource to free 2074 * (IN) count : elements in the block to free 2075 * (IN) elem : the element to free (or base of the block to free) 2076 * (OUT) flags : where to put the flags 2077 * Returns 2078 * BCM_E_NONE if successful 2079 * BCM_E_* as appropriate otherwise 2080 * Notes 2081 * Invokes shr_mres_free_and_status against the unit global resource 2082 * instance. 2083 */ 2084 extern int 2085 shr_res_free_and_status(int unit, 2086 int res_id, 2087 int count, 2088 int elem, 2089 uint32 *flags); 2090 2091 /* 2092 * Function 2093 * shr_res_free 2094 * Purpose 2095 * Free a sparse block of elements of a particular resource 2096 * Parameters 2097 * (IN) unit : unit number of the device 2098 * (IN) res_id : which resource to free 2099 * (IN) pattern: pattern of elements to free 2100 * (IN) length : length of the pattern 2101 * (IN) repeats: number of iterations of the pattern 2102 * (IN) elem : the element to free (or base of the block to free) 2103 * Returns 2104 * BCM_E_NONE if successful 2105 * BCM_E_* as appropriate otherwise 2106 * Notes 2107 * Invokes shr_mres_free_sparse against the unit global resource instance. 2108 */ 2109 extern int 2110 shr_res_free_sparse(int unit, 2111 int res_id, 2112 uint32 pattern, 2113 int length, 2114 int repeats, 2115 int elem); 2116 2117 /* 2118 * Function 2119 * shr_res_free 2120 * Purpose 2121 * Free a sparse block of elements of a particular resource, then get 2122 * flags about that resource. 2123 * Parameters 2124 * (IN) unit : unit number of the device 2125 * (IN) res_id : which resource to free 2126 * (IN) pattern: pattern of elements to free 2127 * (IN) length : length of the pattern 2128 * (IN) repeats: number of iterations of the pattern 2129 * (IN) elem : the element to free (or base of the block to free) 2130 * (OUT) flags : where to put the flags 2131 * Returns 2132 * BCM_E_NONE if successful 2133 * BCM_E_* as appropriate otherwise 2134 * Notes 2135 * Invokes shr_mres_free_sparse_and_status against the unit global 2136 * resource instance. 2137 */ 2138 extern int 2139 shr_res_free_sparse_and_status(int unit, 2140 int res_id, 2141 uint32 pattern, 2142 int length, 2143 int repeats, 2144 int elem, 2145 uint32 *flags); 2146 2147 /* 2148 * Function 2149 * shr_res_check 2150 * Purpose 2151 * Check the status of a specific element 2152 * Parameters 2153 * (IN) unit : unit number of the device 2154 * (IN) res_id : which resource to check 2155 * (IN) count : elements in the block to check 2156 * (IN) elem : the element to check (or base of the block to check) 2157 * Returns 2158 * BCM_E_NOT_FOUND if the element is not in use 2159 * BCM_E_EXISTS if the element is in use 2160 * BCM_E_PARAM if the element is not valid 2161 * BCM_E_* as appropriate otherwise 2162 * Notes 2163 * Invokes shr_mres_check against the unit global resource instance. 2164 */ 2165 extern int 2166 shr_res_check(int unit, 2167 int res_id, 2168 int count, 2169 int elem); 2170 2171 /* 2172 * Function 2173 * shr_res_check_all 2174 * Purpose 2175 * Check the status of a group of elements 2176 * Parameters 2177 * (IN) unit : unit number of the device 2178 * (IN) res_id : which resource to check 2179 * (IN) count : elements in the block to check 2180 * (IN) elem : the element to check (or base of the block to check) 2181 * Returns 2182 * BCM_E_EMPTY if none of the elements are in use 2183 * BCM_E_FULL if all of the elements are in use 2184 * BCM_E_CONFIG if elements are in use but block(s) do not match 2185 * BCM_E_EXISTS if some of the elements are in use but not all of them 2186 * BCM_E_PARAM if any of the elements is not valid 2187 * BCM_E_* as appropriate otherwise 2188 * Notes 2189 * Invokes shr_mres_check_all against the unit global resource instance. 2190 */ 2191 extern int 2192 shr_res_check_all(int unit, 2193 int res_id, 2194 int count, 2195 int elem); 2196 2197 /* 2198 * Function 2199 * shr_res_check_all 2200 * Purpose 2201 * Check the status of a group of elements 2202 * Parameters 2203 * (IN) unit : unit number of the device 2204 * (IN) res_id : which resource to check 2205 * (IN) count : elements in the block to check 2206 * (IN) elem : the element to check (or base of the block to check) 2207 * Returns 2208 * BCM_E_EMPTY if none of the elements are in use 2209 * BCM_E_FULL if all of the elements are in use 2210 * BCM_E_CONFIG if elements are in use but block(s) do not match 2211 * BCM_E_EXISTS if some of the elements are in use but not all of them 2212 * BCM_E_PARAM if any of the elements is not valid 2213 * BCM_E_* as appropriate otherwise 2214 * Notes 2215 * Invokes shr_mres_check_all_sparse against the unit global resource 2216 * instance. 2217 */ 2218 extern int 2219 shr_res_check_all_sparse(int unit, 2220 int res_id, 2221 uint32 pattern, 2222 int length, 2223 int repeats, 2224 int elem); 2225 2226 /* 2227 * Function 2228 * shr_res_check_all_tag 2229 * Purpose 2230 * Check the status of a group of elements 2231 * Parameters 2232 * (IN) unit : unit number of the device 2233 * (IN) res_id : which resource to check 2234 * (IN) tag : tag for checking 2235 * (IN) count : elements in the block to check 2236 * (IN) elem : the element to check (or base of the block to check) 2237 * Returns 2238 * BCM_E_EMPTY if none of the elements are in use 2239 * BCM_E_FULL if all of the elements are in use 2240 * BCM_E_CONFIG if elements are in use but block(s)/tag(s) do not match 2241 * BCM_E_EXISTS if some of the elements are in use but not all of them 2242 * BCM_E_PARAM if any of the elements is not valid 2243 * BCM_E_* as appropriate otherwise 2244 * Notes 2245 * Invokes shr_mres_check_all against the unit global resource instance. 2246 */ 2247 extern int 2248 shr_res_check_all_tag(int unit, 2249 int res_id, 2250 const void *tag, 2251 int count, 2252 int elem); 2253 2254 /* 2255 * Function 2256 * shr_res_alloc_group 2257 * Purpose 2258 * Allocate an group of elements or blocks of elements of a particular 2259 * resource 2260 * Parameters 2261 * (IN) unit : unit number of the device 2262 * (IN) res_id : which resource to allocate 2263 * (IN) grp_flags : flags to apply to the whole group 2264 * (IN) grp_size : number of members of the group 2265 * (OUT) grp_done : where to put how many members were completed 2266 * (IN) *flags : flags providing specifics of what/how to allocate 2267 * (IN) *count : elements to allocate in this block 2268 * (IN/OUT) *elem : where to put the allocated element (block base) 2269 * Returns 2270 * BCM_E_NONE if successful 2271 * BCM_E_* as appropriate otherwise 2272 * Notes 2273 * Invokes shr_mres_alloc_group against the unit global resource instance. 2274 */ 2275 extern int 2276 shr_res_alloc_group(int unit, 2277 int res_id, 2278 uint32 grp_flags, 2279 int grp_size, 2280 int *grp_done, 2281 const uint32 *flags, 2282 const int *count, 2283 int *elem); 2284 2285 /* 2286 * Function 2287 * shr_res_alloc_tag_group 2288 * Purpose 2289 * Allocate an group of elements or blocks of elements of a particular 2290 * resource 2291 * Parameters 2292 * (IN) unit : unit number of the device 2293 * (IN) res_id : which resource to allocate 2294 * (IN) grp_flags : flags to apply to the whole group 2295 * (IN) grp_size : number of members of the group 2296 * (OUT) grp_done : where to put how many members were completed 2297 * (IN) *flags : flags providing specifics of what/how to allocate 2298 * (IN) *tag : pointers to the tags for each block 2299 * (IN) *count : elements to allocate in this block 2300 * (IN/OUT) *elem : where to put the allocated element (block base) 2301 * Returns 2302 * BCM_E_NONE if successful 2303 * BCM_E_* as appropriate otherwise 2304 * Notes 2305 * Invokes shr_mres_alloc_group against the unit global resource instance. 2306 */ 2307 extern int 2308 shr_res_alloc_tag_group(int unit, 2309 int res_id, 2310 uint32 grp_flags, 2311 int grp_size, 2312 int *grp_done, 2313 const uint32 *flags, 2314 const void **tag, 2315 const int *count, 2316 int *elem); 2317 2318 /* 2319 * Function 2320 * shr_res_alloc_align_group 2321 * Purpose 2322 * Allocate an group of elements or blocks of elements of a particular 2323 * resource, with specified alignment and offset 2324 * Parameters 2325 * (IN) unit : unit number of the device 2326 * (IN) res_id : which resource to allocate 2327 * (IN) grp_flags : flags to apply to the whole group 2328 * (IN) grp_size : number of members of the group 2329 * (OUT) grp_done : where to put how many members were completed 2330 * (IN) *flags : flags providing specifics of what/how to allocate 2331 * (IN) *align : base alignment in this block 2332 * (IN) *offset : offest from base alignment for first elem in this blk 2333 * (IN) *count : elements to allocate in this block 2334 * (IN/OUT) *elem : where to put the allocated element (block base) 2335 * Returns 2336 * BCM_E_NONE if successful 2337 * BCM_E_* as appropriate otherwise 2338 * Notes 2339 * Invokes shr_mres_alloc_align_group against the unit global resource 2340 * instance. 2341 */ 2342 extern int 2343 shr_res_alloc_align_group(int unit, 2344 int res_id, 2345 uint32 grp_flags, 2346 int grp_size, 2347 int *grp_done, 2348 const uint32 *flags, 2349 const int *align, 2350 const int *offset, 2351 const int *count, 2352 int *elem); 2353 2354 /* 2355 * Function 2356 * shr_res_alloc_align_tag_group 2357 * Purpose 2358 * Allocate an group of elements or blocks of elements of a particular 2359 * resource, with specified alignment and offset 2360 * Parameters 2361 * (IN) unit : unit number of the device 2362 * (IN) res_id : which resource to allocate 2363 * (IN) grp_flags : flags to apply to the whole group 2364 * (IN) grp_size : number of members of the group 2365 * (OUT) grp_done : where to put how many members were completed 2366 * (IN) *flags : flags providing specifics of what/how to allocate 2367 * (IN) *align : base alignment in this block 2368 * (IN) *offset : offest from base alignment for first elem in this blk 2369 * (IN) *tag : pointers to the tags for each block 2370 * (IN) *count : elements to allocate in this block 2371 * (IN/OUT) *elem : where to put the allocated element (block base) 2372 * Returns 2373 * BCM_E_NONE if successful 2374 * BCM_E_* as appropriate otherwise 2375 * Notes 2376 * Invokes shr_mres_alloc_align_group against the unit global resource 2377 * instance. 2378 */ 2379 extern int 2380 shr_res_alloc_align_tag_group(int unit, 2381 int res_id, 2382 uint32 grp_flags, 2383 int grp_size, 2384 int *grp_done, 2385 const uint32 *flags, 2386 const int *align, 2387 const int *offset, 2388 const void **tag, 2389 const int *count, 2390 int *elem); 2391 2392 /* 2393 * Function 2394 * shr_res_free_group 2395 * Purpose 2396 * Free a group of elements or blocks of elements of a particular resource 2397 * Parameters 2398 * (IN) unit : unit number of the device 2399 * (IN) res_id : which resource to free 2400 * (IN) grp_flags : flags to apply to the whole group 2401 * (IN) grp_size : number of members this group 2402 * (OUT) grp_done : where to put how many members were completed 2403 * (IN) *count : elements in the block to free 2404 * (IN) *elem : the element to free (or base of the block to free) 2405 * Returns 2406 * BCM_E_NONE if successful 2407 * BCM_E_* as appropriate otherwise 2408 * Notes 2409 * Invokes shr_mres_free_group against the unit global resource instance. 2410 */ 2411 extern int 2412 shr_res_free_group(int unit, 2413 int res_id, 2414 uint32 grp_flags, 2415 int grp_size, 2416 int *grp_done, 2417 const int *count, 2418 const int *elem); 2419 2420 /* 2421 * Function 2422 * shr_res_free_group_and_status 2423 * Purpose 2424 * Free a group of elements or blocks of elements of a particular resource 2425 * and get status flags 2426 * Parameters 2427 * (IN) unit : unit number of the device 2428 * (IN) res_id : which resource to free 2429 * (IN) grp_flags : flags to apply to the whole group 2430 * (IN) grp_size : number of members this group 2431 * (OUT) grp_done : where to put how many members were completed 2432 * (IN) *count : elements in the block to free 2433 * (IN) *elem : the element to free (or base of the block to free) 2434 * (OUT) *status : where to put the status flags 2435 * Returns 2436 * BCM_E_NONE if successful 2437 * BCM_E_* as appropriate otherwise 2438 * Notes 2439 * Invokes shr_mres_free_group_and_status against the unit global resource 2440 * instance. 2441 */ 2442 extern int 2443 shr_res_free_group_and_status(int unit, 2444 int res_id, 2445 uint32 grp_flags, 2446 int grp_size, 2447 int *grp_done, 2448 const int *count, 2449 const int *elem, 2450 uint32 *status); 2451 2452 /* 2453 * Function 2454 * shr_res_check_group 2455 * Purpose 2456 * Check the status of a group of specific elements 2457 * Parameters 2458 * (IN) unit : unit number of the device 2459 * (IN) res_id : which resource to check 2460 * (IN) grp_flags : flags to apply to the whole group 2461 * (IN) grp_size : number of members this group 2462 * (OUT) grp_done : where to put how many members were completed 2463 * (IN) *count : elements in the block to check 2464 * (IN) *elem : the element to check (or base of the block to check) 2465 * (OUT) *status : where to put the check results 2466 * Returns 2467 * BCM_E_NONE if successful 2468 * BCM_E_* as appropriate otherwise 2469 * Notes 2470 * Invokes shr_mres_check_group against the unit global resource instance. 2471 */ 2472 extern int 2473 shr_res_check_group(int unit, 2474 int res_id, 2475 uint32 grp_flags, 2476 int grp_size, 2477 int *grp_done, 2478 const int *count, 2479 const int *elem, 2480 int *status); 2481 2482 /* 2483 * Function 2484 * shr_res_check_all_group 2485 * Purpose 2486 * Check the status of a group of specific blocks of elements 2487 * Parameters 2488 * (IN) unit : unit number of the device 2489 * (IN) res_id : which resource to check 2490 * (IN) grp_flags : flags to apply to the whole group 2491 * (IN) grp_size : number of members this group 2492 * (OUT) grp_done : where to put how many members were completed 2493 * (IN) *count : elements in the block to check 2494 * (IN) *elem : the element to check (or base of the block to check) 2495 * (OUT) *status : where to put the check results 2496 * Returns 2497 * BCM_E_NONE if successful 2498 * BCM_E_* as appropriate otherwise 2499 * Notes 2500 * Invokes shr_mres_check_all_group against the unit global resource 2501 * instance. 2502 */ 2503 extern int 2504 shr_res_check_all_group(int unit, 2505 int res_id, 2506 uint32 grp_flags, 2507 int grp_size, 2508 int *grp_done, 2509 const int *count, 2510 const int *elem, 2511 int *status); 2512 2513 /* 2514 * Function 2515 * shr_res_check_all_tag_group 2516 * Purpose 2517 * Check the status of a group of specific blocks of elements 2518 * Parameters 2519 * (IN) unit : unit number of the device 2520 * (IN) res_id : which resource to check 2521 * (IN) grp_flags : flags to apply to the whole group 2522 * (IN) grp_size : number of members this group 2523 * (OUT) grp_done : where to put how many members were completed 2524 * (IN) **tag : tags for the blocks to check 2525 * (IN) *count : elements in the block to check 2526 * (IN) *elem : the element to check (or base of the block to check) 2527 * (OUT) *status : where to put the check results 2528 * Returns 2529 * BCM_E_NONE if successful 2530 * BCM_E_* as appropriate otherwise 2531 * Notes 2532 * Invokes shr_mres_check_all_group against the unit global resource 2533 * instance. 2534 */ 2535 extern int 2536 shr_res_check_all_tag_group(int unit, 2537 int res_id, 2538 uint32 grp_flags, 2539 int grp_size, 2540 int *grp_done, 2541 const void **tag, 2542 const int *count, 2543 const int *elem, 2544 int *status); 2545 2546 /* 2547 * Function 2548 * shr_res_dump 2549 * Purpose 2550 * Diagnostic dump of a unit's resource management information 2551 * Parameters 2552 * (IN) unit : unit number of the device 2553 * Returns 2554 * BCM_E_NONE if successful 2555 * BCM_E_* as appropriate otherwise 2556 * Notes 2557 * Invokes shr_mres_dump against the unit global resource instance. 2558 */ 2559 extern int 2560 shr_res_dump(int unit); 2561 2562 #endif /* ndef _SHR_RESMGR_H */ 2563