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.
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.
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:
27 http://www.microprocessor.org/HDMISpecification13a.pdf
36 The struct cec_adapter represents the CEC adapter hardware. It is created by
37 calling cec_allocate_adapter() and deleted by calling cec_delete_adapter():
40 struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops,
41 void *priv, const char *name, u32 caps, u8 available_las,
42 struct device *parent);
45 void cec_delete_adapter(struct cec_adapter *adap);
47 To create an adapter you need to pass the following information:
50 adapter operations which are called by the CEC framework and that you
54 will be stored in adap->priv and can be used by the adapter ops.
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.
73 To register the /dev/cecX device node and the remote control device (if
74 CEC_CAP_RC is set) you call:
77 int cec_register_adapter(struct cec_adapter \*adap);
79 To unregister the devices call:
82 void cec_unregister_adapter(struct cec_adapter \*adap);
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.
91 Implementing the Low-Level CEC Adapter
92 --------------------------------------
94 The following low-level adapter operations have to be implemented in
97 .. c:type:: struct cec_adap_ops
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_log_status)(struct cec_adapter *adap);
111 /* High-level callbacks */
115 The three low-level ops deal with various aspects of controlling the CEC adapter
119 To enable/disable the hardware:
122 int (*adap_enable)(struct cec_adapter *adap, bool enable);
124 This callback enables or disables the CEC hardware. Enabling the CEC hardware
125 means powering it up in a state where no logical addresses are claimed. This
126 op assumes that the physical address (adap->phys_addr) is valid when enable is
127 true and will not change while the CEC adapter remains enabled. The initial
128 state of the CEC adapter after calling cec_allocate_adapter() is disabled.
130 Note that adap_enable must return 0 if enable is false.
133 To enable/disable the 'monitor all' mode:
136 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
138 If enabled, then the adapter should be put in a mode to also monitor messages
139 that not for us. Not all hardware supports this and this function is only
140 called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional
141 (some hardware may always be in 'monitor all' mode).
143 Note that adap_monitor_all_enable must return 0 if enable is false.
146 To program a new logical address:
149 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
151 If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses
152 are to be erased. Otherwise the given logical address should be programmed.
153 If the maximum number of available logical addresses is exceeded, then it
154 should return -ENXIO. Once a logical address is programmed the CEC hardware
155 can receive directed messages to that address.
157 Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID.
160 To transmit a new message:
163 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
164 u32 signal_free_time, struct cec_msg *msg);
166 This transmits a new message. The attempts argument is the suggested number of
167 attempts for the transmit.
169 The signal_free_time is the number of data bit periods that the adapter should
170 wait when the line is free before attempting to send a message. This value
171 depends on whether this transmit is a retry, a message from a new initiator or
172 a new message for the same initiator. Most hardware will handle this
173 automatically, but in some cases this information is needed.
175 The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to
176 microseconds (one data bit period is 2.4 ms).
179 To log the current CEC hardware status:
182 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
184 This optional callback can be used to show the status of the CEC hardware.
185 The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status
188 Your adapter driver will also have to react to events (typically interrupt
189 driven) by calling into the framework in the following situations:
191 When a transmit finished (successfully or otherwise):
194 void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt,
195 u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt);
197 The status can be one of:
200 the transmit was successful.
202 CEC_TX_STATUS_ARB_LOST:
203 arbitration was lost: another CEC initiator
204 took control of the CEC line and you lost the arbitration.
207 the message was nacked (for a directed message) or
208 acked (for a broadcast message). A retransmission is needed.
210 CEC_TX_STATUS_LOW_DRIVE:
211 low drive was detected on the CEC bus. This indicates that
212 a follower detected an error on the bus and requested a
216 some unspecified error occurred: this can be one of
217 the previous two if the hardware cannot differentiate or something
220 CEC_TX_STATUS_MAX_RETRIES:
221 could not transmit the message after trying multiple times.
222 Should only be set by the driver if it has hardware support for
223 retrying messages. If set, then the framework assumes that it
224 doesn't have to make another attempt to transmit the message
225 since the hardware did that already.
227 The \*_cnt arguments are the number of error conditions that were seen.
228 This may be 0 if no information is available. Drivers that do not support
229 hardware retry can just set the counter corresponding to the transmit error
230 to 1, if the hardware does support retry then either set these counters to
231 0 if the hardware provides no feedback of which errors occurred and how many
232 times, or fill in the correct values as reported by the hardware.
234 When a CEC message was received:
237 void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);
241 Implementing the High-Level CEC Adapter
242 ---------------------------------------
244 The low-level operations drive the hardware, the high-level operations are
245 CEC protocol driven. The following high-level callbacks are available:
249 struct cec_adap_ops {
250 /\* Low-level callbacks \*/
253 /\* High-level CEC message callback \*/
254 int (\*received)(struct cec_adapter \*adap, struct cec_msg \*msg);
257 The received() callback allows the driver to optionally handle a newly
261 int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
263 If the driver wants to process a CEC message, then it can implement this
264 callback. If it doesn't want to handle this message, then it should return
265 -ENOMSG, otherwise the CEC framework assumes it processed this message and
266 it will not no anything with it.
269 CEC framework functions
270 -----------------------
272 CEC Adapter drivers can call the following CEC framework functions:
275 int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg,
278 Transmit a CEC message. If block is true, then wait until the message has been
279 transmitted, otherwise just queue it and return.
282 void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr,
285 Change the physical address. This function will set adap->phys_addr and
286 send an event if it has changed. If cec_s_log_addrs() has been called and
287 the physical address has become valid, then the CEC framework will start
288 claiming the logical addresses. If block is true, then this function won't
289 return until this process has finished.
291 When the physical address is set to a valid value the CEC adapter will
292 be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID,
293 then the CEC adapter will be disabled. If you change a valid physical address
294 to another valid physical address, then this function will first set the
295 address to CEC_PHYS_ADDR_INVALID before enabling the new physical address.
298 int cec_s_log_addrs(struct cec_adapter *adap,
299 struct cec_log_addrs *log_addrs, bool block);
301 Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS
302 is set. If block is true, then wait until the logical addresses have been
303 claimed, otherwise just queue it and return. To unconfigure all logical
304 addresses call this function with log_addrs set to NULL or with
305 log_addrs->num_log_addrs set to 0. The block argument is ignored when
306 unconfiguring. This function will just return if the physical address is
307 invalid. Once the physical address becomes valid, then the framework will
308 attempt to claim these logical addresses.