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 30The Kernel Interface 31==================== 32 33CEC Adapter 34----------- 35 36The struct cec_adapter represents the CEC adapter hardware. It is created by 37calling cec_allocate_adapter() and deleted by calling cec_delete_adapter(): 38 39.. c:function:: 40 struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, 41 void *priv, const char *name, u32 caps, u8 available_las, 42 struct device *parent); 43 44.. c:function:: 45 void cec_delete_adapter(struct cec_adapter *adap); 46 47To create an adapter you need to pass the following information: 48 49ops: 50 adapter operations which are called by the CEC framework and that you 51 have to implement. 52 53priv: 54 will be stored in adap->priv and can be used by the adapter ops. 55 56name: 57 the name of the CEC adapter. Note: this name will be copied. 58 59caps: 60 capabilities of the CEC adapter. These capabilities determine the 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 65available_las: 66 the number of simultaneous logical addresses that this 67 adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. 68 69parent: 70 the parent device. 71 72 73To register the /dev/cecX device node and the remote control device (if 74CEC_CAP_RC is set) you call: 75 76.. c:function:: 77 int cec_register_adapter(struct cec_adapter \*adap); 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_log_status)(struct cec_adapter *adap); 110 111 /* High-level callbacks */ 112 ... 113 }; 114 115The three low-level ops deal with various aspects of controlling the CEC adapter 116hardware: 117 118 119To enable/disable the hardware: 120 121.. c:function:: 122 int (*adap_enable)(struct cec_adapter *adap, bool enable); 123 124This callback enables or disables the CEC hardware. Enabling the CEC hardware 125means powering it up in a state where no logical addresses are claimed. This 126op assumes that the physical address (adap->phys_addr) is valid when enable is 127true and will not change while the CEC adapter remains enabled. The initial 128state of the CEC adapter after calling cec_allocate_adapter() is disabled. 129 130Note that adap_enable must return 0 if enable is false. 131 132 133To enable/disable the 'monitor all' mode: 134 135.. c:function:: 136 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); 137 138If enabled, then the adapter should be put in a mode to also monitor messages 139that not for us. Not all hardware supports this and this function is only 140called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional 141(some hardware may always be in 'monitor all' mode). 142 143Note that adap_monitor_all_enable must return 0 if enable is false. 144 145 146To program a new logical address: 147 148.. c:function:: 149 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); 150 151If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses 152are to be erased. Otherwise the given logical address should be programmed. 153If the maximum number of available logical addresses is exceeded, then it 154should return -ENXIO. Once a logical address is programmed the CEC hardware 155can receive directed messages to that address. 156 157Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. 158 159 160To transmit a new message: 161 162.. c:function:: 163 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, 164 u32 signal_free_time, struct cec_msg *msg); 165 166This transmits a new message. The attempts argument is the suggested number of 167attempts for the transmit. 168 169The signal_free_time is the number of data bit periods that the adapter should 170wait when the line is free before attempting to send a message. This value 171depends on whether this transmit is a retry, a message from a new initiator or 172a new message for the same initiator. Most hardware will handle this 173automatically, but in some cases this information is needed. 174 175The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to 176microseconds (one data bit period is 2.4 ms). 177 178 179To log the current CEC hardware status: 180 181.. c:function:: 182 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); 183 184This optional callback can be used to show the status of the CEC hardware. 185The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status 186 187 188Your adapter driver will also have to react to events (typically interrupt 189driven) by calling into the framework in the following situations: 190 191When a transmit finished (successfully or otherwise): 192 193.. c:function:: 194 void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, 195 u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); 196 197The status can be one of: 198 199CEC_TX_STATUS_OK: 200 the transmit was successful. 201 202CEC_TX_STATUS_ARB_LOST: 203 arbitration was lost: another CEC initiator 204 took control of the CEC line and you lost the arbitration. 205 206CEC_TX_STATUS_NACK: 207 the message was nacked (for a directed message) or 208 acked (for a broadcast message). A retransmission is needed. 209 210CEC_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 215CEC_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 220CEC_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 227The \*_cnt arguments are the number of error conditions that were seen. 228This may be 0 if no information is available. Drivers that do not support 229hardware retry can just set the counter corresponding to the transmit error 230to 1, if the hardware does support retry then either set these counters to 2310 if the hardware provides no feedback of which errors occurred and how many 232times, or fill in the correct values as reported by the hardware. 233 234When a CEC message was received: 235 236.. c:function:: 237 void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); 238 239Speaks for itself. 240 241Implementing the High-Level CEC Adapter 242--------------------------------------- 243 244The low-level operations drive the hardware, the high-level operations are 245CEC protocol driven. The following high-level callbacks are available: 246 247.. code-block:: none 248 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 }; 256 257The received() callback allows the driver to optionally handle a newly 258received CEC message 259 260.. c:function:: 261 int (*received)(struct cec_adapter *adap, struct cec_msg *msg); 262 263If the driver wants to process a CEC message, then it can implement this 264callback. 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 266it will not no anything with it. 267 268 269CEC framework functions 270----------------------- 271 272CEC Adapter drivers can call the following CEC framework functions: 273 274.. c:function:: 275 int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, 276 bool block); 277 278Transmit a CEC message. If block is true, then wait until the message has been 279transmitted, otherwise just queue it and return. 280 281.. c:function:: 282 void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, 283 bool block); 284 285Change the physical address. This function will set adap->phys_addr and 286send an event if it has changed. If cec_s_log_addrs() has been called and 287the physical address has become valid, then the CEC framework will start 288claiming the logical addresses. If block is true, then this function won't 289return until this process has finished. 290 291When the physical address is set to a valid value the CEC adapter will 292be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID, 293then the CEC adapter will be disabled. If you change a valid physical address 294to another valid physical address, then this function will first set the 295address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. 296 297.. c:function:: 298 int cec_s_log_addrs(struct cec_adapter *adap, 299 struct cec_log_addrs *log_addrs, bool block); 300 301Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS 302is set. If block is true, then wait until the logical addresses have been 303claimed, otherwise just queue it and return. To unconfigure all logical 304addresses call this function with log_addrs set to NULL or with 305log_addrs->num_log_addrs set to 0. The block argument is ignored when 306unconfiguring. This function will just return if the physical address is 307invalid. Once the physical address becomes valid, then the framework will 308attempt to claim these logical addresses. 309