1/****************************************************************************** 2 * netif.h 3 * 4 * Unified network-device I/O interface for Xen guest OSes. 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 22 * DEALINGS IN THE SOFTWARE. 23 * 24 * Copyright (c) 2003-2004, Keir Fraser 25 */ 26 27#ifndef __XEN_PUBLIC_IO_NETIF_H__ 28#define __XEN_PUBLIC_IO_NETIF_H__ 29 30#include "ring.h" 31#include "../grant_table.h" 32 33/* 34 * Older implementation of Xen network frontend / backend has an 35 * implicit dependency on the MAX_SKB_FRAGS as the maximum number of 36 * ring slots a skb can use. Netfront / netback may not work as 37 * expected when frontend and backend have different MAX_SKB_FRAGS. 38 * 39 * A better approach is to add mechanism for netfront / netback to 40 * negotiate this value. However we cannot fix all possible 41 * frontends, so we need to define a value which states the minimum 42 * slots backend must support. 43 * 44 * The minimum value derives from older Linux kernel's MAX_SKB_FRAGS 45 * (18), which is proved to work with most frontends. Any new backend 46 * which doesn't negotiate with frontend should expect frontend to 47 * send a valid packet using slots up to this value. 48 */ 49#define XEN_NETIF_NR_SLOTS_MIN 18 50 51/* 52 * Notifications after enqueuing any type of message should be conditional on 53 * the appropriate req_event or rsp_event field in the shared ring. 54 * If the client sends notification for rx requests then it should specify 55 * feature 'feature-rx-notify' via xenbus. Otherwise the backend will assume 56 * that it cannot safely queue packets (as it may not be kicked to send them). 57 */ 58 59/* 60 * "feature-split-event-channels" is introduced to separate guest TX 61 * and RX notification. Backend either doesn't support this feature or 62 * advertises it via xenstore as 0 (disabled) or 1 (enabled). 63 * 64 * To make use of this feature, frontend should allocate two event 65 * channels for TX and RX, advertise them to backend as 66 * "event-channel-tx" and "event-channel-rx" respectively. If frontend 67 * doesn't want to use this feature, it just writes "event-channel" 68 * node as before. 69 */ 70 71/* 72 * Multiple transmit and receive queues: 73 * If supported, the backend will write the key "multi-queue-max-queues" to 74 * the directory for that vif, and set its value to the maximum supported 75 * number of queues. 76 * Frontends that are aware of this feature and wish to use it can write the 77 * key "multi-queue-num-queues", set to the number they wish to use, which 78 * must be greater than zero, and no more than the value reported by the backend 79 * in "multi-queue-max-queues". 80 * 81 * Queues replicate the shared rings and event channels. 82 * "feature-split-event-channels" may optionally be used when using 83 * multiple queues, but is not mandatory. 84 * 85 * Each queue consists of one shared ring pair, i.e. there must be the same 86 * number of tx and rx rings. 87 * 88 * For frontends requesting just one queue, the usual event-channel and 89 * ring-ref keys are written as before, simplifying the backend processing 90 * to avoid distinguishing between a frontend that doesn't understand the 91 * multi-queue feature, and one that does, but requested only one queue. 92 * 93 * Frontends requesting two or more queues must not write the toplevel 94 * event-channel (or event-channel-{tx,rx}) and {tx,rx}-ring-ref keys, 95 * instead writing those keys under sub-keys having the name "queue-N" where 96 * N is the integer ID of the queue for which those keys belong. Queues 97 * are indexed from zero. For example, a frontend with two queues and split 98 * event channels must write the following set of queue-related keys: 99 * 100 * /local/domain/1/device/vif/0/multi-queue-num-queues = "2" 101 * /local/domain/1/device/vif/0/queue-0 = "" 102 * /local/domain/1/device/vif/0/queue-0/tx-ring-ref = "<ring-ref-tx0>" 103 * /local/domain/1/device/vif/0/queue-0/rx-ring-ref = "<ring-ref-rx0>" 104 * /local/domain/1/device/vif/0/queue-0/event-channel-tx = "<evtchn-tx0>" 105 * /local/domain/1/device/vif/0/queue-0/event-channel-rx = "<evtchn-rx0>" 106 * /local/domain/1/device/vif/0/queue-1 = "" 107 * /local/domain/1/device/vif/0/queue-1/tx-ring-ref = "<ring-ref-tx1>" 108 * /local/domain/1/device/vif/0/queue-1/rx-ring-ref = "<ring-ref-rx1" 109 * /local/domain/1/device/vif/0/queue-1/event-channel-tx = "<evtchn-tx1>" 110 * /local/domain/1/device/vif/0/queue-1/event-channel-rx = "<evtchn-rx1>" 111 * 112 * If there is any inconsistency in the XenStore data, the backend may 113 * choose not to connect any queues, instead treating the request as an 114 * error. This includes scenarios where more (or fewer) queues were 115 * requested than the frontend provided details for. 116 * 117 * Mapping of packets to queues is considered to be a function of the 118 * transmitting system (backend or frontend) and is not negotiated 119 * between the two. Guests are free to transmit packets on any queue 120 * they choose, provided it has been set up correctly. Guests must be 121 * prepared to receive packets on any queue they have requested be set up. 122 */ 123 124/* 125 * "feature-no-csum-offload" should be used to turn IPv4 TCP/UDP checksum 126 * offload off or on. If it is missing then the feature is assumed to be on. 127 * "feature-ipv6-csum-offload" should be used to turn IPv6 TCP/UDP checksum 128 * offload on or off. If it is missing then the feature is assumed to be off. 129 */ 130 131/* 132 * "feature-gso-tcpv4" and "feature-gso-tcpv6" advertise the capability to 133 * handle large TCP packets (in IPv4 or IPv6 form respectively). Neither 134 * frontends nor backends are assumed to be capable unless the flags are 135 * present. 136 */ 137 138/* 139 * "feature-multicast-control" advertises the capability to filter ethernet 140 * multicast packets in the backend. To enable use of this capability the 141 * frontend must set "request-multicast-control" before moving into the 142 * connected state. 143 * 144 * If "request-multicast-control" is set then the backend transmit side should 145 * no longer flood multicast packets to the frontend, it should instead drop any 146 * multicast packet that does not match in a filter list. The list is 147 * amended by the frontend by sending dummy transmit requests containing 148 * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL} extra-info fragments as specified below. 149 * Once enabled by the frontend, the feature cannot be disabled except by 150 * closing and re-connecting to the backend. 151 */ 152 153/* 154 * This is the 'wire' format for packets: 155 * Request 1: netif_tx_request_t -- NETTXF_* (any flags) 156 * [Request 2: netif_extra_info_t] (only if request 1 has NETTXF_extra_info) 157 * [Request 3: netif_extra_info_t] (only if request 2 has XEN_NETIF_EXTRA_MORE) 158 * Request 4: netif_tx_request_t -- NETTXF_more_data 159 * Request 5: netif_tx_request_t -- NETTXF_more_data 160 * ... 161 * Request N: netif_tx_request_t -- 0 162 */ 163 164/* 165 * Guest transmit 166 * ============== 167 * 168 * Ring slot size is 12 octets, however not all request/response 169 * structs use the full size. 170 * 171 * tx request data (netif_tx_request_t) 172 * ------------------------------------ 173 * 174 * 0 1 2 3 4 5 6 7 octet 175 * +-----+-----+-----+-----+-----+-----+-----+-----+ 176 * | grant ref | offset | flags | 177 * +-----+-----+-----+-----+-----+-----+-----+-----+ 178 * | id | size | 179 * +-----+-----+-----+-----+ 180 * 181 * grant ref: Reference to buffer page. 182 * offset: Offset within buffer page. 183 * flags: NETTXF_*. 184 * id: request identifier, echoed in response. 185 * size: packet size in bytes. 186 * 187 * tx response (netif_tx_response_t) 188 * --------------------------------- 189 * 190 * 0 1 2 3 4 5 6 7 octet 191 * +-----+-----+-----+-----+-----+-----+-----+-----+ 192 * | id | status | unused | 193 * +-----+-----+-----+-----+-----+-----+-----+-----+ 194 * | unused | 195 * +-----+-----+-----+-----+ 196 * 197 * id: reflects id in transmit request 198 * status: NETIF_RSP_* 199 * 200 * Guest receive 201 * ============= 202 * 203 * Ring slot size is 8 octets. 204 * 205 * rx request (netif_rx_request_t) 206 * ------------------------------- 207 * 208 * 0 1 2 3 4 5 6 7 octet 209 * +-----+-----+-----+-----+-----+-----+-----+-----+ 210 * | id | pad | gref | 211 * +-----+-----+-----+-----+-----+-----+-----+-----+ 212 * 213 * id: request identifier, echoed in response. 214 * gref: reference to incoming granted frame. 215 * 216 * rx response (netif_rx_response_t) 217 * --------------------------------- 218 * 219 * 0 1 2 3 4 5 6 7 octet 220 * +-----+-----+-----+-----+-----+-----+-----+-----+ 221 * | id | offset | flags | status | 222 * +-----+-----+-----+-----+-----+-----+-----+-----+ 223 * 224 * id: reflects id in receive request 225 * offset: offset in page of start of received packet 226 * flags: NETRXF_* 227 * status: -ve: NETIF_RSP_*; +ve: Rx'ed pkt size. 228 * 229 * Extra Info 230 * ========== 231 * 232 * Can be present if initial request has NET{T,R}XF_extra_info, or 233 * previous extra request has XEN_NETIF_EXTRA_MORE. 234 * 235 * The struct therefore needs to fit into either a tx or rx slot and 236 * is therefore limited to 8 octets. 237 * 238 * extra info (netif_extra_info_t) 239 * ------------------------------- 240 * 241 * General format: 242 * 243 * 0 1 2 3 4 5 6 7 octet 244 * +-----+-----+-----+-----+-----+-----+-----+-----+ 245 * |type |flags| type specfic data | 246 * +-----+-----+-----+-----+-----+-----+-----+-----+ 247 * | padding for tx | 248 * +-----+-----+-----+-----+ 249 * 250 * type: XEN_NETIF_EXTRA_TYPE_* 251 * flags: XEN_NETIF_EXTRA_FLAG_* 252 * padding for tx: present only in the tx case due to 8 octet limit 253 * from rx case. Not shown in type specific entries below. 254 * 255 * XEN_NETIF_EXTRA_TYPE_GSO: 256 * 257 * 0 1 2 3 4 5 6 7 octet 258 * +-----+-----+-----+-----+-----+-----+-----+-----+ 259 * |type |flags| size |type | pad | features | 260 * +-----+-----+-----+-----+-----+-----+-----+-----+ 261 * 262 * type: Must be XEN_NETIF_EXTRA_TYPE_GSO 263 * flags: XEN_NETIF_EXTRA_FLAG_* 264 * size: Maximum payload size of each segment. 265 * type: XEN_NETIF_GSO_TYPE_* 266 * features: EN_NETIF_GSO_FEAT_* 267 * 268 * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}: 269 * 270 * 0 1 2 3 4 5 6 7 octet 271 * +-----+-----+-----+-----+-----+-----+-----+-----+ 272 * |type |flags| addr | 273 * +-----+-----+-----+-----+-----+-----+-----+-----+ 274 * 275 * type: Must be XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL} 276 * flags: XEN_NETIF_EXTRA_FLAG_* 277 * addr: address to add/remove 278 */ 279 280/* Protocol checksum field is blank in the packet (hardware offload)? */ 281#define _NETTXF_csum_blank (0) 282#define NETTXF_csum_blank (1U<<_NETTXF_csum_blank) 283 284/* Packet data has been validated against protocol checksum. */ 285#define _NETTXF_data_validated (1) 286#define NETTXF_data_validated (1U<<_NETTXF_data_validated) 287 288/* Packet continues in the next request descriptor. */ 289#define _NETTXF_more_data (2) 290#define NETTXF_more_data (1U<<_NETTXF_more_data) 291 292/* Packet to be followed by extra descriptor(s). */ 293#define _NETTXF_extra_info (3) 294#define NETTXF_extra_info (1U<<_NETTXF_extra_info) 295 296#define XEN_NETIF_MAX_TX_SIZE 0xFFFF 297struct netif_tx_request { 298 grant_ref_t gref; /* Reference to buffer page */ 299 uint16_t offset; /* Offset within buffer page */ 300 uint16_t flags; /* NETTXF_* */ 301 uint16_t id; /* Echoed in response message. */ 302 uint16_t size; /* Packet size in bytes. */ 303}; 304typedef struct netif_tx_request netif_tx_request_t; 305 306/* Types of netif_extra_info descriptors. */ 307#define XEN_NETIF_EXTRA_TYPE_NONE (0) /* Never used - invalid */ 308#define XEN_NETIF_EXTRA_TYPE_GSO (1) /* u.gso */ 309#define XEN_NETIF_EXTRA_TYPE_MCAST_ADD (2) /* u.mcast */ 310#define XEN_NETIF_EXTRA_TYPE_MCAST_DEL (3) /* u.mcast */ 311#define XEN_NETIF_EXTRA_TYPE_MAX (4) 312 313/* netif_extra_info_t flags. */ 314#define _XEN_NETIF_EXTRA_FLAG_MORE (0) 315#define XEN_NETIF_EXTRA_FLAG_MORE (1U<<_XEN_NETIF_EXTRA_FLAG_MORE) 316 317/* GSO types */ 318#define XEN_NETIF_GSO_TYPE_NONE (0) 319#define XEN_NETIF_GSO_TYPE_TCPV4 (1) 320#define XEN_NETIF_GSO_TYPE_TCPV6 (2) 321 322/* 323 * This structure needs to fit within both netif_tx_request_t and 324 * netif_rx_response_t for compatibility. 325 */ 326struct netif_extra_info { 327 uint8_t type; /* XEN_NETIF_EXTRA_TYPE_* */ 328 uint8_t flags; /* XEN_NETIF_EXTRA_FLAG_* */ 329 330 union { 331 /* 332 * XEN_NETIF_EXTRA_TYPE_GSO: 333 */ 334 struct { 335 /* 336 * Maximum payload size of each segment. For example, for TCP this 337 * is just the path MSS. 338 */ 339 uint16_t size; 340 341 /* 342 * GSO type. This determines the protocol of the packet and any 343 * extra features required to segment the packet properly. 344 */ 345 uint8_t type; /* XEN_NETIF_GSO_TYPE_* */ 346 347 /* Future expansion. */ 348 uint8_t pad; 349 350 /* 351 * GSO features. This specifies any extra GSO features required 352 * to process this packet, such as ECN support for TCPv4. 353 */ 354 uint16_t features; /* XEN_NETIF_GSO_FEAT_* */ 355 } gso; 356 357 /* 358 * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}: 359 */ 360 struct { 361 uint8_t addr[6]; /* Address to add/remove. */ 362 } mcast; 363 364 uint16_t pad[3]; 365 } u; 366}; 367typedef struct netif_extra_info netif_extra_info_t; 368 369struct netif_tx_response { 370 uint16_t id; 371 int16_t status; /* NETIF_RSP_* */ 372}; 373typedef struct netif_tx_response netif_tx_response_t; 374 375struct netif_rx_request { 376 uint16_t id; /* Echoed in response message. */ 377 uint16_t pad; 378 grant_ref_t gref; /* Reference to incoming granted frame */ 379}; 380typedef struct netif_rx_request netif_rx_request_t; 381 382/* Packet data has been validated against protocol checksum. */ 383#define _NETRXF_data_validated (0) 384#define NETRXF_data_validated (1U<<_NETRXF_data_validated) 385 386/* Protocol checksum field is blank in the packet (hardware offload)? */ 387#define _NETRXF_csum_blank (1) 388#define NETRXF_csum_blank (1U<<_NETRXF_csum_blank) 389 390/* Packet continues in the next request descriptor. */ 391#define _NETRXF_more_data (2) 392#define NETRXF_more_data (1U<<_NETRXF_more_data) 393 394/* Packet to be followed by extra descriptor(s). */ 395#define _NETRXF_extra_info (3) 396#define NETRXF_extra_info (1U<<_NETRXF_extra_info) 397 398struct netif_rx_response { 399 uint16_t id; 400 uint16_t offset; /* Offset in page of start of received packet */ 401 uint16_t flags; /* NETRXF_* */ 402 int16_t status; /* -ve: NETIF_RSP_* ; +ve: Rx'ed pkt size. */ 403}; 404typedef struct netif_rx_response netif_rx_response_t; 405 406/* 407 * Generate netif ring structures and types. 408 */ 409 410DEFINE_RING_TYPES(netif_tx, struct netif_tx_request, struct netif_tx_response); 411DEFINE_RING_TYPES(netif_rx, struct netif_rx_request, struct netif_rx_response); 412 413#define NETIF_RSP_DROPPED -2 414#define NETIF_RSP_ERROR -1 415#define NETIF_RSP_OKAY 0 416/* No response: used for auxiliary requests (e.g., netif_extra_info_t). */ 417#define NETIF_RSP_NULL 1 418 419#endif 420 421/* 422 * Local variables: 423 * mode: C 424 * c-file-style: "BSD" 425 * c-basic-offset: 4 426 * tab-width: 4 427 * indent-tabs-mode: nil 428 * End: 429 */ 430