[PATCH 0/2] mux: add overview and add to driver-api docs

[PATCH 0/2] mux: add overview and add to driver-api docs

[Peter Rosin]

Hi!

Don't know if this is worth adding, but it might answer at least a few
questions.

It looks ok when I view the htmldocs output, but I'm not all that certain
this is good to go?

Cheers,
Peter

Peter Rosin (2):
  mux: core: add a brief overview of the subsystem
  docs: add mux docs to the driver-api docs

 Documentation/driver-api/index.rst |  1 +
 Documentation/driver-api/mux.rst   | 17 +++++++++++++++++
 drivers/mux/core.c                 | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+)
 create mode 100644 Documentation/driver-api/mux.rst

-- 
2.11.0

[PATCH 1/2] mux: core: add a brief overview of the subsystem

[Peter Rosin]

Preparation for adding the mux subsystem to the driver-api documenation.

Signed-off-by: Peter Rosin <peda@axentia.se>
---
 drivers/mux/core.c | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/drivers/mux/core.c b/drivers/mux/core.c
index d1271c1ee23c..ccb5479f8a39 100644
--- a/drivers/mux/core.c
+++ b/drivers/mux/core.c
@@ -7,6 +7,43 @@
  * Author: Peter Rosin <peda@axentia.se>
  */
 
+/**
+ * DOC: overview
+ *
+ * The multiplexer subsystem uses the following naming:
+ *
+ * - Multiplexer controller: the piece of hardware that changes the
+ *   state of a hardware multiplexer (or indeed, several parallel
+ *   multiplexers).
+ *
+ * - Multiplexer chip: a collection of multiplexer controllers, in a chip.
+ *
+ * - Multiplexer driver: the device driver that interacts with and handles the
+ *   above hardware. The driver has structures representing a mux chip and mux
+ *   controllers.
+ *
+ * - Multiplexer consumer: the driver that needs to manipulate the hardware
+ *   multiplexer.
+ *
+ * The mux subsystem provides a framework for multiplexer drivers that can
+ * be used by other consumer drivers. It has two primary purposes.
+ *
+ * First, when a consumer driver can be used with one of several multiplexers,
+ * depending on hardware configuration, the actual multiplexer is abstracted
+ * away in the mux drivers. The multiplexer consumer driver can be neater
+ * this way.
+ *
+ * Second, when two consumers -- possibly from different subsystems -- compete
+ * for the same mux controller, i.e. when one mux controller muxes more than
+ * one signal, the mux framework provides locking.
+ *
+ * If the mux driver is so special that it will only ever have a single
+ * consumer, and that consumer can really only work with that one mux driver,
+ * the mux framework is not really providing much benefit. It might be a better
+ * idea to simply manipulate the mux hardware directly from the consumer
+ * driver.
+ */
+
 #define pr_fmt(fmt) "mux-core: " fmt
 
 #include <linux/device.h>
-- 
2.11.0

[PATCH 2/2] docs: add mux docs to the driver-api docs

[Peter Rosin]

Include both the overview and the more detailed api docs.

Signed-off-by: Peter Rosin <peda@axentia.se>
---
 Documentation/driver-api/index.rst |  1 +
 Documentation/driver-api/mux.rst   | 17 +++++++++++++++++
 2 files changed, 18 insertions(+)
 create mode 100644 Documentation/driver-api/mux.rst

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d17a9876b473..d10b01b2b429 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -47,6 +47,7 @@ available subsections can be seen below.
    gpio
    misc_devices
    dmaengine/index
+   mux
 
 .. only::  subproject and html
 
diff --git a/Documentation/driver-api/mux.rst b/Documentation/driver-api/mux.rst
new file mode 100644
index 000000000000..d26d7518e9c9
--- /dev/null
+++ b/Documentation/driver-api/mux.rst
@@ -0,0 +1,17 @@
+Multiplexer Subsystem
+=====================
+
+Overview
+--------
+
+.. kernel-doc:: drivers/mux/core.c
+   :doc: overview
+
+Details
+-------
+
+.. kernel-doc:: include/linux/mux/driver.h
+   :internal:
+
+.. kernel-doc:: drivers/mux/core.c
+   :export:
-- 
2.11.0

Re: [PATCH 0/2] mux: add overview and add to driver-api docs

[Jonathan Corbet]

On Mon, 11 Dec 2017 09:29:41 +0100
Peter Rosin <peda@axentia.se> wrote:

> Don't know if this is worth adding, but it might answer at least a few
> questions.
> 
> It looks ok when I view the htmldocs output, but I'm not all that certain
> this is good to go?

Almost, but I have one request: the new mux.rst file is rather
unenlightening for somebody who reads it directly in the docs tree.  If
you want to keep the bulk of the text in the source I can live with that,
but can mux.rst at least get an introductory paragraph saying what it
covers (what *is* the mux subsystem?) and why readers might want to go
find the rest?

Thanks,

jon