Skip to contentSkip to conversation

vfio-ccw: document possible errors

PATCH In review Cornelia Huck 2 participants 7 messages Apr 7, 2020 – May 27, 2020

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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
index fca9c4f5bd9c..4538215a362c 100644
@@ -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
Reviewed-by on v1 1/1
#1 lore raw
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
---
 Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)
Documentation/s390/vfio-ccw.rst +22 -1
index fca9c4f5bd9c..4538215a362c 100644
@@ -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
 --------------------------
 
#2 lore raw
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
---
 Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)
Documentation/s390/vfio-ccw.rst +0 -0
index fca9c4f5bd9c..4538215a362c 100644
@@ -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 -0
 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.

Quoted 4 lines

But other than that suggestion, everything looks fine.

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
 --------------------------
 
#3 lore raw
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
---
 Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)
Documentation/s390/vfio-ccw.rst +0 -0
index fca9c4f5bd9c..4538215a362c 100644
@@ -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 -0
 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.

Quoted 4 lines

But other than that suggestion, everything looks fine.

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
 --------------------------
 
#4 lore raw
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 ;)

#5 lore raw
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.

#6 lore raw
In reply to Cornelia Huck
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.

---
 Documentation/s390/vfio-ccw.rst | 54 ++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)

Queued with the mentioned minor changes.