hashref.h Source File

Reference Documentation

Platform
Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.10
Napatech Software Suite: include/ntutil/hashref.h Source File
hashref.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2023 Napatech A/S. All Rights Reserved.
4  *
5  * 1. Copying, modification, and distribution of this file, or executable
6  * versions of this file, is governed by the terms of the Napatech Software
7  * license agreement under which this file was made available. If you do not
8  * agree to the terms of the license do not install, copy, access or
9  * otherwise use this file.
10  *
11  * 2. Under the Napatech Software license agreement you are granted a
12  * limited, non-exclusive, non-assignable, copyright license to copy, modify
13  * and distribute this file in conjunction with Napatech SmartNIC's and
14  * similar hardware manufactured or supplied by Napatech A/S.
15  *
16  * 3. The full Napatech Software license agreement is included in this
17  * distribution, please see "NP-0405 Napatech Software license
18  * agreement.pdf"
19  *
20  * 4. Redistributions of source code must retain this copyright notice,
21  * list of conditions and the following disclaimer.
22  *
23  * THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES, EXPRESS OR
24  * IMPLIED, AND NAPATECH DISCLAIMS ALL IMPLIED WARRANTIES INCLUDING ANY
25  * IMPLIED WARRANTY OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, OR OF
26  * FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT NOT PROHIBITED BY
27  * APPLICABLE LAW, IN NO EVENT SHALL NAPATECH BE LIABLE FOR PERSONAL INJURY,
28  * OR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES WHATSOEVER,
29  * INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, CORRUPTION OR
30  * LOSS OF DATA, FAILURE TO TRANSMIT OR RECEIVE ANY DATA OR INFORMATION,
31  * BUSINESS INTERRUPTION OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, ARISING
32  * OUT OF OR RELATED TO YOUR USE OR INABILITY TO USE NAPATECH SOFTWARE OR
33  * SERVICES OR ANY THIRD PARTY SOFTWARE OR APPLICATIONS IN CONJUNCTION WITH
34  * THE NAPATECH SOFTWARE OR SERVICES, HOWEVER CAUSED, REGARDLESS OF THE THEORY
35  * OF LIABILITY (CONTRACT, TORT OR OTHERWISE) AND EVEN IF NAPATECH HAS BEEN
36  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME JURISDICTIONS DO NOT ALLOW
37  * THE EXCLUSION OR LIMITATION OF LIABILITY FOR PERSONAL INJURY, OR OF
38  * INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION MAY NOT APPLY TO YOU.
39  *
40  *
41 
42  */
43 
44 /**
45  * @file
46  *
47  * This header file contains the interface to the hash reference library.
48  *
49  */
50 #ifndef __HASHREF_H__
51 #define __HASHREF_H__
52 
53 #include "nt.h"
54 
55 /**
56  * Available hash modes
57  */
60  NT_HASHREF_HASHMODE_LAST_MPLS_LABEL, //!< Hash Key Type 2: Last MPLS Label
61  NT_HASHREF_HASHMODE_ALL_MPLS_LABELS, //!< Hash Key Type 3: All MPLS Labels
62  NT_HASHREF_HASHMODE_2_TUPLE, //!< Hash Key Type 4: 2-Tuple
63  NT_HASHREF_HASHMODE_2_TUPLE_SORTED, //!< Hash Key Type 5: 2-Tuple Sorted
64  NT_HASHREF_HASHMODE_LAST_VLAN_ID, //!< Hash Key Type 6: Last VLAN ID
65  NT_HASHREF_HASHMODE_ALL_VLAN_IDS, //!< Hash Key Type 7: All VLAN IDs
66  NT_HASHREF_HASHMODE_5_TUPLE, //!< Hash Key Type 8: 5-Tuple
67  NT_HASHREF_HASHMODE_5_TUPLE_SORTED, //!< Hash Key Type 9: 5-Tuple Sorted
68  NT_HASHREF_HASHMODE_3_TUPLE_GRE_V0, //!< Hash Key Type 10: 3-Tuple GREv0
69  NT_HASHREF_HASHMODE_3_TUPLE_GRE_V0_SORTED, //!< Hash Key Type 11: 3-Tuple GREv0 Sorted
70  NT_HASHREF_HASHMODE_5_TUPLE_SCTP, //!< Hash Key Type 12: 5-Tuple SCTP
71  NT_HASHREF_HASHMODE_5_TUPLE_SCTP_SORTED, //!< Hash Key Type 13: 5-Tuple SCTP Sorted
72  NT_HASHREF_HASHMODE_INNER_2_TUPLE, //!< Hash Key Type 14 for PCIe Gen2 Adapters: Inner 2-Tuple
73  NT_HASHREF_HASHMODE_3_TUPLE_GTP_V0, //!< Hash Key Type 14 for PCIe Gen1 Adapters: 3-Tuple GTPv0
74  NT_HASHREF_HASHMODE_INNER_2_TUPLE_SORTED, //!< Hash Key Type 15 for PCIe Gen2 Adapters: Inner 2-Tuple Sorted
75  NT_HASHREF_HASHMODE_3_TUPLE_GTP_V0_SORTED, //!< Hash Key Type 15 for PCIe Gen1 Adapters: 3-Tuple GTPv0 Sorted
76  NT_HASHREF_HASHMODE_INNER_5_TUPLE, //!< Hash Key Type 16 for PCIe Gen2 Adapters: Inner 5-Tuple
77  NT_HASHREF_HASHMODE_3_TUPLE_GTP_V1V2, //!< Hash Key Type 16 for PCIe Gen1 Adapters: 3-Tuple GTPv1/GTPv2
78  NT_HASHREF_HASHMODE_INNER_5_TUPLE_SORTED, //!< Hash Key Type 17 for PCIe Gen2 Adapters: Inner 5-Tuple Sorted
79  NT_HASHREF_HASHMODE_3_TUPLE_GTP_V1V2_SORTED, //!< Hash Key Type 17 for PCIe Gen1 Adapters: 3-Tuple GTPv1/GTPv2 Sorted
80  NT_HASHREF_HASHMODE_IP_FRAGMENT_TUPLE, //!< Hash Key Type 30 for PCIe Gen2 Adapters: IP Fragment Tuple
82 };
83 
84 /**
85  * Hash reference configuration
86  */
87 typedef struct NtHashRefConfig_v0_s {
88  enum NtAdapterType_e adapterType; //!< The adapter type
89  union Ntfpgaid_u fpgaid; //!< The FPGA ID of the adapter to emulate in the hash value calculation
90  enum NtHashRefHashMode_e hashmode;//!< The hash mode to use, see @ref ::NtHashRefHashMode_e for available hash modes
91  uint32_t hashmask[10]; //!< Hash mask - default in NTPL is 0xFFFFFFFF for all hash words.
92  uint32_t streams; //!< Number of streams to distribute to
93  uint32_t seed; //!< Hash seed as defined in ntservice.ini. Default is 0xFFFFFFFF
95 
96 /**
97  * Hash reference configuration versions
98  */
101  NT_HASHREF_CONFIG_V0, //!< Use hash reference configuration @ref ::NtHashRefConfig_v0_t
103 };
104 
105 /**
106  * Hash reference configuration
107  */
108 typedef struct NtHashRefConfig_s {
109  enum NtHashRefConfig_e config; //!< Configuration version to use
111  NtHashRefConfig_v0_t config_v0; //!< Hash reference configuration version 0
112  } u;
114 
115 
137 };
138 
139 /**
140  * Hash calculation input
141  */
142 typedef struct {
143  /**
144  * hashref input union
145  */
146  enum NtHashRefInputType_e inputType; /* Denotes the used structure */
149  uint32_t label; //!< 20-bit MPLS label
150  } lastMplsLabel;
152  uint32_t label[7]; //!< 20-bit MPLS label
153  } allMplsLabels;
154  struct NtTuple2IPv4_s {
155  uint32_t srcIP; //!< 32-bit IPv4 address in network order
156  uint32_t dstIP; //!< 32-bit IPv4 address in network order
157  } tuple2IPv4;
158  struct NtTuple2IPv6_s {
159  uint8_t srcIP[16]; //!< 128-bit IPv6 address in network order
160  uint8_t dstIP[16]; //!< 128-bit IPv6 address in network order
161  } tuple2IPv6;
162  struct NtLastVlanId_s {
163  uint16_t vlanId; //!< 12-bit VLAN Id in network order
164  } lastVlanId;
165  struct NtAllVlanIds_s {
166  uint16_t vlanId[3]; //!< 12-bit VLAN Id in network order
167  } allVlanIds;
168  struct NtTuple5IPv4_s {
169  uint32_t srcIP; //!< 32-bit IPv4 address in network order
170  uint32_t dstIP; //!< 32-bit IPv4 address in network order
171  uint16_t srcPort; //!< 16-bit port number in network order
172  uint16_t dstPort; //!< 16-bit port number in network order
173  uint8_t protocol; //!< 8-bit IP protocol number
174  } tuple5IPv4;
175  struct NtTuple5IPv6_s {
176  uint8_t srcIP[16]; //!< 128-bit IPv6 address in network order
177  uint8_t dstIP[16]; //!< 128-bit IPv6 address in network order
178  uint16_t srcPort; //!< 16-bit port number in network order
179  uint16_t dstPort; //!< 16-bit port number in network order
180  uint8_t protocol; //!< 8-bit IP protocol number
181  } tuple5IPv6;
183  uint32_t srcIP; //!< 32-bit IPv4 address in network order
184  uint32_t dstIP; //!< 32-bit IPv4 address in network order
185  uint32_t key; //!< 32-bit GRE key in network order
186  } tuple3GREv0IPv4;
188  uint8_t srcIP[16]; //!< 128-bit IPv6 address in network order
189  uint8_t dstIP[16]; //!< 128-bit IPv6 address in network order
190  uint32_t key; //!< 32-bit GRE key in network order
191  } tuple3GREv0IPv6;
193  uint32_t srcIP; //!< 32-bit IPv4 address in network order
194  uint32_t dstIP; //!< 32-bit IPv4 address in network order
195  uint16_t srcPort; //!< 16-bit port number in network order
196  uint16_t dstPort; //!< 16-bit port number in network order
197  uint32_t verificationTag;//!< 32-bit verification tag in network order
198  } tuple5SCTPIPv4;
200  uint8_t srcIP[16]; //!< 128-bit IPv6 address in network order
201  uint8_t dstIP[16]; //!< 128-bit IPv6 address in network order
202  uint16_t srcPort; //!< 16-bit port number in network order
203  uint16_t dstPort; //!< 16-bit port number in network order
204  uint32_t verificationTag;//!< 32-bit verification tag in network order
205  } tuple5SCTPIPv6;
207  uint32_t srcIP; //!< 32-bit IPv4 address in network order
208  uint32_t dstIP; //!< 32-bit IPv4 address in network order
209  uint16_t ipId; //!< 16-bit IP identifier in network order
210  uint8_t ipProt; //!< 8-bit IP protocol number
211  } ipFragmentTupleIPv4;
213  uint8_t srcIP[16]; //!< 128-bit IPv6 address in network order
214  uint8_t dstIP[16]; //!< 128-bit IPv6 address in network order
215  uint32_t id; //!< 32-bit fragment identifier
216  } ipFragmentTupleIPv6;
218  uint32_t srcIP; //!< 32-bit IPv4 address in network order
219  uint32_t dstIP; //!< 32-bit IPv4 address in network order
220  uint16_t flowLabel; //!< 16-bit flow label in network order
221  } tuple3GTPv0IPv4;
223  uint8_t srcIP[16]; //!< 128-bit IPv6 address in network order
224  uint8_t dstIP[16]; //!< 128-bit IPv6 address in network order
225  uint16_t flowLabel; //!< 16-bit flow label in network order
226  } tuple3GTPv0IPv6;
228  uint32_t srcIP; //!< 32-bit IPv4 address in network order
229  uint32_t dstIP; //!< 32-bit IPv4 address in network order
230  uint32_t teid; //!< 32-bit tunnel identifier in network order
231  } tuple3GTPv1v2IPv4;
233  uint8_t srcIP[16]; //!< 128-bit IPv6 address in network order
234  uint8_t dstIP[16]; //!< 128-bit IPv6 address in network order
235  uint32_t teid; //!< 32-bit tunnel identifier in network order
236  } tuple3GTPv1v2IPv6;
237  } u;
239 
240 typedef struct NtHashRefResult_s {
241  uint32_t hashvalue; //!< 24-bit calculated hash value
242  uint32_t stream; //!< Destination stream - set if the streams value
243  //!< is non-zero in the hash reference configuration
245 
246 /**
247  * Hash reference handle
248  */
249 typedef struct NtHashRef_s *NtHashRef_t;
250 typedef const struct NtHashRef_s *const_NtHashRef_t;
251 
252 /**
253  * @brief Allocate and configure a hash reference handle
254  *
255  * @param[out] handle Allocated hash reference handle
256  * @param[in] config Hash reference configuration
257  *
258  * @retval 0 Success
259  * @retval !=0 Error
260  */
261 int NT_HashRefOpen(NtHashRef_t *handle, const NtHashRefConfig_t *config);
262 
263 /**
264  * @brief Calculate hash value
265  *
266  * This function calculates the hash value based on the configuration
267  * associated with the handle and the input given
268  *
269  * @param[in] handle Hash reference handle
270  * @param[in] input Input for hash calculation. Must match the selected input type
271  * @param[out] result The result of the hash calculation
272  *
273  * @retval 0 Success
274  * @retval !=0 Error
275  */
276 int NT_HashRefCalc(NtHashRef_t handle, const NtHashRefInput_t *input,
277  NtHashRefResult_t *result);
278 
279 /**
280  * @brief Calculate 32-bit hash value
281  *
282  * This function calculates the hash value based on the configuration
283  * associated with the handle and the input given
284  *
285  * @param[in] handle Hash reference handle
286  * @param[in] input Input for hash calculation. Must match the selected input type
287  * @param[out] result The result of the 32-bit hash calculation
288  *
289  * @retval 0 Success
290  * @retval !=0 Error
291  */
292 int NT_HashRefCalcV2(NtHashRef_t handle, const NtHashRefInput_t *input,
293  NtHashRefResult_t *result);
294 
295 /**
296  * @brief Close the hash reference handle and free associated resources
297  *
298  * @retval 0 Success
299  * @retval !=0 Error
300  */
301 int NT_HashRefClose(NtHashRef_t handle);
302 
303 #endif // __HASHREF_H__