[PATCH 0/3] s390: documentation update

[PATCH 0/3] s390: documentation update

[Cornelia Huck]

The first two are updates that I had around for a long time, but
somehow forgot to send them out.

While looking at the result of make pdfdocs, I found that the output
for the cmf stuff looked a bit suboptimal, so I added a bonus patch
for that.

A branch based on the s390 features branch can be found at
git://git.kernel.org/pub/scm/linux/kernel/git/cohuck/linux.git s390-doc-update

Cornelia Huck (3):
  s390/docs: mention subchannel types
  s390/docs: reword airq section
  s390/cmf: fix kerneldoc

 Documentation/driver-api/s390-drivers.rst | 32 +++++++++++++++++++++++++++----
 drivers/s390/cio/cmf.c                    | 15 ++++++++-------
 2 files changed, 36 insertions(+), 11 deletions(-)

-- 
2.13.6

[PATCH 1/3] s390/docs: mention subchannel types

[Cornelia Huck]

Since the original inception of the s390-drivers document, the
common I/O layer has grown support for more types of subchannels.
Give at least a pointer for the various types.

Signed-off-by: Cornelia Huck <cohuck@redhat.com>
---
 Documentation/driver-api/s390-drivers.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Documentation/driver-api/s390-drivers.rst b/Documentation/driver-api/s390-drivers.rst
index ecf8851d3565..42350f21357d 100644
--- a/Documentation/driver-api/s390-drivers.rst
+++ b/Documentation/driver-api/s390-drivers.rst
@@ -22,9 +22,28 @@ While most I/O devices on a s390 system are typically driven through the
 channel I/O mechanism described here, there are various other methods
 (like the diag interface). These are out of the scope of this document.
 
+The s390 common I/O layer also provides access to some devices that are
+not strictly considered I/O devices. They are considered here as well,
+although they are not the focus of this document.
+
 Some additional information can also be found in the kernel source under
 Documentation/s390/driver-model.txt.
 
+The css bus
+===========
+
+The css bus contains the subchannels available on the system. They fall
+into several categories:
+
+* Standard I/O subchannels, for use by the system. They have a child
+  device on the ccw bus and are described below.
+* I/O subchannels bound to the vfio-ccw driver. See
+  Documentation/s390/vfio-ccw.txt.
+* Message subchannels. No Linux driver currently exists.
+* CHSC subchannels (at most one). The chsc subchannel driver can be used
+  to send asynchronous chsc commands.
+* eADM subchannels. Used for talking to storage class memory.
+
 The ccw bus
 ===========
 
-- 
2.13.6

[PATCH 2/3] s390/docs: reword airq section

[Cornelia Huck]

Also mention the iv helpers as well.

Signed-off-by: Cornelia Huck <cohuck@redhat.com>
---
 Documentation/driver-api/s390-drivers.rst | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/s390-drivers.rst b/Documentation/driver-api/s390-drivers.rst
index 42350f21357d..30e6aa7e160b 100644
--- a/Documentation/driver-api/s390-drivers.rst
+++ b/Documentation/driver-api/s390-drivers.rst
@@ -121,10 +121,15 @@ ccw group devices
 Generic interfaces
 ==================
 
-Some interfaces are available to other drivers that do not necessarily
-have anything to do with the busses described above, but still are
-indirectly using basic infrastructure in the common I/O layer. One
-example is the support for adapter interrupts.
+The following section contains interfaces in use not only by drivers
+dealing with ccw devices, but drivers for various other s390 hardware
+as well.
+
+Adapter interrupts
+------------------
+
+The common I/O layer provides helper functions for dealing with adapter
+interrupts and interrupt vectors.
 
 .. kernel-doc:: drivers/s390/cio/airq.c
    :export:
-- 
2.13.6

[PATCH 3/3] s390/cmf: fix kerneldoc

[Cornelia Huck]

Make sure we use proper Return sections, and make the output
for cmf_enable() less odd.

