drivers/net/bnxt/tf_core/tf_core.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2019-2020 Broadcom
   3  * All rights reserved.
   4  */
   5
   6 #ifndef _TF_CORE_H_
   7 #define _TF_CORE_H_
   8
   9 #include <stdint.h>
  10 #include <stdlib.h>
  11 #include <stdbool.h>
  12 #include <stdio.h>
  13
  14 #include "tf_project.h"
  15
  16 /**
  17  * @file
  18  *
  19  * Truflow Core API Header File
  20  */
  21
  22 /********** BEGIN Truflow Core DEFINITIONS **********/
  23
  24
  25 #define TF_KILOBYTE  1024
  26 #define TF_MEGABYTE  (1024 * 1024)
  27
  28 /**
  29  * direction
  30  */
  31 enum tf_dir {
  32         TF_DIR_RX,  /**< Receive */
  33         TF_DIR_TX,  /**< Transmit */
  34         TF_DIR_MAX
  35 };
  36
  37 /**
  38  * memory choice
  39  */
  40 enum tf_mem {
  41         TF_MEM_INTERNAL, /**< Internal */
  42         TF_MEM_EXTERNAL, /**< External */
  43         TF_MEM_MAX
  44 };
  45
  46 /**
  47  * The size of the external action record (Wh+/Brd2)
  48  *
  49  * Currently set to 512.
  50  *
  51  * AR (16B) + encap (256B) + stats_ptrs (8) + resvd (8)
  52  * + stats (16) = 304 aligned on a 16B boundary
  53  *
  54  * Theoretically, the size should be smaller. ~304B
  55  */
  56 #define TF_ACTION_RECORD_SZ 512
  57
  58 /**
  59  * External pool size
  60  *
  61  * Defines a single pool of external action records of
  62  * fixed size.  Currently, this is an index.
  63  */
  64 #define TF_EXT_POOL_ENTRY_SZ_BYTES 1
  65
  66 /**
  67  *  External pool entry count
  68  *
  69  *  Defines the number of entries in the external action pool
  70  */
  71 #define TF_EXT_POOL_ENTRY_CNT (1 * 1024)
  72
  73 /**
  74  * Number of external pools
  75  */
  76 #define TF_EXT_POOL_CNT_MAX 1
  77
  78 /**
  79  * External pool Id
  80  */
  81 #define TF_EXT_POOL_0      0 /**< matches TF_TBL_TYPE_EXT   */
  82 #define TF_EXT_POOL_1      1 /**< matches TF_TBL_TYPE_EXT_0 */
  83
  84 /** EEM record AR helper
  85  *
  86  * Helpers to handle the Action Record Pointer in the EEM Record Entry.
  87  *
  88  * Convert absolute offset to action record pointer in EEM record entry
  89  * Convert action record pointer in EEM record entry to absolute offset
  90  */
  91 #define TF_ACT_REC_OFFSET_2_PTR(offset) ((offset) >> 4)
  92 #define TF_ACT_REC_PTR_2_OFFSET(offset) ((offset) << 4)
  93
  94 #define TF_ACT_REC_INDEX_2_OFFSET(idx) ((idx) << 9)
  95
  96 /*
  97  * Helper Macros
  98  */
  99 #define TF_BITS_2_BYTES(num_bits) (((num_bits) + 7) / 8)
 100
 101 /********** BEGIN API FUNCTION PROTOTYPES/PARAMETERS **********/
 102
 103 /**
 104  * @page general General
 105  *
 106  * @ref tf_open_session
 107  *
 108  * @ref tf_attach_session
 109  *
 110  * @ref tf_close_session
 111  */
 112
 113
 114 /** Session Version defines
 115  *
 116  * The version controls the format of the tf_session and
 117  * tf_session_info structure. This is to assure upgrade between
 118  * versions can be supported.
 119  */
 120 #define TF_SESSION_VER_MAJOR  1   /**< Major Version */
 121 #define TF_SESSION_VER_MINOR  0   /**< Minor Version */
 122 #define TF_SESSION_VER_UPDATE 0   /**< Update Version */
 123
 124 /** Session Name
 125  *
 126  * Name of the TruFlow control channel interface.  Expects
 127  * format to be RTE Name specific, i.e. rte_eth_dev_get_name_by_port()
 128  */
 129 #define TF_SESSION_NAME_MAX       64
 130
 131 #define TF_FW_SESSION_ID_INVALID  0xFF  /**< Invalid FW Session ID define */
 132
 133 /** Session Identifier
 134  *
 135  * Unique session identifier which includes PCIe bus info to
 136  * distinguish the PF and session info to identify the associated
 137  * TruFlow session. Session ID is constructed from the passed in
 138  * ctrl_chan_name in tf_open_session() together with an allocated
 139  * fw_session_id. Done by TruFlow on tf_open_session().
 140  */
 141 union tf_session_id {
 142         uint32_t id;
 143         struct {
 144                 uint8_t domain;
 145                 uint8_t bus;
 146                 uint8_t device;
 147                 uint8_t fw_session_id;
 148         } internal;
 149 };
 150
 151 /** Session Version
 152  *
 153  * The version controls the format of the tf_session and
 154  * tf_session_info structure. This is to assure upgrade between
 155  * versions can be supported.
 156  *
 157  * Please see the TF_VER_MAJOR/MINOR and UPDATE defines.
 158  */
 159 struct tf_session_version {
 160         uint8_t major;
 161         uint8_t minor;
 162         uint8_t update;
 163 };
 164
 165 /** Session supported device types
 166  *
 167  */
 168 enum tf_device_type {
 169         TF_DEVICE_TYPE_WH = 0, /**< Whitney+  */
 170         TF_DEVICE_TYPE_BRD2,   /**< TBD       */
 171         TF_DEVICE_TYPE_BRD3,   /**< TBD       */
 172         TF_DEVICE_TYPE_BRD4,   /**< TBD       */
 173         TF_DEVICE_TYPE_MAX     /**< Maximum   */
 174 };
 175
 176 /** TruFlow Session Information
 177  *
 178  * Structure defining a TruFlow Session, also known as a Management
 179  * session. This structure is initialized at time of
 180  * tf_open_session(). It is passed to all of the TruFlow APIs as way
 181  * to prescribe and isolate resources between different TruFlow ULP
 182  * Applications.
 183  */
 184 struct tf_session_info {
 185         /**
 186          * TrueFlow Version. Used to control the structure layout when
 187          * sharing sessions. No guarantee that a secondary process
 188          * would come from the same version of an executable.
 189          * TruFlow initializes this variable on tf_open_session().
 190          *
 191          * Owner:  TruFlow
 192          * Access: TruFlow
 193          */
 194         struct tf_session_version ver;
 195         /**
 196          * will be STAILQ_ENTRY(tf_session_info) next
 197          *
 198          * Owner:  ULP
 199          * Access: ULP
 200          */
 201         void                 *next;
 202         /**
 203          * Session ID is a unique identifier for the session. TruFlow
 204          * initializes this variable during tf_open_session()
 205          * processing.
 206          *
 207          * Owner:  TruFlow
 208          * Access: Truflow & ULP
 209          */
 210         union tf_session_id   session_id;
 211         /**
 212          * Protects access to core_data. Lock is initialized and owned
 213          * by ULP. TruFlow can access the core_data without checking
 214          * the lock.
 215          *
 216          * Owner:  ULP
 217          * Access: ULP
 218          */
 219         uint8_t               spin_lock;
 220         /**
 221          * The core_data holds the TruFlow tf_session data
 222          * structure. This memory is allocated and owned by TruFlow on
 223          * tf_open_session().
 224          *
 225          * TruFlow uses this memory for session management control
 226          * until the session is closed by ULP. Access control is done
 227          * by the spin_lock which ULP controls ahead of TruFlow API
 228          * calls.
 229          *
 230          * Please see tf_open_session_parms for specification details
 231          * on this variable.
 232          *
 233          * Owner:  TruFlow
 234          * Access: TruFlow
 235          */
 236         void                 *core_data;
 237         /**
 238          * The core_data_sz_bytes specifies the size of core_data in
 239          * bytes.
 240          *
 241          * The size is set by TruFlow on tf_open_session().
 242          *
 243          * Please see tf_open_session_parms for specification details
 244          * on this variable.
 245          *
 246          * Owner:  TruFlow
 247          * Access: TruFlow
 248          */
 249         uint32_t              core_data_sz_bytes;
 250 };
 251
 252 /** TruFlow handle
 253  *
 254  * Contains a pointer to the session info. Allocated by ULP and passed
 255  * to TruFlow using tf_open_session(). TruFlow will populate the
 256  * session info at that time. Additional 'opens' can be done using
 257  * same session_info by using tf_attach_session().
 258  *
 259  * It is expected that ULP allocates this memory as shared memory.
 260  *
 261  * NOTE: This struct must be within the BNXT PMD struct bnxt
 262  *       (bp). This allows use of container_of() to get access to the PMD.
 263  */
 264 struct tf {
 265         struct tf_session_info *session;
 266 };
 267
 268
 269 /**
 270  * tf_open_session parameters definition.
 271  */
 272 struct tf_open_session_parms {
 273         /** [in] ctrl_chan_name
 274          *
 275          * String containing name of control channel interface to be
 276          * used for this session to communicate with firmware.
 277          *
 278          * The ctrl_chan_name can be looked up by using
 279          * rte_eth_dev_get_name_by_port() within the ULP.
 280          *
 281          * ctrl_chan_name will be used as part of a name for any
 282          * shared memory allocation.
 283          */
 284         char ctrl_chan_name[TF_SESSION_NAME_MAX];
 285         /** [in] shadow_copy
 286          *
 287          * Boolean controlling the use and availability of shadow
 288          * copy. Shadow copy will allow the TruFlow to keep track of
 289          * resource content on the firmware side without having to
 290          * query firmware. Additional private session core_data will
 291          * be allocated if this boolean is set to 'true', default
 292          * 'false'.
 293          *
 294          * Size of memory depends on the NVM Resource settings for the
 295          * control channel.
 296          */
 297         bool shadow_copy;
 298         /** [in/out] session_id
 299          *
 300          * Session_id is unique per session.
 301          *
 302          * Session_id is composed of domain, bus, device and
 303          * fw_session_id. The construction is done by parsing the
 304          * ctrl_chan_name together with allocation of a fw_session_id.
 305          *
 306          * The session_id allows a session to be shared between devices.
 307          */
 308         union tf_session_id session_id;
 309         /** [in] device type
 310          *
 311          * Device type is passed, one of Wh+, Brd2, Brd3, Brd4
 312          */
 313         enum tf_device_type device_type;
 314 };
 315
 316 /**
 317  * Opens a new TruFlow management session.
 318  *
 319  * TruFlow will allocate session specific memory, shared memory, to
 320  * hold its session data. This data is private to TruFlow.
 321  *
 322  * Multiple PFs can share the same session. An association, refcount,
 323  * between session and PFs is maintained within TruFlow. Thus, a PF
 324  * can attach to an existing session, see tf_attach_session().
 325  *
 326  * No other TruFlow APIs will succeed unless this API is first called and
 327  * succeeds.
 328  *
 329  * tf_open_session() returns a session id that can be used on attach.
 330  *
 331  * [in] tfp
 332  *   Pointer to TF handle
 333  * [in] parms
 334  *   Pointer to open parameters
 335  *
 336  * Returns
 337  *   - (0) if successful.
 338  *   - (-EINVAL) on failure.
 339  */
 340 int tf_open_session(struct tf *tfp,
 341                     struct tf_open_session_parms *parms);
 342
 343 struct tf_attach_session_parms {
 344         /** [in] ctrl_chan_name
 345          *
 346          * String containing name of control channel interface to be
 347          * used for this session to communicate with firmware.
 348          *
 349          * The ctrl_chan_name can be looked up by using
 350          * rte_eth_dev_get_name_by_port() within the ULP.
 351          *
 352          * ctrl_chan_name will be used as part of a name for any
 353          * shared memory allocation.
 354          */
 355         char ctrl_chan_name[TF_SESSION_NAME_MAX];
 356
 357         /** [in] attach_chan_name
 358          *
 359          * String containing name of attach channel interface to be
 360          * used for this session.
 361          *
 362          * The attach_chan_name must be given to a 2nd process after
 363          * the primary process has been created. This is the
 364          * ctrl_chan_name of the primary process and is used to find
 365          * the shared memory for the session that the attach is going
 366          * to use.
 367          */
 368         char attach_chan_name[TF_SESSION_NAME_MAX];
 369
 370         /** [in] session_id
 371          *
 372          * Session_id is unique per session. For Attach the session_id
 373          * should be the session_id that was returned on the first
 374          * open.
 375          *
 376          * Session_id is composed of domain, bus, device and
 377          * fw_session_id. The construction is done by parsing the
 378          * ctrl_chan_name together with allocation of a fw_session_id
 379          * during tf_open_session().
 380          *
 381          * A reference count will be incremented on attach. A session
 382          * is first fully closed when reference count is zero by
 383          * calling tf_close_session().
 384          */
 385         union tf_session_id session_id;
 386 };
 387
 388 /**
 389  * Attaches to an existing session. Used when more than one PF wants
 390  * to share a single session. In that case all TruFlow management
 391  * traffic will be sent to the TruFlow firmware using the 'PF' that
 392  * did the attach not the session ctrl channel.
 393  *
 394  * Attach will increment a ref count as to manage the shared session data.
 395  *
 396  * [in] tfp, pointer to TF handle
 397  * [in] parms, pointer to attach parameters
 398  *
 399  * Returns
 400  *   - (0) if successful.
 401  *   - (-EINVAL) on failure.
 402  */
 403 int tf_attach_session(struct tf *tfp,
 404                       struct tf_attach_session_parms *parms);
 405
 406 /**
 407  * Closes an existing session. Cleans up all hardware and firmware
 408  * state associated with the TruFlow application session when the last
 409  * PF associated with the session results in refcount to be zero.
 410  *
 411  * Returns success or failure code.
 412  */
 413 int tf_close_session(struct tf *tfp);
 414
 415 /**
 416  * @page  ident Identity Management
 417  *
 418  * @ref tf_alloc_identifier
 419  *
 420  * @ref tf_free_identifier
 421  */
 422 enum tf_identifier_type {
 423         /** The L2 Context is returned from the L2 Ctxt TCAM lookup
 424          *  and can be used in WC TCAM or EM keys to virtualize further
 425          *  lookups.
 426          */
 427         TF_IDENT_TYPE_L2_CTXT,
 428         /** The WC profile func is returned from the L2 Ctxt TCAM lookup
 429          *  to enable virtualization of the profile TCAM.
 430          */
 431         TF_IDENT_TYPE_PROF_FUNC,
 432         /** The WC profile ID is included in the WC lookup key
 433          *  to enable virtualization of the WC TCAM hardware.
 434          */
 435         TF_IDENT_TYPE_WC_PROF,
 436         /** The EM profile ID is included in the EM lookup key
 437          *  to enable virtualization of the EM hardware. (not required for Brd4
 438          *  as it has table scope)
 439          */
 440         TF_IDENT_TYPE_EM_PROF,
 441         /** The L2 func is included in the ILT result and from recycling to
 442          *  enable virtualization of further lookups.
 443          */
 444         TF_IDENT_TYPE_L2_FUNC
 445 };
 446
 447 /** tf_alloc_identifier parameter definition
 448  */
 449 struct tf_alloc_identifier_parms {
 450         /**
 451          * [in]  receive or transmit direction
 452          */
 453         enum tf_dir dir;
 454         /**
 455          * [in] Identifier type
 456          */
 457         enum tf_identifier_type ident_type;
 458         /**
 459          * [out] Identifier allocated
 460          */
 461         uint16_t id;
 462 };
 463
 464 /** tf_free_identifier parameter definition
 465  */
 466 struct tf_free_identifier_parms {
 467         /**
 468          * [in]  receive or transmit direction
 469          */
 470         enum tf_dir dir;
 471         /**
 472          * [in] Identifier type
 473          */
 474         enum tf_identifier_type ident_type;
 475         /**
 476          * [in] ID to free
 477          */
 478         uint16_t id;
 479 };
 480
 481 /** allocate identifier resource
 482  *
 483  * TruFlow core will allocate a free id from the per identifier resource type
 484  * pool reserved for the session during tf_open().  No firmware is involved.
 485  *
 486  * Returns success or failure code.
 487  */
 488 int tf_alloc_identifier(struct tf *tfp,
 489                         struct tf_alloc_identifier_parms *parms);
 490
 491 /** free identifier resource
 492  *
 493  * TruFlow core will return an id back to the per identifier resource type pool
 494  * reserved for the session.  No firmware is involved.  During tf_close, the
 495  * complete pool is returned to the firmware.
 496  *
 497  * Returns success or failure code.
 498  */
 499 int tf_free_identifier(struct tf *tfp,
 500                        struct tf_free_identifier_parms *parms);
 501
 502 /**
 503  * @page dram_table DRAM Table Scope Interface
 504  *
 505  * @ref tf_alloc_tbl_scope
 506  *
 507  * @ref tf_free_tbl_scope
 508  *
 509  * If we allocate the EEM memory from the core, we need to store it in
 510  * the shared session data structure to make sure it can be freed later.
 511  * (for example if the PF goes away)
 512  *
 513  * Current thought is that memory is allocated within core.
 514  */
 515
 516
 517 /** tf_alloc_tbl_scope_parms definition
 518  */
 519 struct tf_alloc_tbl_scope_parms {
 520         /**
 521          * [in] All Maximum key size required.
 522          */
 523         uint16_t rx_max_key_sz_in_bits;
 524         /**
 525          * [in] Maximum Action size required (includes inlined items)
 526          */
 527         uint16_t rx_max_action_entry_sz_in_bits;
 528         /**
 529          * [in] Memory size in Megabytes
 530          * Total memory size allocated by user to be divided
 531          * up for actions, hash, counters.  Only inline external actions.
 532          * Use this variable or the number of flows, do not set both.
 533          */
 534         uint32_t rx_mem_size_in_mb;
 535         /**
 536          * [in] Number of flows * 1000. If set, rx_mem_size_in_mb must equal 0.
 537          */
 538         uint32_t rx_num_flows_in_k;
 539         /**
 540          * [in] Brd4 only receive table access interface id
 541          */
 542         uint32_t rx_tbl_if_id;
 543         /**
 544          * [in] All Maximum key size required.
 545          */
 546         uint16_t tx_max_key_sz_in_bits;
 547         /**
 548          * [in] Maximum Action size required (includes inlined items)
 549          */
 550         uint16_t tx_max_action_entry_sz_in_bits;
 551         /**
 552          * [in] Memory size in Megabytes
 553          * Total memory size allocated by user to be divided
 554          * up for actions, hash, counters.  Only inline external actions.
 555          */
 556         uint32_t tx_mem_size_in_mb;
 557         /**
 558          * [in] Number of flows * 1000
 559          */
 560         uint32_t tx_num_flows_in_k;
 561         /**
 562          * [in] Brd4 only receive table access interface id
 563          */
 564         uint32_t tx_tbl_if_id;
 565         /**
 566          * [out] table scope identifier
 567          */
 568         uint32_t tbl_scope_id;
 569 };
 570
 571 struct tf_free_tbl_scope_parms {
 572         /**
 573          * [in] table scope identifier
 574          */
 575         uint32_t tbl_scope_id;
 576 };
 577
 578 /**
 579  * allocate a table scope
 580  *
 581  * On Brd4 Firmware will allocate a scope ID.  On other devices, the scope
 582  * is a software construct to identify an EEM table.  This function will
 583  * divide the hash memory/buckets and records according to the device
 584  * device constraints based upon calculations using either the number of flows
 585  * requested or the size of memory indicated.  Other parameters passed in
 586  * determine the configuration (maximum key size, maximum external action record
 587  * size.
 588  *
 589  * This API will allocate the table region in
 590  * DRAM, program the PTU page table entries, and program the number of static
 591  * buckets (if Brd4) in the RX and TX CFAs.  Buckets are assumed to start at
 592  * 0 in the EM memory for the scope.  Upon successful completion of this API,
 593  * hash tables are fully initialized and ready for entries to be inserted.
 594  *
 595  * A single API is used to allocate a common table scope identifier in both
 596  * receive and transmit CFA. The scope identifier is common due to nature of
 597  * connection tracking sending notifications between RX and TX direction.
 598  *
 599  * The receive and transmit table access identifiers specify which rings will
 600  * be used to initialize table DRAM.  The application must ensure mutual
 601  * exclusivity of ring usage for table scope allocation and any table update
 602  * operations.
 603  *
 604  * The hash table buckets, EM keys, and EM lookup results are stored in the
 605  * memory allocated based on the rx_em_hash_mb/tx_em_hash_mb parameters.  The
 606  * hash table buckets are stored at the beginning of that memory.
 607  *
 608  * NOTE:  No EM internal setup is done here. On chip EM records are managed
 609  * internally by TruFlow core.
 610  *
 611  * Returns success or failure code.
 612  */
 613 int tf_alloc_tbl_scope(struct tf *tfp,
 614                        struct tf_alloc_tbl_scope_parms *parms);
 615
 616
 617 /**
 618  * free a table scope
 619  *
 620  * Firmware checks that the table scope ID is owned by the TruFlow
 621  * session, verifies that no references to this table scope remains
 622  * (Brd4 ILT) or Profile TCAM entries for either CFA (RX/TX) direction,
 623  * then frees the table scope ID.
 624  *
 625  * Returns success or failure code.
 626  */
 627 int tf_free_tbl_scope(struct tf *tfp,
 628                       struct tf_free_tbl_scope_parms *parms);
 629
 630 /**
 631  * TCAM table type
 632  */
 633 enum tf_tcam_tbl_type {
 634         TF_TCAM_TBL_TYPE_L2_CTXT_TCAM,
 635         TF_TCAM_TBL_TYPE_PROF_TCAM,
 636         TF_TCAM_TBL_TYPE_WC_TCAM,
 637         TF_TCAM_TBL_TYPE_SP_TCAM,
 638         TF_TCAM_TBL_TYPE_CT_RULE_TCAM,
 639         TF_TCAM_TBL_TYPE_VEB_TCAM,
 640         TF_TCAM_TBL_TYPE_MAX
 641
 642 };
 643
 644 /**
 645  * @page tcam TCAM Access
 646  *
 647  * @ref tf_alloc_tcam_entry
 648  *
 649  * @ref tf_set_tcam_entry
 650  *
 651  * @ref tf_get_tcam_entry
 652  *
 653  * @ref tf_free_tcam_entry
 654  */
 655
 656 /** tf_alloc_tcam_entry parameter definition
 657  */
 658 struct tf_alloc_tcam_entry_parms {
 659         /**
 660          * [in] receive or transmit direction
 661          */
 662         enum tf_dir dir;
 663         /**
 664          * [in] TCAM table type
 665          */
 666         enum tf_tcam_tbl_type tcam_tbl_type;
 667         /**
 668          * [in] Enable search for matching entry
 669          */
 670         uint8_t search_enable;
 671         /**
 672          * [in] Key data to match on (if search)
 673          */
 674         uint8_t *key;
 675         /**
 676          * [in] key size in bits (if search)
 677          */
 678         uint16_t key_sz_in_bits;
 679         /**
 680          * [in] Mask data to match on (if search)
 681          */
 682         uint8_t *mask;
 683         /**
 684          * [in] Priority of entry requested (definition TBD)
 685          */
 686         uint32_t priority;
 687         /**
 688          * [out] If search, set if matching entry found
 689          */
 690         uint8_t hit;
 691         /**
 692          * [out] Current refcnt after allocation
 693          */
 694         uint16_t ref_cnt;
 695         /**
 696          * [out] Idx allocated
 697          *
 698          */
 699         uint16_t idx;
 700 };
 701
 702 /** allocate TCAM entry
 703  *
 704  * Allocate a TCAM entry - one of these types:
 705  *
 706  * L2 Context
 707  * Profile TCAM
 708  * WC TCAM
 709  * VEB TCAM
 710  *
 711  * This function allocates a TCAM table record.  This function
 712  * will attempt to allocate a TCAM table entry from the session
 713  * owned TCAM entries or search a shadow copy of the TCAM table for a
 714  * matching entry if search is enabled.  Key, mask and result must match for
 715  * hit to be set.  Only TruFlow core data is accessed.
 716  * A hash table to entry mapping is maintained for search purposes.  If
 717  * search is not enabled, the first available free entry is returned based
 718  * on priority and alloc_cnt is set to 1.  If search is enabled and a matching
 719  * entry to entry_data is found, hit is set to TRUE and alloc_cnt is set to 1.
 720  * RefCnt is also returned.
 721  *
 722  * Also returns success or failure code.
 723  */
 724 int tf_alloc_tcam_entry(struct tf *tfp,
 725                         struct tf_alloc_tcam_entry_parms *parms);
 726
 727 /** tf_set_tcam_entry parameter definition
 728  */
 729 struct  tf_set_tcam_entry_parms {
 730         /**
 731          * [in] receive or transmit direction
 732          */
 733         enum tf_dir dir;
 734         /**
 735          * [in] TCAM table type
 736          */
 737         enum tf_tcam_tbl_type tcam_tbl_type;
 738         /**
 739          * [in] base index of the entry to program
 740          */
 741         uint16_t idx;
 742         /**
 743          * [in] struct containing key
 744          */
 745         uint8_t *key;
 746         /**
 747          * [in] struct containing mask fields
 748          */
 749         uint8_t *mask;
 750         /**
 751          * [in] key size in bits (if search)
 752          */
 753         uint16_t key_sz_in_bits;
 754         /**
 755          * [in] struct containing result
 756          */
 757         uint8_t *result;
 758         /**
 759          * [in] struct containing result size in bits
 760          */
 761         uint16_t result_sz_in_bits;
 762 };
 763
 764 /** set TCAM entry
 765  *
 766  * Program a TCAM table entry for a TruFlow session.
 767  *
 768  * If the entry has not been allocated, an error will be returned.
 769  *
 770  * Returns success or failure code.
 771  */
 772 int tf_set_tcam_entry(struct tf *tfp,
 773                       struct tf_set_tcam_entry_parms *parms);
 774
 775 /** tf_get_tcam_entry parameter definition
 776  */
 777 struct tf_get_tcam_entry_parms {
 778         /**
 779          * [in] receive or transmit direction
 780          */
 781         enum tf_dir dir;
 782         /**
 783          * [in] TCAM table type
 784          */
 785         enum tf_tcam_tbl_type  tcam_tbl_type;
 786         /**
 787          * [in] index of the entry to get
 788          */
 789         uint16_t idx;
 790         /**
 791          * [out] struct containing key
 792          */
 793         uint8_t *key;
 794         /**
 795          * [out] struct containing mask fields
 796          */
 797         uint8_t *mask;
 798         /**
 799          * [out] key size in bits
 800          */
 801         uint16_t key_sz_in_bits;
 802         /**
 803          * [out] struct containing result
 804          */
 805         uint8_t *result;
 806         /**
 807          * [out] struct containing result size in bits
 808          */
 809         uint16_t result_sz_in_bits;
 810 };
 811
 812 /** get TCAM entry
 813  *
 814  * Program a TCAM table entry for a TruFlow session.
 815  *
 816  * If the entry has not been allocated, an error will be returned.
 817  *
 818  * Returns success or failure code.
 819  */
 820 int tf_get_tcam_entry(struct tf *tfp,
 821                       struct tf_get_tcam_entry_parms *parms);
 822
 823 /** tf_free_tcam_entry parameter definition
 824  */
 825 struct tf_free_tcam_entry_parms {
 826         /**
 827          * [in] receive or transmit direction
 828          */
 829         enum tf_dir dir;
 830         /**
 831          * [in] TCAM table type
 832          */
 833         enum tf_tcam_tbl_type tcam_tbl_type;
 834         /**
 835          * [in] Index to free
 836          */
 837         uint16_t idx;
 838         /**
 839          * [out] reference count after free
 840          */
 841         uint16_t ref_cnt;
 842 };
 843
 844 /** free TCAM entry
 845  *
 846  * Free TCAM entry.
 847  *
 848  * Firmware checks to ensure the TCAM entries are owned by the TruFlow
 849  * session.  TCAM entry will be invalidated.  All-ones mask.
 850  * writes to hw.
 851  *
 852  * WCTCAM profile id of 0 must be used to invalidate an entry.
 853  *
 854  * Returns success or failure code.
 855  */
 856 int tf_free_tcam_entry(struct tf *tfp,
 857                        struct tf_free_tcam_entry_parms *parms);
 858
 859 /**
 860  * @page table Table Access
 861  *
 862  * @ref tf_alloc_tbl_entry
 863  *
 864  * @ref tf_free_tbl_entry
 865  *
 866  * @ref tf_set_tbl_entry
 867  *
 868  * @ref tf_get_tbl_entry
 869  */
 870
 871 /**
 872  * Enumeration of TruFlow table types. A table type is used to identify a
 873  * resource object.
 874  *
 875  * NOTE: The table type TF_TBL_TYPE_EXT is unique in that it is
 876  * the only table type that is connected with a table scope.
 877  */
 878 enum tf_tbl_type {
 879         /** Wh+/Brd2 Action Record */
 880         TF_TBL_TYPE_FULL_ACT_RECORD,
 881         /** Multicast Groups */
 882         TF_TBL_TYPE_MCAST_GROUPS,
 883         /** Action Encap 8 Bytes */
 884         TF_TBL_TYPE_ACT_ENCAP_8B,
 885         /** Action Encap 16 Bytes */
 886         TF_TBL_TYPE_ACT_ENCAP_16B,
 887         /** Action Encap 64 Bytes */
 888         TF_TBL_TYPE_ACT_ENCAP_32B,
 889         /** Action Encap 64 Bytes */
 890         TF_TBL_TYPE_ACT_ENCAP_64B,
 891         /** Action Source Properties SMAC */
 892         TF_TBL_TYPE_ACT_SP_SMAC,
 893         /** Action Source Properties SMAC IPv4 */
 894         TF_TBL_TYPE_ACT_SP_SMAC_IPV4,
 895         /** Action Source Properties SMAC IPv6 */
 896         TF_TBL_TYPE_ACT_SP_SMAC_IPV6,
 897         /** Action Statistics 64 Bits */
 898         TF_TBL_TYPE_ACT_STATS_64,
 899         /** Action Modify L4 Src Port */
 900         TF_TBL_TYPE_ACT_MODIFY_SPORT,
 901         /** Action Modify L4 Dest Port */
 902         TF_TBL_TYPE_ACT_MODIFY_DPORT,
 903         /** Action Modify IPv4 Source */
 904         TF_TBL_TYPE_ACT_MODIFY_IPV4_SRC,
 905         /** Action _Modify L4 Dest Port */
 906         TF_TBL_TYPE_ACT_MODIFY_IPV4_DEST,
 907         /** Action Modify IPv6 Source */
 908         TF_TBL_TYPE_ACT_MODIFY_IPV6_SRC,
 909         /** Action Modify IPv6 Destination */
 910         TF_TBL_TYPE_ACT_MODIFY_IPV6_DEST,
 911
 912         /* HW */
 913
 914         /** Meter Profiles */
 915         TF_TBL_TYPE_METER_PROF,
 916         /** Meter Instance */
 917         TF_TBL_TYPE_METER_INST,
 918         /** Mirror Config */
 919         TF_TBL_TYPE_MIRROR_CONFIG,
 920         /** UPAR */
 921         TF_TBL_TYPE_UPAR,
 922         /** Brd4 Epoch 0 table */
 923         TF_TBL_TYPE_EPOCH0,
 924         /** Brd4 Epoch 1 table  */
 925         TF_TBL_TYPE_EPOCH1,
 926         /** Brd4 Metadata  */
 927         TF_TBL_TYPE_METADATA,
 928         /** Brd4 CT State  */
 929         TF_TBL_TYPE_CT_STATE,
 930         /** Brd4 Range Profile  */
 931         TF_TBL_TYPE_RANGE_PROF,
 932         /** Brd4 Range Entry  */
 933         TF_TBL_TYPE_RANGE_ENTRY,
 934         /** Brd4 LAG Entry  */
 935         TF_TBL_TYPE_LAG,
 936         /** Brd4 only VNIC/SVIF Table */
 937         TF_TBL_TYPE_VNIC_SVIF,
 938
 939         /* External */
 940
 941         /** External table type - initially 1 poolsize entries.
 942          * All External table types are associated with a table
 943          * scope. Internal types are not.
 944          */
 945         TF_TBL_TYPE_EXT,
 946         /** Future - external pool of size0 entries */
 947         TF_TBL_TYPE_EXT_0,
 948         TF_TBL_TYPE_MAX
 949 };
 950
 951 /** tf_alloc_tbl_entry parameter definition
 952  */
 953 struct tf_alloc_tbl_entry_parms {
 954         /**
 955          * [in] Receive or transmit direction
 956          */
 957         enum tf_dir dir;
 958         /**
 959          * [in] Type of the allocation
 960          */
 961         enum tf_tbl_type type;
 962         /**
 963          * [in] Enable search for matching entry. If the table type is
 964          * internal the shadow copy will be searched before
 965          * alloc. Session must be configured with shadow copy enabled.
 966          */
 967         uint8_t search_enable;
 968         /**
 969          * [in] Result data to search for (if search_enable)
 970          */
 971         uint8_t *result;
 972         /**
 973          * [in] Result data size in bytes (if search_enable)
 974          */
 975         uint16_t result_sz_in_bytes;
 976         /**
 977          * [out] If search_enable, set if matching entry found
 978          */
 979         uint8_t hit;
 980         /**
 981          * [out] Current ref count after allocation (if search_enable)
 982          */
 983         uint16_t ref_cnt;
 984         /**
 985          * [out] Idx of allocated entry or found entry (if search_enable)
 986          */
 987         uint32_t idx;
 988 };
 989
 990 /** allocate index table entries
 991  *
 992  * Internal types:
 993  *
 994  * Allocate an on chip index table entry or search for a matching
 995  * entry of the indicated type for this TruFlow session.
 996  *
 997  * Allocates an index table record. This function will attempt to
 998  * allocate an entry or search an index table for a matching entry if
 999  * search is enabled (only the shadow copy of the table is accessed).
1000  *
1001  * If search is not enabled, the first available free entry is
1002  * returned. If search is enabled and a matching entry to entry_data
1003  * is found hit is set to TRUE and success is returned.
1004  *
1005  * External types:
1006  *
1007  * These are used to allocate inlined action record memory.
1008  *
1009  * Allocates an external index table action record.
1010  *
1011  * NOTE:
1012  * Implementation of the internals of this function will be a stack with push
1013  * and pop.
1014  *
1015  * Returns success or failure code.
1016  */
1017 int tf_alloc_tbl_entry(struct tf *tfp,
1018                        struct tf_alloc_tbl_entry_parms *parms);
1019
1020 /** tf_free_tbl_entry parameter definition
1021  */
1022 struct tf_free_tbl_entry_parms {
1023         /**
1024          * [in] Receive or transmit direction
1025          */
1026         enum tf_dir dir;
1027         /**
1028          * [in] Type of the allocation type
1029          */
1030         enum tf_tbl_type type;
1031         /**
1032          * [in] Index to free
1033          */
1034         uint32_t idx;
1035         /**
1036          * [out] Reference count after free, only valid if session has been
1037          * created with shadow_copy.
1038          */
1039         uint16_t ref_cnt;
1040 };
1041
1042 /** free index table entry
1043  *
1044  * Used to free a previously allocated table entry.
1045  *
1046  * Internal types:
1047  *
1048  * If session has shadow_copy enabled the shadow DB is searched and if
1049  * found the element ref_cnt is decremented. If ref_cnt goes to
1050  * zero then the element is returned to the session pool.
1051  *
1052  * If the session does not have a shadow DB the element is free'ed and
1053  * given back to the session pool.
1054  *
1055  * External types:
1056  *
1057  * Free's an external index table action record.
1058  *
1059  * NOTE:
1060  * Implementation of the internals of this function will be a stack with push
1061  * and pop.
1062  *
1063  * Returns success or failure code.
1064  */
1065 int tf_free_tbl_entry(struct tf *tfp,
1066                       struct tf_free_tbl_entry_parms *parms);
1067
1068 /** tf_set_tbl_entry parameter definition
1069  */
1070 struct tf_set_tbl_entry_parms {
1071         /**
1072          * [in] Table scope identifier
1073          *
1074          */
1075         uint32_t tbl_scope_id;
1076         /**
1077          * [in] Receive or transmit direction
1078          */
1079         enum tf_dir dir;
1080         /**
1081          * [in] Type of object to set
1082          */
1083         enum tf_tbl_type type;
1084         /**
1085          * [in] Entry data
1086          */
1087         uint8_t *data;
1088         /**
1089          * [in] Entry size
1090          */
1091         uint16_t data_sz_in_bytes;
1092         /**
1093          * [in] Entry index to write to
1094          */
1095         uint32_t idx;
1096 };
1097
1098 /** set index table entry
1099  *
1100  * Used to insert an application programmed index table entry into a
1101  * previous allocated table location.  A shadow copy of the table
1102  * is maintained (if enabled) (only for internal objects)
1103  *
1104  * Returns success or failure code.
1105  */
1106 int tf_set_tbl_entry(struct tf *tfp,
1107                      struct tf_set_tbl_entry_parms *parms);
1108
1109 /** tf_get_tbl_entry parameter definition
1110  */
1111 struct tf_get_tbl_entry_parms {
1112         /**
1113          * [in] Receive or transmit direction
1114          */
1115         enum tf_dir dir;
1116         /**
1117          * [in] Type of object to get
1118          */
1119         enum tf_tbl_type type;
1120         /**
1121          * [out] Entry data
1122          */
1123         uint8_t *data;
1124         /**
1125          * [out] Entry size
1126          */
1127         uint16_t data_sz_in_bytes;
1128         /**
1129          * [in] Entry index to read
1130          */
1131         uint32_t idx;
1132 };
1133
1134 /** get index table entry
1135  *
1136  * Used to retrieve a previous set index table entry.
1137  *
1138  * Reads and compares with the shadow table copy (if enabled) (only
1139  * for internal objects).
1140  *
1141  * Returns success or failure code. Failure will be returned if the
1142  * provided data buffer is too small for the data type requested.
1143  */
1144 int tf_get_tbl_entry(struct tf *tfp,
1145                      struct tf_get_tbl_entry_parms *parms);
1146
1147 /**
1148  * @page exact_match Exact Match Table
1149  *
1150  * @ref tf_insert_em_entry
1151  *
1152  * @ref tf_delete_em_entry
1153  *
1154  * @ref tf_search_em_entry
1155  *
1156  */
1157 /** tf_insert_em_entry parameter definition
1158  */
1159 struct tf_insert_em_entry_parms {
1160         /**
1161          * [in] receive or transmit direction
1162          */
1163         enum tf_dir dir;
1164         /**
1165          * [in] internal or external
1166          */
1167         enum tf_mem mem;
1168         /**
1169          * [in] ID of table scope to use (external only)
1170          */
1171         uint32_t tbl_scope_id;
1172         /**
1173          * [in] ID of table interface to use (Brd4 only)
1174          */
1175         uint32_t tbl_if_id;
1176         /**
1177          * [in] ptr to structure containing key fields
1178          */
1179         uint8_t *key;
1180         /**
1181          * [in] key bit length
1182          */
1183         uint16_t key_sz_in_bits;
1184         /**
1185          * [in] ptr to structure containing result field
1186          */
1187         uint8_t *em_record;
1188         /**
1189          * [out] result size in bits
1190          */
1191         uint16_t em_record_sz_in_bits;
1192         /**
1193          * [in] duplicate check flag
1194          */
1195         uint8_t dup_check;
1196         /**
1197          * [out] Flow handle value for the inserted entry.  This is encoded
1198          * as the entries[4]:bucket[2]:hashId[1]:hash[14]
1199          */
1200         uint64_t flow_handle;
1201         /**
1202          * [out] Flow id is returned as null (internal)
1203          * Flow id is the GFID value for the inserted entry (external)
1204          * This is the value written to the BD and useful information for mark.
1205          */
1206         uint64_t flow_id;
1207 };
1208 /**
1209  * tf_delete_em_entry parameter definition
1210  */
1211 struct tf_delete_em_entry_parms {
1212         /**
1213          * [in] receive or transmit direction
1214          */
1215         enum tf_dir dir;
1216         /**
1217          * [in] internal or external
1218          */
1219         enum tf_mem mem;
1220         /**
1221          * [in] ID of table scope to use (external only)
1222          */
1223         uint32_t tbl_scope_id;
1224         /**
1225          * [in] ID of table interface to use (Brd4 only)
1226          */
1227         uint32_t tbl_if_id;
1228         /**
1229          * [in] epoch group IDs of entry to delete
1230          * 2 element array with 2 ids. (Brd4 only)
1231          */
1232         uint16_t *epochs;
1233         /**
1234          * [in] structure containing flow delete handle information
1235          */
1236         uint64_t flow_handle;
1237 };
1238 /**
1239  * tf_search_em_entry parameter definition
1240  */
1241 struct tf_search_em_entry_parms {
1242         /**
1243          * [in] receive or transmit direction
1244          */
1245         enum tf_dir dir;
1246         /**
1247          * [in] internal or external
1248          */
1249         enum tf_mem mem;
1250         /**
1251          * [in] ID of table scope to use (external only)
1252          */
1253         uint32_t tbl_scope_id;
1254         /**
1255          * [in] ID of table interface to use (Brd4 only)
1256          */
1257         uint32_t tbl_if_id;
1258         /**
1259          * [in] ptr to structure containing key fields
1260          */
1261         uint8_t *key;
1262         /**
1263          * [in] key bit length
1264          */
1265         uint16_t key_sz_in_bits;
1266         /**
1267          * [in/out] ptr to structure containing EM record fields
1268          */
1269         uint8_t *em_record;
1270         /**
1271          * [out] result size in bits
1272          */
1273         uint16_t em_record_sz_in_bits;
1274         /**
1275          * [in] epoch group IDs of entry to lookup
1276          * 2 element array with 2 ids. (Brd4 only)
1277          */
1278         uint16_t *epochs;
1279         /**
1280          * [in] ptr to structure containing flow delete handle
1281          */
1282         uint64_t flow_handle;
1283 };
1284
1285 /** insert em hash entry in internal table memory
1286  *
1287  * Internal:
1288  *
1289  * This API inserts an exact match entry into internal EM table memory
1290  * of the specified direction.
1291  *
1292  * Note: The EM record is managed within the TruFlow core and not the
1293  * application.
1294  *
1295  * Shadow copy of internal record table an association with hash and 1,2, or 4
1296  * associated buckets
1297  *
1298  * External:
1299  * This API inserts an exact match entry into DRAM EM table memory of the
1300  * specified direction and table scope.
1301  *
1302  * When inserting an entry into an exact match table, the TruFlow library may
1303  * need to allocate a dynamic bucket for the entry (Brd4 only).
1304  *
1305  * The insertion of duplicate entries in an EM table is not permitted.  If a
1306  * TruFlow application can guarantee that it will never insert duplicates, it
1307  * can disable duplicate checking by passing a zero value in the  dup_check
1308  * parameter to this API.  This will optimize performance. Otherwise, the
1309  * TruFlow library will enforce protection against inserting duplicate entries.
1310  *
1311  * Flow handle is defined in this document:
1312  *
1313  * https://docs.google.com
1314  * /document/d/1NESu7RpTN3jwxbokaPfYORQyChYRmJgs40wMIRe8_-Q/edit
1315  *
1316  * Returns success or busy code.
1317  *
1318  */
1319 int tf_insert_em_entry(struct tf *tfp,
1320                        struct tf_insert_em_entry_parms *parms);
1321
1322 /** delete em hash entry table memory
1323  *
1324  * Internal:
1325  *
1326  * This API deletes an exact match entry from internal EM table memory of the
1327  * specified direction. If a valid flow ptr is passed in then that takes
1328  * precedence over the pointer to the complete key passed in.
1329  *
1330  *
1331  * External:
1332  *
1333  * This API deletes an exact match entry from EM table memory of the specified
1334  * direction and table scope. If a valid flow handle is passed in then that
1335  * takes precedence over the pointer to the complete key passed in.
1336  *
1337  * The TruFlow library may release a dynamic bucket when an entry is deleted.
1338  *
1339  *
1340  * Returns success or not found code
1341  *
1342  *
1343  */
1344 int tf_delete_em_entry(struct tf *tfp,
1345                        struct tf_delete_em_entry_parms *parms);
1346
1347 /** search em hash entry table memory
1348  *
1349  * Internal:
1350
1351  * This API looks up an EM entry in table memory with the specified EM
1352  * key or flow (flow takes precedence) and direction.
1353  *
1354  * The status will be one of: success or entry not found.  If the lookup
1355  * succeeds, a pointer to the matching entry and the result record associated
1356  * with the matching entry will be provided.
1357  *
1358  * If flow_handle is set, search shadow copy.
1359  *
1360  * Otherwise, query the fw with key to get result.
1361  *
1362  * External:
1363  *
1364  * This API looks up an EM entry in table memory with the specified EM
1365  * key or flow_handle (flow takes precedence), direction and table scope.
1366  *
1367  * The status will be one of: success or entry not found.  If the lookup
1368  * succeeds, a pointer to the matching entry and the result record associated
1369  * with the matching entry will be provided.
1370  *
1371  * Returns success or not found code
1372  *
1373  */
1374 int tf_search_em_entry(struct tf *tfp,
1375                        struct tf_search_em_entry_parms *parms);
1376 #endif /* _TF_CORE_H_ */