On 4/7/20 7:16 AM, Cornelia Huck wrote: > Interacting with the I/O and the async regions can yield a number > of errors, which had been undocumented so far. These are part of > the api, so remedy that. (Makes a note to myself, to do the same for the schib/crw regions we're adding for channel path handling.) > > Signed-off-by: Cornelia Huck <cohuck@xxxxxxxxxx> > --- > Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++- > 1 file changed, 53 insertions(+), 1 deletion(-) > > diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst > index fca9c4f5bd9c..4538215a362c 100644 > --- a/Documentation/s390/vfio-ccw.rst > +++ b/Documentation/s390/vfio-ccw.rst > @@ -210,7 +210,36 @@ Subchannel. > > irb_area stores the I/O result. > > -ret_code stores a return code for each access of the region. > +ret_code stores a return code for each access of the region. The following > +values may occur: > + > +``0`` > + The operation was successful. > + > +``-EOPNOTSUPP`` > + The orb specified transport mode or an unidentified IDAW format, did not > + specify prefetch mode, or the scsw specified a function other than the > + start function. > + > +``-EIO`` > + A request was issued while the device was not in a state ready to accept > + requests, or an internal error occurred. > + > +``-EBUSY`` > + The subchannel was status pending or busy, or a request is already active. > + > +``-EAGAIN`` > + A request was being processed, and the caller should retry. > + > +``-EACCES`` > + The channel path(s) used for the I/O were found to be not operational. > + > +``-ENODEV`` > + The device was found to be not operational. > + > +``-EINVAL`` > + The orb specified a chain longer than 255 ccws, or an internal error > + occurred. > > This region is always available. Maybe move this little line up between the struct layout and "While starting an I/O request, orb_area ..." instead of being lost way down here? But other than that suggestion, everything looks fine. Reviewed-by: Eric Farman <farman@xxxxxxxxxxxxx> > > @@ -231,6 +260,29 @@ This region is exposed via region type VFIO_REGION_SUBTYPE_CCW_ASYNC_CMD. > > Currently, CLEAR SUBCHANNEL and HALT SUBCHANNEL use this region. > > +command specifies the command to be issued; ret_code stores a return code > +for each access of the region. The following values may occur: > + > +``0`` > + The operation was successful. > + > +``-ENODEV`` > + The device was found to be not operational. > + > +``-EINVAL`` > + A command other than halt or clear was specified. > + > +``-EIO`` > + A request was issued while the device was not in a state ready to accept > + requests. > + > +``-EAGAIN`` > + A request was being processed, and the caller should retry. > + > +``-EBUSY`` > + The subchannel was status pending or busy while processing a halt request. > + > + > vfio-ccw operation details > -------------------------- > >
