]>
Commit | Line | Data |
---|---|---|
be85bf89 FT |
1 | /** @file |
2 | The USB Function Protocol provides an I/O abstraction for a USB Controller | |
3 | operating in Function mode (also commonly referred to as Device, Peripheral, | |
4 | or Target mode) and the mechanisms by which the USB Function can communicate | |
5 | with the USB Host. It is used by other UEFI drivers or applications to | |
6 | perform data transactions and basic USB controller management over a USB | |
7 | Function port. | |
8 | ||
9 | This simple protocol only supports USB 2.0 bulk transfers on systems with a | |
10 | single configuration and a single interface. It does not support isochronous | |
11 | or interrupt transfers, alternate interfaces, or USB 3.0 functionality. | |
12 | Future revisions of this protocol may support these or additional features. | |
13 | ||
14 | Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> | |
15 | This program and the accompanying materials | |
16 | are licensed and made available under the terms and conditions of the BSD License | |
17 | which accompanies this distribution. The full text of the license may be found at | |
18 | http://opensource.org/licenses/bsd-license.php | |
19 | ||
20 | THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, | |
21 | WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. | |
22 | ||
23 | **/ | |
24 | ||
25 | #ifndef __USB_FUNCTION_IO_H__ | |
26 | #define __USB_FUNCTION_IO_H__ | |
27 | ||
28 | #include <Protocol/UsbIo.h> | |
29 | ||
30 | #define EFI_USBFN_IO_PROTOCOL_GUID \ | |
31 | { \ | |
32 | 0x32d2963a, 0xfe5d, 0x4f30, {0xb6, 0x33, 0x6e, 0x5d, 0xc5, 0x58, 0x3, 0xcc} \ | |
33 | } | |
34 | ||
35 | typedef struct _EFI_USBFN_IO_PROTOCOL EFI_USBFN_IO_PROTOCOL; | |
36 | ||
37 | #define EFI_USBFN_IO_PROTOCOL_REVISION 0x00010001 | |
38 | ||
39 | typedef enum _EFI_USBFN_PORT_TYPE { | |
40 | EfiUsbUnknownPort = 0, | |
41 | EfiUsbStandardDownstreamPort, | |
42 | EfiUsbChargingDownstreamPort, | |
43 | EfiUsbDedicatedChargingPort, | |
44 | EfiUsbInvalidDedicatedChargingPort | |
45 | } EFI_USBFN_PORT_TYPE; | |
46 | ||
47 | typedef struct { | |
48 | EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor; | |
49 | EFI_USB_ENDPOINT_DESCRIPTOR **EndpointDescriptorTable; | |
50 | } EFI_USB_INTERFACE_INFO; | |
51 | ||
52 | typedef struct { | |
53 | EFI_USB_CONFIG_DESCRIPTOR *ConfigDescriptor; | |
54 | EFI_USB_INTERFACE_INFO **InterfaceInfoTable; | |
55 | } EFI_USB_CONFIG_INFO; | |
56 | ||
57 | typedef struct { | |
58 | EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor; | |
59 | EFI_USB_CONFIG_INFO **ConfigInfoTable; | |
60 | } EFI_USB_DEVICE_INFO; | |
61 | ||
62 | typedef enum _EFI_USB_ENDPOINT_TYPE { | |
63 | UsbEndpointControl = 0x00, | |
64 | //UsbEndpointIsochronous = 0x01, | |
65 | UsbEndpointBulk = 0x02, | |
66 | //UsbEndpointInterrupt = 0x03 | |
67 | } EFI_USB_ENDPOINT_TYPE; | |
68 | ||
69 | typedef enum _EFI_USBFN_DEVICE_INFO_ID { | |
70 | EfiUsbDeviceInfoUnknown = 0, | |
71 | EfiUsbDeviceInfoSerialNumber, | |
72 | EfiUsbDeviceInfoManufacturerName, | |
73 | EfiUsbDeviceInfoProductName | |
74 | } EFI_USBFN_DEVICE_INFO_ID; | |
75 | ||
76 | typedef enum _EFI_USBFN_ENDPOINT_DIRECTION { | |
77 | EfiUsbEndpointDirectionHostOut = 0, | |
78 | EfiUsbEndpointDirectionHostIn, | |
79 | EfiUsbEndpointDirectionDeviceTx = EfiUsbEndpointDirectionHostIn, | |
80 | EfiUsbEndpointDirectionDeviceRx = EfiUsbEndpointDirectionHostOut | |
81 | } EFI_USBFN_ENDPOINT_DIRECTION; | |
82 | ||
83 | typedef enum _EFI_USBFN_MESSAGE { | |
84 | // | |
85 | // Nothing | |
86 | // | |
87 | EfiUsbMsgNone = 0, | |
88 | // | |
89 | // SETUP packet is received, returned Buffer contains | |
90 | // EFI_USB_DEVICE_REQUEST struct | |
91 | // | |
92 | EfiUsbMsgSetupPacket, | |
93 | // | |
94 | // Indicates that some of the requested data has been received from the | |
95 | // host. It is the responsibility of the class driver to determine if it | |
96 | // needs to wait for any remaining data. Returned Buffer contains | |
97 | // EFI_USBFN_TRANSFER_RESULT struct containing endpoint number, transfer | |
98 | // status and count of bytes received. | |
99 | // | |
100 | EfiUsbMsgEndpointStatusChangedRx, | |
101 | // | |
102 | // Indicates that some of the requested data has been transmitted to the | |
103 | // host. It is the responsibility of the class driver to determine if any | |
104 | // remaining data needs to be resent. Returned Buffer contains | |
105 | // EFI_USBFN_TRANSFER_RESULT struct containing endpoint number, transfer | |
106 | // status and count of bytes sent. | |
107 | // | |
108 | EfiUsbMsgEndpointStatusChangedTx, | |
109 | // | |
110 | // DETACH bus event signaled | |
111 | // | |
112 | EfiUsbMsgBusEventDetach, | |
113 | // | |
114 | // ATTACH bus event signaled | |
115 | // | |
116 | EfiUsbMsgBusEventAttach, | |
117 | // | |
118 | // RESET bus event signaled | |
119 | // | |
120 | EfiUsbMsgBusEventReset, | |
121 | // | |
122 | // SUSPEND bus event signaled | |
123 | // | |
124 | EfiUsbMsgBusEventSuspend, | |
125 | // | |
126 | // RESUME bus event signaled | |
127 | // | |
128 | EfiUsbMsgBusEventResume, | |
129 | // | |
130 | // Bus speed updated, returned buffer indicated bus speed using | |
131 | // following enumeration named EFI_USB_BUS_SPEED | |
132 | // | |
133 | EfiUsbMsgBusEventSpeed | |
134 | } EFI_USBFN_MESSAGE; | |
135 | ||
136 | typedef enum _EFI_USBFN_TRANSFER_STATUS { | |
137 | UsbTransferStatusUnknown = 0, | |
138 | UsbTransferStatusComplete, | |
139 | UsbTransferStatusAborted, | |
140 | UsbTransferStatusActive, | |
141 | UsbTransferStatusNone | |
142 | } EFI_USBFN_TRANSFER_STATUS; | |
143 | ||
144 | typedef struct _EFI_USBFN_TRANSFER_RESULT { | |
145 | UINTN BytesTransferred; | |
146 | EFI_USBFN_TRANSFER_STATUS TransferStatus; | |
147 | UINT8 EndpointIndex; | |
148 | EFI_USBFN_ENDPOINT_DIRECTION Direction; | |
149 | VOID *Buffer; | |
150 | } EFI_USBFN_TRANSFER_RESULT; | |
151 | ||
152 | typedef enum _EFI_USB_BUS_SPEED { | |
153 | UsbBusSpeedUnknown = 0, | |
154 | UsbBusSpeedLow, | |
155 | UsbBusSpeedFull, | |
156 | UsbBusSpeedHigh, | |
157 | UsbBusSpeedSuper, | |
158 | UsbBusSpeedMaximum = UsbBusSpeedSuper | |
159 | } EFI_USB_BUS_SPEED; | |
160 | ||
161 | typedef union _EFI_USBFN_MESSAGE_PAYLOAD { | |
162 | EFI_USB_DEVICE_REQUEST udr; | |
163 | EFI_USBFN_TRANSFER_RESULT utr; | |
164 | EFI_USB_BUS_SPEED ubs; | |
165 | } EFI_USBFN_MESSAGE_PAYLOAD; | |
166 | ||
167 | typedef enum _EFI_USBFN_POLICY_TYPE { | |
168 | EfiUsbPolicyUndefined = 0, | |
169 | EfiUsbPolicyMaxTransactionSize, | |
170 | EfiUsbPolicyZeroLengthTerminationSupport, | |
171 | EfiUsbPolicyZeroLengthTermination | |
172 | } EFI_USBFN_POLICY_TYPE; | |
173 | ||
174 | /** | |
175 | Returns information about what USB port type was attached. | |
176 | ||
177 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
178 | @param[out] PortType Returns the USB port type. | |
179 | ||
180 | @retval EFI_SUCCESS The function returned successfully. | |
181 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
182 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
183 | @retval EFI_NOT_READY The physical device is busy or not ready to | |
184 | process this request or there is no USB port | |
185 | attached to the device. | |
186 | ||
187 | **/ | |
188 | typedef | |
189 | EFI_STATUS | |
190 | (EFIAPI *EFI_USBFN_IO_DETECT_PORT) ( | |
191 | IN EFI_USBFN_IO_PROTOCOL *This, | |
192 | OUT EFI_USBFN_PORT_TYPE *PortType | |
193 | ); | |
194 | ||
195 | /** | |
196 | Configures endpoints based on supplied device and configuration descriptors. | |
197 | ||
198 | Assuming that the hardware has already been initialized, this function configures | |
199 | the endpoints using the device information supplied by DeviceInfo, activates the | |
200 | port, and starts receiving USB events. | |
201 | ||
202 | This function must ignore the bMaxPacketSize0field of the Standard Device Descriptor | |
203 | and the wMaxPacketSize field of the Standard Endpoint Descriptor that are made | |
204 | available through DeviceInfo. | |
205 | ||
206 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
207 | @param[out] DeviceInfo A pointer to EFI_USBFN_DEVICE_INFO instance. | |
208 | ||
209 | @retval EFI_SUCCESS The function returned successfully. | |
210 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
211 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
212 | @retval EFI_NOT_READY The physical device is busy or not ready to process | |
213 | this request. | |
214 | @retval EFI_OUT_OF_RESOURCES The request could not be completed due to lack of | |
215 | resources. | |
216 | ||
217 | **/ | |
218 | typedef | |
219 | EFI_STATUS | |
220 | (EFIAPI *EFI_USBFN_IO_CONFIGURE_ENABLE_ENDPOINTS) ( | |
221 | IN EFI_USBFN_IO_PROTOCOL *This, | |
222 | OUT EFI_USB_DEVICE_INFO *DeviceInfo | |
223 | ); | |
224 | ||
225 | /** | |
226 | Returns the maximum packet size of the specified endpoint type for the supplied | |
227 | bus speed. | |
228 | ||
229 | If the BusSpeed is UsbBusSpeedUnknown, the maximum speed the underlying controller | |
230 | supports is assumed. | |
231 | ||
232 | This protocol currently does not support isochronous or interrupt transfers. Future | |
233 | revisions of this protocol may eventually support it. | |
234 | ||
235 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. | |
236 | @param[in] EndpointType Endpoint type as defined as EFI_USB_ENDPOINT_TYPE. | |
237 | @param[in] BusSpeed Bus speed as defined as EFI_USB_BUS_SPEED. | |
238 | @param[out] MaxPacketSize The maximum packet size, in bytes, of the specified | |
239 | endpoint type. | |
240 | ||
241 | @retval EFI_SUCCESS The function returned successfully. | |
242 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
243 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
244 | @retval EFI_NOT_READY The physical device is busy or not ready to process | |
245 | this request. | |
246 | ||
247 | **/ | |
248 | typedef | |
249 | EFI_STATUS | |
250 | (EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_MAXPACKET_SIZE) ( | |
251 | IN EFI_USBFN_IO_PROTOCOL *This, | |
252 | IN EFI_USB_ENDPOINT_TYPE EndpointType, | |
253 | IN EFI_USB_BUS_SPEED BusSpeed, | |
254 | OUT UINT16 *MaxPacketSize | |
255 | ); | |
256 | ||
257 | /** | |
258 | Returns device specific information based on the supplied identifier as a Unicode string. | |
259 | ||
260 | If the supplied Buffer isn't large enough, or is NULL, the method fails with | |
261 | EFI_BUFFER_TOO_SMALL and the required size is returned through BufferSize. All returned | |
262 | strings are in Unicode format. | |
263 | ||
264 | An Id of EfiUsbDeviceInfoUnknown is treated as an invalid parameter. | |
265 | ||
266 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. | |
267 | @param[in] Id The requested information id. | |
268 | ||
269 | ||
270 | @param[in] BufferSize On input, the size of the Buffer in bytes. On output, the | |
271 | amount of data returned in Buffer in bytes. | |
272 | @param[out] Buffer A pointer to a buffer to returnthe requested information | |
273 | as a Unicode string. | |
274 | ||
275 | @retval EFI_SUCCESS The function returned successfully. | |
276 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
277 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
278 | @retval EFI_BUFFER_TOO_SMALL Supplied buffer isn't large enough to hold the request string. | |
279 | ||
280 | **/ | |
281 | typedef | |
282 | EFI_STATUS | |
283 | (EFIAPI *EFI_USBFN_IO_GET_DEVICE_INFO) ( | |
284 | IN EFI_USBFN_IO_PROTOCOL *This, | |
285 | IN EFI_USBFN_DEVICE_INFO_ID Id, | |
286 | IN OUT UINTN *BufferSize, | |
287 | OUT VOID *Buffer OPTIONAL | |
288 | ); | |
289 | ||
290 | /** | |
291 | Returns the vendor-id and product-id of the device. | |
292 | ||
293 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
294 | @param[out] Vid Returned vendor-id of the device. | |
295 | @param[out] Pid Returned product-id of the device. | |
296 | ||
297 | @retval EFI_SUCCESS The function returned successfully. | |
298 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
299 | @retval EFI_NOT_FOUND Unable to return the vendor-id or the product-id. | |
300 | ||
301 | **/ | |
302 | typedef | |
303 | EFI_STATUS | |
304 | (EFIAPI *EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID) ( | |
305 | IN EFI_USBFN_IO_PROTOCOL *This, | |
306 | OUT UINT16 *Vid, | |
307 | OUT UINT16 *Pid | |
308 | ); | |
309 | ||
310 | /** | |
311 | Aborts the transfer on the specified endpoint. | |
312 | ||
313 | This function should fail with EFI_INVALID_PARAMETER if the specified direction | |
314 | is incorrect for the endpoint. | |
315 | ||
316 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
317 | @param[in] EndpointIndex Indicates the endpoint on which the ongoing transfer | |
318 | needs to be canceled. | |
319 | @param[in] Direction Direction of the endpoint. | |
320 | ||
321 | @retval EFI_SUCCESS The function returned successfully. | |
322 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
323 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
324 | @retval EFI_NOT_READY The physical device is busy or not ready to process | |
325 | this request. | |
326 | ||
327 | **/ | |
328 | typedef | |
329 | EFI_STATUS | |
330 | (EFIAPI *EFI_USBFN_IO_ABORT_TRANSFER) ( | |
331 | IN EFI_USBFN_IO_PROTOCOL *This, | |
332 | IN UINT8 EndpointIndex, | |
333 | IN EFI_USBFN_ENDPOINT_DIRECTION Direction | |
334 | ); | |
335 | ||
336 | /** | |
337 | Returns the stall state on the specified endpoint. | |
338 | ||
339 | This function should fail with EFI_INVALID_PARAMETER if the specified direction | |
340 | is incorrect for the endpoint. | |
341 | ||
342 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
343 | @param[in] EndpointIndex Indicates the endpoint. | |
344 | @param[in] Direction Direction of the endpoint. | |
345 | @param[in, out] State Boolean, true value indicates that the endpoint | |
346 | is in a stalled state, false otherwise. | |
347 | ||
348 | @retval EFI_SUCCESS The function returned successfully. | |
349 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
350 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
351 | @retval EFI_NOT_READY The physical device is busy or not ready to process | |
352 | this request. | |
353 | ||
354 | **/ | |
355 | typedef | |
356 | EFI_STATUS | |
357 | (EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE) ( | |
358 | IN EFI_USBFN_IO_PROTOCOL *This, | |
359 | IN UINT8 EndpointIndex, | |
360 | IN EFI_USBFN_ENDPOINT_DIRECTION Direction, | |
361 | IN OUT BOOLEAN *State | |
362 | ); | |
363 | ||
364 | /** | |
365 | Sets or clears the stall state on the specified endpoint. | |
366 | ||
367 | This function should fail with EFI_INVALID_PARAMETER if the specified direction | |
368 | is incorrect for the endpoint. | |
369 | ||
370 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
371 | @param[in] EndpointIndex Indicates the endpoint. | |
372 | @param[in] Direction Direction of the endpoint. | |
373 | @param[in] State Requested stall state on the specified endpoint. | |
374 | True value causes the endpoint to stall; false | |
375 | value clears an existing stall. | |
376 | ||
377 | @retval EFI_SUCCESS The function returned successfully. | |
378 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
379 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
380 | @retval EFI_NOT_READY The physical device is busy or not ready to process | |
381 | this request. | |
382 | ||
383 | **/ | |
384 | typedef | |
385 | EFI_STATUS | |
386 | (EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE) ( | |
387 | IN EFI_USBFN_IO_PROTOCOL *This, | |
388 | IN UINT8 EndpointIndex, | |
389 | IN EFI_USBFN_ENDPOINT_DIRECTION Direction, | |
390 | IN OUT BOOLEAN *State | |
391 | ); | |
392 | ||
393 | /** | |
394 | This function is called repeatedly to get information on USB bus states, | |
395 | receive-completion and transmit-completion events on the endpoints, and | |
396 | notification on setup packet on endpoint 0. | |
397 | ||
398 | A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler()repeatedly | |
399 | to receive updates on the transfer status and number of bytes transferred | |
400 | on various endpoints. | |
401 | ||
402 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
403 | @param[out] Message Indicates the event that initiated this notification. | |
404 | @param[in, out] PayloadSize On input, the size of the memory pointed by | |
405 | Payload. On output, the amount ofdata returned | |
406 | in Payload. | |
407 | @param[out] Payload A pointer to EFI_USBFN_MESSAGE_PAYLOAD instance | |
408 | to return additional payload for current message. | |
409 | ||
410 | @retval EFI_SUCCESS The function returned successfully. | |
411 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
412 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
413 | @retval EFI_NOT_READY The physical device is busy or not ready to process | |
414 | this request. | |
415 | @retval EFI_BUFFER_TOO_SMALL The Supplied buffer is not large enough to hold | |
416 | the message payload. | |
417 | ||
418 | **/ | |
419 | typedef | |
420 | EFI_STATUS | |
421 | (EFIAPI *EFI_USBFN_IO_EVENTHANDLER) ( | |
422 | IN EFI_USBFN_IO_PROTOCOL *This, | |
423 | OUT EFI_USBFN_MESSAGE *Message, | |
424 | IN OUT UINTN *PayloadSize, | |
425 | OUT EFI_USBFN_MESSAGE_PAYLOAD *Payload | |
426 | ); | |
427 | ||
428 | /** | |
429 | This function handles transferring data to or from the host on the specified | |
430 | endpoint, depending on the direction specified. | |
431 | ||
432 | A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler() repeatedly to | |
433 | receive updates on the transfer status and the number of bytes transferred on | |
434 | various endpoints. Upon an update of the transfer status, the Buffer field of | |
435 | the EFI_USBFN_TRANSFER_RESULT structure (as described in the function description | |
436 | for EFI_USBFN_IO_PROTOCOL.EventHandler()) must be initialized with the Buffer | |
437 | pointer that was supplied to this method. | |
438 | ||
439 | The overview of the call sequence is illustrated in the Figure 54. | |
440 | ||
441 | This function should fail with EFI_INVALID_PARAMETER if the specified direction | |
442 | is incorrect for the endpoint. | |
443 | ||
444 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
445 | @param[in] EndpointIndex Indicates the endpoint on which TX or RX transfer | |
446 | needs to take place. | |
447 | @param[in] Direction Direction of the endpoint. | |
448 | @param[in, out] BufferSize If Direction is EfiUsbEndpointDirectionDeviceRx: | |
449 | On input, the size of the Bufferin bytes. | |
450 | On output, the amount of data returned in Buffer | |
451 | in bytes. | |
452 | If Direction is EfiUsbEndpointDirectionDeviceTx: | |
453 | On input, the size of the Bufferin bytes. | |
454 | On output, the amount of data transmitted in bytes. | |
455 | @param[in, out] Buffer If Direction is EfiUsbEndpointDirectionDeviceRx: | |
456 | The Buffer to return the received data. | |
457 | If Directionis EfiUsbEndpointDirectionDeviceTx: | |
458 | The Buffer that contains the data to be transmitted. | |
459 | ||
460 | @retval EFI_SUCCESS The function returned successfully. | |
461 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
462 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
463 | @retval EFI_NOT_READY The physical device is busy or not ready to process | |
464 | this request. | |
465 | ||
466 | **/ | |
467 | typedef | |
468 | EFI_STATUS | |
469 | (EFIAPI *EFI_USBFN_IO_TRANSFER) ( | |
470 | IN EFI_USBFN_IO_PROTOCOL *This, | |
471 | IN UINT8 EndpointIndex, | |
472 | IN EFI_USBFN_ENDPOINT_DIRECTION Direction, | |
473 | IN OUT UINTN *BufferSize, | |
474 | IN OUT VOID *Buffer | |
475 | ); | |
476 | ||
477 | /** | |
478 | Returns the maximum supported transfer size. | |
479 | ||
480 | Returns the maximum number of bytes that the underlying controller can accommodate | |
481 | in a single transfer. | |
482 | ||
483 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
484 | @param[out] MaxTransferSize The maximum supported transfer size, in bytes. | |
485 | ||
486 | @retval EFI_SUCCESS The function returned successfully. | |
487 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
488 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
489 | @retval EFI_NOT_READY The physical device is busy or not ready to process | |
490 | this request. | |
491 | ||
492 | **/ | |
493 | typedef | |
494 | EFI_STATUS | |
495 | (EFIAPI *EFI_USBFN_IO_GET_MAXTRANSFER_SIZE) ( | |
496 | IN EFI_USBFN_IO_PROTOCOL *This, | |
497 | OUT UINTN *MaxTransferSize | |
498 | ); | |
499 | ||
500 | /** | |
501 | Allocates a transfer buffer of the specified sizethat satisfies the controller | |
502 | requirements. | |
503 | ||
504 | The AllocateTransferBuffer() function allocates a memory region of Size bytes and | |
505 | returns the address of the allocated memory that satisfies the underlying controller | |
506 | requirements in the location referenced by Buffer. | |
507 | ||
508 | The allocated transfer buffer must be freed using a matching call to | |
509 | EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer()function. | |
510 | ||
511 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
512 | @param[in] Size The number of bytes to allocate for the transfer buffer. | |
513 | @param[out] Buffer A pointer to a pointer to the allocated buffer if the | |
514 | call succeeds; undefined otherwise. | |
515 | ||
516 | @retval EFI_SUCCESS The function returned successfully. | |
517 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
518 | @retval EFI_OUT_OF_RESOURCES The requested transfer buffer could not be allocated. | |
519 | ||
520 | **/ | |
521 | typedef | |
522 | EFI_STATUS | |
523 | (EFIAPI *EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER) ( | |
524 | IN EFI_USBFN_IO_PROTOCOL *This, | |
525 | IN UINTN Size, | |
526 | OUT VOID **Buffer | |
527 | ); | |
528 | ||
529 | /** | |
530 | Deallocates the memory allocated for the transfer buffer by the | |
531 | EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer() function. | |
532 | ||
533 | The EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer() function deallocates the | |
534 | memory specified by Buffer. The Buffer that is freed must have been allocated | |
535 | by EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer(). | |
536 | ||
537 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
538 | @param[in] Buffer A pointer to the transfer buffer to deallocate. | |
539 | ||
540 | @retval EFI_SUCCESS The function returned successfully. | |
541 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
542 | ||
543 | **/ | |
544 | typedef | |
545 | EFI_STATUS | |
546 | (EFIAPI *EFI_USBFN_IO_FREE_TRANSFER_BUFFER) ( | |
547 | IN EFI_USBFN_IO_PROTOCOL *This, | |
548 | IN VOID *Buffer | |
549 | ); | |
550 | ||
551 | /** | |
552 | This function supplies power to the USB controller if needed and initializes | |
553 | the hardware and the internal data structures. The port must not be activated | |
554 | by this function. | |
555 | ||
556 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
557 | ||
558 | @retval EFI_SUCCESS The function returned successfully. | |
559 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
560 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
561 | ||
562 | **/ | |
563 | typedef | |
564 | EFI_STATUS | |
565 | (EFIAPI *EFI_USBFN_IO_START_CONTROLLER) ( | |
566 | IN EFI_USBFN_IO_PROTOCOL *This | |
567 | ); | |
568 | ||
569 | /** | |
570 | This function stops the USB hardware device. | |
571 | ||
572 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
573 | ||
574 | @retval EFI_SUCCESS The function returned successfully. | |
575 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
576 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
577 | ||
578 | **/ | |
579 | typedef | |
580 | EFI_STATUS | |
581 | (EFIAPI *EFI_USBFN_IO_STOP_CONTROLLER) ( | |
582 | IN EFI_USBFN_IO_PROTOCOL *This | |
583 | ); | |
584 | ||
585 | /** | |
586 | This function sets the configuration policy for the specified non-control | |
587 | endpoint. | |
588 | ||
589 | This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController() | |
590 | or after EFI_USBFN_IO_PROTOCOL.StopController() has been called. | |
591 | ||
592 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
593 | @param[in] EndpointIndex Indicates the non-control endpoint for which the | |
594 | policy needs to be set. | |
595 | @param[in] Direction Direction of the endpoint. | |
596 | @param[in] PolicyType Policy type the user is trying to set for the | |
597 | specified non-control endpoint. | |
598 | @param[in] BufferSize The size of the Bufferin bytes. | |
599 | @param[in] Buffer The new value for the policy parameter that | |
600 | PolicyType specifies. | |
601 | ||
602 | @retval EFI_SUCCESS The function returned successfully. | |
603 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
604 | @retval EFI_DEVICE_ERROR The physical device reported an error. | |
605 | @retval EFI_UNSUPPORTED Changing this policy value is not supported. | |
606 | ||
607 | **/ | |
608 | typedef | |
609 | EFI_STATUS | |
610 | (EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_POLICY) ( | |
611 | IN EFI_USBFN_IO_PROTOCOL *This, | |
612 | IN UINT8 EndpointIndex, | |
613 | IN EFI_USBFN_ENDPOINT_DIRECTION Direction, | |
614 | IN EFI_USBFN_POLICY_TYPE PolicyType, | |
615 | IN UINTN BufferSize, | |
616 | IN VOID *Buffer | |
617 | ); | |
618 | ||
619 | /** | |
620 | This function sets the configuration policy for the specified non-control | |
621 | endpoint. | |
622 | ||
623 | This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController() | |
624 | or after EFI_USBFN_IO_PROTOCOL.StopController() has been called. | |
625 | ||
626 | @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. | |
627 | @param[in] EndpointIndex Indicates the non-control endpoint for which the | |
628 | policy needs to be set. | |
629 | @param[in] Direction Direction of the endpoint. | |
630 | @param[in] PolicyType Policy type the user is trying to retrieve for | |
631 | the specified non-control endpoint. | |
632 | @param[in, out] BufferSize On input, the size of Bufferin bytes. On output, | |
633 | the amount of data returned in Bufferin bytes. | |
634 | @param[in, out] Buffer A pointer to a buffer to return requested endpoint | |
635 | policy value. | |
636 | ||
637 | @retval EFI_SUCCESS The function returned successfully. | |
638 | @retval EFI_INVALID_PARAMETER A parameter is invalid. | |
639 | @retval EFI_DEVICE_ERROR The specified policy value is not supported. | |
640 | @retval EFI_BUFFER_TOO_SMALL Supplied buffer is not large enough to hold requested | |
641 | policy value. | |
642 | ||
643 | **/ | |
644 | typedef | |
645 | EFI_STATUS | |
646 | (EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_POLICY) ( | |
647 | IN EFI_USBFN_IO_PROTOCOL *This, | |
648 | IN UINT8 EndpointIndex, | |
649 | IN EFI_USBFN_ENDPOINT_DIRECTION Direction, | |
650 | IN EFI_USBFN_POLICY_TYPE PolicyType, | |
651 | IN OUT UINTN *BufferSize, | |
652 | IN OUT VOID *Buffer | |
653 | ); | |
654 | ||
655 | /// | |
656 | /// The EFI_USBFN_IO_PROTOCOL provides basic data transactions and basic USB | |
657 | /// controller management for a USB Function port. | |
658 | /// | |
659 | struct _EFI_USBFN_IO_PROTOCOL { | |
660 | UINT32 Revision; | |
661 | EFI_USBFN_IO_DETECT_PORT DetectPort; | |
662 | EFI_USBFN_IO_CONFIGURE_ENABLE_ENDPOINTS ConfigureEnableEndpoints; | |
663 | EFI_USBFN_IO_GET_ENDPOINT_MAXPACKET_SIZE GetEndpointMaxPacketSize; | |
664 | EFI_USBFN_IO_GET_DEVICE_INFO GetDeviceInfo; | |
665 | EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID GetVendorIdProductId; | |
666 | EFI_USBFN_IO_ABORT_TRANSFER AbortTransfer; | |
667 | EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE GetEndpointStallState; | |
668 | EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE SetEndpointStallState; | |
669 | EFI_USBFN_IO_EVENTHANDLER EventHandler; | |
670 | EFI_USBFN_IO_TRANSFER Transfer; | |
671 | EFI_USBFN_IO_GET_MAXTRANSFER_SIZE GetMaxTransferSize; | |
672 | EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER AllocateTransferBuffer; | |
673 | EFI_USBFN_IO_FREE_TRANSFER_BUFFER FreeTransferBuffer; | |
674 | EFI_USBFN_IO_START_CONTROLLER StartController; | |
675 | EFI_USBFN_IO_STOP_CONTROLLER StopController; | |
676 | EFI_USBFN_IO_SET_ENDPOINT_POLICY SetEndpointPolicy; | |
677 | EFI_USBFN_IO_GET_ENDPOINT_POLICY GetEndpointPolicy; | |
678 | }; | |
679 | ||
680 | extern EFI_GUID gEfiUsbFunctionIoProtocolGuid; | |
681 | ||
682 | #endif | |
683 |