1CEC Kernel Support 2================== 3 4The CEC framework provides a unified kernel interface for use with HDMI CEC 5hardware. It is designed to handle a multiple types of hardware (receivers, 6transmitters, USB dongles). The framework also gives the option to decide 7what to do in the kernel driver and what should be handled by userspace 8applications. In addition it integrates the remote control passthrough 9feature into the kernel's remote control framework. 10 11 12The CEC Protocol 13---------------- 14 15The CEC protocol enables consumer electronic devices to communicate with each 16other through the HDMI connection. The protocol uses logical addresses in the 17communication. The logical address is strictly connected with the functionality 18provided by the device. The TV acting as the communication hub is always 19assigned address 0. The physical address is determined by the physical 20connection between devices. 21 22The CEC framework described here is up to date with the CEC 2.0 specification. 23It is documented in the HDMI 1.4 specification with the new 2.0 bits documented 24in the HDMI 2.0 specification. But for most of the features the freely available 25HDMI 1.3a specification is sufficient: 26 27http://www.microprocessor.org/HDMISpecification13a.pdf 28 29 30CEC Adapter Interface 31--------------------- 32 33The struct cec_adapter represents the CEC adapter hardware. It is created by 34calling cec_allocate_adapter() and deleted by calling cec_delete_adapter(): 35 36.. c:function:: 37 struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, void *priv, 38 const char *name, u32 caps, u8 available_las); 39 40.. c:function:: 41 void cec_delete_adapter(struct cec_adapter *adap); 42 43To create an adapter you need to pass the following information: 44 45ops: 46 adapter operations which are called by the CEC framework and that you 47 have to implement. 48 49priv: 50 will be stored in adap->priv and can be used by the adapter ops. 51 Use cec_get_drvdata(adap) to get the priv pointer. 52 53name: 54 the name of the CEC adapter. Note: this name will be copied. 55 56caps: 57 capabilities of the CEC adapter. These capabilities determine the 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 62available_las: 63 the number of simultaneous logical addresses that this 64 adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. 65 66To obtain the priv pointer use this helper function: 67 68.. c:function:: 69 void *cec_get_drvdata(const struct cec_adapter *adap); 70 71To register the /dev/cecX device node and the remote control device (if 72CEC_CAP_RC is set) you call: 73 74.. c:function:: 75 int cec_register_adapter(struct cec_adapter *adap, struct device *parent); 76 77where parent is the parent device. 78 79To unregister the devices call: 80 81.. c:function:: 82 void cec_unregister_adapter(struct cec_adapter *adap); 83 84Note: if cec_register_adapter() fails, then call cec_delete_adapter() to 85clean up. But if cec_register_adapter() succeeded, then only call 86cec_unregister_adapter() to clean up, never cec_delete_adapter(). The 87unregister function will delete the adapter automatically once the last user 88of that /dev/cecX device has closed its file handle. 89 90 91Implementing the Low-Level CEC Adapter 92-------------------------------------- 93 94The following low-level adapter operations have to be implemented in 95your driver: 96 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_status)(struct cec_adapter *adap, struct seq_file *file); 110 void (*adap_free)(struct cec_adapter *adap); 111 112 /* High-level callbacks */ 113 ... 114 }; 115 116The five low-level ops deal with various aspects of controlling the CEC adapter 117hardware: 118 119 120To enable/disable the hardware: 121 122.. c:function:: 123 int (*adap_enable)(struct cec_adapter *adap, bool enable); 124 125This callback enables or disables the CEC hardware. Enabling the CEC hardware 126means powering it up in a state where no logical addresses are claimed. This 127op assumes that the physical address (adap->phys_addr) is valid when enable is 128true and will not change while the CEC adapter remains enabled. The initial 129state of the CEC adapter after calling cec_allocate_adapter() is disabled. 130 131Note that adap_enable must return 0 if enable is false. 132 133 134To enable/disable the 'monitor all' mode: 135 136.. c:function:: 137 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); 138 139If enabled, then the adapter should be put in a mode to also monitor messages 140that not for us. Not all hardware supports this and this function is only 141called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional 142(some hardware may always be in 'monitor all' mode). 143 144Note that adap_monitor_all_enable must return 0 if enable is false. 145 146 147To program a new logical address: 148 149.. c:function:: 150 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); 151 152If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses 153are to be erased. Otherwise the given logical address should be programmed. 154If the maximum number of available logical addresses is exceeded, then it 155should return -ENXIO. Once a logical address is programmed the CEC hardware 156can receive directed messages to that address. 157 158Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. 159 160 161To transmit a new message: 162 163.. c:function:: 164 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, 165 u32 signal_free_time, struct cec_msg *msg); 166 167This transmits a new message. The attempts argument is the suggested number of 168attempts for the transmit. 169 170The signal_free_time is the number of data bit periods that the adapter should 171wait when the line is free before attempting to send a message. This value 172depends on whether this transmit is a retry, a message from a new initiator or 173a new message for the same initiator. Most hardware will handle this 174automatically, but in some cases this information is needed. 175 176The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to 177microseconds (one data bit period is 2.4 ms). 178 179 180To log the current CEC hardware status: 181 182.. c:function:: 183 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); 184 185This optional callback can be used to show the status of the CEC hardware. 186The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status 187 188To free any resources when the adapter is deleted: 189 190.. c:function:: 191 void (*adap_free)(struct cec_adapter *adap); 192 193This optional callback can be used to free any resources that might have been 194allocated by the driver. It's called from cec_delete_adapter. 195 196 197Your adapter driver will also have to react to events (typically interrupt 198driven) by calling into the framework in the following situations: 199 200When a transmit finished (successfully or otherwise): 201 202.. c:function:: 203 void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, 204 u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); 205 206or: 207 208.. c:function:: 209 void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status); 210 211The status can be one of: 212 213CEC_TX_STATUS_OK: 214 the transmit was successful. 215 216CEC_TX_STATUS_ARB_LOST: 217 arbitration was lost: another CEC initiator 218 took control of the CEC line and you lost the arbitration. 219 220CEC_TX_STATUS_NACK: 221 the message was nacked (for a directed message) or 222 acked (for a broadcast message). A retransmission is needed. 223 224CEC_TX_STATUS_LOW_DRIVE: 225 low drive was detected on the CEC bus. This indicates that 226 a follower detected an error on the bus and requested a 227 retransmission. 228 229CEC_TX_STATUS_ERROR: 230 some unspecified error occurred: this can be one of 231 the previous two if the hardware cannot differentiate or something 232 else entirely. 233 234CEC_TX_STATUS_MAX_RETRIES: 235 could not transmit the message after trying multiple times. 236 Should only be set by the driver if it has hardware support for 237 retrying messages. If set, then the framework assumes that it 238 doesn't have to make another attempt to transmit the message 239 since the hardware did that already. 240 241The \*_cnt arguments are the number of error conditions that were seen. 242This may be 0 if no information is available. Drivers that do not support 243hardware retry can just set the counter corresponding to the transmit error 244to 1, if the hardware does support retry then either set these counters to 2450 if the hardware provides no feedback of which errors occurred and how many 246times, or fill in the correct values as reported by the hardware. 247 248The cec_transmit_attempt_done() function is a helper for cases where the 249hardware never retries, so the transmit is always for just a single 250attempt. It will call cec_transmit_done() in turn, filling in 1 for the 251count argument corresponding to the status. Or all 0 if the status was OK. 252 253When a CEC message was received: 254 255.. c:function:: 256 void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); 257 258Speaks for itself. 259 260Implementing the interrupt handler 261---------------------------------- 262 263Typically the CEC hardware provides interrupts that signal when a transmit 264finished and whether it was successful or not, and it provides and interrupt 265when a CEC message was received. 266 267The CEC driver should always process the transmit interrupts first before 268handling the receive interrupt. The framework expects to see the cec_transmit_done 269call before the cec_received_msg call, otherwise it can get confused if the 270received message was in reply to the transmitted message. 271 272Implementing the High-Level CEC Adapter 273--------------------------------------- 274 275The low-level operations drive the hardware, the high-level operations are 276CEC protocol driven. The following high-level callbacks are available: 277 278.. code-block:: none 279 280 struct cec_adap_ops { 281 /* Low-level callbacks */ 282 ... 283 284 /* High-level CEC message callback */ 285 int (*received)(struct cec_adapter *adap, struct cec_msg *msg); 286 }; 287 288The received() callback allows the driver to optionally handle a newly 289received CEC message 290 291.. c:function:: 292 int (*received)(struct cec_adapter *adap, struct cec_msg *msg); 293 294If the driver wants to process a CEC message, then it can implement this 295callback. If it doesn't want to handle this message, then it should return 296-ENOMSG, otherwise the CEC framework assumes it processed this message and 297it will not do anything with it. 298 299 300CEC framework functions 301----------------------- 302 303CEC Adapter drivers can call the following CEC framework functions: 304 305.. c:function:: 306 int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, 307 bool block); 308 309Transmit a CEC message. If block is true, then wait until the message has been 310transmitted, otherwise just queue it and return. 311 312.. c:function:: 313 void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, 314 bool block); 315 316Change the physical address. This function will set adap->phys_addr and 317send an event if it has changed. If cec_s_log_addrs() has been called and 318the physical address has become valid, then the CEC framework will start 319claiming the logical addresses. If block is true, then this function won't 320return until this process has finished. 321 322When the physical address is set to a valid value the CEC adapter will 323be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID, 324then the CEC adapter will be disabled. If you change a valid physical address 325to another valid physical address, then this function will first set the 326address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. 327 328.. c:function:: 329 void cec_s_phys_addr_from_edid(struct cec_adapter *adap, 330 const struct edid *edid); 331 332A helper function that extracts the physical address from the edid struct 333and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID 334if the EDID did not contain a physical address or edid was a NULL pointer. 335 336.. c:function:: 337 int cec_s_log_addrs(struct cec_adapter *adap, 338 struct cec_log_addrs *log_addrs, bool block); 339 340Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS 341is set. If block is true, then wait until the logical addresses have been 342claimed, otherwise just queue it and return. To unconfigure all logical 343addresses call this function with log_addrs set to NULL or with 344log_addrs->num_log_addrs set to 0. The block argument is ignored when 345unconfiguring. This function will just return if the physical address is 346invalid. Once the physical address becomes valid, then the framework will 347attempt to claim these logical addresses. 348 349CEC Pin framework 350----------------- 351 352Most CEC hardware operates on full CEC messages where the software provides 353the message and the hardware handles the low-level CEC protocol. But some 354hardware only drives the CEC pin and software has to handle the low-level 355CEC protocol. The CEC pin framework was created to handle such devices. 356 357Note that due to the close-to-realtime requirements it can never be guaranteed 358to work 100%. This framework uses highres timers internally, but if a 359timer goes off too late by more than 300 microseconds wrong results can 360occur. In reality it appears to be fairly reliable. 361 362One advantage of this low-level implementation is that it can be used as 363a cheap CEC analyser, especially if interrupts can be used to detect 364CEC pin transitions from low to high or vice versa. 365 366.. kernel-doc:: include/media/cec-pin.h 367 368CEC Notifier framework 369---------------------- 370 371Most drm HDMI implementations have an integrated CEC implementation and no 372notifier support is needed. But some have independent CEC implementations 373that have their own driver. This could be an IP block for an SoC or a 374completely separate chip that deals with the CEC pin. For those cases a 375drm driver can install a notifier and use the notifier to inform the 376CEC driver about changes in the physical address. 377 378.. kernel-doc:: include/media/cec-notifier.h 379