1 .. SPDX-License-Identifier: GPL-2.0
6 The CEC framework provides a unified kernel interface for use with HDMI CEC
7 hardware. It is designed to handle a multiple types of hardware (receivers,
8 transmitters, USB dongles). The framework also gives the option to decide
9 what to do in the kernel driver and what should be handled by userspace
10 applications. In addition it integrates the remote control passthrough
11 feature into the kernel's remote control framework.
17 The CEC protocol enables consumer electronic devices to communicate with each
18 other through the HDMI connection. The protocol uses logical addresses in the
19 communication. The logical address is strictly connected with the functionality
20 provided by the device. The TV acting as the communication hub is always
21 assigned address 0. The physical address is determined by the physical
22 connection between devices.
24 The CEC framework described here is up to date with the CEC 2.0 specification.
25 It is documented in the HDMI 1.4 specification with the new 2.0 bits documented
26 in the HDMI 2.0 specification. But for most of the features the freely available
27 HDMI 1.3a specification is sufficient:
29 https://www.hdmi.org/spec/index
35 The struct cec_adapter represents the CEC adapter hardware. It is created by
36 calling cec_allocate_adapter() and deleted by calling cec_delete_adapter():
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);
44 void cec_delete_adapter(struct cec_adapter *adap);
46 To create an adapter you need to pass the following information:
49 adapter operations which are called by the CEC framework and that you
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.
57 the name of the CEC adapter. Note: this name will be copied.
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.
66 the number of simultaneous logical addresses that this
67 adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS.
69 To obtain the priv pointer use this helper function:
72 void *cec_get_drvdata(const struct cec_adapter *adap);
74 To register the /dev/cecX device node and the remote control device (if
75 CEC_CAP_RC is set) you call:
78 int cec_register_adapter(struct cec_adapter *adap, \
79 struct device *parent);
81 where parent is the parent device.
83 To unregister the devices call:
86 void cec_unregister_adapter(struct cec_adapter *adap);
88 Note: if cec_register_adapter() fails, then call cec_delete_adapter() to
89 clean up. But if cec_register_adapter() succeeded, then only call
90 cec_unregister_adapter() to clean up, never cec_delete_adapter(). The
91 unregister function will delete the adapter automatically once the last user
92 of that /dev/cecX device has closed its file handle.
95 Implementing the Low-Level CEC Adapter
96 --------------------------------------
98 The following low-level adapter operations have to be implemented in
101 .. c:struct:: cec_adap_ops
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);
118 /* Error injection callbacks */
121 /* High-level callback */
125 The seven low-level ops deal with various aspects of controlling the CEC adapter
129 To enable/disable the hardware::
131 int (*adap_enable)(struct cec_adapter *adap, bool enable);
133 This callback enables or disables the CEC hardware. Enabling the CEC hardware
134 means powering it up in a state where no logical addresses are claimed. The
135 physical address will always be valid if CEC_CAP_NEEDS_HPD is set. If that
136 capability is not set, then the physical address can change while the CEC
137 hardware is enabled. CEC drivers should not set CEC_CAP_NEEDS_HPD unless
138 the hardware design requires that as this will make it impossible to wake
139 up displays that pull the HPD low when in standby mode. The initial
140 state of the CEC adapter after calling cec_allocate_adapter() is disabled.
142 Note that adap_enable must return 0 if enable is false.
145 To enable/disable the 'monitor all' mode::
147 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
149 If enabled, then the adapter should be put in a mode to also monitor messages
150 that are not for us. Not all hardware supports this and this function is only
151 called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional
152 (some hardware may always be in 'monitor all' mode).
154 Note that adap_monitor_all_enable must return 0 if enable is false.
157 To enable/disable the 'monitor pin' mode::
159 int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable);
161 If enabled, then the adapter should be put in a mode to also monitor CEC pin
162 changes. Not all hardware supports this and this function is only called if
163 the CEC_CAP_MONITOR_PIN capability is set. This callback is optional
164 (some hardware may always be in 'monitor pin' mode).
166 Note that adap_monitor_pin_enable must return 0 if enable is false.
169 To program a new logical address::
171 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
173 If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses
174 are to be erased. Otherwise the given logical address should be programmed.
175 If the maximum number of available logical addresses is exceeded, then it
176 should return -ENXIO. Once a logical address is programmed the CEC hardware
177 can receive directed messages to that address.
179 Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID.
182 Called when the adapter is fully configured or unconfigured::
184 void (*adap_configured)(struct cec_adapter *adap, bool configured);
186 If configured == true, then the adapter is fully configured, i.e. all logical
187 addresses have been successfully claimed. If configured == false, then the
188 adapter is unconfigured. If the driver has to take specific actions after
189 (un)configuration, then that can be done through this optional callback.
192 To transmit a new message::
194 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
195 u32 signal_free_time, struct cec_msg *msg);
197 This transmits a new message. The attempts argument is the suggested number of
198 attempts for the transmit.
200 The signal_free_time is the number of data bit periods that the adapter should
201 wait when the line is free before attempting to send a message. This value
202 depends on whether this transmit is a retry, a message from a new initiator or
203 a new message for the same initiator. Most hardware will handle this
204 automatically, but in some cases this information is needed.
206 The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to
207 microseconds (one data bit period is 2.4 ms).
210 To log the current CEC hardware status::
212 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
214 This optional callback can be used to show the status of the CEC hardware.
215 The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status
217 To free any resources when the adapter is deleted::
219 void (*adap_free)(struct cec_adapter *adap);
221 This optional callback can be used to free any resources that might have been
222 allocated by the driver. It's called from cec_delete_adapter.
225 Your adapter driver will also have to react to events (typically interrupt
226 driven) by calling into the framework in the following situations:
228 When a transmit finished (successfully or otherwise)::
230 void cec_transmit_done(struct cec_adapter *adap, u8 status,
231 u8 arb_lost_cnt, u8 nack_cnt, u8 low_drive_cnt,
236 void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status);
238 The status can be one of:
241 the transmit was successful.
243 CEC_TX_STATUS_ARB_LOST:
244 arbitration was lost: another CEC initiator
245 took control of the CEC line and you lost the arbitration.
248 the message was nacked (for a directed message) or
249 acked (for a broadcast message). A retransmission is needed.
251 CEC_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
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.
264 CEC_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.
271 The hardware must be able to differentiate between OK, NACK and 'something
274 The \*_cnt arguments are the number of error conditions that were seen.
275 This may be 0 if no information is available. Drivers that do not support
276 hardware retry can just set the counter corresponding to the transmit error
277 to 1, if the hardware does support retry then either set these counters to
278 0 if the hardware provides no feedback of which errors occurred and how many
279 times, or fill in the correct values as reported by the hardware.
281 Be aware that calling these functions can immediately start a new transmit
282 if there is one pending in the queue. So make sure that the hardware is in
283 a state where new transmits can be started *before* calling these functions.
285 The cec_transmit_attempt_done() function is a helper for cases where the
286 hardware never retries, so the transmit is always for just a single
287 attempt. It will call cec_transmit_done() in turn, filling in 1 for the
288 count argument corresponding to the status. Or all 0 if the status was OK.
290 When a CEC message was received:
293 void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);
297 Implementing the interrupt handler
298 ----------------------------------
300 Typically the CEC hardware provides interrupts that signal when a transmit
301 finished and whether it was successful or not, and it provides and interrupt
302 when a CEC message was received.
304 The CEC driver should always process the transmit interrupts first before
305 handling the receive interrupt. The framework expects to see the cec_transmit_done
306 call before the cec_received_msg call, otherwise it can get confused if the
307 received message was in reply to the transmitted message.
309 Optional: Implementing Error Injection Support
310 ----------------------------------------------
312 If the CEC adapter supports Error Injection functionality, then that can
313 be exposed through the Error Injection callbacks:
317 struct cec_adap_ops {
318 /* Low-level callbacks */
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);
325 /* High-level CEC message callback */
329 If both callbacks are set, then an ``error-inj`` file will appear in debugfs.
330 The basic syntax is as follows:
332 Leading spaces/tabs are ignored. If the next character is a ``#`` or the end of the
333 line was reached, then the whole line is ignored. Otherwise a command is expected.
335 This basic parsing is done in the CEC Framework. It is up to the driver to decide
336 what commands to implement. The only requirement is that the command ``clear`` without
337 any arguments must be implemented and that it will remove all current error injection
340 This ensures that you can always do ``echo clear >error-inj`` to clear any error
341 injections without having to know the details of the driver-specific commands.
343 Note that the output of ``error-inj`` shall be valid as input to ``error-inj``.
348 $ cat error-inj >einj.txt
349 $ cat einj.txt >error-inj
351 The first callback is called when this file is read and it should show the
352 current error injection state::
354 int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf);
356 It is recommended that it starts with a comment block with basic usage
357 information. It returns 0 for success and an error otherwise.
359 The second callback will parse commands written to the ``error-inj`` file::
361 bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line);
363 The ``line`` argument points to the start of the command. Any leading
364 spaces or tabs have already been skipped. It is a single line only (so there
365 are no embedded newlines) and it is 0-terminated. The callback is free to
366 modify the contents of the buffer. It is only called for lines containing a
367 command, so this callback is never called for empty lines or comment lines.
369 Return true if the command was valid or false if there were syntax errors.
371 Implementing the High-Level CEC Adapter
372 ---------------------------------------
374 The low-level operations drive the hardware, the high-level operations are
375 CEC protocol driven. The following high-level callbacks are available:
379 struct cec_adap_ops {
380 /* Low-level callbacks */
383 /* Error injection callbacks */
386 /* High-level CEC message callback */
387 int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
390 The received() callback allows the driver to optionally handle a newly
391 received CEC message::
393 int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
395 If the driver wants to process a CEC message, then it can implement this
396 callback. 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
398 it will not do anything with it.
401 CEC framework functions
402 -----------------------
404 CEC Adapter drivers can call the following CEC framework functions:
407 int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, \
410 Transmit a CEC message. If block is true, then wait until the message has been
411 transmitted, otherwise just queue it and return.
414 void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block);
416 Change the physical address. This function will set adap->phys_addr and
417 send an event if it has changed. If cec_s_log_addrs() has been called and
418 the physical address has become valid, then the CEC framework will start
419 claiming the logical addresses. If block is true, then this function won't
420 return until this process has finished.
422 When the physical address is set to a valid value the CEC adapter will
423 be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID,
424 then the CEC adapter will be disabled. If you change a valid physical address
425 to another valid physical address, then this function will first set the
426 address to CEC_PHYS_ADDR_INVALID before enabling the new physical address.
429 void cec_s_phys_addr_from_edid(struct cec_adapter *adap, \
430 const struct edid *edid);
432 A helper function that extracts the physical address from the edid struct
433 and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID
434 if the EDID did not contain a physical address or edid was a NULL pointer.
437 int cec_s_log_addrs(struct cec_adapter *adap, \
438 struct cec_log_addrs *log_addrs, bool block);
440 Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS
441 is set. If block is true, then wait until the logical addresses have been
442 claimed, otherwise just queue it and return. To unconfigure all logical
443 addresses call this function with log_addrs set to NULL or with
444 log_addrs->num_log_addrs set to 0. The block argument is ignored when
445 unconfiguring. This function will just return if the physical address is
446 invalid. Once the physical address becomes valid, then the framework will
447 attempt to claim these logical addresses.
452 Most CEC hardware operates on full CEC messages where the software provides
453 the message and the hardware handles the low-level CEC protocol. But some
454 hardware only drives the CEC pin and software has to handle the low-level
455 CEC protocol. The CEC pin framework was created to handle such devices.
457 Note that due to the close-to-realtime requirements it can never be guaranteed
458 to work 100%. This framework uses highres timers internally, but if a
459 timer goes off too late by more than 300 microseconds wrong results can
460 occur. In reality it appears to be fairly reliable.
462 One advantage of this low-level implementation is that it can be used as
463 a cheap CEC analyser, especially if interrupts can be used to detect
464 CEC pin transitions from low to high or vice versa.
466 .. kernel-doc:: include/media/cec-pin.h
468 CEC Notifier framework
469 ----------------------
471 Most drm HDMI implementations have an integrated CEC implementation and no
472 notifier support is needed. But some have independent CEC implementations
473 that have their own driver. This could be an IP block for an SoC or a
474 completely separate chip that deals with the CEC pin. For those cases a
475 drm driver can install a notifier and use the notifier to inform the
476 CEC driver about changes in the physical address.
478 .. kernel-doc:: include/media/cec-notifier.h