Documentation/media/kapi/cec-core.rst

   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 CEC Adapter Interface
  31 ---------------------
  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
  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
  43 To create an adapter you need to pass the following information:
  44
  45 ops:
  46         adapter operations which are called by the CEC framework and that you
  47         have to implement.
  48
  49 priv:
  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
  53 name:
  54         the name of the CEC adapter. Note: this name will be copied.
  55
  56 caps:
  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
  62 available_las:
  63         the number of simultaneous logical addresses that this
  64         adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS.
  65
  66 To obtain the priv pointer use this helper function:
  67
  68 .. c:function::
  69         void *cec_get_drvdata(const struct cec_adapter *adap);
  70
  71 To register the /dev/cecX device node and the remote control device (if
  72 CEC_CAP_RC is set) you call:
  73
  74 .. c:function::
  75         int cec_register_adapter(struct cec_adapter *adap, struct device *parent);
  76
  77 where parent is the parent device.
  78
  79 To unregister the devices call:
  80
  81 .. c:function::
  82         void cec_unregister_adapter(struct cec_adapter *adap);
  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
  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
 111                 /* High-level callbacks */
 112                 ...
 113         };
 114
 115 The five low-level ops deal with various aspects of controlling the CEC adapter
 116 hardware:
 117
 118
 119 To enable/disable the hardware:
 120
 121 .. c:function::
 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
 135 .. c:function::
 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
 148 .. c:function::
 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
 162 .. c:function::
 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
 181 .. c:function::
 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
 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
 197 or:
 198
 199 .. c:function::
 200         void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status);
 201
 202 The status can be one of:
 203
 204 CEC_TX_STATUS_OK:
 205         the transmit was successful.
 206
 207 CEC_TX_STATUS_ARB_LOST:
 208         arbitration was lost: another CEC initiator
 209         took control of the CEC line and you lost the arbitration.
 210
 211 CEC_TX_STATUS_NACK:
 212         the message was nacked (for a directed message) or
 213         acked (for a broadcast message). A retransmission is needed.
 214
 215 CEC_TX_STATUS_LOW_DRIVE:
 216         low drive was detected on the CEC bus. This indicates that
 217         a follower detected an error on the bus and requested a
 218         retransmission.
 219
 220 CEC_TX_STATUS_ERROR:
 221         some unspecified error occurred: this can be one of
 222         the previous two if the hardware cannot differentiate or something
 223         else entirely.
 224
 225 CEC_TX_STATUS_MAX_RETRIES:
 226         could not transmit the message after trying multiple times.
 227         Should only be set by the driver if it has hardware support for
 228         retrying messages. If set, then the framework assumes that it
 229         doesn't have to make another attempt to transmit the message
 230         since the hardware did that already.
 231
 232 The \*_cnt arguments are the number of error conditions that were seen.
 233 This may be 0 if no information is available. Drivers that do not support
 234 hardware retry can just set the counter corresponding to the transmit error
 235 to 1, if the hardware does support retry then either set these counters to
 236 0 if the hardware provides no feedback of which errors occurred and how many
 237 times, or fill in the correct values as reported by the hardware.
 238
 239 The cec_transmit_attempt_done() function is a helper for cases where the
 240 hardware never retries, so the transmit is always for just a single
 241 attempt. It will call cec_transmit_done() in turn, filling in 1 for the
 242 count argument corresponding to the status. Or all 0 if the status was OK.
 243
 244 When a CEC message was received:
 245
 246 .. c:function::
 247         void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);
 248
 249 Speaks for itself.
 250
 251 Implementing the interrupt handler
 252 ----------------------------------
 253
 254 Typically the CEC hardware provides interrupts that signal when a transmit
 255 finished and whether it was successful or not, and it provides and interrupt
 256 when a CEC message was received.
 257
 258 The CEC driver should always process the transmit interrupts first before
 259 handling the receive interrupt. The framework expects to see the cec_transmit_done
 260 call before the cec_received_msg call, otherwise it can get confused if the
 261 received message was in reply to the transmitted message.
 262
 263 Implementing the High-Level CEC Adapter
 264 ---------------------------------------
 265
 266 The low-level operations drive the hardware, the high-level operations are
 267 CEC protocol driven. The following high-level callbacks are available:
 268
 269 .. code-block:: none
 270
 271         struct cec_adap_ops {
 272                 /* Low-level callbacks */
 273                 ...
 274
 275                 /* High-level CEC message callback */
 276                 int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
 277         };
 278
 279 The received() callback allows the driver to optionally handle a newly
 280 received CEC message
 281
 282 .. c:function::
 283         int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
 284
 285 If the driver wants to process a CEC message, then it can implement this
 286 callback. If it doesn't want to handle this message, then it should return
 287 -ENOMSG, otherwise the CEC framework assumes it processed this message and
 288 it will not do anything with it.
 289
 290
 291 CEC framework functions
 292 -----------------------
 293
 294 CEC Adapter drivers can call the following CEC framework functions:
 295
 296 .. c:function::
 297         int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg,
 298                              bool block);
 299
 300 Transmit a CEC message. If block is true, then wait until the message has been
 301 transmitted, otherwise just queue it and return.
 302
 303 .. c:function::
 304         void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr,
 305                              bool block);
 306
 307 Change the physical address. This function will set adap->phys_addr and
 308 send an event if it has changed. If cec_s_log_addrs() has been called and
 309 the physical address has become valid, then the CEC framework will start
 310 claiming the logical addresses. If block is true, then this function won't
 311 return until this process has finished.
 312
 313 When the physical address is set to a valid value the CEC adapter will
 314 be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID,
 315 then the CEC adapter will be disabled. If you change a valid physical address
 316 to another valid physical address, then this function will first set the
 317 address to CEC_PHYS_ADDR_INVALID before enabling the new physical address.
 318
 319 .. c:function::
 320         void cec_s_phys_addr_from_edid(struct cec_adapter *adap,
 321                                        const struct edid *edid);
 322
 323 A helper function that extracts the physical address from the edid struct
 324 and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID
 325 if the EDID did not contain a physical address or edid was a NULL pointer.
 326
 327 .. c:function::
 328         int cec_s_log_addrs(struct cec_adapter *adap,
 329                             struct cec_log_addrs *log_addrs, bool block);
 330
 331 Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS
 332 is set. If block is true, then wait until the logical addresses have been
 333 claimed, otherwise just queue it and return. To unconfigure all logical
 334 addresses call this function with log_addrs set to NULL or with
 335 log_addrs->num_log_addrs set to 0. The block argument is ignored when
 336 unconfiguring. This function will just return if the physical address is
 337 invalid. Once the physical address becomes valid, then the framework will
 338 attempt to claim these logical addresses.