1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2019-2020 Broadcom
13 #include "hcapi/hcapi_cfa.h"
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 * EEM record AR helper
49 * Helper to handle the Action Record Pointer in the EEM Record Entry.
51 * Convert absolute offset to action record pointer in EEM record entry
52 * Convert action record pointer in EEM record entry to absolute offset
54 #define TF_ACT_REC_OFFSET_2_PTR(offset) ((offset) >> 4)
55 #define TF_ACT_REC_PTR_2_OFFSET(offset) ((offset) << 4)
61 #define TF_BITS_2_BYTES(num_bits) (((num_bits) + 7) / 8)
63 /********** BEGIN API FUNCTION PROTOTYPES/PARAMETERS **********/
66 * @page general General
68 * @ref tf_open_session
70 * @ref tf_attach_session
72 * @ref tf_close_session
76 * Session Version defines
78 * The version controls the format of the tf_session and
79 * tf_session_info structure. This is to assure upgrade between
80 * versions can be supported.
82 #define TF_SESSION_VER_MAJOR 1 /**< Major Version */
83 #define TF_SESSION_VER_MINOR 0 /**< Minor Version */
84 #define TF_SESSION_VER_UPDATE 0 /**< Update Version */
89 * Name of the TruFlow control channel interface. Expects
90 * format to be RTE Name specific, i.e. rte_eth_dev_get_name_by_port()
92 #define TF_SESSION_NAME_MAX 64
94 #define TF_FW_SESSION_ID_INVALID 0xFF /**< Invalid FW Session ID define */
99 * Unique session identifier which includes PCIe bus info to
100 * distinguish the PF and session info to identify the associated
101 * TruFlow session. Session ID is constructed from the passed in
102 * ctrl_chan_name in tf_open_session() together with an allocated
103 * fw_session_id. Done by TruFlow on tf_open_session().
105 union tf_session_id {
111 uint8_t fw_session_id;
116 * Session Client Identifier
118 * Unique identifier for a client within a session. Session Client ID
119 * is constructed from the passed in session and a firmware allocated
120 * fw_session_client_id. Done by TruFlow on tf_open_session().
122 union tf_session_client_id {
125 uint8_t fw_session_id;
126 uint8_t fw_session_client_id;
133 * The version controls the format of the tf_session and
134 * tf_session_info structure. This is to assure upgrade between
135 * versions can be supported.
137 * Please see the TF_VER_MAJOR/MINOR and UPDATE defines.
139 struct tf_session_version {
146 * Session supported device types
148 enum tf_device_type {
149 TF_DEVICE_TYPE_WH = 0, /**< Whitney+ */
150 TF_DEVICE_TYPE_SR, /**< Stingray */
151 TF_DEVICE_TYPE_THOR, /**< Thor */
152 TF_DEVICE_TYPE_SR2, /**< Stingray2 */
153 TF_DEVICE_TYPE_MAX /**< Maximum */
157 * Identifier resource types
159 enum tf_identifier_type {
161 * The L2 Context is returned from the L2 Ctxt TCAM lookup
162 * and can be used in WC TCAM or EM keys to virtualize further
165 TF_IDENT_TYPE_L2_CTXT_HIGH,
167 * The L2 Context is returned from the L2 Ctxt TCAM lookup
168 * and can be used in WC TCAM or EM keys to virtualize further
171 TF_IDENT_TYPE_L2_CTXT_LOW,
173 * The WC profile func is returned from the L2 Ctxt TCAM lookup
174 * to enable virtualization of the profile TCAM.
176 TF_IDENT_TYPE_PROF_FUNC,
178 * The WC profile ID is included in the WC lookup key
179 * to enable virtualization of the WC TCAM hardware.
181 TF_IDENT_TYPE_WC_PROF,
183 * The EM profile ID is included in the EM lookup key
184 * to enable virtualization of the EM hardware. (not required for SR2
185 * as it has table scope)
187 TF_IDENT_TYPE_EM_PROF,
189 * The L2 func is included in the ILT result and from recycling to
190 * enable virtualization of further lookups.
192 TF_IDENT_TYPE_L2_FUNC,
197 * Enumeration of TruFlow table types. A table type is used to identify a
200 * NOTE: The table type TF_TBL_TYPE_EXT is unique in that it is
201 * the only table type that is connected with a table scope.
206 /** Wh+/SR Action Record */
207 TF_TBL_TYPE_FULL_ACT_RECORD,
208 /** Wh+/SR/Th Multicast Groups */
209 TF_TBL_TYPE_MCAST_GROUPS,
210 /** Wh+/SR Action Encap 8 Bytes */
211 TF_TBL_TYPE_ACT_ENCAP_8B,
212 /** Wh+/SR Action Encap 16 Bytes */
213 TF_TBL_TYPE_ACT_ENCAP_16B,
214 /** Action Encap 32 Bytes */
215 TF_TBL_TYPE_ACT_ENCAP_32B,
216 /** Wh+/SR Action Encap 64 Bytes */
217 TF_TBL_TYPE_ACT_ENCAP_64B,
218 /** Action Source Properties SMAC */
219 TF_TBL_TYPE_ACT_SP_SMAC,
220 /** Wh+/SR Action Source Properties SMAC IPv4 */
221 TF_TBL_TYPE_ACT_SP_SMAC_IPV4,
222 /** Action Source Properties SMAC IPv6 */
223 TF_TBL_TYPE_ACT_SP_SMAC_IPV6,
224 /** Wh+/SR Action Statistics 64 Bits */
225 TF_TBL_TYPE_ACT_STATS_64,
226 /** Wh+/SR Action Modify L4 Src Port */
227 TF_TBL_TYPE_ACT_MODIFY_SPORT,
228 /** Wh+/SR Action Modify L4 Dest Port */
229 TF_TBL_TYPE_ACT_MODIFY_DPORT,
230 /** Wh+/SR Action Modify IPv4 Source */
231 TF_TBL_TYPE_ACT_MODIFY_IPV4_SRC,
232 /** Wh+/SR Action _Modify L4 Dest Port */
233 TF_TBL_TYPE_ACT_MODIFY_IPV4_DEST,
234 /** Meter Profiles */
235 TF_TBL_TYPE_METER_PROF,
236 /** Meter Instance */
237 TF_TBL_TYPE_METER_INST,
239 TF_TBL_TYPE_MIRROR_CONFIG,
242 /** SR2 Epoch 0 table */
244 /** SR2 Epoch 1 table */
247 TF_TBL_TYPE_METADATA,
249 TF_TBL_TYPE_CT_STATE,
250 /** SR2 Range Profile */
251 TF_TBL_TYPE_RANGE_PROF,
252 /** SR2 Range Entry */
253 TF_TBL_TYPE_RANGE_ENTRY,
256 /** SR2 VNIC/SVIF Table */
257 TF_TBL_TYPE_VNIC_SVIF,
258 /** Th/SR2 EM Flexible Key builder */
260 /** Th/SR2 WC Flexible Key builder */
266 * External table type - initially 1 poolsize entries.
267 * All External table types are associated with a table
268 * scope. Internal types are not.
277 enum tf_tcam_tbl_type {
278 /** L2 Context TCAM */
279 TF_TCAM_TBL_TYPE_L2_CTXT_TCAM_HIGH,
280 /** L2 Context TCAM */
281 TF_TCAM_TBL_TYPE_L2_CTXT_TCAM_LOW,
283 TF_TCAM_TBL_TYPE_PROF_TCAM,
285 TF_TCAM_TBL_TYPE_WC_TCAM,
286 /** Source Properties TCAM */
287 TF_TCAM_TBL_TYPE_SP_TCAM,
288 /** Connection Tracking Rule TCAM */
289 TF_TCAM_TBL_TYPE_CT_RULE_TCAM,
290 /** Virtual Edge Bridge TCAM */
291 TF_TCAM_TBL_TYPE_VEB_TCAM,
297 * These defines are provisioned during
300 enum tf_em_tbl_type {
301 /** The number of internal EM records for the session */
302 TF_EM_TBL_TYPE_EM_RECORD,
303 /** The number of table scopes reequested */
304 TF_EM_TBL_TYPE_TBL_SCOPE,
309 * TruFlow Session Information
311 * Structure defining a TruFlow Session, also known as a Management
312 * session. This structure is initialized at time of
313 * tf_open_session(). It is passed to all of the TruFlow APIs as way
314 * to prescribe and isolate resources between different TruFlow ULP
317 * Ownership of the elements is split between ULP and TruFlow. Please
318 * see the individual elements.
320 struct tf_session_info {
322 * TrueFlow Version. Used to control the structure layout when
323 * sharing sessions. No guarantee that a secondary process
324 * would come from the same version of an executable.
325 * TruFlow initializes this variable on tf_open_session().
330 struct tf_session_version ver;
332 * will be STAILQ_ENTRY(tf_session_info) next
339 * Session ID is a unique identifier for the session. TruFlow
340 * initializes this variable during tf_open_session()
344 * Access: Truflow & ULP
346 union tf_session_id session_id;
348 * Protects access to core_data. Lock is initialized and owned
349 * by ULP. TruFlow can access the core_data without checking
357 * The core_data holds the TruFlow tf_session data
358 * structure. This memory is allocated and owned by TruFlow on
361 * TruFlow uses this memory for session management control
362 * until the session is closed by ULP. Access control is done
363 * by the spin_lock which ULP controls ahead of TruFlow API
366 * Please see tf_open_session_parms for specification details
374 * The core_data_sz_bytes specifies the size of core_data in
377 * The size is set by TruFlow on tf_open_session().
379 * Please see tf_open_session_parms for specification details
385 uint32_t core_data_sz_bytes;
391 * Contains a pointer to the session info. Allocated by ULP and passed
392 * to TruFlow using tf_open_session(). TruFlow will populate the
393 * session info at that time. A TruFlow Session can be used by more
394 * than one PF/VF by using the tf_open_session().
396 * It is expected that ULP allocates this memory as shared memory.
398 * NOTE: This struct must be within the BNXT PMD struct bnxt
399 * (bp). This allows use of container_of() to get access to the PMD.
402 struct tf_session_info *session;
406 * Identifier resource definition
408 struct tf_identifier_resources {
410 * Array of TF Identifiers where each entry is expected to be
411 * set to the requested resource number of that specific type.
412 * The index used is tf_identifier_type.
414 uint16_t cnt[TF_IDENT_TYPE_MAX];
418 * Table type resource definition
420 struct tf_tbl_resources {
422 * Array of TF Table types where each entry is expected to be
423 * set to the requeste resource number of that specific
424 * type. The index used is tf_tbl_type.
426 uint16_t cnt[TF_TBL_TYPE_MAX];
430 * TCAM type resource definition
432 struct tf_tcam_resources {
434 * Array of TF TCAM types where each entry is expected to be
435 * set to the requested resource number of that specific
436 * type. The index used is tf_tcam_tbl_type.
438 uint16_t cnt[TF_TCAM_TBL_TYPE_MAX];
442 * EM type resource definition
444 struct tf_em_resources {
446 * Array of TF EM table types where each entry is expected to
447 * be set to the requested resource number of that specific
448 * type. The index used is tf_em_tbl_type.
450 uint16_t cnt[TF_EM_TBL_TYPE_MAX];
454 * tf_session_resources parameter definition.
456 struct tf_session_resources {
458 * [in] Requested Identifier Resources
460 * Number of identifier resources requested for the
463 struct tf_identifier_resources ident_cnt[TF_DIR_MAX];
465 * [in] Requested Index Table resource counts
467 * The number of index table resources requested for the
470 struct tf_tbl_resources tbl_cnt[TF_DIR_MAX];
472 * [in] Requested TCAM Table resource counts
474 * The number of TCAM table resources requested for the
478 struct tf_tcam_resources tcam_cnt[TF_DIR_MAX];
480 * [in] Requested EM resource counts
482 * The number of internal EM table resources requested for the
485 struct tf_em_resources em_cnt[TF_DIR_MAX];
489 * tf_open_session parameters definition.
491 struct tf_open_session_parms {
493 * [in] ctrl_chan_name
495 * String containing name of control channel interface to be
496 * used for this session to communicate with firmware.
498 * The ctrl_chan_name can be looked up by using
499 * rte_eth_dev_get_name_by_port() within the ULP.
501 * ctrl_chan_name will be used as part of a name for any
502 * shared memory allocation.
504 char ctrl_chan_name[TF_SESSION_NAME_MAX];
508 * Boolean controlling the use and availability of shadow
509 * copy. Shadow copy will allow the TruFlow to keep track of
510 * resource content on the firmware side without having to
511 * query firmware. Additional private session core_data will
512 * be allocated if this boolean is set to 'true', default
515 * Size of memory depends on the NVM Resource settings for the
520 * [in/out] session_id
522 * Session_id is unique per session.
524 * Session_id is composed of domain, bus, device and
525 * fw_session_id. The construction is done by parsing the
526 * ctrl_chan_name together with allocation of a fw_session_id.
528 * The session_id allows a session to be shared between devices.
530 union tf_session_id session_id;
532 * [in/out] session_client_id
534 * Session_client_id is unique per client.
536 * Session_client_id is composed of session_id and the
537 * fw_session_client_id fw_session_id. The construction is
538 * done by parsing the ctrl_chan_name together with allocation
539 * of a fw_session_client_id during tf_open_session().
541 * A reference count will be incremented in the session on
542 * which a client is created.
544 * A session can first be closed if there is one Session
545 * Client left. Session Clients should closed using
546 * tf_close_session().
548 union tf_session_client_id session_client_id;
552 * Device type for the session.
554 enum tf_device_type device_type;
558 * Resource allocation for the session.
560 struct tf_session_resources resources;
564 * Opens a new TruFlow Session or session client.
566 * What gets created depends on the passed in tfp content. If the tfp
567 * does not have prior session data a new session with associated
568 * session client. If tfp has a session already a session client will
569 * be created. In both cases the session client is created using the
570 * provided ctrl_chan_name.
572 * In case of session creation TruFlow will allocate session specific
573 * memory, shared memory, to hold its session data. This data is
574 * private to TruFlow.
576 * No other TruFlow APIs will succeed unless this API is first called
579 * tf_open_session() returns a session id and session client id that
580 * is used on all other TF APIs.
582 * A Session or session client can be closed using tf_close_session().
585 * Pointer to TF handle
588 * Pointer to open parameters
591 * - (0) if successful.
592 * - (-EINVAL) on failure.
594 int tf_open_session(struct tf *tfp,
595 struct tf_open_session_parms *parms);
600 * tf_attach_session parameters definition.
602 struct tf_attach_session_parms {
604 * [in] ctrl_chan_name
606 * String containing name of control channel interface to be
607 * used for this session to communicate with firmware.
609 * The ctrl_chan_name can be looked up by using
610 * rte_eth_dev_get_name_by_port() within the ULP.
612 * ctrl_chan_name will be used as part of a name for any
613 * shared memory allocation.
615 char ctrl_chan_name[TF_SESSION_NAME_MAX];
618 * [in] attach_chan_name
620 * String containing name of attach channel interface to be
621 * used for this session.
623 * The attach_chan_name must be given to a 2nd process after
624 * the primary process has been created. This is the
625 * ctrl_chan_name of the primary process and is used to find
626 * the shared memory for the session that the attach is going
629 char attach_chan_name[TF_SESSION_NAME_MAX];
634 * Session_id is unique per session. For Attach the session_id
635 * should be the session_id that was returned on the first
638 * Session_id is composed of domain, bus, device and
639 * fw_session_id. The construction is done by parsing the
640 * ctrl_chan_name together with allocation of a fw_session_id
641 * during tf_open_session().
643 * A reference count will be incremented on attach. A session
644 * is first fully closed when reference count is zero by
645 * calling tf_close_session().
647 union tf_session_id session_id;
653 * Allows a 2nd application instance to attach to an existing
654 * session. Used when a session is to be shared between two processes.
656 * Attach will increment a ref count as to manage the shared session data.
659 * Pointer to TF handle
662 * Pointer to attach parameters
665 * - (0) if successful.
666 * - (-EINVAL) on failure.
668 int tf_attach_session(struct tf *tfp,
669 struct tf_attach_session_parms *parms);
672 * Closes an existing session client or the session it self. The
673 * session client is default closed and if the session reference count
674 * is 0 then the session is closed as well.
676 * On session close all hardware and firmware state associated with
677 * the TruFlow application is cleaned up.
679 * The session client is extracted from the tfp. Thus tf_close_session()
680 * cannot close a session client on behalf of another function.
682 * Returns success or failure code.
684 int tf_close_session(struct tf *tfp);
687 * @page ident Identity Management
689 * @ref tf_alloc_identifier
691 * @ref tf_free_identifier
694 * tf_alloc_identifier parameter definition
696 struct tf_alloc_identifier_parms {
698 * [in] receive or transmit direction
702 * [in] Identifier type
704 enum tf_identifier_type ident_type;
706 * [out] Allocated identifier
712 * tf_free_identifier parameter definition
714 struct tf_free_identifier_parms {
716 * [in] receive or transmit direction
720 * [in] Identifier type
722 enum tf_identifier_type ident_type;
729 * [out] Current refcnt after free
735 * tf_search_identifier parameter definition (experimental)
737 struct tf_search_identifier_parms {
739 * [in] receive or transmit direction
743 * [in] Identifier type
745 enum tf_identifier_type ident_type;
747 * [in] Identifier data to search for
751 * [out] Set if matching identifier found
755 * [out] Current ref count after allocation
761 * allocate identifier resource
763 * TruFlow core will allocate a free id from the per identifier resource type
764 * pool reserved for the session during tf_open(). No firmware is involved.
766 * If shadow copy is enabled, the internal ref_cnt is set to 1 in the
767 * shadow table for a newly allocated resource.
769 * Returns success or failure code.
771 int tf_alloc_identifier(struct tf *tfp,
772 struct tf_alloc_identifier_parms *parms);
775 * free identifier resource
777 * TruFlow core will return an id back to the per identifier resource type pool
778 * reserved for the session. No firmware is involved. During tf_close, the
779 * complete pool is returned to the firmware.
781 * additional operation (experimental)
782 * Decrement reference count. Only release resource once refcnt goes to 0 if
783 * shadow copy is enabled.
785 * Returns success or failure code.
787 int tf_free_identifier(struct tf *tfp,
788 struct tf_free_identifier_parms *parms);
791 * Search identifier resource (experimental)
793 * If the shadow copy is enabled search_id is used to search for a matching
794 * entry in the shadow table. The shadow table consists of an array of
795 * reference counts indexed by identifier. If a matching entry is found hit is
796 * set to TRUE, refcnt is increased by 1 and returned. Otherwise, hit is
797 * set to false and refcnt is set to 0.
799 * TODO: we may need a per table internal shadow copy enable flag to stage
800 * the shadow table implementation. We do not need the shadow table for other
801 * tables at this time so we may only want to enable the identifier shadow.
803 * TODO: remove this pseudocode below added to show that if search fails
804 * we shouldn't allocate a new entry but return.
806 * identifier alloc (search_en=1)
807 * if (ident is allocated and ref_cnt >=1)
808 * return ident - hit is set, incr refcnt
813 int tf_search_identifier(struct tf *tfp,
814 struct tf_search_identifier_parms *parms);
817 * @page dram_table DRAM Table Scope Interface
819 * @ref tf_alloc_tbl_scope
821 * @ref tf_free_tbl_scope
823 * If we allocate the EEM memory from the core, we need to store it in
824 * the shared session data structure to make sure it can be freed later.
825 * (for example if the PF goes away)
827 * Current thought is that memory is allocated within core.
832 * tf_alloc_tbl_scope_parms definition
834 struct tf_alloc_tbl_scope_parms {
836 * [in] All Maximum key size required.
838 uint16_t rx_max_key_sz_in_bits;
840 * [in] Maximum Action size required (includes inlined items)
842 uint16_t rx_max_action_entry_sz_in_bits;
844 * [in] Memory size in Megabytes
845 * Total memory size allocated by user to be divided
846 * up for actions, hash, counters. Only inline external actions.
847 * Use this variable or the number of flows, do not set both.
849 uint32_t rx_mem_size_in_mb;
851 * [in] Number of flows * 1000. If set, rx_mem_size_in_mb must equal 0.
853 uint32_t rx_num_flows_in_k;
855 * [in] SR2 only receive table access interface id
857 uint32_t rx_tbl_if_id;
859 * [in] All Maximum key size required.
861 uint16_t tx_max_key_sz_in_bits;
863 * [in] Maximum Action size required (includes inlined items)
865 uint16_t tx_max_action_entry_sz_in_bits;
867 * [in] Memory size in Megabytes
868 * Total memory size allocated by user to be divided
869 * up for actions, hash, counters. Only inline external actions.
871 uint32_t tx_mem_size_in_mb;
873 * [in] Number of flows * 1000
875 uint32_t tx_num_flows_in_k;
877 * [in] SR2 only receive table access interface id
879 uint32_t tx_tbl_if_id;
881 * [in] Flush pending HW cached flows every 1/10th of value
882 * set in seconds, both idle and active flows are flushed
883 * from the HW cache. If set to 0, this feature will be disabled.
885 uint8_t hw_flow_cache_flush_timer;
887 * [out] table scope identifier
889 uint32_t tbl_scope_id;
892 struct tf_free_tbl_scope_parms {
894 * [in] table scope identifier
896 uint32_t tbl_scope_id;
900 * allocate a table scope
902 * On SR2 Firmware will allocate a scope ID. On other devices, the scope
903 * is a software construct to identify an EEM table. This function will
904 * divide the hash memory/buckets and records according to the device
905 * device constraints based upon calculations using either the number of flows
906 * requested or the size of memory indicated. Other parameters passed in
907 * determine the configuration (maximum key size, maximum external action record
910 * This API will allocate the table region in
911 * DRAM, program the PTU page table entries, and program the number of static
912 * buckets (if SR2) in the RX and TX CFAs. Buckets are assumed to start at
913 * 0 in the EM memory for the scope. Upon successful completion of this API,
914 * hash tables are fully initialized and ready for entries to be inserted.
916 * A single API is used to allocate a common table scope identifier in both
917 * receive and transmit CFA. The scope identifier is common due to nature of
918 * connection tracking sending notifications between RX and TX direction.
920 * The receive and transmit table access identifiers specify which rings will
921 * be used to initialize table DRAM. The application must ensure mutual
922 * exclusivity of ring usage for table scope allocation and any table update
925 * The hash table buckets, EM keys, and EM lookup results are stored in the
926 * memory allocated based on the rx_em_hash_mb/tx_em_hash_mb parameters. The
927 * hash table buckets are stored at the beginning of that memory.
929 * NOTE: No EM internal setup is done here. On chip EM records are managed
930 * internally by TruFlow core.
932 * Returns success or failure code.
934 int tf_alloc_tbl_scope(struct tf *tfp,
935 struct tf_alloc_tbl_scope_parms *parms);
941 * Firmware checks that the table scope ID is owned by the TruFlow
942 * session, verifies that no references to this table scope remains
943 * (SR2 ILT) or Profile TCAM entries for either CFA (RX/TX) direction,
944 * then frees the table scope ID.
946 * Returns success or failure code.
948 int tf_free_tbl_scope(struct tf *tfp,
949 struct tf_free_tbl_scope_parms *parms);
952 * @page tcam TCAM Access
954 * @ref tf_alloc_tcam_entry
956 * @ref tf_set_tcam_entry
958 * @ref tf_get_tcam_entry
960 * @ref tf_free_tcam_entry
965 * tf_alloc_tcam_entry parameter definition
967 struct tf_alloc_tcam_entry_parms {
969 * [in] receive or transmit direction
973 * [in] TCAM table type
975 enum tf_tcam_tbl_type tcam_tbl_type;
977 * [in] Enable search for matching entry
979 uint8_t search_enable;
981 * [in] Key data to match on (if search)
985 * [in] key size in bits (if search)
987 uint16_t key_sz_in_bits;
989 * [in] Mask data to match on (if search)
993 * [in] Priority of entry requested (definition TBD)
997 * [out] If search, set if matching entry found
1001 * [out] Current refcnt after allocation
1005 * [out] Idx allocated
1012 * allocate TCAM entry
1014 * Allocate a TCAM entry - one of these types:
1021 * This function allocates a TCAM table record. This function
1022 * will attempt to allocate a TCAM table entry from the session
1023 * owned TCAM entries or search a shadow copy of the TCAM table for a
1024 * matching entry if search is enabled. Key, mask and result must match for
1025 * hit to be set. Only TruFlow core data is accessed.
1026 * A hash table to entry mapping is maintained for search purposes. If
1027 * search is not enabled, the first available free entry is returned based
1028 * on priority and alloc_cnt is set to 1. If search is enabled and a matching
1029 * entry to entry_data is found, hit is set to TRUE and alloc_cnt is set to 1.
1030 * RefCnt is also returned.
1032 * Also returns success or failure code.
1034 int tf_alloc_tcam_entry(struct tf *tfp,
1035 struct tf_alloc_tcam_entry_parms *parms);
1038 * tf_set_tcam_entry parameter definition
1040 struct tf_set_tcam_entry_parms {
1042 * [in] receive or transmit direction
1046 * [in] TCAM table type
1048 enum tf_tcam_tbl_type tcam_tbl_type;
1050 * [in] base index of the entry to program
1054 * [in] struct containing key
1058 * [in] struct containing mask fields
1062 * [in] key size in bits (if search)
1064 uint16_t key_sz_in_bits;
1066 * [in] struct containing result
1070 * [in] struct containing result size in bits
1072 uint16_t result_sz_in_bits;
1078 * Program a TCAM table entry for a TruFlow session.
1080 * If the entry has not been allocated, an error will be returned.
1082 * Returns success or failure code.
1084 int tf_set_tcam_entry(struct tf *tfp,
1085 struct tf_set_tcam_entry_parms *parms);
1088 * tf_get_tcam_entry parameter definition
1090 struct tf_get_tcam_entry_parms {
1092 * [in] receive or transmit direction
1096 * [in] TCAM table type
1098 enum tf_tcam_tbl_type tcam_tbl_type;
1100 * [in] index of the entry to get
1104 * [out] struct containing key
1108 * [out] struct containing mask fields
1112 * [out] key size in bits
1114 uint16_t key_sz_in_bits;
1116 * [out] struct containing result
1120 * [out] struct containing result size in bits
1122 uint16_t result_sz_in_bits;
1128 * Program a TCAM table entry for a TruFlow session.
1130 * If the entry has not been allocated, an error will be returned.
1132 * Returns success or failure code.
1134 int tf_get_tcam_entry(struct tf *tfp,
1135 struct tf_get_tcam_entry_parms *parms);
1138 * tf_free_tcam_entry parameter definition
1140 struct tf_free_tcam_entry_parms {
1142 * [in] receive or transmit direction
1146 * [in] TCAM table type
1148 enum tf_tcam_tbl_type tcam_tbl_type;
1150 * [in] Index to free
1154 * [out] reference count after free
1164 * Firmware checks to ensure the TCAM entries are owned by the TruFlow
1165 * session. TCAM entry will be invalidated. All-ones mask.
1168 * WCTCAM profile id of 0 must be used to invalidate an entry.
1170 * Returns success or failure code.
1172 int tf_free_tcam_entry(struct tf *tfp,
1173 struct tf_free_tcam_entry_parms *parms);
1176 * @page table Table Access
1178 * @ref tf_alloc_tbl_entry
1180 * @ref tf_free_tbl_entry
1182 * @ref tf_set_tbl_entry
1184 * @ref tf_get_tbl_entry
1186 * @ref tf_bulk_get_tbl_entry
1190 * tf_alloc_tbl_entry parameter definition
1192 struct tf_alloc_tbl_entry_parms {
1194 * [in] Receive or transmit direction
1198 * [in] Type of the allocation
1200 enum tf_tbl_type type;
1202 * [in] Table scope identifier (ignored unless TF_TBL_TYPE_EXT)
1204 uint32_t tbl_scope_id;
1206 * [in] Enable search for matching entry. If the table type is
1207 * internal the shadow copy will be searched before
1208 * alloc. Session must be configured with shadow copy enabled.
1210 uint8_t search_enable;
1212 * [in] Result data to search for (if search_enable)
1216 * [in] Result data size in bytes (if search_enable)
1218 uint16_t result_sz_in_bytes;
1220 * [out] If search_enable, set if matching entry found
1224 * [out] Current ref count after allocation (if search_enable)
1228 * [out] Idx of allocated entry or found entry (if search_enable)
1234 * allocate index table entries
1238 * Allocate an on chip index table entry or search for a matching
1239 * entry of the indicated type for this TruFlow session.
1241 * Allocates an index table record. This function will attempt to
1242 * allocate an entry or search an index table for a matching entry if
1243 * search is enabled (only the shadow copy of the table is accessed).
1245 * If search is not enabled, the first available free entry is
1246 * returned. If search is enabled and a matching entry to entry_data
1247 * is found hit is set to TRUE and success is returned.
1251 * These are used to allocate inlined action record memory.
1253 * Allocates an external index table action record.
1256 * Implementation of the internals of this function will be a stack with push
1259 * Returns success or failure code.
1261 int tf_alloc_tbl_entry(struct tf *tfp,
1262 struct tf_alloc_tbl_entry_parms *parms);
1265 * tf_free_tbl_entry parameter definition
1267 struct tf_free_tbl_entry_parms {
1269 * [in] Receive or transmit direction
1273 * [in] Type of the allocation type
1275 enum tf_tbl_type type;
1277 * [in] Table scope identifier (ignored unless TF_TBL_TYPE_EXT)
1279 uint32_t tbl_scope_id;
1281 * [in] Index to free
1285 * [out] Reference count after free, only valid if session has been
1286 * created with shadow_copy.
1292 * free index table entry
1294 * Used to free a previously allocated table entry.
1298 * If session has shadow_copy enabled the shadow DB is searched and if
1299 * found the element ref_cnt is decremented. If ref_cnt goes to
1300 * zero then the element is returned to the session pool.
1302 * If the session does not have a shadow DB the element is free'ed and
1303 * given back to the session pool.
1307 * Free's an external index table action record.
1310 * Implementation of the internals of this function will be a stack with push
1313 * Returns success or failure code.
1315 int tf_free_tbl_entry(struct tf *tfp,
1316 struct tf_free_tbl_entry_parms *parms);
1319 * tf_set_tbl_entry parameter definition
1321 struct tf_set_tbl_entry_parms {
1323 * [in] Table scope identifier
1325 uint32_t tbl_scope_id;
1327 * [in] Receive or transmit direction
1331 * [in] Type of object to set
1333 enum tf_tbl_type type;
1341 uint16_t data_sz_in_bytes;
1343 * [in] Entry index to write to
1349 * set index table entry
1351 * Used to insert an application programmed index table entry into a
1352 * previous allocated table location. A shadow copy of the table
1353 * is maintained (if enabled) (only for internal objects)
1355 * Returns success or failure code.
1357 int tf_set_tbl_entry(struct tf *tfp,
1358 struct tf_set_tbl_entry_parms *parms);
1361 * tf_get_tbl_entry parameter definition
1363 struct tf_get_tbl_entry_parms {
1365 * [in] Receive or transmit direction
1369 * [in] Type of object to get
1371 enum tf_tbl_type type;
1379 uint16_t data_sz_in_bytes;
1381 * [in] Entry index to read
1387 * get index table entry
1389 * Used to retrieve a previous set index table entry.
1391 * Reads and compares with the shadow table copy (if enabled) (only
1392 * for internal objects).
1394 * Returns success or failure code. Failure will be returned if the
1395 * provided data buffer is too small for the data type requested.
1397 int tf_get_tbl_entry(struct tf *tfp,
1398 struct tf_get_tbl_entry_parms *parms);
1401 * tf_bulk_get_tbl_entry parameter definition
1403 struct tf_bulk_get_tbl_entry_parms {
1405 * [in] Receive or transmit direction
1409 * [in] Type of object to get
1411 enum tf_tbl_type type;
1413 * [in] Starting index to read from
1415 uint32_t starting_idx;
1417 * [in] Number of sequential entries
1419 uint16_t num_entries;
1421 * [in] Size of the single entry
1423 uint16_t entry_sz_in_bytes;
1425 * [out] Host physical address, where the data
1426 * will be copied to by the firmware.
1427 * Use tfp_calloc() API and mem_pa
1428 * variable of the tfp_calloc_parms
1429 * structure for the physical address.
1431 uint64_t physical_mem_addr;
1435 * Bulk get index table entry
1437 * Used to retrieve a set of index table entries.
1439 * Entries within the range may not have been allocated using
1440 * tf_alloc_tbl_entry() at the time of access. But the range must
1441 * be within the bounds determined from tf_open_session() for the
1442 * given table type. Currently, this is only used for collecting statistics.
1444 * Returns success or failure code. Failure will be returned if the
1445 * provided data buffer is too small for the data type requested.
1447 int tf_bulk_get_tbl_entry(struct tf *tfp,
1448 struct tf_bulk_get_tbl_entry_parms *parms);
1451 * @page exact_match Exact Match Table
1453 * @ref tf_insert_em_entry
1455 * @ref tf_delete_em_entry
1457 * @ref tf_search_em_entry
1461 * tf_insert_em_entry parameter definition
1463 struct tf_insert_em_entry_parms {
1465 * [in] receive or transmit direction
1469 * [in] internal or external
1473 * [in] ID of table scope to use (external only)
1475 uint32_t tbl_scope_id;
1477 * [in] ID of table interface to use (SR2 only)
1481 * [in] ptr to structure containing key fields
1485 * [in] key bit length
1487 uint16_t key_sz_in_bits;
1489 * [in] ptr to structure containing result field
1493 * [out] result size in bits
1495 uint16_t em_record_sz_in_bits;
1497 * [in] duplicate check flag
1501 * [out] Flow handle value for the inserted entry. This is encoded
1502 * as the entries[4]:bucket[2]:hashId[1]:hash[14]
1504 uint64_t flow_handle;
1506 * [out] Flow id is returned as null (internal)
1507 * Flow id is the GFID value for the inserted entry (external)
1508 * This is the value written to the BD and useful information for mark.
1513 * tf_delete_em_entry parameter definition
1515 struct tf_delete_em_entry_parms {
1517 * [in] receive or transmit direction
1521 * [in] internal or external
1525 * [in] ID of table scope to use (external only)
1527 uint32_t tbl_scope_id;
1529 * [in] ID of table interface to use (SR2 only)
1533 * [in] epoch group IDs of entry to delete
1534 * 2 element array with 2 ids. (SR2 only)
1538 * [out] The index of the entry
1542 * [in] structure containing flow delete handle information
1544 uint64_t flow_handle;
1547 * tf_search_em_entry parameter definition
1549 struct tf_search_em_entry_parms {
1551 * [in] receive or transmit direction
1555 * [in] internal or external
1559 * [in] ID of table scope to use (external only)
1561 uint32_t tbl_scope_id;
1563 * [in] ID of table interface to use (SR2 only)
1567 * [in] ptr to structure containing key fields
1571 * [in] key bit length
1573 uint16_t key_sz_in_bits;
1575 * [in/out] ptr to structure containing EM record fields
1579 * [out] result size in bits
1581 uint16_t em_record_sz_in_bits;
1583 * [in] epoch group IDs of entry to lookup
1584 * 2 element array with 2 ids. (SR2 only)
1588 * [in] ptr to structure containing flow delete handle
1590 uint64_t flow_handle;
1594 * insert em hash entry in internal table memory
1598 * This API inserts an exact match entry into internal EM table memory
1599 * of the specified direction.
1601 * Note: The EM record is managed within the TruFlow core and not the
1604 * Shadow copy of internal record table an association with hash and 1,2, or 4
1605 * associated buckets
1608 * This API inserts an exact match entry into DRAM EM table memory of the
1609 * specified direction and table scope.
1611 * When inserting an entry into an exact match table, the TruFlow library may
1612 * need to allocate a dynamic bucket for the entry (SR2 only).
1614 * The insertion of duplicate entries in an EM table is not permitted. If a
1615 * TruFlow application can guarantee that it will never insert duplicates, it
1616 * can disable duplicate checking by passing a zero value in the dup_check
1617 * parameter to this API. This will optimize performance. Otherwise, the
1618 * TruFlow library will enforce protection against inserting duplicate entries.
1620 * Flow handle is defined in this document:
1622 * https://docs.google.com
1623 * /document/d/1NESu7RpTN3jwxbokaPfYORQyChYRmJgs40wMIRe8_-Q/edit
1625 * Returns success or busy code.
1628 int tf_insert_em_entry(struct tf *tfp,
1629 struct tf_insert_em_entry_parms *parms);
1632 * delete em hash entry table memory
1636 * This API deletes an exact match entry from internal EM table memory of the
1637 * specified direction. If a valid flow ptr is passed in then that takes
1638 * precedence over the pointer to the complete key passed in.
1643 * This API deletes an exact match entry from EM table memory of the specified
1644 * direction and table scope. If a valid flow handle is passed in then that
1645 * takes precedence over the pointer to the complete key passed in.
1647 * The TruFlow library may release a dynamic bucket when an entry is deleted.
1650 * Returns success or not found code
1654 int tf_delete_em_entry(struct tf *tfp,
1655 struct tf_delete_em_entry_parms *parms);
1658 * search em hash entry table memory
1662 * This API looks up an EM entry in table memory with the specified EM
1663 * key or flow (flow takes precedence) and direction.
1665 * The status will be one of: success or entry not found. If the lookup
1666 * succeeds, a pointer to the matching entry and the result record associated
1667 * with the matching entry will be provided.
1669 * If flow_handle is set, search shadow copy.
1671 * Otherwise, query the fw with key to get result.
1675 * This API looks up an EM entry in table memory with the specified EM
1676 * key or flow_handle (flow takes precedence), direction and table scope.
1678 * The status will be one of: success or entry not found. If the lookup
1679 * succeeds, a pointer to the matching entry and the result record associated
1680 * with the matching entry will be provided.
1682 * Returns success or not found code
1685 int tf_search_em_entry(struct tf *tfp,
1686 struct tf_search_em_entry_parms *parms);
1689 * @page global Global Configuration
1691 * @ref tf_set_global_cfg
1693 * @ref tf_get_global_cfg
1696 * Tunnel Encapsulation Offsets
1698 enum tf_tunnel_encap_offsets {
1700 TF_TUNNEL_ENCAP_NAT,
1701 TF_TUNNEL_ENCAP_MPLS,
1702 TF_TUNNEL_ENCAP_VXLAN,
1703 TF_TUNNEL_ENCAP_GENEVE,
1704 TF_TUNNEL_ENCAP_NVGRE,
1705 TF_TUNNEL_ENCAP_GRE,
1706 TF_TUNNEL_ENCAP_FULL_GENERIC
1709 * Global Configuration Table Types
1711 enum tf_global_config_type {
1712 TF_TUNNEL_ENCAP, /**< Tunnel Encap Config(TECT) */
1713 TF_ACTION_BLOCK, /**< Action Block Config(ABCR) */
1714 TF_GLOBAL_CFG_TYPE_MAX
1718 * tf_global_cfg parameter definition
1720 struct tf_global_cfg_parms {
1722 * [in] receive or transmit direction
1726 * [in] Global config type
1728 enum tf_global_config_type type;
1730 * [in] Offset @ the type
1734 * [in/out] Value of the configuration
1735 * set - Read, Modify and Write
1736 * get - Read the full configuration
1740 * [in] struct containing size
1742 uint16_t config_sz_in_bytes;
1746 * Get global configuration
1748 * Retrieve the configuration
1750 * Returns success or failure code.
1752 int tf_get_global_cfg(struct tf *tfp,
1753 struct tf_global_cfg_parms *parms);
1756 * Update the global configuration table
1758 * Read, modify write the value.
1760 * Returns success or failure code.
1762 int tf_set_global_cfg(struct tf *tfp,
1763 struct tf_global_cfg_parms *parms);
1766 * @page if_tbl Interface Table Access
1768 * @ref tf_set_if_tbl_entry
1770 * @ref tf_get_if_tbl_entry
1772 * @ref tf_restore_if_tbl_entry
1775 * Enumeration of TruFlow interface table types.
1777 enum tf_if_tbl_type {
1778 /** Default Profile L2 Context Entry */
1779 TF_IF_TBL_TYPE_PROF_SPIF_DFLT_L2_CTXT,
1780 /** Default Profile TCAM/Lookup Action Record Pointer Table */
1781 TF_IF_TBL_TYPE_PROF_PARIF_DFLT_ACT_REC_PTR,
1782 /** Error Profile TCAM Miss Action Record Pointer Table */
1783 TF_IF_TBL_TYPE_PROF_PARIF_ERR_ACT_REC_PTR,
1784 /** Default Error Profile TCAM Miss Action Record Pointer Table */
1785 TF_IF_TBL_TYPE_LKUP_PARIF_DFLT_ACT_REC_PTR,
1786 /** SR2 Ingress lookup table */
1788 /** SR2 VNIC/SVIF Table */
1789 TF_IF_TBL_TYPE_VNIC_SVIF,
1794 * tf_set_if_tbl_entry parameter definition
1796 struct tf_set_if_tbl_entry_parms {
1798 * [in] Receive or transmit direction
1802 * [in] Type of object to set
1804 enum tf_if_tbl_type type;
1812 uint16_t data_sz_in_bytes;
1814 * [in] Interface to write
1820 * set interface table entry
1822 * Used to set an interface table. This API is used for managing tables indexed
1823 * by SVIF/SPIF/PARIF interfaces. In current implementation only the value is
1825 * Returns success or failure code.
1827 int tf_set_if_tbl_entry(struct tf *tfp,
1828 struct tf_set_if_tbl_entry_parms *parms);
1831 * tf_get_if_tbl_entry parameter definition
1833 struct tf_get_if_tbl_entry_parms {
1835 * [in] Receive or transmit direction
1839 * [in] Type of table to get
1841 enum tf_if_tbl_type type;
1849 uint16_t data_sz_in_bytes;
1851 * [in] Entry index to read
1857 * get interface table entry
1859 * Used to retrieve an interface table entry.
1861 * Reads the interface table entry value
1863 * Returns success or failure code. Failure will be returned if the
1864 * provided data buffer is too small for the data type requested.
1866 int tf_get_if_tbl_entry(struct tf *tfp,
1867 struct tf_get_if_tbl_entry_parms *parms);
1869 #endif /* _TF_CORE_H_ */