Demos/Host/MassStorageHost/MassStoreCommands.c

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2009.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6       www.fourwalledcubicle.com
   7 */
   8
   9 /*
  10   Copyright 2009  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, and distribute this software
  13   and its documentation for any purpose and without fee is hereby
  14   granted, provided that the above copyright notice appear in all
  15   copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaim all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *
  33  *  Mass Storage Device commands, to issue MSD commands to the device for
  34  *  reading device status, capacity, and other characteristics. This file
  35  *  also contains block read and write functions, so that device blocks
  36  *  can be read and written. In general, these functions would be chained
  37  *  to a FAT library to give file-level access to an attached device's contents.
  38  *
  39  *  \note Many Mass Storage devices on the market are non-compliant to the
  40  *        specifications and thus can prove difficult to interface with. It
  41  *        may be necessary to retry the functions in the module several times
  42  *        after they have returned and error to successfully send the command
  43  *        to the device. Some devices may also need to have the stream function
  44  *        timeout period extended beyond 100ms (some badly designed devices exceeding
  45  *        1.5 seconds occasionally) by defining USB_STREAM_TIMEOUT_MS to a
  46  *        larger value in the project makefile and passing it to the compiler
  47  *        via the -D switch.
  48  */
  49
  50 #define  INCLUDE_FROM_MASSSTORE_COMMANDS_C
  51 #include "MassStoreCommands.h"
  52
  53 /* Globals: */
  54 /** Current CBW to send to the device. This is automatically filled by the routines
  55  *  in this file and is not externally accessible.
  56  */
  57 static CommandBlockWrapper_t  SCSICommandBlock;
  58
  59 /** Current CSW received from the device. This is automatically filled by the routines
  60  *  in this file and is externally accessible so that the return codes may be checked.
  61  */
  62 CommandStatusWrapper_t        SCSICommandStatus;
  63
  64 /** Current Tag value used in issued CBWs to the device. This is automatically incremented
  65  *  by the routines in this file, and is not externally accessible.
  66  */
  67 static uint32_t               MassStore_Tag = 1;
  68
  69
  70 /** Routine to send the current CBW to the device, and increment the Tag value as needed.
  71  *
  72  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
  73  */
  74 static uint8_t MassStore_SendCommand(void)
  75 {
  76         uint8_t ErrorCode = PIPE_RWSTREAM_ERROR_NoError;
  77
  78         /* Each transmission should have a unique tag value, excluding valued 0 and 0xFFFFFFFF */
  79         if (++MassStore_Tag == 0xFFFFFFFF)
  80           MassStore_Tag = 1;
  81
  82         /* Select the OUT data pipe for CBW transmission */
  83         Pipe_SelectPipe(MASS_STORE_DATA_OUT_PIPE);
  84         Pipe_Unfreeze();
  85
  86         /* Write the CBW command to the OUT pipe */
  87         if ((ErrorCode = Pipe_Write_Stream_LE(&SCSICommandBlock, sizeof(CommandBlockWrapper_t))) != PIPE_RWSTREAM_ERROR_NoError)
  88           return ErrorCode;
  89
  90         /* Send the data in the OUT pipe to the attached device */
  91         Pipe_ClearCurrentBank();
  92
  93         /* Some buggy devices require a delay here before the pipe freezing or they will lock up */
  94         USB_Host_WaitMS(1);
  95
  96         /* Freeze pipe after use */
  97         Pipe_Freeze();
  98
  99         return PIPE_RWSTREAM_ERROR_NoError;
 100 }
 101
 102 /** Waits until the attached device is ready to accept data following a CBW, checking
 103  *  to ensure that the device has not stalled the transaction.
 104  *
 105  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 106  */
 107 static uint8_t MassStore_WaitForDataReceived(void)
 108 {
 109         uint16_t TimeoutMSRem = COMMAND_DATA_TIMEOUT_MS;
 110
 111         /* Unfreeze the OUT pipe so that it can be checked */
 112         Pipe_SelectPipe(MASS_STORE_DATA_OUT_PIPE);
 113         Pipe_Unfreeze();
 114
 115         /* Select the IN data pipe for data reception */
 116         Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 117         Pipe_Unfreeze();
 118
 119         /* Wait until data received in the IN pipe */
 120         while (!(Pipe_ReadWriteAllowed()))
 121         {
 122                 /* Check to see if a new frame has been issued (1ms elapsed) */
 123                 if (USB_INT_HasOccurred(USB_INT_HSOFI))
 124                 {
 125                         /* Clear the flag and decrement the timeout period counter */
 126                         USB_INT_Clear(USB_INT_HSOFI);
 127                         TimeoutMSRem--;
 128
 129                         /* Check to see if the timeout period for the command has elapsed */
 130                         if (!(TimeoutMSRem))
 131                           return PIPE_RWSTREAM_ERROR_Timeout;
 132                 }
 133
 134                 Pipe_SelectPipe(MASS_STORE_DATA_OUT_PIPE);
 135
 136                 /* Check if pipe stalled (command failed by device) */
 137                 if (Pipe_IsStalled())
 138                 {
 139                         /* Clear the stall condition on the OUT pipe */
 140                         MassStore_ClearPipeStall(MASS_STORE_DATA_OUT_PIPE);
 141
 142                         return PIPE_RWSTREAM_ERROR_PipeStalled;
 143                 }
 144
 145                 Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 146
 147                 /* Check if pipe stalled (command failed by device) */
 148                 if (Pipe_IsStalled())
 149                 {
 150                         /* Clear the stall condition on the IN pipe */
 151                         MassStore_ClearPipeStall(MASS_STORE_DATA_IN_PIPE);
 152
 153                         return PIPE_RWSTREAM_ERROR_PipeStalled;
 154                 }
 155
 156                 /* Check to see if the device was disconnected, if so exit function */
 157                 if (!(USB_IsConnected))
 158                   return PIPE_RWSTREAM_ERROR_DeviceDisconnected;
 159         };
 160
 161         return PIPE_RWSTREAM_ERROR_NoError;
 162 }
 163
 164 /** Sends or receives the transaction's data stage to or from the attached device, reading or
 165  *  writing to the nominated buffer.
 166  *
 167  *  \param  BufferPtr  Pointer to the data buffer to read from or write to
 168  *
 169  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 170  */
 171 static uint8_t MassStore_SendReceiveData(void* BufferPtr)
 172 {
 173         uint8_t  ErrorCode = PIPE_RWSTREAM_ERROR_NoError;
 174         uint16_t BytesRem  = SCSICommandBlock.Header.DataTransferLength;
 175
 176         /* Check the direction of the SCSI command data stage */
 177         if (SCSICommandBlock.Header.Flags & COMMAND_DIRECTION_DATA_IN)
 178         {
 179                 /* Select the IN data pipe for data reception */
 180                 Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 181                 Pipe_Unfreeze();
 182
 183                 /* Read in the block data from the pipe */
 184                 if ((ErrorCode = Pipe_Read_Stream_LE(BufferPtr, BytesRem)) != PIPE_RWSTREAM_ERROR_NoError)
 185                   return ErrorCode;
 186         }
 187         else
 188         {
 189                 /* Select the OUT data pipe for data transmission */
 190                 Pipe_SelectPipe(MASS_STORE_DATA_OUT_PIPE);
 191                 Pipe_Unfreeze();
 192
 193                 /* Write the block data to the pipe */
 194                 if ((ErrorCode = Pipe_Write_Stream_LE(BufferPtr, BytesRem)) != PIPE_RWSTREAM_ERROR_NoError)
 195                   return ErrorCode;
 196         }
 197
 198         /* Acknowledge the packet */
 199         Pipe_ClearCurrentBank();
 200
 201         /* Some buggy devices require a delay here before the pipe freezing or they will lock up */
 202         USB_Host_WaitMS(1);
 203
 204         /* Freeze used pipe after use */
 205         Pipe_Freeze();
 206
 207         return PIPE_RWSTREAM_ERROR_NoError;
 208 }
 209
 210 /** Routine to receive the current CSW from the device.
 211  *
 212  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 213  */
 214 static uint8_t MassStore_GetReturnedStatus(void)
 215 {
 216         uint8_t ErrorCode = PIPE_RWSTREAM_ERROR_NoError;
 217
 218         /* If an error in the command ocurred, abort */
 219         if (MassStore_WaitForDataReceived() != NoError)
 220           return;
 221
 222         /* Select the IN data pipe for data reception */
 223         Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 224         Pipe_Unfreeze();
 225
 226         /* Load in the CSW from the attached device */
 227         if ((ErrorCode = Pipe_Read_Stream_LE(&SCSICommandStatus, sizeof(CommandStatusWrapper_t))) != PIPE_RWSTREAM_ERROR_NoError)
 228           return ErrorCode;
 229
 230         /* Clear the data ready for next reception */
 231         Pipe_ClearCurrentBank();
 232
 233         /* Some buggy devices require a delay here before the pipe freezing or they will lock up */
 234         USB_Host_WaitMS(1);
 235
 236         /* Freeze the IN pipe after use */
 237         Pipe_Freeze();
 238
 239         return PIPE_RWSTREAM_ERROR_NoError;
 240 }
 241
 242 /** Clears the stall condition in the attached device on the nominated endpoint number.
 243  *
 244  *  \param EndpointNum  Endpoint number in the attached device whose stall condition is to be cleared
 245  *
 246  *  \return A value from the USB_Host_SendControlErrorCodes_t enum
 247  */
 248 uint8_t MassStore_ClearPipeStall(const uint8_t EndpointNum)
 249 {
 250         USB_HostRequest = (USB_Host_Request_Header_t)
 251                 {
 252                         bmRequestType: (REQDIR_HOSTTODEVICE | REQTYPE_STANDARD | REQREC_ENDPOINT),
 253                         bRequest:      REQ_ClearFeature,
 254                         wValue:        FEATURE_ENDPOINT_HALT,
 255                         wIndex:        EndpointNum,
 256                         wLength:       0,
 257                 };
 258
 259         return USB_Host_SendControlRequest(NULL);
 260 }
 261
 262 /** Issues a Mass Storage class specific request to reset the attached device's Mass Storage interface,
 263  *  readying the device for the next CBW.
 264  *
 265  *  \return A value from the USB_Host_SendControlErrorCodes_t enum
 266  */
 267 uint8_t MassStore_MassStorageReset(void)
 268 {
 269         USB_HostRequest = (USB_Host_Request_Header_t)
 270                 {
 271                         bmRequestType: (REQDIR_HOSTTODEVICE | REQTYPE_CLASS | REQREC_INTERFACE),
 272                         bRequest:      REQ_MassStorageReset,
 273                         wValue:        0,
 274                         wIndex:        0,
 275                         wLength:       0,
 276                 };
 277
 278         return USB_Host_SendControlRequest(NULL);
 279 }
 280
 281 /** Issues a Mass Storage class specific request to determine the index of the highest numbered Logical
 282  *  Unit in the attached device.
 283  *
 284  *  \param MaxLUNIndex  Pointer to the location that the maximum LUN index value should be stored
 285  *
 286  *  \return A value from the USB_Host_SendControlErrorCodes_t enum
 287  */
 288 uint8_t MassStore_GetMaxLUN(uint8_t* const MaxLUNIndex)
 289 {
 290         uint8_t ErrorCode;
 291
 292         USB_HostRequest = (USB_Host_Request_Header_t)
 293                 {
 294                         bmRequestType: (REQDIR_DEVICETOHOST | REQTYPE_CLASS | REQREC_INTERFACE),
 295                         bRequest:      REQ_GetMaxLUN,
 296                         wValue:        0,
 297                         wIndex:        0,
 298                         wLength:       1,
 299                 };
 300
 301         if ((ErrorCode = USB_Host_SendControlRequest(MaxLUNIndex)) == HOST_SENDCONTROL_SetupStalled)
 302         {
 303                 /* Clear the pipe stall */
 304                 Pipe_ClearStall();
 305
 306                 /* Some faulty Mass Storage devices don't implement the GET_MAX_LUN request, so assume a single LUN */
 307                 *MaxLUNIndex = 0;
 308         }
 309
 310         return ErrorCode;
 311 }
 312
 313 /** Issues a SCSI Request Sense command to the attached device, to determine the current SCSI sense information. This
 314  *  gives error codes for the last issued SCSI command to the device.
 315  *
 316  *  \param LUNIndex  Index of the LUN inside the device the command is being addressed to
 317  *  \param SensePtr  Pointer to the sense data structure where the sense data from the device is to be stored
 318  *
 319  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 320  */
 321 uint8_t MassStore_RequestSense(const uint8_t LUNIndex, const SCSI_Request_Sense_Response_t* const SensePtr)
 322 {
 323         uint8_t ReturnCode = PIPE_RWSTREAM_ERROR_NoError;
 324
 325         /* Create a CBW with a SCSI command to issue REQUEST SENSE command */
 326         SCSICommandBlock = (CommandBlockWrapper_t)
 327                 {
 328                         Header:
 329                                 {
 330                                         Signature:          CBW_SIGNATURE,
 331                                         Tag:                MassStore_Tag,
 332                                         DataTransferLength: sizeof(SCSI_Request_Sense_Response_t),
 333                                         Flags:              COMMAND_DIRECTION_DATA_IN,
 334                                         LUN:                LUNIndex,
 335                                         SCSICommandLength:  6
 336                                 },
 337
 338                         SCSICommandData:
 339                                 {
 340                                         SCSI_CMD_REQUEST_SENSE,
 341                                         0x00,                   // Reserved
 342                                         0x00,                   // Reserved
 343                                         0x00,                   // Reserved
 344                                         sizeof(SCSI_Request_Sense_Response_t), // Allocation Length
 345                                         0x00                    // Unused (control)
 346                                 }
 347                 };
 348
 349         /* Send SCSI command to the attached device */
 350         MassStore_SendCommand();
 351
 352         /* Wait until data received from the device */
 353         if ((ReturnCode = MassStore_WaitForDataReceived()) != PIPE_RWSTREAM_ERROR_NoError)
 354         {
 355                 Pipe_Freeze();
 356                 return ReturnCode;
 357         }
 358
 359         /* Read the returned sense data into the buffer */
 360         if ((ReturnCode = MassStore_SendReceiveData((uint8_t*)SensePtr)) != PIPE_RWSTREAM_ERROR_NoError)
 361         {
 362                 Pipe_Freeze();
 363                 return ReturnCode;
 364         }
 365
 366         /* Read in the returned CSW from the device */
 367         if ((ReturnCode = MassStore_GetReturnedStatus()) != PIPE_RWSTREAM_ERROR_NoError)
 368         {
 369                 Pipe_Freeze();
 370                 return ReturnCode;
 371         }
 372
 373         return PIPE_RWSTREAM_ERROR_NoError;
 374 }
 375
 376 /** Issues a SCSI Device Block Read command to the attached device, to read in one or more data blocks from the
 377  *  storage medium into a buffer.
 378  *
 379  *  \param LUNIndex      Index of the LUN inside the device the command is being addressed to
 380  *  \param BlockAddress  Start block address to read from
 381  *  \param Blocks        Number of blocks to read from the device
 382  *  \param BlockSize     Size in bytes of each block to read
 383  *  \param BufferPtr     Pointer to the buffer where the read data is to be written to
 384  *
 385  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 386  */
 387 uint8_t MassStore_ReadDeviceBlock(const uint8_t LUNIndex, const uint32_t BlockAddress,
 388                                   const uint8_t Blocks, const uint16_t BlockSize, void* BufferPtr)
 389 {
 390         uint8_t ReturnCode = PIPE_RWSTREAM_ERROR_NoError;
 391
 392         /* Create a CBW with a SCSI command to read in the given blocks from the device */
 393         SCSICommandBlock = (CommandBlockWrapper_t)
 394                 {
 395                         Header:
 396                                 {
 397                                         Signature:          CBW_SIGNATURE,
 398                                         Tag:                MassStore_Tag,
 399                                         DataTransferLength: ((uint32_t)Blocks * BlockSize),
 400                                         Flags:              COMMAND_DIRECTION_DATA_IN,
 401                                         LUN:                LUNIndex,
 402                                         SCSICommandLength:  10
 403                                 },
 404
 405                         SCSICommandData:
 406                                 {
 407                                         SCSI_CMD_READ_10,
 408                                         0x00,                   // Unused (control bits, all off)
 409                                         (BlockAddress >> 24),   // MSB of Block Address
 410                                         (BlockAddress >> 16),
 411                                         (BlockAddress >> 8),
 412                                         (BlockAddress & 0xFF),  // LSB of Block Address
 413                                         0x00,                   // Unused (reserved)
 414                                         0x00,                   // MSB of Total Blocks to Read
 415                                         Blocks,                 // LSB of Total Blocks to Read
 416                                         0x00                    // Unused (control)
 417                                 }
 418                 };
 419
 420         /* Send SCSI command to the attached device */
 421         MassStore_SendCommand();
 422
 423         /* Wait until data received from the device */
 424         if ((ReturnCode = MassStore_WaitForDataReceived()) != PIPE_RWSTREAM_ERROR_NoError)
 425         {
 426                 Pipe_Freeze();
 427                 return ReturnCode;
 428         }
 429
 430         /* Read the returned block data into the buffer */
 431         if ((ReturnCode = MassStore_SendReceiveData(BufferPtr)) != PIPE_RWSTREAM_ERROR_NoError)
 432         {
 433                 Pipe_Freeze();
 434                 return ReturnCode;
 435         }
 436
 437         /* Read in the returned CSW from the device */
 438         if ((ReturnCode = MassStore_GetReturnedStatus()) != PIPE_RWSTREAM_ERROR_NoError)
 439         {
 440                 Pipe_Freeze();
 441                 return ReturnCode;
 442         }
 443
 444         return PIPE_RWSTREAM_ERROR_NoError;
 445 }
 446
 447 /** Issues a SCSI Device Block Write command to the attached device, to write one or more data blocks to the
 448  *  storage medium from a buffer.
 449  *
 450  *  \param LUNIndex      Index of the LUN inside the device the command is being addressed to
 451  *  \param BlockAddress  Start block address to write to
 452  *  \param Blocks        Number of blocks to write to in the device
 453  *  \param BlockSize     Size in bytes of each block to write
 454  *  \param BufferPtr     Pointer to the buffer where the write data is to be sourced from
 455  *
 456  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 457  */
 458 uint8_t MassStore_WriteDeviceBlock(const uint8_t LUNIndex, const uint32_t BlockAddress,
 459                                    const uint8_t Blocks, const uint16_t BlockSize, void* BufferPtr)
 460 {
 461         uint8_t ReturnCode = PIPE_RWSTREAM_ERROR_NoError;
 462
 463         /* Create a CBW with a SCSI command to write the given blocks to the device */
 464         SCSICommandBlock = (CommandBlockWrapper_t)
 465                 {
 466                         Header:
 467                                 {
 468                                         Signature:          CBW_SIGNATURE,
 469                                         Tag:                MassStore_Tag,
 470                                         DataTransferLength: ((uint32_t)Blocks * BlockSize),
 471                                         Flags:              COMMAND_DIRECTION_DATA_OUT,
 472                                         LUN:                LUNIndex,
 473                                         SCSICommandLength:  10
 474                                 },
 475
 476                         SCSICommandData:
 477                                 {
 478                                         SCSI_CMD_WRITE_10,
 479                                         0x00,                   // Unused (control bits, all off)
 480                                         (BlockAddress >> 24),   // MSB of Block Address
 481                                         (BlockAddress >> 16),
 482                                         (BlockAddress >> 8),
 483                                         (BlockAddress & 0xFF),  // LSB of Block Address
 484                                         0x00,                   // Unused (reserved)
 485                                         0x00,                   // MSB of Total Blocks to Write
 486                                         Blocks,                 // LSB of Total Blocks to Write
 487                                         0x00                    // Unused (control)
 488                                 }
 489                 };
 490
 491         /* Send SCSI command to the attached device */
 492         MassStore_SendCommand();
 493
 494         /* Write the data to the device from the buffer */
 495         if ((ReturnCode = MassStore_SendReceiveData(BufferPtr)) != PIPE_RWSTREAM_ERROR_NoError)
 496         {
 497                 Pipe_Freeze();
 498                 return ReturnCode;
 499         }
 500
 501         /* Read in the returned CSW from the device */
 502         if ((ReturnCode = MassStore_GetReturnedStatus()) != PIPE_RWSTREAM_ERROR_NoError)
 503         {
 504                 Pipe_Freeze();
 505                 return ReturnCode;
 506         }
 507
 508         return PIPE_RWSTREAM_ERROR_NoError;
 509 }
 510
 511 /** Issues a SCSI Device Test Unit Ready command to the attached device, to determine if the device is ready to accept
 512  *  other commands.
 513  *
 514  *  \param LUNIndex      Index of the LUN inside the device the command is being addressed to
 515  *
 516  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 517  */
 518 uint8_t MassStore_TestUnitReady(const uint8_t LUNIndex)
 519 {
 520         uint8_t ReturnCode = PIPE_RWSTREAM_ERROR_NoError;
 521
 522         /* Create a CBW with a SCSI command to issue TEST UNIT READY command */
 523         SCSICommandBlock = (CommandBlockWrapper_t)
 524                 {
 525                         Header:
 526                                 {
 527                                         Signature:          CBW_SIGNATURE,
 528                                         Tag:                MassStore_Tag,
 529                                         DataTransferLength: 0,
 530                                         Flags:              COMMAND_DIRECTION_DATA_IN,
 531                                         LUN:                LUNIndex,
 532                                         SCSICommandLength:  6
 533                                 },
 534
 535                         SCSICommandData:
 536                                 {
 537                                         SCSI_CMD_TEST_UNIT_READY,
 538                                         0x00,                   // Reserved
 539                                         0x00,                   // Reserved
 540                                         0x00,                   // Reserved
 541                                         0x00,                   // Reserved
 542                                         0x00                    // Unused (control)
 543                                 }
 544                 };
 545
 546         /* Send SCSI command to the attached device */
 547         MassStore_SendCommand();
 548
 549         /* Read in the returned CSW from the device */
 550         if ((ReturnCode = MassStore_GetReturnedStatus()) != PIPE_RWSTREAM_ERROR_NoError)
 551         {
 552                 Pipe_Freeze();
 553                 return ReturnCode;
 554         }
 555
 556         return PIPE_RWSTREAM_ERROR_NoError;
 557 }
 558
 559 /** Issues a SCSI Device Read Capacity command to the attached device, to determine the capacity of the
 560  *  given Logical Unit within the device.
 561  *
 562  *  \param LUNIndex     Index of the LUN inside the device the command is being addressed to
 563  *  \param CapacityPtr  Device capacity structure where the capacity data is to be stored
 564  *
 565  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 566  */
 567 uint8_t MassStore_ReadCapacity(const uint8_t LUNIndex, SCSI_Capacity_t* const CapacityPtr)
 568 {
 569         uint8_t ReturnCode = PIPE_RWSTREAM_ERROR_NoError;
 570
 571         /* Create a CBW with a SCSI command to issue READ CAPACITY command */
 572         SCSICommandBlock = (CommandBlockWrapper_t)
 573                 {
 574                         Header:
 575                                 {
 576                                         Signature:          CBW_SIGNATURE,
 577                                         Tag:                MassStore_Tag,
 578                                         DataTransferLength: 8,
 579                                         Flags:              COMMAND_DIRECTION_DATA_IN,
 580                                         LUN:                LUNIndex,
 581                                         SCSICommandLength:  10
 582                                 },
 583
 584                         SCSICommandData:
 585                                 {
 586                                         SCSI_CMD_READ_CAPACITY_10,
 587                                         0x00,                   // Reserved
 588                                         0x00,                   // MSB of Logical block address
 589                                         0x00,
 590                                         0x00,
 591                                         0x00,                   // LSB of Logical block address
 592                                         0x00,                   // Reserved
 593                                         0x00,                   // Reserved
 594                                         0x00,                   // Partial Medium Indicator
 595                                         0x00                    // Unused (control)
 596                                 }
 597                 };
 598
 599         /* Send SCSI command to the attached device */
 600         MassStore_SendCommand();
 601
 602         /* Wait until data received from the device */
 603         if ((ReturnCode = MassStore_WaitForDataReceived()) != PIPE_RWSTREAM_ERROR_NoError)
 604         {
 605                 Pipe_Freeze();
 606                 return ReturnCode;
 607         }
 608
 609         /* Read the returned capacity data into the buffer */
 610         if ((ReturnCode = MassStore_SendReceiveData(CapacityPtr)) != PIPE_RWSTREAM_ERROR_NoError)
 611         {
 612                 Pipe_Freeze();
 613                 return ReturnCode;
 614         }
 615
 616         /* Endian-correct the read data */
 617         CapacityPtr->Blocks    = SwapEndian_32(CapacityPtr->Blocks);
 618         CapacityPtr->BlockSize = SwapEndian_32(CapacityPtr->BlockSize);
 619
 620         /* Read in the returned CSW from the device */
 621         if ((ReturnCode = MassStore_GetReturnedStatus()) != PIPE_RWSTREAM_ERROR_NoError)
 622         {
 623                 Pipe_Freeze();
 624                 return ReturnCode;
 625         }
 626
 627         return PIPE_RWSTREAM_ERROR_NoError;
 628 }
 629
 630 /** Issues a SCSI Device Prevent/Allow Medium Removal command to the attached device, to lock the physical media from
 631  *  being removed. This is a legacy command for SCSI disks with removable storage (such as ZIP disks), but should still
 632  *  be issued before the first read or write command is sent.
 633  *
 634  *  \param LUNIndex        Index of the LUN inside the device the command is being addressed to
 635  *  \param PreventRemoval  Whether or not the LUN media should be locked to prevent removal or not
 636  *
 637  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 638  */
 639 uint8_t MassStore_PreventAllowMediumRemoval(const uint8_t LUNIndex, const bool PreventRemoval)
 640 {
 641         uint8_t ReturnCode = PIPE_RWSTREAM_ERROR_NoError;
 642
 643         /* Create a CBW with a SCSI command to issue PREVENT ALLOW MEDIUM REMOVAL command */
 644         SCSICommandBlock = (CommandBlockWrapper_t)
 645                 {
 646                         Header:
 647                                 {
 648                                         Signature:          CBW_SIGNATURE,
 649                                         Tag:                MassStore_Tag,
 650                                         DataTransferLength: 0,
 651                                         Flags:              COMMAND_DIRECTION_DATA_OUT,
 652                                         LUN:                LUNIndex,
 653                                         SCSICommandLength:  6
 654                                 },
 655
 656                         SCSICommandData:
 657                                 {
 658                                         SCSI_CMD_PREVENT_ALLOW_MEDIUM_REMOVAL,
 659                                         0x00,                   // Reserved
 660                                         0x00,                   // Reserved
 661                                         PreventRemoval,         // Prevent flag
 662                                         0x00,                   // Reserved
 663                                         0x00                    // Unused (control)
 664                                 }
 665                 };
 666
 667         /* Send SCSI command to the attached device */
 668         MassStore_SendCommand();
 669
 670         /* Read in the returned CSW from the device */
 671         if ((ReturnCode = MassStore_GetReturnedStatus()) != PIPE_RWSTREAM_ERROR_NoError)
 672         {
 673                 Pipe_Freeze();
 674                 return ReturnCode;
 675         }
 676
 677         return PIPE_RWSTREAM_ERROR_NoError;
 678 }