ba289fd2ed98645e0ab2ad09de0214ef8d4284ef
[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 // HandlePnp
109 //
110 // Description: This function handles all pnp requests
111
112 virtual NTSTATUS HandlePnp(IN PDEVICE_OBJECT DeviceObject,
113 IN OUT PIRP Irp) = 0;
114
115 //-----------------------------------------------------------------------------------------
116 //
117 // HandlePower
118 //
119 // Description: This function handles all power pnp requests
120 //
121 virtual NTSTATUS HandlePower(IN PDEVICE_OBJECT DeviceObject,
122 IN OUT PIRP Irp) = 0;
123
124 //-----------------------------------------------------------------------------------------
125 //
126 // HandleDeviceControl
127 //
128 // Description: handles device io control requests
129
130 virtual NTSTATUS HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject,
131 IN OUT PIRP Irp) = 0;
132
133 };
134
135 typedef IHCDController *PHCDCONTROLLER;
136
137
138 //=========================================================================================
139 //
140 // class IUSBHardwareDevice
141 //
142 // Description: This class provides access to the usb hardware controller
143 //
144
145 struct IDMAMemoryManager;
146 struct IUSBQueue;
147
148 DECLARE_INTERFACE_(IUSBHardwareDevice, IUnknown)
149 {
150 DEFINE_ABSTRACT_UNKNOWN()
151
152 //-----------------------------------------------------------------------------------------
153 //
154 // Initialize
155 //
156 // Description: Initializes the usb device controller
157
158 virtual NTSTATUS Initialize(PDRIVER_OBJECT DriverObject,
159 PDEVICE_OBJECT FunctionalDeviceObject,
160 PDEVICE_OBJECT PhysicalDeviceObject,
161 PDEVICE_OBJECT LowerDeviceObject) = 0;
162
163 //-----------------------------------------------------------------------------------------
164 //
165 // PnpStart
166 //
167 // Description: handles pnp start request from device. It registeres the interrupt,
168 // sets up the ports and prepares the device. It then starts the controller
169
170 virtual NTSTATUS PnpStart(PCM_RESOURCE_LIST RawResources,
171 PCM_RESOURCE_LIST TranslatedResources) = 0;
172
173 //-----------------------------------------------------------------------------------------
174 //
175 // PnpStop
176 //
177 // Description: handles pnp stop request from device. It unregisteres the interrupt, releases ports and dma object.
178
179 virtual NTSTATUS PnpStop(void) = 0;
180
181 //-----------------------------------------------------------------------------------------
182 //
183 // HandlePower
184 //
185 // Description: handles power requests
186
187 virtual NTSTATUS HandlePower(PIRP Irp) = 0;
188
189 //-----------------------------------------------------------------------------------------
190 //
191 // GetDeviceDetails
192 //
193 // Description: returns the device details such as vendor id, device id, number of ports and speed
194
195 virtual NTSTATUS GetDeviceDetails(OUT OPTIONAL PULONG VendorId,
196 OUT OPTIONAL PULONG DeviceId,
197 OUT OPTIONAL PULONG NumberOfPorts,
198 OUT OPTIONAL PULONG Speed) = 0;
199
200 //-----------------------------------------------------------------------------------------
201 //
202 // GetDmaMemoryManager
203 //
204 // Description: returns interface to DMAMemoryManager
205 // Interface is reference counted, you need to call Release method when you are done with it
206 // Do not call Initialize on IDMAMemoryManager, the object is already initialized
207
208 virtual NTSTATUS GetDmaMemoryManager(OUT struct IDMAMemoryManager **OutMemoryManager) = 0;
209
210 //-----------------------------------------------------------------------------------------
211 //
212 // GetUSBQueue
213 //
214 // Description: returns interface to internal IUSBQueue
215 // Interface is reference counted, you need to call release method when you are done with it
216 // Do not call Initialize on IUSBQueue, the object is already initialized
217
218 virtual NTSTATUS GetUSBQueue(OUT struct IUSBQueue **OutUsbQueue) = 0;
219
220 //-----------------------------------------------------------------------------------------
221 //
222 // ResetController()
223 //
224 // Description: this function resets the controller
225 // Returns STATUS_SUCCESS when the controller was successfully reset
226
227 virtual NTSTATUS ResetController() = 0;
228
229 //-----------------------------------------------------------------------------------------
230 //
231 // ResetPort
232 //
233 // Description: this functions resets the port on the controller
234 //
235
236 virtual NTSTATUS ResetPort(ULONG PortNumber) = 0;
237
238 //-----------------------------------------------------------------------------------------
239 //
240 // AcquireDeviceLock
241 //
242 // Description: acquires the device lock
243
244 virtual KIRQL AcquireDeviceLock(void) = 0;
245
246 //-----------------------------------------------------------------------------------------
247 //
248 // ReleaseLock
249 //
250 // Description: releases the device lock
251
252 virtual void ReleaseDeviceLock(KIRQL OldLevel) = 0;
253 };
254
255 typedef IUSBHardwareDevice *PUSBHARDWAREDEVICE;
256
257
258 //=========================================================================================
259 //
260 // class IDMAMemoryManager
261 //
262 // Description: This class provides access to the dma buffer. It provides methods to
263 // allocate and free from the dma buffer
264 //
265
266 DECLARE_INTERFACE_(IDMAMemoryManager, IUnknown)
267 {
268 DEFINE_ABSTRACT_UNKNOWN()
269
270 //-----------------------------------------------------------------------------------------
271 //
272 // Initialize
273 //
274 // Description: initializes the memory manager
275
276 virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Device,
277 IN PKSPIN_LOCK Lock,
278 IN ULONG DmaBufferSize,
279 IN PVOID VirtualBase,
280 IN PHYSICAL_ADDRESS PhysicalAddress,
281 IN ULONG DefaultBlockSize) = 0;
282
283 //-----------------------------------------------------------------------------------------
284 //
285 // Allocate
286 //
287 // Description: allocates block of memory from allocator
288
289 virtual NTSTATUS Allocate(IN ULONG Size,
290 OUT PVOID *OutVirtualBase,
291 OUT PPHYSICAL_ADDRESS *OutPhysicalAddress) = 0;
292
293
294 //-----------------------------------------------------------------------------------------
295 //
296 // Free
297 //
298 // Description: releases memory block
299
300 virtual NTSTATUS Release(IN PVOID VirtualBase,
301 IN ULONG Size) = 0;
302
303 };
304
305 typedef IDMAMemoryManager *PDMAMEMORYMANAGER;
306
307
308 //=========================================================================================
309 //
310 // class IUSBRequest
311 //
312 // Description: This class is used to issue request to usb controller. The class is
313 // initialized using InitializeXXX methods. You also need to call SetEndpoint to define the endpoint
314 // In addition you can call SetCompletionDetails if you need to wait for the end of
315 // the request or want to complete an irp. You call AddUSBRequest to add the request to the queue.
316 // Once the request is completed the CompletionCallback is invoked. The CompletionCallback
317 // will take care of any completion details which have been set. If the request is cancelled, the
318 // CancelCallback routine is invoked.
319 //
320
321 DECLARE_INTERFACE_(IUSBRequest, IUnknown)
322 {
323 DEFINE_ABSTRACT_UNKNOWN()
324
325 //-----------------------------------------------------------------------------------------
326 //
327 // InitializeWithSetupPacket
328 //
329 // Description: initializes the request packet with an setup packet
330 // If there is a TransferBuffer, the TransferBufferLength contains the length of the buffer
331
332
333 virtual NTSTATUS InitializeWithSetupPacket(IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket,
334 IN ULONG TransferBufferLength,
335 IN PVOID TransferBuffer) = 0;
336
337 //
338 //TODO: find required parameters for different packet types
339 //
340
341
342 //-----------------------------------------------------------------------------------------
343 //
344 // SetEndPoint
345 //
346 // Description: sets the endpoint of the request.
347
348 virtual NTSTATUS SetEndPoint(PUSB_ENDPOINT_DESCRIPTOR EndPoint);
349
350 //-----------------------------------------------------------------------------------------
351 //
352 // SetCompletionDetails
353 //
354 // Description: sets up how the request should be completed
355 // If an irp is passed, then it is completed with status code of the
356 // CompletionCallback or CancelCallback
357 // If an event is passed, then the event is signaled
358
359 virtual NTSTATUS SetCompletionDetails(IN OPTIONAL PIRP Irp,
360 IN OPTIONAL PKEVENT Event) = 0;
361
362 //-----------------------------------------------------------------------------------------
363 //
364 // CompletionCallback
365 //
366 // Description: called when request has been completed. It is called when
367 // IUSBQueue completes the request
368
369 virtual VOID CompletionCallback(IN NTSTATUS NtStatusCode,
370 IN ULONG UrbStatusCode) = 0;
371
372 //-----------------------------------------------------------------------------------------
373 //
374 // CancelCallback
375 //
376 // Description: called when request is cancelled. Called by IUSBQueue
377
378 virtual VOID CancelCallback(IN NTSTATUS NtStatusCode) = 0;
379
380 };
381
382 //=========================================================================================
383 //
384 // class IUSBQueue
385 //
386 // Description: This class manages pending requests
387 //
388
389 DECLARE_INTERFACE_(IUSBQueue, IUnknown)
390 {
391 DEFINE_ABSTRACT_UNKNOWN()
392
393 //-----------------------------------------------------------------------------------------
394 //
395 // Initialize
396 //
397 // Description: initializes the object
398
399 virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Hardware,
400 IN OPTIONAL PKSPIN_LOCK Lock,
401 IN PDMAMEMORYMANAGER MemoryManager) = 0;
402
403 //-----------------------------------------------------------------------------------------
404 //
405 // GetPendingRequestCount
406 //
407 // Description: returns the number of pending requests
408
409 virtual ULONG GetPendingRequestCount() = 0;
410
411 //-----------------------------------------------------------------------------------------
412 //
413 // AddUSBRequest
414 //
415 // Description: adds an usb request to the queue.
416 // Returns status success when successful
417
418 virtual NTSTATUS AddUSBRequest(IUSBRequest * Request) = 0;
419
420 //-----------------------------------------------------------------------------------------
421 //
422 // CancelRequests()
423 //
424 // Description: cancels all requests
425
426 virtual NTSTATUS CancelRequests() = 0;
427
428 //-----------------------------------------------------------------------------------------
429 //
430 // CreateUSBRequest
431 //
432 // Description: creates an usb request
433
434 virtual NTSTATUS CreateUSBRequest(IUSBRequest **OutRequest) = 0;
435 };
436
437 //=========================================================================================
438 //
439 // class IHubController
440 //
441 // Description: This class implements a hub controller
442 //
443
444 DECLARE_INTERFACE_(IHubController, IUnknown)
445 {
446 DEFINE_ABSTRACT_UNKNOWN()
447
448 //----------------------------------------------------------------------------------------
449 //
450 // Initialize
451 //
452 // Description: Initializes the hub controller
453
454 virtual NTSTATUS Initialize(IN PHCDCONTROLLER Controller,
455 IN PUSBHARDWAREDEVICE Device,
456 IN BOOLEAN IsRootHubDevice,
457 IN ULONG DeviceAddress) = 0;
458
459 //-----------------------------------------------------------------------------------------
460 //
461 // HandlePnp
462 //
463 // Description: This function handles all pnp requests
464
465 virtual NTSTATUS HandlePnp(IN PDEVICE_OBJECT DeviceObject,
466 IN OUT PIRP Irp) = 0;
467
468 //-----------------------------------------------------------------------------------------
469 //
470 // HandlePower
471 //
472 // Description: This function handles all power pnp requests
473 //
474 virtual NTSTATUS HandlePower(IN PDEVICE_OBJECT DeviceObject,
475 IN OUT PIRP Irp) = 0;
476
477 //-----------------------------------------------------------------------------------------
478 //
479 // HandleDeviceControl
480 //
481 // Description: handles device io control requests
482
483 virtual NTSTATUS HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject,
484 IN OUT PIRP Irp) = 0;
485 };
486
487 typedef IHubController *PHUBCONTROLLER;
488
489
490 #endif