[PATCHv4 3/5] dt-bindings: document the CEC GPIO bindings

[Hans Verkuil]

On 09/12/2017 04:43 PM, Rob Herring wrote:
> On Thu, Aug 31, 2017 at 01:01:54PM +0200, Hans Verkuil wrote:
>> From: Hans Verkuil <hans.verkuil at cisco.com>
>>
>> Document the bindings for the cec-gpio module for hardware where the
>> CEC line and optionally the HPD line are connected to GPIO lines.
>>
>> Signed-off-by: Hans Verkuil <hans.verkuil at cisco.com>
>> ---
>>  .../devicetree/bindings/media/cec-gpio.txt         | 22 ++++++++++++++++++++++
>>  1 file changed, 22 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/media/cec-gpio.txt
>>
>> diff --git a/Documentation/devicetree/bindings/media/cec-gpio.txt b/Documentation/devicetree/bindings/media/cec-gpio.txt
>> new file mode 100644
>> index 000000000000..db20a7452dbd
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/media/cec-gpio.txt
>> @@ -0,0 +1,22 @@
>> +* HDMI CEC GPIO driver
>> +
>> +The HDMI CEC GPIO module supports CEC implementations where the CEC line
>> +is hooked up to a pull-up GPIO line and - optionally - the HPD line is
>> +hooked up to another GPIO line.
>> +
>> +Required properties:
>> +  - compatible: value must be "cec-gpio"
>> +  - cec-gpio: gpio that the CEC line is connected to
> 
> cec-gpios

Will change.

> 
>> +
>> +Optional property:
>> +  - hpd-gpio: gpio that the HPD line is connected to
> 
> hpd-gpios

Will change.

> 
> However, HPD is already part of the HDMI connector binding. Having it in 
> 2 places would be wrong.

No. This is not an HDMI receiver/transmitter. There are two use-cases for this
driver:

1) For HDMI receivers/transmitters that connect the CEC pin of an HDMI connector
   to a GPIO pin. In that case the HPD goes to the HDMI transmitter/receiver and
   not to this driver. As you say, that would not make any sense.

   But currently no such devices are in the kernel (I know they exist, though).
   Once such a driver would appear in the kernel then these bindings need to be
   extended with an hdmi-phandle.

2) This driver is used for debugging CEC like this:

	https://hverkuil.home.xs4all.nl/rpi3-cec.jpg

   Here the CEC pin of an HDMI breakout connector is hooked up to a Raspberry Pi
   GPIO pin and the RPi monitors it. It's a cheap but very effective CEC analyzer.
   In this use-case it is very helpful to also monitor the HPD pin since some
   displays do weird things with the HPD and knowing the state of the HPD helps
   a lot when debugging CEC problems. It's optional and it only monitors the pin.

   Actually, there does not have to be an HDMI connector involved at all: you can
   make two cec-gpio instances and just connect the two GPIO pins together in
   order to emulate two CEC adapters and play with that.

> 
> I think we should have either:
> 
> hdmi-connector {
> 	compatible = 'hdmi-connector-a";
> 	hpd-gpios = <...>;
> 	cec-gpios = <...>;
> 	ports {
> 		// port to HDMI controller
> 	...
> 	};
> };
> 
> Or:
> 
> hdmi-connector {
>         compatible = 'hdmi-connector-a";
>         hpd-gpios = <...>;
>         cec = <&cec>;
>         ... 
> };
> 
> cec: cec-gpio {
> 	compatible = "cec-gpio";
> 	cec-gpios = <...>;
> };
> 
> My preference is probably the former. The latter just helps create a 
> device to bind to a driver, but DT is not the only way to create 
> devices. Then again, if you have a phandle to real CEC controllers in 
> the HDMI connector node, it may make sense to do the same thing with 
> cec-gpio. 
> 
>> +
>> +Example for the Raspberry Pi 3 where the CEC line is connected to
>> +pin 26 aka BCM7 aka CE1 on the GPIO pin header and the HPD line is
>> +connected to pin 11 aka BCM17:
>> +
>> +cec-gpio at 7 {
> 
> unit address is not valid. Build your dts's with W=2.

I'll do that.

> 
>> +       compatible = "cec-gpio";
>> +       cec-gpio = <&gpio 7 GPIO_OPEN_DRAIN>;
>> +       hpd-gpio = <&gpio 17 GPIO_ACTIVE_HIGH>;
>> +};
>> -- 
>> 2.14.1

Regards,

	Hans