]>
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 | ||
39 | struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, | |
40 | void *priv, const char *name, u32 caps, u8 available_las, | |
41 | struct device *parent); | |
42 | void cec_delete_adapter(struct cec_adapter *adap); | |
43 | ||
44 | To create an adapter you need to pass the following information: | |
45 | ||
46 | ops: adapter operations which are called by the CEC framework and that you | |
47 | have to implement. | |
48 | ||
49 | priv: will be stored in adap->priv and can be used by the adapter ops. | |
50 | ||
51 | name: the name of the CEC adapter. Note: this name will be copied. | |
52 | ||
53 | caps: capabilities of the CEC adapter. These capabilities determine the | |
54 | capabilities of the hardware and which parts are to be handled | |
55 | by userspace and which parts are handled by kernelspace. The | |
56 | capabilities are returned by CEC_ADAP_G_CAPS. | |
57 | ||
58 | available_las: the number of simultaneous logical addresses that this | |
59 | adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. | |
60 | ||
61 | parent: the parent device. | |
62 | ||
63 | ||
64 | To register the /dev/cecX device node and the remote control device (if | |
65 | CEC_CAP_RC is set) you call: | |
66 | ||
67 | int cec_register_adapter(struct cec_adapter *adap); | |
68 | ||
69 | To unregister the devices call: | |
70 | ||
71 | void cec_unregister_adapter(struct cec_adapter *adap); | |
72 | ||
73 | Note: if cec_register_adapter() fails, then call cec_delete_adapter() to | |
74 | clean up. But if cec_register_adapter() succeeded, then only call | |
75 | cec_unregister_adapter() to clean up, never cec_delete_adapter(). The | |
76 | unregister function will delete the adapter automatically once the last user | |
77 | of that /dev/cecX device has closed its file handle. | |
78 | ||
79 | ||
80 | Implementing the Low-Level CEC Adapter | |
81 | -------------------------------------- | |
82 | ||
83 | The following low-level adapter operations have to be implemented in | |
84 | your driver: | |
85 | ||
86 | struct cec_adap_ops { | |
87 | /* Low-level callbacks */ | |
88 | int (*adap_enable)(struct cec_adapter *adap, bool enable); | |
89 | int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); | |
90 | int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); | |
91 | int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, | |
92 | u32 signal_free_time, struct cec_msg *msg); | |
93 | void (*adap_log_status)(struct cec_adapter *adap); | |
94 | ||
95 | /* High-level callbacks */ | |
96 | ... | |
97 | }; | |
98 | ||
99 | The three low-level ops deal with various aspects of controlling the CEC adapter | |
100 | hardware: | |
101 | ||
102 | ||
103 | To enable/disable the hardware: | |
104 | ||
105 | int (*adap_enable)(struct cec_adapter *adap, bool enable); | |
106 | ||
107 | This callback enables or disables the CEC hardware. Enabling the CEC hardware | |
108 | means powering it up in a state where no logical addresses are claimed. This | |
109 | op assumes that the physical address (adap->phys_addr) is valid when enable is | |
110 | true and will not change while the CEC adapter remains enabled. The initial | |
111 | state of the CEC adapter after calling cec_allocate_adapter() is disabled. | |
112 | ||
113 | Note that adap_enable must return 0 if enable is false. | |
114 | ||
115 | ||
116 | To enable/disable the 'monitor all' mode: | |
117 | ||
118 | int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); | |
119 | ||
120 | If enabled, then the adapter should be put in a mode to also monitor messages | |
121 | that not for us. Not all hardware supports this and this function is only | |
122 | called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional | |
123 | (some hardware may always be in 'monitor all' mode). | |
124 | ||
125 | Note that adap_monitor_all_enable must return 0 if enable is false. | |
126 | ||
127 | ||
128 | To program a new logical address: | |
129 | ||
130 | int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); | |
131 | ||
132 | If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses | |
133 | are to be erased. Otherwise the given logical address should be programmed. | |
134 | If the maximum number of available logical addresses is exceeded, then it | |
135 | should return -ENXIO. Once a logical address is programmed the CEC hardware | |
136 | can receive directed messages to that address. | |
137 | ||
138 | Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. | |
139 | ||
140 | ||
141 | To transmit a new message: | |
142 | ||
143 | int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, | |
144 | u32 signal_free_time, struct cec_msg *msg); | |
145 | ||
146 | This transmits a new message. The attempts argument is the suggested number of | |
147 | attempts for the transmit. | |
148 | ||
149 | The signal_free_time is the number of data bit periods that the adapter should | |
150 | wait when the line is free before attempting to send a message. This value | |
151 | depends on whether this transmit is a retry, a message from a new initiator or | |
152 | a new message for the same initiator. Most hardware will handle this | |
153 | automatically, but in some cases this information is needed. | |
154 | ||
155 | The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to | |
156 | microseconds (one data bit period is 2.4 ms). | |
157 | ||
158 | ||
159 | To log the current CEC hardware status: | |
160 | ||
161 | void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); | |
162 | ||
163 | This optional callback can be used to show the status of the CEC hardware. | |
164 | The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status | |
165 | ||
166 | ||
167 | Your adapter driver will also have to react to events (typically interrupt | |
168 | driven) by calling into the framework in the following situations: | |
169 | ||
170 | When a transmit finished (successfully or otherwise): | |
171 | ||
172 | void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, | |
173 | u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); | |
174 | ||
175 | The status can be one of: | |
176 | ||
177 | CEC_TX_STATUS_OK: the transmit was successful. | |
178 | CEC_TX_STATUS_ARB_LOST: arbitration was lost: another CEC initiator | |
179 | took control of the CEC line and you lost the arbitration. | |
180 | CEC_TX_STATUS_NACK: the message was nacked (for a directed message) or | |
181 | acked (for a broadcast message). A retransmission is needed. | |
182 | CEC_TX_STATUS_LOW_DRIVE: low drive was detected on the CEC bus. This | |
183 | indicates that a follower detected an error on the bus and requested a | |
184 | retransmission. | |
185 | CEC_TX_STATUS_ERROR: some unspecified error occurred: this can be one of | |
186 | the previous two if the hardware cannot differentiate or something else | |
187 | entirely. | |
188 | CEC_TX_STATUS_MAX_RETRIES: could not transmit the message after | |
189 | trying multiple times. Should only be set by the driver if it has hardware | |
190 | support for retrying messages. If set, then the framework assumes that it | |
191 | doesn't have to make another attempt to transmit the message since the | |
192 | hardware did that already. | |
193 | ||
194 | The *_cnt arguments are the number of error conditions that were seen. | |
195 | This may be 0 if no information is available. Drivers that do not support | |
196 | hardware retry can just set the counter corresponding to the transmit error | |
197 | to 1, if the hardware does support retry then either set these counters to | |
198 | 0 if the hardware provides no feedback of which errors occurred and how many | |
199 | times, or fill in the correct values as reported by the hardware. | |
200 | ||
201 | When a CEC message was received: | |
202 | ||
203 | void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); | |
204 | ||
205 | Speaks for itself. | |
206 | ||
207 | Implementing the High-Level CEC Adapter | |
208 | --------------------------------------- | |
209 | ||
210 | The low-level operations drive the hardware, the high-level operations are | |
211 | CEC protocol driven. The following high-level callbacks are available: | |
212 | ||
213 | struct cec_adap_ops { | |
214 | /* Low-level callbacks */ | |
215 | ... | |
216 | ||
217 | /* High-level CEC message callback */ | |
218 | int (*received)(struct cec_adapter *adap, struct cec_msg *msg); | |
219 | }; | |
220 | ||
221 | The received() callback allows the driver to optionally handle a newly | |
222 | received CEC message | |
223 | ||
224 | int (*received)(struct cec_adapter *adap, struct cec_msg *msg); | |
225 | ||
226 | If the driver wants to process a CEC message, then it can implement this | |
227 | callback. If it doesn't want to handle this message, then it should return | |
228 | -ENOMSG, otherwise the CEC framework assumes it processed this message and | |
229 | it will not no anything with it. | |
230 | ||
231 | ||
232 | CEC framework functions | |
233 | ----------------------- | |
234 | ||
235 | CEC Adapter drivers can call the following CEC framework functions: | |
236 | ||
237 | int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, | |
238 | bool block); | |
239 | ||
240 | Transmit a CEC message. If block is true, then wait until the message has been | |
241 | transmitted, otherwise just queue it and return. | |
242 | ||
243 | void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block); | |
244 | ||
245 | Change the physical address. This function will set adap->phys_addr and | |
246 | send an event if it has changed. If cec_s_log_addrs() has been called and | |
247 | the physical address has become valid, then the CEC framework will start | |
248 | claiming the logical addresses. If block is true, then this function won't | |
249 | return until this process has finished. | |
250 | ||
251 | When the physical address is set to a valid value the CEC adapter will | |
252 | be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID, | |
253 | then the CEC adapter will be disabled. If you change a valid physical address | |
254 | to another valid physical address, then this function will first set the | |
255 | address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. | |
256 | ||
257 | int cec_s_log_addrs(struct cec_adapter *adap, | |
258 | struct cec_log_addrs *log_addrs, bool block); | |
259 | ||
260 | Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS | |
261 | is set. If block is true, then wait until the logical addresses have been | |
262 | claimed, otherwise just queue it and return. To unconfigure all logical | |
263 | addresses call this function with log_addrs set to NULL or with | |
264 | log_addrs->num_log_addrs set to 0. The block argument is ignored when | |
265 | unconfiguring. This function will just return if the physical address is | |
266 | invalid. Once the physical address becomes valid, then the framework will | |
267 | attempt to claim these logical addresses. |