6c92da9c717d54fda7f4f2362f608c42cffc234b
[mirror_edk2.git] / MdeModulePkg / Bus / Usb / UsbMassStorageDxe / UsbMassBot.c
1 /** @file
2
3 Copyright (c) 2007, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
8
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
11
12 Module Name:
13
14 UsbMassBot.c
15
16 Abstract:
17
18 Implementation of the USB mass storage Bulk-Only Transport protocol.
19
20 Revision History
21
22
23 **/
24
25 #include "UsbMass.h"
26 #include "UsbMassBot.h"
27
28 UINTN mUsbBotInfo = DEBUG_INFO;
29 UINTN mUsbBotError = DEBUG_ERROR;
30
31 STATIC
32 EFI_STATUS
33 UsbBotResetDevice (
34 IN VOID *Context,
35 IN BOOLEAN ExtendedVerification
36 );
37
38
39 /**
40 Initialize the USB mass storage class BOT transport protocol.
41 It will save its context which is a USB_BOT_PROTOCOL structure
42 in the Context if Context isn't NULL.
43
44 @param UsbIo The USB IO protocol to use
45 @param Controller The controller to init
46 @param Context The variable to save the context to
47
48 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory
49 @retval EFI_UNSUPPORTED The transport protocol doesn't support the device.
50 @retval EFI_SUCCESS The device is supported and protocol initialized.
51
52 **/
53 STATIC
54 EFI_STATUS
55 UsbBotInit (
56 IN EFI_USB_IO_PROTOCOL * UsbIo,
57 IN EFI_HANDLE Controller,
58 OUT VOID **Context OPTIONAL
59 )
60 {
61 USB_BOT_PROTOCOL *UsbBot;
62 EFI_USB_INTERFACE_DESCRIPTOR *Interface;
63 EFI_USB_ENDPOINT_DESCRIPTOR EndPoint;
64 EFI_STATUS Status;
65 UINT8 Index;
66
67 //
68 // Allocate the BOT context, append two endpoint descriptors to it
69 //
70 UsbBot = AllocateZeroPool (
71 sizeof (USB_BOT_PROTOCOL) + 2 * sizeof (EFI_USB_ENDPOINT_DESCRIPTOR)
72 );
73 if (UsbBot == NULL) {
74 return EFI_OUT_OF_RESOURCES;
75 }
76
77 UsbBot->UsbIo = UsbIo;
78
79 //
80 // Get the interface descriptor and validate that it
81 // is a USB MSC BOT interface.
82 //
83 Status = UsbIo->UsbGetInterfaceDescriptor (UsbIo, &UsbBot->Interface);
84
85 if (EFI_ERROR (Status)) {
86 DEBUG ((mUsbBotError, "UsbBotInit: Get invalid BOT interface (%r)\n", Status));
87 goto ON_ERROR;
88 }
89
90 Interface = &UsbBot->Interface;
91
92 if (Interface->InterfaceProtocol != USB_MASS_STORE_BOT) {
93 Status = EFI_UNSUPPORTED;
94 goto ON_ERROR;
95 }
96
97 //
98 // Locate and save the first bulk-in and bulk-out endpoint
99 //
100 for (Index = 0; Index < Interface->NumEndpoints; Index++) {
101 Status = UsbIo->UsbGetEndpointDescriptor (UsbIo, Index, &EndPoint);
102
103 if (EFI_ERROR (Status) || !USB_IS_BULK_ENDPOINT (EndPoint.Attributes)) {
104 continue;
105 }
106
107 if (USB_IS_IN_ENDPOINT (EndPoint.EndpointAddress) &&
108 (UsbBot->BulkInEndpoint == NULL)) {
109
110 UsbBot->BulkInEndpoint = (EFI_USB_ENDPOINT_DESCRIPTOR *) (UsbBot + 1);
111 CopyMem(UsbBot->BulkInEndpoint, &EndPoint, sizeof (EndPoint));
112 }
113
114 if (USB_IS_OUT_ENDPOINT (EndPoint.EndpointAddress) &&
115 (UsbBot->BulkOutEndpoint == NULL)) {
116
117 UsbBot->BulkOutEndpoint = (EFI_USB_ENDPOINT_DESCRIPTOR *) (UsbBot + 1) + 1;
118 CopyMem(UsbBot->BulkOutEndpoint, &EndPoint, sizeof(EndPoint));
119 }
120 }
121
122 if ((UsbBot->BulkInEndpoint == NULL) || (UsbBot->BulkOutEndpoint == NULL)) {
123 DEBUG ((mUsbBotError, "UsbBotInit: In/Out Endpoint invalid\n"));
124 Status = EFI_UNSUPPORTED;
125 goto ON_ERROR;
126 }
127
128 //
129 // The USB BOT protocol uses dCBWTag to match the CBW and CSW.
130 //
131 UsbBot->CbwTag = 0x01;
132
133 if (Context != NULL) {
134 *Context = UsbBot;
135 } else {
136 gBS->FreePool (UsbBot);
137 }
138
139 return EFI_SUCCESS;
140
141 ON_ERROR:
142 gBS->FreePool (UsbBot);
143 return Status;
144 }
145
146
147 /**
148 Send the command to the device using Bulk-Out endpoint
149
150 @param UsbBot The USB BOT device
151 @param Cmd The command to transfer to device
152 @param CmdLen the length of the command
153 @param DataDir The direction of the data
154 @param TransLen The expected length of the data
155
156 @retval EFI_NOT_READY The device return NAK to the transfer
157 @retval EFI_SUCCESS The command is sent to the device.
158 @retval Others Failed to send the command to device
159
160 **/
161 STATIC
162 EFI_STATUS
163 UsbBotSendCommand (
164 IN USB_BOT_PROTOCOL *UsbBot,
165 IN UINT8 *Cmd,
166 IN UINT8 CmdLen,
167 IN EFI_USB_DATA_DIRECTION DataDir,
168 IN UINT32 TransLen
169 )
170 {
171 USB_BOT_CBW Cbw;
172 EFI_STATUS Status;
173 UINT32 Result;
174 UINTN DataLen;
175 UINTN Timeout;
176
177 ASSERT ((CmdLen > 0) && (CmdLen <= USB_BOT_MAX_CMDLEN));
178
179 //
180 // Fill in the CSW. Only the first LUN is supported now.
181 //
182 Cbw.Signature = USB_BOT_CBW_SIGNATURE;
183 Cbw.Tag = UsbBot->CbwTag;
184 Cbw.DataLen = TransLen;
185 Cbw.Flag = (UINT8) ((DataDir == EfiUsbDataIn) ? 0x80 : 0);
186 Cbw.Lun = 0;
187 Cbw.CmdLen = CmdLen;
188
189 ZeroMem (Cbw.CmdBlock, USB_BOT_MAX_CMDLEN);
190 CopyMem (Cbw.CmdBlock, Cmd, CmdLen);
191
192 Result = 0;
193 DataLen = sizeof (USB_BOT_CBW);
194 Timeout = USB_BOT_CBW_TIMEOUT / USB_MASS_STALL_1_MS;
195
196 //
197 // Use the UsbIo to send the command to the device. The default
198 // time out is enough.
199 //
200 Status = UsbBot->UsbIo->UsbBulkTransfer (
201 UsbBot->UsbIo,
202 UsbBot->BulkOutEndpoint->EndpointAddress,
203 &Cbw,
204 &DataLen,
205 Timeout,
206 &Result
207 );
208 //
209 // Respond to Bulk-Out endpoint stall with a Reset Recovery,
210 // see the spec section 5.3.1
211 //
212 if (EFI_ERROR (Status)) {
213 if (USB_IS_ERROR (Result, EFI_USB_ERR_STALL) && DataDir == EfiUsbDataOut) {
214 UsbBotResetDevice (UsbBot, FALSE);
215 } else if (USB_IS_ERROR (Result, EFI_USB_ERR_NAK)) {
216 Status = EFI_NOT_READY;
217 }
218 }
219
220 return Status;
221 }
222
223
224 /**
225 Transfer the data between the device and host. BOT transfer
226 is composed of three phase, command, data, and status.
227
228 @param UsbBot The USB BOT device
229 @param DataDir The direction of the data
230 @param Data The buffer to hold data
231 @param TransLen The expected length of the data
232 @param Timeout The time to wait the command to complete
233
234 @retval EFI_SUCCESS The data is transferred
235 @retval Others Failed to transfer data
236
237 **/
238 STATIC
239 EFI_STATUS
240 UsbBotDataTransfer (
241 IN USB_BOT_PROTOCOL *UsbBot,
242 IN EFI_USB_DATA_DIRECTION DataDir,
243 IN OUT UINT8 *Data,
244 IN OUT UINTN *TransLen,
245 IN UINT32 Timeout
246 )
247 {
248 EFI_USB_ENDPOINT_DESCRIPTOR *Endpoint;
249 EFI_STATUS Status;
250 UINT32 Result;
251
252 //
253 // It's OK if no data to transfer
254 //
255 if ((DataDir == EfiUsbNoData) || (*TransLen == 0)) {
256 return EFI_SUCCESS;
257 }
258
259 //
260 // Select the endpoint then issue the transfer
261 //
262 if (DataDir == EfiUsbDataIn) {
263 Endpoint = UsbBot->BulkInEndpoint;
264 } else {
265 Endpoint = UsbBot->BulkOutEndpoint;
266 }
267
268 Result = 0;
269 Timeout = Timeout / USB_MASS_STALL_1_MS;
270
271 Status = UsbBot->UsbIo->UsbBulkTransfer (
272 UsbBot->UsbIo,
273 Endpoint->EndpointAddress,
274 Data,
275 TransLen,
276 Timeout,
277 &Result
278 );
279 if (EFI_ERROR (Status)) {
280 DEBUG ((mUsbBotError, "UsbBotDataTransfer: (%r)\n", Status));
281 if (USB_IS_ERROR (Result, EFI_USB_ERR_STALL)) {
282 DEBUG ((mUsbBotError, "UsbBotDataTransfer: DataIn Stall\n"));
283 UsbClearEndpointStall (UsbBot->UsbIo, Endpoint->EndpointAddress);
284 } else if (USB_IS_ERROR (Result, EFI_USB_ERR_NAK)) {
285 Status = EFI_NOT_READY;
286 }
287 }
288
289 return Status;
290 }
291
292
293 /**
294 Get the command execution status from device. BOT transfer is
295 composed of three phase, command, data, and status.
296 This function return the transfer status of the BOT's CSW status,
297 and return the high level command execution result in Result. So
298 even it returns EFI_SUCCESS, the command may still have failed.
299
300 @param UsbBot The USB BOT device
301 @param TransLen The expected length of the data
302 @param Timeout The time to wait the command to complete
303 @param CmdStatus The result of the command execution.
304
305 @retval EFI_DEVICE_ERROR Failed to retrieve the command execute result
306 @retval EFI_SUCCESS Command execute result is retrieved and in the
307 Result.
308
309 **/
310 STATIC
311 EFI_STATUS
312 UsbBotGetStatus (
313 IN USB_BOT_PROTOCOL *UsbBot,
314 IN UINT32 TransLen,
315 OUT UINT8 *CmdStatus
316 )
317 {
318 USB_BOT_CSW Csw;
319 UINTN Len;
320 UINT8 Endpoint;
321 EFI_STATUS Status;
322 UINT32 Result;
323 EFI_USB_IO_PROTOCOL *UsbIo;
324 UINT32 Index;
325 UINTN Timeout;
326
327 *CmdStatus = USB_BOT_COMMAND_ERROR;
328 Status = EFI_DEVICE_ERROR;
329 Endpoint = UsbBot->BulkInEndpoint->EndpointAddress;
330 UsbIo = UsbBot->UsbIo;
331 Timeout = USB_BOT_CSW_TIMEOUT / USB_MASS_STALL_1_MS;
332
333 for (Index = 0; Index < USB_BOT_GET_STATUS_RETRY; Index++) {
334 //
335 // Attemp to the read CSW from bulk in endpoint
336 //
337 ZeroMem (&Csw, sizeof (USB_BOT_CSW));
338 Result = 0;
339 Len = sizeof (USB_BOT_CSW);
340 Status = UsbIo->UsbBulkTransfer (
341 UsbIo,
342 Endpoint,
343 &Csw,
344 &Len,
345 Timeout,
346 &Result
347 );
348 if (EFI_ERROR(Status)) {
349 DEBUG ((mUsbBotError, "UsbBotGetStatus (%r)\n", Status));
350 if (USB_IS_ERROR (Result, EFI_USB_ERR_STALL)) {
351 DEBUG ((mUsbBotError, "UsbBotGetStatus: DataIn Stall\n"));
352 UsbClearEndpointStall (UsbIo, Endpoint);
353 }
354 continue;
355 }
356
357 if (Csw.Signature != USB_BOT_CSW_SIGNATURE) {
358 //
359 // Invalid Csw need perform reset recovery
360 //
361 DEBUG ((mUsbBotError, "UsbBotGetStatus: Device return a invalid signature\n"));
362 Status = UsbBotResetDevice (UsbBot, FALSE);
363 } else if (Csw.CmdStatus == USB_BOT_COMMAND_ERROR) {
364 //
365 // Respond phase error need perform reset recovery
366 //
367 DEBUG ((mUsbBotError, "UsbBotGetStatus: Device return a phase error\n"));
368 Status = UsbBotResetDevice (UsbBot, FALSE);
369 } else {
370
371 *CmdStatus = Csw.CmdStatus;
372 break;
373 }
374 }
375 //
376 //The tag is increased even there is an error.
377 //
378 UsbBot->CbwTag++;
379
380 return Status;
381 }
382
383
384 /**
385 Call the Usb mass storage class transport protocol to issue
386 the command/data/status circle to execute the commands
387
388 @param Context The context of the BOT protocol, that is,
389 USB_BOT_PROTOCOL
390 @param Cmd The high level command
391 @param CmdLen The command length
392 @param DataDir The direction of the data transfer
393 @param Data The buffer to hold data
394 @param DataLen The length of the data
395 @param Timeout The time to wait command
396 @param CmdStatus The result of high level command execution
397
398 @retval EFI_DEVICE_ERROR Failed to excute command
399 @retval EFI_SUCCESS The command is executed OK, and result in CmdStatus
400
401 **/
402 STATIC
403 EFI_STATUS
404 UsbBotExecCommand (
405 IN VOID *Context,
406 IN VOID *Cmd,
407 IN UINT8 CmdLen,
408 IN EFI_USB_DATA_DIRECTION DataDir,
409 IN VOID *Data,
410 IN UINT32 DataLen,
411 IN UINT32 Timeout,
412 OUT UINT32 *CmdStatus
413 )
414 {
415 USB_BOT_PROTOCOL *UsbBot;
416 EFI_STATUS Status;
417 UINTN TransLen;
418 UINT8 Result;
419
420 *CmdStatus = USB_MASS_CMD_FAIL;
421 UsbBot = (USB_BOT_PROTOCOL *) Context;
422
423 //
424 // Send the command to the device. Return immediately if device
425 // rejects the command.
426 //
427 Status = UsbBotSendCommand (UsbBot, Cmd, CmdLen, DataDir, DataLen);
428 if (EFI_ERROR (Status)) {
429 DEBUG ((mUsbBotError, "UsbBotExecCommand: UsbBotSendCommand (%r)\n", Status));
430 return Status;
431 }
432
433 //
434 // Transfer the data. Don't return immediately even data transfer
435 // failed. The host should attempt to receive the CSW no matter
436 // whether it succeeds or failed.
437 //
438 TransLen = (UINTN) DataLen;
439 UsbBotDataTransfer (UsbBot, DataDir, Data, &TransLen, Timeout);
440
441 //
442 // Get the status, if that succeeds, interpret the result
443 //
444 Status = UsbBotGetStatus (UsbBot, DataLen, &Result);
445 if (EFI_ERROR (Status)) {
446 DEBUG ((mUsbBotError, "UsbBotExecCommand: UsbBotGetStatus (%r)\n", Status));
447 return Status;
448 }
449
450 if (Result == 0) {
451 *CmdStatus = USB_MASS_CMD_SUCCESS;
452 }
453
454 return EFI_SUCCESS;
455 }
456
457
458 /**
459 Reset the mass storage device by BOT protocol
460
461 @param Context The context of the BOT protocol, that is,
462 USB_BOT_PROTOCOL
463
464 @retval EFI_SUCCESS The device is reset
465 @retval Others Failed to reset the device.
466
467 **/
468 STATIC
469 EFI_STATUS
470 UsbBotResetDevice (
471 IN VOID *Context,
472 IN BOOLEAN ExtendedVerification
473 )
474 {
475 USB_BOT_PROTOCOL *UsbBot;
476 EFI_USB_DEVICE_REQUEST Request;
477 EFI_STATUS Status;
478 UINT32 Result;
479 UINT32 Timeout;
480
481 UsbBot = (USB_BOT_PROTOCOL *) Context;
482
483 if (ExtendedVerification) {
484 //
485 // If we need to do strictly reset, reset its parent hub port
486 //
487 Status = UsbBot->UsbIo->UsbPortReset (UsbBot->UsbIo);
488 if (EFI_ERROR (Status)) {
489 return Status;
490 }
491 }
492
493 //
494 // Issue a class specific "Bulk-Only Mass Storage Reset reqest.
495 // See the spec section 3.1
496 //
497 Request.RequestType = 0x21;
498 Request.Request = USB_BOT_RESET_REQUEST;
499 Request.Value = 0;
500 Request.Index = UsbBot->Interface.InterfaceNumber;
501 Request.Length = 0;
502 Timeout = USB_BOT_RESET_TIMEOUT / USB_MASS_STALL_1_MS;
503
504 Status = UsbBot->UsbIo->UsbControlTransfer (
505 UsbBot->UsbIo,
506 &Request,
507 EfiUsbNoData,
508 Timeout,
509 NULL,
510 0,
511 &Result
512 );
513
514 if (EFI_ERROR (Status)) {
515 DEBUG ((mUsbBotError, "UsbBotResetDevice: (%r)\n", Status));
516 return Status;
517 }
518
519 //
520 // The device shall NAK the host's request until the reset is
521 // complete. We can use this to sync the device and host. For
522 // now just stall 100ms to wait the device.
523 //
524 gBS->Stall (USB_BOT_RESET_STALL);
525
526 //
527 // Clear the Bulk-In and Bulk-Out stall condition.
528 //
529 UsbClearEndpointStall (UsbBot->UsbIo, UsbBot->BulkInEndpoint->EndpointAddress);
530 UsbClearEndpointStall (UsbBot->UsbIo, UsbBot->BulkOutEndpoint->EndpointAddress);
531 return Status;
532 }
533
534
535 /**
536 Clean up the resource used by this BOT protocol
537
538 @param Context The context of the BOT protocol, that is,
539 USB_BOT_PROTOCOL
540
541 @retval EFI_SUCCESS The resource is cleaned up.
542
543 **/
544 STATIC
545 EFI_STATUS
546 UsbBotFini (
547 IN VOID *Context
548 )
549 {
550 gBS->FreePool (Context);
551 return EFI_SUCCESS;
552 }
553
554 USB_MASS_TRANSPORT
555 mUsbBotTransport = {
556 USB_MASS_STORE_BOT,
557 UsbBotInit,
558 UsbBotExecCommand,
559 UsbBotResetDevice,
560 UsbBotFini
561 };