UsbBus.h revision 9920ae74af5a38672ddde0a997a7ec0960c96275 
1/** @file
2
3    Usb Bus Driver Binding and Bus IO Protocol.
4
5Copyright (c) 2004 - 2007, Intel Corporation
6All rights reserved. This program and the accompanying materials
7are licensed and made available under the terms and conditions of the BSD License
8which accompanies this distribution.  The full text of the license may be found at
9http://opensource.org/licenses/bsd-license.php
10
11THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14**/
15
16#ifndef _EFI_USB_BUS_H_
17#define _EFI_USB_BUS_H_
18
19
20#include <PiDxe.h>
21
22#include <Protocol/Usb2HostController.h>
23#include <Protocol/UsbHostController.h>
24#include <Protocol/UsbIo.h>
25#include <Protocol/DevicePath.h>
26
27#include <Library/BaseLib.h>
28#include <Library/DebugLib.h>
29#include <Library/BaseMemoryLib.h>
30#include <Library/UefiDriverEntryPoint.h>
31#include <Library/UefiBootServicesTableLib.h>
32#include <Library/UefiLib.h>
33#include <Library/DevicePathLib.h>
34#include <Library/MemoryAllocationLib.h>
35
36
37#include <IndustryStandard/Usb.h>
38
39typedef struct _USB_DEVICE     USB_DEVICE;
40typedef struct _USB_INTERFACE  USB_INTERFACE;
41typedef struct _USB_BUS        USB_BUS;
42typedef struct _USB_HUB_API    USB_HUB_API;
43
44
45#include "UsbUtility.h"
46#include "UsbDesc.h"
47#include "UsbHub.h"
48#include "UsbEnumer.h"
49
50typedef enum {
51  USB_MAX_LANG_ID           = 16,
52  USB_MAX_INTERFACE         = 16,
53  USB_MAX_DEVICES           = 128,
54
55  USB_BUS_1_MILLISECOND     = 1000,
56
57  //
58  // Roothub and hub's polling interval, set by experience,
59  // The unit of roothub is 100us, means 1s as interval, and
60  // the unit of hub is 1ms, means 64ms as interval.
61  //
62  USB_ROOTHUB_POLL_INTERVAL = 1000 * 10000U,
63  USB_HUB_POLL_INTERVAL     = 64,
64
65  //
66  // Wait for port stable to work, refers to specification
67  // [USB20-9.1.2]
68  //
69  USB_WAIT_PORT_STABLE_STALL     = 100 * USB_BUS_1_MILLISECOND,
70
71  //
72  // Wait for port statue reg change, set by experience
73  //
74  USB_WAIT_PORT_STS_CHANGE_STALL = 5 * USB_BUS_1_MILLISECOND,
75
76  //
77  // Wait for set device address, refers to specification
78  // [USB20-9.2.6.3, it says 2ms]
79  //
80  USB_SET_DEVICE_ADDRESS_STALL   = 20 * USB_BUS_1_MILLISECOND,
81
82  //
83  // Wait for retry max packet size, set by experience
84  //
85  USB_RETRY_MAX_PACK_SIZE_STALL  = 100 * USB_BUS_1_MILLISECOND,
86
87  //
88  // Wait for hub port power-on, refers to specification
89  // [USB20-11.23.2]
90  //
91  USB_SET_PORT_POWER_STALL       = 2 * USB_BUS_1_MILLISECOND,
92
93  //
94  // Wait for port reset, refers to specification
95  // [USB20-7.1.7.5, it says 10ms for hub and 50ms for
96  // root hub]
97  //
98  USB_SET_PORT_RESET_STALL       = 20 * USB_BUS_1_MILLISECOND,
99  USB_SET_ROOT_PORT_RESET_STALL  = 50 * USB_BUS_1_MILLISECOND,
100
101  //
102  // Wait for clear roothub port reset, set by experience
103  //
104  USB_CLR_ROOT_PORT_RESET_STALL  = 1 * USB_BUS_1_MILLISECOND,
105
106  //
107  // Wait for set roothub port enable, set by experience
108  //
109  USB_SET_ROOT_PORT_ENABLE_STALL = 20 * USB_BUS_1_MILLISECOND,
110
111  //
112  // Send general device request timeout, refers to
113  // specification[USB20-11.24.1]
114  //
115  USB_GENERAL_DEVICE_REQUEST_TIMEOUT = 50 * USB_BUS_1_MILLISECOND,
116
117  //
118  // Send clear feature request timeout, set by experience
119  //
120  USB_CLEAR_FEATURE_REQUEST_TIMEOUT  = 10 * USB_BUS_1_MILLISECOND
121}USB_BUS_TIMEOUT_EXPERIENCE_VALUE;
122
123//
124// Bus raises TPL to TPL_NOTIFY to serialize all its operations
125// to protect shared data structures.
126//
127#define  USB_BUS_TPL               TPL_NOTIFY
128
129#define  USB_INTERFACE_SIGNATURE   EFI_SIGNATURE_32 ('U', 'S', 'B', 'I')
130#define  USB_BUS_SIGNATURE         EFI_SIGNATURE_32 ('U', 'S', 'B', 'B')
131
132#define USB_BIT(a)                  ((UINTN)(1 << (a)))
133#define USB_BIT_IS_SET(Data, Bit)   ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
134
135#define EFI_USB_BUS_PROTOCOL_GUID \
136          {0x2B2F68CC, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75}}
137
138#define USB_INTERFACE_FROM_USBIO(a) \
139          CR(a, USB_INTERFACE, UsbIo, USB_INTERFACE_SIGNATURE)
140
141#define USB_BUS_FROM_THIS(a) \
142          CR(a, USB_BUS, BusId, USB_BUS_SIGNATURE)
143
144//
145// Used to locate USB_BUS
146//
147typedef struct _EFI_USB_BUS_PROTOCOL {
148  UINT64                    Reserved;
149} EFI_USB_BUS_PROTOCOL;
150
151
152//
153// Stands for the real USB device. Each device may
154// has several seperately working interfaces.
155//
156struct _USB_DEVICE {
157  USB_BUS                   *Bus;
158
159  //
160  // Configuration information
161  //
162  UINT8                     Speed;
163  UINT8                     Address;
164  UINT8                     MaxPacket0;
165
166  //
167  // The device's descriptors and its configuration
168  //
169  USB_DEVICE_DESC           *DevDesc;
170  USB_CONFIG_DESC           *ActiveConfig;
171
172  UINT16                    LangId [USB_MAX_LANG_ID];
173  UINT16                    TotalLangId;
174
175  UINT8                     NumOfInterface;
176  USB_INTERFACE             *Interfaces [USB_MAX_INTERFACE];
177
178  //
179  // Parent child relationship
180  //
181  EFI_USB2_HC_TRANSACTION_TRANSLATOR Translator;
182
183  UINT8                     ParentAddr;
184  USB_INTERFACE             *ParentIf;
185  UINT8                     ParentPort;       // Start at 0
186};
187
188//
189// Stands for different functions of USB device
190//
191struct _USB_INTERFACE {
192  UINTN                     Signature;
193  USB_DEVICE                *Device;
194  USB_INTERFACE_DESC        *IfDesc;
195  USB_INTERFACE_SETTING     *IfSetting;
196
197  //
198  // Handles and protocols
199  //
200  EFI_HANDLE                Handle;
201  EFI_USB_IO_PROTOCOL       UsbIo;
202  EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
203  BOOLEAN                   IsManaged;
204
205  //
206  // Hub device special data
207  //
208  BOOLEAN                   IsHub;
209  USB_HUB_API               *HubApi;
210  UINT8                     NumOfPort;
211  EFI_EVENT                 HubNotify;
212
213  //
214  // Data used only by normal hub devices
215  //
216  USB_ENDPOINT_DESC         *HubEp;
217  UINT8                     *ChangeMap;
218
219  //
220  // Data used only by root hub to hand over device to
221  // companion UHCI driver if low/full speed devices are
222  // connected to EHCI.
223  //
224  UINT8                     MaxSpeed;
225};
226
227//
228// Stands for the current USB Bus
229//
230struct _USB_BUS {
231  UINTN                     Signature;
232  EFI_USB_BUS_PROTOCOL      BusId;
233
234  //
235  // Managed USB host controller
236  //
237  EFI_HANDLE                HostHandle;
238  EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
239  EFI_USB2_HC_PROTOCOL      *Usb2Hc;
240  EFI_USB_HC_PROTOCOL       *UsbHc;
241
242  //
243  // An array of device that is on the bus. Devices[0] is
244  // for root hub. Device with address i is at Devices[i].
245  //
246  USB_DEVICE                *Devices[USB_MAX_DEVICES];
247
248  //
249  // USB Bus driver need to control the recursive connect policy of the bus, only those wanted
250  // usb child device will be recursively connected.
251  //
252  // WantedUsbIoDPList tracks the Usb child devices which user want to recursivly fully connecte,
253  // every wanted child device is stored in a item of the WantedUsbIoDPList, whose structrure is
254  // DEVICE_PATH_LIST_ITEM
255  //
256  LIST_ENTRY                WantedUsbIoDPList;
257
258};
259
260//
261// USB Hub Api
262//
263struct _USB_HUB_API{
264  USB_HUB_INIT                Init;
265  USB_HUB_GET_PORT_STATUS     GetPortStatus;
266  USB_HUB_CLEAR_PORT_CHANGE   ClearPortChange;
267  USB_HUB_SET_PORT_FEATURE    SetPortFeature;
268  USB_HUB_CLEAR_PORT_FEATURE  ClearPortFeature;
269  USB_HUB_RESET_PORT          ResetPort;
270  USB_HUB_RELEASE             Release;
271};
272
273#define USB_US_LAND_ID   0x0409
274
275#define DEVICE_PATH_LIST_ITEM_SIGNATURE     EFI_SIGNATURE_32('d','p','l','i')
276typedef struct _DEVICE_PATH_LIST_ITEM{
277  UINTN                                 Signature;
278  LIST_ENTRY                            Link;
279  EFI_DEVICE_PATH_PROTOCOL              *DevicePath;
280} DEVICE_PATH_LIST_ITEM;
281
282typedef struct {
283  USB_CLASS_DEVICE_PATH           UsbClass;
284  EFI_DEVICE_PATH_PROTOCOL        End;
285} USB_CLASS_FORMAT_DEVICE_PATH;
286
287/**
288  Free a DEVICE_PATH_LIST_ITEM list.
289
290  @param  UsbIoDPList            a DEVICE_PATH_LIST_ITEM list pointer.
291
292  @retval EFI_INVALID_PARAMETER  If parameters are invalid, return this value.
293  @retval EFI_SUCCESS            If free operation is successful, return this value.
294
295**/
296EFI_STATUS
297EFIAPI
298UsbBusFreeUsbDPList (
299  IN     LIST_ENTRY                                 *UsbIoDPList
300  );
301
302/**
303  Store a wanted usb child device info (its Usb part of device path) which is indicated by
304  RemainingDevicePath in a Usb bus which  is indicated by UsbBusId.
305
306  @param  UsbBusId               Point to EFI_USB_BUS_PROTOCOL interface.
307  @param  RemainingDevicePath    The remaining device patch.
308
309  @retval EFI_SUCCESS            Add operation is successful.
310  @retval EFI_INVALID_PARAMETER  The parameters are invalid.
311
312**/
313EFI_STATUS
314EFIAPI
315UsbBusAddWantedUsbIoDP (
316  IN EFI_USB_BUS_PROTOCOL         *UsbBusId,
317  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
318  );
319
320/**
321  Check whether a usb child device is the wanted device in a bus.
322
323  @param  Bus     The Usb bus's private data pointer.
324  @param  UsbIf   The usb child device inferface.
325
326  @retval True    If a usb child device is the wanted device in a bus.
327  @retval False   If a usb child device is *NOT* the wanted device in a bus.
328
329**/
330BOOLEAN
331EFIAPI
332UsbBusIsWantedUsbIO (
333  IN USB_BUS                 *Bus,
334  IN USB_INTERFACE           *UsbIf
335  );
336
337/**
338  Recursively connnect every wanted usb child device to ensure they all fully connected.
339  Check all the child Usb IO handles in this bus, recursively connecte if it is wanted usb child device.
340
341  @param  UsbBusId                  Point to EFI_USB_BUS_PROTOCOL interface.
342
343  @retval EFI_SUCCESS               Connect is done successfully.
344  @retval EFI_INVALID_PARAMETER     The parameter is invalid.
345
346**/
347EFI_STATUS
348EFIAPI
349UsbBusRecursivelyConnectWantedUsbIo (
350  IN EFI_USB_BUS_PROTOCOL         *UsbBusId
351  );
352
353extern EFI_USB_IO_PROTOCOL            mUsbIoProtocol;
354extern EFI_DRIVER_BINDING_PROTOCOL    mUsbBusDriverBinding;
355extern EFI_COMPONENT_NAME_PROTOCOL    mUsbBusComponentName;
356extern EFI_COMPONENT_NAME2_PROTOCOL   mUsbBusComponentName2;
357
358#endif
359