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 **********/
28 TF_DIR_RX, /**< Receive */
29 TF_DIR_TX, /**< Transmit */
36 * Defines a single pool of external action records of
37 * fixed size. Currently, this is an index.
39 #define TF_EXT_POOL_ENTRY_SZ_BYTES 1
42 * External pool entry count
44 * Defines the number of entries in the external action pool
46 #define TF_EXT_POOL_ENTRY_CNT (1 * 1024)
49 * Number of external pools
51 #define TF_EXT_POOL_CNT_MAX 1
56 #define TF_EXT_POOL_0 0 /**< matches TF_TBL_TYPE_EXT */
57 #define TF_EXT_POOL_1 1 /**< matches TF_TBL_TYPE_EXT_0 */
59 /********** BEGIN API FUNCTION PROTOTYPES/PARAMETERS **********/
62 * @page general General
64 * @ref tf_open_session
66 * @ref tf_attach_session
68 * @ref tf_close_session
72 /** Session Version defines
74 * The version controls the format of the tf_session and
75 * tf_session_info structure. This is to assure upgrade between
76 * versions can be supported.
78 #define TF_SESSION_VER_MAJOR 1 /**< Major Version */
79 #define TF_SESSION_VER_MINOR 0 /**< Minor Version */
80 #define TF_SESSION_VER_UPDATE 0 /**< Update Version */
84 * Name of the TruFlow control channel interface. Expects
85 * format to be RTE Name specific, i.e. rte_eth_dev_get_name_by_port()
87 #define TF_SESSION_NAME_MAX 64
89 #define TF_FW_SESSION_ID_INVALID 0xFF /**< Invalid FW Session ID define */
91 /** Session Identifier
93 * Unique session identifier which includes PCIe bus info to
94 * distinguish the PF and session info to identify the associated
95 * TruFlow session. Session ID is constructed from the passed in
96 * ctrl_chan_name in tf_open_session() together with an allocated
97 * fw_session_id. Done by TruFlow on tf_open_session().
105 uint8_t fw_session_id;
111 * The version controls the format of the tf_session and
112 * tf_session_info structure. This is to assure upgrade between
113 * versions can be supported.
115 * Please see the TF_VER_MAJOR/MINOR and UPDATE defines.
117 struct tf_session_version {
123 /** Session supported device types
126 enum tf_device_type {
127 TF_DEVICE_TYPE_WH = 0, /**< Whitney+ */
128 TF_DEVICE_TYPE_BRD2, /**< TBD */
129 TF_DEVICE_TYPE_BRD3, /**< TBD */
130 TF_DEVICE_TYPE_BRD4, /**< TBD */
131 TF_DEVICE_TYPE_MAX /**< Maximum */
134 /** TruFlow Session Information
136 * Structure defining a TruFlow Session, also known as a Management
137 * session. This structure is initialized at time of
138 * tf_open_session(). It is passed to all of the TruFlow APIs as way
139 * to prescribe and isolate resources between different TruFlow ULP
142 struct tf_session_info {
144 * TrueFlow Version. Used to control the structure layout when
145 * sharing sessions. No guarantee that a secondary process
146 * would come from the same version of an executable.
147 * TruFlow initializes this variable on tf_open_session().
152 struct tf_session_version ver;
154 * will be STAILQ_ENTRY(tf_session_info) next
161 * Session ID is a unique identifier for the session. TruFlow
162 * initializes this variable during tf_open_session()
166 * Access: Truflow & ULP
168 union tf_session_id session_id;
170 * Protects access to core_data. Lock is initialized and owned
171 * by ULP. TruFlow can access the core_data without checking
179 * The core_data holds the TruFlow tf_session data
180 * structure. This memory is allocated and owned by TruFlow on
183 * TruFlow uses this memory for session management control
184 * until the session is closed by ULP. Access control is done
185 * by the spin_lock which ULP controls ahead of TruFlow API
188 * Please see tf_open_session_parms for specification details
196 * The core_data_sz_bytes specifies the size of core_data in
199 * The size is set by TruFlow on tf_open_session().
201 * Please see tf_open_session_parms for specification details
207 uint32_t core_data_sz_bytes;
212 * Contains a pointer to the session info. Allocated by ULP and passed
213 * to TruFlow using tf_open_session(). TruFlow will populate the
214 * session info at that time. Additional 'opens' can be done using
215 * same session_info by using tf_attach_session().
217 * It is expected that ULP allocates this memory as shared memory.
219 * NOTE: This struct must be within the BNXT PMD struct bnxt
220 * (bp). This allows use of container_of() to get access to the PMD.
223 struct tf_session_info *session;
228 * tf_open_session parameters definition.
230 struct tf_open_session_parms {
231 /** [in] ctrl_chan_name
233 * String containing name of control channel interface to be
234 * used for this session to communicate with firmware.
236 * The ctrl_chan_name can be looked up by using
237 * rte_eth_dev_get_name_by_port() within the ULP.
239 * ctrl_chan_name will be used as part of a name for any
240 * shared memory allocation.
242 char ctrl_chan_name[TF_SESSION_NAME_MAX];
245 * Boolean controlling the use and availability of shadow
246 * copy. Shadow copy will allow the TruFlow to keep track of
247 * resource content on the firmware side without having to
248 * query firmware. Additional private session core_data will
249 * be allocated if this boolean is set to 'true', default
252 * Size of memory depends on the NVM Resource settings for the
256 /** [in/out] session_id
258 * Session_id is unique per session.
260 * Session_id is composed of domain, bus, device and
261 * fw_session_id. The construction is done by parsing the
262 * ctrl_chan_name together with allocation of a fw_session_id.
264 * The session_id allows a session to be shared between devices.
266 union tf_session_id session_id;
269 * Device type is passed, one of Wh+, Brd2, Brd3, Brd4
271 enum tf_device_type device_type;
275 * Opens a new TruFlow management session.
277 * TruFlow will allocate session specific memory, shared memory, to
278 * hold its session data. This data is private to TruFlow.
280 * Multiple PFs can share the same session. An association, refcount,
281 * between session and PFs is maintained within TruFlow. Thus, a PF
282 * can attach to an existing session, see tf_attach_session().
284 * No other TruFlow APIs will succeed unless this API is first called and
287 * tf_open_session() returns a session id that can be used on attach.
290 * Pointer to TF handle
292 * Pointer to open parameters
295 * - (0) if successful.
296 * - (-EINVAL) on failure.
298 int tf_open_session(struct tf *tfp,
299 struct tf_open_session_parms *parms);
301 struct tf_attach_session_parms {
302 /** [in] ctrl_chan_name
304 * String containing name of control channel interface to be
305 * used for this session to communicate with firmware.
307 * The ctrl_chan_name can be looked up by using
308 * rte_eth_dev_get_name_by_port() within the ULP.
310 * ctrl_chan_name will be used as part of a name for any
311 * shared memory allocation.
313 char ctrl_chan_name[TF_SESSION_NAME_MAX];
315 /** [in] attach_chan_name
317 * String containing name of attach channel interface to be
318 * used for this session.
320 * The attach_chan_name must be given to a 2nd process after
321 * the primary process has been created. This is the
322 * ctrl_chan_name of the primary process and is used to find
323 * the shared memory for the session that the attach is going
326 char attach_chan_name[TF_SESSION_NAME_MAX];
330 * Session_id is unique per session. For Attach the session_id
331 * should be the session_id that was returned on the first
334 * Session_id is composed of domain, bus, device and
335 * fw_session_id. The construction is done by parsing the
336 * ctrl_chan_name together with allocation of a fw_session_id
337 * during tf_open_session().
339 * A reference count will be incremented on attach. A session
340 * is first fully closed when reference count is zero by
341 * calling tf_close_session().
343 union tf_session_id session_id;
347 * Attaches to an existing session. Used when more than one PF wants
348 * to share a single session. In that case all TruFlow management
349 * traffic will be sent to the TruFlow firmware using the 'PF' that
350 * did the attach not the session ctrl channel.
352 * Attach will increment a ref count as to manage the shared session data.
354 * [in] tfp, pointer to TF handle
355 * [in] parms, pointer to attach parameters
358 * - (0) if successful.
359 * - (-EINVAL) on failure.
361 int tf_attach_session(struct tf *tfp,
362 struct tf_attach_session_parms *parms);
365 * Closes an existing session. Cleans up all hardware and firmware
366 * state associated with the TruFlow application session when the last
367 * PF associated with the session results in refcount to be zero.
369 * Returns success or failure code.
371 int tf_close_session(struct tf *tfp);
374 * @page ident Identity Management
376 * @ref tf_alloc_identifier
378 * @ref tf_free_identifier
380 enum tf_identifier_type {
381 /** The L2 Context is returned from the L2 Ctxt TCAM lookup
382 * and can be used in WC TCAM or EM keys to virtualize further
385 TF_IDENT_TYPE_L2_CTXT,
386 /** The WC profile func is returned from the L2 Ctxt TCAM lookup
387 * to enable virtualization of the profile TCAM.
389 TF_IDENT_TYPE_PROF_FUNC,
390 /** The WC profile ID is included in the WC lookup key
391 * to enable virtualization of the WC TCAM hardware.
393 TF_IDENT_TYPE_WC_PROF,
394 /** The EM profile ID is included in the EM lookup key
395 * to enable virtualization of the EM hardware. (not required for Brd4
396 * as it has table scope)
398 TF_IDENT_TYPE_EM_PROF,
399 /** The L2 func is included in the ILT result and from recycling to
400 * enable virtualization of further lookups.
402 TF_IDENT_TYPE_L2_FUNC
405 /** tf_alloc_identifier parameter definition
407 struct tf_alloc_identifier_parms {
409 * [in] receive or transmit direction
413 * [in] Identifier type
415 enum tf_identifier_type ident_type;
417 * [out] Identifier allocated
422 /** tf_free_identifier parameter definition
424 struct tf_free_identifier_parms {
426 * [in] receive or transmit direction
430 * [in] Identifier type
432 enum tf_identifier_type ident_type;
439 /** allocate identifier resource
441 * TruFlow core will allocate a free id from the per identifier resource type
442 * pool reserved for the session during tf_open(). No firmware is involved.
444 * Returns success or failure code.
446 int tf_alloc_identifier(struct tf *tfp,
447 struct tf_alloc_identifier_parms *parms);
449 /** free identifier resource
451 * TruFlow core will return an id back to the per identifier resource type pool
452 * reserved for the session. No firmware is involved. During tf_close, the
453 * complete pool is returned to the firmware.
455 * Returns success or failure code.
457 int tf_free_identifier(struct tf *tfp,
458 struct tf_free_identifier_parms *parms);
461 * @page dram_table DRAM Table Scope Interface
463 * @ref tf_alloc_tbl_scope
465 * @ref tf_free_tbl_scope
467 * If we allocate the EEM memory from the core, we need to store it in
468 * the shared session data structure to make sure it can be freed later.
469 * (for example if the PF goes away)
471 * Current thought is that memory is allocated within core.
475 /** tf_alloc_tbl_scope_parms definition
477 struct tf_alloc_tbl_scope_parms {
479 * [in] All Maximum key size required.
481 uint16_t rx_max_key_sz_in_bits;
483 * [in] Maximum Action size required (includes inlined items)
485 uint16_t rx_max_action_entry_sz_in_bits;
487 * [in] Memory size in Megabytes
488 * Total memory size allocated by user to be divided
489 * up for actions, hash, counters. Only inline external actions.
490 * Use this variable or the number of flows, do not set both.
492 uint32_t rx_mem_size_in_mb;
494 * [in] Number of flows * 1000. If set, rx_mem_size_in_mb must equal 0.
496 uint32_t rx_num_flows_in_k;
498 * [in] SR2 only receive table access interface id
500 uint32_t rx_tbl_if_id;
502 * [in] All Maximum key size required.
504 uint16_t tx_max_key_sz_in_bits;
506 * [in] Maximum Action size required (includes inlined items)
508 uint16_t tx_max_action_entry_sz_in_bits;
510 * [in] Memory size in Megabytes
511 * Total memory size allocated by user to be divided
512 * up for actions, hash, counters. Only inline external actions.
514 uint32_t tx_mem_size_in_mb;
516 * [in] Number of flows * 1000
518 uint32_t tx_num_flows_in_k;
520 * [in] SR2 only receive table access interface id
522 uint32_t tx_tbl_if_id;
524 * [out] table scope identifier
526 uint32_t tbl_scope_id;
529 struct tf_free_tbl_scope_parms {
531 * [in] table scope identifier
533 uint32_t tbl_scope_id;
537 * allocate a table scope
539 * On SR2 Firmware will allocate a scope ID. On other devices, the scope
540 * is a software construct to identify an EEM table. This function will
541 * divide the hash memory/buckets and records according to the device
542 * device constraints based upon calculations using either the number of flows
543 * requested or the size of memory indicated. Other parameters passed in
544 * determine the configuration (maximum key size, maximum external action record
547 * This API will allocate the table region in
548 * DRAM, program the PTU page table entries, and program the number of static
549 * buckets (if SR2) in the RX and TX CFAs. Buckets are assumed to start at
550 * 0 in the EM memory for the scope. Upon successful completion of this API,
551 * hash tables are fully initialized and ready for entries to be inserted.
553 * A single API is used to allocate a common table scope identifier in both
554 * receive and transmit CFA. The scope identifier is common due to nature of
555 * connection tracking sending notifications between RX and TX direction.
557 * The receive and transmit table access identifiers specify which rings will
558 * be used to initialize table DRAM. The application must ensure mutual
559 * exclusivity of ring usage for table scope allocation and any table update
562 * The hash table buckets, EM keys, and EM lookup results are stored in the
563 * memory allocated based on the rx_em_hash_mb/tx_em_hash_mb parameters. The
564 * hash table buckets are stored at the beginning of that memory.
566 * NOTES: No EM internal setup is done here. On chip EM records are managed
567 * internally by TruFlow core.
569 * Returns success or failure code.
571 int tf_alloc_tbl_scope(struct tf *tfp,
572 struct tf_alloc_tbl_scope_parms *parms);
578 * Firmware checks that the table scope ID is owned by the TruFlow
579 * session, verifies that no references to this table scope remains
580 * (SR2 ILT) or Profile TCAM entries for either CFA (RX/TX) direction,
581 * then frees the table scope ID.
583 * Returns success or failure code.
585 int tf_free_tbl_scope(struct tf *tfp,
586 struct tf_free_tbl_scope_parms *parms);
591 enum tf_tcam_tbl_type {
592 TF_TCAM_TBL_TYPE_L2_CTXT_TCAM,
593 TF_TCAM_TBL_TYPE_PROF_TCAM,
594 TF_TCAM_TBL_TYPE_WC_TCAM,
595 TF_TCAM_TBL_TYPE_SP_TCAM,
596 TF_TCAM_TBL_TYPE_CT_RULE_TCAM,
597 TF_TCAM_TBL_TYPE_VEB_TCAM,
603 * @page tcam TCAM Access
605 * @ref tf_alloc_tcam_entry
607 * @ref tf_set_tcam_entry
609 * @ref tf_get_tcam_entry
611 * @ref tf_free_tcam_entry
614 /** tf_alloc_tcam_entry parameter definition
616 struct tf_alloc_tcam_entry_parms {
618 * [in] receive or transmit direction
622 * [in] TCAM table type
624 enum tf_tcam_tbl_type tcam_tbl_type;
626 * [in] Enable search for matching entry
628 uint8_t search_enable;
630 * [in] Key data to match on (if search)
634 * [in] key size in bits (if search)
636 uint16_t key_sz_in_bits;
638 * [in] Mask data to match on (if search)
642 * [in] Priority of entry requested (definition TBD)
646 * [out] If search, set if matching entry found
650 * [out] Current refcnt after allocation
654 * [out] Idx allocated
660 /** allocate TCAM entry
662 * Allocate a TCAM entry - one of these types:
669 * This function allocates a TCAM table record. This function
670 * will attempt to allocate a TCAM table entry from the session
671 * owned TCAM entries or search a shadow copy of the TCAM table for a
672 * matching entry if search is enabled. Key, mask and result must match for
673 * hit to be set. Only TruFlow core data is accessed.
674 * A hash table to entry mapping is maintained for search purposes. If
675 * search is not enabled, the first available free entry is returned based
676 * on priority and alloc_cnt is set to 1. If search is enabled and a matching
677 * entry to entry_data is found, hit is set to TRUE and alloc_cnt is set to 1.
678 * RefCnt is also returned.
680 * Also returns success or failure code.
682 int tf_alloc_tcam_entry(struct tf *tfp,
683 struct tf_alloc_tcam_entry_parms *parms);
685 /** tf_set_tcam_entry parameter definition
687 struct tf_set_tcam_entry_parms {
689 * [in] receive or transmit direction
693 * [in] TCAM table type
695 enum tf_tcam_tbl_type tcam_tbl_type;
697 * [in] base index of the entry to program
701 * [in] struct containing key
705 * [in] struct containing mask fields
709 * [in] key size in bits (if search)
711 uint16_t key_sz_in_bits;
713 * [in] struct containing result
717 * [in] struct containing result size in bits
719 uint16_t result_sz_in_bits;
724 * Program a TCAM table entry for a TruFlow session.
726 * If the entry has not been allocated, an error will be returned.
728 * Returns success or failure code.
730 int tf_set_tcam_entry(struct tf *tfp,
731 struct tf_set_tcam_entry_parms *parms);
733 /** tf_get_tcam_entry parameter definition
735 struct tf_get_tcam_entry_parms {
737 * [in] receive or transmit direction
741 * [in] TCAM table type
743 enum tf_tcam_tbl_type tcam_tbl_type;
745 * [in] index of the entry to get
749 * [out] struct containing key
753 * [out] struct containing mask fields
757 * [out] key size in bits
759 uint16_t key_sz_in_bits;
761 * [out] struct containing result
765 * [out] struct containing result size in bits
767 uint16_t result_sz_in_bits;
772 * Program a TCAM table entry for a TruFlow session.
774 * If the entry has not been allocated, an error will be returned.
776 * Returns success or failure code.
778 int tf_get_tcam_entry(struct tf *tfp,
779 struct tf_get_tcam_entry_parms *parms);
781 /** tf_free_tcam_entry parameter definition
783 struct tf_free_tcam_entry_parms {
785 * [in] receive or transmit direction
789 * [in] TCAM table type
791 enum tf_tcam_tbl_type tcam_tbl_type;
797 * [out] reference count after free
806 * Firmware checks to ensure the TCAM entries are owned by the TruFlow
807 * session. TCAM entry will be invalidated. All-ones mask.
810 * WCTCAM profile id of 0 must be used to invalidate an entry.
812 * Returns success or failure code.
814 int tf_free_tcam_entry(struct tf *tfp,
815 struct tf_free_tcam_entry_parms *parms);
818 * @page table Table Access
820 * @ref tf_alloc_tbl_entry
822 * @ref tf_free_tbl_entry
824 * @ref tf_set_tbl_entry
826 * @ref tf_get_tbl_entry
830 * Enumeration of TruFlow table types. A table type is used to identify a
833 * NOTE: The table type TF_TBL_TYPE_EXT is unique in that it is
834 * the only table type that is connected with a table scope.
837 /** Wh+/Brd2 Action Record */
838 TF_TBL_TYPE_FULL_ACT_RECORD,
839 /** Multicast Groups */
840 TF_TBL_TYPE_MCAST_GROUPS,
841 /** Action Encap 8 Bytes */
842 TF_TBL_TYPE_ACT_ENCAP_8B,
843 /** Action Encap 16 Bytes */
844 TF_TBL_TYPE_ACT_ENCAP_16B,
845 /** Action Encap 64 Bytes */
846 TF_TBL_TYPE_ACT_ENCAP_32B,
847 /** Action Encap 64 Bytes */
848 TF_TBL_TYPE_ACT_ENCAP_64B,
849 /** Action Source Properties SMAC */
850 TF_TBL_TYPE_ACT_SP_SMAC,
851 /** Action Source Properties SMAC IPv4 */
852 TF_TBL_TYPE_ACT_SP_SMAC_IPV4,
853 /** Action Source Properties SMAC IPv6 */
854 TF_TBL_TYPE_ACT_SP_SMAC_IPV6,
855 /** Action Statistics 64 Bits */
856 TF_TBL_TYPE_ACT_STATS_64,
857 /** Action Modify L4 Src Port */
858 TF_TBL_TYPE_ACT_MODIFY_SPORT,
859 /** Action Modify L4 Dest Port */
860 TF_TBL_TYPE_ACT_MODIFY_DPORT,
861 /** Action Modify IPv4 Source */
862 TF_TBL_TYPE_ACT_MODIFY_IPV4_SRC,
863 /** Action _Modify L4 Dest Port */
864 TF_TBL_TYPE_ACT_MODIFY_IPV4_DEST,
865 /** Action Modify IPv6 Source */
866 TF_TBL_TYPE_ACT_MODIFY_IPV6_SRC,
867 /** Action Modify IPv6 Destination */
868 TF_TBL_TYPE_ACT_MODIFY_IPV6_DEST,
872 /** Meter Profiles */
873 TF_TBL_TYPE_METER_PROF,
874 /** Meter Instance */
875 TF_TBL_TYPE_METER_INST,
877 TF_TBL_TYPE_MIRROR_CONFIG,
880 /** Brd4 Epoch 0 table */
882 /** Brd4 Epoch 1 table */
885 TF_TBL_TYPE_METADATA,
887 TF_TBL_TYPE_CT_STATE,
888 /** Brd4 Range Profile */
889 TF_TBL_TYPE_RANGE_PROF,
890 /** Brd4 Range Entry */
891 TF_TBL_TYPE_RANGE_ENTRY,
892 /** Brd4 LAG Entry */
894 /** Brd4 only VNIC/SVIF Table */
895 TF_TBL_TYPE_VNIC_SVIF,
899 /** External table type - initially 1 poolsize entries.
900 * All External table types are associated with a table
901 * scope. Internal types are not.
904 /** Future - external pool of size0 entries */
908 #endif /* _TF_CORE_H_ */