vfio-ccw: document possible errors
Subsystems (3)
PATCH 1/1 vfio-ccw: document possible errors
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.
--- Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-)
Documentation/s390/vfio-ccw.rst +53 -1
@@ -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.
@@ -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 --------------------------
Signature · 1 line
2.21.1
Quoted 3 lines · Cornelia Huck
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.)
Quoted 37 lines
Signed-off-by Cornelia Huck <[email protected]>--- Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-)Documentation/s390/vfio-ccw.rst +22
-1@@ -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``
Documentation/s390/vfio-ccw.rst Subchannel. · line 244
Quoted 10 lines
Documentation/s390/vfio-ccw.rst +8
-0+ 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.
Quoted 32 lines
Documentation/s390/vfio-ccw.rst +23
-0@@ -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 --------------------------
Quoted 7 lines · On Fri, 17 Apr 2020 12:33:18 -0400 Eric Farman <[email protected]> wrote:
Quoted 3 lines · Cornelia Huck
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.
Quoted 15 lines
Quoted 15 lines
Signed-off-by Cornelia Huck <[email protected]>--- Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-)Documentation/s390/vfio-ccw.rst +0
-0@@ -210,7 +210,36 @@ Subchannel. irb_area stores the I/O result.
Quoted 10 lines
Documentation/s390/vfio-ccw.rst Subchannel. · line 221
Quoted 10 lines
Documentation/s390/vfio-ccw.rst +9
-1-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.
Quoted 22 lines
Quoted 22 lines
Documentation/s390/vfio-ccw.rst +21
-0+ 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.
Quoted 4 lines
Documentation/s390/vfio-ccw.rst Subchannel. · line 244
Quoted 1 line
Documentation/s390/vfio-ccw.rst +0
-0This 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.
Quoted 4 lines
But other than that suggestion, everything looks fine.
Reviewed-by Eric Farman <[email protected]>
Thanks!
Quoted 34 lines
Quoted 33 lines
Documentation/s390/vfio-ccw.rst +23
-0@@ -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 --------------------------
Quoted 8 lines · Cornelia Huck
Quoted 5 lines · On Fri, 17 Apr 2020 12:33:18 -0400 Eric Farman <[email protected]> wrote:
Quoted 3 lines · Cornelia Huck
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.
Quoted 5 lines
Quoted 2 lines
(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?
Quoted 101 lines
Quoted 16 lines
Quoted 16 lines
Signed-off-by Cornelia Huck <[email protected]>--- Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-)Documentation/s390/vfio-ccw.rst +0
-0@@ -210,7 +210,36 @@ Subchannel. irb_area stores the I/O result.Quoted 10 lines
Documentation/s390/vfio-ccw.rst Subchannel. · line 221
Quoted 10 lines
Documentation/s390/vfio-ccw.rst +9
-1-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.
Quoted 22 lines
Quoted 22 lines
Documentation/s390/vfio-ccw.rst +21
-0+ 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.Quoted 4 lines
Documentation/s390/vfio-ccw.rst Subchannel. · line 244
Quoted 1 line
Documentation/s390/vfio-ccw.rst +0
-0This 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.
Quoted 4 lines
But other than that suggestion, everything looks fine.
Reviewed-by Eric Farman <[email protected]>Thanks!
Quoted 34 lines
Quoted 33 lines
Documentation/s390/vfio-ccw.rst +23
-0@@ -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 --------------------------
Quoted 12 lines · On Tue, 26 May 2020 15:39:22 -0400 Eric Farman <[email protected]> wrote:
Quoted 11 lines · Cornelia Huck
Quoted 7 lines · On Fri, 17 Apr 2020 12:33:18 -0400 Eric Farman <[email protected]> wrote:
Quoted 3 lines · Cornelia Huck
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.)
Quoted 8 lines
Quoted 2 lines
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?
The fact that you are right :)
No need to do anything, I might have spread my own confusion here ;)
Quoted 24 lines · Cornelia Huck
Quoted 12 lines · On Tue, 26 May 2020 15:39:22 -0400 Eric Farman <[email protected]> wrote:
Quoted 11 lines · Cornelia Huck
Quoted 7 lines · On Fri, 17 Apr 2020 12:33:18 -0400 Eric Farman <[email protected]> wrote:
Quoted 3 lines · Cornelia Huck
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.)
Quoted 8 lines
Quoted 2 lines
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?
Quoted 4 lines
The fact that you are right :)
No need to do anything, I might have spread my own confusion here ;)
Oh, good. I was worried vacation was too long/short. :)
Thanks for confirming; will get back to the other things on the list instead.
Quoted 8 lines · On Tue, 7 Apr 2020 13:16:05 +0200 Cornelia Huck <[email protected]> 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.
Signed-off-by Cornelia Huck <[email protected]>--- Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-)
Queued with the mentioned minor changes.