1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2019-2020 Broadcom
14 #include "tf_project.h"
19 * Truflow Core API Header File
22 /********** BEGIN Truflow Core DEFINITIONS **********/
25 #define TF_KILOBYTE 1024
26 #define TF_MEGABYTE (1024 * 1024)
32 TF_DIR_RX, /**< Receive */
33 TF_DIR_TX, /**< Transmit */
41 TF_MEM_INTERNAL, /**< Internal */
42 TF_MEM_EXTERNAL, /**< External */
47 * The size of the external action record (Wh+/Brd2)
49 * Currently set to 512.
51 * AR (16B) + encap (256B) + stats_ptrs (8) + resvd (8)
52 * + stats (16) = 304 aligned on a 16B boundary
54 * Theoretically, the size should be smaller. ~304B
56 #define TF_ACTION_RECORD_SZ 512
61 * Defines a single pool of external action records of
62 * fixed size. Currently, this is an index.
64 #define TF_EXT_POOL_ENTRY_SZ_BYTES 1
67 * External pool entry count
69 * Defines the number of entries in the external action pool
71 #define TF_EXT_POOL_ENTRY_CNT (1 * 1024)
74 * Number of external pools
76 #define TF_EXT_POOL_CNT_MAX 1
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 */
84 /** EEM record AR helper
86 * Helper to handle the Action Record Pointer in the EEM Record Entry.
88 * Convert absolute offset to action record pointer in EEM record entry
89 * Convert action record pointer in EEM record entry to absolute offset
91 #define TF_ACT_REC_OFFSET_2_PTR(offset) ((offset) >> 4)
92 #define TF_ACT_REC_PTR_2_OFFSET(offset) ((offset) << 4)
97 #define TF_BITS_2_BYTES(num_bits) (((num_bits) + 7) / 8)
99 /********** BEGIN API FUNCTION PROTOTYPES/PARAMETERS **********/
102 * @page general General
104 * @ref tf_open_session
106 * @ref tf_attach_session
108 * @ref tf_close_session
112 /** Session Version defines
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.
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 */
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()
127 #define TF_SESSION_NAME_MAX 64
129 #define TF_FW_SESSION_ID_INVALID 0xFF /**< Invalid FW Session ID define */
131 /** Session Identifier
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().
139 union tf_session_id {
145 uint8_t fw_session_id;
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.
155 * Please see the TF_VER_MAJOR/MINOR and UPDATE defines.
157 struct tf_session_version {
163 /** Session supported device types
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 */
174 /** TruFlow Session Information
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
182 struct tf_session_info {
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().
192 struct tf_session_version ver;
194 * will be STAILQ_ENTRY(tf_session_info) next
201 * Session ID is a unique identifier for the session. TruFlow
202 * initializes this variable during tf_open_session()
206 * Access: Truflow & ULP
208 union tf_session_id session_id;
210 * Protects access to core_data. Lock is initialized and owned
211 * by ULP. TruFlow can access the core_data without checking
219 * The core_data holds the TruFlow tf_session data
220 * structure. This memory is allocated and owned by TruFlow on
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
228 * Please see tf_open_session_parms for specification details
236 * The core_data_sz_bytes specifies the size of core_data in
239 * The size is set by TruFlow on tf_open_session().
241 * Please see tf_open_session_parms for specification details
247 uint32_t core_data_sz_bytes;
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().
257 * It is expected that ULP allocates this memory as shared memory.
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.
263 struct tf_session_info *session;
268 * tf_open_session parameters definition.
270 struct tf_open_session_parms {
271 /** [in] ctrl_chan_name
273 * String containing name of control channel interface to be
274 * used for this session to communicate with firmware.
276 * The ctrl_chan_name can be looked up by using
277 * rte_eth_dev_get_name_by_port() within the ULP.
279 * ctrl_chan_name will be used as part of a name for any
280 * shared memory allocation.
282 char ctrl_chan_name[TF_SESSION_NAME_MAX];
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
292 * Size of memory depends on the NVM Resource settings for the
296 /** [in/out] session_id
298 * Session_id is unique per session.
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.
304 * The session_id allows a session to be shared between devices.
306 union tf_session_id session_id;
309 * Device type is passed, one of Wh+, Brd2, Brd3, Brd4
311 enum tf_device_type device_type;
315 * Opens a new TruFlow management session.
317 * TruFlow will allocate session specific memory, shared memory, to
318 * hold its session data. This data is private to TruFlow.
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().
324 * No other TruFlow APIs will succeed unless this API is first called and
327 * tf_open_session() returns a session id that can be used on attach.
330 * Pointer to TF handle
332 * Pointer to open parameters
335 * - (0) if successful.
336 * - (-EINVAL) on failure.
338 int tf_open_session(struct tf *tfp,
339 struct tf_open_session_parms *parms);
341 struct tf_attach_session_parms {
342 /** [in] ctrl_chan_name
344 * String containing name of control channel interface to be
345 * used for this session to communicate with firmware.
347 * The ctrl_chan_name can be looked up by using
348 * rte_eth_dev_get_name_by_port() within the ULP.
350 * ctrl_chan_name will be used as part of a name for any
351 * shared memory allocation.
353 char ctrl_chan_name[TF_SESSION_NAME_MAX];
355 /** [in] attach_chan_name
357 * String containing name of attach channel interface to be
358 * used for this session.
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
366 char attach_chan_name[TF_SESSION_NAME_MAX];
370 * Session_id is unique per session. For Attach the session_id
371 * should be the session_id that was returned on the first
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().
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().
383 union tf_session_id session_id;
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.
392 * Attach will increment a ref count as to manage the shared session data.
394 * [in] tfp, pointer to TF handle
395 * [in] parms, pointer to attach parameters
398 * - (0) if successful.
399 * - (-EINVAL) on failure.
401 int tf_attach_session(struct tf *tfp,
402 struct tf_attach_session_parms *parms);
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.
409 * Returns success or failure code.
411 int tf_close_session(struct tf *tfp);
414 * @page ident Identity Management
416 * @ref tf_alloc_identifier
418 * @ref tf_free_identifier
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
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.
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.
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)
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.
442 TF_IDENT_TYPE_L2_FUNC
445 /** tf_alloc_identifier parameter definition
447 struct tf_alloc_identifier_parms {
449 * [in] receive or transmit direction
453 * [in] Identifier type
455 enum tf_identifier_type ident_type;
457 * [out] Identifier allocated
462 /** tf_free_identifier parameter definition
464 struct tf_free_identifier_parms {
466 * [in] receive or transmit direction
470 * [in] Identifier type
472 enum tf_identifier_type ident_type;
479 /** allocate identifier resource
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.
484 * Returns success or failure code.
486 int tf_alloc_identifier(struct tf *tfp,
487 struct tf_alloc_identifier_parms *parms);
489 /** free identifier resource
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.
495 * Returns success or failure code.
497 int tf_free_identifier(struct tf *tfp,
498 struct tf_free_identifier_parms *parms);
501 * @page dram_table DRAM Table Scope Interface
503 * @ref tf_alloc_tbl_scope
505 * @ref tf_free_tbl_scope
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)
511 * Current thought is that memory is allocated within core.
515 /** tf_alloc_tbl_scope_parms definition
517 struct tf_alloc_tbl_scope_parms {
519 * [in] All Maximum key size required.
521 uint16_t rx_max_key_sz_in_bits;
523 * [in] Maximum Action size required (includes inlined items)
525 uint16_t rx_max_action_entry_sz_in_bits;
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.
532 uint32_t rx_mem_size_in_mb;
534 * [in] Number of flows * 1000. If set, rx_mem_size_in_mb must equal 0.
536 uint32_t rx_num_flows_in_k;
538 * [in] Brd4 only receive table access interface id
540 uint32_t rx_tbl_if_id;
542 * [in] All Maximum key size required.
544 uint16_t tx_max_key_sz_in_bits;
546 * [in] Maximum Action size required (includes inlined items)
548 uint16_t tx_max_action_entry_sz_in_bits;
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.
554 uint32_t tx_mem_size_in_mb;
556 * [in] Number of flows * 1000
558 uint32_t tx_num_flows_in_k;
560 * [in] Brd4 only receive table access interface id
562 uint32_t tx_tbl_if_id;
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.
568 uint8_t hw_flow_cache_flush_timer;
570 * [out] table scope identifier
572 uint32_t tbl_scope_id;
575 struct tf_free_tbl_scope_parms {
577 * [in] table scope identifier
579 uint32_t tbl_scope_id;
583 * allocate a table scope
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
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.
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.
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
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.
612 * NOTE: No EM internal setup is done here. On chip EM records are managed
613 * internally by TruFlow core.
615 * Returns success or failure code.
617 int tf_alloc_tbl_scope(struct tf *tfp,
618 struct tf_alloc_tbl_scope_parms *parms);
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.
629 * Returns success or failure code.
631 int tf_free_tbl_scope(struct tf *tfp,
632 struct tf_free_tbl_scope_parms *parms);
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,
649 * @page tcam TCAM Access
651 * @ref tf_alloc_tcam_entry
653 * @ref tf_set_tcam_entry
655 * @ref tf_get_tcam_entry
657 * @ref tf_free_tcam_entry
660 /** tf_alloc_tcam_entry parameter definition
662 struct tf_alloc_tcam_entry_parms {
664 * [in] receive or transmit direction
668 * [in] TCAM table type
670 enum tf_tcam_tbl_type tcam_tbl_type;
672 * [in] Enable search for matching entry
674 uint8_t search_enable;
676 * [in] Key data to match on (if search)
680 * [in] key size in bits (if search)
682 uint16_t key_sz_in_bits;
684 * [in] Mask data to match on (if search)
688 * [in] Priority of entry requested (definition TBD)
692 * [out] If search, set if matching entry found
696 * [out] Current refcnt after allocation
700 * [out] Idx allocated
706 /** allocate TCAM entry
708 * Allocate a TCAM entry - one of these types:
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.
726 * Also returns success or failure code.
728 int tf_alloc_tcam_entry(struct tf *tfp,
729 struct tf_alloc_tcam_entry_parms *parms);
731 /** tf_set_tcam_entry parameter definition
733 struct tf_set_tcam_entry_parms {
735 * [in] receive or transmit direction
739 * [in] TCAM table type
741 enum tf_tcam_tbl_type tcam_tbl_type;
743 * [in] base index of the entry to program
747 * [in] struct containing key
751 * [in] struct containing mask fields
755 * [in] key size in bits (if search)
757 uint16_t key_sz_in_bits;
759 * [in] struct containing result
763 * [in] struct containing result size in bits
765 uint16_t result_sz_in_bits;
770 * Program a TCAM table entry for a TruFlow session.
772 * If the entry has not been allocated, an error will be returned.
774 * Returns success or failure code.
776 int tf_set_tcam_entry(struct tf *tfp,
777 struct tf_set_tcam_entry_parms *parms);
779 /** tf_get_tcam_entry parameter definition
781 struct tf_get_tcam_entry_parms {
783 * [in] receive or transmit direction
787 * [in] TCAM table type
789 enum tf_tcam_tbl_type tcam_tbl_type;
791 * [in] index of the entry to get
795 * [out] struct containing key
799 * [out] struct containing mask fields
803 * [out] key size in bits
805 uint16_t key_sz_in_bits;
807 * [out] struct containing result
811 * [out] struct containing result size in bits
813 uint16_t result_sz_in_bits;
818 * Program a TCAM table entry for a TruFlow session.
820 * If the entry has not been allocated, an error will be returned.
822 * Returns success or failure code.
824 int tf_get_tcam_entry(struct tf *tfp,
825 struct tf_get_tcam_entry_parms *parms);
827 /** tf_free_tcam_entry parameter definition
829 struct tf_free_tcam_entry_parms {
831 * [in] receive or transmit direction
835 * [in] TCAM table type
837 enum tf_tcam_tbl_type tcam_tbl_type;
843 * [out] reference count after free
852 * Firmware checks to ensure the TCAM entries are owned by the TruFlow
853 * session. TCAM entry will be invalidated. All-ones mask.
856 * WCTCAM profile id of 0 must be used to invalidate an entry.
858 * Returns success or failure code.
860 int tf_free_tcam_entry(struct tf *tfp,
861 struct tf_free_tcam_entry_parms *parms);
864 * @page table Table Access
866 * @ref tf_alloc_tbl_entry
868 * @ref tf_free_tbl_entry
870 * @ref tf_set_tbl_entry
872 * @ref tf_get_tbl_entry
876 * Enumeration of TruFlow table types. A table type is used to identify a
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.
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,
918 /** Meter Profiles */
919 TF_TBL_TYPE_METER_PROF,
920 /** Meter Instance */
921 TF_TBL_TYPE_METER_INST,
923 TF_TBL_TYPE_MIRROR_CONFIG,
926 /** Brd4 Epoch 0 table */
928 /** Brd4 Epoch 1 table */
931 TF_TBL_TYPE_METADATA,
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 */
940 /** Brd4 only VNIC/SVIF Table */
941 TF_TBL_TYPE_VNIC_SVIF,
945 /** External table type - initially 1 poolsize entries.
946 * All External table types are associated with a table
947 * scope. Internal types are not.
953 /** tf_alloc_tbl_entry parameter definition
955 struct tf_alloc_tbl_entry_parms {
957 * [in] Receive or transmit direction
961 * [in] Type of the allocation
963 enum tf_tbl_type type;
965 * [in] Table scope identifier (ignored unless TF_TBL_TYPE_EXT)
967 uint32_t tbl_scope_id;
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.
973 uint8_t search_enable;
975 * [in] Result data to search for (if search_enable)
979 * [in] Result data size in bytes (if search_enable)
981 uint16_t result_sz_in_bytes;
983 * [out] If search_enable, set if matching entry found
987 * [out] Current ref count after allocation (if search_enable)
991 * [out] Idx of allocated entry or found entry (if search_enable)
996 /** allocate index table entries
1000 * Allocate an on chip index table entry or search for a matching
1001 * entry of the indicated type for this TruFlow session.
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).
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.
1013 * These are used to allocate inlined action record memory.
1015 * Allocates an external index table action record.
1018 * Implementation of the internals of this function will be a stack with push
1021 * Returns success or failure code.
1023 int tf_alloc_tbl_entry(struct tf *tfp,
1024 struct tf_alloc_tbl_entry_parms *parms);
1026 /** tf_free_tbl_entry parameter definition
1028 struct tf_free_tbl_entry_parms {
1030 * [in] Receive or transmit direction
1034 * [in] Type of the allocation type
1036 enum tf_tbl_type type;
1038 * [in] Table scope identifier (ignored unless TF_TBL_TYPE_EXT)
1040 uint32_t tbl_scope_id;
1042 * [in] Index to free
1046 * [out] Reference count after free, only valid if session has been
1047 * created with shadow_copy.
1052 /** free index table entry
1054 * Used to free a previously allocated table entry.
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.
1062 * If the session does not have a shadow DB the element is free'ed and
1063 * given back to the session pool.
1067 * Free's an external index table action record.
1070 * Implementation of the internals of this function will be a stack with push
1073 * Returns success or failure code.
1075 int tf_free_tbl_entry(struct tf *tfp,
1076 struct tf_free_tbl_entry_parms *parms);
1078 /** tf_set_tbl_entry parameter definition
1080 struct tf_set_tbl_entry_parms {
1082 * [in] Table scope identifier
1084 uint32_t tbl_scope_id;
1086 * [in] Receive or transmit direction
1090 * [in] Type of object to set
1092 enum tf_tbl_type type;
1100 uint16_t data_sz_in_bytes;
1102 * [in] Entry index to write to
1107 /** set index table entry
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)
1113 * Returns success or failure code.
1115 int tf_set_tbl_entry(struct tf *tfp,
1116 struct tf_set_tbl_entry_parms *parms);
1118 /** tf_get_tbl_entry parameter definition
1120 struct tf_get_tbl_entry_parms {
1122 * [in] Receive or transmit direction
1126 * [in] Type of object to get
1128 enum tf_tbl_type type;
1136 uint16_t data_sz_in_bytes;
1138 * [in] Entry index to read
1143 /** get index table entry
1145 * Used to retrieve a previous set index table entry.
1147 * Reads and compares with the shadow table copy (if enabled) (only
1148 * for internal objects).
1150 * Returns success or failure code. Failure will be returned if the
1151 * provided data buffer is too small for the data type requested.
1153 int tf_get_tbl_entry(struct tf *tfp,
1154 struct tf_get_tbl_entry_parms *parms);
1157 * @page exact_match Exact Match Table
1159 * @ref tf_insert_em_entry
1161 * @ref tf_delete_em_entry
1163 * @ref tf_search_em_entry
1166 /** tf_insert_em_entry parameter definition
1168 struct tf_insert_em_entry_parms {
1170 * [in] receive or transmit direction
1174 * [in] internal or external
1178 * [in] ID of table scope to use (external only)
1180 uint32_t tbl_scope_id;
1182 * [in] ID of table interface to use (Brd4 only)
1186 * [in] ptr to structure containing key fields
1190 * [in] key bit length
1192 uint16_t key_sz_in_bits;
1194 * [in] ptr to structure containing result field
1198 * [out] result size in bits
1200 uint16_t em_record_sz_in_bits;
1202 * [in] duplicate check flag
1206 * [out] Flow handle value for the inserted entry. This is encoded
1207 * as the entries[4]:bucket[2]:hashId[1]:hash[14]
1209 uint64_t flow_handle;
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.
1218 * tf_delete_em_entry parameter definition
1220 struct tf_delete_em_entry_parms {
1222 * [in] receive or transmit direction
1226 * [in] internal or external
1230 * [in] ID of table scope to use (external only)
1232 uint32_t tbl_scope_id;
1234 * [in] ID of table interface to use (Brd4 only)
1238 * [in] epoch group IDs of entry to delete
1239 * 2 element array with 2 ids. (Brd4 only)
1243 * [in] structure containing flow delete handle information
1245 uint64_t flow_handle;
1248 * tf_search_em_entry parameter definition
1250 struct tf_search_em_entry_parms {
1252 * [in] receive or transmit direction
1256 * [in] internal or external
1260 * [in] ID of table scope to use (external only)
1262 uint32_t tbl_scope_id;
1264 * [in] ID of table interface to use (Brd4 only)
1268 * [in] ptr to structure containing key fields
1272 * [in] key bit length
1274 uint16_t key_sz_in_bits;
1276 * [in/out] ptr to structure containing EM record fields
1280 * [out] result size in bits
1282 uint16_t em_record_sz_in_bits;
1284 * [in] epoch group IDs of entry to lookup
1285 * 2 element array with 2 ids. (Brd4 only)
1289 * [in] ptr to structure containing flow delete handle
1291 uint64_t flow_handle;
1294 /** insert em hash entry in internal table memory
1298 * This API inserts an exact match entry into internal EM table memory
1299 * of the specified direction.
1301 * Note: The EM record is managed within the TruFlow core and not the
1304 * Shadow copy of internal record table an association with hash and 1,2, or 4
1305 * associated buckets
1308 * This API inserts an exact match entry into DRAM EM table memory of the
1309 * specified direction and table scope.
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).
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.
1320 * Flow handle is defined in this document:
1322 * https://docs.google.com
1323 * /document/d/1NESu7RpTN3jwxbokaPfYORQyChYRmJgs40wMIRe8_-Q/edit
1325 * Returns success or busy code.
1328 int tf_insert_em_entry(struct tf *tfp,
1329 struct tf_insert_em_entry_parms *parms);
1331 /** delete em hash entry table memory
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.
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.
1346 * The TruFlow library may release a dynamic bucket when an entry is deleted.
1349 * Returns success or not found code
1353 int tf_delete_em_entry(struct tf *tfp,
1354 struct tf_delete_em_entry_parms *parms);
1356 /** search em hash entry table memory
1360 * This API looks up an EM entry in table memory with the specified EM
1361 * key or flow (flow takes precedence) and direction.
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.
1367 * If flow_handle is set, search shadow copy.
1369 * Otherwise, query the fw with key to get result.
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.
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.
1380 * Returns success or not found code
1383 int tf_search_em_entry(struct tf *tfp,
1384 struct tf_search_em_entry_parms *parms);
1385 #endif /* _TF_CORE_H_ */