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" and "feature-dynamic-multicast-control" 140 * advertise the capability to filter ethernet multicast packets in the 141 * backend. If the frontend wishes to take advantage of this feature then 142 * it may set "request-multicast-control". If the backend only advertises 143 * "feature-multicast-control" then "request-multicast-control" must be set 144 * before the frontend moves into the connected state. The backend will 145 * sample the value on this state transition and any subsequent change in 146 * value will have no effect. However, if the backend also advertises 147 * "feature-dynamic-multicast-control" then "request-multicast-control" 148 * may be set by the frontend at any time. In this case, the backend will 149 * watch the value and re-sample on watch events. 150 * 151 * If the sampled value of "request-multicast-control" is set then the 152 * backend transmit side should no longer flood multicast packets to the 153 * frontend, it should instead drop any multicast packet that does not 154 * match in a filter list. 155 * The list is amended by the frontend by sending dummy transmit requests 156 * containing XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL} extra-info fragments as 157 * specified below. 158 * Note that the filter list may be amended even if the sampled value of 159 * "request-multicast-control" is not set, however the filter should only 160 * be applied if it is set. 161 */ 162 163 /* 164 * Control ring 165 * ============ 166 * 167 * Some features, such as hashing (detailed below), require a 168 * significant amount of out-of-band data to be passed from frontend to 169 * backend. Use of xenstore is not suitable for large quantities of data 170 * because of quota limitations and so a dedicated 'control ring' is used. 171 * The ability of the backend to use a control ring is advertised by 172 * setting: 173 * 174 * /local/domain/X/backend/<domid>/<vif>/feature-ctrl-ring = "1" 175 * 176 * The frontend provides a control ring to the backend by setting: 177 * 178 * /local/domain/<domid>/device/vif/<vif>/ctrl-ring-ref = <gref> 179 * /local/domain/<domid>/device/vif/<vif>/event-channel-ctrl = <port> 180 * 181 * where <gref> is the grant reference of the shared page used to 182 * implement the control ring and <port> is an event channel to be used 183 * as a mailbox interrupt. These keys must be set before the frontend 184 * moves into the connected state. 185 * 186 * The control ring uses a fixed request/response message size and is 187 * balanced (i.e. one request to one response), so operationally it is much 188 * the same as a transmit or receive ring. 189 * Note that there is no requirement that responses are issued in the same 190 * order as requests. 191 */ 192 193 /* 194 * Hash types 195 * ========== 196 * 197 * For the purposes of the definitions below, 'Packet[]' is an array of 198 * octets containing an IP packet without options, 'Array[X..Y]' means a 199 * sub-array of 'Array' containing bytes X thru Y inclusive, and '+' is 200 * used to indicate concatenation of arrays. 201 */ 202 203 /* 204 * A hash calculated over an IP version 4 header as follows: 205 * 206 * Buffer[0..8] = Packet[12..15] (source address) + 207 * Packet[16..19] (destination address) 208 * 209 * Result = Hash(Buffer, 8) 210 */ 211 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4 0 212 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4 \ 213 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4) 214 215 /* 216 * A hash calculated over an IP version 4 header and TCP header as 217 * follows: 218 * 219 * Buffer[0..12] = Packet[12..15] (source address) + 220 * Packet[16..19] (destination address) + 221 * Packet[20..21] (source port) + 222 * Packet[22..23] (destination port) 223 * 224 * Result = Hash(Buffer, 12) 225 */ 226 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP 1 227 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP \ 228 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP) 229 230 /* 231 * A hash calculated over an IP version 6 header as follows: 232 * 233 * Buffer[0..32] = Packet[8..23] (source address ) + 234 * Packet[24..39] (destination address) 235 * 236 * Result = Hash(Buffer, 32) 237 */ 238 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6 2 239 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6 \ 240 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6) 241 242 /* 243 * A hash calculated over an IP version 6 header and TCP header as 244 * follows: 245 * 246 * Buffer[0..36] = Packet[8..23] (source address) + 247 * Packet[24..39] (destination address) + 248 * Packet[40..41] (source port) + 249 * Packet[42..43] (destination port) 250 * 251 * Result = Hash(Buffer, 36) 252 */ 253 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP 3 254 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP \ 255 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP) 256 257 /* 258 * Hash algorithms 259 * =============== 260 */ 261 262 #define XEN_NETIF_CTRL_HASH_ALGORITHM_NONE 0 263 264 /* 265 * Toeplitz hash: 266 */ 267 268 #define XEN_NETIF_CTRL_HASH_ALGORITHM_TOEPLITZ 1 269 270 /* 271 * Control requests (struct xen_netif_ctrl_request) 272 * ================================================ 273 * 274 * All requests have the following format: 275 * 276 * 0 1 2 3 4 5 6 7 octet 277 * +-----+-----+-----+-----+-----+-----+-----+-----+ 278 * | id | type | data[0] | 279 * +-----+-----+-----+-----+-----+-----+-----+-----+ 280 * | data[1] | data[2] | 281 * +-----+-----+-----+-----+-----------------------+ 282 * 283 * id: the request identifier, echoed in response. 284 * type: the type of request (see below) 285 * data[]: any data associated with the request (determined by type) 286 */ 287 288 struct xen_netif_ctrl_request { 289 uint16_t id; 290 uint16_t type; 291 292 #define XEN_NETIF_CTRL_TYPE_INVALID 0 293 #define XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS 1 294 #define XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS 2 295 #define XEN_NETIF_CTRL_TYPE_SET_HASH_KEY 3 296 #define XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE 4 297 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE 5 298 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING 6 299 #define XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM 7 300 #define XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE 8 301 #define XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING 9 302 #define XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING 10 303 304 uint32_t data[3]; 305 }; 306 307 /* 308 * Control responses (struct xen_netif_ctrl_response) 309 * ================================================== 310 * 311 * All responses have the following format: 312 * 313 * 0 1 2 3 4 5 6 7 octet 314 * +-----+-----+-----+-----+-----+-----+-----+-----+ 315 * | id | type | status | 316 * +-----+-----+-----+-----+-----+-----+-----+-----+ 317 * | data | 318 * +-----+-----+-----+-----+ 319 * 320 * id: the corresponding request identifier 321 * type: the type of the corresponding request 322 * status: the status of request processing 323 * data: any data associated with the response (determined by type and 324 * status) 325 */ 326 327 struct xen_netif_ctrl_response { 328 uint16_t id; 329 uint16_t type; 330 uint32_t status; 331 332 #define XEN_NETIF_CTRL_STATUS_SUCCESS 0 333 #define XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED 1 334 #define XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER 2 335 #define XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW 3 336 337 uint32_t data; 338 }; 339 340 /* 341 * Static Grants (struct xen_netif_gref) 342 * ===================================== 343 * 344 * A frontend may provide a fixed set of grant references to be mapped on 345 * the backend. The message of type XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING 346 * prior its usage in the command ring allows for creation of these mappings. 347 * The backend will maintain a fixed amount of these mappings. 348 * 349 * XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE lets a frontend query how many 350 * of these mappings can be kept. 351 * 352 * Each entry in the XEN_NETIF_CTRL_TYPE_{ADD,DEL}_GREF_MAPPING input table has 353 * the following format: 354 * 355 * 0 1 2 3 4 5 6 7 octet 356 * +-----+-----+-----+-----+-----+-----+-----+-----+ 357 * | grant ref | flags | status | 358 * +-----+-----+-----+-----+-----+-----+-----+-----+ 359 * 360 * grant ref: grant reference (IN) 361 * flags: flags describing the control operation (IN) 362 * status: XEN_NETIF_CTRL_STATUS_* (OUT) 363 * 364 * 'status' is an output parameter which does not require to be set to zero 365 * prior to its usage in the corresponding control messages. 366 */ 367 368 struct xen_netif_gref { 369 grant_ref_t ref; 370 uint16_t flags; 371 372 #define _XEN_NETIF_CTRLF_GREF_readonly 0 373 #define XEN_NETIF_CTRLF_GREF_readonly (1U<<_XEN_NETIF_CTRLF_GREF_readonly) 374 375 uint16_t status; 376 }; 377 378 /* 379 * Control messages 380 * ================ 381 * 382 * XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM 383 * -------------------------------------- 384 * 385 * This is sent by the frontend to set the desired hash algorithm. 386 * 387 * Request: 388 * 389 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM 390 * data[0] = a XEN_NETIF_CTRL_HASH_ALGORITHM_* value 391 * data[1] = 0 392 * data[2] = 0 393 * 394 * Response: 395 * 396 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not 397 * supported 398 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - The algorithm is not 399 * supported 400 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 401 * 402 * NOTE: Setting data[0] to XEN_NETIF_CTRL_HASH_ALGORITHM_NONE disables 403 * hashing and the backend is free to choose how it steers packets 404 * to queues (which is the default behaviour). 405 * 406 * XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS 407 * ---------------------------------- 408 * 409 * This is sent by the frontend to query the types of hash supported by 410 * the backend. 411 * 412 * Request: 413 * 414 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS 415 * data[0] = 0 416 * data[1] = 0 417 * data[2] = 0 418 * 419 * Response: 420 * 421 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported 422 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 423 * data = supported hash types (if operation was successful) 424 * 425 * NOTE: A valid hash algorithm must be selected before this operation can 426 * succeed. 427 * 428 * XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS 429 * ---------------------------------- 430 * 431 * This is sent by the frontend to set the types of hash that the backend 432 * should calculate. (See above for hash type definitions). 433 * Note that the 'maximal' type of hash should always be chosen. For 434 * example, if the frontend sets both IPV4 and IPV4_TCP hash types then 435 * the latter hash type should be calculated for any TCP packet and the 436 * former only calculated for non-TCP packets. 437 * 438 * Request: 439 * 440 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS 441 * data[0] = bitwise OR of XEN_NETIF_CTRL_HASH_TYPE_* values 442 * data[1] = 0 443 * data[2] = 0 444 * 445 * Response: 446 * 447 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not 448 * supported 449 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - One or more flag 450 * value is invalid or 451 * unsupported 452 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 453 * data = 0 454 * 455 * NOTE: A valid hash algorithm must be selected before this operation can 456 * succeed. 457 * Also, setting data[0] to zero disables hashing and the backend 458 * is free to choose how it steers packets to queues. 459 * 460 * XEN_NETIF_CTRL_TYPE_SET_HASH_KEY 461 * -------------------------------- 462 * 463 * This is sent by the frontend to set the key of the hash if the algorithm 464 * requires it. (See hash algorithms above). 465 * 466 * Request: 467 * 468 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_KEY 469 * data[0] = grant reference of page containing the key (assumed to 470 * start at beginning of grant) 471 * data[1] = size of key in octets 472 * data[2] = 0 473 * 474 * Response: 475 * 476 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not 477 * supported 478 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Key size is invalid 479 * XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW - Key size is larger 480 * than the backend 481 * supports 482 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 483 * data = 0 484 * 485 * NOTE: Any key octets not specified are assumed to be zero (the key 486 * is assumed to be empty by default) and specifying a new key 487 * invalidates any previous key, hence specifying a key size of 488 * zero will clear the key (which ensures that the calculated hash 489 * will always be zero). 490 * The maximum size of key is algorithm and backend specific, but 491 * is also limited by the single grant reference. 492 * The grant reference may be read-only and must remain valid until 493 * the response has been processed. 494 * 495 * XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE 496 * ----------------------------------------- 497 * 498 * This is sent by the frontend to query the maximum size of mapping 499 * table supported by the backend. The size is specified in terms of 500 * table entries. 501 * 502 * Request: 503 * 504 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE 505 * data[0] = 0 506 * data[1] = 0 507 * data[2] = 0 508 * 509 * Response: 510 * 511 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported 512 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 513 * data = maximum number of entries allowed in the mapping table 514 * (if operation was successful) or zero if a mapping table is 515 * not supported (i.e. hash mapping is done only by modular 516 * arithmetic). 517 * 518 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE 519 * ------------------------------------- 520 * 521 * This is sent by the frontend to set the actual size of the mapping 522 * table to be used by the backend. The size is specified in terms of 523 * table entries. 524 * Any previous table is invalidated by this message and any new table 525 * is assumed to be zero filled. 526 * 527 * Request: 528 * 529 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE 530 * data[0] = number of entries in mapping table 531 * data[1] = 0 532 * data[2] = 0 533 * 534 * Response: 535 * 536 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not 537 * supported 538 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size is invalid 539 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 540 * data = 0 541 * 542 * NOTE: Setting data[0] to 0 means that hash mapping should be done 543 * using modular arithmetic. 544 * 545 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING 546 * ------------------------------------ 547 * 548 * This is sent by the frontend to set the content of the table mapping 549 * hash value to queue number. The backend should calculate the hash from 550 * the packet header, use it as an index into the table (modulo the size 551 * of the table) and then steer the packet to the queue number found at 552 * that index. 553 * 554 * Request: 555 * 556 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING 557 * data[0] = grant reference of page containing the mapping (sub-)table 558 * (assumed to start at beginning of grant) 559 * data[1] = size of (sub-)table in entries 560 * data[2] = offset, in entries, of sub-table within overall table 561 * 562 * Response: 563 * 564 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not 565 * supported 566 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size or content 567 * is invalid 568 * XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW - Table size is larger 569 * than the backend 570 * supports 571 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 572 * data = 0 573 * 574 * NOTE: The overall table has the following format: 575 * 576 * 0 1 2 3 4 5 6 7 octet 577 * +-----+-----+-----+-----+-----+-----+-----+-----+ 578 * | mapping[0] | mapping[1] | 579 * +-----+-----+-----+-----+-----+-----+-----+-----+ 580 * | . | 581 * | . | 582 * | . | 583 * +-----+-----+-----+-----+-----+-----+-----+-----+ 584 * | mapping[N-2] | mapping[N-1] | 585 * +-----+-----+-----+-----+-----+-----+-----+-----+ 586 * 587 * where N is specified by a XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE 588 * message and each mapping must specifies a queue between 0 and 589 * "multi-queue-num-queues" (see above). 590 * The backend may support a mapping table larger than can be 591 * mapped by a single grant reference. Thus sub-tables within a 592 * larger table can be individually set by sending multiple messages 593 * with differing offset values. Specifying a new sub-table does not 594 * invalidate any table data outside that range. 595 * The grant reference may be read-only and must remain valid until 596 * the response has been processed. 597 * 598 * XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE 599 * ----------------------------------------- 600 * 601 * This is sent by the frontend to fetch the number of grefs that can be kept 602 * mapped in the backend. 603 * 604 * Request: 605 * 606 * type = XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE 607 * data[0] = queue index (assumed 0 for single queue) 608 * data[1] = 0 609 * data[2] = 0 610 * 611 * Response: 612 * 613 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not 614 * supported 615 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - The queue index is 616 * out of range 617 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 618 * data = maximum number of entries allowed in the gref mapping table 619 * (if operation was successful) or zero if it is not supported. 620 * 621 * XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING 622 * ------------------------------------ 623 * 624 * This is sent by the frontend for backend to map a list of grant 625 * references. 626 * 627 * Request: 628 * 629 * type = XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING 630 * data[0] = queue index 631 * data[1] = grant reference of page containing the mapping list 632 * (r/w and assumed to start at beginning of page) 633 * data[2] = size of list in entries 634 * 635 * Response: 636 * 637 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not 638 * supported 639 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Operation failed 640 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 641 * 642 * NOTE: Each entry in the input table has the format outlined 643 * in struct xen_netif_gref. 644 * Contrary to XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING, the struct 645 * xen_netif_gref 'status' field is not used and therefore the response 646 * 'status' determines the success of this operation. In case of 647 * failure none of grants mappings get added in the backend. 648 * 649 * XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING 650 * ------------------------------------ 651 * 652 * This is sent by the frontend for backend to unmap a list of grant 653 * references. 654 * 655 * Request: 656 * 657 * type = XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING 658 * data[0] = queue index 659 * data[1] = grant reference of page containing the mapping list 660 * (r/w and assumed to start at beginning of page) 661 * data[2] = size of list in entries 662 * 663 * Response: 664 * 665 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not 666 * supported 667 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Operation failed 668 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful 669 * data = number of entries that were unmapped 670 * 671 * NOTE: Each entry in the input table has the format outlined in struct 672 * xen_netif_gref. 673 * The struct xen_netif_gref 'status' field determines if the entry 674 * was successfully removed. 675 * The entries used are only the ones representing grant references that 676 * were previously the subject of a XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING 677 * operation. Any other entries will have their status set to 678 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER upon completion. 679 */ 680 681 DEFINE_RING_TYPES(xen_netif_ctrl, 682 struct xen_netif_ctrl_request, 683 struct xen_netif_ctrl_response); 684 685 /* 686 * Guest transmit 687 * ============== 688 * 689 * This is the 'wire' format for transmit (frontend -> backend) packets: 690 * 691 * Fragment 1: netif_tx_request_t - flags = NETTXF_* 692 * size = total packet size 693 * [Extra 1: netif_extra_info_t] - (only if fragment 1 flags include 694 * NETTXF_extra_info) 695 * ... 696 * [Extra N: netif_extra_info_t] - (only if extra N-1 flags include 697 * XEN_NETIF_EXTRA_MORE) 698 * ... 699 * Fragment N: netif_tx_request_t - (only if fragment N-1 flags include 700 * NETTXF_more_data - flags on preceding 701 * extras are not relevant here) 702 * flags = 0 703 * size = fragment size 704 * 705 * NOTE: 706 * 707 * This format slightly is different from that used for receive 708 * (backend -> frontend) packets. Specifically, in a multi-fragment 709 * packet the actual size of fragment 1 can only be determined by 710 * subtracting the sizes of fragments 2..N from the total packet size. 711 * 712 * Ring slot size is 12 octets, however not all request/response 713 * structs use the full size. 714 * 715 * tx request data (netif_tx_request_t) 716 * ------------------------------------ 717 * 718 * 0 1 2 3 4 5 6 7 octet 719 * +-----+-----+-----+-----+-----+-----+-----+-----+ 720 * | grant ref | offset | flags | 721 * +-----+-----+-----+-----+-----+-----+-----+-----+ 722 * | id | size | 723 * +-----+-----+-----+-----+ 724 * 725 * grant ref: Reference to buffer page. 726 * offset: Offset within buffer page. 727 * flags: NETTXF_*. 728 * id: request identifier, echoed in response. 729 * size: packet size in bytes. 730 * 731 * tx response (netif_tx_response_t) 732 * --------------------------------- 733 * 734 * 0 1 2 3 4 5 6 7 octet 735 * +-----+-----+-----+-----+-----+-----+-----+-----+ 736 * | id | status | unused | 737 * +-----+-----+-----+-----+-----+-----+-----+-----+ 738 * | unused | 739 * +-----+-----+-----+-----+ 740 * 741 * id: reflects id in transmit request 742 * status: NETIF_RSP_* 743 * 744 * Guest receive 745 * ============= 746 * 747 * This is the 'wire' format for receive (backend -> frontend) packets: 748 * 749 * Fragment 1: netif_rx_request_t - flags = NETRXF_* 750 * size = fragment size 751 * [Extra 1: netif_extra_info_t] - (only if fragment 1 flags include 752 * NETRXF_extra_info) 753 * ... 754 * [Extra N: netif_extra_info_t] - (only if extra N-1 flags include 755 * XEN_NETIF_EXTRA_MORE) 756 * ... 757 * Fragment N: netif_rx_request_t - (only if fragment N-1 flags include 758 * NETRXF_more_data - flags on preceding 759 * extras are not relevant here) 760 * flags = 0 761 * size = fragment size 762 * 763 * NOTE: 764 * 765 * This format slightly is different from that used for transmit 766 * (frontend -> backend) packets. Specifically, in a multi-fragment 767 * packet the size of the packet can only be determined by summing the 768 * sizes of fragments 1..N. 769 * 770 * Ring slot size is 8 octets. 771 * 772 * rx request (netif_rx_request_t) 773 * ------------------------------- 774 * 775 * 0 1 2 3 4 5 6 7 octet 776 * +-----+-----+-----+-----+-----+-----+-----+-----+ 777 * | id | pad | gref | 778 * +-----+-----+-----+-----+-----+-----+-----+-----+ 779 * 780 * id: request identifier, echoed in response. 781 * gref: reference to incoming granted frame. 782 * 783 * rx response (netif_rx_response_t) 784 * --------------------------------- 785 * 786 * 0 1 2 3 4 5 6 7 octet 787 * +-----+-----+-----+-----+-----+-----+-----+-----+ 788 * | id | offset | flags | status | 789 * +-----+-----+-----+-----+-----+-----+-----+-----+ 790 * 791 * id: reflects id in receive request 792 * offset: offset in page of start of received packet 793 * flags: NETRXF_* 794 * status: -ve: NETIF_RSP_*; +ve: Rx'ed pkt size. 795 * 796 * NOTE: Historically, to support GSO on the frontend receive side, Linux 797 * netfront does not make use of the rx response id (because, as 798 * described below, extra info structures overlay the id field). 799 * Instead it assumes that responses always appear in the same ring 800 * slot as their corresponding request. Thus, to maintain 801 * compatibility, backends must make sure this is the case. 802 * 803 * Extra Info 804 * ========== 805 * 806 * Can be present if initial request or response has NET{T,R}XF_extra_info, 807 * or previous extra request has XEN_NETIF_EXTRA_MORE. 808 * 809 * The struct therefore needs to fit into either a tx or rx slot and 810 * is therefore limited to 8 octets. 811 * 812 * NOTE: Because extra info data overlays the usual request/response 813 * structures, there is no id information in the opposite direction. 814 * So, if an extra info overlays an rx response the frontend can 815 * assume that it is in the same ring slot as the request that was 816 * consumed to make the slot available, and the backend must ensure 817 * this assumption is true. 818 * 819 * extra info (netif_extra_info_t) 820 * ------------------------------- 821 * 822 * General format: 823 * 824 * 0 1 2 3 4 5 6 7 octet 825 * +-----+-----+-----+-----+-----+-----+-----+-----+ 826 * |type |flags| type specific data | 827 * +-----+-----+-----+-----+-----+-----+-----+-----+ 828 * | padding for tx | 829 * +-----+-----+-----+-----+ 830 * 831 * type: XEN_NETIF_EXTRA_TYPE_* 832 * flags: XEN_NETIF_EXTRA_FLAG_* 833 * padding for tx: present only in the tx case due to 8 octet limit 834 * from rx case. Not shown in type specific entries 835 * below. 836 * 837 * XEN_NETIF_EXTRA_TYPE_GSO: 838 * 839 * 0 1 2 3 4 5 6 7 octet 840 * +-----+-----+-----+-----+-----+-----+-----+-----+ 841 * |type |flags| size |type | pad | features | 842 * +-----+-----+-----+-----+-----+-----+-----+-----+ 843 * 844 * type: Must be XEN_NETIF_EXTRA_TYPE_GSO 845 * flags: XEN_NETIF_EXTRA_FLAG_* 846 * size: Maximum payload size of each segment. For example, 847 * for TCP this is just the path MSS. 848 * type: XEN_NETIF_GSO_TYPE_*: This determines the protocol of 849 * the packet and any extra features required to segment the 850 * packet properly. 851 * features: EN_NETIF_GSO_FEAT_*: This specifies any extra GSO 852 * features required to process this packet, such as ECN 853 * support for TCPv4. 854 * 855 * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}: 856 * 857 * 0 1 2 3 4 5 6 7 octet 858 * +-----+-----+-----+-----+-----+-----+-----+-----+ 859 * |type |flags| addr | 860 * +-----+-----+-----+-----+-----+-----+-----+-----+ 861 * 862 * type: Must be XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL} 863 * flags: XEN_NETIF_EXTRA_FLAG_* 864 * addr: address to add/remove 865 * 866 * XEN_NETIF_EXTRA_TYPE_HASH: 867 * 868 * A backend that supports teoplitz hashing is assumed to accept 869 * this type of extra info in transmit packets. 870 * A frontend that enables hashing is assumed to accept 871 * this type of extra info in receive packets. 872 * 873 * 0 1 2 3 4 5 6 7 octet 874 * +-----+-----+-----+-----+-----+-----+-----+-----+ 875 * |type |flags|htype| alg |LSB ---- value ---- MSB| 876 * +-----+-----+-----+-----+-----+-----+-----+-----+ 877 * 878 * type: Must be XEN_NETIF_EXTRA_TYPE_HASH 879 * flags: XEN_NETIF_EXTRA_FLAG_* 880 * htype: Hash type (one of _XEN_NETIF_CTRL_HASH_TYPE_* - see above) 881 * alg: The algorithm used to calculate the hash (one of 882 * XEN_NETIF_CTRL_HASH_TYPE_ALGORITHM_* - see above) 883 * value: Hash value 884 */ 885 886 /* Protocol checksum field is blank in the packet (hardware offload)? */ 887 #define _NETTXF_csum_blank (0) 888 #define NETTXF_csum_blank (1U<<_NETTXF_csum_blank) 889 890 /* Packet data has been validated against protocol checksum. */ 891 #define _NETTXF_data_validated (1) 892 #define NETTXF_data_validated (1U<<_NETTXF_data_validated) 893 894 /* Packet continues in the next request descriptor. */ 895 #define _NETTXF_more_data (2) 896 #define NETTXF_more_data (1U<<_NETTXF_more_data) 897 898 /* Packet to be followed by extra descriptor(s). */ 899 #define _NETTXF_extra_info (3) 900 #define NETTXF_extra_info (1U<<_NETTXF_extra_info) 901 902 #define XEN_NETIF_MAX_TX_SIZE 0xFFFF 903 struct netif_tx_request { 904 grant_ref_t gref; 905 uint16_t offset; 906 uint16_t flags; 907 uint16_t id; 908 uint16_t size; 909 }; 910 typedef struct netif_tx_request netif_tx_request_t; 911 912 /* Types of netif_extra_info descriptors. */ 913 #define XEN_NETIF_EXTRA_TYPE_NONE (0) /* Never used - invalid */ 914 #define XEN_NETIF_EXTRA_TYPE_GSO (1) /* u.gso */ 915 #define XEN_NETIF_EXTRA_TYPE_MCAST_ADD (2) /* u.mcast */ 916 #define XEN_NETIF_EXTRA_TYPE_MCAST_DEL (3) /* u.mcast */ 917 #define XEN_NETIF_EXTRA_TYPE_HASH (4) /* u.hash */ 918 #define XEN_NETIF_EXTRA_TYPE_MAX (5) 919 920 /* netif_extra_info_t flags. */ 921 #define _XEN_NETIF_EXTRA_FLAG_MORE (0) 922 #define XEN_NETIF_EXTRA_FLAG_MORE (1U<<_XEN_NETIF_EXTRA_FLAG_MORE) 923 924 /* GSO types */ 925 #define XEN_NETIF_GSO_TYPE_NONE (0) 926 #define XEN_NETIF_GSO_TYPE_TCPV4 (1) 927 #define XEN_NETIF_GSO_TYPE_TCPV6 (2) 928 929 /* 930 * This structure needs to fit within both netif_tx_request_t and 931 * netif_rx_response_t for compatibility. 932 */ 933 struct netif_extra_info { 934 uint8_t type; 935 uint8_t flags; 936 union { 937 struct { 938 uint16_t size; 939 uint8_t type; 940 uint8_t pad; 941 uint16_t features; 942 } gso; 943 struct { 944 uint8_t addr[6]; 945 } mcast; 946 struct { 947 uint8_t type; 948 uint8_t algorithm; 949 uint8_t value[4]; 950 } hash; 951 uint16_t pad[3]; 952 } u; 953 }; 954 typedef struct netif_extra_info netif_extra_info_t; 955 956 struct netif_tx_response { 957 uint16_t id; 958 int16_t status; 959 }; 960 typedef struct netif_tx_response netif_tx_response_t; 961 962 struct netif_rx_request { 963 uint16_t id; /* Echoed in response message. */ 964 uint16_t pad; 965 grant_ref_t gref; 966 }; 967 typedef struct netif_rx_request netif_rx_request_t; 968 969 /* Packet data has been validated against protocol checksum. */ 970 #define _NETRXF_data_validated (0) 971 #define NETRXF_data_validated (1U<<_NETRXF_data_validated) 972 973 /* Protocol checksum field is blank in the packet (hardware offload)? */ 974 #define _NETRXF_csum_blank (1) 975 #define NETRXF_csum_blank (1U<<_NETRXF_csum_blank) 976 977 /* Packet continues in the next request descriptor. */ 978 #define _NETRXF_more_data (2) 979 #define NETRXF_more_data (1U<<_NETRXF_more_data) 980 981 /* Packet to be followed by extra descriptor(s). */ 982 #define _NETRXF_extra_info (3) 983 #define NETRXF_extra_info (1U<<_NETRXF_extra_info) 984 985 /* Packet has GSO prefix. Deprecated but included for compatibility */ 986 #define _NETRXF_gso_prefix (4) 987 #define NETRXF_gso_prefix (1U<<_NETRXF_gso_prefix) 988 989 struct netif_rx_response { 990 uint16_t id; 991 uint16_t offset; 992 uint16_t flags; 993 int16_t status; 994 }; 995 typedef struct netif_rx_response netif_rx_response_t; 996 997 /* 998 * Generate netif ring structures and types. 999 */ 1000 1001 DEFINE_RING_TYPES(netif_tx, struct netif_tx_request, struct netif_tx_response); 1002 DEFINE_RING_TYPES(netif_rx, struct netif_rx_request, struct netif_rx_response); 1003 1004 #define NETIF_RSP_DROPPED -2 1005 #define NETIF_RSP_ERROR -1 1006 #define NETIF_RSP_OKAY 0 1007 /* No response: used for auxiliary requests (e.g., netif_extra_info_t). */ 1008 #define NETIF_RSP_NULL 1 1009 1010 #endif 1011