sw_state_resmgr.h (69509B)
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 _SW_STATE_RESMGR_H_ 13 #define _SW_STATE_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/swstate/sw_state_res_bitmap.h> 20 #include <bcm/types.h> 21 22 /* 23 * Flags supported by the allocation system for each allocation. If any of 24 * these are provided as group flags, they are automatically applied to the 25 * entire group, whether the individual flags include them or not. 26 * 27 * SW_STATE_RES_ALLOC_WITH_ID indicates that the element ID is provided by the 28 * caller, and that specific element (or the specified block starting at that 29 * element) is being requested. The allocation must fail if the requested 30 * element/block is invalid or already in use. 31 * 32 * SW_STATE_RES_ALLOC_ALIGN_ZERO indicates that the _align_ allocators should align 33 * the block of elements with respect to zero, and not relative to the 34 * lowest element in the underlying pool. 35 * 36 * SW_STATE_RES_ALLOC_REPLACE is used with SW_STATE_RES_ALLOC_WITH_ID to indicate that 37 * the intent is to replace an existing block. Note the blocks must be of the 38 * same size (and tag if applicable) -- this does not 'realloc' a block; it 39 * only verifies that the block already exists as per the alloc request. 40 */ 41 #define SW_STATE_RES_ALLOC_SINGLE_FLAGS 0x0000001f 42 #define SW_STATE_RES_ALLOC_WITH_ID 0x00000001 43 #define SW_STATE_RES_ALLOC_ALIGN_ZERO 0x00000002 44 #define SW_STATE_RES_ALLOC_REPLACE 0x00000004 45 #define SW_STATE_RES_ALLOC_ALWAYS_CHECK_TAG 0x00000008 46 #define SW_STATE_RES_ALLOC_CHECK_ONLY 0x00000010 47 /* 48 * Flags supported by the allocation system for group allocation. Note these 49 * are specifically for the group call itself, not the individual blocks 50 * within the group call. 51 * 52 * SW_STATE_RES_ALLOC_GROUP_ATOMIC indicates that the allocation is to be 53 * considered atomic -- if there is any failure, back out all of it rather 54 * than stopping at the failure point. This can only be applied to the 55 * allocation call. There is no support to undo frees and aborting a check 56 * based upon the result being other than BCM_E_NONE makes no sense because 57 * check should always return some other result code. 58 */ 59 #define SW_STATE_RES_ALLOC_GROUP_FLAGS 0x00010000 60 #define SW_STATE_RES_ALLOC_GROUP_ATOMIC 0x00010000 61 62 /* 63 * For optimisation, there is a version of free that returns whether the last 64 * element of a type or pool has been freed by that free. 65 * 66 * SW_STATE_RES_FREED_TYPE_LAST_ELEM indicates that the last in-use element of a 67 * type was freed by the free call (or if the free call failed, that there 68 * were no elements of that type in use). 69 * 70 * SW_STATE_RES_FREED_POOL_LAST_ELEM indicates that the last in-use element of a 71 * pool was freed by the free call (or if the free call failed, that there 72 * were no elements of that pool in use). 73 */ 74 #define SW_STATE_RES_FREED_TYPE_LAST_ELEM 0x00000001 75 #define SW_STATE_RES_FREED_POOL_LAST_ELEM 0x00000002 76 77 /* 78 * That's the max length of types and pools' names. Trying to create a type or a pool 79 * with a longer name would return an error. 80 */ 81 #define SW_STATE_RES_NAME_MAX_LENGTH 50 82 83 /* 84 * This enum defines the supported allocation mechanisms. Each one has some 85 * of its own advantages and disadvantages. See the notes for each one if you 86 * need details to choose which might be best for a particular resource pool. 87 */ 88 typedef enum sw_state_res_allocator_e { 89 SW_STATE_RES_ALLOCATOR_BITMAP = 0, /* bitmap based allocator */ 90 SW_STATE_RES_ALLOCATOR_TAGGED_BITMAP, /* bitmap based allocator with tags */ 91 SW_STATE_RES_ALLOCATOR_COUNT /* last one indicates how many, not valid item */ 92 } sw_state_res_allocator_t; 93 94 /* 95 * This struct contains the extra arguments needed to configure a resource 96 * pool to be managed by the tagged_bitmap allocator. 97 */ 98 typedef struct sw_state_res_tagged_bitmap_extras_s { 99 int tag_length; /* tag length in bytes */ 100 int grain_size; /* number of elements per grain */ 101 } sw_state_res_tagged_bitmap_extras_t; 102 103 /* 104 * When fetching additional data about a pool (not available with 'pool_get'), 105 * the caller provides one of this structure to be filled in. 106 */ 107 typedef struct sw_state_res_pool_info_s { 108 int used; 109 int free; 110 } sw_state_res_pool_info_t; 111 112 /* 113 * When fetching additional data about a pool (not available with 'pool_get'), 114 * the caller provides one of this structure to be filled in. 115 * 116 * Since more than one type can be using a single pool, and each type can use 117 * a different number of elements of the underlying pool per each of its own 118 * elements, a value for 'free' would require some possibly considerable 119 * effort to figure out how many nonoverlapping requests could be made for the 120 * number of pool elements that one type element represents. It is simpler 121 * and reasonably consistent to not include it. 122 */ 123 typedef struct sw_state_res_type_info_s { 124 int used; 125 } sw_state_res_type_info_t; 126 127 128 typedef struct sw_state_res_name_s { 129 char name[SW_STATE_RES_NAME_MAX_LENGTH]; 130 } sw_state_res_name_t; 131 132 /* 133 * This describes how a single resource maps to an underlying pool. 134 * 135 * resPoolId is the ID of the resource pool on this unit from which this 136 * resource is drawn. 137 * 138 * resElemSize is the number of elements in the specified resource pool that 139 * must be taken to make a single element of this resource. Basically, any 140 * alloc/free of this resource will multiply the number of elements by this 141 * value to determine how many to alloc/free of the underlying pool. 142 * 143 * name is a string that names this resource. It is used only for diagnostic 144 * purposes. Internally, the provided name will be copied to the same cell as 145 * the structure, so the name array is really variable length. 146 */ 147 typedef struct _sw_state_res_type_desc_s { 148 int resPoolId; /* unit specific resource pool ID */ 149 int resElemSize; /* how many elems of this pool per this res */ 150 int refCount; /* number of elements allocated currently */ 151 sw_state_res_name_t name; /* descriptive name (for diagnostics) */ 152 } _sw_state_res_type_desc_t; 153 154 /* 155 * This describes a single resource pool on a unit. 156 * 157 * resManagerType is the ID of the reousrce manager that will be used to 158 * manage this resource pool on this unit. 159 * 160 * low is the minimum valid element of this resource. 161 * 162 * count is the number of valid elements of this resource. 163 * 164 * extras points to a struct (which will be appended to this during setup of 165 * this pool) that provides additional arguments to how the pool needs to be 166 * managed. This is provided because some of the supported allocation 167 * managers require more information than just the range of valid IDs. 168 * 169 * name is a string that names this resource. It is used only for diagnostic 170 * purposes. Internally, the provided name will be copied to the same cell as 171 * the structure, so the name array is really variable length. 172 * 173 * Note that the extras struct will be appended to the same memory cell as 174 * this struct, after the name, and so the pointer will not need to be freed 175 * when this is destroyed. 176 */ 177 typedef struct _sw_state_res_pool_desc_s { 178 sw_state_res_allocator_t resManagerType; /* which resoource manager to use */ 179 int low; /* minimum available element */ 180 int count; /* number of available elements */ 181 int refCount; /* number of types using this pool */ 182 int inuse; /* number of active elems this pool */ 183 uint32 resHandle; /* handle for this resource */ 184 sw_state_res_tagged_bitmap_extras_t 185 tagged_bmp_extras; /* Additional config for tagged bitmap. 186 Only allocate if in use. */ 187 sw_state_res_name_t name; /* descriptive name for diagnostics */ 188 } _sw_state_res_pool_desc_t; 189 190 191 /* 192 * This structure describes attributes about the unit, and includes lists 193 * that are applicable to the unit. Note that while resource IDs and resource 194 * types are unit-specific, the resource managers themselves are globally 195 * available to all units. 196 * 197 * resTypeCount indicates how many different resources on this unit are being 198 * managed through this system. It is possible for more than one resource to 199 * use the same resource pool, but it is not possible for one resource to use 200 * more than one resource pool. 201 * 202 * resPoolCount indicates how many different resource pools are being managed 203 * on this unit. 204 * 205 * res points to an array of resource descriptors, Each descriptor will map a 206 * single resource on the unit to its underlying resource pool. 207 * 208 * pool points to an array of resource pool descriptors. Each of these will 209 * describe a single resource pool on the unit and map to the manager that 210 * will be used for that particular pool. 211 */ 212 typedef struct _sw_state_res_unit_desc_s { 213 uint16 resTypeCount; /* maximum presented resource ID */ 214 uint16 resPoolCount; /* maximum resource pool ID */ 215 PARSER_HINT_ARR_PTR _sw_state_res_type_desc_t **res; /* array of type -> pool map pointers */ 216 PARSER_HINT_ARR_PTR _sw_state_res_pool_desc_t **pool; /* array of pool description pointers */ 217 } _sw_state_res_unit_desc_t; 218 219 /* A handle for a non-unit-based resource manager instance */ 220 typedef _sw_state_res_unit_desc_t *sw_state_mres_handle_t; 221 222 223 /****************************************************************************** 224 * 225 * Unit based shared resource management (global within a unit) 226 * 227 * These functions are intended for use when resources are common between 228 * multiple modules on a single unit, or can be used in that way. 229 */ 230 231 /* 232 * Function 233 * sw_state_res_init 234 * Purpose 235 * Initialize the resource manager for the unit 236 * Parameters 237 * (IN) unit : unit number of the device 238 * (IN) num_res_types : number of resource types for the unit 239 * (IN) num_res_pools : number of resource pools for the unit 240 * Returns 241 * BCM_E_NONE if successful 242 * BCM_E_* as appropriate otherwise 243 * Notes 244 * Resource types map to resource pools, from which the actual elements of 245 * the resources are drawn, and more than one type can pull elements from 246 * the same pool, so there should always be at least as many types as 247 * there are pools. 248 * 249 * The instance will be limited to the number of types and pools specified 250 * here, as the descriptor space will be allocated and cleared by this 251 * function. See below for how to configure types and pools. 252 */ 253 extern int 254 sw_state_res_init(int unit, 255 int num_res_types, 256 int num_res_pools); 257 258 /* 259 * Function 260 * sw_state_res_get 261 * Purpose 262 * Get number of resource pools and types configured for a unit 263 * Parameters 264 * (IN) unit : unit number of the device 265 * (OUT) num_res_types : where to put number of resource types for unit 266 * (OUT) num_res_pools : where to put number of resource pools for unit 267 * Returns 268 * BCM_E_NONE if successful 269 * BCM_E_* as appropriate otherwise 270 * Notes 271 * Outbound arguments may be NULL for this call; any NULL outbound 272 * argument(s) will simply not be filled in. 273 */ 274 extern int 275 sw_state_res_get(int unit, 276 int *num_res_types, 277 int *num_res_pools); 278 279 /* 280 * Function 281 * sw_state_res_pool_set 282 * Purpose 283 * Configure a resource pool for the unit 284 * Parameters 285 * (IN) unit : unit number of the device 286 * (IN) pool_id : which pool to configure (0..max_res_pools-1) 287 * (IN) manager : which manager to use for this pool 288 * (IN) low_id : lowest valid resource element ID in this pool 289 * (IN) count : number of valid resource elements in this pool 290 * (IN) extras : pointer to extra information for the manager type 291 * (IN) name : pointer to string naming the pool 292 * Returns 293 * BCM_E_NONE if successful 294 * BCM_E_* as appropriate otherwise 295 * Notes 296 * A resource pool must be configured before any resources can point to 297 * it, and can not be changed after resources point to it. 298 * 299 * The underlying resource management information will be created during 300 * this call. If this call is made again for the same resource pool, and 301 * there are no resources using this pool, the old information will be 302 * destroyed and the new will be created in its stead, but if resources 303 * are already using this pool, the call will fail. 304 * 305 * Most of the allocation managers require some extra arguments, so the 306 * extras argument is likely obligatory. Each allocation manager has its 307 * own addiitonal arguments, for specific behavioural control or 308 * optimisation, and the correct extras type must be used accordingly. 309 * 310 * This must be called after create, and before a pool can be used, even 311 * before a resource can be assigned to the pool. 312 * 313 * Note that name and extras will be copied internally, and so the memory 314 * underlying those can be reused by the caller once this call completes. 315 */ 316 extern int 317 sw_state_res_pool_set(int unit, 318 int pool_id, 319 sw_state_res_allocator_t manager, 320 int low_id, 321 int count, 322 const void *extras, 323 const char *name); 324 325 /* 326 * Function 327 * sw_state_res_pool_unset 328 * Purpose 329 * Destroy a resource pool for the unit 330 * Parameters 331 * (IN) unit : unit number of the device 332 * (IN) pool_id : which pool to configure (0..max_res_pools-1) 333 * Returns 334 * BCM_E_NONE if successful 335 * BCM_E_* as appropriate otherwise 336 * Notes 337 * Destroys the resource pool only if there are no types using the pool. 338 * 339 * It will report an error (though the pool will be destroyed) if there 340 * appear to be elements in use but no types using the pool. 341 */ 342 extern int 343 sw_state_res_pool_unset(int unit, 344 int pool_id); 345 346 /* 347 * Function 348 * sw_state_res_pool_get 349 * Purpose 350 * Get configuration for a resource pool on a particular unit 351 * Parameters 352 * (IN) unit : unit number of the device 353 * (IN) pool_id : which pool to query (0..max_res_pools-1) 354 * (OUT) manager : where to put manager that is used for this pool 355 * (OUT) low_id : where to put low ID value for this pool 356 * (OUT) count : where to put count value for this pool 357 * (OUT) extras : where to put pointer to extras for this pool 358 * (OUT) name : where to put pointer to name for this pool 359 * Returns 360 * BCM_E_NONE if successful 361 * BCM_E_* as appropriate otherwise 362 * Notes 363 * Currently only the tag bitmap extras can be returned by this function. 364 * 365 * Outbound arguments may be NULL for this call; any NULL outbound 366 * argument(s) will simply not be filled in. 367 */ 368 extern int 369 sw_state_res_pool_get(int unit, 370 int pool_id, 371 sw_state_res_allocator_t *manger, 372 int *low_id, 373 int *count, 374 sw_state_res_tagged_bitmap_extras_t *extras, 375 sw_state_res_name_t *name); 376 377 /* 378 * Function 379 * sw_state_res_pool_info_get 380 * Purpose 381 * Get status information for a resource pool 382 * Parameters 383 * (IN) unit : unit number of the device 384 * (IN) pool_id : which pool to query (0..max_res_pools-1) 385 * (OUT) info : where to put information about this pool 386 * Returns 387 * BCM_E_NONE if successful 388 * BCM_E_* as appropriate otherwise 389 * Notes 390 * Outbound arguments may be NULL for this call; any NULL outbound 391 * argument(s) will simply not be filled in. 392 */ 393 extern int 394 sw_state_res_pool_info_get(int unit, 395 int pool_id, 396 sw_state_res_pool_info_t *info); 397 398 /* 399 * Function 400 * sw_state_res_type_set 401 * Purpose 402 * Configure a resource type 403 * Parameters 404 * (IN) unit : unit number of the device 405 * (IN) res_id : which resource to configure (0..max_res_types-1) 406 * (IN) pool_id : which pool this resource uses (0..max_res_pools-1) 407 * (IN) elem_size : number of pool elements per element of this resource 408 * (IN) name : pointer to string naming the type 409 * Returns 410 * BCM_E_NONE if successful 411 * BCM_E_* as appropriate otherwise 412 * Notes 413 * More than one resource can use the same pool, but a single resource can 414 * only use one pool. 415 * 416 * If this is called after a resource has elements allocated, it will 417 * fail. If it is called before a resource has elements allocated, it 418 * will map the resource so it uses the specified pool. 419 * 420 * This must be called after init and after the pool it uses has been 421 * configured, and before the associted resource can be used. 422 * 423 * elem_size indicates how many of the underlying pool elements are 424 * required to make a single element of this resource. Some allocators do 425 * not support more than a single element being allocated at a time, and 426 * so the resource manager will try to allocate contiguous blocks of the 427 * specified number of pool elements, but it is possible this will fail. 428 * 429 * Note that name will be copied internally, and so the underlying memory 430 * can be reused by the caller once this call completes. 431 */ 432 extern int 433 sw_state_res_type_set(int unit, 434 int res_id, 435 int pool_id, 436 int elem_size, 437 const char *name); 438 439 /* 440 * Function 441 * sw_state_res_type_unset 442 * Purpose 443 * Destroy a resource type 444 * Parameters 445 * (IN) unit : unit number of the device 446 * (IN) res_id : which resource to configure (0..max_res_types-1) 447 * Returns 448 * BCM_E_NONE if successful 449 * BCM_E_* as appropriate otherwise 450 * Notes 451 * Will not destroy a resource type if elements of that resource are still 452 * in use. 453 */ 454 extern int 455 sw_state_res_type_unset(int unit, 456 int res_id); 457 458 /* 459 * Function 460 * sw_state_res_type_get 461 * Purpose 462 * Get information about a resource type 463 * Parameters 464 * (IN) unit : unit number of the device 465 * (IN) res_id : which resource to query (0..max_res_types-1) 466 * (OUT) pool_id : where to put pool ID 467 * (OUT) elem_size : where to put element size 468 * (OUT) name : where to put name pointer 469 * Returns 470 * BCM_E_NONE if successful 471 * BCM_E_* as appropriate otherwise 472 * Notes 473 * Name will point to internal data for the type and MUST NOT BE MODIFIED 474 * by the caller. If the caller wants to change the name, the type will 475 * have to be reconfigured with sw_state_res_type_set. If the caller wants to 476 * use the name in a destructive manner, the caller must copy the name to 477 * a local buffer first and use that buffer. 478 * 479 * Outbound arguments may be NULL for this call; any NULL outbound 480 * argument(s) will simply not be filled in. 481 */ 482 extern int 483 sw_state_res_type_get(int unit, 484 int res_id, 485 int *pool_id, 486 int *elem_size, 487 sw_state_res_name_t *name); 488 489 /* 490 * Function 491 * sw_state_res_type_info_get 492 * Purpose 493 * Get status information for a resource type 494 * Parameters 495 * (IN) unit : unit number of the device 496 * (IN) res_id : which resource to query (0..max_res_types-1) 497 * (OUT) info : where to put information about this type 498 * Returns 499 * BCM_E_NONE if successful 500 * BCM_E_* as appropriate otherwise 501 * Notes 502 * Outbound arguments may be NULL for this call; any NULL outbound 503 * argument(s) will simply not be filled in. 504 */ 505 extern int 506 sw_state_res_type_info_get(int unit, 507 int res_id, 508 sw_state_res_type_info_t *info); 509 510 511 /* 512 * Function 513 * sw_state_res_type_status_get 514 * Purpose 515 * Get status information for a resource type: full, empty, or neither. 516 * Parameters 517 * (IN) unit : unit number of the device 518 * (IN) res_id : which resource to query (0..max_res_types-1) 519 * Returns 520 * BCM_E_FULL if resource is full 521 * BCM_E_EMPTY if resrouce is empty 522 * BCM_E_NONE if resource is neither full nor empty 523 * BCM_E_* as appropriate otherwise 524 * Notes 525 * If a pool still has free resources, but not enough for the type, then 526 * BCM_E_FULL will be returned. Another type using the pool with less 527 * resources per allocation will still be able to allocate. 528 */ 529 extern int 530 sw_state_res_type_status_get(int unit, 531 int res_id); 532 533 /* 534 * Function 535 * sw_state_res_detach 536 * Purpose 537 * Remove all resource management for a unit 538 * Parameters 539 * (IN) unit : unit number of the device 540 * Returns 541 * BCM_E_NONE if successful 542 * BCM_E_* as appropriate otherwise 543 * Notes 544 * This will destroy all of the resource pools, then tear down the rest of 545 * the resource management for the instance. 546 */ 547 extern int 548 sw_state_res_detach(int unit); 549 550 /* 551 * Function 552 * sw_state_res_alloc 553 * Purpose 554 * Allocate an element or block of elements of a particular resource 555 * Parameters 556 * (IN) unit : unit number of the device 557 * (IN) res_id : which resource to allocate 558 * (IN) flags : flags providing specifics of what/how to allocate 559 * (IN) count : elements to allocate in this block 560 * (IN/OUT) elem : where to put the allocated element (block base) 561 * Returns 562 * BCM_E_NONE if successful 563 * BCM_E_* as appropriate otherwise 564 * Notes 565 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 566 * the WITH_ID flag is not specified. 567 * 568 * This will allocate a single block of the requested number of elements 569 * of this resource (each of which may be a number of elements taken from 570 * the underlying pool). Some underlying managers do not support more 571 * than single element blocks, and while the manager will try to allocate 572 * a contiguous block in such case, it is possible that it will fail even 573 * if there are enough underlying elements available for the request. 574 * 575 * Partial blocks will not be allocated. 576 * 577 * The caller must track how many elements were requested and provide that 578 * number when freeing the block. 579 */ 580 extern int 581 sw_state_res_alloc(int unit, 582 int res_id, 583 uint32 flags, 584 int count, 585 int *elem); 586 587 /* 588 * Function 589 * sw_state_res_alloc_tag 590 * Purpose 591 * Allocate an element or block of elements of a particular resource, 592 * assuring all of the elements have the same tag. 593 * Parameters 594 * (IN) unit : unit number of the device 595 * (IN) res_id : which resource to allocate 596 * (IN) flags : flags providing specifics of what/how to allocate 597 * (IN) tag : pointer to the tag for the elements 598 * (IN) count : elements to allocate in this block 599 * (IN/OUT) elem : where to put the allocated element (block base) 600 * Returns 601 * BCM_E_NONE if successful 602 * BCM_E_* as appropriate otherwise 603 * Notes 604 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 605 * the WITH_ID flag is not specified. 606 * 607 * The tag pointer is a pointer to the value that will be used for tagging 608 * the requested block of elements. Note that since tags are a number of 609 * bytes starting at the pointer, the tag must already be masked as needed 610 * and should be stored in something no larger than the number of bytes 611 * that was specified as tag size when setting up the pool. 612 * 613 * This will allocate a single block of the requested number of elements 614 * of this resource (each of which may be a number of elements taken from 615 * the underlying pool). Some underlying managers do not support more 616 * than single element blocks, and while the manager will try to allocate 617 * a contiguous block in such case, it is possible that it will fail even 618 * if there are enough underlying elements available for the request. 619 * 620 * Some allocators do not support tagged mode. If allocating elements 621 * from a resource that has tagging, either this call or the alloc_tag 622 * call must be used so the tag can be specified. If neither this nor the 623 * alloc_tag call is used, the tag will be assumed to be all zeroes. 624 * 625 * Partial blocks will not be allocated. 626 * 627 * The caller must track how many elements were requested and provide that 628 * number when freeing the block. 629 */ 630 extern int 631 sw_state_res_alloc_tag(int unit, 632 int res_id, 633 uint32 flags, 634 const void *tag, 635 int count, 636 int *elem); 637 638 /* 639 * Function 640 * sw_state_res_alloc_align 641 * Purpose 642 * Allocate an element or block of elements of a particular resource, 643 * using a base alignment and an offset. 644 * Parameters 645 * (IN) unit : unit number of the device 646 * (IN) res_id : which resource to allocate 647 * (IN) flags : flags providing specifics of what/how to allocate 648 * (IN) align : base alignment 649 * (IN) offset : offest from base alignment for first element 650 * (IN) count : elements to allocate in this block 651 * (IN/OUT) elem : where to put the allocated element (block base) 652 * Returns 653 * BCM_E_NONE if successful 654 * BCM_E_* as appropriate otherwise 655 * Notes 656 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 657 * the WITH_ID flag is not specified. If WITH_ID is specified, and the 658 * requested base element does not comply with the indicated alignment, 659 * BCM_E_PARAM will be returned. 660 * 661 * This will allocate a single block of the requested number of elements 662 * of this resource (each of which may be a number of elements taken from 663 * the underlying pool). Some underlying managers do not support more 664 * than single element blocks, and while the manager will try to allocate 665 * a contiguous block in such case, it is possible that it will fail even 666 * if there are enough underlying elements available for the request. 667 * 668 * The first element of the returned block will be at ((n * align) + 669 * offset), where n is some integer. If it is not possible to allocate a 670 * block with the requested constraints, the call will fail. Note that 671 * the alignment is within the specified range of the resource, and not 672 * specifically aligned against the absolute value zero; to request the 673 * alignment be against zero, specify the ALIGN_ZERO flag. 674 * 675 * If offset >= align, BCM_E_PARAM. If align is zero or negative, it will 676 * be treated as if it were 1. 677 * 678 * Some allocators may not support this feature; some may place 679 * restrictions, such as the base alignment being a power of two, or not 680 * supporting the ALIGN_ZERO flag. 681 * 682 * Partial blocks will not be allocated. 683 * 684 * The caller must track how many elements were requested and provide that 685 * number when freeing the block. 686 */ 687 extern int 688 sw_state_res_alloc_align(int unit, 689 int res_id, 690 uint32 flags, 691 int align, 692 int offset, 693 int count, 694 int *elem); 695 696 /* 697 * Function 698 * sw_state_res_alloc_align_sparse 699 * Purpose 700 * Allocate a sparse block of elements of a particular resource, using a 701 * base alignment and an offset. 702 * Parameters 703 * (IN) unit : unit number of the device 704 * (IN) res_id : which resource to allocate 705 * (IN) flags : flags providing specifics of what/how to allocate 706 * (IN) align : base alignment 707 * (IN) offset : offest from base alignment for first element 708 * (IN) pattern : pattern of elements to allocate 709 * (IN) length : length of pattern 710 * (IN) repeats : number of iterations of the pattern 711 * (IN/OUT) elem : where to put the allocated element (block base) 712 * Returns 713 * BCM_E_NONE if successful 714 * BCM_E_* as appropriate otherwise 715 * Notes 716 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 717 * the WITH_ID flag is not specified. If WITH_ID is specified, and the 718 * requested base element does not comply with the indicated alignment, 719 * BCM_E_PARAM will be returned. 720 * 721 * This will allocate a single block of the requested number of elements 722 * of this resource. 723 * 724 * This function can not be used with a 'scaled' allocator. 725 * 726 * The first element of the returned block will be at ((n * align) + 727 * offset), where n is some integer. If it is not possible to allocate a 728 * block with the requested constraints, the call will fail. Note that 729 * the alignment is within the specified range of the resource, and not 730 * specifically aligned against the absolute value zero; to request the 731 * alignment be against zero, specify the ALIGN_ZERO flag. 732 * 733 * If offset >= align, BCM_E_PARAM. If align is zero or negative, it will 734 * be treated as if it were 1. 735 * 736 * Some allocators may not support this feature; some may place 737 * restrictions, such as the base alignment being a power of two, or not 738 * supporting the ALIGN_ZERO flag. 739 * 740 * Partial blocks will not be allocated. 741 * 742 * The pattern argument is a bitmap of the elements that are of interest 743 * in a single iteration of the pattern (and only the least significant 744 * 'length' bits are used; higher bits are ignored). The bit with value 745 * (1 << k) set indicates the element at (elem + k) must be in the block; 746 * clear it indicates the element at (elem + k) is not in the block. This 747 * repeats for as many iterations as indicated by 'repeats'. 748 * 749 * For example: 750 * align = 4, offs = 0, pattern = 0x7, length = 8, repeats = 2 would 751 * request a block of three elements, a gap of one element, and then 752 * another block of three elements, with the first allocated element 753 * aligned to a multiple of four. 754 * 755 * align = 8, offs = 1, pattern = 0x1, length = 2, repeats = 4 would 756 * request four oddly numbered elements with the first one allocated at 757 * (8 * n) + 1 where n is some arbitrary number. 758 * 759 * Note the bitmap is considered based at the requested alignment+offset, 760 * even if the least significant bit is not set, so it is probably 761 * simplest to ensure the LSb of pattern is set. 762 * 763 * For example: 764 * align = 4, offs = 0, pattern = 0xA, length = 4, repeats = 1 would 765 * request two elements, but the returned base element number would be 766 * (4 * n), while the actually allocated elements would be (4 * n) + 1 767 * and (4 * n) + 3. 768 * 769 * The caller must track the pattern, length and repeats values and 770 * provide these values along with the elem value when freeing the block. 771 * 772 * Any allocation made through this function must be freed using the 773 * sw_state_mres_free_sparse function. 774 * 775 * Sparse functions do not work with scaled resources. 776 */ 777 extern int 778 sw_state_res_alloc_align_sparse(int unit, 779 int res_id, 780 uint32 flags, 781 int align, 782 int offset, 783 uint32 pattern, 784 int length, 785 int repeats, 786 int *elem); 787 788 /* 789 * Function 790 * sw_state_res_alloc_align_tag 791 * Purpose 792 * Allocate an element or block of elements of a particular resource, 793 * using a base alignment and an offset, and assuring the elements all 794 * have the same tag. 795 * Parameters 796 * (IN) unit : unit number of the device 797 * (IN) res_id : which resource to allocate 798 * (IN) flags : flags providing specifics of what/how to allocate 799 * (IN) align : base alignment 800 * (IN) offset : offest from base alignment for first element 801 * (IN) tag : pointer to the tag for the elements 802 * (IN) count : elements to allocate in this block 803 * (IN/OUT) elem : where to put the allocated element (block base) 804 * Returns 805 * BCM_E_NONE if successful 806 * BCM_E_* as appropriate otherwise 807 * Notes 808 * The elem argument is IN if the WITH_ID flag is specified; it is OUT if 809 * the WITH_ID flag is not specified. If WITH_ID is specified, and the 810 * requested base element does not comply with the indicated alignment, 811 * BCM_E_PARAM will be returned. 812 * 813 * The tag pointer is a pointer to the value that will be used for tagging 814 * the requested block of elements. Note that since tags are a number of 815 * bytes starting at the pointer, the tag must already be masked as needed 816 * and should be stored in something no larger than the number of bytes 817 * that was specified as tag size when setting up the pool. 818 * 819 * This will allocate a single block of the requested number of elements 820 * of this resource (each of which may be a number of elements taken from 821 * the underlying pool), and ensuring all have the same tag (elements can 822 * be within the same grain as elements from other blocks only if the tag 823 * of the partial grain is equal to the tag for the new elements). Some 824 * underlying managers do not support more than single element blocks, and 825 * while the manager will try to allocate a contiguous block in such case, 826 * it is possible that it will fail even if there are enough underlying 827 * elements available for the request. 828 * 829 * The first element of the returned block will be at ((n * align) + 830 * offset), where n is some integer. If it is not possible to allocate a 831 * block with the requested constraints, the call will fail. Note that 832 * the alignment is within the specified range of the resource, and not 833 * specifically aligned against the absolute value zero; to request the 834 * alignment be against zero, specify the ALIGN_ZERO flag. 835 * 836 * If offset >= align, BCM_E_PARAM. If align is zero or negative, it will 837 * be treated as if it were 1. 838 * 839 * Some allocators may not support this feature; some may place 840 * restrictions, such as the base alignment being a power of two, or not 841 * supporting the ALIGN_ZERO flag. 842 * 843 * Some allocators do not support tagged mode. If allocating elements 844 * from a resource that has tagging, either this call or the alloc_tag 845 * call must be used so the tag can be specified. If neither this nor the 846 * alloc_tag call is used, the tag will be assumed to be all zeroes. 847 * 848 * Partial blocks will not be allocated. 849 * 850 * The caller must track how many elements were requested and provide that 851 * number when freeing the block. 852 */ 853 extern int 854 sw_state_res_alloc_align_tag(int unit, 855 int res_id, 856 uint32 flags, 857 int align, 858 int offset, 859 const void *tag, 860 int count, 861 int *elem); 862 863 /* 864 * Function 865 * sw_state_res_free 866 * Purpose 867 * Free an element or block of elements of a particular resource 868 * Parameters 869 * (IN) unit : unit number of the device 870 * (IN) res_id : which resource to free 871 * (IN) count : elements in the block to free 872 * (IN) elem : the element to free (or base of the block to free) 873 * Returns 874 * BCM_E_NONE if successful 875 * BCM_E_* as appropriate otherwise 876 * Notes 877 * This will free a single block of the requested number of elements, 878 * starting at the specified element. Some of the allocators do not deal 879 * with blocks and so must be told how large a block was, so it is 880 * obligatory that the caller be able to provide such information. 881 * 882 * This should only be called with valid data (base element and element 883 * count) against known allocated blocks. Trying to free a block that is 884 * not in use or trying to free something that spans multiple allocated 885 * blocks may not work. 886 * 887 * Must not be used to free sparse blocks. 888 */ 889 extern int 890 sw_state_res_free(int unit, 891 int res_id, 892 int count, 893 int elem); 894 895 /* 896 * Function 897 * sw_state_res_free 898 * Purpose 899 * Free an element or block of elements of a particular resource, then get 900 * flags about that resource. 901 * Parameters 902 * (IN) unit : unit number of the device 903 * (IN) res_id : which resource to free 904 * (IN) count : elements in the block to free 905 * (IN) elem : the element to free (or base of the block to free) 906 * (OUT) flags : where to put the flags 907 * Returns 908 * BCM_E_NONE if successful 909 * BCM_E_* as appropriate otherwise 910 * Notes 911 * This will free a single block of the requested number of elements, 912 * starting at the specified element. Some of the allocators do not deal 913 * with blocks and so must be told how large a block was, so it is 914 * obligatory that the caller be able to provide such information. 915 * 916 * This should only be called with valid data (base element and element 917 * count) against known allocated blocks. Trying to free a block that is 918 * not in use or trying to free something that spans multiple allocated 919 * blocks may not work. 920 * 921 * The value at status will generally be updated to reflect the proper 922 * status unless the type is not defined at the time of the call. The 923 * values for the individual flags are of the SW_STATE_RES_FREED_* form. 924 * 925 * Must not be used to free sparse blocks. 926 */ 927 extern int 928 sw_state_res_free_and_status(int unit, 929 int res_id, 930 int count, 931 int elem, 932 uint32 *flags); 933 934 /* 935 * Function 936 * sw_state_res_free 937 * Purpose 938 * Free a sparse block of elements of a particular resource 939 * Parameters 940 * (IN) unit : unit number of the device 941 * (IN) res_id : which resource to free 942 * (IN) pattern: pattern of elements to free 943 * (IN) length : length of the pattern 944 * (IN) repeats: number of iterations of the pattern 945 * (IN) elem : the element to free (or base of the block to free) 946 * Returns 947 * BCM_E_NONE if successful 948 * BCM_E_* as appropriate otherwise 949 * Notes 950 * This will free a sparse block of elements, starting at the specified 951 * element and proceeding as specified. 952 * 953 * This function can not be used with a 'scaled' allocator. 954 * 955 * This should only be called with valid data (base element, pattern, 956 * length, repeats). Trying to free a block that is not in use or trying 957 * to free something that spans multiple allocated blocks may not work. 958 * 959 * Anything allocated with sw_state_mres_alloc_align_sparse must be freed using 960 * this function. While it is possible to use this function to free 961 * blocks allocated with other functions, it is not advised. 962 * 963 * Sparse functions do not work with scaled resources. 964 * 965 * While this can be used to free non-sparse blocks, it is probably best 966 * to use the non-sparse free functions for that purpose. 967 */ 968 extern int 969 sw_state_res_free_sparse(int unit, 970 int res_id, 971 uint32 pattern, 972 int length, 973 int repeats, 974 int elem); 975 976 /* 977 * Function 978 * sw_state_res_free 979 * Purpose 980 * Free a sparse block of elements of a particular resource, then get 981 * flags about that resource. 982 * Parameters 983 * (IN) unit : unit number of the device 984 * (IN) res_id : which resource to free 985 * (IN) pattern: pattern of elements to free 986 * (IN) length : length of the pattern 987 * (IN) repeats: number of iterations of the pattern 988 * (IN) elem : the element to free (or base of the block to free) 989 * (OUT) flags : where to put the flags 990 * Returns 991 * BCM_E_NONE if successful 992 * BCM_E_* as appropriate otherwise 993 * Notes 994 * This will free a sparse block of elements, starting at the specified 995 * element and proceeding as specified. 996 * 997 * This function can not be used with a 'scaled' allocator. 998 * 999 * This should only be called with valid data (base element, pattern, 1000 * length, repeats). Trying to free a block that is not in use or trying 1001 * to free something that spans multiple allocated blocks may not work. 1002 * 1003 * Anything allocated with sw_state_mres_alloc_align_sparse must be freed using 1004 * this function. While it is possible to use this function to free 1005 * blocks allocated with other functions, it is not advised. 1006 * 1007 * Sparse functions do not work with scaled resources. 1008 * 1009 * While this can be used to free non-sparse blocks, it is probably best 1010 * to use the non-sparse free functions for that purpose. 1011 */ 1012 extern int 1013 sw_state_res_free_sparse_and_status(int unit, 1014 int res_id, 1015 uint32 pattern, 1016 int length, 1017 int repeats, 1018 int elem, 1019 uint32 *flags); 1020 1021 /* 1022 * Function 1023 * sw_state_res_check 1024 * Purpose 1025 * Check the status of a specific element 1026 * Parameters 1027 * (IN) unit : unit number of the device 1028 * (IN) res_id : which resource to check 1029 * (IN) count : elements in the block to check 1030 * (IN) elem : the element to check (or base of the block to check) 1031 * Returns 1032 * BCM_E_NOT_FOUND if the element is not in use 1033 * BCM_E_EXISTS if the element is in use 1034 * BCM_E_PARAM if the element is not valid 1035 * BCM_E_* as appropriate otherwise 1036 * Notes 1037 * This will check whether the requested block of the resource is 1038 * allocated. Note that if any element of the resource in the range of 1039 * [elem..(elem+count-1)] (inclusive) is not free, it returns 1040 * BCM_E_EXISTS; it will only return BCM_E_NOT_FOUND if all elements 1041 * within the specified block are free. 1042 * 1043 * Normally this should be called to check on a specific block (one that 1044 * is thought to exist or in preparation for allocating it WITH_ID. 1045 * 1046 * Unlike sw_state_mres_check_all, this considers the whole set of elements in 1047 * use if any of them is in use. 1048 */ 1049 extern int 1050 sw_state_res_check(int unit, 1051 int res_id, 1052 int count, 1053 int elem); 1054 1055 /* 1056 * Function 1057 * sw_state_res_check_all 1058 * Purpose 1059 * Check the status of a group of elements 1060 * Parameters 1061 * (IN) unit : unit number of the device 1062 * (IN) res_id : which resource to check 1063 * (IN) count : elements in the block to check 1064 * (IN) elem : the element to check (or base of the block to check) 1065 * Returns 1066 * BCM_E_EMPTY if none of the elements are in use 1067 * BCM_E_FULL if all of the elements are in use 1068 * BCM_E_CONFIG if elements are in use but block(s) do not match 1069 * BCM_E_EXISTS if some of the elements are in use but not all of them 1070 * BCM_E_PARAM if any of the elements is not valid 1071 * BCM_E_* as appropriate otherwise 1072 * Notes 1073 * This will check all of the elements (and blocks, on those allocators 1074 * supporting block tracking) in the specified range, and return a result 1075 * based upon that examination. 1076 * 1077 * Normally, this would be called in case of intent to directly replace a 1078 * possibly existing block of elements with a new one. 1079 * 1080 * Unlike sw_state_mres_check, this does not immediately return if it finds an 1081 * in-use element. Instead, it continues through the specified range and 1082 * returns a more detailed result, considering the requested range as if 1083 * it were intended for immediate direct reuse (such as WITH_ID+REPLACE). 1084 * 1085 * For TAGGED resources, this assumes the tag to be used is the tag 1086 * already associated with the first element in the block. If the default 1087 * tag behaviour is desired instead, use sw_state_mres_check_all_tag with the 1088 * tag pointer set to NULL. 1089 */ 1090 extern int 1091 sw_state_res_check_all(int unit, 1092 int res_id, 1093 int count, 1094 int elem); 1095 1096 /* 1097 * Function 1098 * sw_state_res_check_all 1099 * Purpose 1100 * Check the status of a group of elements 1101 * Parameters 1102 * (IN) unit : unit number of the device 1103 * (IN) res_id : which resource to check 1104 * (IN) count : elements in the block to check 1105 * (IN) elem : the element to check (or base of the block to check) 1106 * Returns 1107 * BCM_E_EMPTY if none of the elements are in use 1108 * BCM_E_FULL if all of the elements are in use 1109 * BCM_E_CONFIG if elements are in use but block(s) do not match 1110 * BCM_E_EXISTS if some of the elements are in use but not all of them 1111 * BCM_E_PARAM if any of the elements is not valid 1112 * BCM_E_* as appropriate otherwise 1113 * Notes 1114 * This will check whether the requested sparse block of the resource is 1115 * allocated. If all of the specified elements are allocated, it will 1116 * return BCM_E_FULL; if all of the specified elements are free, it will 1117 * return BCM_E_EMPTY; if some of the specified elements are allocated and 1118 * some are free, it will return BCM_E_EXISTS. 1119 * 1120 * See sw_state_res_bitmap_sparse_alloc_align_sparse for information about 1121 * how sparse patterns are specified. 1122 * 1123 * Normally, this would be called in case of intent to directly replace a 1124 * possibly existing block of elements with a new one. 1125 * 1126 * Unlike sw_state_mres_check, this does not immediately return if it finds an 1127 * in-use element. Instead, it continues through the specified range and 1128 * returns a more detailed result, considering the requested range as if 1129 * it were intended for immediate direct reuse (such as WITH_ID+REPLACE). 1130 * 1131 * For TAGGED resources, this assumes the tag to be used is the tag 1132 * already associated with the first element in the block. If the default 1133 * tag behaviour is desired instead, use sw_state_mres_check_all_tag with the 1134 * tag pointer set to NULL. 1135 * 1136 * Sparse functions do not work with scaled resources. 1137 */ 1138 extern int 1139 sw_state_res_check_all_sparse(int unit, 1140 int res_id, 1141 uint32 pattern, 1142 int length, 1143 int repeats, 1144 int elem); 1145 1146 /* 1147 * Function 1148 * sw_state_res_check_all_tag 1149 * Purpose 1150 * Check the status of a group of elements 1151 * Parameters 1152 * (IN) unit : unit number of the device 1153 * (IN) res_id : which resource to check 1154 * (IN) tag : tag for checking 1155 * (IN) count : elements in the block to check 1156 * (IN) elem : the element to check (or base of the block to check) 1157 * Returns 1158 * BCM_E_EMPTY if none of the elements are in use 1159 * BCM_E_FULL if all of the elements are in use 1160 * BCM_E_CONFIG if elements are in use but block(s)/tag(s) do not match 1161 * BCM_E_EXISTS if some of the elements are in use but not all of them 1162 * BCM_E_PARAM if any of the elements is not valid 1163 * BCM_E_* as appropriate otherwise 1164 * Notes 1165 * This will check all of the elements (and blocks, on those allocators 1166 * supporting block tracking) in the specified range, and return a result 1167 * based upon that examination. 1168 * 1169 * Normally, this would be called in case of intent to directly replace a 1170 * possibly existing block of elements with a new one. 1171 * 1172 * Unlike sw_state_mres_check, this does not immediately return if it finds an 1173 * in-use element. Instead, it continues through the specified range and 1174 * returns a more detailed result, considering the requested range as if 1175 * it were intended for immediate direct reuse (such as WITH_ID+REPLACE). 1176 */ 1177 extern int 1178 sw_state_res_check_all_tag(int unit, 1179 int res_id, 1180 const void *tag, 1181 int count, 1182 int elem); 1183 1184 /* 1185 * Function 1186 * sw_state_res_alloc_group 1187 * Purpose 1188 * Allocate an group of elements or blocks of elements of a particular 1189 * resource 1190 * Parameters 1191 * (IN) unit : unit number of the device 1192 * (IN) res_id : which resource to allocate 1193 * (IN) grp_flags : flags to apply to the whole group 1194 * (IN) grp_size : number of members of the group 1195 * (OUT) grp_done : where to put how many members were completed 1196 * (IN) *flags : flags providing specifics of what/how to allocate 1197 * (IN) *count : elements to allocate in this block 1198 * (IN/OUT) *elem : where to put the allocated element (block base) 1199 * Returns 1200 * BCM_E_NONE if successful 1201 * BCM_E_* as appropriate otherwise 1202 * Notes 1203 * The flags, count, and elem all point to arrays. This function will act 1204 * as if sw_state_mres_alloc were called exactly once with each member from 1205 * these arrays as its arguments, including the behaviour for elem. 1206 * 1207 * If all goes well, grp_done will be set equal to grp_size; if something 1208 * goes wrong, grp_done will indicate how many of the members were 1209 * successfully allocated before the failure. 1210 * 1211 * If the SW_STATE_RES_ALLOC_GROUP_ATOMIC flag is set in the group flags, any 1212 * failure will be taken as complete, and all elements/blocks allocated up 1213 * to that point will be freed before the error is returned. If it is not 1214 * set in the group flags, any failure will stop further allocations, but 1215 * will leave existing allocations alone. 1216 * 1217 * This function is essentially a wrapper around sw_state_mres_alloc. 1218 */ 1219 extern int 1220 sw_state_res_alloc_group(int unit, 1221 int res_id, 1222 uint32 grp_flags, 1223 int grp_size, 1224 int *grp_done, 1225 const uint32 *flags, 1226 const int *count, 1227 int *elem); 1228 1229 /* 1230 * Function 1231 * sw_state_res_alloc_tag_group 1232 * Purpose 1233 * Allocate an group of elements or blocks of elements of a particular 1234 * resource 1235 * Parameters 1236 * (IN) unit : unit number of the device 1237 * (IN) res_id : which resource to allocate 1238 * (IN) grp_flags : flags to apply to the whole group 1239 * (IN) grp_size : number of members of the group 1240 * (OUT) grp_done : where to put how many members were completed 1241 * (IN) *flags : flags providing specifics of what/how to allocate 1242 * (IN) *tag : pointers to the tags for each block 1243 * (IN) *count : elements to allocate in this block 1244 * (IN/OUT) *elem : where to put the allocated element (block base) 1245 * Returns 1246 * BCM_E_NONE if successful 1247 * BCM_E_* as appropriate otherwise 1248 * Notes 1249 * The flags, count, and elem all point to arrays. This function will act 1250 * as if sw_state_mres_alloc were called exactly once with each member from 1251 * these arrays as its arguments, including the behaviour for elem. 1252 * 1253 * If all goes well, grp_done will be set equal to grp_size; if something 1254 * goes wrong, grp_done will indicate how many of the members were 1255 * successfully allocated before the failure. 1256 * 1257 * If the SW_STATE_RES_ALLOC_GROUP_ATOMIC flag is set in the group flags, any 1258 * failure will be taken as complete, and all elements/blocks allocated up 1259 * to that point will be freed before the error is returned. If it is not 1260 * set in the group flags, any failure will stop further allocations, but 1261 * will leave existing allocations alone. 1262 * 1263 * This function is essentially a wrapper around sw_state_mres_alloc. 1264 */ 1265 extern int 1266 sw_state_res_alloc_tag_group(int unit, 1267 int res_id, 1268 uint32 grp_flags, 1269 int grp_size, 1270 int *grp_done, 1271 const uint32 *flags, 1272 const void **tag, 1273 const int *count, 1274 int *elem); 1275 1276 /* 1277 * Function 1278 * sw_state_res_alloc_align_group 1279 * Purpose 1280 * Allocate an group of elements or blocks of elements of a particular 1281 * resource, with specified alignment and offset 1282 * Parameters 1283 * (IN) unit : unit number of the device 1284 * (IN) res_id : which resource to allocate 1285 * (IN) grp_flags : flags to apply to the whole group 1286 * (IN) grp_size : number of members of the group 1287 * (OUT) grp_done : where to put how many members were completed 1288 * (IN) *flags : flags providing specifics of what/how to allocate 1289 * (IN) *align : base alignment in this block 1290 * (IN) *offset : offest from base alignment for first elem in this blk 1291 * (IN) *count : elements to allocate in this block 1292 * (IN/OUT) *elem : where to put the allocated element (block base) 1293 * Returns 1294 * BCM_E_NONE if successful 1295 * BCM_E_* as appropriate otherwise 1296 * Notes 1297 * The flags, align, offset, count, and elem all point to arrays. This 1298 * function will act as if sw_state_mres_alloc_align were called exactly once 1299 * with each member from these arrays as its arguments, including the 1300 * behaviour for elem. 1301 * 1302 * If all goes well, grp_done will be set equal to grp_size; if something 1303 * goes wrong, grp_done will indicate how many of the members were 1304 * successfully allocated before the failure. 1305 * 1306 * If the SW_STATE_RES_ALLOC_GROUP_ATOMIC flag is set in the group flags, any 1307 * failure will be taken as complete, and all elements/blocks allocated up 1308 * to that point will be freed before the error is returned. If it is not 1309 * set in the group flags, any failure will stop further allocations, but 1310 * will leave existing allocations alone. 1311 * 1312 * This function is essentially a wrapper around sw_state_mres_alloc_align. 1313 */ 1314 extern int 1315 sw_state_res_alloc_align_group(int unit, 1316 int res_id, 1317 uint32 grp_flags, 1318 int grp_size, 1319 int *grp_done, 1320 const uint32 *flags, 1321 const int *align, 1322 const int *offset, 1323 const int *count, 1324 int *elem); 1325 /* 1326 * Function 1327 * sw_state_res_tag_set 1328 * Purpose 1329 * Set a tag for a range of elements. 1330 * Useful for using taged bit map for different type of allocation. 1331 * Parameters 1332 * (IN) unit : unit number of the device 1333 * (IN) res_id : which resource to allocate 1334 * (IN) int offset : first elemet which will have its tag changed. 1335 * (IN) count : number of elemets elemets which will have there tag changed. 1336 * (IN) *tag : tag to set 1337 * Returns 1338 * BCM_E_NONE if successful 1339 * BCM_E_* as appropriate otherwise 1340 */ 1341 int 1342 sw_state_res_tag_set(int unit, 1343 int res_id, 1344 int offset, 1345 int count, 1346 const void* tag); 1347 /* 1348 * Function 1349 * sw_state_res_tag_get 1350 * Purpose 1351 * get a tag for a range of elements. 1352 * Useful for using taged bit map for different type of allocation. 1353 * Parameters 1354 * (IN) unit : unit number of the device 1355 * (IN) res_id : which resource to allocate 1356 * (IN) element : element to get its tag 1357 * (IN) *tag : tag to set 1358 * Returns 1359 * BCM_E_NONE if successful 1360 * BCM_E_* as appropriate otherwise 1361 */ 1362 int 1363 sw_state_res_tag_get(int unit, 1364 int res_id, 1365 int element, 1366 const void* tag); 1367 /* 1368 * Function 1369 * sw_state_res_alloc_align_tag_group 1370 * Purpose 1371 * Allocate an group of elements or blocks of elements of a particular 1372 * resource, with specified alignment and offset 1373 * Parameters 1374 * (IN) unit : unit number of the device 1375 * (IN) res_id : which resource to allocate 1376 * (IN) grp_flags : flags to apply to the whole group 1377 * (IN) grp_size : number of members of the group 1378 * (OUT) grp_done : where to put how many members were completed 1379 * (IN) *flags : flags providing specifics of what/how to allocate 1380 * (IN) *align : base alignment in this block 1381 * (IN) *offset : offest from base alignment for first elem in this blk 1382 * (IN) *tag : pointers to the tags for each block 1383 * (IN) *count : elements to allocate in this block 1384 * (IN/OUT) *elem : where to put the allocated element (block base) 1385 * Returns 1386 * BCM_E_NONE if successful 1387 * BCM_E_* as appropriate otherwise 1388 * Notes 1389 * The flags, align, offset, count, and elem all point to arrays. This 1390 * function will act as if sw_state_mres_alloc_align were called exactly once 1391 * with each member from these arrays as its arguments, including the 1392 * behaviour for elem. 1393 * 1394 * If all goes well, grp_done will be set equal to grp_size; if something 1395 * goes wrong, grp_done will indicate how many of the members were 1396 * successfully allocated before the failure. 1397 * 1398 * If the SW_STATE_RES_ALLOC_GROUP_ATOMIC flag is set in the group flags, any 1399 * failure will be taken as complete, and all elements/blocks allocated up 1400 * to that point will be freed before the error is returned. If it is not 1401 * set in the group flags, any failure will stop further allocations, but 1402 * will leave existing allocations alone. 1403 * 1404 * This function is essentially a wrapper around sw_state_mres_alloc_align. 1405 */ 1406 extern int 1407 sw_state_res_alloc_align_tag_group(int unit, 1408 int res_id, 1409 uint32 grp_flags, 1410 int grp_size, 1411 int *grp_done, 1412 const uint32 *flags, 1413 const int *align, 1414 const int *offset, 1415 const void **tag, 1416 const int *count, 1417 int *elem); 1418 1419 /* 1420 * Function 1421 * sw_state_res_free_group 1422 * Purpose 1423 * Free a group of elements or blocks of elements of a particular resource 1424 * Parameters 1425 * (IN) unit : unit number of the device 1426 * (IN) res_id : which resource to free 1427 * (IN) grp_flags : flags to apply to the whole group 1428 * (IN) grp_size : number of members this group 1429 * (OUT) grp_done : where to put how many members were completed 1430 * (IN) *count : elements in the block to free 1431 * (IN) *elem : the element to free (or base of the block to free) 1432 * Returns 1433 * BCM_E_NONE if successful 1434 * BCM_E_* as appropriate otherwise 1435 * Notes 1436 * The flags, count, and elem all point to arrays. This function will act 1437 * as if sw_state_mres_free were called exactly once with each member from 1438 * these arrays as its arguments, including the behaviour for elem. 1439 * 1440 * If all goes well, grp_done will be set equal to grp_size; if something 1441 * goes wrong, grp_done will indicate how many of the members were 1442 * successfully freed before the failure. 1443 * 1444 * This function is essentially a wrapper around sw_state_mres_free. 1445 */ 1446 extern int 1447 sw_state_res_free_group(int unit, 1448 int res_id, 1449 uint32 grp_flags, 1450 int grp_size, 1451 int *grp_done, 1452 const int *count, 1453 const int *elem); 1454 1455 /* 1456 * Function 1457 * sw_state_res_free_group_and_status 1458 * Purpose 1459 * Free a group of elements or blocks of elements of a particular resource 1460 * and get status flags 1461 * Parameters 1462 * (IN) unit : unit number of the device 1463 * (IN) res_id : which resource to free 1464 * (IN) grp_flags : flags to apply to the whole group 1465 * (IN) grp_size : number of members this group 1466 * (OUT) grp_done : where to put how many members were completed 1467 * (IN) *count : elements in the block to free 1468 * (IN) *elem : the element to free (or base of the block to free) 1469 * (OUT) *status : where to put the status flags 1470 * Returns 1471 * BCM_E_NONE if successful 1472 * BCM_E_* as appropriate otherwise 1473 * Notes 1474 * The flags, count, and elem all point to arrays. This function will act 1475 * as if sw_state_mres_free were called exactly once with each member from 1476 * these arrays as its arguments, including the behaviour for elem. 1477 * 1478 * If all goes well, grp_done will be set equal to grp_size; if something 1479 * goes wrong, grp_done will indicate how many of the members were 1480 * successfully freed before the failure. 1481 * 1482 * This function is essentially a wrapper around sw_state_mres_free_and_status. 1483 * 1484 * The value at status will generally be updated to reflect the proper 1485 * status unless the type is not defined at the time of the call. The 1486 * values for the individual flags are of the SW_STATE_RES_FREED_* form. 1487 */ 1488 extern int 1489 sw_state_res_free_group_and_status(int unit, 1490 int res_id, 1491 uint32 grp_flags, 1492 int grp_size, 1493 int *grp_done, 1494 const int *count, 1495 const int *elem, 1496 uint32 *status); 1497 1498 /* 1499 * Function 1500 * sw_state_res_check_group 1501 * Purpose 1502 * Check the status of a group of specific elements 1503 * Parameters 1504 * (IN) unit : unit number of the device 1505 * (IN) res_id : which resource to check 1506 * (IN) grp_flags : flags to apply to the whole group 1507 * (IN) grp_size : number of members this group 1508 * (OUT) grp_done : where to put how many members were completed 1509 * (IN) *count : elements in the block to check 1510 * (IN) *elem : the element to check (or base of the block to check) 1511 * (OUT) *status : where to put the check results 1512 * Returns 1513 * BCM_E_NONE if successful 1514 * BCM_E_* as appropriate otherwise 1515 * Notes 1516 * This behaves similarly to calling sw_state_mres_check, except that it places 1517 * the result in the provided status array rather than returning the 1518 * status for exactly one element. 1519 * 1520 * The result code from this function should be BCM_E_NONE unless there is 1521 * something obviously wrong with the arguments or an unexpected result is 1522 * encountered. Normally, grp_done would be set equal to grp_size, but if 1523 * there is an unexpected failure, grp_done will indicate how many 1524 * elements were checked before the failure. 1525 * 1526 * If the SW_STATE_RES_ALLOC_GROUP_ATOMIC is set, this function will continue 1527 * to the end of the provided list despite any errors that occur once it 1528 * starts to check the provided list, and will return BCM_E_NONE if it 1529 * gets that far, but it will still return an appropriate error if it is 1530 * unable to begin checking the list due to some error. 1531 * 1532 * This function is essentially a wrapper around sw_state_mres_check. 1533 */ 1534 extern int 1535 sw_state_res_check_group(int unit, 1536 int res_id, 1537 uint32 grp_flags, 1538 int grp_size, 1539 int *grp_done, 1540 const int *count, 1541 const int *elem, 1542 int *status); 1543 1544 /* 1545 * Function 1546 * sw_state_res_check_all_group 1547 * Purpose 1548 * Check the status of a group of specific blocks of elements 1549 * Parameters 1550 * (IN) unit : unit number of the device 1551 * (IN) res_id : which resource to check 1552 * (IN) grp_flags : flags to apply to the whole group 1553 * (IN) grp_size : number of members this group 1554 * (OUT) grp_done : where to put how many members were completed 1555 * (IN) *count : elements in the block to check 1556 * (IN) *elem : the element to check (or base of the block to check) 1557 * (OUT) *status : where to put the check results 1558 * Returns 1559 * BCM_E_NONE if successful 1560 * BCM_E_* as appropriate otherwise 1561 * Notes 1562 * This behaves similarly to calling sw_state_mres_check, except that it places 1563 * the result in the provided status array rather than returning the 1564 * status for exactly one element. 1565 * 1566 * The result code from this function should be BCM_E_NONE unless there is 1567 * something obviously wrong with the arguments or an unexpected result is 1568 * encountered. Normally, grp_done would be set equal to grp_size, but if 1569 * there is an unexpected failure, grp_done will indicate how many 1570 * elements were checked before the failure. 1571 * 1572 * If the SW_STATE_RES_ALLOC_GROUP_ATOMIC is set, this function will continue 1573 * to the end of the provided list despite any errors that occur once it 1574 * starts to check the provided list, and will return BCM_E_NONE if it 1575 * gets that far, but it will still return an appropriate error if it is 1576 * unable to begin checking the list due to some error. 1577 * 1578 * This function is essentially a wrapper around sw_state_mres_check_all. 1579 */ 1580 extern int 1581 sw_state_res_check_all_group(int unit, 1582 int res_id, 1583 uint32 grp_flags, 1584 int grp_size, 1585 int *grp_done, 1586 const int *count, 1587 const int *elem, 1588 int *status); 1589 1590 /* 1591 * Function 1592 * sw_state_res_check_all_tag_group 1593 * Purpose 1594 * Check the status of a group of specific blocks of elements 1595 * Parameters 1596 * (IN) unit : unit number of the device 1597 * (IN) res_id : which resource to check 1598 * (IN) grp_flags : flags to apply to the whole group 1599 * (IN) grp_size : number of members this group 1600 * (OUT) grp_done : where to put how many members were completed 1601 * (IN) **tag : tags for the blocks to check 1602 * (IN) *count : elements in the block to check 1603 * (IN) *elem : the element to check (or base of the block to check) 1604 * (OUT) *status : where to put the check results 1605 * Returns 1606 * BCM_E_NONE if successful 1607 * BCM_E_* as appropriate otherwise 1608 * Notes 1609 * This behaves similarly to calling sw_state_mres_check, except that it places 1610 * the result in the provided status array rather than returning the 1611 * status for exactly one element. 1612 * 1613 * The result code from this function should be BCM_E_NONE unless there is 1614 * something obviously wrong with the arguments or an unexpected result is 1615 * encountered. Normally, grp_done would be set equal to grp_size, but if 1616 * there is an unexpected failure, grp_done will indicate how many 1617 * elements were checked before the failure. 1618 * 1619 * If the SW_STATE_RES_ALLOC_GROUP_ATOMIC is set, this function will continue 1620 * to the end of the provided list despite any errors that occur once it 1621 * starts to check the provided list, and will return BCM_E_NONE if it 1622 * gets that far, but it will still return an appropriate error if it is 1623 * unable to begin checking the list due to some error. 1624 * 1625 * This function is essentially a wrapper around sw_state_mres_check_all_tag. 1626 */ 1627 extern int 1628 sw_state_res_check_all_tag_group(int unit, 1629 int res_id, 1630 uint32 grp_flags, 1631 int grp_size, 1632 int *grp_done, 1633 const void **tag, 1634 const int *count, 1635 const int *elem, 1636 int *status); 1637 1638 /* 1639 * Function 1640 * sw_state_res_dump 1641 * Purpose 1642 * Diagnostic dump of a unit's resource management information 1643 * Parameters 1644 * (IN) unit : unit number of the device 1645 * Returns 1646 * BCM_E_NONE if successful 1647 * BCM_E_* as appropriate otherwise 1648 * Notes 1649 */ 1650 extern int 1651 sw_state_res_dump(int unit); 1652 1653 #endif /* ndef _SHR_RESMGR_H */ 1654