1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
/* Copyright (c) 2015, Linaro Limited
* All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
/**
* @file
*
* ODP table
*
* TCAM(Ternary Content Addressable Memory) is used widely in packet
* forwarding to speedup the table lookup.
*
* This file contains a simple interface for creating and using the table.
* Table here means a collection of related data held in a structured
* format.
* Some examples for table are ARP Table, Routing Table, etc.The table
* contains many entries, each consist of key and associated data
* (called key/value pair or rule/action pair in some paper.).
* Enclosed are some classical table examples, used publicly
* in data plane packet processing:
*
* <H3>Use Case: ARP table</H3>
* Once a route has been identified for an IP packet (so the output
* interface and the IP address of the next hop station are known),
* the MAC address of the next hop station is needed in order to
* send this packet onto the next leg of the journey
* towards its destination (as identified by its destination IP address).
* The MAC address of the next hop station becomes the destination
* MAC address of the outgoing Ethernet frame.
* <ol>
* <li>Key: The pair of (Output interface, Next Hop IP address)
* <li>Associated Data: MAC address of the next hop station
* <li>Algorithm: Hash
* </ol>
*
* <H3>Use Case: Routing Table</H3>
* When each router receives a packet, it searches its routing table
* to find the best match between the destination IP address of
* the packet and one of the network addresses in the routing table.
* <ol>
* <li>Key: destination IP address
* <li>Associated Data: The pair of (Output interface, Next Hop IP address)
* <li>Algorithm: LPM(Longest Prefix Match)
* </ol>
*
* <H3>Use Case: Flow Classification</H3>
* The flow classification is executed at least once for each
* input packet.This operation maps each incoming packet against
* one of the known traffic
* flows in the flow database that typically contains millions of flows.
* <ol>
* <li>Key:n-tuple of packet fields that uniquely identify a traffic flow.
* <li>Associated data:
* actions and action meta-data describing what processing to be
* applied for the packets of the current flow, such as whether
* encryption/decryption is required on this packet, what kind of cipher
* algorithm should be chosed.
* <li>Algorithm: Hash
* </ol>
*
* All these different types of lookup tables have the common operations:
* create a table, destroy a table, add (key,associated data),
* delete key and look up the associated data via the key.
* Usually these operations are software based, but also can be
* hardware accelerated such as using TCAM to implement ARP table
* or Routing Table.
* And specific alogithm can be used for specific lookup table.
*
* notes: key/value and key/associated data mean the same thing
* in this file unless otherwise mentioned.
*
*/
#ifndef ODPH_TABLE_H_
#define ODPH_TABLE_H_
#ifdef __cplusplus
extern "C" {
#endif
/**
* @addtogroup odph_tables ODPH TABLES
* @{
*/
#include <stdint.h>
/**
* @def ODPH_TABLE_NAME_LEN
* Max length of table name
*/
#define ODPH_TABLE_NAME_LEN 32
#include <odp/helper/strong_types.h>
/** ODP table handle */
typedef ODPH_HANDLE_T(odph_table_t);
/**
* create a table
* Generally, tables only support key-value pair both with fixed size
*
* @param name
* name of this table, max ODPH_TABLE_NAME_LEN - 1
* May be specified as NULL for anonymous table
* @param capacity
* Max memory usage this table use, in MBytes
* @param key_size
* fixed size of the 'key' in bytes.
* @param value_size
* fixed size of the 'value' in bytes.
* @return
* Handle to table instance or NULL if failed
* @note
*/
typedef odph_table_t (*odph_table_create)(const char *name,
uint32_t capacity,
uint32_t key_size,
uint32_t value_size);
/**
* Find a table by name
*
* @param name Name of the table
*
* @return Handle of found table
* @retval NULL table could not be found
*
* @note This routine cannot be used to look up an anonymous
* table (one created with no name).
* This API supports Multiprocess
*/
typedef odph_table_t (*odph_table_lookup)(const char *name);
/**
* Destroy a table previously created by odph_table_create()
*
* @param table Handle of the table to be destroyed
*
* @retval 0 Success
* @retval -1 Failure
*
* @note This routine destroys a previously created pool
* also should free any memory allocated at creation
*
*/
typedef int (*odph_table_destroy)(odph_table_t table);
/**
* Add (key,associated data) pair into the specific table.
* When no associated data is currently assocated with key,
* then the (key,assocatied data) association is created.
* When key is already associated with data0, then association (key, data0)
* will be removed and association (key, associated data) is created.
*
* @param table Handle of the table that the element be added
*
* @param key address of 'key' in key-value pair.
* User should make sure the address and 'key_size'
* bytes after are accessible
* @param value address of 'value' in key-value pair
* User should make sure the address and 'value_size'
* bytes after are accessible
* @retval 0 Success
* @retval -1 Failure
* @note Add a same key again with a new value, the older one will
* be covered.
*/
typedef int (*odph_table_put_value)(odph_table_t table, void *key,
void *value);
/**
* Lookup the associated data via specific key.
* When no value is currently associated with key, then this operation
* restuns <0 to indicate the lookup miss.
* When key is associated with value,
* then this operation returns value.
* The (key,value) association won't change.
*
* @param table Handle of the table that the element be added
*
* @param key address of 'key' in key-value pair
* User should make sure the address and key_size bytes after
* are accessible
*
* @param buffer output The buffer address to the 'value'
* After successfully found, the content of 'value' will be
* copied to this address
* User should make sure the address and value_size bytes
* after are accessible
* @param buffer_size size of the buffer
* should be equal or bigger than value_size
* @retval 0 Success
* @retval -1 Failure
*
* @note
*/
typedef int (*odph_table_get_value)(odph_table_t table, void *key,
void *buffer,
uint32_t buffer_size);
/**
* Delete the association specified by key
* When no data is currently associated with key, this operation
* has no effect. When key is already associated data ad0,
* then (key,ad0) pair is deleted.
*
* @param table Handle of the table that the element will be removed from
*
* @param key address of 'key' in key-value pair
* User should make sure the address and key_size bytes after
* are accessible
*
* @retval 0 Success
* @retval -1 Failure
*
* @note
*/
typedef int (*odph_table_remove_value)(odph_table_t table, void *key);
/**
* Table interface set. Defining the table operations.
*/
typedef struct odph_table_ops_t {
odph_table_create f_create; /**< Table Create */
odph_table_lookup f_lookup; /**< Table Lookup */
odph_table_destroy f_des; /**< Table Destroy */
/** add (key,associated data) pair into the specific table */
odph_table_put_value f_put;
/** lookup the associated data via specific key */
odph_table_get_value f_get;
/** delete the association specified by key */
odph_table_remove_value f_remove;
} odph_table_ops_t;
/**
* @}
*/
#ifdef __cplusplus
}
#endif
#endif
|
