Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

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>

authored by

Hans Verkuil and committed by
Mauro Carvalho Chehab
f807d06c 948a77aa

+34 -10
+34 -10
Documentation/driver-api/media/cec-core.rst
··· 109 109 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); 110 110 int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); 111 111 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); 112 - void (*adap_configured)(struct cec_adapter *adap, bool configured); 112 + void (*adap_unconfigured)(struct cec_adapter *adap); 113 113 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, 114 114 u32 signal_free_time, struct cec_msg *msg); 115 + void (*adap_nb_transmit_canceled)(struct cec_adapter *adap, 116 + const struct cec_msg *msg); 115 117 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); 116 118 void (*adap_free)(struct cec_adapter *adap); 117 119 ··· 124 122 ... 125 123 }; 126 124 127 - The seven low-level ops deal with various aspects of controlling the CEC adapter 128 - hardware: 125 + These low-level ops deal with various aspects of controlling the CEC adapter 126 + hardware. They are all called with the mutex adap->lock held. 129 127 130 128 131 129 To enable/disable the hardware:: ··· 181 179 Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. 182 180 183 181 184 - Called when the adapter is fully configured or unconfigured:: 182 + Called when the adapter is unconfigured:: 185 183 186 - void (*adap_configured)(struct cec_adapter *adap, bool configured); 184 + void (*adap_unconfigured)(struct cec_adapter *adap); 187 185 188 - If configured == true, then the adapter is fully configured, i.e. all logical 189 - addresses have been successfully claimed. If configured == false, then the 190 - adapter is unconfigured. If the driver has to take specific actions after 191 - (un)configuration, then that can be done through this optional callback. 186 + The adapter is unconfigured. If the driver has to take specific actions after 187 + unconfiguration, then that can be done through this optional callback. 192 188 193 189 194 190 To transmit a new message:: ··· 205 205 206 206 The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to 207 207 microseconds (one data bit period is 2.4 ms). 208 + 209 + 210 + To pass on the result of a canceled non-blocking transmit:: 211 + 212 + void (*adap_nb_transmit_canceled)(struct cec_adapter *adap, 213 + const struct cec_msg *msg); 214 + 215 + This optional callback can be used to obtain the result of a canceled 216 + non-blocking transmit with sequence number msg->sequence. This is 217 + called if the transmit was aborted, the transmit timed out (i.e. the 218 + hardware never signaled that the transmit finished), or the transmit 219 + was successful, but the wait for the expected reply was either aborted 220 + or it timed out. 208 221 209 222 210 223 To log the current CEC hardware status:: ··· 385 372 --------------------------------------- 386 373 387 374 The low-level operations drive the hardware, the high-level operations are 388 - CEC protocol driven. The following high-level callbacks are available: 375 + CEC protocol driven. The high-level callbacks are called without the adap->lock 376 + mutex being held. The following high-level callbacks are available: 389 377 390 378 .. code-block:: none 391 379 ··· 398 384 ... 399 385 400 386 /* High-level CEC message callback */ 387 + void (*configured)(struct cec_adapter *adap); 401 388 int (*received)(struct cec_adapter *adap, struct cec_msg *msg); 402 389 }; 390 + 391 + Called when the adapter is configured:: 392 + 393 + void (*configured)(struct cec_adapter *adap); 394 + 395 + The adapter is fully configured, i.e. all logical addresses have been 396 + successfully claimed. If the driver has to take specific actions after 397 + configuration, then that can be done through this optional callback. 398 + 403 399 404 400 The received() callback allows the driver to optionally handle a newly 405 401 received CEC message::