1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2019-2021 Broadcom
13 #include "hcapi/hcapi_cfa_defs.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,
232 /** Meter Profiles */
233 TF_TBL_TYPE_METER_PROF,
234 /** Meter Instance */
235 TF_TBL_TYPE_METER_INST,
237 TF_TBL_TYPE_MIRROR_CONFIG,
240 /** SR2 Epoch 0 table */
242 /** SR2 Epoch 1 table */
245 TF_TBL_TYPE_METADATA,
247 TF_TBL_TYPE_CT_STATE,
248 /** SR2 Range Profile */
249 TF_TBL_TYPE_RANGE_PROF,
250 /** SR2 Range Entry */
251 TF_TBL_TYPE_RANGE_ENTRY,
254 /** SR2 VNIC/SVIF Table */
255 TF_TBL_TYPE_VNIC_SVIF,
256 /** Th/SR2 EM Flexible Key builder */
258 /** Th/SR2 WC Flexible Key builder */
264 * External table type - initially 1 poolsize entries.
265 * All External table types are associated with a table
266 * scope. Internal types are not.
275 enum tf_tcam_tbl_type {
276 /** L2 Context TCAM */
277 TF_TCAM_TBL_TYPE_L2_CTXT_TCAM_HIGH,
278 /** L2 Context TCAM */
279 TF_TCAM_TBL_TYPE_L2_CTXT_TCAM_LOW,
281 TF_TCAM_TBL_TYPE_PROF_TCAM,
283 TF_TCAM_TBL_TYPE_WC_TCAM,
284 /** Source Properties TCAM */
285 TF_TCAM_TBL_TYPE_SP_TCAM,
286 /** Connection Tracking Rule TCAM */
287 TF_TCAM_TBL_TYPE_CT_RULE_TCAM,
288 /** Virtual Edge Bridge TCAM */
289 TF_TCAM_TBL_TYPE_VEB_TCAM,
296 enum tf_search_status {
297 /** The entry was not found, but an idx was allocated if requested. */
299 /** The entry was found, and the result/idx are valid */
301 /** The entry was not found and the table is full */
307 * These defines are provisioned during
310 enum tf_em_tbl_type {
311 /** The number of internal EM records for the session */
312 TF_EM_TBL_TYPE_EM_RECORD,
313 /** The number of table scopes reequested */
314 TF_EM_TBL_TYPE_TBL_SCOPE,
319 * TruFlow Session Information
321 * Structure defining a TruFlow Session, also known as a Management
322 * session. This structure is initialized at time of
323 * tf_open_session(). It is passed to all of the TruFlow APIs as way
324 * to prescribe and isolate resources between different TruFlow ULP
327 * Ownership of the elements is split between ULP and TruFlow. Please
328 * see the individual elements.
330 struct tf_session_info {
332 * TrueFlow Version. Used to control the structure layout when
333 * sharing sessions. No guarantee that a secondary process
334 * would come from the same version of an executable.
335 * TruFlow initializes this variable on tf_open_session().
340 struct tf_session_version ver;
342 * will be STAILQ_ENTRY(tf_session_info) next
349 * Session ID is a unique identifier for the session. TruFlow
350 * initializes this variable during tf_open_session()
354 * Access: Truflow & ULP
356 union tf_session_id session_id;
358 * Protects access to core_data. Lock is initialized and owned
359 * by ULP. TruFlow can access the core_data without checking
367 * The core_data holds the TruFlow tf_session data
368 * structure. This memory is allocated and owned by TruFlow on
371 * TruFlow uses this memory for session management control
372 * until the session is closed by ULP. Access control is done
373 * by the spin_lock which ULP controls ahead of TruFlow API
376 * Please see tf_open_session_parms for specification details
384 * The core_data_sz_bytes specifies the size of core_data in
387 * The size is set by TruFlow on tf_open_session().
389 * Please see tf_open_session_parms for specification details
395 uint32_t core_data_sz_bytes;
401 * Contains a pointer to the session info. Allocated by ULP and passed
402 * to TruFlow using tf_open_session(). TruFlow will populate the
403 * session info at that time. A TruFlow Session can be used by more
404 * than one PF/VF by using the tf_open_session().
406 * It is expected that ULP allocates this memory as shared memory.
408 * NOTE: This struct must be within the BNXT PMD struct bnxt
409 * (bp). This allows use of container_of() to get access to the PMD.
412 struct tf_session_info *session;
416 * Identifier resource definition
418 struct tf_identifier_resources {
420 * Array of TF Identifiers where each entry is expected to be
421 * set to the requested resource number of that specific type.
422 * The index used is tf_identifier_type.
424 uint16_t cnt[TF_IDENT_TYPE_MAX];
428 * Table type resource definition
430 struct tf_tbl_resources {
432 * Array of TF Table types where each entry is expected to be
433 * set to the requeste resource number of that specific
434 * type. The index used is tf_tbl_type.
436 uint16_t cnt[TF_TBL_TYPE_MAX];
440 * TCAM type resource definition
442 struct tf_tcam_resources {
444 * Array of TF TCAM types where each entry is expected to be
445 * set to the requested resource number of that specific
446 * type. The index used is tf_tcam_tbl_type.
448 uint16_t cnt[TF_TCAM_TBL_TYPE_MAX];
452 * EM type resource definition
454 struct tf_em_resources {
456 * Array of TF EM table types where each entry is expected to
457 * be set to the requested resource number of that specific
458 * type. The index used is tf_em_tbl_type.
460 uint16_t cnt[TF_EM_TBL_TYPE_MAX];
464 * tf_session_resources parameter definition.
466 struct tf_session_resources {
468 * [in] Requested Identifier Resources
470 * Number of identifier resources requested for the
473 struct tf_identifier_resources ident_cnt[TF_DIR_MAX];
475 * [in] Requested Index Table resource counts
477 * The number of index table resources requested for the
480 struct tf_tbl_resources tbl_cnt[TF_DIR_MAX];
482 * [in] Requested TCAM Table resource counts
484 * The number of TCAM table resources requested for the
488 struct tf_tcam_resources tcam_cnt[TF_DIR_MAX];
490 * [in] Requested EM resource counts
492 * The number of internal EM table resources requested for the
495 struct tf_em_resources em_cnt[TF_DIR_MAX];
499 * tf_open_session parameters definition.
501 struct tf_open_session_parms {
503 * [in] ctrl_chan_name
505 * String containing name of control channel interface to be
506 * used for this session to communicate with firmware.
508 * The ctrl_chan_name can be looked up by using
509 * rte_eth_dev_get_name_by_port() within the ULP.
511 * ctrl_chan_name will be used as part of a name for any
512 * shared memory allocation.
514 char ctrl_chan_name[TF_SESSION_NAME_MAX];
518 * Boolean controlling the use and availability of shadow
519 * copy. Shadow copy will allow the TruFlow to keep track of
520 * resource content on the firmware side without having to
521 * query firmware. Additional private session core_data will
522 * be allocated if this boolean is set to 'true', default
525 * Size of memory depends on the NVM Resource settings for the
530 * [in/out] session_id
532 * Session_id is unique per session.
534 * Session_id is composed of domain, bus, device and
535 * fw_session_id. The construction is done by parsing the
536 * ctrl_chan_name together with allocation of a fw_session_id.
538 * The session_id allows a session to be shared between devices.
540 union tf_session_id session_id;
542 * [in/out] session_client_id
544 * Session_client_id is unique per client.
546 * Session_client_id is composed of session_id and the
547 * fw_session_client_id fw_session_id. The construction is
548 * done by parsing the ctrl_chan_name together with allocation
549 * of a fw_session_client_id during tf_open_session().
551 * A reference count will be incremented in the session on
552 * which a client is created.
554 * A session can first be closed if there is one Session
555 * Client left. Session Clients should closed using
556 * tf_close_session().
558 union tf_session_client_id session_client_id;
562 * Device type for the session.
564 enum tf_device_type device_type;
568 * Resource allocation for the session.
570 struct tf_session_resources resources;
574 * Opens a new TruFlow Session or session client.
576 * What gets created depends on the passed in tfp content. If the tfp
577 * does not have prior session data a new session with associated
578 * session client. If tfp has a session already a session client will
579 * be created. In both cases the session client is created using the
580 * provided ctrl_chan_name.
582 * In case of session creation TruFlow will allocate session specific
583 * memory, shared memory, to hold its session data. This data is
584 * private to TruFlow.
586 * No other TruFlow APIs will succeed unless this API is first called
589 * tf_open_session() returns a session id and session client id that
590 * is used on all other TF APIs.
592 * A Session or session client can be closed using tf_close_session().
595 * Pointer to TF handle
598 * Pointer to open parameters
601 * - (0) if successful.
602 * - (-EINVAL) on failure.
604 int tf_open_session(struct tf *tfp,
605 struct tf_open_session_parms *parms);
610 * tf_attach_session parameters definition.
612 struct tf_attach_session_parms {
614 * [in] ctrl_chan_name
616 * String containing name of control channel interface to be
617 * used for this session to communicate with firmware.
619 * The ctrl_chan_name can be looked up by using
620 * rte_eth_dev_get_name_by_port() within the ULP.
622 * ctrl_chan_name will be used as part of a name for any
623 * shared memory allocation.
625 char ctrl_chan_name[TF_SESSION_NAME_MAX];
628 * [in] attach_chan_name
630 * String containing name of attach channel interface to be
631 * used for this session.
633 * The attach_chan_name must be given to a 2nd process after
634 * the primary process has been created. This is the
635 * ctrl_chan_name of the primary process and is used to find
636 * the shared memory for the session that the attach is going
639 char attach_chan_name[TF_SESSION_NAME_MAX];
644 * Session_id is unique per session. For Attach the session_id
645 * should be the session_id that was returned on the first
648 * Session_id is composed of domain, bus, device and
649 * fw_session_id. The construction is done by parsing the
650 * ctrl_chan_name together with allocation of a fw_session_id
651 * during tf_open_session().
653 * A reference count will be incremented on attach. A session
654 * is first fully closed when reference count is zero by
655 * calling tf_close_session().
657 union tf_session_id session_id;
663 * Allows a 2nd application instance to attach to an existing
664 * session. Used when a session is to be shared between two processes.
666 * Attach will increment a ref count as to manage the shared session data.
669 * Pointer to TF handle
672 * Pointer to attach parameters
675 * - (0) if successful.
676 * - (-EINVAL) on failure.
678 int tf_attach_session(struct tf *tfp,
679 struct tf_attach_session_parms *parms);
682 * Closes an existing session client or the session it self. The
683 * session client is default closed and if the session reference count
684 * is 0 then the session is closed as well.
686 * On session close all hardware and firmware state associated with
687 * the TruFlow application is cleaned up.
689 * The session client is extracted from the tfp. Thus tf_close_session()
690 * cannot close a session client on behalf of another function.
692 * Returns success or failure code.
694 int tf_close_session(struct tf *tfp);
697 * @page ident Identity Management
699 * @ref tf_alloc_identifier
701 * @ref tf_free_identifier
704 * tf_alloc_identifier parameter definition
706 struct tf_alloc_identifier_parms {
708 * [in] receive or transmit direction
712 * [in] Identifier type
714 enum tf_identifier_type ident_type;
716 * [out] Allocated identifier
722 * tf_free_identifier parameter definition
724 struct tf_free_identifier_parms {
726 * [in] receive or transmit direction
730 * [in] Identifier type
732 enum tf_identifier_type ident_type;
739 * [out] Current refcnt after free
745 * tf_search_identifier parameter definition (experimental)
747 struct tf_search_identifier_parms {
749 * [in] receive or transmit direction
753 * [in] Identifier type
755 enum tf_identifier_type ident_type;
757 * [in] Identifier data to search for
761 * [out] Set if matching identifier found
765 * [out] Current ref count after allocation
771 * allocate identifier resource
773 * TruFlow core will allocate a free id from the per identifier resource type
774 * pool reserved for the session during tf_open(). No firmware is involved.
776 * If shadow copy is enabled, the internal ref_cnt is set to 1 in the
777 * shadow table for a newly allocated resource.
779 * Returns success or failure code.
781 int tf_alloc_identifier(struct tf *tfp,
782 struct tf_alloc_identifier_parms *parms);
785 * free identifier resource
787 * TruFlow core will return an id back to the per identifier resource type pool
788 * reserved for the session. No firmware is involved. During tf_close, the
789 * complete pool is returned to the firmware.
791 * additional operation (experimental)
792 * Decrement reference count. Only release resource once refcnt goes to 0 if
793 * shadow copy is enabled.
795 * Returns success or failure code.
797 int tf_free_identifier(struct tf *tfp,
798 struct tf_free_identifier_parms *parms);
801 * Search identifier resource (experimental)
803 * If the shadow copy is enabled search_id is used to search for a matching
804 * entry in the shadow table. The shadow table consists of an array of
805 * reference counts indexed by identifier. If a matching entry is found hit is
806 * set to TRUE, refcnt is increased by 1 and returned. Otherwise, hit is
807 * set to false and refcnt is set to 0.
809 * TODO: we may need a per table internal shadow copy enable flag to stage
810 * the shadow table implementation. We do not need the shadow table for other
811 * tables at this time so we may only want to enable the identifier shadow.
813 * TODO: remove this pseudocode below added to show that if search fails
814 * we shouldn't allocate a new entry but return.
816 * identifier alloc (search_en=1)
817 * if (ident is allocated and ref_cnt >=1)
818 * return ident - hit is set, incr refcnt
823 int tf_search_identifier(struct tf *tfp,
824 struct tf_search_identifier_parms *parms);
827 * @page dram_table DRAM Table Scope Interface
829 * @ref tf_alloc_tbl_scope
831 * @ref tf_free_tbl_scope
833 * If we allocate the EEM memory from the core, we need to store it in
834 * the shared session data structure to make sure it can be freed later.
835 * (for example if the PF goes away)
837 * Current thought is that memory is allocated within core.
842 * tf_alloc_tbl_scope_parms definition
844 struct tf_alloc_tbl_scope_parms {
846 * [in] All Maximum key size required.
848 uint16_t rx_max_key_sz_in_bits;
850 * [in] Maximum Action size required (includes inlined items)
852 uint16_t rx_max_action_entry_sz_in_bits;
854 * [in] Memory size in Megabytes
855 * Total memory size allocated by user to be divided
856 * up for actions, hash, counters. Only inline external actions.
857 * Use this variable or the number of flows, do not set both.
859 uint32_t rx_mem_size_in_mb;
861 * [in] Number of flows * 1000. If set, rx_mem_size_in_mb must equal 0.
863 uint32_t rx_num_flows_in_k;
865 * [in] SR2 only receive table access interface id
867 uint32_t rx_tbl_if_id;
869 * [in] All Maximum key size required.
871 uint16_t tx_max_key_sz_in_bits;
873 * [in] Maximum Action size required (includes inlined items)
875 uint16_t tx_max_action_entry_sz_in_bits;
877 * [in] Memory size in Megabytes
878 * Total memory size allocated by user to be divided
879 * up for actions, hash, counters. Only inline external actions.
881 uint32_t tx_mem_size_in_mb;
883 * [in] Number of flows * 1000
885 uint32_t tx_num_flows_in_k;
887 * [in] SR2 only receive table access interface id
889 uint32_t tx_tbl_if_id;
891 * [in] Flush pending HW cached flows every 1/10th of value
892 * set in seconds, both idle and active flows are flushed
893 * from the HW cache. If set to 0, this feature will be disabled.
895 uint8_t hw_flow_cache_flush_timer;
897 * [out] table scope identifier
899 uint32_t tbl_scope_id;
902 * tf_free_tbl_scope_parms definition
904 struct tf_free_tbl_scope_parms {
906 * [in] table scope identifier
908 uint32_t tbl_scope_id;
912 * tf_map_tbl_scope_parms definition
914 struct tf_map_tbl_scope_parms {
916 * [in] table scope identifier
918 uint32_t tbl_scope_id;
920 * [in] Which parifs are associated with this table scope. Bit 0
923 uint16_t parif_bitmask;
927 * allocate a table scope
929 * On SR2 Firmware will allocate a scope ID. On other devices, the scope
930 * is a software construct to identify an EEM table. This function will
931 * divide the hash memory/buckets and records according to the device
932 * device constraints based upon calculations using either the number of flows
933 * requested or the size of memory indicated. Other parameters passed in
934 * determine the configuration (maximum key size, maximum external action record
937 * This API will allocate the table region in DRAM, program the PTU page table
938 * entries, and program the number of static buckets (if SR2) in the RX and TX
939 * CFAs. Buckets are assumed to start at 0 in the EM memory for the scope.
940 * Upon successful completion of this API, hash tables are fully initialized and
941 * ready for entries to be inserted.
943 * A single API is used to allocate a common table scope identifier in both
944 * receive and transmit CFA. The scope identifier is common due to nature of
945 * connection tracking sending notifications between RX and TX direction.
947 * The receive and transmit table access identifiers specify which rings will
948 * be used to initialize table DRAM. The application must ensure mutual
949 * exclusivity of ring usage for table scope allocation and any table update
952 * The hash table buckets, EM keys, and EM lookup results are stored in the
953 * memory allocated based on the rx_em_hash_mb/tx_em_hash_mb parameters. The
954 * hash table buckets are stored at the beginning of that memory.
956 * NOTE: No EM internal setup is done here. On chip EM records are managed
957 * internally by TruFlow core.
959 * Returns success or failure code.
961 int tf_alloc_tbl_scope(struct tf *tfp,
962 struct tf_alloc_tbl_scope_parms *parms);
965 * map a table scope (legacy device only Wh+/SR)
967 * Map a table scope to one or more partition interfaces (parifs).
968 * The parif can be remapped in the L2 context lookup for legacy devices. This
969 * API allows a number of parifs to be mapped to the same table scope. On
970 * legacy devices a table scope identifies one of 16 sets of EEM table base
971 * addresses and is associated with a PF communication channel. The associated
972 * PF must be configured for the table scope to operate.
974 * An L2 context TCAM lookup returns a remapped parif value used to
975 * index into the set of 16 parif_to_pf registers which are used to map to one
976 * of the 16 table scopes. This API allows the user to map the parifs in the
977 * mask to the previously allocated table scope (EEM table).
979 * Returns success or failure code.
981 int tf_map_tbl_scope(struct tf *tfp,
982 struct tf_map_tbl_scope_parms *parms);
986 * Firmware checks that the table scope ID is owned by the TruFlow
987 * session, verifies that no references to this table scope remains
988 * (SR2 ILT) or Profile TCAM entries for either CFA (RX/TX) direction,
989 * then frees the table scope ID.
991 * Returns success or failure code.
993 int tf_free_tbl_scope(struct tf *tfp,
994 struct tf_free_tbl_scope_parms *parms);
997 * @page tcam TCAM Access
999 * @ref tf_search_tcam_entry
1001 * @ref tf_alloc_tcam_entry
1003 * @ref tf_set_tcam_entry
1005 * @ref tf_get_tcam_entry
1007 * @ref tf_free_tcam_entry
1011 * tf_search_tcam_entry parameter definition (experimental)
1013 struct tf_search_tcam_entry_parms {
1015 * [in] receive or transmit direction
1019 * [in] TCAM table type
1021 enum tf_tcam_tbl_type tcam_tbl_type;
1023 * [in] Key data to match on
1027 * [in] key size in bits
1029 uint16_t key_sz_in_bits;
1031 * [in] Mask data to match on
1035 * [in] Priority of entry requested (definition TBD)
1039 * [in] Allocate on miss.
1043 * [out] Set if matching entry found
1047 * [out] Search result status (hit, miss, reject)
1049 enum tf_search_status search_status;
1051 * [out] Current refcnt after allocation
1055 * [in out] The result data from the search is copied here
1059 * [in out] result size in bits for the result data
1061 uint16_t result_sz_in_bits;
1069 * search TCAM entry (experimental)
1071 * Search for a TCAM entry
1073 * This function searches the shadow copy of the TCAM table for a matching
1074 * entry. Key and mask must match for hit to be set. Only TruFlow core data
1075 * is accessed. If shadow_copy is not enabled, an error is returned.
1079 * A hash is performed on the key/mask data and mapped to a shadow copy entry
1080 * where the full key/mask is populated. If the full key/mask matches the
1081 * entry, hit is set, ref_cnt is incremented, and search_status indicates what
1082 * action the caller can take regarding setting the entry.
1084 * search_status should be used as follows:
1085 * - On Miss, the caller should create a result and call tf_set_tcam_entry with
1088 * - On Reject, the hash table is full and the entry cannot be added.
1090 * - On Hit, the result data is returned to the caller. Additionally, the
1091 * ref_cnt is updated.
1093 * Also returns success or failure code.
1095 int tf_search_tcam_entry(struct tf *tfp,
1096 struct tf_search_tcam_entry_parms *parms);
1099 * tf_alloc_tcam_entry parameter definition
1101 struct tf_alloc_tcam_entry_parms {
1103 * [in] receive or transmit direction
1107 * [in] TCAM table type
1109 enum tf_tcam_tbl_type tcam_tbl_type;
1111 * [in] Enable search for matching entry
1113 uint8_t search_enable;
1115 * [in] Key data to match on (if search)
1119 * [in] key size in bits (if search)
1121 uint16_t key_sz_in_bits;
1123 * [in] Mask data to match on (if search)
1127 * [in] Priority of entry requested (definition TBD)
1131 * [out] If search, set if matching entry found
1135 * [out] Current refcnt after allocation
1139 * [out] Idx allocated
1146 * allocate TCAM entry
1148 * Allocate a TCAM entry - one of these types:
1155 * This function allocates a TCAM table record. This function
1156 * will attempt to allocate a TCAM table entry from the session
1157 * owned TCAM entries or search a shadow copy of the TCAM table for a
1158 * matching entry if search is enabled. Key, mask and result must match for
1159 * hit to be set. Only TruFlow core data is accessed.
1160 * A hash table to entry mapping is maintained for search purposes. If
1161 * search is not enabled, the first available free entry is returned based
1162 * on priority and alloc_cnt is set to 1. If search is enabled and a matching
1163 * entry to entry_data is found, hit is set to TRUE and alloc_cnt is set to 1.
1164 * RefCnt is also returned.
1166 * Also returns success or failure code.
1168 int tf_alloc_tcam_entry(struct tf *tfp,
1169 struct tf_alloc_tcam_entry_parms *parms);
1172 * tf_set_tcam_entry parameter definition
1174 struct tf_set_tcam_entry_parms {
1176 * [in] receive or transmit direction
1180 * [in] TCAM table type
1182 enum tf_tcam_tbl_type tcam_tbl_type;
1184 * [in] base index of the entry to program
1188 * [in] struct containing key
1192 * [in] struct containing mask fields
1196 * [in] key size in bits (if search)
1198 uint16_t key_sz_in_bits;
1200 * [in] struct containing result
1204 * [in] struct containing result size in bits
1206 uint16_t result_sz_in_bits;
1212 * Program a TCAM table entry for a TruFlow session.
1214 * If the entry has not been allocated, an error will be returned.
1216 * Returns success or failure code.
1218 int tf_set_tcam_entry(struct tf *tfp,
1219 struct tf_set_tcam_entry_parms *parms);
1222 * tf_get_tcam_entry parameter definition
1224 struct tf_get_tcam_entry_parms {
1226 * [in] receive or transmit direction
1230 * [in] TCAM table type
1232 enum tf_tcam_tbl_type tcam_tbl_type;
1234 * [in] index of the entry to get
1238 * [out] struct containing key
1242 * [out] struct containing mask fields
1246 * [out] key size in bits
1248 uint16_t key_sz_in_bits;
1250 * [out] struct containing result
1254 * [out] struct containing result size in bits
1256 uint16_t result_sz_in_bits;
1262 * Program a TCAM table entry for a TruFlow session.
1264 * If the entry has not been allocated, an error will be returned.
1266 * Returns success or failure code.
1268 int tf_get_tcam_entry(struct tf *tfp,
1269 struct tf_get_tcam_entry_parms *parms);
1272 * tf_free_tcam_entry parameter definition
1274 struct tf_free_tcam_entry_parms {
1276 * [in] receive or transmit direction
1280 * [in] TCAM table type
1282 enum tf_tcam_tbl_type tcam_tbl_type;
1284 * [in] Index to free
1288 * [out] reference count after free
1298 * Firmware checks to ensure the TCAM entries are owned by the TruFlow
1299 * session. TCAM entry will be invalidated. All-ones mask.
1302 * WCTCAM profile id of 0 must be used to invalidate an entry.
1304 * Returns success or failure code.
1306 int tf_free_tcam_entry(struct tf *tfp,
1307 struct tf_free_tcam_entry_parms *parms);
1310 * @page table Table Access
1312 * @ref tf_alloc_tbl_entry
1314 * @ref tf_free_tbl_entry
1316 * @ref tf_set_tbl_entry
1318 * @ref tf_get_tbl_entry
1320 * @ref tf_bulk_get_tbl_entry
1324 * tf_alloc_tbl_entry parameter definition
1326 struct tf_search_tbl_entry_parms {
1328 * [in] Receive or transmit direction
1332 * [in] Type of the allocation
1334 enum tf_tbl_type type;
1336 * [in] Table scope identifier (ignored unless TF_TBL_TYPE_EXT)
1338 uint32_t tbl_scope_id;
1340 * [in] Result data to search for
1344 * [in] Result data size in bytes
1346 uint16_t result_sz_in_bytes;
1348 * [in] Allocate on miss.
1352 * [out] Set if matching entry found
1356 * [out] Search result status (hit, miss, reject)
1358 enum tf_search_status search_status;
1360 * [out] Current ref count after allocation
1364 * [out] Idx of allocated entry or found entry
1370 * search Table Entry (experimental)
1372 * This function searches the shadow copy of an index table for a matching
1373 * entry. The result data must match for hit to be set. Only TruFlow core
1374 * data is accessed. If shadow_copy is not enabled, an error is returned.
1378 * A hash is performed on the result data and mappe3d to a shadow copy entry
1379 * where the result is populated. If the result matches the entry, hit is set,
1380 * ref_cnt is incremented (if alloc), and the search status indicates what
1381 * action the caller can take regarding setting the entry.
1383 * search status should be used as follows:
1384 * - On MISS, the caller should set the result into the returned index.
1386 * - On REJECT, the caller should reject the flow since there are no resources.
1388 * - On Hit, the matching index is returned to the caller. Additionally, the
1389 * ref_cnt is updated.
1391 * Also returns success or failure code.
1393 int tf_search_tbl_entry(struct tf *tfp,
1394 struct tf_search_tbl_entry_parms *parms);
1397 * tf_alloc_tbl_entry parameter definition
1399 struct tf_alloc_tbl_entry_parms {
1401 * [in] Receive or transmit direction
1405 * [in] Type of the allocation
1407 enum tf_tbl_type type;
1409 * [in] Table scope identifier (ignored unless TF_TBL_TYPE_EXT)
1411 uint32_t tbl_scope_id;
1413 * [in] Enable search for matching entry. If the table type is
1414 * internal the shadow copy will be searched before
1415 * alloc. Session must be configured with shadow copy enabled.
1417 uint8_t search_enable;
1419 * [in] Result data to search for (if search_enable)
1423 * [in] Result data size in bytes (if search_enable)
1425 uint16_t result_sz_in_bytes;
1427 * [out] If search_enable, set if matching entry found
1431 * [out] Current ref count after allocation (if search_enable)
1435 * [out] Idx of allocated entry or found entry (if search_enable)
1441 * allocate index table entries
1445 * Allocate an on chip index table entry or search for a matching
1446 * entry of the indicated type for this TruFlow session.
1448 * Allocates an index table record. This function will attempt to
1449 * allocate an entry or search an index table for a matching entry if
1450 * search is enabled (only the shadow copy of the table is accessed).
1452 * If search is not enabled, the first available free entry is
1453 * returned. If search is enabled and a matching entry to entry_data
1454 * is found hit is set to TRUE and success is returned.
1458 * These are used to allocate inlined action record memory.
1460 * Allocates an external index table action record.
1463 * Implementation of the internals of this function will be a stack with push
1466 * Returns success or failure code.
1468 int tf_alloc_tbl_entry(struct tf *tfp,
1469 struct tf_alloc_tbl_entry_parms *parms);
1472 * tf_free_tbl_entry parameter definition
1474 struct tf_free_tbl_entry_parms {
1476 * [in] Receive or transmit direction
1480 * [in] Type of the allocation type
1482 enum tf_tbl_type type;
1484 * [in] Table scope identifier (ignored unless TF_TBL_TYPE_EXT)
1486 uint32_t tbl_scope_id;
1488 * [in] Index to free
1492 * [out] Reference count after free, only valid if session has been
1493 * created with shadow_copy.
1499 * free index table entry
1501 * Used to free a previously allocated table entry.
1505 * If session has shadow_copy enabled the shadow DB is searched and if
1506 * found the element ref_cnt is decremented. If ref_cnt goes to
1507 * zero then the element is returned to the session pool.
1509 * If the session does not have a shadow DB the element is free'ed and
1510 * given back to the session pool.
1514 * Free's an external index table action record.
1517 * Implementation of the internals of this function will be a stack with push
1520 * Returns success or failure code.
1522 int tf_free_tbl_entry(struct tf *tfp,
1523 struct tf_free_tbl_entry_parms *parms);
1526 * tf_set_tbl_entry parameter definition
1528 struct tf_set_tbl_entry_parms {
1530 * [in] Table scope identifier
1532 uint32_t tbl_scope_id;
1534 * [in] Receive or transmit direction
1538 * [in] Type of object to set
1540 enum tf_tbl_type type;
1548 uint16_t data_sz_in_bytes;
1550 * [in] Entry index to write to
1556 * set index table entry
1558 * Used to insert an application programmed index table entry into a
1559 * previous allocated table location. A shadow copy of the table
1560 * is maintained (if enabled) (only for internal objects)
1562 * Returns success or failure code.
1564 int tf_set_tbl_entry(struct tf *tfp,
1565 struct tf_set_tbl_entry_parms *parms);
1568 * tf_get_tbl_entry parameter definition
1570 struct tf_get_tbl_entry_parms {
1572 * [in] Receive or transmit direction
1576 * [in] Type of object to get
1578 enum tf_tbl_type type;
1586 uint16_t data_sz_in_bytes;
1588 * [in] Entry index to read
1594 * get index table entry
1596 * Used to retrieve a previous set index table entry.
1598 * Reads and compares with the shadow table copy (if enabled) (only
1599 * for internal objects).
1601 * Returns success or failure code. Failure will be returned if the
1602 * provided data buffer is too small for the data type requested.
1604 int tf_get_tbl_entry(struct tf *tfp,
1605 struct tf_get_tbl_entry_parms *parms);
1608 * tf_bulk_get_tbl_entry parameter definition
1610 struct tf_bulk_get_tbl_entry_parms {
1612 * [in] Receive or transmit direction
1616 * [in] Type of object to get
1618 enum tf_tbl_type type;
1620 * [in] Starting index to read from
1622 uint32_t starting_idx;
1624 * [in] Number of sequential entries
1626 uint16_t num_entries;
1628 * [in] Size of the single entry
1630 uint16_t entry_sz_in_bytes;
1632 * [out] Host physical address, where the data
1633 * will be copied to by the firmware.
1634 * Use tfp_calloc() API and mem_pa
1635 * variable of the tfp_calloc_parms
1636 * structure for the physical address.
1638 uint64_t physical_mem_addr;
1642 * Bulk get index table entry
1644 * Used to retrieve a set of index table entries.
1646 * Entries within the range may not have been allocated using
1647 * tf_alloc_tbl_entry() at the time of access. But the range must
1648 * be within the bounds determined from tf_open_session() for the
1649 * given table type. Currently, this is only used for collecting statistics.
1651 * Returns success or failure code. Failure will be returned if the
1652 * provided data buffer is too small for the data type requested.
1654 int tf_bulk_get_tbl_entry(struct tf *tfp,
1655 struct tf_bulk_get_tbl_entry_parms *parms);
1658 * @page exact_match Exact Match Table
1660 * @ref tf_insert_em_entry
1662 * @ref tf_delete_em_entry
1664 * @ref tf_search_em_entry
1668 * tf_insert_em_entry parameter definition
1670 struct tf_insert_em_entry_parms {
1672 * [in] receive or transmit direction
1676 * [in] internal or external
1680 * [in] ID of table scope to use (external only)
1682 uint32_t tbl_scope_id;
1684 * [in] ID of table interface to use (SR2 only)
1688 * [in] ptr to structure containing key fields
1692 * [in] key bit length
1694 uint16_t key_sz_in_bits;
1696 * [in] ptr to structure containing result field
1700 * [out] result size in bits
1702 uint16_t em_record_sz_in_bits;
1704 * [in] duplicate check flag
1708 * [out] Flow handle value for the inserted entry. This is encoded
1709 * as the entries[4]:bucket[2]:hashId[1]:hash[14]
1711 uint64_t flow_handle;
1713 * [out] Flow id is returned as null (internal)
1714 * Flow id is the GFID value for the inserted entry (external)
1715 * This is the value written to the BD and useful information for mark.
1720 * tf_delete_em_entry parameter definition
1722 struct tf_delete_em_entry_parms {
1724 * [in] receive or transmit direction
1728 * [in] internal or external
1732 * [in] ID of table scope to use (external only)
1734 uint32_t tbl_scope_id;
1736 * [in] ID of table interface to use (SR2 only)
1740 * [in] epoch group IDs of entry to delete
1741 * 2 element array with 2 ids. (SR2 only)
1745 * [out] The index of the entry
1749 * [in] structure containing flow delete handle information
1751 uint64_t flow_handle;
1754 * tf_search_em_entry parameter definition
1756 struct tf_search_em_entry_parms {
1758 * [in] receive or transmit direction
1762 * [in] internal or external
1766 * [in] ID of table scope to use (external only)
1768 uint32_t tbl_scope_id;
1770 * [in] ID of table interface to use (SR2 only)
1774 * [in] ptr to structure containing key fields
1778 * [in] key bit length
1780 uint16_t key_sz_in_bits;
1782 * [in/out] ptr to structure containing EM record fields
1786 * [out] result size in bits
1788 uint16_t em_record_sz_in_bits;
1790 * [in] epoch group IDs of entry to lookup
1791 * 2 element array with 2 ids. (SR2 only)
1795 * [in] ptr to structure containing flow delete handle
1797 uint64_t flow_handle;
1801 * insert em hash entry in internal table memory
1805 * This API inserts an exact match entry into internal EM table memory
1806 * of the specified direction.
1808 * Note: The EM record is managed within the TruFlow core and not the
1811 * Shadow copy of internal record table an association with hash and 1,2, or 4
1812 * associated buckets
1815 * This API inserts an exact match entry into DRAM EM table memory of the
1816 * specified direction and table scope.
1818 * When inserting an entry into an exact match table, the TruFlow library may
1819 * need to allocate a dynamic bucket for the entry (SR2 only).
1821 * The insertion of duplicate entries in an EM table is not permitted. If a
1822 * TruFlow application can guarantee that it will never insert duplicates, it
1823 * can disable duplicate checking by passing a zero value in the dup_check
1824 * parameter to this API. This will optimize performance. Otherwise, the
1825 * TruFlow library will enforce protection against inserting duplicate entries.
1827 * Flow handle is defined in this document:
1829 * https://docs.google.com
1830 * /document/d/1NESu7RpTN3jwxbokaPfYORQyChYRmJgs40wMIRe8_-Q/edit
1832 * Returns success or busy code.
1835 int tf_insert_em_entry(struct tf *tfp,
1836 struct tf_insert_em_entry_parms *parms);
1839 * delete em hash entry table memory
1843 * This API deletes an exact match entry from internal EM table memory of the
1844 * specified direction. If a valid flow ptr is passed in then that takes
1845 * precedence over the pointer to the complete key passed in.
1850 * This API deletes an exact match entry from EM table memory of the specified
1851 * direction and table scope. If a valid flow handle is passed in then that
1852 * takes precedence over the pointer to the complete key passed in.
1854 * The TruFlow library may release a dynamic bucket when an entry is deleted.
1857 * Returns success or not found code
1861 int tf_delete_em_entry(struct tf *tfp,
1862 struct tf_delete_em_entry_parms *parms);
1865 * search em hash entry table memory
1869 * This API looks up an EM entry in table memory with the specified EM
1870 * key or flow (flow takes precedence) and direction.
1872 * The status will be one of: success or entry not found. If the lookup
1873 * succeeds, a pointer to the matching entry and the result record associated
1874 * with the matching entry will be provided.
1876 * If flow_handle is set, search shadow copy.
1878 * Otherwise, query the fw with key to get result.
1882 * This API looks up an EM entry in table memory with the specified EM
1883 * key or flow_handle (flow takes precedence), direction and table scope.
1885 * The status will be one of: success or entry not found. If the lookup
1886 * succeeds, a pointer to the matching entry and the result record associated
1887 * with the matching entry will be provided.
1889 * Returns success or not found code
1892 int tf_search_em_entry(struct tf *tfp,
1893 struct tf_search_em_entry_parms *parms);
1896 * @page global Global Configuration
1898 * @ref tf_set_global_cfg
1900 * @ref tf_get_global_cfg
1903 * Tunnel Encapsulation Offsets
1905 enum tf_tunnel_encap_offsets {
1907 TF_TUNNEL_ENCAP_NAT,
1908 TF_TUNNEL_ENCAP_MPLS,
1909 TF_TUNNEL_ENCAP_VXLAN,
1910 TF_TUNNEL_ENCAP_GENEVE,
1911 TF_TUNNEL_ENCAP_NVGRE,
1912 TF_TUNNEL_ENCAP_GRE,
1913 TF_TUNNEL_ENCAP_FULL_GENERIC
1916 * Global Configuration Table Types
1918 enum tf_global_config_type {
1919 TF_TUNNEL_ENCAP, /**< Tunnel Encap Config(TECT) */
1920 TF_ACTION_BLOCK, /**< Action Block Config(ABCR) */
1921 TF_GLOBAL_CFG_TYPE_MAX
1925 * tf_global_cfg parameter definition
1927 struct tf_global_cfg_parms {
1929 * [in] receive or transmit direction
1933 * [in] Global config type
1935 enum tf_global_config_type type;
1937 * [in] Offset @ the type
1941 * [in/out] Value of the configuration
1942 * set - Read, Modify and Write
1943 * get - Read the full configuration
1947 * [in] Configuration mask
1948 * set - Read, Modify with mask and Write
1951 uint8_t *config_mask;
1953 * [in] struct containing size
1955 uint16_t config_sz_in_bytes;
1959 * Get global configuration
1961 * Retrieve the configuration
1963 * Returns success or failure code.
1965 int tf_get_global_cfg(struct tf *tfp,
1966 struct tf_global_cfg_parms *parms);
1969 * Update the global configuration table
1971 * Read, modify write the value.
1973 * Returns success or failure code.
1975 int tf_set_global_cfg(struct tf *tfp,
1976 struct tf_global_cfg_parms *parms);
1979 * @page if_tbl Interface Table Access
1981 * @ref tf_set_if_tbl_entry
1983 * @ref tf_get_if_tbl_entry
1985 * @ref tf_restore_if_tbl_entry
1988 * Enumeration of TruFlow interface table types.
1990 enum tf_if_tbl_type {
1991 /** Default Profile L2 Context Entry */
1992 TF_IF_TBL_TYPE_PROF_SPIF_DFLT_L2_CTXT,
1993 /** Default Profile TCAM/Lookup Action Record Pointer Table */
1994 TF_IF_TBL_TYPE_PROF_PARIF_DFLT_ACT_REC_PTR,
1995 /** Error Profile TCAM Miss Action Record Pointer Table */
1996 TF_IF_TBL_TYPE_PROF_PARIF_ERR_ACT_REC_PTR,
1997 /** Default Error Profile TCAM Miss Action Record Pointer Table */
1998 TF_IF_TBL_TYPE_LKUP_PARIF_DFLT_ACT_REC_PTR,
1999 /** SR2 Ingress lookup table */
2001 /** SR2 VNIC/SVIF Table */
2002 TF_IF_TBL_TYPE_VNIC_SVIF,
2007 * tf_set_if_tbl_entry parameter definition
2009 struct tf_set_if_tbl_entry_parms {
2011 * [in] Receive or transmit direction
2015 * [in] Type of object to set
2017 enum tf_if_tbl_type type;
2025 uint16_t data_sz_in_bytes;
2027 * [in] Interface to write
2033 * set interface table entry
2035 * Used to set an interface table. This API is used for managing tables indexed
2036 * by SVIF/SPIF/PARIF interfaces. In current implementation only the value is
2038 * Returns success or failure code.
2040 int tf_set_if_tbl_entry(struct tf *tfp,
2041 struct tf_set_if_tbl_entry_parms *parms);
2044 * tf_get_if_tbl_entry parameter definition
2046 struct tf_get_if_tbl_entry_parms {
2048 * [in] Receive or transmit direction
2052 * [in] Type of table to get
2054 enum tf_if_tbl_type type;
2062 uint16_t data_sz_in_bytes;
2064 * [in] Entry index to read
2070 * get interface table entry
2072 * Used to retrieve an interface table entry.
2074 * Reads the interface table entry value
2076 * Returns success or failure code. Failure will be returned if the
2077 * provided data buffer is too small for the data type requested.
2079 int tf_get_if_tbl_entry(struct tf *tfp,
2080 struct tf_get_if_tbl_entry_parms *parms);
2082 #endif /* _TF_CORE_H_ */