From 3de864b0c506da07cc96884530037d8a947f2aed Mon Sep 17 00:00:00 2001 From: rusty Date: Mon, 10 Feb 2014 10:43:09 +0000 Subject: Feedback: update so it applies sequentially. Signed-off-by: Rusty Russell git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@226 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- feedback/6.txt | 69 +++++++++++++++++++++++++--------------------------------- 1 file changed, 30 insertions(+), 39 deletions(-) (limited to 'feedback/6.txt') diff --git a/feedback/6.txt b/feedback/6.txt index 21d9583..64706f3 100644 --- a/feedback/6.txt +++ b/feedback/6.txt @@ -80,10 +80,10 @@ device" or "read-only for the driver" throughout the specification. Proposal: diff --git a/content.tex b/content.tex -index 2eb0b26..4a5e868 100644 +index 7e77740..ca155ec 100644 --- a/content.tex +++ b/content.tex -@@ -289,7 +289,7 @@ struct vring { +@@ -286,7 +286,7 @@ struct vring { struct vring_avail avail; // Padding to the next PAGE_SIZE boundary. @@ -92,7 +92,7 @@ index 2eb0b26..4a5e868 100644 // A ring of used descriptor heads with free-running index. struct vring_used used; -@@ -337,8 +337,11 @@ VIRTIO_F_ANY_LAYOUT feature is accepted. +@@ -334,8 +334,11 @@ VIRTIO_F_ANY_LAYOUT feature is accepted. The descriptor table refers to the buffers the driver is using for the device. The addresses are physical addresses, and the buffers can be chained via the next field. Each descriptor describes a @@ -106,7 +106,7 @@ index 2eb0b26..4a5e868 100644 The actual contents of the memory offered to the device depends on the device type. Most common is to begin the data with a header -@@ -357,7 +360,7 @@ struct vring_desc { +@@ -355,7 +358,7 @@ struct vring_desc { /* This marks a buffer as continuing via the next field. */ #define VRING_DESC_F_NEXT 1 @@ -115,7 +115,7 @@ index 2eb0b26..4a5e868 100644 #define VRING_DESC_F_WRITE 2 /* This means the buffer contains a list of buffer descriptors. */ #define VRING_DESC_F_INDIRECT 4 -@@ -403,7 +406,7 @@ chained by next field. An indirect descriptor without next field +@@ -401,7 +404,7 @@ chained by next field. An indirect descriptor without next field An indirect descriptor can not refer to another indirect descriptor table (flags\&VRING_DESC_F_INDIRECT MUST be off). A single indirect descriptor @@ -124,7 +124,7 @@ index 2eb0b26..4a5e868 100644 the device MUST ignore the write-only flag (flags\&VRING_DESC_F_WRITE) in the descriptor that refers to it. \subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring} -@@ -574,8 +577,8 @@ There are two parts to device operation: supplying new buffers to +@@ -575,8 +578,8 @@ There are two parts to device operation: supplying new buffers to the device, and processing used buffers from the device. As an example, the simplest virtio network device has two virtqueues: the transmit virtqueue and the receive virtqueue. The driver adds @@ -135,7 +135,7 @@ index 2eb0b26..4a5e868 100644 buffers are added to the receive virtqueue, and processed after they are used. -@@ -620,9 +623,9 @@ Here is a description of each stage in more detail. +@@ -621,9 +624,9 @@ Here is a description of each stage in more detail. \subsubsection{Placing Buffers Into The Descriptor Table}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Placing Buffers Into The Descriptor Table} @@ -147,7 +147,7 @@ index 2eb0b26..4a5e868 100644 algorithm maps it into the descriptor table to form a descriptor chain: -@@ -632,7 +635,7 @@ for each buffer element, b: +@@ -633,7 +636,7 @@ for each buffer element, b: \item Get the next free descriptor table entry, d \item Set d.addr to the physical address of the start of b \item Set d.len to the length of b. @@ -156,7 +156,7 @@ index 2eb0b26..4a5e868 100644 otherwise 0. \item If there is a buffer element after this: \begin{enumerate} -@@ -707,7 +710,7 @@ notification: +@@ -708,7 +711,7 @@ notification: \subsection{Receiving Used Buffers From The Device}\label{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device} @@ -165,7 +165,7 @@ index 2eb0b26..4a5e868 100644 parts of both, depending on the nature of the virtqueue and the device), it SHOULD send an interrupt, following an algorithm very similar to the algorithm used for the driver to send the device a -@@ -842,20 +845,20 @@ Common configuration structure layout is documented below: +@@ -946,20 +949,20 @@ The device MUST present at least one common configuration capability. struct virtio_pci_common_cfg { /* About the whole device. */ le32 device_feature_select; /* read-write */ @@ -190,16 +190,7 @@ index 2eb0b26..4a5e868 100644 le64 queue_desc; /* read-write */ le64 queue_avail; /* read-write */ le64 queue_used; /* read-write */ -@@ -1044,7 +1047,7 @@ or accessed though PCI configuration space. - Actual location of each structure is specified using vendor-specific PCI capability located - on capability list in PCI configuration space of the device. - This virtio structure capability uses little-endian format; all bits are --read-only: -+read-only for the driver: - - \begin{lstlisting} - struct virtio_pci_cap { -@@ -2342,6 +2345,13 @@ Device ID & Virtio Device \\ +@@ -2351,6 +2354,13 @@ Device ID & Virtio Device \\ \hline \end{tabular} @@ -213,7 +204,7 @@ index 2eb0b26..4a5e868 100644 \section{Network Device}\label{sec:Device Types / Network Device} The virtio network device is a virtual ethernet card, and is the -@@ -2753,7 +2763,7 @@ off. The command-specific-data is one byte containing 0 (off) or +@@ -2764,7 +2774,7 @@ off. The command-specific-data is one byte containing 0 (off) or \begin{lstlisting} struct virtio_net_ctrl_mac { le32 entries; @@ -222,7 +213,7 @@ index 2eb0b26..4a5e868 100644 }; #define VIRTIO_NET_CTRL_MAC 1 -@@ -3077,7 +3087,7 @@ struct virtio_blk_req { +@@ -3090,7 +3100,7 @@ struct virtio_blk_req { le32 type; le32 reserved; le64 sector; @@ -231,7 +222,7 @@ index 2eb0b26..4a5e868 100644 u8 status; }; \end{lstlisting} -@@ -3142,8 +3152,8 @@ struct virtio_scsi_pc_req { +@@ -3155,8 +3165,8 @@ struct virtio_scsi_pc_req { u32 type; u32 ioprio; u64 sector; @@ -242,7 +233,7 @@ index 2eb0b26..4a5e868 100644 #define SCSI_SENSE_BUFFERSIZE 96 u8 sense[SCSI_SENSE_BUFFERSIZE]; u32 errors; -@@ -3169,8 +3179,8 @@ single, separate read-only buffer; command length can be derived +@@ -3182,8 +3192,8 @@ single, separate read-only buffer; command length can be derived from the length of this buffer. Note that these first three (four for scsi packet commands) @@ -253,7 +244,7 @@ index 2eb0b26..4a5e868 100644 write can be derived from the total size of the request buffers. The sense field is only present for scsi packet command requests, -@@ -3189,12 +3199,12 @@ requests and indicates the residual size, calculated as data +@@ -3202,12 +3212,12 @@ requests and indicates the residual size, calculated as data length - number of bytes actually transferred. Historically, devices assumed that the fields type, ioprio and @@ -270,7 +261,7 @@ index 2eb0b26..4a5e868 100644 byte, by itself. -@@ -3229,7 +3239,8 @@ data and outgoing characters are placed in the transmit queue. +@@ -3242,7 +3252,8 @@ data and outgoing characters are placed in the transmit queue. \item[\ldots] \end{description} @@ -280,7 +271,7 @@ index 2eb0b26..4a5e868 100644 \subsection{Feature bits}\label{sec:Device Types / Console Device / Feature bits} -@@ -3291,7 +3302,7 @@ native endian of the guest rather than (necessarily) little-endian. +@@ -3305,7 +3316,7 @@ native endian of the guest rather than (necessarily) little-endian. control messages for adding new ports to the device. After creating and initializing each port, a VIRTIO_CONSOLE_PORT_READY control message is sent to the device @@ -289,7 +280,7 @@ index 2eb0b26..4a5e868 100644 configuration options set for that port. \item The receiveq for each port is populated with one or more -@@ -3317,22 +3328,21 @@ when a port is closed or hot-unplugged. +@@ -3331,22 +3342,21 @@ when a port is closed or hot-unplugged. \item If the driver negotiated the VIRTIO_CONSOLE_F_SIZE feature, a configuration change interrupt may occur. The updated size can @@ -319,8 +310,8 @@ index 2eb0b26..4a5e868 100644 +control messages is: \begin{lstlisting} - struct virtio_console_control { -@@ -3340,18 +3350,45 @@ struct virtio_console_control { + /* Note: LEGACY version was not little endian! */ +@@ -3355,18 +3365,45 @@ struct virtio_console_control { le16 event; /* The kind of control event */ le16 value; /* Extra information for the event */ }; @@ -376,7 +367,7 @@ index 2eb0b26..4a5e868 100644 \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Console Device / Device Operation / Legacy Interface: Device Operation} For legacy devices, the fields in struct virtio_console_control are the -@@ -3600,7 +3637,7 @@ targets that receive and process the requests. +@@ -3616,7 +3653,7 @@ targets that receive and process the requests. \begin{description} \item[VIRTIO_SCSI_F_INOUT (0)] A single request can include both @@ -385,9 +376,9 @@ index 2eb0b26..4a5e868 100644 \item[VIRTIO_SCSI_F_HOTPLUG (1)] The host should enable hot-plug/hot-unplug of new LUNs and targets on the SCSI bus. -@@ -3700,22 +3737,22 @@ Requests have the following format: - +@@ -3718,22 +3755,22 @@ Requests have the following format: \begin{lstlisting} + /* Note: LEGACY version was not little endian! */ struct virtio_scsi_req_cmd { - // Read-only + // Device-readable part @@ -413,7 +404,7 @@ index 2eb0b26..4a5e868 100644 }; -@@ -3756,10 +3793,10 @@ value defined by the protocol is 255, since CRN is stored in an +@@ -3774,10 +3811,10 @@ value defined by the protocol is 255, since CRN is stored in an 8-bit integer. All of these fields are defined in SAM. They are always @@ -426,8 +417,8 @@ index 2eb0b26..4a5e868 100644 field indicates the number of bytes actually written to the sense buffer. The residual field indicates the residual size, calculated as “data_length - number_of_transferred_bytes”, for -@@ -3861,12 +3898,12 @@ The following commands are defined: - +@@ -3880,12 +3917,12 @@ The following commands are defined: + /* Note: LEGACY version was not little endian! */ struct virtio_scsi_ctrl_tmf { - // Read-only part @@ -441,7 +432,7 @@ index 2eb0b26..4a5e868 100644 u8 response; } -@@ -3898,11 +3935,11 @@ struct virtio_scsi_ctrl_tmf +@@ -3917,11 +3954,11 @@ struct virtio_scsi_ctrl_tmf #define VIRTIO_SCSI_T_AN_QUERY 1 struct virtio_scsi_ctrl_an { @@ -455,7 +446,7 @@ index 2eb0b26..4a5e868 100644 le32 event_actual; u8 response; } -@@ -3933,11 +3970,11 @@ struct virtio_scsi_ctrl_an { +@@ -3952,11 +3989,11 @@ struct virtio_scsi_ctrl_an { #define VIRTIO_SCSI_T_AN_SUBSCRIBE 2 struct virtio_scsi_ctrl_an { @@ -469,7 +460,7 @@ index 2eb0b26..4a5e868 100644 le32 event_actual; u8 response; } -@@ -3992,7 +4029,7 @@ following format: +@@ -4011,7 +4048,7 @@ following format: #define VIRTIO_SCSI_T_EVENTS_MISSED 0x80000000 struct virtio_scsi_event { -- cgit v1.2.3