Skip to content

Commit 3c74b93

Browse files
numbqqnumbqq
committed
add CEC patch
Signed-off-by: Nick Xie <[email protected]>
1 parent 333a08b commit 3c74b93

38 files changed

+3736
-13
lines changed

‎Documentation/devicetree/bindings/media/cec.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Common bindings for HDMI CEC adapters
2+
3+
- hdmi-phandle: phandle to the HDMI controller.
4+
5+
- needs-hpd: if present the CEC support is only available when the HPD
6+
is high. Some boards only let the CEC pin through if the HPD is high,
7+
for example if there is a level converter that uses the HPD to power
8+
up or down.

‎Documentation/media/kapi/cec-core.rst‎

Lines changed: 381 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,381 @@
1+
CEC Kernel Support
2+
==================
3+
4+
The CEC framework provides a unified kernel interface for use with HDMI CEC
5+
hardware. It is designed to handle a multiple types of hardware (receivers,
6+
transmitters, USB dongles). The framework also gives the option to decide
7+
what to do in the kernel driver and what should be handled by userspace
8+
applications. In addition it integrates the remote control passthrough
9+
feature into the kernel's remote control framework.
10+
11+
12+
The CEC Protocol
13+
----------------
14+
15+
The CEC protocol enables consumer electronic devices to communicate with each
16+
other through the HDMI connection. The protocol uses logical addresses in the
17+
communication. The logical address is strictly connected with the functionality
18+
provided by the device. The TV acting as the communication hub is always
19+
assigned address 0. The physical address is determined by the physical
20+
connection between devices.
21+
22+
The CEC framework described here is up to date with the CEC 2.0 specification.
23+
It is documented in the HDMI 1.4 specification with the new 2.0 bits documented
24+
in the HDMI 2.0 specification. But for most of the features the freely available
25+
HDMI 1.3a specification is sufficient:
26+
27+
http://www.microprocessor.org/HDMISpecification13a.pdf
28+
29+
30+
CEC Adapter Interface
31+
---------------------
32+
33+
The struct cec_adapter represents the CEC adapter hardware. It is created by
34+
calling cec_allocate_adapter() and deleted by calling cec_delete_adapter():
35+
36+
.. c:function::
37+
struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, void *priv,
38+
const char *name, u32 caps, u8 available_las);
39+
40+
.. c:function::
41+
void cec_delete_adapter(struct cec_adapter *adap);
42+
43+
To create an adapter you need to pass the following information:
44+
45+
ops:
46+
adapter operations which are called by the CEC framework and that you
47+
have to implement.
48+
49+
priv:
50+
will be stored in adap->priv and can be used by the adapter ops.
51+
Use cec_get_drvdata(adap) to get the priv pointer.
52+
53+
name:
54+
the name of the CEC adapter. Note: this name will be copied.
55+
56+
caps:
57+
capabilities of the CEC adapter. These capabilities determine the
58+
capabilities of the hardware and which parts are to be handled
59+
by userspace and which parts are handled by kernelspace. The
60+
capabilities are returned by CEC_ADAP_G_CAPS.
61+
62+
available_las:
63+
the number of simultaneous logical addresses that this
64+
adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS.
65+
66+
To obtain the priv pointer use this helper function:
67+
68+
.. c:function::
69+
void *cec_get_drvdata(const struct cec_adapter *adap);
70+
71+
To register the /dev/cecX device node and the remote control device (if
72+
CEC_CAP_RC is set) you call:
73+
74+
.. c:function::
75+
int cec_register_adapter(struct cec_adapter *adap, struct device *parent);
76+
77+
where parent is the parent device.
78+
79+
To unregister the devices call:
80+
81+
.. c:function::
82+
void cec_unregister_adapter(struct cec_adapter *adap);
83+
84+
Note: if cec_register_adapter() fails, then call cec_delete_adapter() to
85+
clean up. But if cec_register_adapter() succeeded, then only call
86+
cec_unregister_adapter() to clean up, never cec_delete_adapter(). The
87+
unregister function will delete the adapter automatically once the last user
88+
of that /dev/cecX device has closed its file handle.
89+
90+
91+
Implementing the Low-Level CEC Adapter
92+
--------------------------------------
93+
94+
The following low-level adapter operations have to be implemented in
95+
your driver:
96+
97+
.. c:type:: struct cec_adap_ops
98+
99+
.. code-block:: none
100+
101+
struct cec_adap_ops
102+
{
103+
/* Low-level callbacks */
104+
int (*adap_enable)(struct cec_adapter *adap, bool enable);
105+
int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
106+
int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
107+
int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
108+
u32 signal_free_time, struct cec_msg *msg);
109+
void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
110+
void (*adap_free)(struct cec_adapter *adap);
111+
112+
/* High-level callbacks */
113+
...
114+
};
115+
116+
The five low-level ops deal with various aspects of controlling the CEC adapter
117+
hardware:
118+
119+
120+
To enable/disable the hardware:
121+
122+
.. c:function::
123+
int (*adap_enable)(struct cec_adapter *adap, bool enable);
124+
125+
This callback enables or disables the CEC hardware. Enabling the CEC hardware
126+
means powering it up in a state where no logical addresses are claimed. This
127+
op assumes that the physical address (adap->phys_addr) is valid when enable is
128+
true and will not change while the CEC adapter remains enabled. The initial
129+
state of the CEC adapter after calling cec_allocate_adapter() is disabled.
130+
131+
Note that adap_enable must return 0 if enable is false.
132+
133+
134+
To enable/disable the 'monitor all' mode:
135+
136+
.. c:function::
137+
int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
138+
139+
If enabled, then the adapter should be put in a mode to also monitor messages
140+
that not for us. Not all hardware supports this and this function is only
141+
called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional
142+
(some hardware may always be in 'monitor all' mode).
143+
144+
Note that adap_monitor_all_enable must return 0 if enable is false.
145+
146+
147+
To program a new logical address:
148+
149+
.. c:function::
150+
int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
151+
152+
If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses
153+
are to be erased. Otherwise the given logical address should be programmed.
154+
If the maximum number of available logical addresses is exceeded, then it
155+
should return -ENXIO. Once a logical address is programmed the CEC hardware
156+
can receive directed messages to that address.
157+
158+
Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID.
159+
160+
161+
To transmit a new message:
162+
163+
.. c:function::
164+
int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
165+
u32 signal_free_time, struct cec_msg *msg);
166+
167+
This transmits a new message. The attempts argument is the suggested number of
168+
attempts for the transmit.
169+
170+
The signal_free_time is the number of data bit periods that the adapter should
171+
wait when the line is free before attempting to send a message. This value
172+
depends on whether this transmit is a retry, a message from a new initiator or
173+
a new message for the same initiator. Most hardware will handle this
174+
automatically, but in some cases this information is needed.
175+
176+
The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to
177+
microseconds (one data bit period is 2.4 ms).
178+
179+
180+
To log the current CEC hardware status:
181+
182+
.. c:function::
183+
void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
184+
185+
This optional callback can be used to show the status of the CEC hardware.
186+
The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status
187+
188+
To free any resources when the adapter is deleted:
189+
190+
.. c:function::
191+
void (*adap_free)(struct cec_adapter *adap);
192+
193+
This optional callback can be used to free any resources that might have been
194+
allocated by the driver. It's called from cec_delete_adapter.
195+
196+
197+
Your adapter driver will also have to react to events (typically interrupt
198+
driven) by calling into the framework in the following situations:
199+
200+
When a transmit finished (successfully or otherwise):
201+
202+
.. c:function::
203+
void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt,
204+
u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt);
205+
206+
or:
207+
208+
.. c:function::
209+
void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status);
210+
211+
The status can be one of:
212+
213+
CEC_TX_STATUS_OK:
214+
the transmit was successful.
215+
216+
CEC_TX_STATUS_ARB_LOST:
217+
arbitration was lost: another CEC initiator
218+
took control of the CEC line and you lost the arbitration.
219+
220+
CEC_TX_STATUS_NACK:
221+
the message was nacked (for a directed message) or
222+
acked (for a broadcast message). A retransmission is needed.
223+
224+
CEC_TX_STATUS_LOW_DRIVE:
225+
low drive was detected on the CEC bus. This indicates that
226+
a follower detected an error on the bus and requested a
227+
retransmission.
228+
229+
CEC_TX_STATUS_ERROR:
230+
some unspecified error occurred: this can be one of ARB_LOST
231+
or LOW_DRIVE if the hardware cannot differentiate or something
232+
else entirely.
233+
234+
CEC_TX_STATUS_MAX_RETRIES:
235+
could not transmit the message after trying multiple times.
236+
Should only be set by the driver if it has hardware support for
237+
retrying messages. If set, then the framework assumes that it
238+
doesn't have to make another attempt to transmit the message
239+
since the hardware did that already.
240+
241+
The hardware must be able to differentiate between OK, NACK and 'something
242+
else'.
243+
244+
The \*_cnt arguments are the number of error conditions that were seen.
245+
This may be 0 if no information is available. Drivers that do not support
246+
hardware retry can just set the counter corresponding to the transmit error
247+
to 1, if the hardware does support retry then either set these counters to
248+
0 if the hardware provides no feedback of which errors occurred and how many
249+
times, or fill in the correct values as reported by the hardware.
250+
251+
The cec_transmit_attempt_done() function is a helper for cases where the
252+
hardware never retries, so the transmit is always for just a single
253+
attempt. It will call cec_transmit_done() in turn, filling in 1 for the
254+
count argument corresponding to the status. Or all 0 if the status was OK.
255+
256+
When a CEC message was received:
257+
258+
.. c:function::
259+
void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);
260+
261+
Speaks for itself.
262+
263+
Implementing the interrupt handler
264+
----------------------------------
265+
266+
Typically the CEC hardware provides interrupts that signal when a transmit
267+
finished and whether it was successful or not, and it provides and interrupt
268+
when a CEC message was received.
269+
270+
The CEC driver should always process the transmit interrupts first before
271+
handling the receive interrupt. The framework expects to see the cec_transmit_done
272+
call before the cec_received_msg call, otherwise it can get confused if the
273+
received message was in reply to the transmitted message.
274+
275+
Implementing the High-Level CEC Adapter
276+
---------------------------------------
277+
278+
The low-level operations drive the hardware, the high-level operations are
279+
CEC protocol driven. The following high-level callbacks are available:
280+
281+
.. code-block:: none
282+
283+
struct cec_adap_ops {
284+
/* Low-level callbacks */
285+
...
286+
287+
/* High-level CEC message callback */
288+
int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
289+
};
290+
291+
The received() callback allows the driver to optionally handle a newly
292+
received CEC message
293+
294+
.. c:function::
295+
int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
296+
297+
If the driver wants to process a CEC message, then it can implement this
298+
callback. If it doesn't want to handle this message, then it should return
299+
-ENOMSG, otherwise the CEC framework assumes it processed this message and
300+
it will not do anything with it.
301+
302+
303+
CEC framework functions
304+
-----------------------
305+
306+
CEC Adapter drivers can call the following CEC framework functions:
307+
308+
.. c:function::
309+
int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg,
310+
bool block);
311+
312+
Transmit a CEC message. If block is true, then wait until the message has been
313+
transmitted, otherwise just queue it and return.
314+
315+
.. c:function::
316+
void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr,
317+
bool block);
318+
319+
Change the physical address. This function will set adap->phys_addr and
320+
send an event if it has changed. If cec_s_log_addrs() has been called and
321+
the physical address has become valid, then the CEC framework will start
322+
claiming the logical addresses. If block is true, then this function won't
323+
return until this process has finished.
324+
325+
When the physical address is set to a valid value the CEC adapter will
326+
be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID,
327+
then the CEC adapter will be disabled. If you change a valid physical address
328+
to another valid physical address, then this function will first set the
329+
address to CEC_PHYS_ADDR_INVALID before enabling the new physical address.
330+
331+
.. c:function::
332+
void cec_s_phys_addr_from_edid(struct cec_adapter *adap,
333+
const struct edid *edid);
334+
335+
A helper function that extracts the physical address from the edid struct
336+
and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID
337+
if the EDID did not contain a physical address or edid was a NULL pointer.
338+
339+
.. c:function::
340+
int cec_s_log_addrs(struct cec_adapter *adap,
341+
struct cec_log_addrs *log_addrs, bool block);
342+
343+
Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS
344+
is set. If block is true, then wait until the logical addresses have been
345+
claimed, otherwise just queue it and return. To unconfigure all logical
346+
addresses call this function with log_addrs set to NULL or with
347+
log_addrs->num_log_addrs set to 0. The block argument is ignored when
348+
unconfiguring. This function will just return if the physical address is
349+
invalid. Once the physical address becomes valid, then the framework will
350+
attempt to claim these logical addresses.
351+
352+
CEC Pin framework
353+
-----------------
354+
355+
Most CEC hardware operates on full CEC messages where the software provides
356+
the message and the hardware handles the low-level CEC protocol. But some
357+
hardware only drives the CEC pin and software has to handle the low-level
358+
CEC protocol. The CEC pin framework was created to handle such devices.
359+
360+
Note that due to the close-to-realtime requirements it can never be guaranteed
361+
to work 100%. This framework uses highres timers internally, but if a
362+
timer goes off too late by more than 300 microseconds wrong results can
363+
occur. In reality it appears to be fairly reliable.
364+
365+
One advantage of this low-level implementation is that it can be used as
366+
a cheap CEC analyser, especially if interrupts can be used to detect
367+
CEC pin transitions from low to high or vice versa.
368+
369+
.. kernel-doc:: include/media/cec-pin.h
370+
371+
CEC Notifier framework
372+
----------------------
373+
374+
Most drm HDMI implementations have an integrated CEC implementation and no
375+
notifier support is needed. But some have independent CEC implementations
376+
that have their own driver. This could be an IP block for an SoC or a
377+
completely separate chip that deals with the CEC pin. For those cases a
378+
drm driver can install a notifier and use the notifier to inform the
379+
CEC driver about changes in the physical address.
380+
381+
.. kernel-doc:: include/media/cec-notifier.h

0 commit comments

Comments
 (0)