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