net/bnxt: fix mark id update to mbuf
[dpdk.git] / lib / librte_kni / rte_kni.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2010-2014 Intel Corporation
3  */
4
5 #ifndef _RTE_KNI_H_
6 #define _RTE_KNI_H_
7
8 /**
9  * @file
10  * RTE KNI
11  *
12  * The KNI library provides the ability to create and destroy kernel NIC
13  * interfaces that may be used by the RTE application to receive/transmit
14  * packets from/to Linux kernel net interfaces.
15  *
16  * This library provides two APIs to burst receive packets from KNI interfaces,
17  * and burst transmit packets to KNI interfaces.
18  */
19
20 #include <rte_pci.h>
21 #include <rte_memory.h>
22 #include <rte_mempool.h>
23 #include <rte_ether.h>
24
25 #include <rte_kni_common.h>
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 struct rte_kni;
32 struct rte_mbuf;
33
34 /**
35  * Structure which has the function pointers for KNI interface.
36  */
37 struct rte_kni_ops {
38         uint16_t port_id; /* Port ID */
39
40         /* Pointer to function of changing MTU */
41         int (*change_mtu)(uint16_t port_id, unsigned int new_mtu);
42
43         /* Pointer to function of configuring network interface */
44         int (*config_network_if)(uint16_t port_id, uint8_t if_up);
45
46         /* Pointer to function of configuring mac address */
47         int (*config_mac_address)(uint16_t port_id, uint8_t mac_addr[]);
48
49         /* Pointer to function of configuring promiscuous mode */
50         int (*config_promiscusity)(uint16_t port_id, uint8_t to_on);
51
52         /* Pointer to function of configuring allmulticast mode */
53         int (*config_allmulticast)(uint16_t port_id, uint8_t to_on);
54 };
55
56 /**
57  * Structure for configuring KNI device.
58  */
59 struct rte_kni_conf {
60         /*
61          * KNI name which will be used in relevant network device.
62          * Let the name as short as possible, as it will be part of
63          * memzone name.
64          */
65         char name[RTE_KNI_NAMESIZE];
66         uint32_t core_id;   /* Core ID to bind kernel thread on */
67         uint16_t group_id;  /* Group ID */
68         unsigned mbuf_size; /* mbuf size */
69         struct rte_pci_addr addr; /* depreciated */
70         struct rte_pci_id id; /* depreciated */
71
72         __extension__
73         uint8_t force_bind : 1; /* Flag to bind kernel thread */
74         uint8_t mac_addr[RTE_ETHER_ADDR_LEN]; /* MAC address assigned to KNI */
75         uint16_t mtu;
76         uint16_t min_mtu;
77         uint16_t max_mtu;
78 };
79
80 /**
81  * Initialize and preallocate KNI subsystem
82  *
83  * This function is to be executed on the MASTER lcore only, after EAL
84  * initialization and before any KNI interface is attempted to be
85  * allocated
86  *
87  * @param max_kni_ifaces
88  *  The maximum number of KNI interfaces that can coexist concurrently
89  *
90  * @return
91  *  - 0 indicates success.
92  *  - negative value indicates failure.
93  */
94 int rte_kni_init(unsigned int max_kni_ifaces);
95
96
97 /**
98  * Allocate KNI interface according to the port id, mbuf size, mbuf pool,
99  * configurations and callbacks for kernel requests.The KNI interface created
100  * in the kernel space is the net interface the traditional Linux application
101  * talking to.
102  *
103  * The rte_kni_alloc shall not be called before rte_kni_init() has been
104  * called. rte_kni_alloc is thread safe.
105  *
106  * The mempool should have capacity of more than "2 x KNI_FIFO_COUNT_MAX"
107  * elements for each KNI interface allocated.
108  *
109  * @param pktmbuf_pool
110  *  The mempool for allocating mbufs for packets.
111  * @param conf
112  *  The pointer to the configurations of the KNI device.
113  * @param ops
114  *  The pointer to the callbacks for the KNI kernel requests.
115  *
116  * @return
117  *  - The pointer to the context of a KNI interface.
118  *  - NULL indicate error.
119  */
120 struct rte_kni *rte_kni_alloc(struct rte_mempool *pktmbuf_pool,
121                 const struct rte_kni_conf *conf, struct rte_kni_ops *ops);
122
123 /**
124  * Release KNI interface according to the context. It will also release the
125  * paired KNI interface in kernel space. All processing on the specific KNI
126  * context need to be stopped before calling this interface.
127  *
128  * rte_kni_release is thread safe.
129  *
130  * @param kni
131  *  The pointer to the context of an existent KNI interface.
132  *
133  * @return
134  *  - 0 indicates success.
135  *  - negative value indicates failure.
136  */
137 int rte_kni_release(struct rte_kni *kni);
138
139 /**
140  * It is used to handle the request mbufs sent from kernel space.
141  * Then analyzes it and calls the specific actions for the specific requests.
142  * Finally constructs the response mbuf and puts it back to the resp_q.
143  *
144  * @param kni
145  *  The pointer to the context of an existent KNI interface.
146  *
147  * @return
148  *  - 0
149  *  - negative value indicates failure.
150  */
151 int rte_kni_handle_request(struct rte_kni *kni);
152
153 /**
154  * Retrieve a burst of packets from a KNI interface. The retrieved packets are
155  * stored in rte_mbuf structures whose pointers are supplied in the array of
156  * mbufs, and the maximum number is indicated by num. It handles allocating
157  * the mbufs for KNI interface alloc queue.
158  *
159  * @param kni
160  *  The KNI interface context.
161  * @param mbufs
162  *  The array to store the pointers of mbufs.
163  * @param num
164  *  The maximum number per burst.
165  *
166  * @return
167  *  The actual number of packets retrieved.
168  */
169 unsigned rte_kni_rx_burst(struct rte_kni *kni, struct rte_mbuf **mbufs,
170                 unsigned num);
171
172 /**
173  * Send a burst of packets to a KNI interface. The packets to be sent out are
174  * stored in rte_mbuf structures whose pointers are supplied in the array of
175  * mbufs, and the maximum number is indicated by num. It handles the freeing of
176  * the mbufs in the free queue of KNI interface.
177  *
178  * @param kni
179  *  The KNI interface context.
180  * @param mbufs
181  *  The array to store the pointers of mbufs.
182  * @param num
183  *  The maximum number per burst.
184  *
185  * @return
186  *  The actual number of packets sent.
187  */
188 unsigned rte_kni_tx_burst(struct rte_kni *kni, struct rte_mbuf **mbufs,
189                 unsigned num);
190
191 /**
192  * Get the KNI context of its name.
193  *
194  * @param name
195  *  pointer to the KNI device name.
196  *
197  * @return
198  *  On success: Pointer to KNI interface.
199  *  On failure: NULL.
200  */
201 struct rte_kni *rte_kni_get(const char *name);
202
203 /**
204  * Get the name given to a KNI device
205  *
206  * @param kni
207  *   The KNI instance to query
208  * @return
209  *   The pointer to the KNI name
210  */
211 const char *rte_kni_get_name(const struct rte_kni *kni);
212
213 /**
214  * Register KNI request handling for a specified port,and it can
215  * be called by master process or slave process.
216  *
217  * @param kni
218  *  pointer to struct rte_kni.
219  * @param ops
220  *  pointer to struct rte_kni_ops.
221  *
222  * @return
223  *  On success: 0
224  *  On failure: -1
225  */
226 int rte_kni_register_handlers(struct rte_kni *kni, struct rte_kni_ops *ops);
227
228 /**
229  *  Unregister KNI request handling for a specified port.
230  *
231  *  @param kni
232  *   pointer to struct rte_kni.
233  *
234  *  @return
235  *   On success: 0
236  *   On failure: -1
237  */
238 int rte_kni_unregister_handlers(struct rte_kni *kni);
239
240 /**
241  * Update link carrier state for KNI port.
242  *
243  * Update the linkup/linkdown state of a KNI interface in the kernel.
244  *
245  * @param kni
246  *  pointer to struct rte_kni.
247  * @param linkup
248  *  New link state:
249  *  0 for linkdown.
250  *  > 0 for linkup.
251  *
252  * @return
253  *  On failure: -1
254  *  Previous link state == linkdown: 0
255  *  Previous link state == linkup: 1
256  */
257 __rte_experimental
258 int
259 rte_kni_update_link(struct rte_kni *kni, unsigned int linkup);
260
261 /**
262  *  Close KNI device.
263  */
264 void rte_kni_close(void);
265
266 #ifdef __cplusplus
267 }
268 #endif
269
270 #endif /* _RTE_KNI_H_ */