1.. SPDX-License-Identifier: GPL-2.0 2 3CEC Kernel Support 4================== 5 6The CEC framework provides a unified kernel interface for use with HDMI CEC 7hardware. It is designed to handle a multiple types of hardware (receivers, 8transmitters, USB dongles). The framework also gives the option to decide 9what to do in the kernel driver and what should be handled by userspace 10applications. In addition it integrates the remote control passthrough 11feature into the kernel's remote control framework. 12 13 14The CEC Protocol 15---------------- 16 17The CEC protocol enables consumer electronic devices to communicate with each 18other through the HDMI connection. The protocol uses logical addresses in the 19communication. The logical address is strictly connected with the functionality 20provided by the device. The TV acting as the communication hub is always 21assigned address 0. The physical address is determined by the physical 22connection between devices. 23 24The CEC framework described here is up to date with the CEC 2.0 specification. 25It is documented in the HDMI 1.4 specification with the new 2.0 bits documented 26in the HDMI 2.0 specification. But for most of the features the freely available 27HDMI 1.3a specification is sufficient: 28 29https://www.hdmi.org/spec/index 30 31 32CEC Adapter Interface 33--------------------- 34 35The struct cec_adapter represents the CEC adapter hardware. It is created by 36calling cec_allocate_adapter() and deleted by calling cec_delete_adapter(): 37 38.. c:function:: 39 struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, \ 40 void *priv, const char *name, \ 41 u32 caps, u8 available_las); 42 43.. c:function:: 44 void cec_delete_adapter(struct cec_adapter *adap); 45 46To create an adapter you need to pass the following information: 47 48ops: 49 adapter operations which are called by the CEC framework and that you 50 have to implement. 51 52priv: 53 will be stored in adap->priv and can be used by the adapter ops. 54 Use cec_get_drvdata(adap) to get the priv pointer. 55 56name: 57 the name of the CEC adapter. Note: this name will be copied. 58 59caps: 60 capabilities of the CEC adapter. These capabilities determine the 61 capabilities of the hardware and which parts are to be handled 62 by userspace and which parts are handled by kernelspace. The 63 capabilities are returned by CEC_ADAP_G_CAPS. 64 65available_las: 66 the number of simultaneous logical addresses that this 67 adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. 68 69To obtain the priv pointer use this helper function: 70 71.. c:function:: 72 void *cec_get_drvdata(const struct cec_adapter *adap); 73 74To register the /dev/cecX device node and the remote control device (if 75CEC_CAP_RC is set) you call: 76 77.. c:function:: 78 int cec_register_adapter(struct cec_adapter *adap, \ 79 struct device *parent); 80 81where parent is the parent device. 82 83To unregister the devices call: 84 85.. c:function:: 86 void cec_unregister_adapter(struct cec_adapter *adap); 87 88Note: if cec_register_adapter() fails, then call cec_delete_adapter() to 89clean up. But if cec_register_adapter() succeeded, then only call 90cec_unregister_adapter() to clean up, never cec_delete_adapter(). The 91unregister function will delete the adapter automatically once the last user 92of that /dev/cecX device has closed its file handle. 93 94 95Implementing the Low-Level CEC Adapter 96-------------------------------------- 97 98The following low-level adapter operations have to be implemented in 99your driver: 100 101.. c:struct:: cec_adap_ops 102 103.. code-block:: none 104 105 struct cec_adap_ops 106 { 107 /* Low-level callbacks */ 108 int (*adap_enable)(struct cec_adapter *adap, bool enable); 109 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); 110 int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); 111 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); 112 void (*adap_configured)(struct cec_adapter *adap, bool configured); 113 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, 114 u32 signal_free_time, struct cec_msg *msg); 115 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); 116 void (*adap_free)(struct cec_adapter *adap); 117 118 /* Error injection callbacks */ 119 ... 120 121 /* High-level callback */ 122 ... 123 }; 124 125The seven low-level ops deal with various aspects of controlling the CEC adapter 126hardware: 127 128 129To enable/disable the hardware:: 130 131 int (*adap_enable)(struct cec_adapter *adap, bool enable); 132 133This callback enables or disables the CEC hardware. Enabling the CEC hardware 134means powering it up in a state where no logical addresses are claimed. The 135physical address will always be valid if CEC_CAP_NEEDS_HPD is set. If that 136capability is not set, then the physical address can change while the CEC 137hardware is enabled. CEC drivers should not set CEC_CAP_NEEDS_HPD unless 138the hardware design requires that as this will make it impossible to wake 139up displays that pull the HPD low when in standby mode. The initial 140state of the CEC adapter after calling cec_allocate_adapter() is disabled. 141 142Note that adap_enable must return 0 if enable is false. 143 144 145To enable/disable the 'monitor all' mode:: 146 147 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); 148 149If enabled, then the adapter should be put in a mode to also monitor messages 150that are not for us. Not all hardware supports this and this function is only 151called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional 152(some hardware may always be in 'monitor all' mode). 153 154Note that adap_monitor_all_enable must return 0 if enable is false. 155 156 157To enable/disable the 'monitor pin' mode:: 158 159 int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); 160 161If enabled, then the adapter should be put in a mode to also monitor CEC pin 162changes. Not all hardware supports this and this function is only called if 163the CEC_CAP_MONITOR_PIN capability is set. This callback is optional 164(some hardware may always be in 'monitor pin' mode). 165 166Note that adap_monitor_pin_enable must return 0 if enable is false. 167 168 169To program a new logical address:: 170 171 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); 172 173If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses 174are to be erased. Otherwise the given logical address should be programmed. 175If the maximum number of available logical addresses is exceeded, then it 176should return -ENXIO. Once a logical address is programmed the CEC hardware 177can receive directed messages to that address. 178 179Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. 180 181 182Called when the adapter is fully configured or unconfigured:: 183 184 void (*adap_configured)(struct cec_adapter *adap, bool configured); 185 186If configured == true, then the adapter is fully configured, i.e. all logical 187addresses have been successfully claimed. If configured == false, then the 188adapter is unconfigured. If the driver has to take specific actions after 189(un)configuration, then that can be done through this optional callback. 190 191 192To transmit a new message:: 193 194 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, 195 u32 signal_free_time, struct cec_msg *msg); 196 197This transmits a new message. The attempts argument is the suggested number of 198attempts for the transmit. 199 200The signal_free_time is the number of data bit periods that the adapter should 201wait when the line is free before attempting to send a message. This value 202depends on whether this transmit is a retry, a message from a new initiator or 203a new message for the same initiator. Most hardware will handle this 204automatically, but in some cases this information is needed. 205 206The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to 207microseconds (one data bit period is 2.4 ms). 208 209 210To log the current CEC hardware status:: 211 212 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); 213 214This optional callback can be used to show the status of the CEC hardware. 215The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status 216 217To free any resources when the adapter is deleted:: 218 219 void (*adap_free)(struct cec_adapter *adap); 220 221This optional callback can be used to free any resources that might have been 222allocated by the driver. It's called from cec_delete_adapter. 223 224 225Your adapter driver will also have to react to events (typically interrupt 226driven) by calling into the framework in the following situations: 227 228When a transmit finished (successfully or otherwise):: 229 230 void cec_transmit_done(struct cec_adapter *adap, u8 status, 231 u8 arb_lost_cnt, u8 nack_cnt, u8 low_drive_cnt, 232 u8 error_cnt); 233 234or:: 235 236 void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status); 237 238The status can be one of: 239 240CEC_TX_STATUS_OK: 241 the transmit was successful. 242 243CEC_TX_STATUS_ARB_LOST: 244 arbitration was lost: another CEC initiator 245 took control of the CEC line and you lost the arbitration. 246 247CEC_TX_STATUS_NACK: 248 the message was nacked (for a directed message) or 249 acked (for a broadcast message). A retransmission is needed. 250 251CEC_TX_STATUS_LOW_DRIVE: 252 low drive was detected on the CEC bus. This indicates that 253 a follower detected an error on the bus and requested a 254 retransmission. 255 256CEC_TX_STATUS_ERROR: 257 some unspecified error occurred: this can be one of ARB_LOST 258 or LOW_DRIVE if the hardware cannot differentiate or something 259 else entirely. Some hardware only supports OK and FAIL as the 260 result of a transmit, i.e. there is no way to differentiate 261 between the different possible errors. In that case map FAIL 262 to CEC_TX_STATUS_NACK and not to CEC_TX_STATUS_ERROR. 263 264CEC_TX_STATUS_MAX_RETRIES: 265 could not transmit the message after trying multiple times. 266 Should only be set by the driver if it has hardware support for 267 retrying messages. If set, then the framework assumes that it 268 doesn't have to make another attempt to transmit the message 269 since the hardware did that already. 270 271The hardware must be able to differentiate between OK, NACK and 'something 272else'. 273 274The \*_cnt arguments are the number of error conditions that were seen. 275This may be 0 if no information is available. Drivers that do not support 276hardware retry can just set the counter corresponding to the transmit error 277to 1, if the hardware does support retry then either set these counters to 2780 if the hardware provides no feedback of which errors occurred and how many 279times, or fill in the correct values as reported by the hardware. 280 281Be aware that calling these functions can immediately start a new transmit 282if there is one pending in the queue. So make sure that the hardware is in 283a state where new transmits can be started *before* calling these functions. 284 285The cec_transmit_attempt_done() function is a helper for cases where the 286hardware never retries, so the transmit is always for just a single 287attempt. It will call cec_transmit_done() in turn, filling in 1 for the 288count argument corresponding to the status. Or all 0 if the status was OK. 289 290When a CEC message was received: 291 292.. c:function:: 293 void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); 294 295Speaks for itself. 296 297Implementing the interrupt handler 298---------------------------------- 299 300Typically the CEC hardware provides interrupts that signal when a transmit 301finished and whether it was successful or not, and it provides and interrupt 302when a CEC message was received. 303 304The CEC driver should always process the transmit interrupts first before 305handling the receive interrupt. The framework expects to see the cec_transmit_done 306call before the cec_received_msg call, otherwise it can get confused if the 307received message was in reply to the transmitted message. 308 309Optional: Implementing Error Injection Support 310---------------------------------------------- 311 312If the CEC adapter supports Error Injection functionality, then that can 313be exposed through the Error Injection callbacks: 314 315.. code-block:: none 316 317 struct cec_adap_ops { 318 /* Low-level callbacks */ 319 ... 320 321 /* Error injection callbacks */ 322 int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); 323 bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line); 324 325 /* High-level CEC message callback */ 326 ... 327 }; 328 329If both callbacks are set, then an ``error-inj`` file will appear in debugfs. 330The basic syntax is as follows: 331 332Leading spaces/tabs are ignored. If the next character is a ``#`` or the end of the 333line was reached, then the whole line is ignored. Otherwise a command is expected. 334 335This basic parsing is done in the CEC Framework. It is up to the driver to decide 336what commands to implement. The only requirement is that the command ``clear`` without 337any arguments must be implemented and that it will remove all current error injection 338commands. 339 340This ensures that you can always do ``echo clear >error-inj`` to clear any error 341injections without having to know the details of the driver-specific commands. 342 343Note that the output of ``error-inj`` shall be valid as input to ``error-inj``. 344So this must work: 345 346.. code-block:: none 347 348 $ cat error-inj >einj.txt 349 $ cat einj.txt >error-inj 350 351The first callback is called when this file is read and it should show the 352current error injection state:: 353 354 int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); 355 356It is recommended that it starts with a comment block with basic usage 357information. It returns 0 for success and an error otherwise. 358 359The second callback will parse commands written to the ``error-inj`` file:: 360 361 bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line); 362 363The ``line`` argument points to the start of the command. Any leading 364spaces or tabs have already been skipped. It is a single line only (so there 365are no embedded newlines) and it is 0-terminated. The callback is free to 366modify the contents of the buffer. It is only called for lines containing a 367command, so this callback is never called for empty lines or comment lines. 368 369Return true if the command was valid or false if there were syntax errors. 370 371Implementing the High-Level CEC Adapter 372--------------------------------------- 373 374The low-level operations drive the hardware, the high-level operations are 375CEC protocol driven. The following high-level callbacks are available: 376 377.. code-block:: none 378 379 struct cec_adap_ops { 380 /* Low-level callbacks */ 381 ... 382 383 /* Error injection callbacks */ 384 ... 385 386 /* High-level CEC message callback */ 387 int (*received)(struct cec_adapter *adap, struct cec_msg *msg); 388 }; 389 390The received() callback allows the driver to optionally handle a newly 391received CEC message:: 392 393 int (*received)(struct cec_adapter *adap, struct cec_msg *msg); 394 395If the driver wants to process a CEC message, then it can implement this 396callback. If it doesn't want to handle this message, then it should return 397-ENOMSG, otherwise the CEC framework assumes it processed this message and 398it will not do anything with it. 399 400 401CEC framework functions 402----------------------- 403 404CEC Adapter drivers can call the following CEC framework functions: 405 406.. c:function:: 407 int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, \ 408 bool block); 409 410Transmit a CEC message. If block is true, then wait until the message has been 411transmitted, otherwise just queue it and return. 412 413.. c:function:: 414 void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block); 415 416Change the physical address. This function will set adap->phys_addr and 417send an event if it has changed. If cec_s_log_addrs() has been called and 418the physical address has become valid, then the CEC framework will start 419claiming the logical addresses. If block is true, then this function won't 420return until this process has finished. 421 422When the physical address is set to a valid value the CEC adapter will 423be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID, 424then the CEC adapter will be disabled. If you change a valid physical address 425to another valid physical address, then this function will first set the 426address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. 427 428.. c:function:: 429 void cec_s_phys_addr_from_edid(struct cec_adapter *adap, \ 430 const struct edid *edid); 431 432A helper function that extracts the physical address from the edid struct 433and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID 434if the EDID did not contain a physical address or edid was a NULL pointer. 435 436.. c:function:: 437 int cec_s_log_addrs(struct cec_adapter *adap, \ 438 struct cec_log_addrs *log_addrs, bool block); 439 440Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS 441is set. If block is true, then wait until the logical addresses have been 442claimed, otherwise just queue it and return. To unconfigure all logical 443addresses call this function with log_addrs set to NULL or with 444log_addrs->num_log_addrs set to 0. The block argument is ignored when 445unconfiguring. This function will just return if the physical address is 446invalid. Once the physical address becomes valid, then the framework will 447attempt to claim these logical addresses. 448 449CEC Pin framework 450----------------- 451 452Most CEC hardware operates on full CEC messages where the software provides 453the message and the hardware handles the low-level CEC protocol. But some 454hardware only drives the CEC pin and software has to handle the low-level 455CEC protocol. The CEC pin framework was created to handle such devices. 456 457Note that due to the close-to-realtime requirements it can never be guaranteed 458to work 100%. This framework uses highres timers internally, but if a 459timer goes off too late by more than 300 microseconds wrong results can 460occur. In reality it appears to be fairly reliable. 461 462One advantage of this low-level implementation is that it can be used as 463a cheap CEC analyser, especially if interrupts can be used to detect 464CEC pin transitions from low to high or vice versa. 465 466.. kernel-doc:: include/media/cec-pin.h 467 468CEC Notifier framework 469---------------------- 470 471Most drm HDMI implementations have an integrated CEC implementation and no 472notifier support is needed. But some have independent CEC implementations 473that have their own driver. This could be an IP block for an SoC or a 474completely separate chip that deals with the CEC pin. For those cases a 475drm driver can install a notifier and use the notifier to inform the 476CEC driver about changes in the physical address. 477 478.. kernel-doc:: include/media/cec-notifier.h 479