media/cec-core.rst: update adap_enable doc

Commit Message

Hans Verkuil June 28, 2021, 8:23 a.m. UTC

The description of adap_enable was out-of-date. Improve it so that it
corresponds to what really happens.

Signed-off-by: Hans Verkuil <[e-mail]>
---

Patch

diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst
index 56345eae9a26..c6194ee81c41 100644
--- a/Documentation/driver-api/media/cec-core.rst
+++ b/Documentation/driver-api/media/cec-core.rst
@@ -130,9 +130,12 @@  To enable/disable the hardware::
 	int (*adap_enable)(struct cec_adapter *adap, bool enable);

 This callback enables or disables the CEC hardware. Enabling the CEC hardware
-means powering it up in a state where no logical addresses are claimed. This
-op assumes that the physical address (adap->phys_addr) is valid when enable is
-true and will not change while the CEC adapter remains enabled. The initial
+means powering it up in a state where no logical addresses are claimed. The
+physical address will always be valid if CEC_CAP_NEEDS_HPD is set. If that
+capability is not set, then the physical address can change while the CEC
+hardware is enabled. CEC drivers should not set CEC_CAP_NEEDS_HPD unless
+the hardware design requires that as this will make it impossible to wake
+up displays that pull the HPD low when in standby mode.  The initial
 state of the CEC adapter after calling cec_allocate_adapter() is disabled.

 Note that adap_enable must return 0 if enable is false.