Re: [PATCH v4 1/2] dt-bindings: gpio-mux-input: add documentation

From: Mauri Sandberg <maukka@ext.kapsi.fi>
To: Linus Walleij <linus.walleij@linaro.org>
Cc: Mauri Sandberg <sandberg@mailfence.com>,
	Andy Shevchenko <andy.shevchenko@gmail.com>,
	Bartosz Golaszewski <bgolaszewski@baylibre.com>,
	Geert Uytterhoeven <geert+renesas@glider.be>,
	"open list:GPIO SUBSYSTEM" <linux-gpio@vger.kernel.org>,
	Rob Herring <robh+dt@kernel.org>,
	"open list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS" 
	<devicetree@vger.kernel.org>,
	linux-kernel <linux-kernel@vger.kernel.org>,
	Drew Fustini <drew@beagleboard.org>
Subject: Re: [PATCH v4 1/2] dt-bindings: gpio-mux-input: add documentation
Date: Wed, 2 Jun 2021 12:31:34 +0300	[thread overview]
Message-ID: <866ff376-6d74-49c9-9e4c-2bf36bbd5981@ext.kapsi.fi> (raw)
In-Reply-To: <CACRpkdZfdd=ogHoNGuLzGGZYkvw7xtNO2VJm-t-2vMibGNy=dA@mail.gmail.com>

On 1.6.2021 13.44, Linus Walleij wrote:
> On Sun, May 30, 2021 at 6:16 PM Mauri Sandberg <maukka@ext.kapsi.fi> wrote:
>
>> Add documentation for a general GPIO multiplexer.
>>
>> Signed-off-by: Mauri Sandberg <maukka@ext.kapsi.fi>
>> Tested-by: Drew Fustini <drew@beagleboard.org>
>> Reviewed-by: Drew Fustini <drew@beagleboard.org>
> After some thinking I realized these bindings should not
> be restricted to just input. There exist electronic constructions
> such as open drain that would make it possible to mux also
> outputs.
>
>>   .../bindings/gpio/gpio-mux-input.yaml         | 75 +++++++++++++++++++
> Rename it just gpio-mux.yaml
>
>> +$id: http://devicetree.org/schemas/gpio/gpio-mux-input.yaml#
> Also here
>
>> +title: Generic GPIO input multiplexer
> Generic GPIO multiplexer
>
>> +description: |
>> +  A generic GPIO based input multiplexer
> Not just input
>
>> +  This driver uses a mux-controller to drive the multiplexer and has a single
>> +  output pin for reading the inputs to the mux.
> Make this clearer and do not mention "driver".
> Here is a suggestion:
>
> This hardware construction multiplexes (cascades) several GPIO
> lines from one-to-many using a software controlled multiplexer.
> The most common use case is probably reading several inputs
> by switching the multiplexer over several input lines, which in
> practice works well since input lines has high impedance.
>
> Constructions with multiplexed outputs are also possible using
> open drain electronics.
>
>> +  For GPIO consumer documentation see gpio.txt.
> No need to mention this I think, not your problem :D
>
>> +  pin-gpios:
> I still want this renamed like in my previous mail.
>
> Hope all is clear!
>
> Yours,
> Linus Walleij

Hi and thanks the  comments.

Generally I agree with everything you noted above and elsewhere and will 
make changes
accordingly. But there is a small detail that needs to be sorted out. 
The name 'gpio-mux'
has already been taken by 'mux-gpio' driver [2] [3].

Should we look for another name for this driver and it's bindings or 
refactor the mux-gpio's bindings
first? I would be inclined to do the latter as the config symbol for 
mux-gpio is the same way around,
MUX_GPIO.

The bindings for mux-gpio need to be converted to .yaml anyhow and maybe 
the issues with the schema
that Rob pointed out elsewhere would go away too. Otherwise I cannot 
really say what's wrong as the
errors look unrelated to me.

-- Mauri

[2] 
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/mux/gpio-mux.txt
[3] 
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/mux/gpio.c