xref: /illumos-gate/usr/src/uts/common/sys/usb/clients/video/usbvc/usbvc_var.h (revision bea83d026ee1bd1b2a2419e1d0232f107a5d7d9b)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef _SYS_USB_USBVC_VAR_H
27 #define	_SYS_USB_USBVC_VAR_H
28 
29 #pragma ident	"%Z%%M%	%I%	%E% SMI"
30 
31 #ifdef	__cplusplus
32 extern "C" {
33 #endif
34 
35 #include <sys/list.h>
36 #include <sys/usb/usba/usbai_private.h>
37 #include <sys/videodev2.h>
38 #include <sys/usb/clients/video/usbvc/usbvc.h>
39 
40 typedef struct usbvc_state usbvc_state_t;
41 
42 /*
43  * Power Management support
44  */
45 typedef struct usbvc_power  {
46 
47 	void		*usbvc_state;	/* points back to usbvc_state */
48 	uint8_t		usbvc_pwr_states; /* bit mask of device pwr states */
49 	int		usbvc_pm_busy;
50 
51 	/* Wakeup and power transistion capabilites of an interface */
52 	uint8_t		usbvc_pm_capabilities;
53 
54 	/* flag to indicate if driver is about to raise power level */
55 	boolean_t	usbvc_raise_power;
56 
57 	uint8_t		usbvc_current_power;
58 	uint8_t		usbvc_wakeup_enabled;
59 } usbvc_power_t;
60 
61 /* Raw data buf from the USB cam */
62 typedef struct usbvc_buf
63 {
64 	uchar_t *data;
65 	uint_t len;	/* the length of the allocated memory of data */
66 	uint_t filled;	/* number of bytes filled */
67 	uchar_t status; /* empty, filling done, read done */
68 
69 	/* cookie used for memory mapping */
70 	ddi_umem_cookie_t	umem_cookie;
71 	struct			v4l2_buffer v4l2_buf;
72 	list_node_t		buf_node;	/* list */
73 } usbvc_buf_t;
74 
75 /* Group data buf related lists and other elements */
76 typedef struct usbvc_buf_grp
77 {
78 	list_t		uv_buf_free;
79 	list_t		uv_buf_done;
80 	usbvc_buf_t	*buf_filling;
81 	uint_t		buf_cnt;
82 	usbvc_buf_t	*buf_head;
83 } usbvc_buf_grp_t;
84 
85 /*
86  * UVC Spec: one format descriptor may be followed by sererval frame
87  * descriptors, one still image descriptor and one color matching descriptor.
88  * It is called a format group. There might be several format groups follow
89  * one input/output header.
90  */
91 typedef struct usbvc_format_group {
92 	usbvc_format_descr_t	*format;
93 	usbvc_frames_t		*frames;
94 	uint8_t			frame_cnt;
95 
96 	/* bytes per pix, used to calculate bytesperline */
97 	uint8_t			v4l2_bpp;
98 
99 	uint8_t			v4l2_color;
100 	uint32_t		v4l2_pixelformat;	/* fcc, pixelformat */
101 	usbvc_still_image_frame_t	*still;
102 	usbvc_color_matching_descr_t	*color;
103 	usbvc_frames_t			*cur_frame;
104 } usbvc_format_group_t;
105 
106 /* A stream interface may have several format groups */
107 typedef struct usbvc_stream_if {
108 
109 	/* The actual format groups we parsed for the stream interface */
110 	uint8_t			fmtgrp_cnt;
111 
112 	usb_if_data_t		*if_descr;
113 	usbvc_input_header_t	*input_header;
114 	usbvc_output_header_t	*output_header;
115 	usbvc_format_group_t	*format_group;
116 	usbvc_format_group_t	*cur_format_group;
117 	usbvc_vs_probe_commit_t	ctrl_pc;
118 	usb_ep_descr_t		*curr_ep;	/* current isoc ep descr */
119 	usb_pipe_handle_t	datain_ph;	/* current isoc pipe handle */
120 	uint_t			curr_alt;	/* current alternate  */
121 
122 	/* The max payload that the isoc data EPs can support */
123 	uint32_t	max_isoc_payload;
124 
125 	uchar_t		start_polling;	/* indicate if isoc polling started */
126 	uchar_t		fid;		/* the MJPEG FID bit */
127 	usbvc_buf_grp_t	buf_read;	/* buf used for read I/O */
128 	usbvc_buf_grp_t	buf_map;	/* buf used for mmap I/O */
129 	list_node_t	stream_if_node;
130 } usbvc_stream_if_t;
131 
132 /* video interface collection */
133 typedef struct usbvc_vic {
134 
135 	/* bFirstInterface, the video control infterface num of this VIC */
136 	uint8_t	vctrl_if_num;
137 
138 	/*
139 	 * bInterfaceCount -1, the total number of stream interfaces
140 	 * belong to this VIC
141 	 */
142 	uint8_t	vstrm_if_cnt;
143 } usbvc_vic_t;
144 
145 /* Macros */
146 #define	USBVC_OPEN		0x00000001
147 
148 /* For serialization. */
149 #define	USBVC_SER_NOSIG	B_FALSE
150 #define	USBVC_SER_SIG		B_TRUE
151 
152 /*
153  * Masks for debug printing
154  */
155 #define	PRINT_MASK_ATTA		0x00000001
156 #define	PRINT_MASK_OPEN 	0x00000002
157 #define	PRINT_MASK_CLOSE	0x00000004
158 #define	PRINT_MASK_READ		0x00000008
159 #define	PRINT_MASK_IOCTL	0x00000010
160 #define	PRINT_MASK_PM	0x00000020
161 #define	PRINT_MASK_CB	0x00000040
162 #define	PRINT_MASK_HOTPLUG	0x00000080
163 #define	PRINT_MASK_DEVCTRL	0x00000100
164 #define	PRINT_MASK_DEVMAP	0x00000200
165 #define	PRINT_MASK_ALL		0xFFFFFFFF
166 
167 #define	offsetof(s, m)	((size_t)(&(((s *)0)->m)))
168 
169 #define	USBVC_MAX_PKTS 40
170 
171 #define	USBVC_READ_BUF_NUM 3
172 #define	USBVC_MAX_MAP_BUF_NUM 40
173 
174 /* Only D3...D0 are writable, Table 4-6, UVC Spec */
175 #define	USBVC_POWER_MODE_MASK	0xf0;
176 
177 enum usbvc_buf_status {
178 	USBVC_BUF_INIT		= 0,  /* Allocated, to be queued */
179 	USBVC_BUF_MAPPED	= 1,  /* For map I/O only. Memory is mapped. */
180 	USBVC_BUF_EMPTY		= 2, /* not initialized, to be filled */
181 
182 	/*
183 	 * buf is filled with a full frame without any errors,
184 	 * it will be moved to full list.
185 	 */
186 	USBVC_BUF_DONE		= 4,
187 
188 	/*
189 	 * buf is filled to full but no EOF bit is found at the end
190 	 * of video data
191 	 */
192 	USBVC_BUF_ERR		= 8
193 };
194 
195 /*
196  * This structure is used to map v4l2 controls to uvc controls. The structure
197  * array is addressed by (V4L2_CID_BASE - V4L2_CID_*)
198  */
199 typedef struct usbvc_v4l2_ctrl_map {
200 	char	name[32];
201 	uint8_t	selector; /* Control Selector */
202 	uint8_t	len;	/* wLength, defined in uvc spec chp 4 for each ctrl */
203 
204 	/* The xth bit in bmControls bitmap of processing unit descriptor */
205 	uint8_t	bit;
206 
207 	enum	v4l2_ctrl_type type;
208 } usbvc_v4l2_ctrl_map_t;
209 
210 typedef struct usbvc_v4l2_ctrl {
211 	uint8_t			entity_id;
212 	usbvc_v4l2_ctrl_map_t	*ctrl_map;
213 } usbvc_v4l2_ctrl_t;
214 
215 
216 /*
217  * State structure
218  */
219 struct usbvc_state {
220 	dev_info_t		*usbvc_dip;	/* per-device info handle */
221 	usb_client_dev_data_t	*usbvc_reg;	/* registration data */
222 	int			usbvc_dev_state; /* USB device states. */
223 	int			usbvc_drv_state; /* driver states. */
224 	kmutex_t		usbvc_mutex;
225 	kcondvar_t		usbvc_serial_cv;
226 	boolean_t		usbvc_serial_inuse;
227 	boolean_t		usbvc_locks_initialized;
228 
229 	usbvc_power_t		*usbvc_pm;
230 
231 	usb_log_handle_t	usbvc_log_handle;	/* log handle */
232 	usb_pipe_handle_t	usbvc_default_ph; /* default pipe */
233 
234 	/* Video ctrl interface header descriptor */
235 	usbvc_vc_header_t	*usbvc_vc_header;
236 	list_t			usbvc_term_list;
237 	list_t			usbvc_unit_list;
238 
239 	list_t			usbvc_stream_list;
240 	usbvc_stream_if_t	*usbvc_curr_strm;
241 	kcondvar_t		usbvc_read_cv;	/* wait for read buf done */
242 	kcondvar_t		usbvc_mapio_cv;	/* wait for mmap I/O buf done */
243 
244 	/* current I/O type: read or mmap. */
245 	uchar_t			usbvc_io_type;
246 };
247 
248 
249 /*
250  * Used in ioctl entry to copy an argument from kernel space (arg_name)
251  * to USER space (arg)
252  */
253 #define	USBVC_COPYOUT(arg_name) \
254 if (ddi_copyout(&arg_name, (caddr_t)arg, sizeof (arg_name), mode)) { \
255 	rv = EFAULT; \
256 	break;	\
257 }
258 
259 /*
260  * Used in ioctl entry to copy an argument from USER space (arg) to
261  * KERNEL space (arg_name)
262  */
263 #define	USBVC_COPYIN(arg_name) \
264 if (ddi_copyin((caddr_t)arg, &arg_name, sizeof (arg_name), mode)) { \
265 	rv = EFAULT; \
266 	break;	\
267 }
268 
269 /* Turn a little endian byte array to a uint32_t */
270 #define	LE_TO_UINT32(src, off, des)	{ \
271 				uint32_t tmp; \
272 				des = src[off + 3]; \
273 				des = des << 24; \
274 				tmp = src[off + 2]; \
275 				des |= tmp << 16; \
276 				tmp = src[off + 1]; \
277 				des |= tmp << 8; \
278 				des |= src[off]; \
279 				}
280 
281 /* Turn a uint32_t to a little endian byte array */
282 #define	UINT32_TO_LE(src, off, des)	{ \
283 				des[off + 0] = 0xff & src; \
284 				des[off + 1] = 0xff & (src >> 8); \
285 				des[off + 2] = 0xff & (src >> 16); \
286 				des[off + 3] = 0xff & (src >> 24); \
287 				}
288 
289 /* Turn a little endian byte array to a uint16_t */
290 #define	LE_TO_UINT16(src, off, des)	 \
291 				des = src[off + 1]; \
292 				des = des << 8; \
293 				des |= src[off];
294 
295 /* Turn a uint16_t to alittle endian byte array */
296 #define	UINT16_TO_LE(src, off, des)	{ \
297 				des[off + 0] = 0xff & src; \
298 				des[off + 1] = 0xff & (src >> 8); \
299 				}
300 
301 #define	NELEM(a)	(sizeof (a) / sizeof (*(a)))
302 
303 /* Minimum length of class specific descriptors */
304 #define	USBVC_C_HEAD_LEN_MIN	12	/* ctrl header */
305 #define	USBVC_I_TERM_LEN_MIN	8	/* input term */
306 #define	USBVC_O_TERM_LEN_MIN	9	/* output term */
307 #define	USBVC_P_UNIT_LEN_MIN	8	/* processing unit */
308 #define	USBVC_S_UNIT_LEN_MIN	5	/* selector unit */
309 #define	USBVC_E_UNIT_LEN_MIN	22	/* extension unit */
310 #define	USBVC_FRAME_LEN_MIN	26	/* Frame descriptor */
311 
312 /* Length of the Frame descriptor which has continuous frame intervals */
313 #define	USBVC_FRAME_LEN_CON	38
314 
315 
316 /*
317  * According to usb2.0 spec (table 9-13), for all ep, bits 10..0 specify the
318  * max pkt size; for high speed ep, bits 12..11 specify the number of
319  * additional transaction opportunities per microframe.
320  */
321 #define	HS_PKT_SIZE(pktsize) (pktsize & 0x07ff) * (1 + ((pktsize >> 11) & 3))
322 
323 /*
324  * warlock directives
325  * _NOTE is an advice for locklint.  Locklint checks lock use for deadlocks.
326  */
327 _NOTE(MUTEX_PROTECTS_DATA(usbvc_state_t::usbvc_mutex, usbvc_state_t))
328 _NOTE(DATA_READABLE_WITHOUT_LOCK(usbvc_state_t::{
329 	usbvc_dip
330 	usbvc_pm
331 	usbvc_log_handle
332 	usbvc_reg
333 	usbvc_default_ph
334 	usbvc_vc_header
335 	usbvc_term_list
336 	usbvc_unit_list
337 	usbvc_stream_list
338 }))
339 
340 _NOTE(SCHEME_PROTECTS_DATA("stable data", usb_pipe_policy))
341 _NOTE(SCHEME_PROTECTS_DATA("USBA", usbvc_stream_if::datain_ph))
342 _NOTE(SCHEME_PROTECTS_DATA("USBA", usbvc_stream_if::curr_alt))
343 _NOTE(SCHEME_PROTECTS_DATA("USBA", usbvc_stream_if::curr_ep))
344 _NOTE(SCHEME_PROTECTS_DATA("unshared data", usbvc_buf::umem_cookie))
345 _NOTE(SCHEME_PROTECTS_DATA("unshared data", usbvc_buf::data))
346 _NOTE(SCHEME_PROTECTS_DATA("unshared data", usbvc_v4l2_ctrl))
347 _NOTE(SCHEME_PROTECTS_DATA("unshared data", usbvc_v4l2_ctrl_map))
348 _NOTE(SCHEME_PROTECTS_DATA("unshared data", mblk_t))
349 _NOTE(SCHEME_PROTECTS_DATA("unshared data", buf))
350 _NOTE(SCHEME_PROTECTS_DATA("unshared data", usb_isoc_req))
351 _NOTE(SCHEME_PROTECTS_DATA("unshared data", v4l2_queryctrl))
352 _NOTE(SCHEME_PROTECTS_DATA("unshared data", v4l2_format))
353 _NOTE(SCHEME_PROTECTS_DATA("unshared data", v4l2_control))
354 
355 int	usbvc_open_isoc_pipe(usbvc_state_t *, usbvc_stream_if_t *);
356 int	usbvc_start_isoc_polling(usbvc_state_t *, usbvc_stream_if_t *, uchar_t);
357 int	usbvc_vc_set_ctrl(usbvc_state_t *, uint8_t,  uint8_t,
358 		uint16_t, uint16_t, mblk_t *);
359 int	usbvc_vc_get_ctrl(usbvc_state_t *, uint8_t,  uint8_t,
360 		uint16_t, uint16_t, mblk_t *);
361 int	usbvc_vs_set_probe_commit(usbvc_state_t *, usbvc_stream_if_t *,
362 	usbvc_vs_probe_commit_t *, uchar_t);
363 void	usbvc_free_map_bufs(usbvc_state_t *, usbvc_stream_if_t *);
364 int	usbvc_alloc_map_bufs(usbvc_state_t *, usbvc_stream_if_t *, int, int);
365 int	usbvc_vs_get_probe(usbvc_state_t *, usbvc_stream_if_t *,
366 		usbvc_vs_probe_commit_t *, uchar_t);
367 
368 /* Functions specific for V4L2 API */
369 uint8_t		usbvc_v4l2_colorspace(uint8_t);
370 uint32_t	usbvc_v4l2_guid2fcc(uint8_t *);
371 int		usbvc_v4l2_ioctl(usbvc_state_t *, int, intptr_t, int);
372 
373 
374 #ifdef __cplusplus
375 }
376 #endif
377 
378 #endif	/* _SYS_USB_USBVC_VAR_H */
379