lt_intf.h (22484B)
1 /*! \file lt_intf.h 2 * 3 * LT Wrapper interface header file. 4 * This file contains the lightweight wrapper of SDKLT LT APIs. 5 */ 6 /* 7 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 8 * 9 * Copyright 2007-2020 Broadcom Inc. All rights reserved. 10 */ 11 12 #ifndef BCMI_LT_INTF_H 13 #define BCMI_LT_INTF_H 14 15 #include <bcmlt/bcmlt.h> 16 17 /******************************************************************************/ 18 /* Encapsulation for Complete SDKLT LT API Sequence */ 19 /******************************************************************************/ 20 21 /*! Recommended Maximum number of fields in LT entry information. */ 22 #define BCMI_LT_FIELD_MAX 32 23 24 /*! Field value can be represented by a symbol string. */ 25 #define BCMI_LT_FIELD_F_SYMBOL (1 << 0) 26 /*! Field contents are represented by an array. */ 27 #define BCMI_LT_FIELD_F_ARRAY (1 << 1) 28 /*! Field to set. */ 29 #define BCMI_LT_FIELD_F_SET (1 << 2) 30 /*! Field to get. */ 31 #define BCMI_LT_FIELD_F_GET (1 << 3) 32 /*! Indicate if an element in scalar or symbol array is valid. */ 33 #define BCMI_LT_FIELD_F_ELE_VALID (1 << 4) 34 35 /*! 36 * \brief LT field information. 37 * 38 * This data structure is used to identify the field, its type and value. 39 */ 40 typedef struct bcmi_lt_field_s { 41 /*! Field name. */ 42 const char *fld_name; 43 /*! Field attribute (ref LT_FIELD_F_xxx). */ 44 uint16_t flags; 45 /*! Indicating the index of the element in an array. */ 46 uint16_t idx; 47 /*! The field data portion is a union of possible types. */ 48 union { 49 /*! scalar data. */ 50 uint64_t val; 51 /*! symbol data. */ 52 const char *sym_val; 53 } u; 54 } bcmi_lt_field_t; 55 56 /*! 57 * \brief LT entry information. 58 * 59 * This data structure is used to identify the entry fields and attributes. 60 */ 61 typedef struct bcmi_lt_entry_s { 62 /*! Fields information array. */ 63 bcmi_lt_field_t *fields; 64 65 /*! 66 * The number of fields array, it's not suggested to exceed 67 * BCMI_LT_FIELD_MAX. Note that each element in an array will be counted. 68 */ 69 int nfields; 70 71 /*! Entry attributes of the entry table(ref BCMLT_ENT_ATTR_F_xxx). */ 72 uint32_t attr; 73 } bcmi_lt_entry_t; 74 75 /*! 76 * \brief Callback function to handle an LT entry. 77 * 78 * This callback function is used to handle an LT entry. 79 */ 80 typedef int (*bcmi_lt_entry_handle_cb) ( 81 /*! Device Number. */ 82 int unit, 83 /*! LT Name. */ 84 const char *lt_name, 85 /*! Handle to the entry. */ 86 bcmlt_entry_handle_t entry_hdl, 87 /*! Cookie for LT entry information. */ 88 void *cookie 89 ); 90 91 /*! 92 * \brief LT field information. 93 * 94 * This data structure is used to provide the immutable propertires of a field. 95 */ 96 typedef struct bcmi_lt_field_info_s { 97 /*! Enabled if this is a key field. */ 98 bool key; 99 100 /*! 101 * Enabled to indicate this field is specified via symbols, 102 * not numeric values. 103 */ 104 bool symbol; 105 106 /*! 107 * The least permitted value for this field in this LT, 108 * as restricted by device resource and table configuration. 109 * Applicable if SYMBOL is disabled. 110 */ 111 uint64_t min_limit; 112 113 /*! 114 * The greatest permitted value for this field in this LT, 115 * as restricted by device resource and table configuration. 116 * Applicable if SYMBOL is disabled. 117 */ 118 uint64_t max_limit; 119 120 /*! 121 * Number of array elements for this field. 122 * If the field is scalar, this value is 0. 123 */ 124 uint32_t array_depth; 125 126 /*! 127 * Number of elements for this field. 128 * For a scalar, this will be (FIELD_WIDTH + 63 / 64). 129 * For an array, this is equal to ARRAY_DEPTH. 130 * The valid field index values for this field range 131 * [ELEMENTS - 1, 0]. 132 */ 133 uint32_t elements; 134 135 /*! Bit width of this field. */ 136 uint32_t field_width; 137 138 } bcmi_lt_field_info_t; 139 140 /*! 141 * \brief Initialize LT entry struct. 142 * 143 * \param [in] entry LT entry information. 144 * \param [in] fields Pointer to fields information array. 145 * 146 * \retval None. 147 */ 148 extern void 149 bcmi_lt_entry_init(bcmi_lt_entry_t *entry, bcmi_lt_field_t *fields); 150 151 /*! 152 * \brief Set entry attributes. 153 * 154 * \param [in] entry LT entry information. 155 * \param [in] attr Entry attributes of the entry table(ref 156 * BCMLT_ENT_ATTR_F_xxx). 157 * 158 * \retval None. 159 */ 160 extern void 161 bcmi_lt_entry_attrib_set(bcmi_lt_entry_t *entry, uint32_t attr); 162 163 /*! 164 * \brief Insert an entry into LT table. 165 * 166 * \param [in] unit Unit number. 167 * \param [in] lt_name LT name. 168 * \param [in] cookie LT entry information. 169 * \param [in] hdl_cb User callback to set LT fields. If it's not 170 * specified(NULL), cookie should be organized per \c bcmi_lt_entry_t 171 * definition. 172 * 173 * \retval SHR_E_NONE No errors. 174 * \retval !SHR_E_NONE Failure. 175 */ 176 extern int 177 bcmi_lt_entry_insert(int unit, const char *lt_name, void *cookie, 178 bcmi_lt_entry_handle_cb hdl_cb); 179 180 /*! 181 * \brief Modify the specified fields of an entry. 182 * 183 * \param [in] unit Unit number. 184 * \param [in] lt_name LT name. 185 * \param [in] cookie LT entry information. 186 * \param [in] hdl_cb User callback to set LT fields. If it's not 187 * specified(NULL), cookie should be organized per \c bcmi_lt_entry_t 188 * definition. 189 * 190 * \retval SHR_E_NONE No errors. 191 * \retval !SHR_E_NONE Failure. 192 */ 193 extern int 194 bcmi_lt_entry_update(int unit, const char *lt_name, void *cookie, 195 bcmi_lt_entry_handle_cb hdl_cb); 196 197 /*! 198 * \brief Delete an entry from LT table. 199 * 200 * \param [in] unit Unit number. 201 * \param [in] lt_name LT name. 202 * \param [in] cookie LT entry information. 203 * \param [in] hdl_cb User callback to set LT fields. If it's not 204 * specified(NULL), cookie should be organized per \c bcmi_lt_entry_t 205 * definition. 206 * 207 * \retval SHR_E_NONE No errors. 208 * \retval !SHR_E_NONE Failure. 209 */ 210 extern int 211 bcmi_lt_entry_delete(int unit, const char *lt_name, void *cookie, 212 bcmi_lt_entry_handle_cb hdl_cb); 213 214 /*! 215 * \brief Lookup if an entry exists or not. 216 * 217 * \param [in] unit Unit number. 218 * \param [in] lt_name LT name. 219 * \param [in] cookie LT entry information. 220 * \param [in] hdl_cb User callback to set LT fields. If it's not 221 * specified(NULL), cookie should be organized per \c bcmi_lt_entry_t 222 * definition. 223 * 224 * \retval SHR_E_NONE No errors. 225 * \retval !SHR_E_NONE Failure. 226 */ 227 extern int 228 bcmi_lt_entry_lookup(int unit, const char *lt_name, void *cookie, 229 bcmi_lt_entry_handle_cb hdl_cb); 230 231 /*! 232 * \brief Retrieve the specified fields of an entry. 233 * 234 * \param [in] unit Unit number. 235 * \param [in] lt_name LT name. 236 * \param [out] cookie LT entry information. 237 * \param [in] hdl_set_cb User callback to set LT fields. If it's not 238 * specified(NULL), cookie should be organized per \c bcmi_lt_entry_t 239 * definition. 240 * \param [in] hdl_get_cb User callback to get LT fields. If it's not 241 * specified(NULL), cookie should be organized per \c bcmi_lt_entry_t 242 * definition. 243 * 244 * \retval SHR_E_NONE No errors. 245 * \retval !SHR_E_NONE Failure. 246 */ 247 extern int 248 bcmi_lt_entry_get(int unit, const char *lt_name, void *cookie, 249 bcmi_lt_entry_handle_cb hdl_set_cb, 250 bcmi_lt_entry_handle_cb hdl_get_cb); 251 252 /*! 253 * \brief Insert or update an entry. 254 * 255 * If the LT entry exists, it will be updated directly. If the LT entry doesn't 256 * exist, a new LT entry will be inserted. 257 * 258 * \param [in] unit Unit number. 259 * \param [in] lt_name LT name. 260 * \param [out] cookie LT entry information. 261 * \param [in] hdl_cb User callback to set LT fields. If it's not 262 * specified(NULL), cookie should be organized per \c bcmi_lt_entry_t 263 * definition. 264 * 265 * \retval SHR_E_NONE No errors. 266 * \retval !SHR_E_NONE Failure. 267 */ 268 extern int 269 bcmi_lt_entry_set(int unit, const char *lt_name, 270 void *cookie, bcmi_lt_entry_handle_cb hdl_cb); 271 272 /*! 273 * \brief Traverse all the entries in an LT. 274 * 275 * This function goes through LT table entries and runs the user callback 276 * function at each LT entry. Don't support the bcmi_lt_entry_t format so far. 277 * 278 * \param [in] unit Unit number. 279 * \param [in] lt_name LT name. 280 * \param [out] cookie LT entry information. 281 * \param [in] hdl_cb User callback to set LT fields/traverse entries. 282 * 283 * \retval SHR_E_NONE No errors. 284 * \retval !SHR_E_NONE Failure. 285 */ 286 extern int 287 bcmi_lt_entry_traverse(int unit, const char *lt_name, 288 void *cookie, bcmi_lt_entry_handle_cb hdl_cb); 289 290 /*! 291 * \brief Add a field to an LT entry. 292 * 293 * This function is used to add a field to an entry. The field can be up to 294 * 64-bits in size. Use field array for larger fields (see 295 * \ref bcmi_lt_entry_field_array_add) 296 * 297 * \param [in] unit Unit number. 298 * \param [in] entry LT entry information. 299 * \param [in] fld_name LT field name. 300 * \param [in] data 64-bits value of the field to set. 301 * \param [in] flags Field flags(\c BCMI_LT_FIELD_F_SET 302 * or \c BCMI_LT_FIELD_F_GET). 303 * 304 * \retval None. 305 */ 306 extern void 307 bcmi_lt_entry_field_add(int unit, bcmi_lt_entry_t *entry, 308 const char *fld_name, uint64_t data, uint16_t flags); 309 310 /*! 311 * \brief Get a field from an LT entry. 312 * 313 * This function is used to get a field value from an entry. The field 314 * can be up to 64-bits in size. Use field array for larger fields (see 315 * \ref bcmi_lt_entry_field_array_get) 316 * 317 * \param [in] unit Unit number. 318 * \param [in] entry LT entry information. 319 * \param [in] fld_name LT field name. 320 * \param [out] data 64-bits value of the field to get. 321 * 322 * \retval SHR_E_NONE No errors. 323 * \retval !SHR_E_NONE Failure. 324 */ 325 extern int 326 bcmi_lt_entry_field_get(int unit, bcmi_lt_entry_t *entry, 327 const char *fld_name, uint64_t *data); 328 329 /*! 330 * \brief Add a symbol field to an entry. 331 * 332 * \param [in] unit Unit number. 333 * \param [in] entry LT entry information. 334 * \param [in] fld_name LT field name. 335 * \param [in] data Symbol of the field to set. 336 * \param [in] flags Field flags(\c BCMI_LT_FIELD_F_SET 337 * or \c BCMI_LT_FIELD_F_GET). 338 * 339 * \retval None. 340 */ 341 extern void 342 bcmi_lt_entry_field_symbol_add(int unit, bcmi_lt_entry_t *entry, 343 const char *fld_name, const char *data, 344 uint16_t flags); 345 /*! 346 * \brief Get a symbol field to an entry. 347 * 348 * \param [in] unit Unit number. 349 * \param [in] entry LT entry information. 350 * \param [in] fld_name LT field name. 351 * \param [out] data Symbol of the field to get. 352 * 353 * \retval SHR_E_NONE No errors. 354 * \retval !SHR_E_NONE Failure. 355 */ 356 extern int 357 bcmi_lt_entry_field_symbol_get(int unit, bcmi_lt_entry_t *entry, 358 const char *fld_name, const char **data); 359 360 /*! 361 * \brief Add a field array to an entry. 362 * 363 * This function is used to add a field array to an entry. Each element of the 364 * field array can be up to 64-bits in size. This function can be called 365 * multiple times with different \c start_idx values to construct a complete 366 * array of elements. For example, if the application wants to insert two 367 * elements at index 3 & 4 the application will set \c start_idx = 3 and 368 * num_of_elem = 2. Note that the array index starts from index 0. 369 * 370 * \param [in] unit Unit number. 371 * \param [in] entry LT entry information. 372 * \param [in] fld_name LT field name. 373 * \param [in] start_idx Target array index where elements should start 374 * being applied. 375 * \param [in] array Pointer to array of 64-bits values. 376 * \param [in] size Indicates the number of array elements. 377 * \param [in] flags Field flags(\c BCMI_LT_FIELD_F_SET 378 * or \c BCMI_LT_FIELD_F_GET). 379 * 380 * \retval None. 381 */ 382 extern void 383 bcmi_lt_entry_field_array_add(int unit, bcmi_lt_entry_t *entry, 384 const char *fld_name, uint16_t start_idx, 385 uint64_t *array, uint16_t size, uint16_t flags); 386 387 /*! 388 * \brief Get a field array from an entry. 389 * 390 * This function is used to get a field array from an entry. Each element of the 391 * field array must be up to 64 bits in size. This function can be called 392 * multiple times with different \c start_idx values to construct a complete 393 * array of elements. For example, if the application wants to get the values of 394 * two elements in index 3 & 4 the application will set \c start_idx = 3 and 395 * num_of_elem = 2. Note that the array index starts from index 0. 396 * 397 * \param [in] unit Unit number. 398 * \param [in] entry LT entry information. 399 * \param [in] fld_name LT field name. 400 * \param [in] start_idx Target array index where elements should start 401 * being applied. 402 * \param [in] array Pointer to array of 64-bits values. 403 * \param [in] size Indicates the number of array elements. 404 * \param [in] r_size Actual number of array elements that are written 405 * into the data array. 406 * 407 * \retval SHR_E_NONE No errors. 408 * \retval !SHR_E_NONE Failure. 409 */ 410 extern int 411 bcmi_lt_entry_field_array_get(int unit, bcmi_lt_entry_t *entry, 412 const char *fld_name, uint16_t start_idx, 413 uint64_t *array, uint16_t size, uint16_t *r_size); 414 415 /*! 416 * \brief Add a symbol array to an entry. 417 * 418 * This function is used to add a symbol array to an entry. This function can 419 * be called multiple times with different start_idx values to construct a 420 * complete array of elements. For example, if the application wants to insert 421 * two elements at index 3 & 4 the application will set \c start_idx = 3 and 422 * num_of_elem = 2. Note that the array index starts from index 0. 423 * 424 * \param [in] unit Unit number. 425 * \param [in] entry LT entry information. 426 * \param [in] fld_name LT field name. 427 * \param [in] start_idx Target array index where elements should start 428 * being applied. 429 * \param [in] array Pointer to array of symbols (strings). 430 * \param [in] size Indicates the number of array elements. 431 * \param [in] flags Field flags(\c BCMI_LT_FIELD_F_SET 432 * or \c BCMI_LT_FIELD_F_GET). 433 * 434 * \retval None. 435 */ 436 extern void 437 bcmi_lt_entry_field_array_symbol_add(int unit, bcmi_lt_entry_t *entry, 438 const char *fld_name, uint16_t start_idx, 439 const char **array, uint16_t size, 440 uint16_t flags); 441 442 /*! 443 * \brief Get a symbol array from an entry. 444 * 445 * This function is used to get a symbol field array from an entry. This 446 * function can be called multiple times with different \c start_idx values 447 * to construct a complete array of elements. For example, if the application 448 * wants to get the values of two elements in index 3 & 4 the application will 449 * set \c start_idx = 3 and num_of_elem = 2. Note that the array index starts 450 * from index 0. 451 * 452 * \param [in] unit Unit number. 453 * \param [in] entry LT entry information. 454 * \param [in] fld_name LT field name. 455 * \param [in] start_idx Target array index where elements should start 456 * being applied. 457 * \param [out] array Pointer to array of symbols (strings). 458 * \param [in] size Indicates the number of array elements. 459 * \param [in] r_size Actual number of array elements that are written 460 * into the data array. 461 * 462 * \retval SHR_E_NONE No errors. 463 * \retval !SHR_E_NONE Failure. 464 */ 465 extern int 466 bcmi_lt_entry_field_array_symbol_get(int unit, bcmi_lt_entry_t *entry, 467 const char *fld_name, uint16_t start_idx, 468 const char **array, uint16_t size, 469 uint16_t *r_size); 470 471 /******************************************************************************/ 472 /* Encapsulation for Partial SDKLT LT API Sequence */ 473 /******************************************************************************/ 474 475 /*! 476 * \brief LT Synchronous entry commit. 477 * 478 * SDKLT LT commit APIs have been successful if the operation had been executed 479 * regardless of the actual result of the operation, and it is required to 480 * validate the entry status after the function returns. This function provides 481 * the encapsulation with the combination of above SDKLT operations. 482 * 483 * \param [in] unit Unit number. 484 * \param [in] entry_hdl Handle to the entry. 485 * \param [in] opcode LT operations code. 486 * \param [in] priority Priority. 487 * 488 * \retval SHR_E_NONE No errors. 489 * \retval !SHR_E_NONE Failure. 490 */ 491 extern int 492 bcmi_lt_entry_commit(int unit, bcmlt_entry_handle_t entry_hdl, 493 bcmlt_opcode_t opcode, bcmlt_priority_level_t priority); 494 495 /*! 496 * \brief Commit an entry with LT set operation. 497 * 498 * If the LT entry exists, it will be updated directly. If the LT entry doesn't 499 * exist, a new LT entry will be inserted. 500 * 501 * \param [in] unit Unit number. 502 * \param [in] entry_hdl Handle to the entry. 503 * \param [in] priority Priority. 504 * 505 * \retval SHR_E_NONE No errors. 506 * \retval !SHR_E_NONE Failure. 507 */ 508 extern int 509 bcmi_lt_entry_set_commit(int unit, bcmlt_entry_handle_t entry_hdl, 510 bcmlt_priority_level_t priority); 511 512 /*! 513 * \brief Transaction synchronous commit. 514 * 515 * SDKLT LT commit APIs have been successful if the operation had been executed 516 * regardless of the actual result of the operation, and it is required to 517 * validate the entry status after the function returns. This function provides 518 * the encapsulation with the combination of above SDKLT operations in 519 * transaction. 520 * 521 * \param [in] unit Unit number. 522 * \param [in] trans_hdl Handle to the transaction. 523 * \param [in] priority Priority. 524 * 525 * \retval SHR_E_NONE No errors. 526 * \retval !SHR_E_NONE Failure. 527 */ 528 extern int 529 bcmi_lt_transaction_commit(int unit,bcmlt_transaction_hdl_t trans_hdl, 530 bcmlt_priority_level_t priority); 531 532 /*! 533 * \brief Retrieve the definition of a specified LT field. 534 * 535 * This function retrieves the definition associated with the specified 536 * LT field on a particular device. 537 * 538 * \param [in] unit Unit number. 539 * \param [in] tbl_name LT name. 540 * \param [in] fld_name LT field name. 541 * \param [out] fld_def LT field definition. 542 * 543 * \retval SHR_E_NONE No errors. 544 * \retval !SHR_E_NONE Failure. 545 */ 546 extern int 547 bcmi_lt_field_def_get(int unit, const char *tbl_name, 548 const char *fld_name, bcmlt_field_def_t *fld_def); 549 550 /*! 551 * \brief Retrieve the width of a specified LT field. 552 * 553 * This function retrieves the width(number of bits) of the specified 554 * LT field on a particular device. 555 * 556 * \param [in] unit Unit number. 557 * \param [in] tbl_name LT name. 558 * \param [in] fld_name LT field name. 559 * \param [out] width LT field width. 560 * 561 * \retval SHR_E_NONE No errors. 562 * \retval !SHR_E_NONE Failure. 563 */ 564 extern int 565 bcmi_lt_field_width_get(int unit, const char *tbl_name, 566 const char *fld_name, uint32_t *width); 567 568 /*! 569 * \brief Retrieve the range of a specified LT field value. 570 * 571 * This function retrieves the allowed value range of a specified LT field 572 * on a particular device. 573 * 574 * \param [in] unit Unit number. 575 * \param [in] tbl_name LT name. 576 * \param [in] fld_name LT field name. 577 * \param [out] value_min Minimum field value allowed. 578 * \param [out] value_max Maximum field value allowed. 579 * 580 * \retval SHR_E_NONE No errors. 581 * \retval !SHR_E_NONE Failure. 582 */ 583 extern int 584 bcmi_lt_field_value_range_get(int unit, const char *tbl_name, 585 const char *fld_name, uint64_t *value_min, 586 uint64_t *value_max); 587 588 /*! 589 * \brief Get immutable properties of a field. 590 * 591 * \param [in] unit Unit number. 592 * \param [in] tbl_name LT name. 593 * \param [in] fld_name LT field name. 594 * \param [out] fld_info LT field info. 595 * 596 * \retval SHR_E_NONE No errors. 597 * \retval !SHR_E_NONE Failure. 598 */ 599 extern int 600 bcmi_lt_field_info_get(int unit, const char *tbl_name, const char *fld_name, 601 bcmi_lt_field_info_t *fld_info); 602 603 /*! 604 * \brief Check the specified field is valid. 605 * 606 * \param [in] unit Unit number. 607 * \param [in] tbl_name LT name. 608 * \param [in] fld_name LT field name. 609 * 610 * \retval SHR_E_NONE The field is valid. 611 * \retval !SHR_E_NONE The field is invalid. 612 */ 613 extern int 614 bcmi_lt_field_validate(int unit, const char *tbl_name, const char *fld_name); 615 616 /*! 617 * \brief Clear table content. 618 * 619 * This API clears the content of a table. 620 * 621 * \param [in] unit Unit number. 622 * \param [in] tbl_name LT name. 623 * 624 * \retval SHR_E_NONE No errors. 625 * \retval !SHR_E_NONE Failure. 626 */ 627 extern int 628 bcmi_lt_clear(int unit, const char *tbl_name); 629 630 /*! 631 * \brief Retrieves the capacity of a specified LT. 632 * 633 * This function retrieves the capacity of a specified LT. 634 * 635 * \param [in] unit Unit number. 636 * \param [in] tbl_name LT name. 637 * \param [out] entry_num Maximum number of entries in a table. 638 * 639 * \retval SHR_E_NONE No errors. 640 * \retval !SHR_E_NONE Failure. 641 */ 642 extern int 643 bcmi_lt_capacity_get(int unit, const char *tbl_name, uint32_t *entry_num); 644 645 /*! 646 * \brief Retrieves the current number of entries inserted in a specified LT. 647 * 648 * \param [in] unit Unit number. 649 * \param [in] tbl_name LT name. 650 * \param [out] cnt The number of entries inserted in a table. 651 * 652 * \retval SHR_E_NONE No errors. 653 * \retval !SHR_E_NONE Failure. 654 */ 655 extern int 656 bcmi_lt_entry_inuse_cnt_get(int unit, const char *tbl_name, uint32_t *cnt); 657 658 #endif /* BCMI_LT_INTF_H */