1 /* |
|
2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 /** @file |
|
19 @brief USB Host SHAI header |
|
20 @version 0.2.0 |
|
21 |
|
22 This header specifies the USB host SHAI. |
|
23 |
|
24 @publishedDeviceAbstraction |
|
25 */ |
|
26 |
|
27 |
|
28 #ifndef USB_HOST_SHAI_H |
|
29 #define USB_HOST_SHAI_H |
|
30 |
|
31 // System includes |
|
32 #include <kern_priv.h> |
|
33 #include <usb/usb_common_shai.h> // Common types shared between the USB SHAIs |
|
34 |
|
35 /** |
|
36 * This macro specifies the version of the USB Host SHAI header in |
|
37 * binary coded decimal format. This allows the PSL layer to confirm a |
|
38 * certain definition is available, if needed. This can for example |
|
39 * make it possible for a new PSL to support compilation in an older |
|
40 * environment with old USB SHAI version that is missing some new |
|
41 * definitions. |
|
42 */ |
|
43 #define USB_HOST_SHAI_VERSION 0x020 |
|
44 |
|
45 // The namespace is documented in file usb_common_shai.h, so it is not |
|
46 // repeated here |
|
47 namespace UsbShai |
|
48 { |
|
49 // Forward declarations |
|
50 |
|
51 class MHostControllerIf; |
|
52 class MHostTransferCallbackIf; |
|
53 class MRootHubCallbackIf; |
|
54 class MRootHubIf; |
|
55 |
|
56 // Data types |
|
57 |
|
58 /** |
|
59 * An enumeration listing the host role electrical test modes |
|
60 * supported. These correspond to the test modes specified in |
|
61 * Section "6.4.1.1 Test Modes" of the "On-The-Go and Embedded |
|
62 * Host Supplement to the USB Revision 2.0 Specification" Revision |
|
63 * 2.0 (a.k.a. USB OTG 2.0). |
|
64 * |
|
65 * @see MHostControllerIf::EnterHostTestMode() |
|
66 */ |
|
67 enum THostTestMode |
|
68 { |
|
69 /** |
|
70 * Drive SE0 until host controller is reset. The call returns |
|
71 * immediately after enabling the test mode. |
|
72 */ |
|
73 ETestModeTestSE0NAK = 0, |
|
74 |
|
75 /** |
|
76 * Drive high-speed J until host controller is reset. The call |
|
77 * returns immediately after enabling the test mode. |
|
78 */ |
|
79 ETestModeTestJ, |
|
80 |
|
81 /** |
|
82 * Drive high-speed K until host controller is reset. The call |
|
83 * returns immediately after enabling the test mode. |
|
84 */ |
|
85 ETestModeTestK, |
|
86 |
|
87 /** |
|
88 * Send test packets until host controller is reset. The |
|
89 * format of the required test packet is specified in Section |
|
90 * "7.1.20 Test Mode Support" of the USB 2.0 specification. |
|
91 * |
|
92 * The call returns immediately after enabling the test |
|
93 * mode. |
|
94 */ |
|
95 ETestModeTestPacket, |
|
96 |
|
97 /** |
|
98 * Suspend and resume the port with 15 second delays to allow |
|
99 * the operator to adjust test tool settings. The Host |
|
100 * Controller PSL must perform the following test steps: |
|
101 * |
|
102 * 1. Allow SOFs to continue for 15 seconds. |
|
103 * |
|
104 * 2. Suspend the port under test. |
|
105 * |
|
106 * 3. Wait for 15 seconds. |
|
107 * |
|
108 * 4. Resume the port under test. |
|
109 * |
|
110 * This test mode is synchronous, i.e. the call returns after |
|
111 * the test has been completed. |
|
112 */ |
|
113 ETestModeHsHostPortSuspendResume, |
|
114 |
|
115 /** |
|
116 * Perform a single-step GetDescriptor(Device) transfer. This |
|
117 * is called after the USB Host Stack has enumerated a device |
|
118 * with VID=0x1A0A and PID=0x0107. The Host Controller PSL |
|
119 * must perform the following test steps: |
|
120 * |
|
121 * 1. Allow SOFs to continue for 15 seconds. |
|
122 * |
|
123 * 2. Send a complete GetDescriptor(Device) transfer |
|
124 * |
|
125 * This test mode is synchronous, i.e. the call returns after |
|
126 * the test has been completed. |
|
127 */ |
|
128 ETestModeSingleStepGetDeviceDescriptor, |
|
129 |
|
130 /** |
|
131 * Perform a single-step GetDescriptor(Device) transfer with a |
|
132 * delayed data phase. This is called after the USB Host Stack |
|
133 * has enumerated a device with VID=0x1A0A and PID=0x0108. The |
|
134 * Host Controller PSL must perform the following test steps: |
|
135 * |
|
136 * 1. Send the SETUP packet for GetDescriptor(Device). The |
|
137 * device ACKs the packet as usual. |
|
138 * |
|
139 * 2. Allow SOFs to continue for 15 seconds. |
|
140 * |
|
141 * 3. Send the IN token for the data phase of |
|
142 * GetDescriptor(Device). The device responds with |
|
143 * the data. |
|
144 * |
|
145 * 4. Send the acknowledgement (zero-length OUT data) in |
|
146 * response to the data. |
|
147 * |
|
148 * This test mode is synchronous, i.e. the call returns after |
|
149 * the test has been completed. |
|
150 */ |
|
151 ETestModeSingleStepGetDeviceDescriptorData |
|
152 }; |
|
153 |
|
154 |
|
155 // Class declaration |
|
156 |
|
157 /** |
|
158 * This class specifies a memory block that is used for USB |
|
159 * transfers. The memory pointers and the buffer length are filled |
|
160 * by the USB Host stack before issuing the transfer to the Host |
|
161 * Controller PSL. |
|
162 */ |
|
163 NONSHARABLE_CLASS( TUsbMemoryBlock ) |
|
164 { |
|
165 public: |
|
166 /** |
|
167 * Linear (virtual) start address of the memory buffer. This |
|
168 * address is always provided. |
|
169 */ |
|
170 TLinAddr iLinAddr; |
|
171 |
|
172 /** |
|
173 * Physical start address of the memory buffer. This address |
|
174 * is always provided, but it is the responsibility of the |
|
175 * Host Controller PSL to guarantee that the memory is |
|
176 * physically contiguous, if contiguous memory is needed. The |
|
177 * PSL can guarantee this by implementing |
|
178 * MHostControllerIf::ChunkCreate() to allocate physically |
|
179 * contiguous memory. |
|
180 * |
|
181 * @see MHostControllerIf::ChunkCreate() |
|
182 */ |
|
183 TPhysAddr iPhysAddr; |
|
184 |
|
185 /** |
|
186 * Pointer to an array of physical addresses each pointing to |
|
187 * one physical page of the memory block. This address is |
|
188 * always provided. |
|
189 * |
|
190 * The size of each page matches the size reported in |
|
191 * THostControllerProperties::iControllerPageSize by the Host |
|
192 * Controller PSL when it registered to the PIL. |
|
193 */ |
|
194 TPhysAddr* iPhysPages; |
|
195 |
|
196 /** The length of the memory buffer in bytes */ |
|
197 TUint iLength; |
|
198 }; |
|
199 |
|
200 |
|
201 /** |
|
202 * This class specifies the enumerated types for different endpoint |
|
203 * configuration items and specifies the structure of the endpoint |
|
204 * configuration. Instances of this class are used to specify the |
|
205 * endpoint information when opening a pipe. |
|
206 * |
|
207 * @see MHostControllerIf::OpenPipe() |
|
208 */ |
|
209 NONSHARABLE_CLASS( THostPipe ) |
|
210 { |
|
211 public: |
|
212 // These are flag constants that specify the values that can |
|
213 // be bitwise OR'ed to the endpoint flags field iEndpointFlags |
|
214 // to indicate some boolean parameters of the endpoint |
|
215 |
|
216 /** |
|
217 * This flag specifies whether the targeted endpoint is behind |
|
218 * a hub that is performing transaction translation. This |
|
219 * occurs when the attached device is a low/full-speed device |
|
220 * attached to a high-speed hub. |
|
221 * |
|
222 * When this flag is set, the iHubAddr and iHubPort members |
|
223 * specify the hub address and the port to which the targeted |
|
224 * device is connected, and the iEndpointFlags flag |
|
225 * KHubHasMultipleTTs specifies whether the hub has been |
|
226 * configured to use multiple transaction translators. |
|
227 */ |
|
228 static const TUint32 KHubTranslates = 0x00000001; |
|
229 |
|
230 /** |
|
231 * When the iEndpointFlags flag KHubTranslates is set, this |
|
232 * flag is set if the hub has multiple transaction |
|
233 * translators. |
|
234 */ |
|
235 static const TUint32 KHubHasMultipleTTs = 0x00000002; |
|
236 |
|
237 public: // Data |
|
238 /** |
|
239 * The type of the endpoint (control, bulk, interrupt, |
|
240 * isochronous) |
|
241 */ |
|
242 TEndpointType iType; |
|
243 |
|
244 /** Maximum packet size to be used on this endpoint */ |
|
245 TUint iMaxPacketSize; |
|
246 |
|
247 /** Flags specifying some boolean parameters of the endpoint */ |
|
248 TUint32 iEndpointFlags; |
|
249 |
|
250 /** |
|
251 * The speed (low, full, high) to use for this endpoint. This |
|
252 * may differ from the current speed of the local port if the |
|
253 * targeted device is a low-speed or full-speed device |
|
254 * connected to a high-speed hub. |
|
255 */ |
|
256 TSpeed iSpeed; |
|
257 |
|
258 /** |
|
259 * The polling interval specified as number of frames or |
|
260 * microframes, depending on the speed. This is used for |
|
261 * interrupt and isochronous endpoints only. |
|
262 */ |
|
263 TUint iPollingInterval; |
|
264 |
|
265 /** |
|
266 * The USB address of the remote device that we are |
|
267 * communicating with |
|
268 */ |
|
269 TUint8 iRemoteAddr; |
|
270 |
|
271 /** |
|
272 * The remote endpoint number that we are communicating |
|
273 * with. This is the physical endpoint number in the USB 2.0 |
|
274 * descriptor format, i.e. the most significant bit indicates |
|
275 * the direction (1 for IN, 0 for OUT), and the least |
|
276 * significant bits indicate the endpoint number. |
|
277 */ |
|
278 TUint8 iRemoteEpNum; |
|
279 |
|
280 /** |
|
281 * For cases where the attached device is a low/full-speed |
|
282 * device attached to a high-speed hub that does the necessary |
|
283 * transaction translation, this member records the address of |
|
284 * the hub doing the translation. |
|
285 */ |
|
286 TUint8 iHubAddr; |
|
287 |
|
288 /** |
|
289 * For cases where the attached device is a low/full-speed |
|
290 * device attached to a high-speed hub that does the necessary |
|
291 * transaction translation, this member records the number of |
|
292 * the port where the device is connected on the hub that does |
|
293 * the transaction translation. |
|
294 */ |
|
295 TUint8 iHubPort; |
|
296 }; |
|
297 |
|
298 |
|
299 /** |
|
300 * This class specifies the structure of the endpoint transfer |
|
301 * requests. The USB Host Stack passes the Host Controller PSL a |
|
302 * reference to an object of this class when setting up a new transfer |
|
303 * with MHostPipeIf::StartTransfer(). |
|
304 */ |
|
305 NONSHARABLE_CLASS( THostTransfer ) |
|
306 { |
|
307 public: |
|
308 // These are public constants that specify the values that can |
|
309 // be bitwise OR'ed to the request flags field iRequestFlags |
|
310 // to indicate some boolean parameters of the transfer |
|
311 |
|
312 /** |
|
313 * When set, specifies that the transfer direction is IN, |
|
314 * i.e. the host is reading from the connected device. This is |
|
315 * needed for endpoint zero, which is bi-directional and |
|
316 * cannot implicitly know the direction of the transfer. |
|
317 * |
|
318 * This bit is set or cleared by the USB Host stack before |
|
319 * issuing a new transfer. |
|
320 */ |
|
321 static const TUint32 KTransferDirIsIN = 0x00000001; |
|
322 |
|
323 /** |
|
324 * For OUT endpoint transfers, indicates whether the Host |
|
325 * Controller PSL is required to force a short packet at the |
|
326 * end of the transfer. |
|
327 * |
|
328 * When the bit is set, the Host Controller PSL must send a |
|
329 * ZLP (Zero-Length Packet) after the last packet of the |
|
330 * transfer, if and only if the last packet was a full packet, |
|
331 * i.e. had the same size as the maximum packet size for the |
|
332 * endpoint. |
|
333 * |
|
334 * This bit is set or cleared by the USB Host stack before |
|
335 * issuing a new transfer. |
|
336 */ |
|
337 static const TUint32 KOutForceShortPacket = 0x00000002; |
|
338 |
|
339 /** |
|
340 * For IN endpoint transfers, indicates whether the transfer |
|
341 * was terminated with a ZLP (Zero-Length Packet). |
|
342 * |
|
343 * This bit is set by the Host Controller PSL before |
|
344 * completing the transfer if the transfer ended due to a |
|
345 * ZLP. Otherwise the bit is cleared by the Host Controller |
|
346 * PSL. |
|
347 */ |
|
348 static const TUint32 KInZlpReceived = 0x00000004; |
|
349 |
|
350 /** |
|
351 * Enumeration specifying the packet status values to be used |
|
352 * for isochronous transfers. |
|
353 */ |
|
354 enum TIsocPacketStatus |
|
355 { |
|
356 /** No error has occurred, transfer succesful */ |
|
357 ESuccess = 0, |
|
358 |
|
359 /** |
|
360 * Data error has occurred in a data transfer, i.e. the |
|
361 * CRC did not match |
|
362 */ |
|
363 EDataError, |
|
364 |
|
365 /** Overrun has occurred */ |
|
366 EOverrun, |
|
367 |
|
368 /** Underrun has occurred */ |
|
369 EUnderrun, |
|
370 }; |
|
371 |
|
372 public: // Data |
|
373 /** |
|
374 * Pointer to the information of the pipe that this transfer |
|
375 * is being made on. This is the same information that was |
|
376 * used when opening the pipe that the transfer is being made |
|
377 * on. |
|
378 */ |
|
379 THostPipe* iPipeInfo; |
|
380 |
|
381 /** |
|
382 * A pointer to the callback interface to be used for |
|
383 * indicating the completion of the transfer. This is set by |
|
384 * the USB Host Stack before making a transfer request. |
|
385 */ |
|
386 MHostTransferCallbackIf* iTransferCbIf; |
|
387 |
|
388 /** |
|
389 * Request flags specifying some boolean parameters for the |
|
390 * transfer. |
|
391 */ |
|
392 TUint32 iRequestFlags; |
|
393 |
|
394 /** |
|
395 * Memory block specifying the memory buffer used for the data |
|
396 * transfer. This is filled by the USB Host Stack before |
|
397 * making a transfer request. |
|
398 * |
|
399 * The memory block used here will be part of a chunk |
|
400 * previously created by a call to |
|
401 * MHostControllerIf::ChunkCreate() and the block will |
|
402 * fullfill the alignment requirements reported by the call to |
|
403 * MHostControllerIf::GetSizeAndAlignment(). |
|
404 * |
|
405 * For control transfers, this specifies the buffer for the |
|
406 * data stage and has zero length and NULL pointers if the |
|
407 * transaction does not include a data stage. |
|
408 */ |
|
409 TUsbMemoryBlock iDataBuffer; |
|
410 |
|
411 /** |
|
412 * For control transfers, this memory block specifies the |
|
413 * contents of the setup packet to be sent. For other than |
|
414 * control transfers, it is not used, and it has zero length |
|
415 * and NULL pointers. |
|
416 */ |
|
417 TUsbMemoryBlock iSetupBuffer; |
|
418 |
|
419 /** |
|
420 * For isochronous transfers, this sets the number of |
|
421 * isochronous packets to send/receive. This is set by the |
|
422 * USB Host Stack before making a transfer request. |
|
423 */ |
|
424 TInt iNumIsocPackets; |
|
425 |
|
426 /** |
|
427 * The number of bytes successfully transferred during the |
|
428 * data transfer. This is set by the Host Controller PSL |
|
429 * before completing the transfer. |
|
430 */ |
|
431 TUint iTransferLength; |
|
432 |
|
433 /** |
|
434 * The status code of a completed transfer. This is set by the |
|
435 * Host Controller PSL before completing the request to the |
|
436 * transfer callback interface. |
|
437 */ |
|
438 TInt iStatus; |
|
439 |
|
440 /** |
|
441 * For isochronous transfers, a pointer to an array of |
|
442 * iNumIsoPackets entries that specify the length of each |
|
443 * packet in the transfer. For OUT transfers, the array is |
|
444 * filled by the USB Host Stack and is read by the Host |
|
445 * Controller PSL to decide the length for each packet. For IN |
|
446 * transfers, the array is filled by the Host Controller PSL |
|
447 * to record to length of each received packet. |
|
448 */ |
|
449 TUint16* iIsocPacketLengths; |
|
450 |
|
451 /** |
|
452 * For isochronous transfers, a pointer to an array of |
|
453 * iNumIsoPackets entries that specify the status of each |
|
454 * packet in the transfer. The array is filled by the Host |
|
455 * Controller PSL to record to success or failure of each |
|
456 * received packet. |
|
457 */ |
|
458 TIsocPacketStatus* iIsocPacketStatuses; |
|
459 }; |
|
460 |
|
461 |
|
462 /** |
|
463 * This class specifies the structure and contents of root hub |
|
464 * information that is filled by the adaptation to let the USB Host |
|
465 * Stack hub driver learn the capabilities of the root hub. |
|
466 * |
|
467 * @see MHostControllerIf::OpenRootHub |
|
468 */ |
|
469 NONSHARABLE_CLASS( TRootHubInfo ) |
|
470 { |
|
471 public: // Types and constants |
|
472 /** |
|
473 * A bitmask type used to indicate the static capabilities of |
|
474 * the root hub. |
|
475 */ |
|
476 typedef TUint32 TRootHubCaps; |
|
477 |
|
478 /** |
|
479 * Capability bit to indicate whether the root hub supports |
|
480 * user-visible port indications such as LEDs. |
|
481 * |
|
482 * If the root hub supports this feature, the PSL shall set |
|
483 * the corresponding bit in iCapabilities (by bitwise OR'ing |
|
484 * this value). Otherwise the PSL shall clear the |
|
485 * corresponding bit in iCapabilities. |
|
486 */ |
|
487 static const TRootHubCaps KRootHubCapPortIndication = 0x00000001; |
|
488 |
|
489 public: // Data |
|
490 /** |
|
491 * A bitmask specifying the static capabilities of this root |
|
492 * hub. The PSL fills this field by bitwise OR'ing the |
|
493 * TRootHubCaps capability bits corresponding to supported |
|
494 * features. |
|
495 */ |
|
496 TRootHubCaps iCapabilities; |
|
497 |
|
498 /** Number of ports in this root hub */ |
|
499 TUint iNumberOfPorts; |
|
500 |
|
501 /** |
|
502 * Maximum number of milliamps of current that this root hub |
|
503 * can supply to VBUS. |
|
504 */ |
|
505 TUint iMaxSuppliedVbusCurrentMA; |
|
506 |
|
507 /** |
|
508 * Time taken by this root hub between starting to power up a |
|
509 * port and power being good on that port. This is expressed |
|
510 * in units of one millisecond. |
|
511 */ |
|
512 TUint iTimePowerOnToPowerGoodMs; |
|
513 |
|
514 /** |
|
515 * The maximum speed supported by the root hub. |
|
516 */ |
|
517 TSpeed iMaxSpeed; |
|
518 |
|
519 /** Pointer to the root hub interface */ |
|
520 MRootHubIf* iRootHubIf; |
|
521 }; |
|
522 |
|
523 |
|
524 /** |
|
525 * An interface class used by the USB Host Stack to perform data |
|
526 * transfers on a USB pipe. The Host Controller PSL must implement |
|
527 * this interface and provide a pointer to a pipe-specific |
|
528 * instance when the USB Host Stack creates the pipe by calling |
|
529 * MHostControllerIf::OpenPipe(). |
|
530 * |
|
531 * The USB Host Stack will call the functions of this interface |
|
532 * from a DFC queued on the DFC queue supplied by the Host |
|
533 * Controller in THostControllerProperties::iControllerDfcQueue when the |
|
534 * Host Controller PSL registered. |
|
535 * |
|
536 * @see MHostControllerIf::OpenPipe() |
|
537 */ |
|
538 NONSHARABLE_CLASS( MHostPipeIf ) |
|
539 { |
|
540 public: |
|
541 /** |
|
542 * Close the USB pipe. This is called by the USB Host Stack |
|
543 * when the pipe is no longer used and the Host Controller PSL |
|
544 * may release any resources that were allocated for this |
|
545 * instance, including deleting the object itself. |
|
546 * |
|
547 * @param aPipeInfo Information describing the target endpoint |
|
548 * of the pipe. This is the same information passed to |
|
549 * MHostControllerIf::OpenPipe() when creating the |
|
550 * pipe. |
|
551 * |
|
552 * @post After calling the function, the USB Host stack will |
|
553 * consider the invoked instance to have been deleted and will |
|
554 * no longer call any of the functions. |
|
555 */ |
|
556 virtual void ClosePipeD( const THostPipe& aPipeInfo ) = 0; |
|
557 |
|
558 /** |
|
559 * Clear the data toggle bit of this pipe. This is used for |
|
560 * interrupt and bulk pipes when the host stack needs to |
|
561 * guarantee that the host controller will start the next |
|
562 * interrupt or bulk transfer with data toggle value zero. |
|
563 * |
|
564 * @param aPipeInfo Information describing the target endpoint |
|
565 * of the pipe. This is the same information passed to |
|
566 * MHostControllerIf::OpenPipe() when creating the |
|
567 * pipe. |
|
568 */ |
|
569 virtual void ClearDataToggle( const THostPipe& aPipeInfo ) = 0; |
|
570 |
|
571 /** |
|
572 * Start a transfer on this pipe. |
|
573 * |
|
574 * When the transfer is considered completed, the Host |
|
575 * Controller PSL must update the transfer information object |
|
576 * with the actual length and status of the transfer and then |
|
577 * complete it to the callback interface by calling |
|
578 * MHostTransferCallbackIf::CompleteTransfer(). The pointer to |
|
579 * the callback interface is provided in the member |
|
580 * THostTransfer::iTransferCbIf of the supplied aTransferInfo. |
|
581 * |
|
582 * The following rules shall be used by the Host Controller |
|
583 * PSL to assess the completeness of a transfer: |
|
584 * |
|
585 * 1. A read or write transfer on a control pipe is completed |
|
586 * when all the stages (two or three) of the control transfer |
|
587 * have been completed successfully, or when an error |
|
588 * occurs. It is the responsibility of the upper layers to |
|
589 * guarantee that there is sufficient buffer space for a read |
|
590 * request, so the buffer should not run out. |
|
591 * |
|
592 * 2. A read or write transfer on an isochronous pipe is |
|
593 * completed when the number of isochronous packets specified |
|
594 * in the member THostTransfer::iNumIsocPackets of the |
|
595 * supplied aTransferInfo have been sent or received |
|
596 * successfully, or if a fatal error occurs. It is the |
|
597 * responsibility of the upper layers to guarantee that there |
|
598 * is sufficient buffer space for a read request, so the |
|
599 * buffer should not run out. |
|
600 * |
|
601 * 3. A read transfer on a bulk or interrupt pipe is completed |
|
602 * when the buffer space is exhausted, a short packet (a |
|
603 * packet smaller than the maximum packet size of the pipe) is |
|
604 * received, or an error occurs. |
|
605 * |
|
606 * 4. A write transfer on a bulk or interrupt pipe is |
|
607 * completed when the requested buffer has been fully sent, or |
|
608 * an error occurs. |
|
609 * |
|
610 * @param aTransferInfo Information specifying the transfer to perform |
|
611 * |
|
612 * @return KErrNone if the transfer was started successfully, |
|
613 * otherwise a system-wide error code |
|
614 */ |
|
615 virtual TInt StartTransfer( THostTransfer& aTransferInfo ) = 0; |
|
616 |
|
617 /** |
|
618 * Cancel a transfer that was previously started with |
|
619 * StartTransfer(). The Host Controller PSL must flush any |
|
620 * pending data (either received or about to be sent) and |
|
621 * discard the transfer. The PSL must not attempt to complete |
|
622 * the canceled transfer by calling |
|
623 * MHostTransferCallbackIf::CompleteTransfer(). |
|
624 * |
|
625 * @param aTransferInfo Information specifying the transfer to |
|
626 * cancel. This is the same information passed to |
|
627 * StartTransfer() when the transfer as started. |
|
628 */ |
|
629 virtual void CancelTransfer( THostTransfer& aTransferInfo ) = 0; |
|
630 }; |
|
631 |
|
632 |
|
633 /** |
|
634 * An interface class used by the USB Host Stack hub driver to |
|
635 * operate on the root hub ports. The Host Controller PSL must |
|
636 * implement this interface and provide a pointer when the USB |
|
637 * Host Stack opens the root hub by calling |
|
638 * MHostControllerIf::OpenRootHub(). |
|
639 * |
|
640 * The USB Host Stack will call the functions of this interface |
|
641 * from a DFC queued on the DFC queue supplied by the Host |
|
642 * Controller in THostControllerProperties::iControllerDfcQueue |
|
643 * when the Host Controller PSL registered. |
|
644 * |
|
645 * @see MHostControllerIf::OpenRootHub() |
|
646 */ |
|
647 NONSHARABLE_CLASS( MRootHubIf ) |
|
648 { |
|
649 public: |
|
650 /** |
|
651 * Close the connection to the root hub. This is called by the |
|
652 * USB Host Stack when the Host Controller is about to be |
|
653 * deleted and the root hub is no longer used. The Host |
|
654 * Controller PSL may release any resources that were |
|
655 * allocated for this instance, including deleting the object |
|
656 * itself. |
|
657 * |
|
658 * @post After calling the function, the USB Host stack will |
|
659 * consider the invoked instance to have been deleted and will |
|
660 * no longer call any of the functions. |
|
661 */ |
|
662 virtual void CloseRootHubD() = 0; |
|
663 |
|
664 /** |
|
665 * Enable the power supply, i.e. raise VBUS, on the specified |
|
666 * root hub port. |
|
667 * |
|
668 * If there are problems raising VBUS, the Host Controller PSL |
|
669 * must report a VBUS error by notifying the root hub callback |
|
670 * interface MRootHubCallbackIf of an over-current condition |
|
671 * on the port. |
|
672 * |
|
673 * @param aPort The number of the root hub port to operate |
|
674 * on. For a root hub with N ports, the port numbers are in |
|
675 * range [1..N]. |
|
676 * |
|
677 * @see MRootHubCallbackIf::OverCurrentDetected() |
|
678 */ |
|
679 virtual void PowerOnPort( TUint aPort ) = 0; |
|
680 |
|
681 /** |
|
682 * Stop session (A-device only). |
|
683 * |
|
684 * @param aPort The number of the root hub port to operate |
|
685 * on. For a root hub with N ports, the port numbers are in |
|
686 * range [1..N]. |
|
687 */ |
|
688 virtual void PowerOffPort( TUint aPort ) = 0; |
|
689 |
|
690 /** |
|
691 * Reset the specified root hub port. The total reset length |
|
692 * has to be at least 50 milliseconds and the reset signalling |
|
693 * must follow the requirements specified in USB 2.0 |
|
694 * Specification Section 7.1.7.5 Reset Signaling. |
|
695 * |
|
696 * This function is synchronous and should return when the |
|
697 * reset signalling on the port has completed. |
|
698 * |
|
699 * @param aPort The number of the root hub port to operate |
|
700 * on. For a root hub with N ports, the port numbers are in |
|
701 * range [1..N]. |
|
702 */ |
|
703 virtual void ResetPort( TUint aPort ) = 0; |
|
704 |
|
705 /** |
|
706 * Place the specified root hub port to the USB suspend state |
|
707 * where it does not send SOF packets to the connected device. |
|
708 * |
|
709 * When all ports of the root hub have been suspended, the USB |
|
710 * Host Stack will suspend the entire host controller by |
|
711 * calling MHostControllerIf::SuspendController(). |
|
712 * |
|
713 * When the root hub only has one port and SOFs cannot be |
|
714 * gated on the port without suspending the whole controller, |
|
715 * the Host Controller PSL should ignore the port-specific |
|
716 * suspend and resume calls and instead suspend/resume the |
|
717 * controller based on the controller-specific suspend and |
|
718 * resume calls in MHostControllerIf. |
|
719 * |
|
720 * @param aPort The number of the root hub port to operate |
|
721 * on. For a root hub with N ports, the port numbers are in |
|
722 * range [1..N]. |
|
723 */ |
|
724 virtual void SuspendPort( TUint aPort ) = 0; |
|
725 |
|
726 /** |
|
727 * Resume the specified root hub port from the USB suspend |
|
728 * state by driving the resume signalling on the port. The |
|
729 * signalling must last at least 20 milliseconds and follow |
|
730 * the requirements specified in USB 2.0 Specification Section |
|
731 * 7.1.7.7 Resume Signaling. After the resume signalling has |
|
732 * completed, the port must allow SOFs to be sent to the |
|
733 * connected device again. |
|
734 * |
|
735 * Before resuming the first port of a completely suspended |
|
736 * controller, the USB Host Stack will first resume the entire |
|
737 * host controller by calling |
|
738 * MHostControllerIf::ResumeController(). |
|
739 * |
|
740 * When the root hub only has one port and SOFs cannot be |
|
741 * gated on the port without suspending the whole controller, |
|
742 * the Host Controller PSL should ignore the port-specific |
|
743 * suspend and resume calls and instead suspend/resume the |
|
744 * controller based on the controller-specific suspend and |
|
745 * resume calls in MHostControllerIf. |
|
746 * |
|
747 * @param aPort The number of the root hub port to operate |
|
748 * on. For a root hub with N ports, the port numbers are in |
|
749 * range [1..N]. |
|
750 */ |
|
751 virtual void ResumePort( TUint aPort ) = 0; |
|
752 |
|
753 /** |
|
754 * Query whether a device (a hub or a function) is currently |
|
755 * connected to the specified root hub port, and what speed it |
|
756 * is. |
|
757 * |
|
758 * @param aPort The number of the root hub port to check for a |
|
759 * connected device on. For a root hub with N ports, the port |
|
760 * numbers are in range [1..N]. |
|
761 * |
|
762 * @param aSpeed Variable to fill with the speed, if connected |
|
763 * |
|
764 * @return ETrue if a device is currently connected and aSpeed |
|
765 * has been set to the speed of the connected device. EFalse |
|
766 * otherwise. |
|
767 */ |
|
768 virtual TBool IsDeviceConnected( TUint aPort, |
|
769 TSpeed& aSpeed ) = 0; |
|
770 }; |
|
771 |
|
772 |
|
773 /** |
|
774 * An interface class that needs to be implemented by each Host |
|
775 * Controller PSL that registers to the USB stack. |
|
776 * |
|
777 * This interface is used by the USB Host Stack to do controller level |
|
778 * operations like suspending and resuming the host controller. It is |
|
779 * also used to open the root hub interface upon creating the SHAI |
|
780 * Host Controller, and to open USB pipes to connected devices. |
|
781 * |
|
782 * The USB Host Stack will call the functions of this interface |
|
783 * from a DFC queued on the DFC queue supplied by the Host |
|
784 * Controller in THostControllerProperties::iControllerDfcQueue when the |
|
785 * Host Controller PSL registered. |
|
786 */ |
|
787 NONSHARABLE_CLASS( MHostControllerIf ) |
|
788 { |
|
789 public: |
|
790 /** |
|
791 * Open a pipe to an endpoint on a remote USB peripheral. |
|
792 * |
|
793 * This function is called by the USB host stack when it wants |
|
794 * to communicate with a certain endpoint on a discovered USB |
|
795 * peripheral. The opened pipe is then used to read or write |
|
796 * from/to the peripheral until the pipe is later closed by |
|
797 * MHostPipeIf::ClosePipeD(). |
|
798 * |
|
799 * @param aPipeInfo Information describing the target endpoint |
|
800 * that the USB host stack wants to create a pipe to. The |
|
801 * ownership of the info object remains with the USB host |
|
802 * stack and the Host Controller PSL must not refer to data |
|
803 * inside this after the function has returned. All |
|
804 * MHostPipeIf functions that operate on the pipe will be |
|
805 * passed the same pipe information so that the Host |
|
806 * Controller PSL does not necessarily need to take a copy. |
|
807 * |
|
808 * @param aPipe Upon success, set by the Host Controller PSL |
|
809 * to point to an instance that implements the SHAI pipe |
|
810 * interface for the opened pipe. This interface will then be |
|
811 * used by the USB Host Stack to perform transfers until the |
|
812 * pipe is eventually closed by the USB Host Stack calling |
|
813 * MHostPipeIf::ClosePipeD(). |
|
814 * |
|
815 * @return KErrNone if successful, otherwise a system error code |
|
816 */ |
|
817 virtual TInt OpenPipe( const THostPipe& aPipeInfo, |
|
818 MHostPipeIf*& aPipe ) = 0; |
|
819 |
|
820 /** |
|
821 * Open the root hub for the Host Controller. |
|
822 * |
|
823 * This is called by the USB Host Stack after creating the |
|
824 * Host Controller PSL to learn the capabilities of the |
|
825 * respective root hub and to establish the communication |
|
826 * between the hub driver in the USB Host Stack and the root |
|
827 * hub ports controlled by the Host Controller PSL. |
|
828 * |
|
829 * @param aRootHubInfo Reference to a root hub information |
|
830 * object to be filled by the adaptation. |
|
831 * |
|
832 * @param aRootHubCbIf Reference to the callback interface of |
|
833 * the root hub driver in the USB stack. The root hub |
|
834 * implementation of the Host Controller PSL shall use this |
|
835 * interface to report events of this root hub. |
|
836 * |
|
837 * @return KErrNone if successful, otherwise a system error code |
|
838 */ |
|
839 virtual TInt OpenRootHub( TRootHubInfo& aRootHubInfo, |
|
840 MRootHubCallbackIf& aRootHubCbIf ) = 0; |
|
841 |
|
842 /** |
|
843 * Start and enable the host controller. This is called prior |
|
844 * to powering up any port of the root hub to allow to Host |
|
845 * Controller PSL to perform any preparation that may be |
|
846 * necessary to activate the controller. This may include |
|
847 * actions such as enabling clocks or power to the host |
|
848 * controller HW. |
|
849 * |
|
850 * This function is also used in an OTG environment when the |
|
851 * host stack becomes enabled and the controller needs to be |
|
852 * started and enabled for host use. If the HW platform shares |
|
853 * resources such as clocks and power between the host and |
|
854 * peripheral HW, it is probably easiest for the PSL to handle |
|
855 * the role switch based on the |
|
856 * MOtgControllerIf::SetControllerRole() call to the OTG |
|
857 * Controller interface. |
|
858 * |
|
859 * @return KErrNone if the host controller was successfully started, |
|
860 * otherwise a system-wide error code. |
|
861 * |
|
862 * @see usb_otg_shai.h, MOtgControllerIf::SetControllerRole() |
|
863 */ |
|
864 virtual TInt StartHostController() = 0; |
|
865 |
|
866 /** |
|
867 * Disable and stop the host controller. This is called after |
|
868 * powering down all ports of the root hub to allow to Host |
|
869 * Controller PSL to release any HW resources needed by the |
|
870 * controller. This may include actions such as disabling |
|
871 * clocks or power to the host controller HW. |
|
872 * |
|
873 * This function is also used in an OTG environment when the |
|
874 * host stack becomes disabled and the host HW resources can |
|
875 * be released. If the HW platform shares resources such as |
|
876 * clocks and power between the host and peripheral HW, it is |
|
877 * probably easiest for the PSL to handle the role switch |
|
878 * based on the MOtgControllerIf::SetControllerRole() call to |
|
879 * the OTG Controller interface. |
|
880 * |
|
881 * @return KErrNone if the host controller was successfully started, |
|
882 * otherwise a system-wide error code. |
|
883 * |
|
884 * @see usb_otg_shai.h, MOtgControllerIf::SetControllerRole() |
|
885 */ |
|
886 virtual TInt StopHostController() = 0; |
|
887 |
|
888 /** |
|
889 * Place the host controller to the USB suspend state where it |
|
890 * does not send SOF packets. |
|
891 */ |
|
892 virtual void SuspendController() = 0; |
|
893 |
|
894 /** |
|
895 * Resume the host controller from the USB suspend state by |
|
896 * driving the resume signalling towards the root hub. The |
|
897 * signalling must last at least 20 milliseconds and follow |
|
898 * the requirements specified in USB 2.0 Specification Section |
|
899 * 7.1.7.7 Resume Signaling. After the resume signalling has |
|
900 * completed, the controller must allow SOFs to be sent to the |
|
901 * connected device again. |
|
902 */ |
|
903 virtual void ResumeController() = 0; |
|
904 |
|
905 /** |
|
906 * Force the controller into a specific high-speed host test |
|
907 * mode. This function needs to be implemented only by Host |
|
908 * Controller PSLs for high-speed capable controllers. The |
|
909 * function will only be called when the controller is |
|
910 * operating in high-speed mode and a special test device has |
|
911 * been enumerated. |
|
912 * |
|
913 * When called, the Host Controller PSL shall synchronously |
|
914 * run the selected test as specified for each tests in the |
|
915 * documentation of THostTestMode. |
|
916 * |
|
917 * @param aTestMode Specifies the test mode to enter |
|
918 * |
|
919 * @param aDefaultPipe Information of the default pipe (the |
|
920 * control pipe to endpoint zero) of the connected test |
|
921 * device. |
|
922 * |
|
923 * @return KErrNone if the specified test mode was entered |
|
924 * successfully, otherwise a system-wide error |
|
925 */ |
|
926 virtual TInt EnterHostTestMode( THostTestMode aTestMode, |
|
927 const THostPipe& aDefaultPipe ) = 0; |
|
928 |
|
929 /** |
|
930 * Get the size and alignment requirements for the Host |
|
931 * Controller. The reference parameters are both input and |
|
932 * output. Upon input, they describe the values requested by |
|
933 * the client, but they may be increased by this function if |
|
934 * the Host Controller requires additional memory or has some |
|
935 * alignment requirements. |
|
936 * |
|
937 * @param aType The type of the endpoint that the memory will |
|
938 * be used for. |
|
939 * |
|
940 * @param aAlignment Output for required alignment in bytes |
|
941 * |
|
942 * @param aSize Input/output for buffer size (may be increased |
|
943 * in this function) |
|
944 * |
|
945 * @param aMaxPackets Input/output for maximum number of |
|
946 * packets in the transfer (may be increased in this function) |
|
947 * |
|
948 * @return KErrNone if successful, otherwise a system-wide |
|
949 * error code |
|
950 */ |
|
951 virtual TInt GetSizeAndAlignment( TEndpointType aType, |
|
952 TUint& aAlignment, |
|
953 TInt& aSize, |
|
954 TInt& aMaxPackets ) = 0; |
|
955 |
|
956 /** |
|
957 * Creates a shared chunk and commits memory to it. The memory |
|
958 * allocated with this function will later be used when making |
|
959 * data transfers with this Host Controller (see |
|
960 * THostTransfer::iDataBuffer). |
|
961 * |
|
962 * The adaptation shall create a chunk by calling |
|
963 * Kern::ChunkCreate(), and then commit memory to it with one |
|
964 * of the Commit functions Kern::ChunkCommit(), |
|
965 * Kern::ChunkCommitContiguous(), and Kern::ChunkCommitPhysical(). |
|
966 * |
|
967 * This task is delegated to the adaptation so that it can |
|
968 * allocate the correct type of memory. For example, if the |
|
969 * Host Controller requires the memory to be physically |
|
970 * contiguous, the implementation of this function must commit |
|
971 * contiguous memory to the chunk. |
|
972 * |
|
973 * @param aChunk Output handle to the chunk that was created. |
|
974 * The adaptation must pass this value as the aChunk argument |
|
975 * to the Kern::ChunkCreate() call. |
|
976 * |
|
977 * @param aOffset The offset (in bytes) from start of chunk, |
|
978 * which indicates the start of the memory region to be |
|
979 * committed. This will be a multiple of the MMU page |
|
980 * size. The adaptation must pass this value as the aOffset |
|
981 * argument to the used Commit call. |
|
982 * |
|
983 * @param aSize Number of bytes to commit. This will be a |
|
984 * multiple of the MMU page size. The adaptation must pass |
|
985 * this value as the aSize argument to the used Commit call. |
|
986 * |
|
987 * @param aInfo At input, specifies the chunk properties |
|
988 * requested by the upper layers. The adaptation is allowed |
|
989 * to change the attributes in aInfo.iMapAttr to match the |
|
990 * requirements of the Host Controller. The adaptation must |
|
991 * pass this value as the aInfo argument to the |
|
992 * Kern::ChunkCreate() call. If the adaptation commits |
|
993 * cached memory, it is the responsibility of the adaptation |
|
994 * to deal with cache synchronization when making data |
|
995 * transfers. If the adaptation needs special cleanup when |
|
996 * the chunk is deleted, the adaptation can set a cleanup |
|
997 * DFC pointer in aInfo.iDestroyedDfc. |
|
998 * |
|
999 * @param aPhysicalAddress On success, will be set to the |
|
1000 * physical address of the chunk as referenced by the HC |
|
1001 * |
|
1002 * @return KErrNone if successful, otherwise a system-wide |
|
1003 * error code |
|
1004 * |
|
1005 * @see System documentation for Kern::ChunkCreate(), |
|
1006 * Kern::ChunkCommit(), Kern::ChunkCommitContiguous(), and |
|
1007 * Kern::ChunkCommitPhysical() |
|
1008 */ |
|
1009 virtual TInt ChunkCreate( DChunk*& aChunk, |
|
1010 TUint aOffset, |
|
1011 TUint aSize, |
|
1012 TChunkCreateInfo& aInfo, |
|
1013 TPhysAddr& aPhysicalAddress ) = 0; |
|
1014 |
|
1015 /** |
|
1016 * Maps virtual to physical addresses. If the memory addresses |
|
1017 * used by the host controller are different to the ones of |
|
1018 * the main memory bus (e.g. due to memory mapping or use of |
|
1019 * different address spaces), this method is used to translate |
|
1020 * from kernel physical addresses to host controller physical |
|
1021 * addresses. |
|
1022 * |
|
1023 * @param aPhysicalAddressList On entering, the list of |
|
1024 * physical addresses as used kernel-side, on successful |
|
1025 * return it contains the list of physical addresses as |
|
1026 * referenced by the HC |
|
1027 * |
|
1028 * @param aPhysicalAddressListSize Number of elements in |
|
1029 * aPhysicalAddressList |
|
1030 * |
|
1031 * @return KErrNone if successful, otherwise a system-wide |
|
1032 * error code |
|
1033 */ |
|
1034 virtual TInt MapPhysicalAddresses( TPhysAddr*& aPhysicalAddressList, |
|
1035 TInt aPhysicalAddressListSize ) = 0; |
|
1036 }; |
|
1037 |
|
1038 |
|
1039 /** |
|
1040 * An interface class implemented by the USB stack to allow the |
|
1041 * host controller to report events to the root hub. This includes |
|
1042 * notifications of a device being connected or disconnected on a |
|
1043 * port, and other port conditions such as seeing a remote wakeup |
|
1044 * signalling, an error on the port (such as babble from a |
|
1045 * peripheral), or VBUS over-current. |
|
1046 * |
|
1047 * It is required that the Host Controller PSL calls these |
|
1048 * functions in the context of the DFC queue supplied by the Host |
|
1049 * Controller PSL in |
|
1050 * THostControllerProperties::iControllerDfcQueue when the Host |
|
1051 * Controller PSL registered. |
|
1052 */ |
|
1053 NONSHARABLE_CLASS( MRootHubCallbackIf ) |
|
1054 { |
|
1055 public: |
|
1056 /** |
|
1057 * A constant to specify an unknown port. In those port |
|
1058 * notifications where this is explicitly specified to be OK, |
|
1059 * this value is allowed to be used as the port number where |
|
1060 * the real port number is unknown. |
|
1061 */ |
|
1062 static const TUint KPortUnknown = 0; |
|
1063 |
|
1064 /** |
|
1065 * Informs the root hub that a device (a hub or function) has |
|
1066 * been connected to the specified root hub port. |
|
1067 * |
|
1068 * The Host Controller PSL uses this function to inform device |
|
1069 * connection also during HNP role switch when the remote |
|
1070 * device connects in peripheral role. |
|
1071 * |
|
1072 * @param aPort The number of the root hub port that the event |
|
1073 * occurred on. For a root hub with N ports, the port numbers |
|
1074 * are in range [1..N]. |
|
1075 */ |
|
1076 virtual void DeviceConnected( TUint aPort ) = 0; |
|
1077 |
|
1078 /** |
|
1079 * Informs the root hub that a device (a hub or function) has |
|
1080 * been disconnected from the specified root hub port. |
|
1081 * |
|
1082 * The Host Controller PSL uses this function to inform device |
|
1083 * disconnection also during HNP role switch when the remote |
|
1084 * peripheral disconnects to start the role switch. |
|
1085 * |
|
1086 * The Host Controller PSL must report device disconnection by |
|
1087 * calling this function even if the port is currently |
|
1088 * suspended. A disconnection that is part of an HNP role |
|
1089 * switch will always occur in suspended state, and even a |
|
1090 * normal peripheral may be physically disconnected at any |
|
1091 * time. |
|
1092 * |
|
1093 * @param aPort The number of the root hub port that the event |
|
1094 * occurred on. For a root hub with N ports, the port numbers |
|
1095 * are in range [1..N]. |
|
1096 */ |
|
1097 virtual void DeviceDisconnected( TUint aPort ) = 0; |
|
1098 |
|
1099 /** |
|
1100 * Informs the root hub that a device connected to the |
|
1101 * specified root hub port has requested remote wakeup. |
|
1102 * |
|
1103 * @param aPort The number of the root hub port that the event |
|
1104 * occurred on. For a root hub with N ports, the port numbers |
|
1105 * are in range [1..N]. |
|
1106 */ |
|
1107 virtual void RemoteWakeupRequested( TUint aPort ) = 0; |
|
1108 |
|
1109 /** |
|
1110 * Informs the root hub that a port error (such as babble) has |
|
1111 * been detected on the specified root hub port. The |
|
1112 * adaptation is expected to disable the port that has caused |
|
1113 * the error condition. |
|
1114 * |
|
1115 * @param aPort The number of the root hub port that the event |
|
1116 * occurred on. For a root hub with N ports, the port numbers |
|
1117 * are in range [1..N]. |
|
1118 */ |
|
1119 virtual void PortErrorDetected( TUint aPort ) = 0; |
|
1120 |
|
1121 /** |
|
1122 * Informs the root hub that an over-current condition has |
|
1123 * been detected on the specified port. |
|
1124 * |
|
1125 * It may not always be possible to see which port out of |
|
1126 * several caused the overcurrent. In this case the Host |
|
1127 * Controller PSL may use the port number |
|
1128 * MRootHubCallbackIf::KPortUnknown. |
|
1129 * |
|
1130 * @param aPort The number of the root hub port that the event |
|
1131 * occurred on, if known. For a root hub with N ports, the |
|
1132 * port numbers are in range [1..N]. If the exact port is |
|
1133 * not known, the Host Controller PSL root hub may report |
|
1134 * the port number MRootHubCallbackIf::KPortUnknown. |
|
1135 */ |
|
1136 virtual void OverCurrentDetected( TUint aPort ) = 0; |
|
1137 }; |
|
1138 |
|
1139 |
|
1140 /** |
|
1141 * An interface class implemented by the USB Host Stack to allow the |
|
1142 * host controller to complete transfers to the USB Host Stack. |
|
1143 * |
|
1144 * It is required that the Host Controller PSL calls these |
|
1145 * functions in the context of the DFC queue supplied by the Host |
|
1146 * Controller PSL in THostControllerProperties::iControllerDfcQueue when |
|
1147 * the Host Controller PSL registered. |
|
1148 */ |
|
1149 NONSHARABLE_CLASS( MHostTransferCallbackIf ) |
|
1150 { |
|
1151 public: |
|
1152 /** |
|
1153 * Complete a transfer request that had been set up with |
|
1154 * MHostPipeIf::StartTransfer(). |
|
1155 * |
|
1156 * @param aTransferInfo The transfer information that |
|
1157 * identifies the transfer that has completed |
|
1158 */ |
|
1159 virtual void CompleteTransfer( const THostTransfer& aTransferInfo ) = 0; |
|
1160 }; |
|
1161 |
|
1162 |
|
1163 /** |
|
1164 * This class specifies the static information provided by a Host |
|
1165 * Controller PSL when registering to the USB Host stack. |
|
1166 * |
|
1167 * The PSL should prepare for the possibility that members may be |
|
1168 * added to the end of this class in later SHAI versions if new |
|
1169 * information is needed to support new features. The PSL should |
|
1170 * not use this class as a direct member in an object that is not |
|
1171 * allowed to grow in size due to binary compatibility reasons. |
|
1172 * |
|
1173 * @see UsbHostPil::RegisterHostController() |
|
1174 */ |
|
1175 NONSHARABLE_CLASS( THostControllerProperties ) |
|
1176 { |
|
1177 public: // Types and constants |
|
1178 /** |
|
1179 * A bitmask type used to indicate the static capabilities of |
|
1180 * the Host Controller. |
|
1181 */ |
|
1182 typedef TUint32 THostCaps; |
|
1183 |
|
1184 public: |
|
1185 /** |
|
1186 * Inline constructor for the Host Controller properties |
|
1187 * object. This is inline rather than an exported function to |
|
1188 * prevent a binary break in a case where an older PSL binary |
|
1189 * might provide the constructor a smaller object due to the |
|
1190 * PSL being compiled against an older version of the SHAI |
|
1191 * header. When it's inline, the function is always in sync |
|
1192 * with the object size. |
|
1193 * |
|
1194 * We slightly violate the coding conventions which say that |
|
1195 * inline functions should be in their own file. We don't want |
|
1196 * to double the number of USB SHAI headers just for sake of a |
|
1197 * trivial constructor. |
|
1198 */ |
|
1199 inline THostControllerProperties() : |
|
1200 iCapabilities(0), |
|
1201 iControllerDfcQueue(NULL), |
|
1202 iControllerPageSize(0) |
|
1203 { |
|
1204 }; |
|
1205 |
|
1206 public: // Data |
|
1207 /** |
|
1208 * A bitmask specifying the static capabilities of this Host |
|
1209 * Controller. No capabilities are specified at the moment and |
|
1210 * the PSL shall fill this field with a zero value. |
|
1211 * |
|
1212 * The field is added for sake of future proofing the binary |
|
1213 * compatibility of the Host SHAI. By having a field reserved |
|
1214 * for capability bits, we can later specify bits to indicate |
|
1215 * added virtual functions or extension to this controller |
|
1216 * properties structure. The PIL layer can then at runtime |
|
1217 * confirm the existence of the new functions or fields and |
|
1218 * safely support an older binary, if we choose to. |
|
1219 */ |
|
1220 THostCaps iCapabilities; |
|
1221 |
|
1222 /** |
|
1223 * Pointer to a DFC queue that will be used for DFCs of this |
|
1224 * controller. |
|
1225 * |
|
1226 * A stand-alone (one not associated with an OTG-port) Host |
|
1227 * Controller PSL must supply a pointer to a dedicated DFC |
|
1228 * queue that has been created for this controller. Both the |
|
1229 * PSL itself and the PIL layer must queue their DFCs for this |
|
1230 * controller in this DFC queue to ensure the code is running |
|
1231 * in the same context. |
|
1232 * |
|
1233 * A Host Controller PSL that is part of an OTG port will be |
|
1234 * registered by the OTG PSL. In this case, the DFC queue |
|
1235 * supplied here must be the same DFC queue as the one |
|
1236 * supplied in the properties of the OTG Controller. |
|
1237 */ |
|
1238 TDfcQue* iControllerDfcQueue; |
|
1239 |
|
1240 /** |
|
1241 * The page size used by this Host Controller. The host stack |
|
1242 * will fill scatter-gather lists with pages of this size. If |
|
1243 * the Host Controller does not have specific page |
|
1244 * requirements itself, the registering Host Controller PSL |
|
1245 * must supply here the CPU MMU page size that can be obtained |
|
1246 * by the call Kern::RoundToPageSize(1). |
|
1247 */ |
|
1248 TInt iControllerPageSize; |
|
1249 }; |
|
1250 |
|
1251 |
|
1252 /** |
|
1253 * A static class implemented by the USB Host PIL layer to allow |
|
1254 * the host controller PSL to register to the PIL layer. |
|
1255 */ |
|
1256 NONSHARABLE_CLASS( UsbHostPil ) |
|
1257 { |
|
1258 public: |
|
1259 /** |
|
1260 * Registration function to be used by a stand-alone (non-OTG |
|
1261 * port) Host Controller PSL to register itself to the PIL |
|
1262 * layer. Host Controllers that are part of an OTG-port are |
|
1263 * registered by the OTG Controller PSL (see usb_otg_shai.h, |
|
1264 * function UsbOtgPil::RegisterOtgController). |
|
1265 * |
|
1266 * The intended usage is that each stand-alone Host Controller |
|
1267 * PSL is a kernel extension that registers itself to the USB |
|
1268 * Host PIL layer by making this call from their own kernel |
|
1269 * extension entry point function (or an equivalent code that |
|
1270 * runs during bootup). |
|
1271 * |
|
1272 * @param aHostControllerIf Reference to the Host Controller |
|
1273 * interface implemented by the registering PSL. |
|
1274 * |
|
1275 * @param aProperties Reference to an object describing the |
|
1276 * static properties of the Host Controller. The PIL layer |
|
1277 * requires that the supplied reference remains valid |
|
1278 * indefinitely, as a Host Controller cannot unregister. |
|
1279 * |
|
1280 * @lib usbotghostpil.lib |
|
1281 */ |
|
1282 IMPORT_C static void RegisterHostController( |
|
1283 MHostControllerIf& aHostControllerIf, |
|
1284 const THostControllerProperties& aProperties ); |
|
1285 }; |
|
1286 }; |
|
1287 |
|
1288 #endif // USB_HOST_SHAI_H |
|
1289 |
|
1290 /* End of File */ |
|