Signed-off-by: Cornelia Huck <cohuck@redhat.com>
---
 drivers/s390/cio/cmf.c | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/drivers/s390/cio/cmf.c b/drivers/s390/cio/cmf.c
index 5e495c62cfa7..6e4f50d5b655 100644
--- a/drivers/s390/cio/cmf.c
+++ b/drivers/s390/cio/cmf.c
@@ -1118,9 +1118,10 @@ int ccw_set_cmf(struct ccw_device *cdev, int enable)
  * enable_cmf() - switch on the channel measurement for a specific device
  *  @cdev:	The ccw device to be enabled
  *
- *  Returns %0 for success or a negative error value.
- *  Note: If this is called on a device for which channel measurement is already
- *	  enabled a reset of the measurement data is triggered.
+ *  Enable channel measurements for @cdev. If this is called on a device
+ *  for which channel measurement is already enabled a reset of the
+ *  measurement data is triggered.
+ *  Returns: %0 for success or a negative error value
  *  Context:
  *    non-atomic
  */
@@ -1160,7 +1161,7 @@ int enable_cmf(struct ccw_device *cdev)
  * __disable_cmf() - switch off the channel measurement for a specific device
  *  @cdev:	The ccw device to be disabled
  *
- *  Returns %0 for success or a negative error value.
+ *  Returns: %0 for success or a negative error value.
  *
  *  Context:
  *    non-atomic, device_lock() held.
@@ -1184,7 +1185,7 @@ int __disable_cmf(struct ccw_device *cdev)
  * disable_cmf() - switch off the channel measurement for a specific device
  *  @cdev:	The ccw device to be disabled
  *
- *  Returns %0 for success or a negative error value.
+ *  Returns: %0 for success or a negative error value.
  *
  *  Context:
  *    non-atomic
@@ -1205,7 +1206,7 @@ int disable_cmf(struct ccw_device *cdev)
  * @cdev:	the channel to be read
  * @index:	the index of the value to be read
  *
- * Returns the value read or %0 if the value cannot be read.
+ * Returns: The value read or %0 if the value cannot be read.
  *
  *  Context:
  *    any
@@ -1220,7 +1221,7 @@ u64 cmf_read(struct ccw_device *cdev, int index)
  * @cdev:	the channel to be read
  * @data:	a pointer to a data block that will be filled
  *
- * Returns %0 on success, a negative error value otherwise.
+ * Returns: %0 on success, a negative error value otherwise.
  *
  *  Context:
  *    any
-- 
2.13.6

Re: [PATCH 3/3] s390/cmf: fix kerneldoc

[Sebastian Ott]

On Tue, 23 Jan 2018, Cornelia Huck wrote:
> Make sure we use proper Return sections, and make the output
> for cmf_enable() less odd.
> 
> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> ---
> +++ b/drivers/s390/cio/cmf.c
> @@ -1118,9 +1118,10 @@ int ccw_set_cmf(struct ccw_device *cdev, int enable)
>   * enable_cmf() - switch on the channel measurement for a specific device
>   *  @cdev:	The ccw device to be enabled
>   *
> - *  Returns %0 for success or a negative error value.
> - *  Note: If this is called on a device for which channel measurement is already
> - *	  enabled a reset of the measurement data is triggered.
> + *  Enable channel measurements for @cdev. If this is called on a device
> + *  for which channel measurement is already enabled a reset of the
> + *  measurement data is triggered.
> + *  Returns: %0 for success or a negative error value
                                                        ^
I took the liberty to do re-add the dot at the end..
Applied. Thanks!

Re: [PATCH 0/3] s390: documentation update

[Sebastian Ott]

On Tue, 23 Jan 2018, Cornelia Huck wrote:
> Cornelia Huck (3):
>   s390/docs: mention subchannel types
>   s390/docs: reword airq section
>   s390/cmf: fix kerneldoc

All applied. Thanks!