On 5/8/20 6:55 AM, Cornelia Huck wrote: > On Fri, 17 Apr 2020 12:33:18 -0400 > Eric Farman <farman@xxxxxxxxxxxxx> wrote: > >> 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.) > > Yes, please :) I plan to merge this today, so you can add a patch on > top. I finally picked this up and realized that the io and async regions both document the return codes that would be stored in a field within their respective regions. The schib/crw regions don't have any such field, so the only values to be documented are the ones that the .read callback itself returns. What obvious thing am I missing? > >> >>> >>> 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 > > 'did not specify prefetch mode' needs to be dropped now, will do so > before queuing. > >>> + 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? > > Good idea, that also would match the documentation for the async region. > >> >> But other than that suggestion, everything looks fine. >> >> Reviewed-by: Eric Farman <farman@xxxxxxxxxxxxx> > > Thanks! > >> >>> >>> @@ -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 >>> -------------------------- >>> >>> >> >
