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          * [in] Flush pending HW cached flows every 1/10th of value
 565          * set in seconds, both idle and active flows are flushed
 566          * from the HW cache. If set to 0, this feature will be disabled.
 567          */
 568         uint8_t hw_flow_cache_flush_timer;
 569         /**
 570          * [out] table scope identifier
 571          */
 572         uint32_t tbl_scope_id;
 573 };
 574
 575 struct tf_free_tbl_scope_parms {
 576         /**
 577          * [in] table scope identifier
 578          */
 579         uint32_t tbl_scope_id;
 580 };
 581
 582 /**
 583  * allocate a table scope
 584  *
 585  * On Brd4 Firmware will allocate a scope ID.  On other devices, the scope
 586  * is a software construct to identify an EEM table.  This function will
 587  * divide the hash memory/buckets and records according to the device
 588  * device constraints based upon calculations using either the number of flows
 589  * requested or the size of memory indicated.  Other parameters passed in
 590  * determine the configuration (maximum key size, maximum external action record
 591  * size.
 592  *
 593  * This API will allocate the table region in
 594  * DRAM, program the PTU page table entries, and program the number of static
 595  * buckets (if Brd4) in the RX and TX CFAs.  Buckets are assumed to start at
 596  * 0 in the EM memory for the scope.  Upon successful completion of this API,
 597  * hash tables are fully initialized and ready for entries to be inserted.
 598  *
 599  * A single API is used to allocate a common table scope identifier in both
 600  * receive and transmit CFA. The scope identifier is common due to nature of
 601  * connection tracking sending notifications between RX and TX direction.
 602  *
 603  * The receive and transmit table access identifiers specify which rings will
 604  * be used to initialize table DRAM.  The application must ensure mutual
 605  * exclusivity of ring usage for table scope allocation and any table update
 606  * operations.
 607  *
 608  * The hash table buckets, EM keys, and EM lookup results are stored in the
 609  * memory allocated based on the rx_em_hash_mb/tx_em_hash_mb parameters.  The
 610  * hash table buckets are stored at the beginning of that memory.
 611  *
 612  * NOTE:  No EM internal setup is done here. On chip EM records are managed
 613  * internally by TruFlow core.
 614  *
 615  * Returns success or failure code.
 616  */
 617 int tf_alloc_tbl_scope(struct tf *tfp,
 618                        struct tf_alloc_tbl_scope_parms *parms);
 619
 620
 621 /**
 622  * free a table scope
 623  *
 624  * Firmware checks that the table scope ID is owned by the TruFlow
 625  * session, verifies that no references to this table scope remains
 626  * (Brd4 ILT) or Profile TCAM entries for either CFA (RX/TX) direction,
 627  * then frees the table scope ID.
 628  *
 629  * Returns success or failure code.
 630  */
 631 int tf_free_tbl_scope(struct tf *tfp,
 632                       struct tf_free_tbl_scope_parms *parms);
 633
 634 /**
 635  * TCAM table type
 636  */
 637 enum tf_tcam_tbl_type {
 638         TF_TCAM_TBL_TYPE_L2_CTXT_TCAM,
 639         TF_TCAM_TBL_TYPE_PROF_TCAM,
 640         TF_TCAM_TBL_TYPE_WC_TCAM,
 641         TF_TCAM_TBL_TYPE_SP_TCAM,
 642         TF_TCAM_TBL_TYPE_CT_RULE_TCAM,
 643         TF_TCAM_TBL_TYPE_VEB_TCAM,
 644         TF_TCAM_TBL_TYPE_MAX
 645
 646 };
 647
 648 /**
 649  * @page tcam TCAM Access
 650  *
 651  * @ref tf_alloc_tcam_entry
 652  *
 653  * @ref tf_set_tcam_entry
 654  *
 655  * @ref tf_get_tcam_entry
 656  *
 657  * @ref tf_free_tcam_entry
 658  */
 659
 660 /** tf_alloc_tcam_entry parameter definition
 661  */
 662 struct tf_alloc_tcam_entry_parms {
 663         /**
 664          * [in] receive or transmit direction
 665          */
 666         enum tf_dir dir;
 667         /**
 668          * [in] TCAM table type
 669          */
 670         enum tf_tcam_tbl_type tcam_tbl_type;
 671         /**
 672          * [in] Enable search for matching entry
 673          */
 674         uint8_t search_enable;
 675         /**
 676          * [in] Key data to match on (if search)
 677          */
 678         uint8_t *key;
 679         /**
 680          * [in] key size in bits (if search)
 681          */
 682         uint16_t key_sz_in_bits;
 683         /**
 684          * [in] Mask data to match on (if search)
 685          */
 686         uint8_t *mask;
 687         /**
 688          * [in] Priority of entry requested (definition TBD)
 689          */
 690         uint32_t priority;
 691         /**
 692          * [out] If search, set if matching entry found
 693          */
 694         uint8_t hit;
 695         /**
 696          * [out] Current refcnt after allocation
 697          */
 698         uint16_t ref_cnt;
 699         /**
 700          * [out] Idx allocated
 701          *
 702          */
 703         uint16_t idx;
 704 };
 705
 706 /** allocate TCAM entry
 707  *
 708  * Allocate a TCAM entry - one of these types:
 709  *
 710  * L2 Context
 711  * Profile TCAM
 712  * WC TCAM
 713  * VEB TCAM
 714  *
 715  * This function allocates a TCAM table record.  This function
 716  * will attempt to allocate a TCAM table entry from the session
 717  * owned TCAM entries or search a shadow copy of the TCAM table for a
 718  * matching entry if search is enabled.  Key, mask and result must match for
 719  * hit to be set.  Only TruFlow core data is accessed.
 720  * A hash table to entry mapping is maintained for search purposes.  If
 721  * search is not enabled, the first available free entry is returned based
 722  * on priority and alloc_cnt is set to 1.  If search is enabled and a matching
 723  * entry to entry_data is found, hit is set to TRUE and alloc_cnt is set to 1.
 724  * RefCnt is also returned.
 725  *
 726  * Also returns success or failure code.
 727  */
 728 int tf_alloc_tcam_entry(struct tf *tfp,
 729                         struct tf_alloc_tcam_entry_parms *parms);
 730
 731 /** tf_set_tcam_entry parameter definition
 732  */
 733 struct  tf_set_tcam_entry_parms {
 734         /**
 735          * [in] receive or transmit direction
 736          */
 737         enum tf_dir dir;
 738         /**
 739          * [in] TCAM table type
 740          */
 741         enum tf_tcam_tbl_type tcam_tbl_type;
 742         /**
 743          * [in] base index of the entry to program
 744          */
 745         uint16_t idx;
 746         /**
 747          * [in] struct containing key
 748          */
 749         uint8_t *key;
 750         /**
 751          * [in] struct containing mask fields
 752          */
 753         uint8_t *mask;
 754         /**
 755          * [in] key size in bits (if search)
 756          */
 757         uint16_t key_sz_in_bits;
 758         /**
 759          * [in] struct containing result
 760          */
 761         uint8_t *result;
 762         /**
 763          * [in] struct containing result size in bits
 764          */
 765         uint16_t result_sz_in_bits;
 766 };
 767
 768 /** set TCAM entry
 769  *
 770  * Program a TCAM table entry for a TruFlow session.
 771  *
 772  * If the entry has not been allocated, an error will be returned.
 773  *
 774  * Returns success or failure code.
 775  */
 776 int tf_set_tcam_entry(struct tf *tfp,
 777                       struct tf_set_tcam_entry_parms *parms);
 778
 779 /** tf_get_tcam_entry parameter definition
 780  */
 781 struct tf_get_tcam_entry_parms {
 782         /**
 783          * [in] receive or transmit direction
 784          */
 785         enum tf_dir dir;
 786         /**
 787          * [in] TCAM table type
 788          */
 789         enum tf_tcam_tbl_type  tcam_tbl_type;
 790         /**
 791          * [in] index of the entry to get
 792          */
 793         uint16_t idx;
 794         /**
 795          * [out] struct containing key
 796          */
 797         uint8_t *key;
 798         /**
 799          * [out] struct containing mask fields
 800          */
 801         uint8_t *mask;
 802         /**
 803          * [out] key size in bits
 804          */
 805         uint16_t key_sz_in_bits;
 806         /**
 807          * [out] struct containing result
 808          */
 809         uint8_t *result;
 810         /**
 811          * [out] struct containing result size in bits
 812          */
 813         uint16_t result_sz_in_bits;
 814 };
 815
 816 /** get TCAM entry
 817  *
 818  * Program a TCAM table entry for a TruFlow session.
 819  *
 820  * If the entry has not been allocated, an error will be returned.
 821  *
 822  * Returns success or failure code.
 823  */
 824 int tf_get_tcam_entry(struct tf *tfp,
 825                       struct tf_get_tcam_entry_parms *parms);
 826
 827 /** tf_free_tcam_entry parameter definition
 828  */
 829 struct tf_free_tcam_entry_parms {
 830         /**
 831          * [in] receive or transmit direction
 832          */
 833         enum tf_dir dir;
 834         /**
 835          * [in] TCAM table type
 836          */
 837         enum tf_tcam_tbl_type tcam_tbl_type;
 838         /**
 839          * [in] Index to free
 840          */
 841         uint16_t idx;
 842         /**
 843          * [out] reference count after free
 844          */
 845         uint16_t ref_cnt;
 846 };
 847
 848 /** free TCAM entry
 849  *
 850  * Free TCAM entry.
 851  *
 852  * Firmware checks to ensure the TCAM entries are owned by the TruFlow
 853  * session.  TCAM entry will be invalidated.  All-ones mask.
 854  * writes to hw.
 855  *
 856  * WCTCAM profile id of 0 must be used to invalidate an entry.
 857  *
 858  * Returns success or failure code.
 859  */
 860 int tf_free_tcam_entry(struct tf *tfp,
 861                        struct tf_free_tcam_entry_parms *parms);
 862
 863 /**
 864  * @page table Table Access
 865  *
 866  * @ref tf_alloc_tbl_entry
 867  *
 868  * @ref tf_free_tbl_entry
 869  *
 870  * @ref tf_set_tbl_entry
 871  *
 872  * @ref tf_get_tbl_entry
 873  */
 874
 875 /**
 876  * Enumeration of TruFlow table types. A table type is used to identify a
 877  * resource object.
 878  *
 879  * NOTE: The table type TF_TBL_TYPE_EXT is unique in that it is
 880  * the only table type that is connected with a table scope.
 881  */
 882 enum tf_tbl_type {
 883         /** Wh+/Brd2 Action Record */
 884         TF_TBL_TYPE_FULL_ACT_RECORD,
 885         /** Multicast Groups */
 886         TF_TBL_TYPE_MCAST_GROUPS,
 887         /** Action Encap 8 Bytes */
 888         TF_TBL_TYPE_ACT_ENCAP_8B,
 889         /** Action Encap 16 Bytes */
 890         TF_TBL_TYPE_ACT_ENCAP_16B,
 891         /** Action Encap 64 Bytes */
 892         TF_TBL_TYPE_ACT_ENCAP_32B,
 893         /** Action Encap 64 Bytes */
 894         TF_TBL_TYPE_ACT_ENCAP_64B,
 895         /** Action Source Properties SMAC */
 896         TF_TBL_TYPE_ACT_SP_SMAC,
 897         /** Action Source Properties SMAC IPv4 */
 898         TF_TBL_TYPE_ACT_SP_SMAC_IPV4,
 899         /** Action Source Properties SMAC IPv6 */
 900         TF_TBL_TYPE_ACT_SP_SMAC_IPV6,
 901         /** Action Statistics 64 Bits */
 902         TF_TBL_TYPE_ACT_STATS_64,
 903         /** Action Modify L4 Src Port */
 904         TF_TBL_TYPE_ACT_MODIFY_SPORT,
 905         /** Action Modify L4 Dest Port */
 906         TF_TBL_TYPE_ACT_MODIFY_DPORT,
 907         /** Action Modify IPv4 Source */
 908         TF_TBL_TYPE_ACT_MODIFY_IPV4_SRC,
 909         /** Action _Modify L4 Dest Port */
 910         TF_TBL_TYPE_ACT_MODIFY_IPV4_DEST,
 911         /** Action Modify IPv6 Source */
 912         TF_TBL_TYPE_ACT_MODIFY_IPV6_SRC,
 913         /** Action Modify IPv6 Destination */
 914         TF_TBL_TYPE_ACT_MODIFY_IPV6_DEST,
 915
 916         /* HW */
 917
 918         /** Meter Profiles */
 919         TF_TBL_TYPE_METER_PROF,
 920         /** Meter Instance */
 921         TF_TBL_TYPE_METER_INST,
 922         /** Mirror Config */
 923         TF_TBL_TYPE_MIRROR_CONFIG,
 924         /** UPAR */
 925         TF_TBL_TYPE_UPAR,
 926         /** Brd4 Epoch 0 table */
 927         TF_TBL_TYPE_EPOCH0,
 928         /** Brd4 Epoch 1 table  */
 929         TF_TBL_TYPE_EPOCH1,
 930         /** Brd4 Metadata  */
 931         TF_TBL_TYPE_METADATA,
 932         /** Brd4 CT State  */
 933         TF_TBL_TYPE_CT_STATE,
 934         /** Brd4 Range Profile  */
 935         TF_TBL_TYPE_RANGE_PROF,
 936         /** Brd4 Range Entry  */
 937         TF_TBL_TYPE_RANGE_ENTRY,
 938         /** Brd4 LAG Entry  */
 939         TF_TBL_TYPE_LAG,
 940         /** Brd4 only VNIC/SVIF Table */
 941         TF_TBL_TYPE_VNIC_SVIF,
 942
 943         /* External */
 944
 945         /** External table type - initially 1 poolsize entries.
 946          * All External table types are associated with a table
 947          * scope. Internal types are not.
 948          */
 949         TF_TBL_TYPE_EXT,
 950         TF_TBL_TYPE_MAX
 951 };
 952
 953 /** tf_alloc_tbl_entry parameter definition
 954  */
 955 struct tf_alloc_tbl_entry_parms {
 956         /**
 957          * [in] Receive or transmit direction
 958          */
 959         enum tf_dir dir;
 960         /**
 961          * [in] Type of the allocation
 962          */
 963         enum tf_tbl_type type;
 964         /**
 965          * [in] Table scope identifier (ignored unless TF_TBL_TYPE_EXT)
 966          */
 967         uint32_t tbl_scope_id;
 968         /**
 969          * [in] Enable search for matching entry. If the table type is
 970          * internal the shadow copy will be searched before
 971          * alloc. Session must be configured with shadow copy enabled.
 972          */
 973         uint8_t search_enable;
 974         /**
 975          * [in] Result data to search for (if search_enable)
 976          */
 977         uint8_t *result;
 978         /**
 979          * [in] Result data size in bytes (if search_enable)
 980          */
 981         uint16_t result_sz_in_bytes;
 982         /**
 983          * [out] If search_enable, set if matching entry found
 984          */
 985         uint8_t hit;
 986         /**
 987          * [out] Current ref count after allocation (if search_enable)
 988          */
 989         uint16_t ref_cnt;
 990         /**
 991          * [out] Idx of allocated entry or found entry (if search_enable)
 992          */
 993         uint32_t idx;
 994 };
 995
 996 /** allocate index table entries
 997  *
 998  * Internal types:
 999  *
1000  * Allocate an on chip index table entry or search for a matching
1001  * entry of the indicated type for this TruFlow session.
1002  *
1003  * Allocates an index table record. This function will attempt to
1004  * allocate an entry or search an index table for a matching entry if
1005  * search is enabled (only the shadow copy of the table is accessed).
1006  *
1007  * If search is not enabled, the first available free entry is
1008  * returned. If search is enabled and a matching entry to entry_data
1009  * is found hit is set to TRUE and success is returned.
1010  *
1011  * External types:
1012  *
1013  * These are used to allocate inlined action record memory.
1014  *
1015  * Allocates an external index table action record.
1016  *
1017  * NOTE:
1018  * Implementation of the internals of this function will be a stack with push
1019  * and pop.
1020  *
1021  * Returns success or failure code.
1022  */
1023 int tf_alloc_tbl_entry(struct tf *tfp,
1024                        struct tf_alloc_tbl_entry_parms *parms);
1025
1026 /** tf_free_tbl_entry parameter definition
1027  */
1028 struct tf_free_tbl_entry_parms {
1029         /**
1030          * [in] Receive or transmit direction
1031          */
1032         enum tf_dir dir;
1033         /**
1034          * [in] Type of the allocation type
1035          */
1036         enum tf_tbl_type type;
1037         /**
1038          * [in] Table scope identifier (ignored unless TF_TBL_TYPE_EXT)
1039          */
1040         uint32_t tbl_scope_id;
1041         /**
1042          * [in] Index to free
1043          */
1044         uint32_t idx;
1045         /**
1046          * [out] Reference count after free, only valid if session has been
1047          * created with shadow_copy.
1048          */
1049         uint16_t ref_cnt;
1050 };
1051
1052 /** free index table entry
1053  *
1054  * Used to free a previously allocated table entry.
1055  *
1056  * Internal types:
1057  *
1058  * If session has shadow_copy enabled the shadow DB is searched and if
1059  * found the element ref_cnt is decremented. If ref_cnt goes to
1060  * zero then the element is returned to the session pool.
1061  *
1062  * If the session does not have a shadow DB the element is free'ed and
1063  * given back to the session pool.
1064  *
1065  * External types:
1066  *
1067  * Free's an external index table action record.
1068  *
1069  * NOTE:
1070  * Implementation of the internals of this function will be a stack with push
1071  * and pop.
1072  *
1073  * Returns success or failure code.
1074  */
1075 int tf_free_tbl_entry(struct tf *tfp,
1076                       struct tf_free_tbl_entry_parms *parms);
1077
1078 /** tf_set_tbl_entry parameter definition
1079  */
1080 struct tf_set_tbl_entry_parms {
1081         /**
1082          * [in] Table scope identifier
1083          */
1084         uint32_t tbl_scope_id;
1085         /**
1086          * [in] Receive or transmit direction
1087          */
1088         enum tf_dir dir;
1089         /**
1090          * [in] Type of object to set
1091          */
1092         enum tf_tbl_type type;
1093         /**
1094          * [in] Entry data
1095          */
1096         uint8_t *data;
1097         /**
1098          * [in] Entry size
1099          */
1100         uint16_t data_sz_in_bytes;
1101         /**
1102          * [in] Entry index to write to
1103          */
1104         uint32_t idx;
1105 };
1106
1107 /** set index table entry
1108  *
1109  * Used to insert an application programmed index table entry into a
1110  * previous allocated table location.  A shadow copy of the table
1111  * is maintained (if enabled) (only for internal objects)
1112  *
1113  * Returns success or failure code.
1114  */
1115 int tf_set_tbl_entry(struct tf *tfp,
1116                      struct tf_set_tbl_entry_parms *parms);
1117
1118 /** tf_get_tbl_entry parameter definition
1119  */
1120 struct tf_get_tbl_entry_parms {
1121         /**
1122          * [in] Receive or transmit direction
1123          */
1124         enum tf_dir dir;
1125         /**
1126          * [in] Type of object to get
1127          */
1128         enum tf_tbl_type type;
1129         /**
1130          * [out] Entry data
1131          */
1132         uint8_t *data;
1133         /**
1134          * [out] Entry size
1135          */
1136         uint16_t data_sz_in_bytes;
1137         /**
1138          * [in] Entry index to read
1139          */
1140         uint32_t idx;
1141 };
1142
1143 /** get index table entry
1144  *
1145  * Used to retrieve a previous set index table entry.
1146  *
1147  * Reads and compares with the shadow table copy (if enabled) (only
1148  * for internal objects).
1149  *
1150  * Returns success or failure code. Failure will be returned if the
1151  * provided data buffer is too small for the data type requested.
1152  */
1153 int tf_get_tbl_entry(struct tf *tfp,
1154                      struct tf_get_tbl_entry_parms *parms);
1155
1156 /**
1157  * @page exact_match Exact Match Table
1158  *
1159  * @ref tf_insert_em_entry
1160  *
1161  * @ref tf_delete_em_entry
1162  *
1163  * @ref tf_search_em_entry
1164  *
1165  */
1166 /** tf_insert_em_entry parameter definition
1167  */
1168 struct tf_insert_em_entry_parms {
1169         /**
1170          * [in] receive or transmit direction
1171          */
1172         enum tf_dir dir;
1173         /**
1174          * [in] internal or external
1175          */
1176         enum tf_mem mem;
1177         /**
1178          * [in] ID of table scope to use (external only)
1179          */
1180         uint32_t tbl_scope_id;
1181         /**
1182          * [in] ID of table interface to use (Brd4 only)
1183          */
1184         uint32_t tbl_if_id;
1185         /**
1186          * [in] ptr to structure containing key fields
1187          */
1188         uint8_t *key;
1189         /**
1190          * [in] key bit length
1191          */
1192         uint16_t key_sz_in_bits;
1193         /**
1194          * [in] ptr to structure containing result field
1195          */
1196         uint8_t *em_record;
1197         /**
1198          * [out] result size in bits
1199          */
1200         uint16_t em_record_sz_in_bits;
1201         /**
1202          * [in] duplicate check flag
1203          */
1204         uint8_t dup_check;
1205         /**
1206          * [out] Flow handle value for the inserted entry.  This is encoded
1207          * as the entries[4]:bucket[2]:hashId[1]:hash[14]
1208          */
1209         uint64_t flow_handle;
1210         /**
1211          * [out] Flow id is returned as null (internal)
1212          * Flow id is the GFID value for the inserted entry (external)
1213          * This is the value written to the BD and useful information for mark.
1214          */
1215         uint64_t flow_id;
1216 };
1217 /**
1218  * tf_delete_em_entry parameter definition
1219  */
1220 struct tf_delete_em_entry_parms {
1221         /**
1222          * [in] receive or transmit direction
1223          */
1224         enum tf_dir dir;
1225         /**
1226          * [in] internal or external
1227          */
1228         enum tf_mem mem;
1229         /**
1230          * [in] ID of table scope to use (external only)
1231          */
1232         uint32_t tbl_scope_id;
1233         /**
1234          * [in] ID of table interface to use (Brd4 only)
1235          */
1236         uint32_t tbl_if_id;
1237         /**
1238          * [in] epoch group IDs of entry to delete
1239          * 2 element array with 2 ids. (Brd4 only)
1240          */
1241         uint16_t *epochs;
1242         /**
1243          * [in] structure containing flow delete handle information
1244          */
1245         uint64_t flow_handle;
1246 };
1247 /**
1248  * tf_search_em_entry parameter definition
1249  */
1250 struct tf_search_em_entry_parms {
1251         /**
1252          * [in] receive or transmit direction
1253          */
1254         enum tf_dir dir;
1255         /**
1256          * [in] internal or external
1257          */
1258         enum tf_mem mem;
1259         /**
1260          * [in] ID of table scope to use (external only)
1261          */
1262         uint32_t tbl_scope_id;
1263         /**
1264          * [in] ID of table interface to use (Brd4 only)
1265          */
1266         uint32_t tbl_if_id;
1267         /**
1268          * [in] ptr to structure containing key fields
1269          */
1270         uint8_t *key;
1271         /**
1272          * [in] key bit length
1273          */
1274         uint16_t key_sz_in_bits;
1275         /**
1276          * [in/out] ptr to structure containing EM record fields
1277          */
1278         uint8_t *em_record;
1279         /**
1280          * [out] result size in bits
1281          */
1282         uint16_t em_record_sz_in_bits;
1283         /**
1284          * [in] epoch group IDs of entry to lookup
1285          * 2 element array with 2 ids. (Brd4 only)
1286          */
1287         uint16_t *epochs;
1288         /**
1289          * [in] ptr to structure containing flow delete handle
1290          */
1291         uint64_t flow_handle;
1292 };
1293
1294 /** insert em hash entry in internal table memory
1295  *
1296  * Internal:
1297  *
1298  * This API inserts an exact match entry into internal EM table memory
1299  * of the specified direction.
1300  *
1301  * Note: The EM record is managed within the TruFlow core and not the
1302  * application.
1303  *
1304  * Shadow copy of internal record table an association with hash and 1,2, or 4
1305  * associated buckets
1306  *
1307  * External:
1308  * This API inserts an exact match entry into DRAM EM table memory of the
1309  * specified direction and table scope.
1310  *
1311  * When inserting an entry into an exact match table, the TruFlow library may
1312  * need to allocate a dynamic bucket for the entry (Brd4 only).
1313  *
1314  * The insertion of duplicate entries in an EM table is not permitted.  If a
1315  * TruFlow application can guarantee that it will never insert duplicates, it
1316  * can disable duplicate checking by passing a zero value in the  dup_check
1317  * parameter to this API.  This will optimize performance. Otherwise, the
1318  * TruFlow library will enforce protection against inserting duplicate entries.
1319  *
1320  * Flow handle is defined in this document:
1321  *
1322  * https://docs.google.com
1323  * /document/d/1NESu7RpTN3jwxbokaPfYORQyChYRmJgs40wMIRe8_-Q/edit
1324  *
1325  * Returns success or busy code.
1326  *
1327  */
1328 int tf_insert_em_entry(struct tf *tfp,
1329                        struct tf_insert_em_entry_parms *parms);
1330
1331 /** delete em hash entry table memory
1332  *
1333  * Internal:
1334  *
1335  * This API deletes an exact match entry from internal EM table memory of the
1336  * specified direction. If a valid flow ptr is passed in then that takes
1337  * precedence over the pointer to the complete key passed in.
1338  *
1339  *
1340  * External:
1341  *
1342  * This API deletes an exact match entry from EM table memory of the specified
1343  * direction and table scope. If a valid flow handle is passed in then that
1344  * takes precedence over the pointer to the complete key passed in.
1345  *
1346  * The TruFlow library may release a dynamic bucket when an entry is deleted.
1347  *
1348  *
1349  * Returns success or not found code
1350  *
1351  *
1352  */
1353 int tf_delete_em_entry(struct tf *tfp,
1354                        struct tf_delete_em_entry_parms *parms);
1355
1356 /** search em hash entry table memory
1357  *
1358  * Internal:
1359
1360  * This API looks up an EM entry in table memory with the specified EM
1361  * key or flow (flow takes precedence) and direction.
1362  *
1363  * The status will be one of: success or entry not found.  If the lookup
1364  * succeeds, a pointer to the matching entry and the result record associated
1365  * with the matching entry will be provided.
1366  *
1367  * If flow_handle is set, search shadow copy.
1368  *
1369  * Otherwise, query the fw with key to get result.
1370  *
1371  * External:
1372  *
1373  * This API looks up an EM entry in table memory with the specified EM
1374  * key or flow_handle (flow takes precedence), direction and table scope.
1375  *
1376  * The status will be one of: success or entry not found.  If the lookup
1377  * succeeds, a pointer to the matching entry and the result record associated
1378  * with the matching entry will be provided.
1379  *
1380  * Returns success or not found code
1381  *
1382  */
1383 int tf_search_em_entry(struct tf *tfp,
1384                        struct tf_search_em_entry_parms *parms);
1385 #endif /* _TF_CORE_H_ */