xref: /linux/include/media/cec.h (revision bb1c928df78ee6e3665a0d013e74108cc9abf34b)
1 /*
2  * cec - HDMI Consumer Electronics Control support header
3  *
4  * Copyright 2016 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
5  *
6  * This program is free software; you may redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; version 2 of the License.
9  *
10  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
11  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
12  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
13  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
14  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
15  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
16  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
17  * SOFTWARE.
18  */
19 
20 #ifndef _MEDIA_CEC_H
21 #define _MEDIA_CEC_H
22 
23 #include <linux/poll.h>
24 #include <linux/fs.h>
25 #include <linux/debugfs.h>
26 #include <linux/device.h>
27 #include <linux/cdev.h>
28 #include <linux/kthread.h>
29 #include <linux/timer.h>
30 #include <linux/cec-funcs.h>
31 #include <media/rc-core.h>
32 #include <media/cec-notifier.h>
33 
34 /**
35  * struct cec_devnode - cec device node
36  * @dev:	cec device
37  * @cdev:	cec character device
38  * @minor:	device node minor number
39  * @registered:	the device was correctly registered
40  * @unregistered: the device was unregistered
41  * @fhs_lock:	lock to control access to the filehandle list
42  * @fhs:	the list of open filehandles (cec_fh)
43  *
44  * This structure represents a cec-related device node.
45  *
46  * The @parent is a physical device. It must be set by core or device drivers
47  * before registering the node.
48  */
49 struct cec_devnode {
50 	/* sysfs */
51 	struct device dev;
52 	struct cdev cdev;
53 
54 	/* device info */
55 	int minor;
56 	bool registered;
57 	bool unregistered;
58 	struct list_head fhs;
59 	struct mutex lock;
60 };
61 
62 struct cec_adapter;
63 struct cec_data;
64 
65 struct cec_data {
66 	struct list_head list;
67 	struct list_head xfer_list;
68 	struct cec_adapter *adap;
69 	struct cec_msg msg;
70 	struct cec_fh *fh;
71 	struct delayed_work work;
72 	struct completion c;
73 	u8 attempts;
74 	bool new_initiator;
75 	bool blocking;
76 	bool completed;
77 };
78 
79 struct cec_msg_entry {
80 	struct list_head	list;
81 	struct cec_msg		msg;
82 };
83 
84 #define CEC_NUM_EVENTS		CEC_EVENT_LOST_MSGS
85 
86 struct cec_fh {
87 	struct list_head	list;
88 	struct list_head	xfer_list;
89 	struct cec_adapter	*adap;
90 	u8			mode_initiator;
91 	u8			mode_follower;
92 
93 	/* Events */
94 	wait_queue_head_t	wait;
95 	unsigned int		pending_events;
96 	struct cec_event	events[CEC_NUM_EVENTS];
97 	struct mutex		lock;
98 	struct list_head	msgs; /* queued messages */
99 	unsigned int		queued_msgs;
100 };
101 
102 #define CEC_SIGNAL_FREE_TIME_RETRY		3
103 #define CEC_SIGNAL_FREE_TIME_NEW_INITIATOR	5
104 #define CEC_SIGNAL_FREE_TIME_NEXT_XFER		7
105 
106 /* The nominal data bit period is 2.4 ms */
107 #define CEC_FREE_TIME_TO_USEC(ft)		((ft) * 2400)
108 
109 struct cec_adap_ops {
110 	/* Low-level callbacks */
111 	int (*adap_enable)(struct cec_adapter *adap, bool enable);
112 	int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
113 	int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
114 	int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
115 			     u32 signal_free_time, struct cec_msg *msg);
116 	void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
117 
118 	/* High-level CEC message callback */
119 	int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
120 };
121 
122 /*
123  * The minimum message length you can receive (excepting poll messages) is 2.
124  * With a transfer rate of at most 36 bytes per second this makes 18 messages
125  * per second worst case.
126  *
127  * We queue at most 3 seconds worth of received messages. The CEC specification
128  * requires that messages are replied to within a second, so 3 seconds should
129  * give more than enough margin. Since most messages are actually more than 2
130  * bytes, this is in practice a lot more than 3 seconds.
131  */
132 #define CEC_MAX_MSG_RX_QUEUE_SZ		(18 * 3)
133 
134 /*
135  * The transmit queue is limited to 1 second worth of messages (worst case).
136  * Messages can be transmitted by userspace and kernel space. But for both it
137  * makes no sense to have a lot of messages queued up. One second seems
138  * reasonable.
139  */
140 #define CEC_MAX_MSG_TX_QUEUE_SZ		(18 * 1)
141 
142 struct cec_adapter {
143 	struct module *owner;
144 	char name[32];
145 	struct cec_devnode devnode;
146 	struct mutex lock;
147 	struct rc_dev *rc;
148 
149 	struct list_head transmit_queue;
150 	unsigned int transmit_queue_sz;
151 	struct list_head wait_queue;
152 	struct cec_data *transmitting;
153 
154 	struct task_struct *kthread_config;
155 	struct completion config_completion;
156 
157 	struct task_struct *kthread;
158 	wait_queue_head_t kthread_waitq;
159 	wait_queue_head_t waitq;
160 
161 	const struct cec_adap_ops *ops;
162 	void *priv;
163 	u32 capabilities;
164 	u8 available_log_addrs;
165 
166 	u16 phys_addr;
167 	bool needs_hpd;
168 	bool is_configuring;
169 	bool is_configured;
170 	u32 monitor_all_cnt;
171 	u32 follower_cnt;
172 	struct cec_fh *cec_follower;
173 	struct cec_fh *cec_initiator;
174 	bool passthrough;
175 	struct cec_log_addrs log_addrs;
176 
177 #ifdef CONFIG_CEC_NOTIFIER
178 	struct cec_notifier *notifier;
179 #endif
180 
181 	struct dentry *cec_dir;
182 	struct dentry *status_file;
183 
184 	u16 phys_addrs[15];
185 	u32 sequence;
186 
187 	char input_name[32];
188 	char input_phys[32];
189 	char input_drv[32];
190 };
191 
192 static inline void *cec_get_drvdata(const struct cec_adapter *adap)
193 {
194 	return adap->priv;
195 }
196 
197 static inline bool cec_has_log_addr(const struct cec_adapter *adap, u8 log_addr)
198 {
199 	return adap->log_addrs.log_addr_mask & (1 << log_addr);
200 }
201 
202 static inline bool cec_is_sink(const struct cec_adapter *adap)
203 {
204 	return adap->phys_addr == 0;
205 }
206 
207 #define cec_phys_addr_exp(pa) \
208 	((pa) >> 12), ((pa) >> 8) & 0xf, ((pa) >> 4) & 0xf, (pa) & 0xf
209 
210 struct edid;
211 
212 #if IS_REACHABLE(CONFIG_CEC_CORE)
213 struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops,
214 		void *priv, const char *name, u32 caps, u8 available_las);
215 int cec_register_adapter(struct cec_adapter *adap, struct device *parent);
216 void cec_unregister_adapter(struct cec_adapter *adap);
217 void cec_delete_adapter(struct cec_adapter *adap);
218 
219 int cec_s_log_addrs(struct cec_adapter *adap, struct cec_log_addrs *log_addrs,
220 		    bool block);
221 void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr,
222 		     bool block);
223 void cec_s_phys_addr_from_edid(struct cec_adapter *adap,
224 			       const struct edid *edid);
225 int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg,
226 		     bool block);
227 
228 /* Called by the adapter */
229 void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt,
230 		       u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt);
231 /*
232  * Simplified version of cec_transmit_done for hardware that doesn't retry
233  * failed transmits. So this is always just one attempt in which case
234  * the status is sufficient.
235  */
236 void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status);
237 void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);
238 
239 /**
240  * cec_get_edid_phys_addr() - find and return the physical address
241  *
242  * @edid:	pointer to the EDID data
243  * @size:	size in bytes of the EDID data
244  * @offset:	If not %NULL then the location of the physical address
245  *		bytes in the EDID will be returned here. This is set to 0
246  *		if there is no physical address found.
247  *
248  * Return: the physical address or CEC_PHYS_ADDR_INVALID if there is none.
249  */
250 u16 cec_get_edid_phys_addr(const u8 *edid, unsigned int size,
251 			   unsigned int *offset);
252 
253 /**
254  * cec_set_edid_phys_addr() - find and set the physical address
255  *
256  * @edid:	pointer to the EDID data
257  * @size:	size in bytes of the EDID data
258  * @phys_addr:	the new physical address
259  *
260  * This function finds the location of the physical address in the EDID
261  * and fills in the given physical address and updates the checksum
262  * at the end of the EDID block. It does nothing if the EDID doesn't
263  * contain a physical address.
264  */
265 void cec_set_edid_phys_addr(u8 *edid, unsigned int size, u16 phys_addr);
266 
267 /**
268  * cec_phys_addr_for_input() - calculate the PA for an input
269  *
270  * @phys_addr:	the physical address of the parent
271  * @input:	the number of the input port, must be between 1 and 15
272  *
273  * This function calculates a new physical address based on the input
274  * port number. For example:
275  *
276  * PA = 0.0.0.0 and input = 2 becomes 2.0.0.0
277  *
278  * PA = 3.0.0.0 and input = 1 becomes 3.1.0.0
279  *
280  * PA = 3.2.1.0 and input = 5 becomes 3.2.1.5
281  *
282  * PA = 3.2.1.3 and input = 5 becomes f.f.f.f since it maxed out the depth.
283  *
284  * Return: the new physical address or CEC_PHYS_ADDR_INVALID.
285  */
286 u16 cec_phys_addr_for_input(u16 phys_addr, u8 input);
287 
288 /**
289  * cec_phys_addr_validate() - validate a physical address from an EDID
290  *
291  * @phys_addr:	the physical address to validate
292  * @parent:	if not %NULL, then this is filled with the parents PA.
293  * @port:	if not %NULL, then this is filled with the input port.
294  *
295  * This validates a physical address as read from an EDID. If the
296  * PA is invalid (such as 1.0.1.0 since '0' is only allowed at the end),
297  * then it will return -EINVAL.
298  *
299  * The parent PA is passed into %parent and the input port is passed into
300  * %port. For example:
301  *
302  * PA = 0.0.0.0: has parent 0.0.0.0 and input port 0.
303  *
304  * PA = 1.0.0.0: has parent 0.0.0.0 and input port 1.
305  *
306  * PA = 3.2.0.0: has parent 3.0.0.0 and input port 2.
307  *
308  * PA = f.f.f.f: has parent f.f.f.f and input port 0.
309  *
310  * Return: 0 if the PA is valid, -EINVAL if not.
311  */
312 int cec_phys_addr_validate(u16 phys_addr, u16 *parent, u16 *port);
313 
314 #ifdef CONFIG_CEC_NOTIFIER
315 void cec_register_cec_notifier(struct cec_adapter *adap,
316 			       struct cec_notifier *notifier);
317 #endif
318 
319 #else
320 
321 static inline int cec_register_adapter(struct cec_adapter *adap,
322 				       struct device *parent)
323 {
324 	return 0;
325 }
326 
327 static inline void cec_unregister_adapter(struct cec_adapter *adap)
328 {
329 }
330 
331 static inline void cec_delete_adapter(struct cec_adapter *adap)
332 {
333 }
334 
335 static inline void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr,
336 				   bool block)
337 {
338 }
339 
340 static inline void cec_s_phys_addr_from_edid(struct cec_adapter *adap,
341 					     const struct edid *edid)
342 {
343 }
344 
345 static inline u16 cec_get_edid_phys_addr(const u8 *edid, unsigned int size,
346 					 unsigned int *offset)
347 {
348 	if (offset)
349 		*offset = 0;
350 	return CEC_PHYS_ADDR_INVALID;
351 }
352 
353 static inline void cec_set_edid_phys_addr(u8 *edid, unsigned int size,
354 					  u16 phys_addr)
355 {
356 }
357 
358 static inline u16 cec_phys_addr_for_input(u16 phys_addr, u8 input)
359 {
360 	return CEC_PHYS_ADDR_INVALID;
361 }
362 
363 static inline int cec_phys_addr_validate(u16 phys_addr, u16 *parent, u16 *port)
364 {
365 	return 0;
366 }
367 
368 #endif
369 
370 /**
371  * cec_phys_addr_invalidate() - set the physical address to INVALID
372  *
373  * @adap:	the CEC adapter
374  *
375  * This is a simple helper function to invalidate the physical
376  * address.
377  */
378 static inline void cec_phys_addr_invalidate(struct cec_adapter *adap)
379 {
380 	cec_s_phys_addr(adap, CEC_PHYS_ADDR_INVALID, false);
381 }
382 
383 #endif /* _MEDIA_CEC_H */
384