e3a2547f32462bc78890ca503888a92e762aa0cb
[dpdk.git] / lib / librte_kni / rte_kni.h
1 /*-
2  *   BSD LICENSE
3  * 
4  *   Copyright(c) 2010-2013 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 provide two APIs to burst receive packets from KNI interfaces,
46  * and burst transmit packets to KNI interfaces.
47  */
48
49 #include <rte_mbuf.h>
50
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54
55 struct rte_kni;
56
57 /**
58  * Structure which has the function pointers for KNI interface.
59  */
60 struct rte_kni_ops {
61         /* Pointer to function of changing MTU */
62         int (*change_mtu)(uint8_t port_id, unsigned new_mtu);
63
64         /* Pointer to function of configuring network interface */
65         int (*config_network_if)(uint8_t port_id, uint8_t if_up);
66 };
67
68 /**
69  * Create kni interface according to the port id. It will create a paired KNI
70  * interface in the kernel space for each NIC port. The KNI interface created
71  * in the kernel space is the net interface the traditional Linux application
72  * talking to.
73  *
74  * @param port_id
75  *  The port id.
76  * @param pktmbuf_pool
77  *  The mempool for allocting mbufs for packets.
78  * @param mbuf_size
79  *  The mbuf size to store a packet.
80  *
81  * @return
82  *  - The pointer to the context of a KNI interface.
83  *  - NULL indicate error.
84  */
85 extern struct rte_kni *rte_kni_create(uint8_t port_id, unsigned mbuf_size,
86                 struct rte_mempool *pktmbuf_pool, struct rte_kni_ops *ops);
87
88 /**
89  * Release KNI interface according to the context. It will also release the
90  * paired KNI interface in kernel space. All processing on the specific KNI
91  * context need to be stopped before calling this interface.
92  *
93  * @param kni
94  *  The pointer to the context of an existant KNI interface.
95  *
96  * @return
97  *  - 0 indicates success.
98  *  - negative value indicates failure.
99  */
100 extern int rte_kni_release(struct rte_kni *kni);
101
102 /**
103  * It is used to handle the request mbufs sent from kernel space. 
104  * Then analyzes it and calls the specific actions for the specific requests.
105  * Finally constructs the response mbuf and puts it back to the resp_q.
106  *
107  * @param kni
108  *  The pointer to the context of an existant KNI interface.
109  *
110  * @return
111  *  - 0 
112  *  - negative value indicates failure.
113  */
114 extern int rte_kni_handle_request(struct rte_kni *kni);
115
116 /**
117  * Retrieve a burst of packets from a KNI interface. The retrieved packets are
118  * stored in rte_mbuf structures whose pointers are supplied in the array of
119  * mbufs, and the maximum number is indicated by num. It handles the freeing of
120  * the mbufs in the free queue of KNI interface.
121  *
122  * @param kni
123  *  The KNI interface context.
124  * @param mbufs
125  *  The array to store the pointers of mbufs.
126  * @param num
127  *  The maximum number per burst.
128  *
129  * @return
130  *  The actual number of packets retrieved.
131  */
132 extern unsigned rte_kni_rx_burst(struct rte_kni *kni,
133                 struct rte_mbuf **mbufs, unsigned num);
134
135 /**
136  * Send a burst of packets to a KNI interface. The packets to be sent out are
137  * stored in rte_mbuf structures whose pointers are supplied in the array of
138  * mbufs, and the maximum number is indicated by num. It handles allocating
139  * the mbufs for KNI interface alloc queue.
140  *
141  * @param kni
142  *  The KNI interface context.
143  * @param mbufs
144  *  The array to store the pointers of mbufs.
145  * @param num
146  *  The maximum number per burst.
147  *
148  * @return
149  *  The actual number of packets sent.
150  */
151 extern unsigned rte_kni_tx_burst(struct rte_kni *kni,
152                 struct rte_mbuf **mbufs, unsigned num);
153
154 /**
155  * Get the port id from KNI interface.
156  *
157  * @param kni
158  *  The KNI interface context.
159  *
160  * @return
161  *  On success: The port id.
162  *  On failure: ~0x0
163  */
164 extern uint8_t rte_kni_get_port_id(struct rte_kni *kni);
165
166 /**
167  * Get the KNI context of the specific port.
168  *
169  * @param port_id
170  *  the port id.
171  *
172  * @return 
173  *  On success: Pointer to KNI interface.
174  *  On failure: NULL
175  */
176 extern struct rte_kni * rte_kni_info_get(uint8_t port_id);
177
178 /**
179  * Register KNI request handling for a specified port,and it can
180  * be called by master process or slave process.
181  *
182  * @param kni 
183  *  pointer to struct rte_kni. 
184  * @param ops 
185  *  ponter to struct rte_kni_ops.
186  *
187  * @return
188  *  On success: 0
189  *  On failure: -1
190  */
191 extern int rte_kni_register_handlers(struct rte_kni *kni,
192                         struct rte_kni_ops *ops);
193
194 /**
195  *  Unregister KNI request handling for a specified port.
196  * 
197  *  @param kni 
198  *   pointer to struct rte_kni. 
199  *
200  *  @return
201  *   On success: 0
202  *   On failure: -1
203  */
204 extern int rte_kni_unregister_handlers(struct rte_kni *kni);
205
206 #ifdef __cplusplus
207 }
208 #endif
209
210 #endif /* _RTE_KNI_H_ */
211