blob: 3ce26b7c2b2b6f597ea1f9532ec59c8e17073db5 [file] [log] [blame]
Mauro Carvalho Chehabf2ac8ce82018-08-30 10:20:04 -04001.. SPDX-License-Identifier: GPL-2.0
2
Hans Verkuilefe29382015-05-04 14:32:59 -03003CEC 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
Sakari Ailus3b8b2e1c2017-03-09 06:40:18 -030032CEC Adapter Interface
33---------------------
Hans Verkuilefe29382015-05-04 14:32:59 -030034
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
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030038.. c:function::
Hans Verkuilf51e8082016-11-25 06:23:34 -020039 struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, void *priv,
40 const char *name, u32 caps, u8 available_las);
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030041
42.. c:function::
43 void cec_delete_adapter(struct cec_adapter *adap);
Hans Verkuilefe29382015-05-04 14:32:59 -030044
45To create an adapter you need to pass the following information:
46
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030047ops:
48 adapter operations which are called by the CEC framework and that you
49 have to implement.
Hans Verkuilefe29382015-05-04 14:32:59 -030050
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030051priv:
52 will be stored in adap->priv and can be used by the adapter ops.
Hans Verkuil6eae60c2017-03-27 06:53:00 -030053 Use cec_get_drvdata(adap) to get the priv pointer.
Hans Verkuilefe29382015-05-04 14:32:59 -030054
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030055name:
56 the name of the CEC adapter. Note: this name will be copied.
Hans Verkuilefe29382015-05-04 14:32:59 -030057
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030058caps:
59 capabilities of the CEC adapter. These capabilities determine the
Hans Verkuilefe29382015-05-04 14:32:59 -030060 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
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030064available_las:
65 the number of simultaneous logical addresses that this
Hans Verkuilefe29382015-05-04 14:32:59 -030066 adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS.
67
Hans Verkuil6eae60c2017-03-27 06:53:00 -030068To obtain the priv pointer use this helper function:
69
70.. c:function::
71 void *cec_get_drvdata(const struct cec_adapter *adap);
Hans Verkuilefe29382015-05-04 14:32:59 -030072
73To register the /dev/cecX device node and the remote control device (if
74CEC_CAP_RC is set) you call:
75
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030076.. c:function::
Hans Verkuilf51e8082016-11-25 06:23:34 -020077 int cec_register_adapter(struct cec_adapter *adap, struct device *parent);
78
79where parent is the parent device.
Hans Verkuilefe29382015-05-04 14:32:59 -030080
81To unregister the devices call:
82
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030083.. c:function::
Hans Verkuilf51e8082016-11-25 06:23:34 -020084 void cec_unregister_adapter(struct cec_adapter *adap);
Hans Verkuilefe29382015-05-04 14:32:59 -030085
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
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -030099.. c:type:: struct cec_adap_ops
Hans Verkuilefe29382015-05-04 14:32:59 -0300100
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300101.. 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);
Hans Verkuil15ae0be2017-11-23 09:05:06 -0500108 int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable);
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300109 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);
Hans Verkuile92ca732016-11-09 06:00:53 -0200112 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
Hans Verkuilf987cde2017-07-11 03:30:37 -0300113 void (*adap_free)(struct cec_adapter *adap);
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300114
Hans Verkuil6902c882018-02-25 06:05:55 -0500115 /* Error injection callbacks */
116 ...
117
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300118 /* High-level callbacks */
119 ...
120 };
Hans Verkuilefe29382015-05-04 14:32:59 -0300121
Hans Verkuil6902c882018-02-25 06:05:55 -0500122The seven low-level ops deal with various aspects of controlling the CEC adapter
Hans Verkuilefe29382015-05-04 14:32:59 -0300123hardware:
124
125
126To enable/disable the hardware:
127
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300128.. c:function::
Hans Verkuilefe29382015-05-04 14:32:59 -0300129 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
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300142.. c:function::
Hans Verkuilefe29382015-05-04 14:32:59 -0300143 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
Hans Verkuil15ae0be2017-11-23 09:05:06 -0500153To 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
Hans Verkuilefe29382015-05-04 14:32:59 -0300166To program a new logical address:
167
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300168.. c:function::
Hans Verkuilefe29382015-05-04 14:32:59 -0300169 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
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300182.. c:function::
Hans Verkuilefe29382015-05-04 14:32:59 -0300183 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
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300201.. c:function::
Hans Verkuilefe29382015-05-04 14:32:59 -0300202 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
Hans Verkuilf987cde2017-07-11 03:30:37 -0300207To 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
Hans Verkuilefe29382015-05-04 14:32:59 -0300215
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
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300221.. c:function::
222 void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt,
Hans Verkuilefe29382015-05-04 14:32:59 -0300223 u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt);
224
Hans Verkuilc94cdc12017-06-07 11:46:10 -0300225or:
226
227.. c:function::
228 void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status);
229
Hans Verkuilefe29382015-05-04 14:32:59 -0300230The status can be one of:
231
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300232CEC_TX_STATUS_OK:
233 the transmit was successful.
Hans Verkuilefe29382015-05-04 14:32:59 -0300234
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300235CEC_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:
Hans Verkuilda634f62017-09-18 05:23:57 -0400249 some unspecified error occurred: this can be one of ARB_LOST
250 or LOW_DRIVE if the hardware cannot differentiate or something
Hans Verkuil6aecad62018-05-15 03:21:01 -0400251 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.
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300255
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
Hans Verkuilda634f62017-09-18 05:23:57 -0400263The hardware must be able to differentiate between OK, NACK and 'something
264else'.
265
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300266The \*_cnt arguments are the number of error conditions that were seen.
Hans Verkuilefe29382015-05-04 14:32:59 -0300267This 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
Hans Verkuil81e33272018-10-05 08:58:12 -0400273Be 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
Hans Verkuilc94cdc12017-06-07 11:46:10 -0300277The 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
Hans Verkuilefe29382015-05-04 14:32:59 -0300282When a CEC message was received:
283
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300284.. c:function::
285 void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);
Hans Verkuilefe29382015-05-04 14:32:59 -0300286
287Speaks for itself.
288
Hans Verkuile92ca732016-11-09 06:00:53 -0200289Implementing 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
Hans Verkuil6902c882018-02-25 06:05:55 -0500301Optional: 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
Hans Verkuilefe29382015-05-04 14:32:59 -0300365Implementing 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
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300371.. code-block:: none
Hans Verkuilefe29382015-05-04 14:32:59 -0300372
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300373 struct cec_adap_ops {
Hans Verkuile92ca732016-11-09 06:00:53 -0200374 /* Low-level callbacks */
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300375 ...
376
Hans Verkuil6902c882018-02-25 06:05:55 -0500377 /* Error injection callbacks */
378 ...
379
Hans Verkuile92ca732016-11-09 06:00:53 -0200380 /* High-level CEC message callback */
381 int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300382 };
Hans Verkuilefe29382015-05-04 14:32:59 -0300383
384The received() callback allows the driver to optionally handle a newly
385received CEC message
386
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300387.. c:function::
Hans Verkuilefe29382015-05-04 14:32:59 -0300388 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
Hans Verkuile92ca732016-11-09 06:00:53 -0200393it will not do anything with it.
Hans Verkuilefe29382015-05-04 14:32:59 -0300394
395
396CEC framework functions
397-----------------------
398
399CEC Adapter drivers can call the following CEC framework functions:
400
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300401.. c:function::
402 int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg,
403 bool block);
Hans Verkuilefe29382015-05-04 14:32:59 -0300404
405Transmit a CEC message. If block is true, then wait until the message has been
406transmitted, otherwise just queue it and return.
407
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300408.. c:function::
409 void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr,
410 bool block);
Hans Verkuilefe29382015-05-04 14:32:59 -0300411
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
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300424.. c:function::
Hans Verkuil23111ec2017-06-07 11:46:08 -0300425 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::
Mauro Carvalho Chehab9486f2b2016-08-19 08:46:13 -0300433 int cec_s_log_addrs(struct cec_adapter *adap,
434 struct cec_log_addrs *log_addrs, bool block);
Hans Verkuilefe29382015-05-04 14:32:59 -0300435
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.
Hans Verkuilab2ec7a2017-07-11 03:30:43 -0300444
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
Mauro Carvalho Chehab177894b2017-07-19 14:29:06 -0400465----------------------
Hans Verkuilab2ec7a2017-07-11 03:30:43 -0300466
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