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