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 2008 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef	_SYS_USB_HUBDVAR_H
27 #define	_SYS_USB_HUBDVAR_H
28 
29 
30 #ifdef	__cplusplus
31 extern "C" {
32 #endif
33 
34 #include <sys/sunndi.h>
35 #include <sys/ndi_impldefs.h>
36 #include <sys/usb/usba/usba_types.h>
37 #include <sys/callb.h>
38 
39 /*
40  * HUB USB device state management :
41  *
42  *                          CHILD PWRLVL---1>--------+
43  *                               ^                   |
44  *                               8                   |
45  *                               |                   |
46  *                               9                   |
47  *                               v                   |
48  *	PWRED_DWN---<3----4>--ONLINE---<2-----1>-DISCONNECTED
49  *          |                  |  ^                |  |
50  *          |                  |  10               |  |
51  *          |                  |  |                |  |
52  *          |                  |  RECOVER-<2-------+  |
53  *          |                  |  ^                   |
54  *          |                  5  6                   |
55  *          |                  |  |                   |
56  *          |                  v  |                   |
57  *          +----5>----------SUSPENDED----<5----7>----+
58  *
59  *	1 = Device Unplug
60  *	2 = Original Device reconnected and after hub driver restores its own
61  *	    device state.
62  *	3 = Device idles for time T & transitions to low power state
63  *	4 = Remote wakeup by device OR Application kicking off IO to device
64  *	5 = Notification to save state prior to DDI_SUSPEND
65  *	6 = Notification to restore state after DDI_RESUME with correct device
66  *          and after hub driver restores its own device state.
67  *	7 = Notification to restore state after DDI_RESUME with device
68  *	    disconnected or a wrong device
69  *	8 = Hub detect child doing remote wakeup and request the PM
70  *	    framework to bring it to full power
71  *      9 = PM framework has compeleted call power entry point of the child
72  *	    and bus ctls of hub
73  *     10 = Restoring states of its children i.e. set addrs & config.
74  *
75  */
76 
77 #define	HUBD_INITIAL_SOFT_SPACE	4
78 
79 typedef struct hub_power_struct {
80 	void		*hubp_hubd;	/* points back to hubd_t */
81 
82 	uint8_t		hubp_wakeup_enabled;	/* remote wakeup enabled? */
83 
84 	/* this is the bit mask of the power states that device has */
85 	uint8_t		hubp_pwr_states;
86 
87 	int		hubp_busy_pm;	/* device busy accounting */
88 
89 	/* wakeup and power transition capabilities of an interface */
90 	uint8_t		hubp_pm_capabilities;
91 
92 	uint8_t		hubp_current_power;	/* current power level */
93 
94 	time_t		hubp_time_at_full_power;	/* timestamp 0->3 */
95 
96 	uint8_t		hubp_min_pm_threshold;		/* in seconds */
97 
98 	/* power state of all children are tracked here */
99 	uint8_t		*hubp_child_pwrstate;
100 
101 	/* pm-components properties are stored here */
102 	char		*hubp_pmcomp[5];
103 
104 	usba_cfg_pwr_descr_t	hubp_confpwr_descr; /* config pwr descr */
105 } hub_power_t;
106 
107 /* warlock directives, stable data */
108 _NOTE(DATA_READABLE_WITHOUT_LOCK(hub_power_t::hubp_hubd))
109 _NOTE(DATA_READABLE_WITHOUT_LOCK(hub_power_t::hubp_wakeup_enabled))
110 _NOTE(DATA_READABLE_WITHOUT_LOCK(hub_power_t::hubp_pwr_states))
111 _NOTE(DATA_READABLE_WITHOUT_LOCK(hub_power_t::hubp_time_at_full_power))
112 _NOTE(DATA_READABLE_WITHOUT_LOCK(hub_power_t::hubp_min_pm_threshold))
113 _NOTE(DATA_READABLE_WITHOUT_LOCK(hub_power_t::hubp_pm_capabilities))
114 _NOTE(DATA_READABLE_WITHOUT_LOCK(hub_power_t::hubp_pmcomp))
115 _NOTE(DATA_READABLE_WITHOUT_LOCK(hub_power_t::hubp_confpwr_descr))
116 
117 
118 #define	HUBD_APID_NAMELEN	32		/* max len in cfgadm display */
119 
120 /*
121  * hubd cpr data structure used for callback before kernel threads are
122  * suspended
123  */
124 typedef struct hubd_cpr {
125 	callb_cpr_t		cpr;		/* for cpr related info */
126 	struct hubd		*statep;	/* ohci soft state struct */
127 	kmutex_t		lockp;
128 } hubd_cpr_t;
129 
130 _NOTE(DATA_READABLE_WITHOUT_LOCK(hubd_cpr_t::cpr))
131 _NOTE(DATA_READABLE_WITHOUT_LOCK(hubd_cpr_t::statep))
132 
133 
134 /*
135  * soft	state information for this hubd
136  */
137 typedef struct hubd {
138 	int			h_instance;
139 	uint_t			h_init_state;
140 	uint_t			h_dev_state;
141 	int8_t			h_bus_ctls;
142 	int8_t			h_bus_pwr;
143 	hub_power_t		*h_hubpm; /* pointer to power struct */
144 	dev_info_t		*h_dip;
145 
146 	/*
147 	 * mutex to protect softstate and hw regs
148 	 */
149 	kmutex_t		h_mutex;
150 
151 	/*
152 	 * save the usba_device pointer
153 	 */
154 	usba_device_t		*h_usba_device;
155 
156 	int			h_softstate;
157 
158 	/*
159 	 * default pipe handle
160 	 */
161 	usb_pipe_handle_t	h_default_pipe;
162 
163 	/*
164 	 * pipe handle for ep1
165 	 */
166 	usb_pipe_handle_t	h_ep1_ph;
167 	usb_ep_descr_t		h_ep1_descr;
168 	usb_pipe_policy_t	h_pipe_policy;
169 	uint_t			h_intr_pipe_state;
170 
171 	/*
172 	 * root hub descriptor
173 	 */
174 	struct usb_hub_descr	h_hub_descr;
175 
176 	/*
177 	 * hotplug handling
178 	 */
179 	uint_t			h_hotplug_thread;
180 
181 	/*
182 	 * h_children_dips is a  array for holding
183 	 * each child dip indexed by port
184 	 * h_usba_devices is the corresponding usba_device
185 	 */
186 	dev_info_t		**h_children_dips;
187 	size_t			h_cd_list_length;
188 	usba_device_t		**h_usba_devices;
189 
190 	/* change reported by hub, limited to 31 ports */
191 	usb_port_mask_t		h_port_change;
192 
193 	/* waiting for reset completion callback */
194 	usb_port_mask_t		h_port_reset_wait;
195 
196 	/* track transitions of child on each port */
197 	uint16_t		h_port_state[MAX_PORTS + 1];
198 
199 	/* track reset state of each port */
200 	boolean_t		h_reset_port[MAX_PORTS + 1];
201 
202 	/* track event registration of children */
203 	uint8_t			h_child_events[MAX_PORTS + 1];
204 
205 	kcondvar_t		h_cv_reset_port;
206 	kcondvar_t		h_cv_hotplug_dev;
207 	uint_t			h_intr_completion_reason;
208 	usb_log_handle_t	h_log_handle;	/* for logging msgs */
209 
210 	ndi_event_hdl_t		h_ndi_event_hdl;
211 	hubd_cpr_t		*h_cpr_cb;
212 
213 	/*
214 	 * Hotplug event statistics since hub was attached
215 	 */
216 	ulong_t			h_total_hotplug_success;
217 	ulong_t			h_total_hotplug_failure;
218 
219 	/* for minor node */
220 	char			*h_ancestry_str;
221 
222 	/* registration data */
223 	usb_client_dev_data_t	*h_dev_data;
224 
225 	/* for deathrow implementation */
226 	boolean_t		h_cleanup_enabled;
227 	boolean_t		h_cleanup_needed;
228 	boolean_t		h_cleanup_active;
229 
230 	/*
231 	 * for power budget support
232 	 * h_pwr_limit and h_pwr_left are expressed
233 	 * in 2mA units
234 	 */
235 	boolean_t		h_local_pwr_capable;
236 	boolean_t		h_local_pwr_on;
237 	uint16_t		h_pwr_limit; /* per port pwr limit */
238 	int16_t			h_pwr_left; /* limit on the whole hub */
239 
240 	/*
241 	 * conf file override to power budget property
242 	 * if 1, power budget is disabled
243 	 */
244 	boolean_t		h_ignore_pwr_budget;
245 } hubd_t;
246 
247 _NOTE(MUTEX_PROTECTS_DATA(hubd::h_mutex, hubd))
248 _NOTE(MUTEX_PROTECTS_DATA(hubd::h_mutex, hub_power_t))
249 _NOTE(DATA_READABLE_WITHOUT_LOCK(hubd::h_default_pipe
250 		hubd::h_usba_device
251 		hubd::h_dev_data
252 		hubd::h_ndi_event_hdl
253 		hubd::h_cpr_cb
254 		hubd::h_log_handle
255 		hubd::h_ep1_ph
256 		hubd::h_instance
257 		hubd::h_hubpm
258 		hubd::h_dip
259 		hubd::h_ignore_pwr_budget
260 ))
261 
262 _NOTE(SCHEME_PROTECTS_DATA("stable data", usb_ep_descr))
263 
264 /*
265  * hubd hotplug thread argument data structure
266  */
267 typedef struct hubd_hotplug_arg {
268 	hubd_t		*hubd;
269 
270 	/*
271 	 * flag to indicate if a hotplug thread is started
272 	 * during hubd attach time, if true, it means the
273 	 * connected devices need to be enumerated regardless
274 	 * of the connect status change bit
275 	 */
276 	boolean_t	hotplug_during_attach;
277 } hubd_hotplug_arg_t;
278 
279 /*
280  * hubd reset thread argument data structure
281  */
282 typedef struct hubd_reset_arg {
283 	hubd_t		*hubd;
284 	/* The port needs to be reset */
285 	uint16_t	reset_port;
286 } hubd_reset_arg_t;
287 
288 _NOTE(SCHEME_PROTECTS_DATA("unshared", hubd_hotplug_arg))
289 _NOTE(SCHEME_PROTECTS_DATA("unshared", hubd_reset_arg))
290 
291 #define	HUBD_UNIT(dev)		(getminor((dev)))
292 #define	HUBD_MUTEX(hubd)	(&((hubd)->h_mutex))
293 #define	HUBD_SS_ISOPEN		0x0001
294 #define	HUBD_ACK_ALL_CHANGES	PORT_CHANGE_MASK
295 
296 /* init state */
297 #define	HUBD_LOCKS_DONE		0x0001
298 #define	HUBD_HUBDI_REGISTERED	0x0002
299 #define	HUBD_MINOR_NODE_CREATED 0x0004
300 #define	HUBD_CHILDREN_CREATED	0x0008
301 #define	HUBD_EVENTS_REGISTERED	0x0020
302 
303 /*
304  * port flags : These are essentially extensions of  Port Status Field Bits
305  * as in USB 2.0 spec Table 11-21 and #defined in hubd.h file. We make use
306  * of the unused bits (5-7,13-15) here to track states of the hub's child.
307  */
308 #define	HUBD_CHILD_ATTACHING		0x0020
309 #define	HUBD_CHILD_DETACHING		0x0040
310 #define	HUBD_CHILD_PWRLVL_CHNG		0x0080
311 #define	HUBD_CHILD_RAISE_POWER		0x2000
312 #define	HUBD_CHILD_ZAP			0x4000
313 
314 /* Tracking events registered by children */
315 #define	HUBD_CHILD_EVENT_DISCONNECT	0x01
316 #define	HUBD_CHILD_EVENT_PRESUSPEND	0x02
317 
318 /* This dev state is used exclusively by hub to change port suspend/resume */
319 #define	USB_DEV_HUB_CHILD_PWRLVL	0x80
320 #define	USB_DEV_HUB_STATE_RECOVER	0x81
321 
322 /*
323  * hubd interrupt pipe management :
324  *
325  * Following are the states of the interrupt pipe
326  *
327  * IDLE:
328  *	initial state and after closing of the interrupt pipe
329  *
330  * OPENING:
331  *	Set when the pipe is being opened
332  *
333  * ACTIVE:
334  *	Set when the pipe has been opened in hubd_open_intr_pipe. This is
335  *	typically after a hub has got enumerated and initialized.
336  *
337  * CLOSING :
338  *	Set when the pipe is closed by calling hubd_close_intr_pipe(). This is
339  *	typically called on hub disconnect via hubd_cleanup.
340  */
341 #define	HUBD_INTR_PIPE_IDLE		0
342 #define	HUBD_INTR_PIPE_OPENING		1
343 #define	HUBD_INTR_PIPE_ACTIVE		2
344 #define	HUBD_INTR_PIPE_STOPPED		3
345 #define	HUBD_INTR_PIPE_CLOSING		4
346 
347 
348 /* request structure for putting dips on deathrow list */
349 typedef struct hubd_offline_req {
350 	usba_list_entry_t	or_queue; /* DO NOT MOVE! */
351 	hubd_t			*or_hubd;
352 	usb_port_t		or_port;
353 	dev_info_t		*or_dip;
354 	uint_t			or_flag;
355 } hubd_offline_req_t;
356 
357 _NOTE(SCHEME_PROTECTS_DATA("unshared", hubd_offline_req))
358 
359 
360 /*
361  * cfgadm state values
362  */
363 #define	HUBD_CFGADM_NORMAL		0	/* normal state */
364 #define	HUBD_CFGADM_DISCONNECTED	1	/* logically disconnected */
365 #define	HUBD_CFGADM_UNCONFIGURED	2	/* port is unconfigured */
366 #define	HUBD_CFGADM_EMPTY		3	/* port is empty */
367 #define	HUBD_CFGADM_STILL_REFERENCED	4	/* ndi_devi_offline failed */
368 #define	HUBD_CFGADM_CONFIGURED		5	/* port is configured */
369 
370 /*
371  * Debug printing
372  * Masks
373  */
374 #define	DPRINT_MASK_ATTA	0x00000001
375 #define	DPRINT_MASK_CBOPS	0x00000002
376 #define	DPRINT_MASK_CALLBACK	0x00000004
377 #define	DPRINT_MASK_PORT	0x00000008
378 #define	DPRINT_MASK_HUB 	0x00000010
379 #define	DPRINT_MASK_HOTPLUG	0x00000020
380 #define	DPRINT_MASK_EVENTS	0x00000040
381 #define	DPRINT_MASK_PM		0x00000080
382 #define	DPRINT_MASK_ALL 	0xFFFFFFFF
383 
384 
385 /* status length used in getting hub status */
386 #define	GET_STATUS_LENGTH	0x04		/* length of get status req */
387 
388 /* flag for hubd_start_polling */
389 #define	HUBD_ALWAYS_START_POLLING	1
390 
391 /* enumeration timeout */
392 #define	HUBDI_ENUM_TIMEOUT	1	/* 1 second */
393 
394 /* power budget unit in mA */
395 #define	USB_PWR_UNIT_LOAD	100
396 
397 /* power values in 100mA units */
398 #define	USB_HIGH_PWR_VALUE	5
399 #define	USB_LOW_PWR_VALUE	1
400 
401 /*
402  * According to section 9.6.3 of USB 2.0 spec,
403  * bMaxPower in the device configuration descriptor
404  * is expressed in 2mA units
405  */
406 #define	USB_CFG_DESCR_PWR_UNIT	2
407 
408 #ifdef	__cplusplus
409 }
410 #endif
411 
412 #endif	/* _SYS_USB_HUBDVAR_H */
413