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_timeouts: number of transmit timeouts |
211 | * @notifier: CEC notifier |
212 | * @pin: CEC pin status struct |
213 | * @cec_dir: debugfs cec directory |
214 | * @status_file: debugfs cec status file |
215 | * @error_inj_file: debugfs cec error injection file |
216 | * @sequence: transmit sequence counter |
217 | * @input_phys: remote control input_phys name |
218 | * |
219 | * This structure represents a cec adapter. |
220 | */ |
221 | struct cec_adapter { |
222 | struct module *owner; |
223 | char name[32]; |
224 | struct cec_devnode devnode; |
225 | struct mutex lock; |
226 | struct rc_dev *rc; |
227 | |
228 | struct list_head transmit_queue; |
229 | unsigned int transmit_queue_sz; |
230 | struct list_head wait_queue; |
231 | struct cec_data *transmitting; |
232 | bool transmit_in_progress; |
233 | bool transmit_in_progress_aborted; |
234 | unsigned int xfer_timeout_ms; |
235 | |
236 | struct task_struct *kthread_config; |
237 | struct completion config_completion; |
238 | |
239 | struct task_struct *kthread; |
240 | wait_queue_head_t kthread_waitq; |
241 | |
242 | const struct cec_adap_ops *ops; |
243 | void *priv; |
244 | u32 capabilities; |
245 | u8 available_log_addrs; |
246 | |
247 | u16 phys_addr; |
248 | bool needs_hpd; |
249 | bool is_enabled; |
250 | bool is_configuring; |
251 | bool must_reconfigure; |
252 | bool is_configured; |
253 | bool cec_pin_is_high; |
254 | bool adap_controls_phys_addr; |
255 | u8 last_initiator; |
256 | u32 monitor_all_cnt; |
257 | u32 monitor_pin_cnt; |
258 | u32 follower_cnt; |
259 | struct cec_fh *cec_follower; |
260 | struct cec_fh *cec_initiator; |
261 | bool passthrough; |
262 | struct cec_log_addrs log_addrs; |
263 | struct cec_connector_info conn_info; |
264 | |
265 | u32 tx_timeouts; |
266 | |
267 | #ifdef CONFIG_CEC_NOTIFIER |
268 | struct cec_notifier *notifier; |
269 | #endif |
270 | #ifdef CONFIG_CEC_PIN |
271 | struct cec_pin *pin; |
272 | #endif |
273 | |
274 | struct dentry *cec_dir; |
275 | |
276 | u32 sequence; |
277 | |
278 | char input_phys[40]; |
279 | }; |
280 | |
281 | static inline void *cec_get_drvdata(const struct cec_adapter *adap) |
282 | { |
283 | return adap->priv; |
284 | } |
285 | |
286 | static inline bool cec_has_log_addr(const struct cec_adapter *adap, u8 log_addr) |
287 | { |
288 | return adap->log_addrs.log_addr_mask & (1 << log_addr); |
289 | } |
290 | |
291 | static inline bool cec_is_sink(const struct cec_adapter *adap) |
292 | { |
293 | return adap->phys_addr == 0; |
294 | } |
295 | |
296 | /** |
297 | * cec_is_registered() - is the CEC adapter registered? |
298 | * |
299 | * @adap: the CEC adapter, may be NULL. |
300 | * |
301 | * Return: true if the adapter is registered, false otherwise. |
302 | */ |
303 | static inline bool cec_is_registered(const struct cec_adapter *adap) |
304 | { |
305 | return adap && adap->devnode.registered; |
306 | } |
307 | |
308 | #define cec_phys_addr_exp(pa) \ |
309 | ((pa) >> 12), ((pa) >> 8) & 0xf, ((pa) >> 4) & 0xf, (pa) & 0xf |
310 | |
311 | struct edid; |
312 | struct drm_connector; |
313 | |
314 | #if IS_REACHABLE(CONFIG_CEC_CORE) |
315 | struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, |
316 | void *priv, const char *name, u32 caps, u8 available_las); |
317 | int cec_register_adapter(struct cec_adapter *adap, struct device *parent); |
318 | void cec_unregister_adapter(struct cec_adapter *adap); |
319 | void cec_delete_adapter(struct cec_adapter *adap); |
320 | |
321 | int cec_s_log_addrs(struct cec_adapter *adap, struct cec_log_addrs *log_addrs, |
322 | bool block); |
323 | void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, |
324 | bool block); |
325 | void cec_s_phys_addr_from_edid(struct cec_adapter *adap, |
326 | const struct edid *edid); |
327 | void cec_s_conn_info(struct cec_adapter *adap, |
328 | const struct cec_connector_info *conn_info); |
329 | int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, |
330 | bool block); |
331 | |
332 | /* Called by the adapter */ |
333 | void cec_transmit_done_ts(struct cec_adapter *adap, u8 status, |
334 | u8 arb_lost_cnt, u8 nack_cnt, u8 low_drive_cnt, |
335 | u8 error_cnt, ktime_t ts); |
336 | |
337 | static inline void cec_transmit_done(struct cec_adapter *adap, u8 status, |
338 | u8 arb_lost_cnt, u8 nack_cnt, |
339 | u8 low_drive_cnt, u8 error_cnt) |
340 | { |
341 | cec_transmit_done_ts(adap, status, arb_lost_cnt, nack_cnt, |
342 | low_drive_cnt, error_cnt, ts: ktime_get()); |
343 | } |
344 | /* |
345 | * Simplified version of cec_transmit_done for hardware that doesn't retry |
346 | * failed transmits. So this is always just one attempt in which case |
347 | * the status is sufficient. |
348 | */ |
349 | void cec_transmit_attempt_done_ts(struct cec_adapter *adap, |
350 | u8 status, ktime_t ts); |
351 | |
352 | static inline void cec_transmit_attempt_done(struct cec_adapter *adap, |
353 | u8 status) |
354 | { |
355 | cec_transmit_attempt_done_ts(adap, status, ts: ktime_get()); |
356 | } |
357 | |
358 | void cec_received_msg_ts(struct cec_adapter *adap, |
359 | struct cec_msg *msg, ktime_t ts); |
360 | |
361 | static inline void cec_received_msg(struct cec_adapter *adap, |
362 | struct cec_msg *msg) |
363 | { |
364 | cec_received_msg_ts(adap, msg, ts: ktime_get()); |
365 | } |
366 | |
367 | /** |
368 | * cec_queue_pin_cec_event() - queue a CEC pin event with a given timestamp. |
369 | * |
370 | * @adap: pointer to the cec adapter |
371 | * @is_high: when true the CEC pin is high, otherwise it is low |
372 | * @dropped_events: when true some events were dropped |
373 | * @ts: the timestamp for this event |
374 | * |
375 | */ |
376 | void cec_queue_pin_cec_event(struct cec_adapter *adap, bool is_high, |
377 | bool dropped_events, ktime_t ts); |
378 | |
379 | /** |
380 | * cec_queue_pin_hpd_event() - queue a pin event with a given timestamp. |
381 | * |
382 | * @adap: pointer to the cec adapter |
383 | * @is_high: when true the HPD pin is high, otherwise it is low |
384 | * @ts: the timestamp for this event |
385 | * |
386 | */ |
387 | void cec_queue_pin_hpd_event(struct cec_adapter *adap, bool is_high, ktime_t ts); |
388 | |
389 | /** |
390 | * cec_queue_pin_5v_event() - queue a pin event with a given timestamp. |
391 | * |
392 | * @adap: pointer to the cec adapter |
393 | * @is_high: when true the 5V pin is high, otherwise it is low |
394 | * @ts: the timestamp for this event |
395 | * |
396 | */ |
397 | void cec_queue_pin_5v_event(struct cec_adapter *adap, bool is_high, ktime_t ts); |
398 | |
399 | /** |
400 | * cec_get_edid_phys_addr() - find and return the physical address |
401 | * |
402 | * @edid: pointer to the EDID data |
403 | * @size: size in bytes of the EDID data |
404 | * @offset: If not %NULL then the location of the physical address |
405 | * bytes in the EDID will be returned here. This is set to 0 |
406 | * if there is no physical address found. |
407 | * |
408 | * Return: the physical address or CEC_PHYS_ADDR_INVALID if there is none. |
409 | */ |
410 | u16 cec_get_edid_phys_addr(const u8 *edid, unsigned int size, |
411 | unsigned int *offset); |
412 | |
413 | void cec_fill_conn_info_from_drm(struct cec_connector_info *conn_info, |
414 | const struct drm_connector *connector); |
415 | |
416 | #else |
417 | |
418 | static inline int cec_register_adapter(struct cec_adapter *adap, |
419 | struct device *parent) |
420 | { |
421 | return 0; |
422 | } |
423 | |
424 | static inline void cec_unregister_adapter(struct cec_adapter *adap) |
425 | { |
426 | } |
427 | |
428 | static inline void cec_delete_adapter(struct cec_adapter *adap) |
429 | { |
430 | } |
431 | |
432 | static inline void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, |
433 | bool block) |
434 | { |
435 | } |
436 | |
437 | static inline void cec_s_phys_addr_from_edid(struct cec_adapter *adap, |
438 | const struct edid *edid) |
439 | { |
440 | } |
441 | |
442 | static inline u16 cec_get_edid_phys_addr(const u8 *edid, unsigned int size, |
443 | unsigned int *offset) |
444 | { |
445 | if (offset) |
446 | *offset = 0; |
447 | return CEC_PHYS_ADDR_INVALID; |
448 | } |
449 | |
450 | static inline void cec_s_conn_info(struct cec_adapter *adap, |
451 | const struct cec_connector_info *conn_info) |
452 | { |
453 | } |
454 | |
455 | static inline void |
456 | cec_fill_conn_info_from_drm(struct cec_connector_info *conn_info, |
457 | const struct drm_connector *connector) |
458 | { |
459 | memset(conn_info, 0, sizeof(*conn_info)); |
460 | } |
461 | |
462 | #endif |
463 | |
464 | /** |
465 | * cec_phys_addr_invalidate() - set the physical address to INVALID |
466 | * |
467 | * @adap: the CEC adapter |
468 | * |
469 | * This is a simple helper function to invalidate the physical |
470 | * address. |
471 | */ |
472 | static inline void cec_phys_addr_invalidate(struct cec_adapter *adap) |
473 | { |
474 | cec_s_phys_addr(adap, CEC_PHYS_ADDR_INVALID, block: false); |
475 | } |
476 | |
477 | /** |
478 | * cec_get_edid_spa_location() - find location of the Source Physical Address |
479 | * |
480 | * @edid: the EDID |
481 | * @size: the size of the EDID |
482 | * |
483 | * This EDID is expected to be a CEA-861 compliant, which means that there are |
484 | * at least two blocks and one or more of the extensions blocks are CEA-861 |
485 | * blocks. |
486 | * |
487 | * The returned location is guaranteed to be <= size-2. |
488 | * |
489 | * This is an inline function since it is used by both CEC and V4L2. |
490 | * Ideally this would go in a module shared by both, but it is overkill to do |
491 | * that for just a single function. |
492 | */ |
493 | static inline unsigned int cec_get_edid_spa_location(const u8 *edid, |
494 | unsigned int size) |
495 | { |
496 | unsigned int blocks = size / 128; |
497 | unsigned int block; |
498 | u8 d; |
499 | |
500 | /* Sanity check: at least 2 blocks and a multiple of the block size */ |
501 | if (blocks < 2 || size % 128) |
502 | return 0; |
503 | |
504 | /* |
505 | * If there are fewer extension blocks than the size, then update |
506 | * 'blocks'. It is allowed to have more extension blocks than the size, |
507 | * since some hardware can only read e.g. 256 bytes of the EDID, even |
508 | * though more blocks are present. The first CEA-861 extension block |
509 | * should normally be in block 1 anyway. |
510 | */ |
511 | if (edid[0x7e] + 1 < blocks) |
512 | blocks = edid[0x7e] + 1; |
513 | |
514 | for (block = 1; block < blocks; block++) { |
515 | unsigned int offset = block * 128; |
516 | |
517 | /* Skip any non-CEA-861 extension blocks */ |
518 | if (edid[offset] != 0x02 || edid[offset + 1] != 0x03) |
519 | continue; |
520 | |
521 | /* search Vendor Specific Data Block (tag 3) */ |
522 | d = edid[offset + 2] & 0x7f; |
523 | /* Check if there are Data Blocks */ |
524 | if (d <= 4) |
525 | continue; |
526 | if (d > 4) { |
527 | unsigned int i = offset + 4; |
528 | unsigned int end = offset + d; |
529 | |
530 | /* Note: 'end' is always < 'size' */ |
531 | do { |
532 | u8 tag = edid[i] >> 5; |
533 | u8 len = edid[i] & 0x1f; |
534 | |
535 | if (tag == 3 && len >= 5 && i + len <= end && |
536 | edid[i + 1] == 0x03 && |
537 | edid[i + 2] == 0x0c && |
538 | edid[i + 3] == 0x00) |
539 | return i + 4; |
540 | i += len + 1; |
541 | } while (i < end); |
542 | } |
543 | } |
544 | return 0; |
545 | } |
546 | |
547 | #endif /* _MEDIA_CEC_H */ |
548 | |