Based on kernel version 4.8. Page generated on 2016-10-06 23:10 EST.
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.
