503 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3CEC Kernel Support4==================5 6The CEC framework provides a unified kernel interface for use with HDMI CEC7hardware. It is designed to handle a multiple types of hardware (receivers,8transmitters, USB dongles). The framework also gives the option to decide9what to do in the kernel driver and what should be handled by userspace10applications. In addition it integrates the remote control passthrough11feature into the kernel's remote control framework.12 13 14The CEC Protocol15----------------16 17The CEC protocol enables consumer electronic devices to communicate with each18other through the HDMI connection. The protocol uses logical addresses in the19communication. The logical address is strictly connected with the functionality20provided by the device. The TV acting as the communication hub is always21assigned address 0. The physical address is determined by the physical22connection 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 documented26in the HDMI 2.0 specification. But for most of the features the freely available27HDMI 1.3a specification is sufficient:28 29https://www.hdmi.org/spec/index30 31 32CEC Adapter Interface33---------------------34 35The struct cec_adapter represents the CEC adapter hardware. It is created by36calling 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 you50 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 the61 capabilities of the hardware and which parts are to be handled62 by userspace and which parts are handled by kernelspace. The63 capabilities are returned by CEC_ADAP_G_CAPS.64 65available_las:66 the number of simultaneous logical addresses that this67 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 (if75CEC_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() to89clean up. But if cec_register_adapter() succeeded, then only call90cec_unregister_adapter() to clean up, never cec_delete_adapter(). The91unregister function will delete the adapter automatically once the last user92of that /dev/cecX device has closed its file handle.93 94 95Implementing the Low-Level CEC Adapter96--------------------------------------97 98The following low-level adapter operations have to be implemented in99your driver:100 101.. c:struct:: cec_adap_ops102 103.. code-block:: none104 105 struct cec_adap_ops106 {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_unconfigured)(struct cec_adapter *adap);113 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,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);117 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);118 void (*adap_free)(struct cec_adapter *adap);119 120 /* Error injection callbacks */121 ...122 123 /* High-level callback */124 ...125 };126 127These low-level ops deal with various aspects of controlling the CEC adapter128hardware. They are all called with the mutex adap->lock held.129 130 131To enable/disable the hardware::132 133 int (*adap_enable)(struct cec_adapter *adap, bool enable);134 135This callback enables or disables the CEC hardware. Enabling the CEC hardware136means powering it up in a state where no logical addresses are claimed. The137physical address will always be valid if CEC_CAP_NEEDS_HPD is set. If that138capability is not set, then the physical address can change while the CEC139hardware is enabled. CEC drivers should not set CEC_CAP_NEEDS_HPD unless140the hardware design requires that as this will make it impossible to wake141up displays that pull the HPD low when in standby mode. The initial142state of the CEC adapter after calling cec_allocate_adapter() is disabled.143 144Note that adap_enable must return 0 if enable is false.145 146 147To enable/disable the 'monitor all' mode::148 149 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);150 151If enabled, then the adapter should be put in a mode to also monitor messages152that are not for us. Not all hardware supports this and this function is only153called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional154(some hardware may always be in 'monitor all' mode).155 156Note that adap_monitor_all_enable must return 0 if enable is false.157 158 159To enable/disable the 'monitor pin' mode::160 161 int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable);162 163If enabled, then the adapter should be put in a mode to also monitor CEC pin164changes. Not all hardware supports this and this function is only called if165the CEC_CAP_MONITOR_PIN capability is set. This callback is optional166(some hardware may always be in 'monitor pin' mode).167 168Note that adap_monitor_pin_enable must return 0 if enable is false.169 170 171To program a new logical address::172 173 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);174 175If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses176are to be erased. Otherwise the given logical address should be programmed.177If the maximum number of available logical addresses is exceeded, then it178should return -ENXIO. Once a logical address is programmed the CEC hardware179can receive directed messages to that address.180 181Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID.182 183 184Called when the adapter is unconfigured::185 186 void (*adap_unconfigured)(struct cec_adapter *adap);187 188The adapter is unconfigured. If the driver has to take specific actions after189unconfiguration, 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 of198attempts for the transmit.199 200The signal_free_time is the number of data bit periods that the adapter should201wait when the line is free before attempting to send a message. This value202depends on whether this transmit is a retry, a message from a new initiator or203a new message for the same initiator. Most hardware will handle this204automatically, but in some cases this information is needed.205 206The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to207microseconds (one data bit period is 2.4 ms).208 209 210To 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 215This optional callback can be used to obtain the result of a canceled216non-blocking transmit with sequence number msg->sequence. This is217called if the transmit was aborted, the transmit timed out (i.e. the218hardware never signaled that the transmit finished), or the transmit219was successful, but the wait for the expected reply was either aborted220or it timed out.221 222 223To log the current CEC hardware status::224 225 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);226 227This optional callback can be used to show the status of the CEC hardware.228The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status229 230To free any resources when the adapter is deleted::231 232 void (*adap_free)(struct cec_adapter *adap);233 234This optional callback can be used to free any resources that might have been235allocated by the driver. It's called from cec_delete_adapter.236 237 238Your adapter driver will also have to react to events (typically interrupt239driven) by calling into the framework in the following situations:240 241When a transmit finished (successfully or otherwise)::242 243 void cec_transmit_done(struct cec_adapter *adap, u8 status,244 u8 arb_lost_cnt, u8 nack_cnt, u8 low_drive_cnt,245 u8 error_cnt);246 247or::248 249 void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status);250 251The status can be one of:252 253CEC_TX_STATUS_OK:254 the transmit was successful.255 256CEC_TX_STATUS_ARB_LOST:257 arbitration was lost: another CEC initiator258 took control of the CEC line and you lost the arbitration.259 260CEC_TX_STATUS_NACK:261 the message was nacked (for a directed message) or262 acked (for a broadcast message). A retransmission is needed.263 264CEC_TX_STATUS_LOW_DRIVE:265 low drive was detected on the CEC bus. This indicates that266 a follower detected an error on the bus and requested a267 retransmission.268 269CEC_TX_STATUS_ERROR:270 some unspecified error occurred: this can be one of ARB_LOST271 or LOW_DRIVE if the hardware cannot differentiate or something272 else entirely. Some hardware only supports OK and FAIL as the273 result of a transmit, i.e. there is no way to differentiate274 between the different possible errors. In that case map FAIL275 to CEC_TX_STATUS_NACK and not to CEC_TX_STATUS_ERROR.276 277CEC_TX_STATUS_MAX_RETRIES:278 could not transmit the message after trying multiple times.279 Should only be set by the driver if it has hardware support for280 retrying messages. If set, then the framework assumes that it281 doesn't have to make another attempt to transmit the message282 since the hardware did that already.283 284The hardware must be able to differentiate between OK, NACK and 'something285else'.286 287The \*_cnt arguments are the number of error conditions that were seen.288This may be 0 if no information is available. Drivers that do not support289hardware retry can just set the counter corresponding to the transmit error290to 1, if the hardware does support retry then either set these counters to2910 if the hardware provides no feedback of which errors occurred and how many292times, or fill in the correct values as reported by the hardware.293 294Be aware that calling these functions can immediately start a new transmit295if there is one pending in the queue. So make sure that the hardware is in296a state where new transmits can be started *before* calling these functions.297 298The cec_transmit_attempt_done() function is a helper for cases where the299hardware never retries, so the transmit is always for just a single300attempt. It will call cec_transmit_done() in turn, filling in 1 for the301count argument corresponding to the status. Or all 0 if the status was OK.302 303When a CEC message was received:304 305.. c:function::306 void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);307 308Speaks for itself.309 310Implementing the interrupt handler311----------------------------------312 313Typically the CEC hardware provides interrupts that signal when a transmit314finished and whether it was successful or not, and it provides and interrupt315when a CEC message was received.316 317The CEC driver should always process the transmit interrupts first before318handling the receive interrupt. The framework expects to see the cec_transmit_done319call before the cec_received_msg call, otherwise it can get confused if the320received message was in reply to the transmitted message.321 322Optional: Implementing Error Injection Support323----------------------------------------------324 325If the CEC adapter supports Error Injection functionality, then that can326be exposed through the Error Injection callbacks:327 328.. code-block:: none329 330 struct cec_adap_ops {331 /* Low-level callbacks */332 ...333 334 /* Error injection callbacks */335 int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf);336 bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line);337 338 /* High-level CEC message callback */339 ...340 };341 342If both callbacks are set, then an ``error-inj`` file will appear in debugfs.343The basic syntax is as follows:344 345Leading spaces/tabs are ignored. If the next character is a ``#`` or the end of the346line was reached, then the whole line is ignored. Otherwise a command is expected.347 348This basic parsing is done in the CEC Framework. It is up to the driver to decide349what commands to implement. The only requirement is that the command ``clear`` without350any arguments must be implemented and that it will remove all current error injection351commands.352 353This ensures that you can always do ``echo clear >error-inj`` to clear any error354injections without having to know the details of the driver-specific commands.355 356Note that the output of ``error-inj`` shall be valid as input to ``error-inj``.357So this must work:358 359.. code-block:: none360 361 $ cat error-inj >einj.txt362 $ cat einj.txt >error-inj363 364The first callback is called when this file is read and it should show the365current error injection state::366 367 int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf);368 369It is recommended that it starts with a comment block with basic usage370information. It returns 0 for success and an error otherwise.371 372The second callback will parse commands written to the ``error-inj`` file::373 374 bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line);375 376The ``line`` argument points to the start of the command. Any leading377spaces or tabs have already been skipped. It is a single line only (so there378are no embedded newlines) and it is 0-terminated. The callback is free to379modify the contents of the buffer. It is only called for lines containing a380command, so this callback is never called for empty lines or comment lines.381 382Return true if the command was valid or false if there were syntax errors.383 384Implementing the High-Level CEC Adapter385---------------------------------------386 387The low-level operations drive the hardware, the high-level operations are388CEC protocol driven. The high-level callbacks are called without the adap->lock389mutex being held. The following high-level callbacks are available:390 391.. code-block:: none392 393 struct cec_adap_ops {394 /* Low-level callbacks */395 ...396 397 /* Error injection callbacks */398 ...399 400 /* High-level CEC message callback */401 void (*configured)(struct cec_adapter *adap);402 int (*received)(struct cec_adapter *adap, struct cec_msg *msg);403 };404 405Called when the adapter is configured::406 407 void (*configured)(struct cec_adapter *adap);408 409The adapter is fully configured, i.e. all logical addresses have been410successfully claimed. If the driver has to take specific actions after411configuration, then that can be done through this optional callback.412 413 414The received() callback allows the driver to optionally handle a newly415received CEC message::416 417 int (*received)(struct cec_adapter *adap, struct cec_msg *msg);418 419If the driver wants to process a CEC message, then it can implement this420callback. If it doesn't want to handle this message, then it should return421-ENOMSG, otherwise the CEC framework assumes it processed this message and422it will not do anything with it.423 424 425CEC framework functions426-----------------------427 428CEC Adapter drivers can call the following CEC framework functions:429 430.. c:function::431 int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, \432 bool block);433 434Transmit a CEC message. If block is true, then wait until the message has been435transmitted, otherwise just queue it and return.436 437.. c:function::438 void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block);439 440Change the physical address. This function will set adap->phys_addr and441send an event if it has changed. If cec_s_log_addrs() has been called and442the physical address has become valid, then the CEC framework will start443claiming the logical addresses. If block is true, then this function won't444return until this process has finished.445 446When the physical address is set to a valid value the CEC adapter will447be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID,448then the CEC adapter will be disabled. If you change a valid physical address449to another valid physical address, then this function will first set the450address to CEC_PHYS_ADDR_INVALID before enabling the new physical address.451 452.. c:function::453 void cec_s_phys_addr_from_edid(struct cec_adapter *adap, \454 const struct edid *edid);455 456A helper function that extracts the physical address from the edid struct457and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID458if the EDID did not contain a physical address or edid was a NULL pointer.459 460.. c:function::461 int cec_s_log_addrs(struct cec_adapter *adap, \462 struct cec_log_addrs *log_addrs, bool block);463 464Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS465is set. If block is true, then wait until the logical addresses have been466claimed, otherwise just queue it and return. To unconfigure all logical467addresses call this function with log_addrs set to NULL or with468log_addrs->num_log_addrs set to 0. The block argument is ignored when469unconfiguring. This function will just return if the physical address is470invalid. Once the physical address becomes valid, then the framework will471attempt to claim these logical addresses.472 473CEC Pin framework474-----------------475 476Most CEC hardware operates on full CEC messages where the software provides477the message and the hardware handles the low-level CEC protocol. But some478hardware only drives the CEC pin and software has to handle the low-level479CEC protocol. The CEC pin framework was created to handle such devices.480 481Note that due to the close-to-realtime requirements it can never be guaranteed482to work 100%. This framework uses highres timers internally, but if a483timer goes off too late by more than 300 microseconds wrong results can484occur. In reality it appears to be fairly reliable.485 486One advantage of this low-level implementation is that it can be used as487a cheap CEC analyser, especially if interrupts can be used to detect488CEC pin transitions from low to high or vice versa.489 490.. kernel-doc:: include/media/cec-pin.h491 492CEC Notifier framework493----------------------494 495Most drm HDMI implementations have an integrated CEC implementation and no496notifier support is needed. But some have independent CEC implementations497that have their own driver. This could be an IP block for an SoC or a498completely separate chip that deals with the CEC pin. For those cases a499drm driver can install a notifier and use the notifier to inform the500CEC driver about changes in the physical address.501 502.. kernel-doc:: include/media/cec-notifier.h503