From 4c087bd79a3fe3bc192fa09a76340fea2864105c Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Thu, 29 Aug 2013 22:22:30 +0000 Subject: formatting: fix up section and footnote numbering automatically done by script. Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@24 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- virtio-v1.0-wd01-part1-specification.txt | 224 +++++++++++++++---------------- 1 file changed, 112 insertions(+), 112 deletions(-) diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt index e05e2cd..9e63e0e 100644 --- a/virtio-v1.0-wd01-part1-specification.txt +++ b/virtio-v1.0-wd01-part1-specification.txt @@ -606,18 +606,18 @@ interrupt is delivered when a configuration change occurs. -2.4. Virtio Transport Options +2.3. Virtio Transport Options ============================ Virtio can use various different busses, thus the standard is split into virtio general and bus-specific sections. -2.4.1. Virtio Over PCI Bus +2.3.1. Virtio Over PCI Bus ------------------------- Virtio devices are commonly implemented as PCI devices. -2.4.1.1. PCI Device Discovery +2.3.1.1. PCI Device Discovery ---------------------------- Any PCI device with Vendor ID 0x1AF4, and Device ID 0x1000 through @@ -629,7 +629,7 @@ supported by the device. The Subsystem Vendor ID should reflect the PCI Vendor ID of the environment (it's currently only used for informational purposes by the guest). -2.4.1.2. PCI Device Layout +2.3.1.2. PCI Device Layout ------------------------- To configure the device, we use the first I/O region of the PCI @@ -647,7 +647,7 @@ Note that this is possible because while the virtio header is PCI the native endian of the guest (where such distinction is applicable). -2.4.1.2.1. PCI Device Virtio Header +2.3.1.2.1. PCI Device Virtio Header ---------------------------------- The virtio header looks as follows: @@ -689,16 +689,16 @@ device-specific headers: | || | +------------++--------------------+ -2.4.1.3. PCI-specific Initialization And Device Operation +2.3.1.3. PCI-specific Initialization And Device Operation -------------------------------------------------------- The page size for a virtqueue on a PCI virtio device is defined as 4096 bytes. -2.4.1.3.1. Device Initialization +2.3.1.3.1. Device Initialization ------------------------------- -2.4.1.3.1.1. Queue Vector Configuration +2.3.1.3.1.1. Queue Vector Configuration -------------------------------------- When MSI-X capability is present and enabled in the device @@ -732,7 +732,7 @@ success, the previously written value is returned, and on failure, NO_VECTOR is returned. If a mapping failure is detected, the driver can retry mapping with fewervectors, or disable MSI-X. -2.4.1.3.1.2. Virtqueue Configuration +2.3.1.3.1.2. Virtqueue Configuration ----------------------------------- As a device can have zero or more virtqueues for bulk data @@ -760,14 +760,14 @@ This is done as follows, for each virtqueue a device has: Queue Vector field: on success, previously written value is returned; on failure, NO_VECTOR value is returned. -2.4.1.3.2. Notifying The Device +2.3.1.3.2. Notifying The Device ------------------------------ Device notification occurs by writing the 16-bit virtqueue index of this virtqueue to the Queue Notify field of the virtio header in the first I/O region of the PCI device. -2.4.1.3.3. Virtqueue Interrupts From The Device +2.3.1.3.3. Virtqueue Interrupts From The Device ---------------------------------------------- If an interrupt is necessary: @@ -801,7 +801,7 @@ The guest interrupt handler should: device, to see if any progress has been made by the device which requires servicing. -2.4.1.3.4. Notification of Device Configuration Changes +2.3.1.3.4. Notification of Device Configuration Changes ------------------------------------------------------ Some virtio PCI devices can change the device configuration @@ -821,7 +821,7 @@ space. In this case: entry number to use. If Configuration Vector field value is NO_VECTOR, no interrupt message is requested for this event. -2.4.2. Virtio Over MMIO +2.3.2. Virtio Over MMIO ---------------------- Virtual environments without PCI support (a common situation in @@ -834,7 +834,7 @@ initialization, queues configuration and buffer transfers are nearly identical. Existing differences are described in the following sections. -2.4.2.1. MMIO Device Discovery +2.3.2.1. MMIO Device Discovery ----------------------------- Unlike PCI, MMIO provides no generic device discovery. For systems using @@ -846,7 +846,7 @@ a device-tree such as Linux's dtc or Open Firmware, the suggested format is: interrupts = <42>; } -2.4.2.2. MMIO Device Layout +2.3.2.2. MMIO Device Layout -------------------------- MMIO virtio devices provides a set of memory mapped control @@ -999,17 +999,17 @@ the Guest. Writing to registers described as “R” and reading from registers described as “W” is not permitted and can cause undefined behavior. -2.4.2.3. MMIO-specific Initialization And Device Operation +2.3.2.3. MMIO-specific Initialization And Device Operation --------------------------------------------------------- -2.4.2.3.1. Device Initialization +2.3.2.3.1. Device Initialization ------------------------------- Unlike the fixed page size for PCI, the virtqueue page size is defined by the GuestPageSize field, as written by the guest. This must be done before the virtqueues are configured. -2.4.2.3.1.1. Virtqueue Configuration +2.3.2.3.1.1. Virtqueue Configuration ----------------------------------- 1. Select the queue writing its index (first queue is 0) to the @@ -1036,13 +1036,13 @@ done before the virtqueues are configured. 7. Write the physical number of the first page of the queue to the QueuePFN register. -2.4.2.3.2. Notifying The Device +2.3.2.3.2. Notifying The Device ------------------------------ The device is notified about new buffers available in a queue by writing the queue index to register QueueNum. -2.4.2.3.3. Receiving Used Buffers From The Device +2.3.2.3.3. Receiving Used Buffers From The Device ------------------------------------------------ The memory mapped virtio device is using single, dedicated @@ -1055,13 +1055,13 @@ interrupt is handled, the driver must acknowledge it by writing a bit mask corresponding to the serviced interrupt to the InterruptACK register. -2.4.2.4.4. Notification of Device Configuration Changes +2.3.2.4.4. Notification of Device Configuration Changes ------------------------------------------------------ This is indicated by bit 1 in the InterruptStatus register, as documented in the register description. -2.5. Device Types +2.4. Device Types ================ On top of the queues, config space and feature negotiation facilities @@ -1102,7 +1102,7 @@ Discovering what devices are available and their type is bus-dependent. | 12 | virtio CAIF | +------------+--------------------+ -2.5.1. Network Device +2.4.1. Network Device ==================== The virtio network device is a virtual ethernet card, and is the @@ -1114,19 +1114,19 @@ packets are enqueued into another for transmission in that order. A third command queue is used to control advanced filtering features. -2.5.1.1. Device ID +2.4.1.1. Device ID ----------------- 1 -2.5.1.2. Virtqueues +2.4.1.2. Virtqueues ------------------ 0:receiveq. 1:transmitq. 2:controlq Virtqueue 2 only exists if VIRTIO_NET_F_CTRL_VQ set. -2.5.1.3. Feature bits +2.4.1.3. Feature bits -------------------- VIRTIO_NET_F_CSUM (0) Device handles packets with partial checksum @@ -1139,7 +1139,7 @@ features. VIRTIO_NET_F_MAC (5) Device has given MAC address. VIRTIO_NET_F_GSO (6) (Deprecated) device handles packets with - any GSO type.[13] + any GSO type.[12] VIRTIO_NET_F_GUEST_TSO4 (7) Guest can receive TSOv4. @@ -1186,7 +1186,7 @@ features. u16 status; }; -2.5.1.4. Device Initialization +2.4.1.4. Device Initialization ----------------------------- 1. The initialization routine should identify the receive and @@ -1213,16 +1213,16 @@ features. packets by negotating the VIRTIO_NET_F_CSUM feature. This “ checksum offload” is a common feature on modern network cards. -7. If that feature is negotiated[14], a driver can use TCP or UDP +7. If that feature is negotiated[13], a driver can use TCP or UDP segmentation offload by negotiating the VIRTIO_NET_F_HOST_TSO4 (IPv4 TCP), VIRTIO_NET_F_HOST_TSO6 (IPv6 TCP) and VIRTIO_NET_F_HOST_UFO (UDP fragmentation) features. It should not send TCP packets requiring segmentation offload which have the Explicit Congestion Notification bit set, unless the VIRTIO_NET_F_HOST_ECN feature is - negotiated.[15] + negotiated.[14] 8. The converse features are also available: a driver can save - the virtual device some work by negotiating these features.[16] + the virtual device some work by negotiating these features.[15] The VIRTIO_NET_F_GUEST_CSUM feature indicates that partially checksummed packets can be received, and if it can do that then the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, @@ -1230,7 +1230,7 @@ features. equivalents of the features described above. See “Receiving Packets” below. -2.5.1.5. Device Operation +2.4.1.5. Device Operation ------------------------ Packets are transmitted by placing them in the transmitq, and @@ -1257,7 +1257,7 @@ case, the packet itself is preceeded by a header: The controlq is used to control device features such as filtering. -2.5.1.5.1. Packet Transmission +2.4.1.5.1. Packet Transmission ----------------------------- Transmitting a single packet is simple, but varies depending on @@ -1274,7 +1274,7 @@ the different features the driver negotiated. and • csum_offset indicates how many bytes after the csum_start the - new (16 bit ones' complement) checksum should be placed.[17] + new (16 bit ones' complement) checksum should be placed.[16] 2. If the driver negotiated VIRTIO_NET_F_HOST_TSO4, TSO6 or UFO, and the packet requires @@ -1287,23 +1287,23 @@ the different features the driver negotiated. • hdr_len is a hint to the device as to how much of the header needs to be kept to copy into each packet, usually set to the - length of the headers, including the transport header.[18] + length of the headers, including the transport header.[17] • gso_size is the maximum size of each packet beyond that header (ie. MSS). • If the driver negotiated the VIRTIO_NET_F_HOST_ECN feature, the VIRTIO_NET_HDR_GSO_ECN bit may be set in “gso_type” as - well, indicating that the TCP packet has the ECN bit set.[19] + well, indicating that the TCP packet has the ECN bit set.[18] 3. If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature, the num_buffers field is set to zero. 4. The header and packet are added as one output buffer to the transmitq, and the device is notified of the new entry (see "2.4.1.4. - Notifying The Device").[20] + Notifying The Device").[19] -2.5.1.5.1.1. Packet Transmission Interrupt +2.4.1.5.1.1. Packet Transmission Interrupt ----------------------------------------- Often a driver will suppress transmission interrupts using the @@ -1317,7 +1317,7 @@ The normal behavior in this interrupt handler is to retrieve and new descriptors from the used ring and free the corresponding headers and packets. -2.5.1.5.2. Setting Up Receive Buffers +2.4.1.5.2. Setting Up Receive Buffers It is generally a good idea to keep the receive virtqueue as fully populated as possible: if it runs out, network performance @@ -1328,12 +1328,12 @@ VIRTIO_NET_F_GUEST_UFO features are used, the Guest will need to accept packets of up to 65550 bytes long (the maximum size of a TCP or UDP packet, plus the 14 byte ethernet header), otherwise 1514. bytes. So unless VIRTIO_NET_F_MRG_RXBUF is negotiated, every -buffer in the receive queue needs to be at least this length [99] +buffer in the receive queue needs to be at least this length [20] If VIRTIO_NET_F_MRG_RXBUF is negotiated, each buffer must be at least the size of the struct virtio_net_hdr. -2.5.1.5.2.1. Packet Receive Interrupt +2.4.1.5.2.1. Packet Receive Interrupt ------------------------------------ When a packet is copied into a buffer in the receiveq, the @@ -1368,7 +1368,7 @@ Processing packet involves: VIRTIO_NET_HDR_GSO_NONE, and the “gso_size” field indicates the desired MSS (see Packet Transmission point 2). -2.5.1.5.3. Control Virtqueue +2.4.1.5.3. Control Virtqueue --------------------------- The driver uses the control virtqueue (if VIRTIO_NET_F_VTRL_VQ is @@ -1394,7 +1394,7 @@ driver, and the device sets the ack byte. There is little it can do except issue a diagnostic if the ack byte is not VIRTIO_NET_OK. -2.5.1.5.3.1. Packet Receive Filtering +2.4.1.5.2.1. Packet Receive Filtering ------------------------------------ If the VIRTIO_NET_F_CTRL_RX feature is negotiated, the driver can @@ -1416,7 +1416,7 @@ VIRTIO_NET_CTRL_RX_ALLMULTI turns all-multicast receive on and off. The command-specific-data is one byte containing 0 (off) or 1 (on). -2.5.1.5.3.2. Setting MAC Address Filtering +2.4.1.5.2.2. Setting MAC Address Filtering ----------------------------------------- struct virtio_net_ctrl_mac { @@ -1434,7 +1434,7 @@ command-specific-data is two variable length tables of 6-byte MAC addresses. The first table contains unicast addresses, and the second contains multicast addresses. -2.5.1.5.3.3. VLAN Filtering +2.4.1.5.3.3. VLAN Filtering -------------------------- If the driver negotiates the VIRTION_NET_F_CTRL_VLAN feature, it @@ -1447,7 +1447,7 @@ can control a VLAN filter table in the device. Both the VIRTIO_NET_CTRL_VLAN_ADD and VIRTIO_NET_CTRL_VLAN_DEL command take a 16-bit VLAN id as the command-specific-data. -2.5.1.5.3.4. Gratuitous Packet Sending +2.4.1.5.3.4. Gratuitous Packet Sending ------------------------------------- If the driver negotiates the VIRTIO_NET_F_GUEST_ANNOUNCE (depends @@ -1477,13 +1477,13 @@ Processing this notification involves: 2. Sending VIRTIO_NET_CTRL_ANNOUNCE_ACK command through control vq. -2.5.1.5.3.5. Offloads State Configuration +2.4.1.5.3.5. Offloads State Configuration ------------------------------------- If the VIRTIO_NET_F_CTRL_GUEST_OFFLOADS feature is negotiated, the driver can send control commands for dynamic offloads state configuration. -2.5.1.5.4.3.1. Setting Offloads State +2.4.1.5.4.3.1. Setting Offloads State ------------------------------------- u64 offloads; @@ -1511,7 +1511,7 @@ Corresponding feature must be negotiated at startup in order to allow dynamic change of specific offload state. -2.5.2. Block Device +2.4.2. Block Device ================== The virtio block device is a simple virtual block device (ie. @@ -1519,15 +1519,15 @@ disk). Read and write requests (and other exotic requests) are placed in the queue, and serviced (probably out of order) by the device except where noted. -2.5.2.1. Device ID +2.4.2.1. Device ID ----------------- 2 -2.5.2.2. Virtqueues +2.4.2.2. Virtqueues ------------------ 0:requestq -2.5.2.3. Feature bits +2.4.2.3. Feature bits -------------------- VIRTIO_BLK_F_BARRIER (0) Host supports request barriers. @@ -1566,7 +1566,7 @@ device except where noted. u32 blk_size; }; -2.5.2.4. Device Initialization +2.4.2.3. Device Initialization ----------------------------- 1. The device size should be read from the “capacity” @@ -1582,7 +1582,7 @@ device except where noted. 3. If the VIRTIO_BLK_F_RO feature is set by the device, any write requests will fail. -2.5.2.5. Device Operation +2.4.2.5. Device Operation ------------------------ The driver queues requests to the virtqueue, and they are used by @@ -1685,7 +1685,7 @@ and the status field is a separate read-only buffer of size 1 byte, by itself. -2.5.3. Console Device +2.4.3. Console Device ==================== The virtio console device is a simple device for data input and @@ -1701,12 +1701,12 @@ successfully added, port open/close, etc.. For data IO, one or more empty buffers are placed in the receive queue for incoming data and outgoing characters are placed in the transmit queue. -2.5.3.1. Device ID +2.4.3.1. Device ID ----------------- 3 -2.5.3.2. Virtqueues +2.4.3.2. Virtqueues ------------------ 0:receiveq(port0). 1:transmitq(port0), 2:control receiveq, 3:control transmitq, 4:receiveq(port1), 5:transmitq(port1), @@ -1714,7 +1714,7 @@ data and outgoing characters are placed in the transmit queue. Ports 2 onwards only exist if VIRTIO_CONSOLE_F_MULTIPORT is set. -2.5.3.3. Feature bits +2.4.3.3. Feature bits -------------------- VIRTIO_CONSOLE_F_SIZE (0) Configuration cols and rows fields @@ -1724,7 +1724,7 @@ data and outgoing characters are placed in the transmit queue. ports; configuration fields nr_ports and max_nr_ports are valid and control virtqueues will be used. -2.5.3.4. Device configuration layout +2.4.3.4. Device configuration layout ----------------------------------- The size of the console is supplied @@ -1739,7 +1739,7 @@ data and outgoing characters are placed in the transmit queue. u32 max_nr_ports; }; -2.5.3.5. Device Initialization +2.4.3.5. Device Initialization ----------------------------- 1. If the VIRTIO_CONSOLE_F_SIZE feature is negotiated, the driver @@ -1761,11 +1761,11 @@ data and outgoing characters are placed in the transmit queue. 3. The receiveq for each port is populated with one or more receive buffers. -2.5.3.6. Device Operation +2.4.3.6. Device Operation ------------------------ 1. For output, a buffer containing the characters is placed in - the port's transmitq.[25] + the port's transmitq.[24] 2. When a buffer is used in the receiveq (signalled by an interrupt), the contents is the input to the port associated @@ -1806,41 +1806,41 @@ data and outgoing characters are placed in the transmit queue. #define VIRTIO_CONSOLE_PORT_OPEN 6 #define VIRTIO_CONSOLE_PORT_NAME 7 -2.5.4. Entropy Device +2.4.4. Entropy Device ==================== The virtio entropy device supplies high-quality randomness for guest use. -2.5.4.1. Device ID +2.4.4.1. Device ID ----------------- 4 -2.5.4.2. Virtqueues +2.4.4.2. Virtqueues ------------------ 0:requestq. -2.5.4.3. Feature bits +2.4.4.3. Feature bits -------------------- None currently defined -2.5.4.4. Device configuration layout +2.4.4.4. Device configuration layout ----------------------------------- None currently defined. -2.5.4.5. Device Initialization +2.4.4.5. Device Initialization ----------------------------- 1. The virtqueue is initialized -2.5.4.6. Device Operation +2.4.4.6. Device Operation ------------------------ When the driver requires random bytes, it places the descriptor of one or more buffers in the queue. It will be completely filled by random data by the device. -2.5.5. Memory Balloon Device +2.4.5. Memory Balloon Device =========================== The virtio memory balloon device is a primitive device for @@ -1851,17 +1851,17 @@ changes in allowance of underlying physical memory. If the feature is negotiated, the device can also be used to communicate guest memory statistics to the host. -2.5.5.1. Device ID +2.4.5.1. Device ID ----------------- 5 -2.5.5.2. Virtqueues +2.4.5.2. Virtqueues ------------------ 0:inflateq. 1:deflateq. 2:statsq. Virtqueue 2 only exists if VIRTIO_BALLON_F_STATS_VQ set. -2.5.5.3. Feature bits +2.4.5.3. Feature bits -------------------- VIRTIO_BALLOON_F_MUST_TELL_HOST (0) Host must be told before pages from the balloon are used. @@ -1869,7 +1869,7 @@ guest memory statistics to the host. VIRTIO_BALLOON_F_STATS_VQ (1) A virtqueue for reporting guest memory statistics is present. -2.5.5.4. Device configuration layout +2.4.5.4. Device configuration layout ----------------------------------- Both fields of this configuration are always available. Note that they are little endian, despite @@ -1880,7 +1880,7 @@ guest memory statistics to the host. u32 actual; }; -2.5.5.5. Device Initialization +2.4.5.5. Device Initialization ----------------------------- 1. The inflate and deflate virtqueues are identified. @@ -1894,7 +1894,7 @@ guest memory statistics to the host. Device operation begins immediately. -2.5.5.6. Device Operation +2.4.5.6. Device Operation ------------------------ Memory Ballooning The device is driven by the receipt of a @@ -1909,7 +1909,7 @@ configuration change interrupt. 2. To supply memory to the balloon (aka. inflate): (a) The driver constructs an array of addresses of unused memory - pages. These addresses are divided by 4096[27] and the descriptor + pages. These addresses are divided by 4096[25] and the descriptor describing the resulting 32-bit array is added to the inflateq. 3. To remove memory from the balloon (aka. deflate): @@ -1924,13 +1924,13 @@ configuration change interrupt. (c) Otherwise, the guest may begin to re-use pages previously given to the balloon before the device has acknowledged their - withdrawl. [28] + withdrawl. [26] 4. In either case, once the device has completed the inflation or deflation, the “actual” field of the configuration should be - updated to reflect the new number of pages in the balloon.[29] + updated to reflect the new number of pages in the balloon.[27] -2.5.5.6.1. Memory Statistics +2.4.5.6.1. Memory Statistics --------------------------- The stats virtqueue is atypical because communication is driven @@ -1970,7 +1970,7 @@ as follows: u64 val; } __attribute__((packed)); -2.5.5.6.2. Memory Statistics Tags +2.4.5.6.2. Memory Statistics Tags -------------------------------- VIRTIO_BALLOON_S_SWAP_IN The amount of memory that has been @@ -1992,7 +1992,7 @@ as follows: (in bytes). -2.5.6. SCSI Host Device +2.4.6. SCSI Host Device ====================== The virtio SCSI host device groups together one or more virtual @@ -2014,15 +2014,15 @@ medium. In the transport protocol, the virtio driver acts as the initiator, while the virtio SCSI host provides one or more targets that receive and process the requests. -2.5.6.1. Device ID +2.4.6.1. Device ID ----------------- 8 -2.5.6.2. Virtqueues +2.4.6.2. Virtqueues ------------------ 0:controlq; 1:eventq; 2..n:request queues. -2.5.6.3. Feature bits +2.4.6.3. Feature bits -------------------- VIRTIO_SCSI_F_INOUT (0) A single request can include both @@ -2031,7 +2031,7 @@ targets that receive and process the requests. VIRTIO_SCSI_F_HOTPLUG (1) The host should enable hot-plug/hot-unplug of new LUNs and targets on the SCSI bus. -2.5.6.4. Device configuration layout +2.4.6.4. Device configuration layout ----------------------------------- All fields of this configuration are always available. sense_size @@ -2086,7 +2086,7 @@ targets that receive and process the requests. as hints to constrain scanning the logical units on the host.h -2.5.6.5. Device Initialization +2.4.6.5. Device Initialization ----------------------------- The initialization routine should first of all discover the @@ -2099,13 +2099,13 @@ The driver can immediately issue requests (for example, INQUIRY or REPORT LUNS) or task management functions (for example, I_T RESET). -2.5.6.6. Device Operation +2.4.6.6. Device Operation ------------------------ Device operation consists of operating request queues, the control queue and the event queue. -2.5.6.6.1. Device Operation: Request Queues +2.4.6.6.1. Device Operation: Request Queues ------------------------------------------ The driver queues requests to an arbitrary request queue, and @@ -2228,7 +2228,7 @@ following: request will be immediately returned with a response equal to VIRTIO_SCSI_S_FAILURE. -2.5.6.6.2. Device Operation: controlq +2.4.6.6.2. Device Operation: controlq ------------------------------------ The controlq is used for other SCSI transport operations. @@ -2360,7 +2360,7 @@ The following commands are defined: No command-specific values are defined for the response byte. -2.5.6.6.3. Device Operation: eventq +2.4.6.6.3. Device Operation: eventq ---------------------------------- The eventq is used by the device to report information on logical @@ -2505,7 +2505,7 @@ contents of the event field. The following events are defined: asynchronous events manually using SCSI commands. -2.6. Reserved Feature Bits +2.5. Reserved Feature Bits ========================= Currently there are four device-independent feature bits defined: @@ -2544,7 +2544,7 @@ In addition, bit 30 is used by qemu's implementation to check for experimental early versions of virtio which did not perform correct feature negotiation, and should not be used. -2.7. virtio_ring.h +2.6. virtio_ring.h ================= #ifndef VIRTIO_RING_H @@ -2714,13 +2714,13 @@ static inline uint16_t *vring_avail_event(struct vring *vr) -2.10. Creating New Device Types +2.7. Creating New Device Types ============================== Various considerations are necessary when creating a new device type. -2.10.1. How Many Virtqueues? +2.7.1. How Many Virtqueues? --------------------------- It is possible that a very simple device will operate entirely @@ -2731,7 +2731,7 @@ need two queues: one which the driver fills with buffers to receive input, and one which the driver places buffers to transmit output. -2.10.2. What Configuration Space Layout? +2.7.2. What Configuration Space Layout? --------------------------------------- Configuration space should only be used for initialization-time @@ -2741,7 +2741,7 @@ information (the network device does this for filtering, otherwise the table in the config space could potentially be very large). -2.10.3. What Device Number? +2.7.3. What Device Number? -------------------------- Currently device numbers are assigned quite freely: a simple @@ -2750,7 +2750,7 @@ virtualization mailing list[9] will be sufficient to secure a unique one. Meanwhile for experimental drivers, use 65535 and work backwards. -2.10.4. How many MSI-X vectors? (for PCI) +2.7.4. How many MSI-X vectors? (for PCI) ----------------------------------------- Using the optional MSI-X capability devices can speed up @@ -2769,7 +2769,7 @@ space. Drivers can control this by mapping events to as small number of vectors as possible, or disabling MSI-X capability altogether. -2.10.5. Device Improvements +2.7.5. Device Improvements -------------------------- Any change to configuration space, or new virtqueues, or @@ -2828,24 +2828,24 @@ intuiting field lengths from frame boundaries. mistakes! -[13] It was supposed to indicate segmentation offload support, but +[12] It was supposed to indicate segmentation offload support, but upon further investigation it became clear that multiple bits were required. -[14] ie. VIRTIO_NET_F_HOST_TSO* and VIRTIO_NET_F_HOST_UFO are +[13] ie. VIRTIO_NET_F_HOST_TSO* and VIRTIO_NET_F_HOST_UFO are dependent on VIRTIO_NET_F_CSUM; a dvice which offers the offload features must offer the checksum feature, and a driver which accepts the offload features must accept the checksum feature. Similar logic applies to the VIRTIO_NET_F_GUEST_TSO4 features depending on VIRTIO_NET_F_GUEST_CSUM. -[15] This is a common restriction in real, older network cards. +[14] This is a common restriction in real, older network cards. -[16] For example, a network packet transported between two guests on +[15] For example, a network packet transported between two guests on the same system may not require checksumming at all, nor segmentation, if both guests are amenable. -[17] For example, consider a partially checksummed TCP (IPv4) packet. +[16] For example, consider a partially checksummed TCP (IPv4) packet. It will have a 14 byte ethernet header and 20 byte IP header followed by the TCP header (with the TCP checksum field 16 bytes into that header). csum_start will be 14+20 = 34 (the TCP @@ -2855,16 +2855,16 @@ of the TCP pseudo header, so that replacing it by the ones' complement checksum of the TCP header and body will give the correct result. -[18] Due to various bugs in implementations, this field is not useful +[17] Due to various bugs in implementations, this field is not useful as a guarantee of the transport header size. -[19] This case is not handled by some older hardware, so is called out +[18] This case is not handled by some older hardware, so is called out specifically in the protocol. -[20] Note that the header will be two bytes longer for the +[19] Note that the header will be two bytes longer for the VIRTIO_NET_F_MRG_RXBUF case. -[99] Obviously each one can be split across multiple descriptor +[20] Obviously each one can be split across multiple descriptor elements. [21] Since there are no guarentees, it can use a hash filter or @@ -2877,7 +2877,7 @@ does not distinguish between them. [23] The FLUSH and FLUSH_OUT types are equivalent, the device does not distinguish between them -[25] Because this is high importance and low bandwidth, the current +[24] Because this is high importance and low bandwidth, the current Linux implementation polls for the buffer to be used, rather than waiting for an interrupt, simplifying the implementation significantly. However, for generic serial ports with the @@ -2885,9 +2885,9 @@ O_NONBLOCK flag set, the polling limitation is relaxed and the consumed buffers are freed upon the next write or poll call or when a port is closed or hot-unplugged. -[27] This is historical, and independent of the guest page size +[25] This is historical, and independent of the guest page size -[28] In this case, deflation advice is merely a courtesy +[26] In this case, deflation advice is merely a courtesy -[29] As updates to configuration space are not atomic, this field +[27] As updates to configuration space are not atomic, this field isn't particularly reliable, but can be used to diagnose buggy guests. -- cgit v1.2.3