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