cec-core.rst 17 KB

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