]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
4 | * Copyright(c) 2010-2014 Intel Corporation. All rights reserved. | |
5 | * All rights reserved. | |
6 | * | |
7 | * Redistribution and use in source and binary forms, with or without | |
8 | * modification, are permitted provided that the following conditions | |
9 | * are met: | |
10 | * | |
11 | * * Redistributions of source code must retain the above copyright | |
12 | * notice, this list of conditions and the following disclaimer. | |
13 | * * Redistributions in binary form must reproduce the above copyright | |
14 | * notice, this list of conditions and the following disclaimer in | |
15 | * the documentation and/or other materials provided with the | |
16 | * distribution. | |
17 | * * Neither the name of Intel Corporation nor the names of its | |
18 | * contributors may be used to endorse or promote products derived | |
19 | * from this software without specific prior written permission. | |
20 | * | |
21 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
22 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
23 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
24 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
25 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
26 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
27 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
28 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
29 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
30 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
31 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
32 | */ | |
33 | ||
34 | #ifndef _RTE_KNI_H_ | |
35 | #define _RTE_KNI_H_ | |
36 | ||
37 | /** | |
38 | * @file | |
39 | * RTE KNI | |
40 | * | |
41 | * The KNI library provides the ability to create and destroy kernel NIC | |
42 | * interfaces that may be used by the RTE application to receive/transmit | |
43 | * packets from/to Linux kernel net interfaces. | |
44 | * | |
45 | * This library provides two APIs to burst receive packets from KNI interfaces, | |
46 | * and burst transmit packets to KNI interfaces. | |
47 | */ | |
48 | ||
49 | #include <rte_pci.h> | |
50 | #include <rte_memory.h> | |
51 | #include <rte_mempool.h> | |
52 | ||
53 | #include <exec-env/rte_kni_common.h> | |
54 | ||
55 | #ifdef __cplusplus | |
56 | extern "C" { | |
57 | #endif | |
58 | ||
59 | struct rte_kni; | |
60 | struct rte_mbuf; | |
61 | ||
62 | /** | |
63 | * Structure which has the function pointers for KNI interface. | |
64 | */ | |
65 | struct rte_kni_ops { | |
66 | uint8_t port_id; /* Port ID */ | |
67 | ||
68 | /* Pointer to function of changing MTU */ | |
69 | int (*change_mtu)(uint8_t port_id, unsigned new_mtu); | |
70 | ||
71 | /* Pointer to function of configuring network interface */ | |
72 | int (*config_network_if)(uint8_t port_id, uint8_t if_up); | |
73 | }; | |
74 | ||
75 | /** | |
76 | * Structure for configuring KNI device. | |
77 | */ | |
78 | struct rte_kni_conf { | |
79 | /* | |
80 | * KNI name which will be used in relevant network device. | |
81 | * Let the name as short as possible, as it will be part of | |
82 | * memzone name. | |
83 | */ | |
84 | char name[RTE_KNI_NAMESIZE]; | |
85 | uint32_t core_id; /* Core ID to bind kernel thread on */ | |
86 | uint16_t group_id; /* Group ID */ | |
87 | unsigned mbuf_size; /* mbuf size */ | |
88 | struct rte_pci_addr addr; | |
89 | struct rte_pci_id id; | |
90 | ||
91 | __extension__ | |
92 | uint8_t force_bind : 1; /* Flag to bind kernel thread */ | |
93 | }; | |
94 | ||
95 | /** | |
96 | * Initialize and preallocate KNI subsystem | |
97 | * | |
98 | * This function is to be executed on the MASTER lcore only, after EAL | |
99 | * initialization and before any KNI interface is attempted to be | |
100 | * allocated | |
101 | * | |
102 | * @param max_kni_ifaces | |
103 | * The maximum number of KNI interfaces that can coexist concurrently | |
104 | */ | |
105 | void rte_kni_init(unsigned int max_kni_ifaces); | |
106 | ||
107 | ||
108 | /** | |
109 | * Allocate KNI interface according to the port id, mbuf size, mbuf pool, | |
110 | * configurations and callbacks for kernel requests.The KNI interface created | |
111 | * in the kernel space is the net interface the traditional Linux application | |
112 | * talking to. | |
113 | * | |
114 | * The rte_kni_alloc shall not be called before rte_kni_init() has been | |
115 | * called. rte_kni_alloc is thread safe. | |
116 | * | |
117 | * The mempool should have capacity of more than "2 x KNI_FIFO_COUNT_MAX" | |
118 | * elements for each KNI interface allocated. | |
119 | * | |
120 | * @param pktmbuf_pool | |
121 | * The mempool for allocting mbufs for packets. | |
122 | * @param conf | |
123 | * The pointer to the configurations of the KNI device. | |
124 | * @param ops | |
125 | * The pointer to the callbacks for the KNI kernel requests. | |
126 | * | |
127 | * @return | |
128 | * - The pointer to the context of a KNI interface. | |
129 | * - NULL indicate error. | |
130 | */ | |
131 | struct rte_kni *rte_kni_alloc(struct rte_mempool *pktmbuf_pool, | |
132 | const struct rte_kni_conf *conf, struct rte_kni_ops *ops); | |
133 | ||
134 | /** | |
135 | * Release KNI interface according to the context. It will also release the | |
136 | * paired KNI interface in kernel space. All processing on the specific KNI | |
137 | * context need to be stopped before calling this interface. | |
138 | * | |
139 | * rte_kni_release is thread safe. | |
140 | * | |
141 | * @param kni | |
142 | * The pointer to the context of an existent KNI interface. | |
143 | * | |
144 | * @return | |
145 | * - 0 indicates success. | |
146 | * - negative value indicates failure. | |
147 | */ | |
148 | int rte_kni_release(struct rte_kni *kni); | |
149 | ||
150 | /** | |
151 | * It is used to handle the request mbufs sent from kernel space. | |
152 | * Then analyzes it and calls the specific actions for the specific requests. | |
153 | * Finally constructs the response mbuf and puts it back to the resp_q. | |
154 | * | |
155 | * @param kni | |
156 | * The pointer to the context of an existent KNI interface. | |
157 | * | |
158 | * @return | |
159 | * - 0 | |
160 | * - negative value indicates failure. | |
161 | */ | |
162 | int rte_kni_handle_request(struct rte_kni *kni); | |
163 | ||
164 | /** | |
165 | * Retrieve a burst of packets from a KNI interface. The retrieved packets are | |
166 | * stored in rte_mbuf structures whose pointers are supplied in the array of | |
167 | * mbufs, and the maximum number is indicated by num. It handles allocating | |
168 | * the mbufs for KNI interface alloc queue. | |
169 | * | |
170 | * @param kni | |
171 | * The KNI interface context. | |
172 | * @param mbufs | |
173 | * The array to store the pointers of mbufs. | |
174 | * @param num | |
175 | * The maximum number per burst. | |
176 | * | |
177 | * @return | |
178 | * The actual number of packets retrieved. | |
179 | */ | |
180 | unsigned rte_kni_rx_burst(struct rte_kni *kni, struct rte_mbuf **mbufs, | |
181 | unsigned num); | |
182 | ||
183 | /** | |
184 | * Send a burst of packets to a KNI interface. The packets to be sent out are | |
185 | * stored in rte_mbuf structures whose pointers are supplied in the array of | |
186 | * mbufs, and the maximum number is indicated by num. It handles the freeing of | |
187 | * the mbufs in the free queue of KNI interface. | |
188 | * | |
189 | * @param kni | |
190 | * The KNI interface context. | |
191 | * @param mbufs | |
192 | * The array to store the pointers of mbufs. | |
193 | * @param num | |
194 | * The maximum number per burst. | |
195 | * | |
196 | * @return | |
197 | * The actual number of packets sent. | |
198 | */ | |
199 | unsigned rte_kni_tx_burst(struct rte_kni *kni, struct rte_mbuf **mbufs, | |
200 | unsigned num); | |
201 | ||
202 | /** | |
203 | * Get the KNI context of its name. | |
204 | * | |
205 | * @param name | |
206 | * pointer to the KNI device name. | |
207 | * | |
208 | * @return | |
209 | * On success: Pointer to KNI interface. | |
210 | * On failure: NULL. | |
211 | */ | |
212 | struct rte_kni *rte_kni_get(const char *name); | |
213 | ||
214 | /** | |
215 | * Get the name given to a KNI device | |
216 | * | |
217 | * @param kni | |
218 | * The KNI instance to query | |
219 | * @return | |
220 | * The pointer to the KNI name | |
221 | */ | |
222 | const char *rte_kni_get_name(const struct rte_kni *kni); | |
223 | ||
224 | /** | |
225 | * Register KNI request handling for a specified port,and it can | |
226 | * be called by master process or slave process. | |
227 | * | |
228 | * @param kni | |
229 | * pointer to struct rte_kni. | |
230 | * @param ops | |
231 | * ponter to struct rte_kni_ops. | |
232 | * | |
233 | * @return | |
234 | * On success: 0 | |
235 | * On failure: -1 | |
236 | */ | |
237 | int rte_kni_register_handlers(struct rte_kni *kni, struct rte_kni_ops *ops); | |
238 | ||
239 | /** | |
240 | * Unregister KNI request handling for a specified port. | |
241 | * | |
242 | * @param kni | |
243 | * pointer to struct rte_kni. | |
244 | * | |
245 | * @return | |
246 | * On success: 0 | |
247 | * On failure: -1 | |
248 | */ | |
249 | int rte_kni_unregister_handlers(struct rte_kni *kni); | |
250 | ||
251 | /** | |
252 | * Close KNI device. | |
253 | */ | |
254 | void rte_kni_close(void); | |
255 | ||
256 | #ifdef __cplusplus | |
257 | } | |
258 | #endif | |
259 | ||
260 | #endif /* _RTE_KNI_H_ */ |