Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Sakari Ailus | 3b8b2e1c | 2017-03-09 06:40:18 -0300 | [diff] [blame] | 30 | CEC Adapter Interface |
| 31 | --------------------- |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 36 | .. c:function:: |
Hans Verkuil | f51e808 | 2016-11-25 06:23:34 -0200 | [diff] [blame] | 37 | struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, void *priv, |
| 38 | const char *name, u32 caps, u8 available_las); |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 39 | |
| 40 | .. c:function:: |
| 41 | void cec_delete_adapter(struct cec_adapter *adap); |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 42 | |
| 43 | To create an adapter you need to pass the following information: |
| 44 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 45 | ops: |
| 46 | adapter operations which are called by the CEC framework and that you |
| 47 | have to implement. |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 48 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 49 | priv: |
| 50 | will be stored in adap->priv and can be used by the adapter ops. |
Hans Verkuil | 6eae60c | 2017-03-27 06:53:00 -0300 | [diff] [blame] | 51 | Use cec_get_drvdata(adap) to get the priv pointer. |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 52 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 53 | name: |
| 54 | the name of the CEC adapter. Note: this name will be copied. |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 55 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 56 | caps: |
| 57 | capabilities of the CEC adapter. These capabilities determine the |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 62 | available_las: |
| 63 | the number of simultaneous logical addresses that this |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 64 | adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. |
| 65 | |
Hans Verkuil | 6eae60c | 2017-03-27 06:53:00 -0300 | [diff] [blame] | 66 | To obtain the priv pointer use this helper function: |
| 67 | |
| 68 | .. c:function:: |
| 69 | void *cec_get_drvdata(const struct cec_adapter *adap); |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 70 | |
| 71 | To register the /dev/cecX device node and the remote control device (if |
| 72 | CEC_CAP_RC is set) you call: |
| 73 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 74 | .. c:function:: |
Hans Verkuil | f51e808 | 2016-11-25 06:23:34 -0200 | [diff] [blame] | 75 | int cec_register_adapter(struct cec_adapter *adap, struct device *parent); |
| 76 | |
| 77 | where parent is the parent device. |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 78 | |
| 79 | To unregister the devices call: |
| 80 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 81 | .. c:function:: |
Hans Verkuil | f51e808 | 2016-11-25 06:23:34 -0200 | [diff] [blame] | 82 | void cec_unregister_adapter(struct cec_adapter *adap); |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 97 | .. c:type:: struct cec_adap_ops |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 98 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 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); |
Hans Verkuil | e92ca73 | 2016-11-09 06:00:53 -0200 | [diff] [blame] | 109 | void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 110 | |
| 111 | /* High-level callbacks */ |
| 112 | ... |
| 113 | }; |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 114 | |
Hans Verkuil | e92ca73 | 2016-11-09 06:00:53 -0200 | [diff] [blame] | 115 | The five low-level ops deal with various aspects of controlling the CEC adapter |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 116 | hardware: |
| 117 | |
| 118 | |
| 119 | To enable/disable the hardware: |
| 120 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 121 | .. c:function:: |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 135 | .. c:function:: |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 148 | .. c:function:: |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 162 | .. c:function:: |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 181 | .. c:function:: |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 193 | .. c:function:: |
| 194 | void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 195 | u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); |
| 196 | |
| 197 | The status can be one of: |
| 198 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 199 | CEC_TX_STATUS_OK: |
| 200 | the transmit was successful. |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 201 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 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. |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 236 | .. c:function:: |
| 237 | void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 238 | |
| 239 | Speaks for itself. |
| 240 | |
Hans Verkuil | e92ca73 | 2016-11-09 06:00:53 -0200 | [diff] [blame] | 241 | Implementing the interrupt handler |
| 242 | ---------------------------------- |
| 243 | |
| 244 | Typically the CEC hardware provides interrupts that signal when a transmit |
| 245 | finished and whether it was successful or not, and it provides and interrupt |
| 246 | when a CEC message was received. |
| 247 | |
| 248 | The CEC driver should always process the transmit interrupts first before |
| 249 | handling the receive interrupt. The framework expects to see the cec_transmit_done |
| 250 | call before the cec_received_msg call, otherwise it can get confused if the |
| 251 | received message was in reply to the transmitted message. |
| 252 | |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 253 | Implementing the High-Level CEC Adapter |
| 254 | --------------------------------------- |
| 255 | |
| 256 | The low-level operations drive the hardware, the high-level operations are |
| 257 | CEC protocol driven. The following high-level callbacks are available: |
| 258 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 259 | .. code-block:: none |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 260 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 261 | struct cec_adap_ops { |
Hans Verkuil | e92ca73 | 2016-11-09 06:00:53 -0200 | [diff] [blame] | 262 | /* Low-level callbacks */ |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 263 | ... |
| 264 | |
Hans Verkuil | e92ca73 | 2016-11-09 06:00:53 -0200 | [diff] [blame] | 265 | /* High-level CEC message callback */ |
| 266 | int (*received)(struct cec_adapter *adap, struct cec_msg *msg); |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 267 | }; |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 268 | |
| 269 | The received() callback allows the driver to optionally handle a newly |
| 270 | received CEC message |
| 271 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 272 | .. c:function:: |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 273 | int (*received)(struct cec_adapter *adap, struct cec_msg *msg); |
| 274 | |
| 275 | If the driver wants to process a CEC message, then it can implement this |
| 276 | callback. If it doesn't want to handle this message, then it should return |
| 277 | -ENOMSG, otherwise the CEC framework assumes it processed this message and |
Hans Verkuil | e92ca73 | 2016-11-09 06:00:53 -0200 | [diff] [blame] | 278 | it will not do anything with it. |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 279 | |
| 280 | |
| 281 | CEC framework functions |
| 282 | ----------------------- |
| 283 | |
| 284 | CEC Adapter drivers can call the following CEC framework functions: |
| 285 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 286 | .. c:function:: |
| 287 | int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, |
| 288 | bool block); |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 289 | |
| 290 | Transmit a CEC message. If block is true, then wait until the message has been |
| 291 | transmitted, otherwise just queue it and return. |
| 292 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 293 | .. c:function:: |
| 294 | void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, |
| 295 | bool block); |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 296 | |
| 297 | Change the physical address. This function will set adap->phys_addr and |
| 298 | send an event if it has changed. If cec_s_log_addrs() has been called and |
| 299 | the physical address has become valid, then the CEC framework will start |
| 300 | claiming the logical addresses. If block is true, then this function won't |
| 301 | return until this process has finished. |
| 302 | |
| 303 | When the physical address is set to a valid value the CEC adapter will |
| 304 | be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID, |
| 305 | then the CEC adapter will be disabled. If you change a valid physical address |
| 306 | to another valid physical address, then this function will first set the |
| 307 | address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. |
| 308 | |
Mauro Carvalho Chehab | 9486f2b | 2016-08-19 08:46:13 -0300 | [diff] [blame] | 309 | .. c:function:: |
| 310 | int cec_s_log_addrs(struct cec_adapter *adap, |
| 311 | struct cec_log_addrs *log_addrs, bool block); |
Hans Verkuil | efe2938 | 2015-05-04 14:32:59 -0300 | [diff] [blame] | 312 | |
| 313 | Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS |
| 314 | is set. If block is true, then wait until the logical addresses have been |
| 315 | claimed, otherwise just queue it and return. To unconfigure all logical |
| 316 | addresses call this function with log_addrs set to NULL or with |
| 317 | log_addrs->num_log_addrs set to 0. The block argument is ignored when |
| 318 | unconfiguring. This function will just return if the physical address is |
| 319 | invalid. Once the physical address becomes valid, then the framework will |
| 320 | attempt to claim these logical addresses. |