summaryrefslogtreecommitdiff
path: root/lib/librte_kni/rte_kni.h
blob: 8be6281d8bba03f4aa9a5514bf7fad8a97d8d9ae (plain)
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
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
/*-
 *   BSD LICENSE
 * 
 *   Copyright(c) 2010-2013 Intel Corporation. All rights reserved.
 *   All rights reserved.
 * 
 *   Redistribution and use in source and binary forms, with or without
 *   modification, are permitted provided that the following conditions
 *   are met:
 * 
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in
 *       the documentation and/or other materials provided with the
 *       distribution.
 *     * Neither the name of Intel Corporation nor the names of its
 *       contributors may be used to endorse or promote products derived
 *       from this software without specific prior written permission.
 * 
 *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _RTE_KNI_H_
#define _RTE_KNI_H_

/**
 * @file
 * RTE KNI
 *
 * The KNI library provides the ability to create and destroy kernel NIC
 * interfaces that may be used by the RTE application to receive/transmit
 * packets from/to Linux kernel net interfaces.
 *
 * This library provide two APIs to burst receive packets from KNI interfaces,
 * and burst transmit packets to KNI interfaces.
 */

#include <rte_pci.h>
#include <rte_mbuf.h>

#include <exec-env/rte_kni_common.h>

#ifdef __cplusplus
extern "C" {
#endif

struct rte_kni;

/**
 * Structure which has the function pointers for KNI interface.
 */
struct rte_kni_ops {
	uint8_t port_id; /* Port ID */

	/* Pointer to function of changing MTU */
	int (*change_mtu)(uint8_t port_id, unsigned new_mtu);

	/* Pointer to function of configuring network interface */
	int (*config_network_if)(uint8_t port_id, uint8_t if_up);
};

/**
 * Structure for configuring KNI device.
 */
struct rte_kni_conf {
	/*
	 * KNI name which will be used in relevant network device.
	 * Let the name as short as possible, as it will be part of
	 * memzone name.
	 */
	char name[RTE_KNI_NAMESIZE];
	uint16_t group_id;  /* Group ID */
	unsigned mbuf_size; /* mbuf size */
	struct rte_pci_addr addr;
	struct rte_pci_id id;
};

/**
 * Allocate KNI interface according to the port id, mbuf size, mbuf pool,
 * configurations and callbacks for kernel requests.The KNI interface created
 * in the kernel space is the net interface the traditional Linux application
 * talking to.
 *
 * @param pktmbuf_pool
 *  The mempool for allocting mbufs for packets.
 * @param conf
 *  The pointer to the configurations of the KNI device.
 * @param ops
 *  The pointer to the callbacks for the KNI kernel requests.
 *
 * @return
 *  - The pointer to the context of a KNI interface.
 *  - NULL indicate error.
 */
extern struct rte_kni *rte_kni_alloc(struct rte_mempool *pktmbuf_pool,
				     const struct rte_kni_conf *conf,
				     struct rte_kni_ops *ops);

/**
 * It create a KNI device for specific port.
 *
 * Note: It is deprecated and just for backward compatibility.
 *
 * @param port_id
 *  Port ID.
 * @param mbuf_size
 *  mbuf size.
 * @param pktmbuf_pool
 *  The mempool for allocting mbufs for packets.
 * @param ops
 *  The pointer to the callbacks for the KNI kernel requests.
 *
 * @return
 *  - The pointer to the context of a KNI interface.
 *  - NULL indicate error.
 */
extern struct rte_kni *rte_kni_create(uint8_t port_id,
				      unsigned mbuf_size,
				      struct rte_mempool *pktmbuf_pool,
				      struct rte_kni_ops *ops) \
				      __attribute__ ((deprecated));

/**
 * Release KNI interface according to the context. It will also release the
 * paired KNI interface in kernel space. All processing on the specific KNI
 * context need to be stopped before calling this interface.
 *
 * @param kni
 *  The pointer to the context of an existant KNI interface.
 *
 * @return
 *  - 0 indicates success.
 *  - negative value indicates failure.
 */
extern int rte_kni_release(struct rte_kni *kni);

/**
 * It is used to handle the request mbufs sent from kernel space. 
 * Then analyzes it and calls the specific actions for the specific requests.
 * Finally constructs the response mbuf and puts it back to the resp_q.
 *
 * @param kni
 *  The pointer to the context of an existant KNI interface.
 *
 * @return
 *  - 0 
 *  - negative value indicates failure.
 */
extern int rte_kni_handle_request(struct rte_kni *kni);

/**
 * Retrieve a burst of packets from a KNI interface. The retrieved packets are
 * stored in rte_mbuf structures whose pointers are supplied in the array of
 * mbufs, and the maximum number is indicated by num. It handles the freeing of
 * the mbufs in the free queue of KNI interface.
 *
 * @param kni
 *  The KNI interface context.
 * @param mbufs
 *  The array to store the pointers of mbufs.
 * @param num
 *  The maximum number per burst.
 *
 * @return
 *  The actual number of packets retrieved.
 */
extern unsigned rte_kni_rx_burst(struct rte_kni *kni,
		struct rte_mbuf **mbufs, unsigned num);

/**
 * Send a burst of packets to a KNI interface. The packets to be sent out are
 * stored in rte_mbuf structures whose pointers are supplied in the array of
 * mbufs, and the maximum number is indicated by num. It handles allocating
 * the mbufs for KNI interface alloc queue.
 *
 * @param kni
 *  The KNI interface context.
 * @param mbufs
 *  The array to store the pointers of mbufs.
 * @param num
 *  The maximum number per burst.
 *
 * @return
 *  The actual number of packets sent.
 */
extern unsigned rte_kni_tx_burst(struct rte_kni *kni,
		struct rte_mbuf **mbufs, unsigned num);

/**
 * Get the port id from KNI interface.
 *
 * Note: It is deprecated and just for backward compatibility.
 *
 * @param kni
 *  The KNI interface context.
 *
 * @return
 *  On success: The port id.
 *  On failure: ~0x0
 */
extern uint8_t rte_kni_get_port_id(struct rte_kni *kni) \
				__attribute__ ((deprecated));

/**
 * Get the KNI context of its name.
 *
 * @param name
 *  pointer to the KNI device name.
 *
 * @return
 *  On success: Pointer to KNI interface.
 *  On failure: NULL.
 */
extern struct rte_kni *rte_kni_get(const char *name);

/**
 * Get the KNI context of the specific port.
 *
 * Note: It is deprecated and just for backward compatibility.
 *
 * @param port_id
 *  the port id.
 *
 * @return 
 *  On success: Pointer to KNI interface.
 *  On failure: NULL
 */
extern struct rte_kni *rte_kni_info_get(uint8_t port_id) \
				__attribute__ ((deprecated));

/**
 * Register KNI request handling for a specified port,and it can
 * be called by master process or slave process.
 *
 * @param kni 
 *  pointer to struct rte_kni. 
 * @param ops 
 *  ponter to struct rte_kni_ops.
 *
 * @return
 *  On success: 0
 *  On failure: -1
 */
extern int rte_kni_register_handlers(struct rte_kni *kni,
			struct rte_kni_ops *ops);

/**
 *  Unregister KNI request handling for a specified port.
 * 
 *  @param kni 
 *   pointer to struct rte_kni. 
 *
 *  @return
 *   On success: 0
 *   On failure: -1
 */
extern int rte_kni_unregister_handlers(struct rte_kni *kni);

#ifdef __cplusplus
}
#endif

#endif /* _RTE_KNI_H_ */