1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
2 | /* |
3 | * cec - HDMI Consumer Electronics Control support header |
4 | * |
5 | * Copyright 2016 Cisco Systems, Inc. and/or its affiliates. All rights reserved. |
6 | */ |
7 | |
8 | #ifndef _MEDIA_CEC_H |
9 | #define _MEDIA_CEC_H |
10 | |
11 | #include <linux/poll.h> |
12 | #include <linux/fs.h> |
13 | #include <linux/debugfs.h> |
14 | #include <linux/device.h> |
15 | #include <linux/cdev.h> |
16 | #include <linux/kthread.h> |
17 | #include <linux/timer.h> |
18 | #include <linux/cec-funcs.h> |
19 | #include <media/rc-core.h> |
20 | |
21 | #define CEC_CAP_DEFAULTS (CEC_CAP_LOG_ADDRS | CEC_CAP_TRANSMIT | \ |
22 | CEC_CAP_PASSTHROUGH | CEC_CAP_RC) |
23 | |
24 | /** |
25 | * struct cec_devnode - cec device node |
26 | * @dev: cec device |
27 | * @cdev: cec character device |
28 | * @minor: device node minor number |
29 | * @lock: lock to serialize open/release and registration |
30 | * @registered: the device was correctly registered |
31 | * @unregistered: the device was unregistered |
32 | * @lock_fhs: lock to control access to @fhs |
33 | * @fhs: the list of open filehandles (cec_fh) |
34 | * |
35 | * This structure represents a cec-related device node. |
36 | * |
37 | * To add or remove filehandles from @fhs the @lock must be taken first, |
38 | * followed by @lock_fhs. It is safe to access @fhs if either lock is held. |
39 | * |
40 | * The @parent is a physical device. It must be set by core or device drivers |
41 | * before registering the node. |
42 | */ |
43 | struct cec_devnode { |
44 | /* sysfs */ |
45 | struct device dev; |
46 | struct cdev cdev; |
47 | |
48 | /* device info */ |
49 | int minor; |
50 | /* serialize open/release and registration */ |
51 | struct mutex lock; |
52 | bool registered; |
53 | bool unregistered; |
54 | /* protect access to fhs */ |
55 | struct mutex lock_fhs; |
56 | struct list_head fhs; |
57 | }; |
58 | |
59 | struct cec_adapter; |
60 | struct cec_data; |
61 | struct cec_pin; |
62 | struct cec_notifier; |
63 | |
64 | struct cec_data { |
65 | struct list_head list; |
66 | struct list_head xfer_list; |
67 | struct cec_adapter *adap; |
68 | struct cec_msg msg; |
69 | struct cec_fh *fh; |
70 | struct delayed_work work; |
71 | struct completion c; |
72 | u8 attempts; |
73 | bool blocking; |
74 | bool completed; |
75 | }; |
76 | |
77 | struct cec_msg_entry { |
78 | struct list_head list; |
79 | struct cec_msg msg; |
80 | }; |
81 | |
82 | struct cec_event_entry { |
83 | struct list_head list; |
84 | struct cec_event ev; |
85 | }; |
86 | |
87 | #define CEC_NUM_CORE_EVENTS 2 |
88 | #define CEC_NUM_EVENTS CEC_EVENT_PIN_5V_HIGH |
89 | |
90 | struct cec_fh { |
91 | struct list_head list; |
92 | struct list_head xfer_list; |
93 | struct cec_adapter *adap; |
94 | u8 mode_initiator; |
95 | u8 mode_follower; |
96 | |
97 | /* Events */ |
98 | wait_queue_head_t wait; |
99 | struct mutex lock; |
100 | struct list_head events[CEC_NUM_EVENTS]; /* queued events */ |
101 | u16 queued_events[CEC_NUM_EVENTS]; |
102 | unsigned int total_queued_events; |
103 | struct cec_event_entry core_events[CEC_NUM_CORE_EVENTS]; |
104 | struct list_head msgs; /* queued messages */ |
105 | unsigned int queued_msgs; |
106 | }; |
107 | |
108 | #define CEC_SIGNAL_FREE_TIME_RETRY 3 |
109 | #define CEC_SIGNAL_FREE_TIME_NEW_INITIATOR 5 |
110 | #define CEC_SIGNAL_FREE_TIME_NEXT_XFER 7 |
111 | |
112 | /* The nominal data bit period is 2.4 ms */ |
113 | #define CEC_FREE_TIME_TO_USEC(ft) ((ft) * 2400) |
114 | |
115 | struct cec_adap_ops { |
116 | /* Low-level callbacks, called with adap->lock held */ |
117 | int (*adap_enable)(struct cec_adapter *adap, bool enable); |
118 | int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); |
119 | int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); |
120 | int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); |
121 | void (*adap_unconfigured)(struct cec_adapter *adap); |
122 | int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, |
123 | u32 signal_free_time, struct cec_msg *msg); |
124 | void (*adap_nb_transmit_canceled)(struct cec_adapter *adap, |
125 | const struct cec_msg *msg); |
126 | void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); |
127 | void (*adap_free)(struct cec_adapter *adap); |
128 | |
129 | /* Error injection callbacks, called without adap->lock held */ |
130 | int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); |
131 | bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line); |
132 | |
133 | /* High-level CEC message callback, called without adap->lock held */ |
134 | void (*configured)(struct cec_adapter *adap); |
135 | int (*received)(struct cec_adapter *adap, struct cec_msg *msg); |
136 | }; |
137 | |
138 | /* |
139 | * The minimum message length you can receive (excepting poll messages) is 2. |
140 | * With a transfer rate of at most 36 bytes per second this makes 18 messages |
141 | * per second worst case. |
142 | * |
143 | * We queue at most 3 seconds worth of received messages. The CEC specification |
144 | * requires that messages are replied to within a second, so 3 seconds should |
145 | * give more than enough margin. Since most messages are actually more than 2 |
146 | * bytes, this is in practice a lot more than 3 seconds. |
147 | */ |
148 | #define CEC_MAX_MSG_RX_QUEUE_SZ (18 * 3) |
149 | |
150 | /* |
151 | * The transmit queue is limited to 1 second worth of messages (worst case). |
152 | * Messages can be transmitted by userspace and kernel space. But for both it |
153 | * makes no sense to have a lot of messages queued up. One second seems |
154 | * reasonable. |
155 | */ |
156 | #define CEC_MAX_MSG_TX_QUEUE_SZ (18 * 1) |
157 | |
158 | /** |
159 | * struct cec_adapter - cec adapter structure |
160 | * @owner: module owner |
161 | * @name: name of the CEC adapter |
162 | * @devnode: device node for the /dev/cecX device |
163 | * @lock: mutex controlling access to this structure |
164 | * @rc: remote control device |
165 | * @transmit_queue: queue of pending transmits |
166 | * @transmit_queue_sz: number of pending transmits |
167 | * @wait_queue: queue of transmits waiting for a reply |
168 | * @transmitting: CEC messages currently being transmitted |
169 | * @transmit_in_progress: true if a transmit is in progress |
170 | * @transmit_in_progress_aborted: true if a transmit is in progress is to be |
171 | * aborted. This happens if the logical address is |
172 | * invalidated while the transmit is ongoing. In that |
173 | * case the transmit will finish, but will not retransmit |
174 | * and be marked as ABORTED. |
175 | * @xfer_timeout_ms: the transfer timeout in ms. |
176 | * If 0, then timeout after 2.1 ms. |
177 | * @kthread_config: kthread used to configure a CEC adapter |
178 | * @config_completion: used to signal completion of the config kthread |
179 | * @kthread: main CEC processing thread |
180 | * @kthread_waitq: main CEC processing wait_queue |
181 | * @ops: cec adapter ops |
182 | * @priv: cec driver's private data |
183 | * @capabilities: cec adapter capabilities |
184 | * @available_log_addrs: maximum number of available logical addresses |
185 | * @phys_addr: the current physical address |
186 | * @needs_hpd: if true, then the HDMI HotPlug Detect pin must be high |
187 | * in order to transmit or receive CEC messages. This is usually a HW |
188 | * limitation. |
189 | * @is_enabled: the CEC adapter is enabled |
190 | * @is_configuring: the CEC adapter is configuring (i.e. claiming LAs) |
191 | * @must_reconfigure: while configuring, the PA changed, so reclaim LAs |
192 | * @is_configured: the CEC adapter is configured (i.e. has claimed LAs) |
193 | * @cec_pin_is_high: if true then the CEC pin is high. Only used with the |
194 | * CEC pin framework. |
195 | * @adap_controls_phys_addr: if true, then the CEC adapter controls the |
196 | * physical address, i.e. the CEC hardware can detect HPD changes and |
197 | * read the EDID and is not dependent on an external HDMI driver. |
198 | * Drivers that need this can set this field to true after the |
199 | * cec_allocate_adapter() call. |
200 | * @last_initiator: the initiator of the last transmitted message. |
201 | * @monitor_all_cnt: number of filehandles monitoring all msgs |
202 | * @monitor_pin_cnt: number of filehandles monitoring pin changes |
203 | * @follower_cnt: number of filehandles in follower mode |
204 | * @cec_follower: filehandle of the exclusive follower |
205 | * @cec_initiator: filehandle of the exclusive initiator |
206 | * @passthrough: if true, then the exclusive follower is in |
207 | * passthrough mode. |
208 | * @log_addrs: current logical addresses |
209 | * @conn_info: current connector info |
210 | * @tx_timeout_cnt: count the number of Timed Out transmits. |
211 | * Reset to 0 when this is reported in cec_adap_status(). |
212 | * @tx_low_drive_cnt: count the number of Low Drive transmits. |
213 | * Reset to 0 when this is reported in cec_adap_status(). |
214 | * @tx_error_cnt: count the number of Error transmits. |
215 | * Reset to 0 when this is reported in cec_adap_status(). |
216 | * @tx_arb_lost_cnt: count the number of Arb Lost transmits. |
217 | * Reset to 0 when this is reported in cec_adap_status(). |
218 | * @tx_low_drive_log_cnt: number of logged Low Drive transmits since the |
219 | * adapter was enabled. Used to avoid flooding the kernel |
220 | * log if this happens a lot. |
221 | * @tx_error_log_cnt: number of logged Error transmits since the adapter was |
222 | * enabled. Used to avoid flooding the kernel log if this |
223 | * happens a lot. |
224 | * @notifier: CEC notifier |
225 | * @pin: CEC pin status struct |
226 | * @cec_dir: debugfs cec directory |
227 | * @sequence: transmit sequence counter |
228 | * @input_phys: remote control input_phys name |
229 | * |
230 | * This structure represents a cec adapter. |
231 | */ |
232 | struct cec_adapter { |
233 | struct module *owner; |
234 | char name[32]; |
235 | struct cec_devnode devnode; |
236 | struct mutex lock; |
237 | struct rc_dev *rc; |
238 | |
239 | struct list_head transmit_queue; |
240 | unsigned int transmit_queue_sz; |
241 | struct list_head wait_queue; |
242 | struct cec_data *transmitting; |
243 | bool transmit_in_progress; |
244 | bool transmit_in_progress_aborted; |
245 | unsigned int xfer_timeout_ms; |
246 | |
247 | struct task_struct *kthread_config; |
248 | struct completion config_completion; |
249 | |
250 | struct task_struct *kthread; |
251 | wait_queue_head_t kthread_waitq; |
252 | |
253 | const struct cec_adap_ops *ops; |
254 | void *priv; |
255 | u32 capabilities; |
256 | u8 available_log_addrs; |
257 | |
258 | u16 phys_addr; |
259 | bool needs_hpd; |
260 | bool is_enabled; |
261 | bool is_configuring; |
262 | bool must_reconfigure; |
263 | bool is_configured; |
264 | bool cec_pin_is_high; |
265 | bool adap_controls_phys_addr; |
266 | u8 last_initiator; |
267 | u32 monitor_all_cnt; |
268 | u32 monitor_pin_cnt; |
269 | u32 follower_cnt; |
270 | struct cec_fh *cec_follower; |
271 | struct cec_fh *cec_initiator; |
272 | bool passthrough; |
273 | struct cec_log_addrs log_addrs; |
274 | struct cec_connector_info conn_info; |
275 | |
276 | u32 tx_timeout_cnt; |
277 | u32 tx_low_drive_cnt; |
278 | u32 tx_error_cnt; |
279 | u32 tx_arb_lost_cnt; |
280 | u32 tx_low_drive_log_cnt; |
281 | u32 tx_error_log_cnt; |
282 | |
283 | #ifdef CONFIG_CEC_NOTIFIER |
284 | struct cec_notifier *notifier; |
285 | #endif |
286 | #ifdef CONFIG_CEC_PIN |
287 | struct cec_pin *pin; |
288 | #endif |
289 | |
290 | struct dentry *cec_dir; |
291 | |
292 | u32 sequence; |
293 | |
294 | char input_phys[40]; |
295 | }; |
296 | |
297 | static inline void *cec_get_drvdata(const struct cec_adapter *adap) |
298 | { |
299 | return adap->priv; |
300 | } |
301 | |
302 | static inline bool cec_has_log_addr(const struct cec_adapter *adap, u8 log_addr) |
303 | { |
304 | return adap->log_addrs.log_addr_mask & (1 << log_addr); |
305 | } |
306 | |
307 | static inline bool cec_is_sink(const struct cec_adapter *adap) |
308 | { |
309 | return adap->phys_addr == 0; |
310 | } |
311 | |
312 | /** |
313 | * cec_is_registered() - is the CEC adapter registered? |
314 | * |
315 | * @adap: the CEC adapter, may be NULL. |
316 | * |
317 | * Return: true if the adapter is registered, false otherwise. |
318 | */ |
319 | static inline bool cec_is_registered(const struct cec_adapter *adap) |
320 | { |
321 | return adap && adap->devnode.registered; |
322 | } |
323 | |
324 | #define cec_phys_addr_exp(pa) \ |
325 | ((pa) >> 12), ((pa) >> 8) & 0xf, ((pa) >> 4) & 0xf, (pa) & 0xf |
326 | |
327 | struct edid; |
328 | struct drm_connector; |
329 | |
330 | #if IS_REACHABLE(CONFIG_CEC_CORE) |
331 | struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, |
332 | void *priv, const char *name, u32 caps, u8 available_las); |
333 | int cec_register_adapter(struct cec_adapter *adap, struct device *parent); |
334 | void cec_unregister_adapter(struct cec_adapter *adap); |
335 | void cec_delete_adapter(struct cec_adapter *adap); |
336 | |
337 | int cec_s_log_addrs(struct cec_adapter *adap, struct cec_log_addrs *log_addrs, |
338 | bool block); |
339 | void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, |
340 | bool block); |
341 | void cec_s_phys_addr_from_edid(struct cec_adapter *adap, |
342 | const struct edid *edid); |
343 | void cec_s_conn_info(struct cec_adapter *adap, |
344 | const struct cec_connector_info *conn_info); |
345 | int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, |
346 | bool block); |
347 | |
348 | /* Called by the adapter */ |
349 | void cec_transmit_done_ts(struct cec_adapter *adap, u8 status, |
350 | u8 arb_lost_cnt, u8 nack_cnt, u8 low_drive_cnt, |
351 | u8 error_cnt, ktime_t ts); |
352 | |
353 | static inline void cec_transmit_done(struct cec_adapter *adap, u8 status, |
354 | u8 arb_lost_cnt, u8 nack_cnt, |
355 | u8 low_drive_cnt, u8 error_cnt) |
356 | { |
357 | cec_transmit_done_ts(adap, status, arb_lost_cnt, nack_cnt, |
358 | low_drive_cnt, error_cnt, ts: ktime_get()); |
359 | } |
360 | /* |
361 | * Simplified version of cec_transmit_done for hardware that doesn't retry |
362 | * failed transmits. So this is always just one attempt in which case |
363 | * the status is sufficient. |
364 | */ |
365 | void cec_transmit_attempt_done_ts(struct cec_adapter *adap, |
366 | u8 status, ktime_t ts); |
367 | |
368 | static inline void cec_transmit_attempt_done(struct cec_adapter *adap, |
369 | u8 status) |
370 | { |
371 | cec_transmit_attempt_done_ts(adap, status, ts: ktime_get()); |
372 | } |
373 | |
374 | void cec_received_msg_ts(struct cec_adapter *adap, |
375 | struct cec_msg *msg, ktime_t ts); |
376 | |
377 | static inline void cec_received_msg(struct cec_adapter *adap, |
378 | struct cec_msg *msg) |
379 | { |
380 | cec_received_msg_ts(adap, msg, ts: ktime_get()); |
381 | } |
382 | |
383 | /** |
384 | * cec_queue_pin_cec_event() - queue a CEC pin event with a given timestamp. |
385 | * |
386 | * @adap: pointer to the cec adapter |
387 | * @is_high: when true the CEC pin is high, otherwise it is low |
388 | * @dropped_events: when true some events were dropped |
389 | * @ts: the timestamp for this event |
390 | * |
391 | */ |
392 | void cec_queue_pin_cec_event(struct cec_adapter *adap, bool is_high, |
393 | bool dropped_events, ktime_t ts); |
394 | |
395 | /** |
396 | * cec_queue_pin_hpd_event() - queue a pin event with a given timestamp. |
397 | * |
398 | * @adap: pointer to the cec adapter |
399 | * @is_high: when true the HPD pin is high, otherwise it is low |
400 | * @ts: the timestamp for this event |
401 | * |
402 | */ |
403 | void cec_queue_pin_hpd_event(struct cec_adapter *adap, bool is_high, ktime_t ts); |
404 | |
405 | /** |
406 | * cec_queue_pin_5v_event() - queue a pin event with a given timestamp. |
407 | * |
408 | * @adap: pointer to the cec adapter |
409 | * @is_high: when true the 5V pin is high, otherwise it is low |
410 | * @ts: the timestamp for this event |
411 | * |
412 | */ |
413 | void cec_queue_pin_5v_event(struct cec_adapter *adap, bool is_high, ktime_t ts); |
414 | |
415 | /** |
416 | * cec_get_edid_phys_addr() - find and return the physical address |
417 | * |
418 | * @edid: pointer to the EDID data |
419 | * @size: size in bytes of the EDID data |
420 | * @offset: If not %NULL then the location of the physical address |
421 | * bytes in the EDID will be returned here. This is set to 0 |
422 | * if there is no physical address found. |
423 | * |
424 | * Return: the physical address or CEC_PHYS_ADDR_INVALID if there is none. |
425 | */ |
426 | u16 cec_get_edid_phys_addr(const u8 *edid, unsigned int size, |
427 | unsigned int *offset); |
428 | |
429 | void cec_fill_conn_info_from_drm(struct cec_connector_info *conn_info, |
430 | const struct drm_connector *connector); |
431 | |
432 | #else |
433 | |
434 | static inline int cec_register_adapter(struct cec_adapter *adap, |
435 | struct device *parent) |
436 | { |
437 | return 0; |
438 | } |
439 | |
440 | static inline void cec_unregister_adapter(struct cec_adapter *adap) |
441 | { |
442 | } |
443 | |
444 | static inline void cec_delete_adapter(struct cec_adapter *adap) |
445 | { |
446 | } |
447 | |
448 | static inline void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, |
449 | bool block) |
450 | { |
451 | } |
452 | |
453 | static inline void cec_s_phys_addr_from_edid(struct cec_adapter *adap, |
454 | const struct edid *edid) |
455 | { |
456 | } |
457 | |
458 | static inline u16 cec_get_edid_phys_addr(const u8 *edid, unsigned int size, |
459 | unsigned int *offset) |
460 | { |
461 | if (offset) |
462 | *offset = 0; |
463 | return CEC_PHYS_ADDR_INVALID; |
464 | } |
465 | |
466 | static inline void cec_s_conn_info(struct cec_adapter *adap, |
467 | const struct cec_connector_info *conn_info) |
468 | { |
469 | } |
470 | |
471 | static inline void |
472 | cec_fill_conn_info_from_drm(struct cec_connector_info *conn_info, |
473 | const struct drm_connector *connector) |
474 | { |
475 | memset(conn_info, 0, sizeof(*conn_info)); |
476 | } |
477 | |
478 | #endif |
479 | |
480 | /** |
481 | * cec_phys_addr_invalidate() - set the physical address to INVALID |
482 | * |
483 | * @adap: the CEC adapter |
484 | * |
485 | * This is a simple helper function to invalidate the physical |
486 | * address. |
487 | */ |
488 | static inline void cec_phys_addr_invalidate(struct cec_adapter *adap) |
489 | { |
490 | cec_s_phys_addr(adap, CEC_PHYS_ADDR_INVALID, block: false); |
491 | } |
492 | |
493 | /** |
494 | * cec_get_edid_spa_location() - find location of the Source Physical Address |
495 | * |
496 | * @edid: the EDID |
497 | * @size: the size of the EDID |
498 | * |
499 | * This EDID is expected to be a CEA-861 compliant, which means that there are |
500 | * at least two blocks and one or more of the extensions blocks are CEA-861 |
501 | * blocks. |
502 | * |
503 | * The returned location is guaranteed to be <= size-2. |
504 | * |
505 | * This is an inline function since it is used by both CEC and V4L2. |
506 | * Ideally this would go in a module shared by both, but it is overkill to do |
507 | * that for just a single function. |
508 | */ |
509 | static inline unsigned int cec_get_edid_spa_location(const u8 *edid, |
510 | unsigned int size) |
511 | { |
512 | unsigned int blocks = size / 128; |
513 | unsigned int block; |
514 | u8 d; |
515 | |
516 | /* Sanity check: at least 2 blocks and a multiple of the block size */ |
517 | if (blocks < 2 || size % 128) |
518 | return 0; |
519 | |
520 | /* |
521 | * If there are fewer extension blocks than the size, then update |
522 | * 'blocks'. It is allowed to have more extension blocks than the size, |
523 | * since some hardware can only read e.g. 256 bytes of the EDID, even |
524 | * though more blocks are present. The first CEA-861 extension block |
525 | * should normally be in block 1 anyway. |
526 | */ |
527 | if (edid[0x7e] + 1 < blocks) |
528 | blocks = edid[0x7e] + 1; |
529 | |
530 | for (block = 1; block < blocks; block++) { |
531 | unsigned int offset = block * 128; |
532 | |
533 | /* Skip any non-CEA-861 extension blocks */ |
534 | if (edid[offset] != 0x02 || edid[offset + 1] != 0x03) |
535 | continue; |
536 | |
537 | /* search Vendor Specific Data Block (tag 3) */ |
538 | d = edid[offset + 2] & 0x7f; |
539 | /* Check if there are Data Blocks */ |
540 | if (d <= 4) |
541 | continue; |
542 | if (d > 4) { |
543 | unsigned int i = offset + 4; |
544 | unsigned int end = offset + d; |
545 | |
546 | /* Note: 'end' is always < 'size' */ |
547 | do { |
548 | u8 tag = edid[i] >> 5; |
549 | u8 len = edid[i] & 0x1f; |
550 | |
551 | if (tag == 3 && len >= 5 && i + len <= end && |
552 | edid[i + 1] == 0x03 && |
553 | edid[i + 2] == 0x0c && |
554 | edid[i + 3] == 0x00) |
555 | return i + 4; |
556 | i += len + 1; |
557 | } while (i < end); |
558 | } |
559 | } |
560 | return 0; |
561 | } |
562 | |
563 | #endif /* _MEDIA_CEC_H */ |
564 | |