3abb71a8cb79d03139145c300c88570819f7d2a1
[reactos.git] / drivers / usb / usbehci_new / interfaces.h
1
2 #ifndef INTERFACES_HPP
3 #define INTERFACES_HPP
4
5 //---------------------------------------------------------------------------
6 //
7 // Object Hierachy
8 // --------------------------------------------------------------------
9 // | IRootHCDController |
10 // | IHCDController Intel USB Universal Host Controller - 3A37 |
11 // | IHCDController - Intel USB Universal HostController - 3A38 |
12 // | IHCDController - Intel USB Universal HostController - 3A38 |
13 // |------------------------------------------------------------------|
14 //
15 //
16 // IHCDController Intel USB Universal Host Controller - 3A37
17 // IHubController
18 // IUSBHardwareDevice
19 // IDMAMemoryManager
20 // IUSBQueue <- interacts with -> IUSBRequest
21 //
22 //
23 // Each IHCDController creates an IUSBHardwareDevice class upon initialization. The
24 // IUSBHardwardeDevice class is used to abstract usb controller specifics. The IHubController
25 // manages all attached devices and handles hub control ioctl requests.
26 //
27 // Each IUSBHardwareDevice has one IDMAMemoryManager and one IUSBQueue. The IDMAMemoryManager
28 // is used to handle dma memory allocations. The IUSBQueue manages requests which are send to the
29 // usb hardware. See IUSBRequest class for details.
30 //
31
32
33 //=========================================================================================
34 //
35 // class IRootHCDController
36 //
37 // Description: This class serves as the root host controller. The host controller mantains
38 // a list of registered controllers and provides support functions for the host controllers
39
40 struct IHCDController;
41
42 DECLARE_INTERFACE_(IRootHCDController, IUnknown)
43 {
44 DEFINE_ABSTRACT_UNKNOWN()
45
46 //-----------------------------------------------------------------------------------------
47 //
48 // Initialize
49 //
50 // Description: This function initializes the root host controller. It allocates the resources
51 // required to manage the registered controllers
52
53 virtual NTSTATUS Initialize() = 0;
54
55 //-----------------------------------------------------------------------------------------
56 //
57 // RegisterHCD
58 //
59 // Description: this function registers a host controller with the root host controller
60
61 virtual NTSTATUS RegisterHCD(struct IHCDController * Controller) = 0;
62
63 //-----------------------------------------------------------------------------------------
64 //
65 // UnregisterHCD
66 //
67 // Description: this function unregistes a host controller
68
69 virtual NTSTATUS UnregisterHCD(struct IHCDController * Controller) = 0;
70
71 //-----------------------------------------------------------------------------------------
72 //
73 // GetControllerCount
74 //
75 // Description: returns the number of host controllers registered
76
77 virtual ULONG GetControllerCount() = 0;
78
79 };
80
81 typedef IRootHCDController *PROOTHDCCONTROLLER;
82
83 //=========================================================================================
84 //
85 // class IHCDController
86 //
87 // Description: This class is used to manage a single USB host controller
88 //
89
90 DECLARE_INTERFACE_(IHCDController, IUnknown)
91 {
92 DEFINE_ABSTRACT_UNKNOWN()
93
94 //-----------------------------------------------------------------------------------------
95 //
96 // Initialize
97 //
98 // Description: This function initializes the IHCDController implementation.
99 // It creates an IUSBHardwareDevice object and initializes it. It also registeres itself with
100 // the IRootHCDController
101 //
102 virtual NTSTATUS Initialize(IN PROOTHDCCONTROLLER RootHCDController,
103 IN PDRIVER_OBJECT DriverObject,
104 IN PDEVICE_OBJECT PhysicalDeviceObject) = 0;
105
106 };
107
108 typedef IHCDController *PHCDCONTROLLER;
109
110
111 //=========================================================================================
112 //
113 // class IUSBHardwareDevice
114 //
115 // Description: This class provides access to the usb hardware controller
116 //
117
118 struct IDMAMemoryManager;
119 struct IUSBQueue;
120
121 DECLARE_INTERFACE_(IUSBHardwareDevice, IUnknown)
122 {
123 DEFINE_ABSTRACT_UNKNOWN()
124
125 //-----------------------------------------------------------------------------------------
126 //
127 // Initialize
128 //
129 // Description: Initializes the usb device controller
130
131 virtual NTSTATUS Initialize(PDRIVER_OBJECT DriverObject,
132 PDEVICE_OBJECT FunctionalDeviceObject,
133 PDEVICE_OBJECT PhysicalDeviceObject,
134 PDEVICE_OBJECT LowerDeviceObject) = 0;
135
136 //-----------------------------------------------------------------------------------------
137 //
138 // PnpStart
139 //
140 // Description: handles pnp start request from device. It registeres the interrupt,
141 // sets up the ports and prepares the device. It then starts the controller
142
143 virtual NTSTATUS PnpStart(PCM_RESOURCE_LIST RawResources,
144 PCM_RESOURCE_LIST TranslatedResources) = 0;
145
146 //-----------------------------------------------------------------------------------------
147 //
148 // PnpStop
149 //
150 // Description: handles pnp stop request from device. It unregisteres the interrupt, releases ports and dma object.
151
152 virtual NTSTATUS PnpStop(void) = 0;
153
154 //-----------------------------------------------------------------------------------------
155 //
156 // GetDeviceDetails
157 //
158 // Description: returns the device details such as vendor id, device id, number of ports and speed
159
160 virtual NTSTATUS GetDeviceDetails(OUT OPTIONAL PULONG VendorId,
161 OUT OPTIONAL PULONG DeviceId,
162 OUT OPTIONAL PULONG NumberOfPorts,
163 OUT OPTIONAL PULONG Speed) = 0;
164
165 //-----------------------------------------------------------------------------------------
166 //
167 // GetDmaMemoryManager
168 //
169 // Description: returns interface to DMAMemoryManager
170 // Interface is reference counted, you need to call Release method when you are done with it
171 // Do not call Initialize on IDMAMemoryManager, the object is already initialized
172
173 virtual NTSTATUS GetDmaMemoryManager(OUT struct IDMAMemoryManager **OutMemoryManager) = 0;
174
175 //-----------------------------------------------------------------------------------------
176 //
177 // GetUSBQueue
178 //
179 // Description: returns interface to internal IUSBQueue
180 // Interface is reference counted, you need to call release method when you are done with it
181 // Do not call Initialize on IUSBQueue, the object is already initialized
182
183 virtual NTSTATUS GetUSBQueue(OUT struct IUSBQueue **OutUsbQueue) = 0;
184
185 //-----------------------------------------------------------------------------------------
186 //
187 // ResetController()
188 //
189 // Description: this function resets the controller
190 // Returns STATUS_SUCCESS when the controller was successfully reset
191
192 virtual NTSTATUS ResetController() = 0;
193
194 //-----------------------------------------------------------------------------------------
195 //
196 // ResetPort
197 //
198 // Description: this functions resets the port on the controller
199 //
200
201 virtual NTSTATUS ResetPort(ULONG PortNumber) = 0;
202
203 //-----------------------------------------------------------------------------------------
204 //
205 // AcquireDeviceLock
206 //
207 // Description: acquires the device lock
208
209 virtual KIRQL AcquireDeviceLock(void) = 0;
210
211 //-----------------------------------------------------------------------------------------
212 //
213 // ReleaseLock
214 //
215 // Description: releases the device lock
216
217 virtual void ReleaseDeviceLock(KIRQL OldLevel) = 0;
218 };
219
220 typedef IUSBHardwareDevice *PUSBHARDWAREDEVICE;
221
222
223 //=========================================================================================
224 //
225 // class IDMAMemoryManager
226 //
227 // Description: This class provides access to the dma buffer. It provides methods to
228 // allocate and free from the dma buffer
229 //
230
231 DECLARE_INTERFACE_(IDMAMemoryManager, IUnknown)
232 {
233 DEFINE_ABSTRACT_UNKNOWN()
234
235 //-----------------------------------------------------------------------------------------
236 //
237 // Initialize
238 //
239 // Description: initializes the memory manager
240
241 virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Device,
242 IN PKSPIN_LOCK Lock,
243 IN ULONG DmaBufferSize,
244 IN PVOID VirtualBase,
245 IN PHYSICAL_ADDRESS PhysicalAddress,
246 IN ULONG DefaultBlockSize) = 0;
247
248 //-----------------------------------------------------------------------------------------
249 //
250 // Allocate
251 //
252 // Description: allocates block of memory from allocator
253
254 virtual NTSTATUS Allocate(IN ULONG Size,
255 OUT PVOID *OutVirtualBase,
256 OUT PPHYSICAL_ADDRESS *OutPhysicalAddress) = 0;
257
258
259 //-----------------------------------------------------------------------------------------
260 //
261 // Free
262 //
263 // Description: releases memory block
264
265 virtual NTSTATUS Release(IN PVOID VirtualBase,
266 IN ULONG Size) = 0;
267
268 };
269
270 typedef IDMAMemoryManager *PDMAMEMORYMANAGER;
271
272
273 //=========================================================================================
274 //
275 // class IUSBRequest
276 //
277 // Description: This class is used to issue request to usb controller. The class is
278 // initialized using InitializeXXX methods. You also need to call SetEndpoint to define the endpoint
279 // In addition you can call SetCompletionDetails if you need to wait for the end of
280 // the request or want to complete an irp. You call AddUSBRequest to add the request to the queue.
281 // Once the request is completed the CompletionCallback is invoked. The CompletionCallback
282 // will take care of any completion details which have been set. If the request is cancelled, the
283 // CancelCallback routine is invoked.
284 //
285
286 DECLARE_INTERFACE_(IUSBRequest, IUnknown)
287 {
288 DEFINE_ABSTRACT_UNKNOWN()
289
290 //-----------------------------------------------------------------------------------------
291 //
292 // InitializeWithSetupPacket
293 //
294 // Description: initializes the request packet with an setup packet
295 // If there is a TransferBuffer, the TransferBufferLength contains the length of the buffer
296
297
298 virtual NTSTATUS InitializeWithSetupPacket(IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket,
299 IN ULONG TransferBufferLength,
300 IN PVOID TransferBuffer) = 0;
301
302 //
303 //TODO: find required parameters for different packet types
304 //
305
306
307 //-----------------------------------------------------------------------------------------
308 //
309 // SetEndPoint
310 //
311 // Description: sets the endpoint of the request.
312
313 virtual NTSTATUS SetEndPoint(PUSB_ENDPOINT_DESCRIPTOR EndPoint);
314
315 //-----------------------------------------------------------------------------------------
316 //
317 // SetCompletionDetails
318 //
319 // Description: sets up how the request should be completed
320 // If an irp is passed, then it is completed with status code of the
321 // CompletionCallback or CancelCallback
322 // If an event is passed, then the event is signaled
323
324 virtual NTSTATUS SetCompletionDetails(IN OPTIONAL PIRP Irp,
325 IN OPTIONAL PKEVENT Event) = 0;
326
327 //-----------------------------------------------------------------------------------------
328 //
329 // CompletionCallback
330 //
331 // Description: called when request has been completed. It is called when
332 // IUSBQueue completes the request
333
334 virtual VOID CompletionCallback(IN NTSTATUS NtStatusCode,
335 IN ULONG UrbStatusCode) = 0;
336
337 //-----------------------------------------------------------------------------------------
338 //
339 // CancelCallback
340 //
341 // Description: called when request is cancelled. Called by IUSBQueue
342
343 virtual VOID CancelCallback(IN NTSTATUS NtStatusCode) = 0;
344
345 };
346
347 //=========================================================================================
348 //
349 // class IUSBQueue
350 //
351 // Description: This class manages pending requests
352 //
353
354 DECLARE_INTERFACE_(IUSBQueue, IUnknown)
355 {
356 DEFINE_ABSTRACT_UNKNOWN()
357
358 //-----------------------------------------------------------------------------------------
359 //
360 // Initialize
361 //
362 // Description: initializes the object
363
364 virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Hardware,
365 IN OPTIONAL PKSPIN_LOCK Lock,
366 IN PDMAMEMORYMANAGER MemoryManager) = 0;
367
368 //-----------------------------------------------------------------------------------------
369 //
370 // GetPendingRequestCount
371 //
372 // Description: returns the number of pending requests
373
374 virtual ULONG GetPendingRequestCount() = 0;
375
376 //-----------------------------------------------------------------------------------------
377 //
378 // AddUSBRequest
379 //
380 // Description: adds an usb request to the queue.
381 // Returns status success when successful
382
383 virtual NTSTATUS AddUSBRequest(IUSBRequest * Request) = 0;
384
385 //-----------------------------------------------------------------------------------------
386 //
387 // CancelRequests()
388 //
389 // Description: cancels all requests
390
391 virtual NTSTATUS CancelRequests() = 0;
392
393 //-----------------------------------------------------------------------------------------
394 //
395 // CreateUSBRequest
396 //
397 // Description: creates an usb request
398
399 virtual NTSTATUS CreateUSBRequest(IUSBRequest **OutRequest) = 0;
400 };
401
402 //=========================================================================================
403 //
404 // class IHubController
405 //
406 // Description: This class implements a hub controller
407 //
408
409 DECLARE_INTERFACE_(IHubController, IUnknown)
410 {
411 DEFINE_ABSTRACT_UNKNOWN()
412
413 //----------------------------------------------------------------------------------------
414 //
415 // Initialize
416 //
417 // Description: Initializes the hub controller
418
419 virtual NTSTATUS Initialize(IN PDRIVER_OBJECT DriverObject,
420 IN PHCDCONTROLLER Controller,
421 IN PUSBHARDWAREDEVICE Device,
422 IN BOOLEAN IsRootHubDevice,
423 IN ULONG DeviceAddress) = 0;
424
425 //----------------------------------------------------------------------------------------
426 //
427 // GetHubControllerDeviceObject
428 //
429 // Description: Returns the hub controller device object
430
431 virtual NTSTATUS GetHubControllerDeviceObject(PDEVICE_OBJECT * HubDeviceObject) = 0;
432
433 };
434
435 typedef IHubController *PHUBCONTROLLER;
436
437 //=========================================================================================
438 //
439 // class IDispatchIrp
440 //
441 // Description: This class is used to handle irp dispatch requests
442 //
443
444 DECLARE_INTERFACE_(IDispatchIrp, IUnknown)
445 {
446 DEFINE_ABSTRACT_UNKNOWN()
447
448 //-----------------------------------------------------------------------------------------
449 //
450 // HandlePnp
451 //
452 // Description: This function handles all pnp requests
453
454 virtual NTSTATUS HandlePnp(IN PDEVICE_OBJECT DeviceObject,
455 IN OUT PIRP Irp) = 0;
456
457 //-----------------------------------------------------------------------------------------
458 //
459 // HandlePower
460 //
461 // Description: This function handles all power pnp requests
462 //
463 virtual NTSTATUS HandlePower(IN PDEVICE_OBJECT DeviceObject,
464 IN OUT PIRP Irp) = 0;
465
466 //-----------------------------------------------------------------------------------------
467 //
468 // HandleDeviceControl
469 //
470 // Description: handles device io control requests
471
472 virtual NTSTATUS HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject,
473 IN OUT PIRP Irp) = 0;
474 };
475
476 typedef IDispatchIrp *PDISPATCHIRP;
477
478 #endif