Commit | Line | Data |
---|---|---|
efe2938d HV |
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 | The Kernel Interface | |
31 | ==================== | |
32 | ||
33 | CEC Adapter | |
34 | ----------- | |
35 | ||
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(): | |
38 | ||
9486f2ba MCC |
39 | .. c:function:: |
40 | struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, | |
efe2938d HV |
41 | void *priv, const char *name, u32 caps, u8 available_las, |
42 | struct device *parent); | |
9486f2ba MCC |
43 | |
44 | .. c:function:: | |
45 | void cec_delete_adapter(struct cec_adapter *adap); | |
efe2938d HV |
46 | |
47 | To create an adapter you need to pass the following information: | |
48 | ||
9486f2ba MCC |
49 | ops: |
50 | adapter operations which are called by the CEC framework and that you | |
51 | have to implement. | |
efe2938d | 52 | |
9486f2ba MCC |
53 | priv: |
54 | will be stored in adap->priv and can be used by the adapter ops. | |
efe2938d | 55 | |
9486f2ba MCC |
56 | name: |
57 | the name of the CEC adapter. Note: this name will be copied. | |
efe2938d | 58 | |
9486f2ba MCC |
59 | caps: |
60 | capabilities of the CEC adapter. These capabilities determine the | |
efe2938d HV |
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 | ||
9486f2ba MCC |
65 | available_las: |
66 | the number of simultaneous logical addresses that this | |
efe2938d HV |
67 | adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. |
68 | ||
9486f2ba MCC |
69 | parent: |
70 | the parent device. | |
efe2938d HV |
71 | |
72 | ||
73 | To register the /dev/cecX device node and the remote control device (if | |
74 | CEC_CAP_RC is set) you call: | |
75 | ||
9486f2ba MCC |
76 | .. c:function:: |
77 | int cec_register_adapter(struct cec_adapter \*adap); | |
efe2938d HV |
78 | |
79 | To unregister the devices call: | |
80 | ||
9486f2ba MCC |
81 | .. c:function:: |
82 | void cec_unregister_adapter(struct cec_adapter \*adap); | |
efe2938d HV |
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 | ||
9486f2ba MCC |
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_log_status)(struct cec_adapter *adap); | |
efe2938d | 110 | |
9486f2ba MCC |
111 | /* High-level callbacks */ |
112 | ... | |
113 | }; | |
efe2938d HV |
114 | |
115 | The three low-level ops deal with various aspects of controlling the CEC adapter | |
116 | hardware: | |
117 | ||
118 | ||
119 | To enable/disable the hardware: | |
120 | ||
9486f2ba | 121 | .. c:function:: |
efe2938d HV |
122 | int (*adap_enable)(struct cec_adapter *adap, bool enable); |
123 | ||
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. | |
129 | ||
130 | Note that adap_enable must return 0 if enable is false. | |
131 | ||
132 | ||
133 | To enable/disable the 'monitor all' mode: | |
134 | ||
9486f2ba | 135 | .. c:function:: |
efe2938d HV |
136 | int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); |
137 | ||
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). | |
142 | ||
143 | Note that adap_monitor_all_enable must return 0 if enable is false. | |
144 | ||
145 | ||
146 | To program a new logical address: | |
147 | ||
9486f2ba | 148 | .. c:function:: |
efe2938d HV |
149 | int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); |
150 | ||
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. | |
156 | ||
157 | Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. | |
158 | ||
159 | ||
160 | To transmit a new message: | |
161 | ||
9486f2ba | 162 | .. c:function:: |
efe2938d HV |
163 | int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, |
164 | u32 signal_free_time, struct cec_msg *msg); | |
165 | ||
166 | This transmits a new message. The attempts argument is the suggested number of | |
167 | attempts for the transmit. | |
168 | ||
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. | |
174 | ||
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). | |
177 | ||
178 | ||
179 | To log the current CEC hardware status: | |
180 | ||
9486f2ba | 181 | .. c:function:: |
efe2938d HV |
182 | void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); |
183 | ||
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 | |
186 | ||
187 | ||
188 | Your adapter driver will also have to react to events (typically interrupt | |
189 | driven) by calling into the framework in the following situations: | |
190 | ||
191 | When a transmit finished (successfully or otherwise): | |
192 | ||
9486f2ba MCC |
193 | .. c:function:: |
194 | void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, | |
efe2938d HV |
195 | u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); |
196 | ||
197 | The status can be one of: | |
198 | ||
9486f2ba MCC |
199 | CEC_TX_STATUS_OK: |
200 | the transmit was successful. | |
201 | ||
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. | |
205 | ||
206 | CEC_TX_STATUS_NACK: | |
207 | the message was nacked (for a directed message) or | |
208 | acked (for a broadcast message). A retransmission is needed. | |
209 | ||
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 | |
213 | retransmission. | |
214 | ||
215 | CEC_TX_STATUS_ERROR: | |
216 | some unspecified error occurred: this can be one of | |
217 | the previous two if the hardware cannot differentiate or something | |
218 | else entirely. | |
219 | ||
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. | |
226 | ||
227 | The \*_cnt arguments are the number of error conditions that were seen. | |
efe2938d HV |
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. | |
233 | ||
234 | When a CEC message was received: | |
235 | ||
9486f2ba MCC |
236 | .. c:function:: |
237 | void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); | |
efe2938d HV |
238 | |
239 | Speaks for itself. | |
240 | ||
241 | Implementing the High-Level CEC Adapter | |
242 | --------------------------------------- | |
243 | ||
244 | The low-level operations drive the hardware, the high-level operations are | |
245 | CEC protocol driven. The following high-level callbacks are available: | |
246 | ||
9486f2ba | 247 | .. code-block:: none |
efe2938d | 248 | |
9486f2ba MCC |
249 | struct cec_adap_ops { |
250 | /\* Low-level callbacks \*/ | |
251 | ... | |
252 | ||
253 | /\* High-level CEC message callback \*/ | |
254 | int (\*received)(struct cec_adapter \*adap, struct cec_msg \*msg); | |
255 | }; | |
efe2938d HV |
256 | |
257 | The received() callback allows the driver to optionally handle a newly | |
258 | received CEC message | |
259 | ||
9486f2ba | 260 | .. c:function:: |
efe2938d HV |
261 | int (*received)(struct cec_adapter *adap, struct cec_msg *msg); |
262 | ||
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. | |
267 | ||
268 | ||
269 | CEC framework functions | |
270 | ----------------------- | |
271 | ||
272 | CEC Adapter drivers can call the following CEC framework functions: | |
273 | ||
9486f2ba MCC |
274 | .. c:function:: |
275 | int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, | |
276 | bool block); | |
efe2938d HV |
277 | |
278 | Transmit a CEC message. If block is true, then wait until the message has been | |
279 | transmitted, otherwise just queue it and return. | |
280 | ||
9486f2ba MCC |
281 | .. c:function:: |
282 | void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, | |
283 | bool block); | |
efe2938d HV |
284 | |
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. | |
290 | ||
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. | |
296 | ||
9486f2ba MCC |
297 | .. c:function:: |
298 | int cec_s_log_addrs(struct cec_adapter *adap, | |
299 | struct cec_log_addrs *log_addrs, bool block); | |
efe2938d HV |
300 | |
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. |