diff options
author | Hans Verkuil <hverkuil-cisco@xs4all.nl> | 2023-06-12 16:58:39 +0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@kernel.org> | 2023-08-10 08:58:32 +0300 |
commit | f807d06c72095410da8bd2d4f0acdd062c7de261 (patch) | |
tree | de15d2e76f99917e8ca9056524790de92ef1f16e /Documentation/driver-api/media | |
parent | 948a77aaecf202f722cf2264025f9987e5bd5c26 (diff) | |
download | linux-f807d06c72095410da8bd2d4f0acdd062c7de261.tar.xz |
media: Documentation: media: cec: describe new callbacks
Describe the new callbacks and clarify when the adap->lock
mutex is held or not.
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Diffstat (limited to 'Documentation/driver-api/media')
-rw-r--r-- | Documentation/driver-api/media/cec-core.rst | 44 |
1 files changed, 34 insertions, 10 deletions
diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst index ae0d20798edc..f1ffdec388f3 100644 --- a/Documentation/driver-api/media/cec-core.rst +++ b/Documentation/driver-api/media/cec-core.rst @@ -109,9 +109,11 @@ your driver: int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); - void (*adap_configured)(struct cec_adapter *adap, bool configured); + void (*adap_unconfigured)(struct cec_adapter *adap); int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, u32 signal_free_time, struct cec_msg *msg); + void (*adap_nb_transmit_canceled)(struct cec_adapter *adap, + const struct cec_msg *msg); void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); void (*adap_free)(struct cec_adapter *adap); @@ -122,8 +124,8 @@ your driver: ... }; -The seven low-level ops deal with various aspects of controlling the CEC adapter -hardware: +These low-level ops deal with various aspects of controlling the CEC adapter +hardware. They are all called with the mutex adap->lock held. To enable/disable the hardware:: @@ -179,14 +181,12 @@ can receive directed messages to that address. Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. -Called when the adapter is fully configured or unconfigured:: +Called when the adapter is unconfigured:: - void (*adap_configured)(struct cec_adapter *adap, bool configured); + void (*adap_unconfigured)(struct cec_adapter *adap); -If configured == true, then the adapter is fully configured, i.e. all logical -addresses have been successfully claimed. If configured == false, then the -adapter is unconfigured. If the driver has to take specific actions after -(un)configuration, then that can be done through this optional callback. +The adapter is unconfigured. If the driver has to take specific actions after +unconfiguration, then that can be done through this optional callback. To transmit a new message:: @@ -207,6 +207,19 @@ The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to microseconds (one data bit period is 2.4 ms). +To pass on the result of a canceled non-blocking transmit:: + + void (*adap_nb_transmit_canceled)(struct cec_adapter *adap, + const struct cec_msg *msg); + +This optional callback can be used to obtain the result of a canceled +non-blocking transmit with sequence number msg->sequence. This is +called if the transmit was aborted, the transmit timed out (i.e. the +hardware never signaled that the transmit finished), or the transmit +was successful, but the wait for the expected reply was either aborted +or it timed out. + + To log the current CEC hardware status:: void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); @@ -372,7 +385,8 @@ Implementing the High-Level CEC Adapter --------------------------------------- The low-level operations drive the hardware, the high-level operations are -CEC protocol driven. The following high-level callbacks are available: +CEC protocol driven. The high-level callbacks are called without the adap->lock +mutex being held. The following high-level callbacks are available: .. code-block:: none @@ -384,9 +398,19 @@ CEC protocol driven. The following high-level callbacks are available: ... /* High-level CEC message callback */ + void (*configured)(struct cec_adapter *adap); int (*received)(struct cec_adapter *adap, struct cec_msg *msg); }; +Called when the adapter is configured:: + + void (*configured)(struct cec_adapter *adap); + +The adapter is fully configured, i.e. all logical addresses have been +successfully claimed. If the driver has to take specific actions after +configuration, then that can be done through this optional callback. + + The received() callback allows the driver to optionally handle a newly received CEC message:: |