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 main 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 primary process or secondary 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_ */ 271