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