[virtio-dev] [RFC] content: use a consistent wording for device status

[virtio-dev] [RFC] content: use a consistent wording for device status

[Tiwei Bie]

There is a part called "device status field" in a
Virtio device. Currently, both of \field{status}
and \field{device status} are used to refer to it,
which is a bit confusing. This patch changes spec
to use \field{device status} consistently.

Suggested-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Tiwei Bie <tiwei.bie@intel.com>
---
If we want this change, I'll open an issue and
send a formal patch.

 content.tex | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/content.tex b/content.tex
index be18234..b8f7b0a 100644
--- a/content.tex
+++ b/content.tex
@@ -2099,7 +2099,7 @@ value.
 
 As described in
 \ref{devicenormative:Basic Facilities of a Virtio Device / Feature Bits},
-a device sometimes fails to set the \field{status} field: For example, it
+a device sometimes fails to set the \field{device status} field: For example, it
 might fail to accept the FEATURES_OK status bit during device initialization.
 
 With revision 2, CCW_CMD_READ_STATUS is defined: It reads an 8 bit status
@@ -2109,10 +2109,11 @@ value from the device and acts as a reverse operation to CCW_CMD_WRITE_STATUS.
 
 If the device posts a unit check with command reject in response to the
 CCW_CMD_WRITE_STATUS command, the driver MUST assume that the device failed
-to set the status and the \field{status} field retained its previous value.
+to set the status and the \field{device status} field retained
+its previous value.
 
 If at least revision 2 has been negotiated, the driver SHOULD use the
-CCW_CMD_READ_STATUS command to retrieve the \field{status} field after
+CCW_CMD_READ_STATUS command to retrieve the \field{device status} field after
 a configuration change has been detected.
 
 If not at least revision 2 has been negotiated, the driver MUST NOT attempt
@@ -2120,12 +2121,14 @@ to issue the CCW_CMD_READ_STATUS command.
 
 \devicenormative{\paragraph}{Communicating Status Information}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information}
 
-If the device fails to set the \field{status} field to the value written by
-the driver, the device MUST assure that the \field{status} field is left
-unchanged and MUST post a unit check with command reject.
+If the device fails to set the \field{device status} field
+to the value written by the driver, the device MUST assure
+that the \field{device status} field is left unchanged and
+MUST post a unit check with command reject.
 
 If at least revision 2 has been negotiated, the device MUST return the
-current \field{status} field if the CCW_CMD_READ_STATUS command is issued.
+current \field{device status} field if the CCW_CMD_READ_STATUS
+command is issued.
 
 \subsubsection{Handling Device Features}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Handling Device Features}
 
@@ -3665,7 +3668,7 @@ If VIRTIO_BLK_F_CONFIG_WCE was not negotiated but VIRTIO_BLK_F_FLUSH was,
 the driver SHOULD assume presence of a writeback cache.
 
 The driver MUST NOT read \field{writeback} before setting
-the FEATURES_OK \field{status} bit.
+the FEATURES_OK \field{device status} bit.
 
 \devicenormative{\subsubsection}{Device Initialization}{Device Types / Block Device / Device Initialization}
 
@@ -3687,7 +3690,7 @@ legacy interface:
 
 \begin{itemize}
 \item the driver MAY read or write \field{writeback} before setting
-  the DRIVER or DRIVER_OK \field{status} bit
+  the DRIVER or DRIVER_OK \field{device status} bit
 
 \item the device MUST NOT modify the cache mode (and \field{writeback})
   as a result of a driver setting a status bit, unless
-- 
2.17.0


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio-dev] Re: [RFC] content: use a consistent wording for device status

[Cornelia Huck]

On Tue, 12 Jun 2018 13:32:21 +0800
Tiwei Bie <tiwei.bie@intel.com> wrote:

> There is a part called "device status field" in a
> Virtio device. Currently, both of \field{status}
> and \field{device status} are used to refer to it,
> which is a bit confusing. This patch changes spec
> to use \field{device status} consistently.
> 
> Suggested-by: Michael S. Tsirkin <mst@redhat.com>
> Signed-off-by: Tiwei Bie <tiwei.bie@intel.com>
> ---
> If we want this change, I'll open an issue and
> send a formal patch.

Sounds good, given that there are some device-type specific 'status'
fields, which makes things confusing.

> 
>  content.tex | 21 ++++++++++++---------
>  1 file changed, 12 insertions(+), 9 deletions(-)

Patch looks good.

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio-dev] Re: [RFC] content: use a consistent wording for device status

[Tiwei Bie]

On Wed, Jun 13, 2018 at 11:05:52AM +0200, Cornelia Huck wrote:
> On Tue, 12 Jun 2018 13:32:21 +0800
> Tiwei Bie <tiwei.bie@intel.com> wrote:
> 
> > There is a part called "device status field" in a
> > Virtio device. Currently, both of \field{status}
> > and \field{device status} are used to refer to it,
> > which is a bit confusing. This patch changes spec
> > to use \field{device status} consistently.
> > 
> > Suggested-by: Michael S. Tsirkin <mst@redhat.com>
> > Signed-off-by: Tiwei Bie <tiwei.bie@intel.com>
> > ---
> > If we want this change, I'll open an issue and
> > send a formal patch.
> 
> Sounds good, given that there are some device-type specific 'status'
> fields, which makes things confusing.
> 
> > 
> >  content.tex | 21 ++++++++++++---------
> >  1 file changed, 12 insertions(+), 9 deletions(-)
> 
> Patch looks good.
> 
> Reviewed-by: Cornelia Huck <cohuck@redhat.com>

Thank you very much for the review! :)

I'll open an issue and send a new patch (just
to drop the "RFC" from the subject) with your
Reviewed-by.

Best regards,
Tiwei Bie

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org