| Message ID | 20210226143413.188046-3-pbonzini@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | docs: replace master/slave with more accurate wording | expand |
On Fri, Feb 26, 2021 at 09:34:12AM -0500, Paolo Bonzini wrote: > This section is using the word "back-end" to refer to the > "slave's back-end", and talking about the "client" for > what the rest of the document calls the "slave". > > Rework it to free the use of the term "back-end", which in > the next patch will replace "slave". > > Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> > --- > docs/interop/vhost-user.rst | 46 +++++++++++++++++-------------------- > 1 file changed, 21 insertions(+), 25 deletions(-) > > diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst > index 6bbc092958..028ff98eac 100644 > --- a/docs/interop/vhost-user.rst > +++ b/docs/interop/vhost-user.rst > @@ -307,40 +307,36 @@ bit was dedicated for this purpose:: > > #define VHOST_USER_F_PROTOCOL_FEATURES 30 > > -Starting and stopping rings > ---------------------------- > +Ring states > +----------- > > -Client must only process each ring when it is started. > +Rings can be in one of three states: > > -Client must only pass data between the ring and the backend, when the > -ring is enabled. > +* stopped: the slave must not process the ring at all. > > -If ring is started but disabled, client must process the ring without > -talking to the backend. > +* started but disabled: the slave must process the ring without > + causing any side effects. For example, for a networking device, > + in the disabled state the slave must not supply any new RX packets, > + but must process and discard any TX packets. > > -For example, for a networking device, in the disabled state client > -must not supply any new RX packets, but must process and discard any > -TX packets. > +* started and enabled. > > -If ``VHOST_USER_F_PROTOCOL_FEATURES`` has not been negotiated, the > -ring is initialized in an enabled state. > +Each ring is initialized in a stopped state. The slave must start > +ring upon receiving a kick (that is, detecting that file descriptor is s/ring/the ring/ > +readable) on the descriptor specified by ``VHOST_USER_SET_VRING_KICK`` > +or receiving the in-band message ``VHOST_USER_VRING_KICK`` if negotiated, > +and stop ring upon receiving ``VHOST_USER_GET_VRING_BASE``. s/ring/the ring/ > > -If ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated, the ring is > -initialized in a disabled state. Client must not pass data to/from the > -backend until ring is enabled by ``VHOST_USER_SET_VRING_ENABLE`` with > -parameter 1, or after it has been disabled by > -``VHOST_USER_SET_VRING_ENABLE`` with parameter 0. > +Rings can be enabled or disabled by ``VHOST_USER_SET_VRING_ENABLE``. > > -Each ring is initialized in a stopped state, client must not process > -it until ring is started, or after it has been stopped. > +If ``VHOST_USER_F_PROTOCOL_FEATURES`` has not been negotiated, the > +ring starts directly in the enabled state. "starts" can be confused with the started ring state but is used to mean "initialized" above. The following is clearer: "ring is initialized to the stopped but enabled state" > > -Client must start ring upon receiving a kick (that is, detecting that > -file descriptor is readable) on the descriptor specified by > -``VHOST_USER_SET_VRING_KICK`` or receiving the in-band message > -``VHOST_USER_VRING_KICK`` if negotiated, and stop ring upon receiving > -``VHOST_USER_GET_VRING_BASE``. > +If ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated, the ring is > +initialized in a disabled state and is enabled by > +``VHOST_USER_SET_VRING_ENABLE`` with parameter 1. > > -While processing the rings (whether they are enabled or not), client > +While processing the rings (whether they are enabled or not), the slave > must support changing some configuration aspects on the fly. > > Multiple queue support > -- > 2.26.2 > >
diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst index 6bbc092958..028ff98eac 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -307,40 +307,36 @@ bit was dedicated for this purpose:: #define VHOST_USER_F_PROTOCOL_FEATURES 30 -Starting and stopping rings ---------------------------- +Ring states +----------- -Client must only process each ring when it is started. +Rings can be in one of three states: -Client must only pass data between the ring and the backend, when the -ring is enabled. +* stopped: the slave must not process the ring at all. -If ring is started but disabled, client must process the ring without -talking to the backend. +* started but disabled: the slave must process the ring without + causing any side effects. For example, for a networking device, + in the disabled state the slave must not supply any new RX packets, + but must process and discard any TX packets. -For example, for a networking device, in the disabled state client -must not supply any new RX packets, but must process and discard any -TX packets. +* started and enabled. -If ``VHOST_USER_F_PROTOCOL_FEATURES`` has not been negotiated, the -ring is initialized in an enabled state. +Each ring is initialized in a stopped state. The slave must start +ring upon receiving a kick (that is, detecting that file descriptor is +readable) on the descriptor specified by ``VHOST_USER_SET_VRING_KICK`` +or receiving the in-band message ``VHOST_USER_VRING_KICK`` if negotiated, +and stop ring upon receiving ``VHOST_USER_GET_VRING_BASE``. -If ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated, the ring is -initialized in a disabled state. Client must not pass data to/from the -backend until ring is enabled by ``VHOST_USER_SET_VRING_ENABLE`` with -parameter 1, or after it has been disabled by -``VHOST_USER_SET_VRING_ENABLE`` with parameter 0. +Rings can be enabled or disabled by ``VHOST_USER_SET_VRING_ENABLE``. -Each ring is initialized in a stopped state, client must not process -it until ring is started, or after it has been stopped. +If ``VHOST_USER_F_PROTOCOL_FEATURES`` has not been negotiated, the +ring starts directly in the enabled state. -Client must start ring upon receiving a kick (that is, detecting that -file descriptor is readable) on the descriptor specified by -``VHOST_USER_SET_VRING_KICK`` or receiving the in-band message -``VHOST_USER_VRING_KICK`` if negotiated, and stop ring upon receiving -``VHOST_USER_GET_VRING_BASE``. +If ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated, the ring is +initialized in a disabled state and is enabled by +``VHOST_USER_SET_VRING_ENABLE`` with parameter 1. -While processing the rings (whether they are enabled or not), client +While processing the rings (whether they are enabled or not), the slave must support changing some configuration aspects on the fly. Multiple queue support
This section is using the word "back-end" to refer to the "slave's back-end", and talking about the "client" for what the rest of the document calls the "slave". Rework it to free the use of the term "back-end", which in the next patch will replace "slave". Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> --- docs/interop/vhost-user.rst | 46 +++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 25 deletions(-)