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