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

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

[Peter Rosin]

Hi!

Changes since v1:
- added a short introductory paragraph to mux.rst
- added an entry in MAINTAINERS.

I forgot to mention that this applies on top of linux-next, I suspect
there will be a trivial conflict with an SPDX conversion in mux/core.c
on Linus upstream.

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   | 25 +++++++++++++++++++++++++
 MAINTAINERS                        |  1 +
 drivers/mux/core.c                 | 37 +++++++++++++++++++++++++++++++++++++
 4 files changed, 64 insertions(+)
 create mode 100644 Documentation/driver-api/mux.rst

-- 
2.11.0

[PATCH v2 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 v2 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   | 25 +++++++++++++++++++++++++
 MAINTAINERS                        |  1 +
 3 files changed, 27 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..48fc5108ff0e
--- /dev/null
+++ b/Documentation/driver-api/mux.rst
@@ -0,0 +1,25 @@
+Multiplexer Subsystem
+=====================
+
+A multiplexer is a type of device that selects one of many signals and
+forwards this signal to a single output. A variant is a demultiplexer
+that instead forwards a single input to one of many outputs. There are
+also bidirectional variants. All these variants are handled the same
+by the multiplexer subsystem, and can be used to e.g. fan out an I2C
+bus to avoid client device address collisions or to allow converting
+more signals using a single analog to digital converter.
+
+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:
diff --git a/MAINTAINERS b/MAINTAINERS
index d4fdcb12616c..2c0bbabedca0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9298,6 +9298,7 @@ M:	Peter Rosin <peda@axentia.se>
 S:	Maintained
 F:	Documentation/ABI/testing/mux/sysfs-class-mux*
 F:	Documentation/devicetree/bindings/mux/
+F:	Documentation/driver-api/mux.rst
 F:	include/linux/dt-bindings/mux/
 F:	include/linux/mux/
 F:	drivers/mux/
-- 
2.11.0

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

[Jonathan Corbet]

On Tue, 12 Dec 2017 09:46:31 +0100
Peter Rosin <peda@axentia.se> wrote:

> Changes since v1:
> - added a short introductory paragraph to mux.rst
> - added an entry in MAINTAINERS.
> 
> I forgot to mention that this applies on top of linux-next, I suspect
> there will be a trivial conflict with an SPDX conversion in mux/core.c
> on Linus upstream.

Sorry, I've had this just sitting here for a bit.  Did you want me to take
both patches through the docs tree?

Thanks,

jon

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

[Peter Rosin]

On 2017-12-21 22:35, Jonathan Corbet wrote:
> On Tue, 12 Dec 2017 09:46:31 +0100
> Peter Rosin <peda@axentia.se> wrote:
> 
>> Changes since v1:
>> - added a short introductory paragraph to mux.rst
>> - added an entry in MAINTAINERS.
>>
>> I forgot to mention that this applies on top of linux-next, I suspect
>> there will be a trivial conflict with an SPDX conversion in mux/core.c
>> on Linus upstream.
> 
> Sorry, I've had this just sitting here for a bit.  Did you want me to take
> both patches through the docs tree?

I think that's going to be easiest, thanks! Let me know if you want me
to rebase them to something w/o the SPDX change.

Cheers,
Peter

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

[Peter Rosin]

On 2017-12-21 23:11, Peter Rosin wrote:
> On 2017-12-21 22:35, Jonathan Corbet wrote:
>> On Tue, 12 Dec 2017 09:46:31 +0100
>> Peter Rosin <peda@axentia.se> wrote:
>>
>>> Changes since v1:
>>> - added a short introductory paragraph to mux.rst
>>> - added an entry in MAINTAINERS.
>>>
>>> I forgot to mention that this applies on top of linux-next, I suspect
>>> there will be a trivial conflict with an SPDX conversion in mux/core.c
>>> on Linus upstream.
>>
>> Sorry, I've had this just sitting here for a bit.  Did you want me to take
>> both patches through the docs tree?
> 
> I think that's going to be easiest, thanks! Let me know if you want me
> to rebase them to something w/o the SPDX change.

Hi,

Gentle ping...

Cheers,
Peter