protocol/lufa/LUFA-git/Demos/Host/LowLevel/MassStorageHost/Lib/MassStoreCommands.c

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2014.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2014  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all 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 disclaims 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 /** Current Tag value used in issued CBWs to the device. This is automatically incremented
  54  *  each time a command is sent, and is not externally accessible.
  55  */
  56 static uint32_t MassStore_Tag = 1;
  57
  58
  59 /** Routine to send the current CBW to the device, and increment the Tag value as needed.
  60  *
  61  *  \param[in] SCSICommandBlock  Pointer to a SCSI command block structure to send to the attached device
  62  *  \param[in,out] BufferPtr     Pointer to a buffer for the data to send or receive to/from the device, or NULL if no data
  63  *
  64  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
  65  */
  66 static uint8_t MassStore_SendCommand(MS_CommandBlockWrapper_t* const SCSICommandBlock,
  67                                      void* BufferPtr)
  68 {
  69         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
  70
  71         /* Wrap Tag value when invalid - MS class defines tag values of 0 and 0xFFFFFFFF to be invalid */
  72         if (++MassStore_Tag == 0xFFFFFFFF)
  73           MassStore_Tag = 1;
  74
  75         /* Each transmission should have a unique tag value, increment before use */
  76         SCSICommandBlock->Tag = MassStore_Tag;
  77
  78         /* Select the OUT data pipe for CBW transmission */
  79         Pipe_SelectPipe(MASS_STORE_DATA_OUT_PIPE);
  80         Pipe_Unfreeze();
  81
  82         /* Write the CBW command to the OUT pipe */
  83         if ((ErrorCode = Pipe_Write_Stream_LE(SCSICommandBlock, sizeof(MS_CommandBlockWrapper_t), NULL)) !=
  84                                               PIPE_RWSTREAM_NoError)
  85         {
  86                 Pipe_Freeze();
  87                 return ErrorCode;
  88         }
  89
  90         /* Send the data in the OUT pipe to the attached device */
  91         Pipe_ClearOUT();
  92
  93         /* Wait until command has been sent */
  94         Pipe_WaitUntilReady();
  95
  96         /* Freeze pipe after use */
  97         Pipe_Freeze();
  98
  99         if (BufferPtr != NULL)
 100         {
 101                 /* Transfer the requested data (if any) to or from the device */
 102                 ErrorCode = MassStore_SendReceiveData(SCSICommandBlock, (void*)BufferPtr);
 103
 104                 /* Only fail completely if the transfer fails without a STALL, as a logical STALL can be recovered from */
 105                 if ((ErrorCode != PIPE_RWSTREAM_NoError) && (ErrorCode != PIPE_RWSTREAM_PipeStalled))
 106                 {
 107                         Pipe_Freeze();
 108                         return ErrorCode;
 109                 }
 110         }
 111
 112         /* Retrieve the returned SCSI status from the device */
 113         MS_CommandStatusWrapper_t SCSIStatusBlock;
 114         return MassStore_GetReturnedStatus(&SCSIStatusBlock);
 115 }
 116
 117 /** Waits until the attached device is ready to accept data following a CBW, checking
 118  *  to ensure that the device has not stalled the transaction.
 119  *
 120  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 121  */
 122 static uint8_t MassStore_WaitForDataReceived(void)
 123 {
 124         uint16_t TimeoutMSRem        = COMMAND_DATA_TIMEOUT_MS;
 125         uint16_t PreviousFrameNumber = USB_Host_GetFrameNumber();
 126
 127         /* Select the IN data pipe for data reception */
 128         Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 129         Pipe_Unfreeze();
 130
 131         /* Wait until data received in the IN pipe */
 132         while (!(Pipe_IsINReceived()))
 133         {
 134                 uint16_t CurrentFrameNumber = USB_Host_GetFrameNumber();
 135
 136                 /* Check to see if a new frame has been issued (1ms elapsed) */
 137                 if (CurrentFrameNumber != PreviousFrameNumber)
 138                 {
 139                         /* Save the new frame number and decrement the timeout period */
 140                         PreviousFrameNumber = CurrentFrameNumber;
 141                         TimeoutMSRem--;
 142
 143                         /* Check to see if the timeout period for the command has elapsed */
 144                         if (!(TimeoutMSRem))
 145                           return PIPE_RWSTREAM_Timeout;
 146                 }
 147
 148                 Pipe_Freeze();
 149                 Pipe_SelectPipe(MASS_STORE_DATA_OUT_PIPE);
 150                 Pipe_Unfreeze();
 151
 152                 /* Check if pipe stalled (command failed by device) */
 153                 if (Pipe_IsStalled())
 154                 {
 155                         /* Clear the stall condition on the OUT pipe */
 156                         USB_Host_ClearEndpointStall(Pipe_GetBoundEndpointAddress());
 157
 158                         return PIPE_RWSTREAM_PipeStalled;
 159                 }
 160
 161                 Pipe_Freeze();
 162                 Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 163                 Pipe_Unfreeze();
 164
 165                 /* Check if pipe stalled (command failed by device) */
 166                 if (Pipe_IsStalled())
 167                 {
 168                         /* Clear the stall condition on the IN pipe */
 169                         USB_Host_ClearEndpointStall(Pipe_GetBoundEndpointAddress());
 170
 171                         return PIPE_RWSTREAM_PipeStalled;
 172                 }
 173
 174                 /* Check to see if the device was disconnected, if so exit function */
 175                 if (USB_HostState == HOST_STATE_Unattached)
 176                   return PIPE_RWSTREAM_DeviceDisconnected;
 177         };
 178
 179         Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 180         Pipe_Freeze();
 181
 182         Pipe_SelectPipe(MASS_STORE_DATA_OUT_PIPE);
 183         Pipe_Freeze();
 184
 185         return PIPE_RWSTREAM_NoError;
 186 }
 187
 188 /** Sends or receives the transaction's data stage to or from the attached device, reading or
 189  *  writing to the nominated buffer.
 190  *
 191  *  \param[in] SCSICommandBlock  Pointer to a SCSI command block structure being sent to the attached device
 192  *  \param[in,out]  BufferPtr    Pointer to the data buffer to read from or write to
 193  *
 194  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum
 195  */
 196 static uint8_t MassStore_SendReceiveData(MS_CommandBlockWrapper_t* const SCSICommandBlock,
 197                                          void* BufferPtr)
 198 {
 199         uint8_t  ErrorCode = PIPE_RWSTREAM_NoError;
 200         uint16_t BytesRem  = SCSICommandBlock->DataTransferLength;
 201
 202         /* Check the direction of the SCSI command data stage */
 203         if (SCSICommandBlock->Flags & MS_COMMAND_DIR_DATA_IN)
 204         {
 205                 /* Wait until the device has replied with some data */
 206                 if ((ErrorCode = MassStore_WaitForDataReceived()) != PIPE_RWSTREAM_NoError)
 207                   return ErrorCode;
 208
 209                 /* Select the IN data pipe for data reception */
 210                 Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 211                 Pipe_Unfreeze();
 212
 213                 /* Read in the block data from the pipe */
 214                 if ((ErrorCode = Pipe_Read_Stream_LE(BufferPtr, BytesRem, NULL)) != PIPE_RWSTREAM_NoError)
 215                   return ErrorCode;
 216
 217                 /* Acknowledge the packet */
 218                 Pipe_ClearIN();
 219         }
 220         else
 221         {
 222                 /* Select the OUT data pipe for data transmission */
 223                 Pipe_SelectPipe(MASS_STORE_DATA_OUT_PIPE);
 224                 Pipe_Unfreeze();
 225
 226                 /* Write the block data to the pipe */
 227                 if ((ErrorCode = Pipe_Write_Stream_LE(BufferPtr, BytesRem, NULL)) != PIPE_RWSTREAM_NoError)
 228                   return ErrorCode;
 229
 230                 /* Acknowledge the packet */
 231                 Pipe_ClearOUT();
 232
 233                 while (!(Pipe_IsOUTReady()))
 234                 {
 235                         if (USB_HostState == HOST_STATE_Unattached)
 236                           return PIPE_RWSTREAM_DeviceDisconnected;
 237                 }
 238         }
 239
 240         /* Freeze used pipe after use */
 241         Pipe_Freeze();
 242
 243         return PIPE_RWSTREAM_NoError;
 244 }
 245
 246 /** Routine to receive the current CSW from the device.
 247  *
 248  *  \param[out] SCSICommandStatus  Pointer to a destination where the returned status data should be stored
 249  *
 250  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 251  */
 252 static uint8_t MassStore_GetReturnedStatus(MS_CommandStatusWrapper_t* const SCSICommandStatus)
 253 {
 254         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
 255
 256         /* If an error in the command occurred, abort */
 257         if ((ErrorCode = MassStore_WaitForDataReceived()) != PIPE_RWSTREAM_NoError)
 258           return ErrorCode;
 259
 260         /* Select the IN data pipe for data reception */
 261         Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 262         Pipe_Unfreeze();
 263
 264         /* Load in the CSW from the attached device */
 265         if ((ErrorCode = Pipe_Read_Stream_LE(SCSICommandStatus, sizeof(MS_CommandStatusWrapper_t), NULL)) !=
 266                                              PIPE_RWSTREAM_NoError)
 267         {
 268                 return ErrorCode;
 269         }
 270
 271         /* Clear the data ready for next reception */
 272         Pipe_ClearIN();
 273
 274         /* Freeze the IN pipe after use */
 275         Pipe_Freeze();
 276
 277         /* Check to see if command failed */
 278         if (SCSICommandStatus->Status != MS_SCSI_COMMAND_Pass)
 279           ErrorCode = MASS_STORE_SCSI_COMMAND_FAILED;
 280
 281         return ErrorCode;
 282 }
 283
 284 /** Issues a Mass Storage class specific request to reset the attached device's Mass Storage interface,
 285  *  readying the device for the next CBW. The Data endpoints are cleared of any STALL condition once this
 286  *  command completes successfully.
 287  *
 288  *  \return A value from the USB_Host_SendControlErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 289  */
 290 uint8_t MassStore_MassStorageReset(void)
 291 {
 292         uint8_t ErrorCode;
 293
 294         USB_ControlRequest = (USB_Request_Header_t)
 295                 {
 296                         .bmRequestType = (REQDIR_HOSTTODEVICE | REQTYPE_CLASS | REQREC_INTERFACE),
 297                         .bRequest      = MS_REQ_MassStorageReset,
 298                         .wValue        = 0,
 299                         .wIndex        = 0,
 300                         .wLength       = 0,
 301                 };
 302
 303         /* Select the control pipe for the request transfer */
 304         Pipe_SelectPipe(PIPE_CONTROLPIPE);
 305
 306         if ((ErrorCode = USB_Host_SendControlRequest(NULL)) != HOST_SENDCONTROL_Successful)
 307           return ErrorCode;
 308
 309         /* Select first data pipe to clear STALL condition if one exists */
 310         Pipe_SelectPipe(MASS_STORE_DATA_IN_PIPE);
 311
 312         if ((ErrorCode = USB_Host_ClearEndpointStall(Pipe_GetBoundEndpointAddress())) != HOST_SENDCONTROL_Successful)
 313           return ErrorCode;
 314
 315         /* Select second data pipe to clear STALL condition if one exists */
 316         Pipe_SelectPipe(MASS_STORE_DATA_OUT_PIPE);
 317
 318         if ((ErrorCode = USB_Host_ClearEndpointStall(Pipe_GetBoundEndpointAddress())) != HOST_SENDCONTROL_Successful)
 319           return ErrorCode;
 320
 321         return HOST_SENDCONTROL_Successful;
 322 }
 323
 324 /** Issues a Mass Storage class specific request to determine the index of the highest numbered Logical
 325  *  Unit in the attached device.
 326  *
 327  *  \note Some devices do not support this request, and will STALL it when issued. To get around this,
 328  *        on unsupported devices the max LUN index will be reported as zero and no error will be returned
 329  *        if the device STALLs the request.
 330  *
 331  *  \param[out] MaxLUNIndex  Pointer to the location that the maximum LUN index value should be stored
 332  *
 333  *  \return A value from the USB_Host_SendControlErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 334  */
 335 uint8_t MassStore_GetMaxLUN(uint8_t* const MaxLUNIndex)
 336 {
 337         uint8_t ErrorCode;
 338
 339         USB_ControlRequest = (USB_Request_Header_t)
 340                 {
 341                         .bmRequestType = (REQDIR_DEVICETOHOST | REQTYPE_CLASS | REQREC_INTERFACE),
 342                         .bRequest      = MS_REQ_GetMaxLUN,
 343                         .wValue        = 0,
 344                         .wIndex        = 0,
 345                         .wLength       = 1,
 346                 };
 347
 348         /* Select the control pipe for the request transfer */
 349         Pipe_SelectPipe(PIPE_CONTROLPIPE);
 350
 351         if ((ErrorCode = USB_Host_SendControlRequest(MaxLUNIndex)) == HOST_SENDCONTROL_SetupStalled)
 352         {
 353                 /* Clear the pipe stall */
 354                 Pipe_ClearStall();
 355
 356                 /* Some faulty Mass Storage devices don't implement the GET_MAX_LUN request, so assume a single LUN */
 357                 *MaxLUNIndex = 0;
 358
 359                 /* Clear the error, and pretend the request executed correctly if the device STALLed it */
 360                 ErrorCode = HOST_SENDCONTROL_Successful;
 361         }
 362
 363         return ErrorCode;
 364 }
 365
 366 /** Issues a SCSI Inquiry command to the attached device, to determine the device's information. This
 367  *  gives information on the device's capabilities.
 368  *
 369  *  \param[in] LUNIndex    Index of the LUN inside the device the command is being addressed to
 370  *  \param[out] InquiryPtr  Pointer to the inquiry data structure where the inquiry data from the device is to be stored
 371  *
 372  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 373  */
 374 uint8_t MassStore_Inquiry(const uint8_t LUNIndex,
 375                           SCSI_Inquiry_Response_t* const InquiryPtr)
 376 {
 377         /* Create a CBW with a SCSI command to issue INQUIRY command */
 378         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 379                 {
 380                         .Signature          = MS_CBW_SIGNATURE,
 381                         .DataTransferLength = sizeof(SCSI_Inquiry_Response_t),
 382                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 383                         .LUN                = LUNIndex,
 384                         .SCSICommandLength  = 6,
 385                         .SCSICommandData    =
 386                                 {
 387                                         SCSI_CMD_INQUIRY,
 388                                         0x00,                   // Reserved
 389                                         0x00,                   // Reserved
 390                                         0x00,                   // Reserved
 391                                         sizeof(SCSI_Inquiry_Response_t), // Allocation Length
 392                                         0x00                    // Unused (control)
 393                                 }
 394                 };
 395
 396         /* Send the command and any data to the attached device */
 397         return MassStore_SendCommand(&SCSICommandBlock, InquiryPtr);
 398 }
 399
 400 /** Issues a SCSI Request Sense command to the attached device, to determine the current SCSI sense information. This
 401  *  gives error codes for the last issued SCSI command to the device.
 402  *
 403  *  \param[in] LUNIndex   Index of the LUN inside the device the command is being addressed to
 404  *  \param[out] SensePtr  Pointer to the sense data structure where the sense data from the device is to be stored
 405  *
 406  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 407  */
 408 uint8_t MassStore_RequestSense(const uint8_t LUNIndex,
 409                                SCSI_Request_Sense_Response_t* const SensePtr)
 410 {
 411         /* Create a CBW with a SCSI command to issue REQUEST SENSE command */
 412         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 413                 {
 414                         .Signature          = MS_CBW_SIGNATURE,
 415                         .DataTransferLength = sizeof(SCSI_Request_Sense_Response_t),
 416                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 417                         .LUN                = LUNIndex,
 418                         .SCSICommandLength  = 6,
 419                         .SCSICommandData =
 420                                 {
 421                                         SCSI_CMD_REQUEST_SENSE,
 422                                         0x00,                   // Reserved
 423                                         0x00,                   // Reserved
 424                                         0x00,                   // Reserved
 425                                         sizeof(SCSI_Request_Sense_Response_t), // Allocation Length
 426                                         0x00                    // Unused (control)
 427                                 }
 428                 };
 429
 430         /* Send the command and any data to the attached device */
 431         return MassStore_SendCommand(&SCSICommandBlock, SensePtr);
 432 }
 433
 434 /** Issues a SCSI Device Block Read command to the attached device, to read in one or more data blocks from the
 435  *  storage medium into a buffer.
 436  *
 437  *  \param[in] LUNIndex      Index of the LUN inside the device the command is being addressed to
 438  *  \param[in] BlockAddress  Start block address to read from
 439  *  \param[in] Blocks        Number of blocks to read from the device
 440  *  \param[in] BlockSize     Size in bytes of each block to read
 441  *  \param[out] BufferPtr    Pointer to the buffer where the read data is to be written to
 442  *
 443  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 444  */
 445 uint8_t MassStore_ReadDeviceBlock(const uint8_t LUNIndex,
 446                                   const uint32_t BlockAddress,
 447                                   const uint8_t Blocks,
 448                                   const uint16_t BlockSize,
 449                                   void* BufferPtr)
 450 {
 451         /* Create a CBW with a SCSI command to read in the given blocks from the device */
 452         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 453                 {
 454                         .Signature          = MS_CBW_SIGNATURE,
 455                         .DataTransferLength = ((uint32_t)Blocks * BlockSize),
 456                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 457                         .LUN                = LUNIndex,
 458                         .SCSICommandLength  = 10,
 459                         .SCSICommandData    =
 460                                 {
 461                                         SCSI_CMD_READ_10,
 462                                         0x00,                   // Unused (control bits, all off)
 463                                         (BlockAddress >> 24),   // MSB of Block Address
 464                                         (BlockAddress >> 16),
 465                                         (BlockAddress >> 8),
 466                                         (BlockAddress & 0xFF),  // LSB of Block Address
 467                                         0x00,                   // Reserved
 468                                         0x00,                   // MSB of Total Blocks to Read
 469                                         Blocks,                 // LSB of Total Blocks to Read
 470                                         0x00                    // Unused (control)
 471                                 }
 472                 };
 473
 474         /* Send the command and any data to the attached device */
 475         return MassStore_SendCommand(&SCSICommandBlock, BufferPtr);
 476 }
 477
 478 /** Issues a SCSI Device Block Write command to the attached device, to write one or more data blocks to the
 479  *  storage medium from a buffer.
 480  *
 481  *  \param[in] LUNIndex      Index of the LUN inside the device the command is being addressed to
 482  *  \param[in] BlockAddress  Start block address to write to
 483  *  \param[in] Blocks        Number of blocks to write to in the device
 484  *  \param[in] BlockSize     Size in bytes of each block to write
 485  *  \param[in] BufferPtr     Pointer to the buffer where the write data is to be sourced from
 486  *
 487  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 488  */
 489 uint8_t MassStore_WriteDeviceBlock(const uint8_t LUNIndex,
 490                                    const uint32_t BlockAddress,
 491                                    const uint8_t Blocks,
 492                                    const uint16_t BlockSize,
 493                                    void* BufferPtr)
 494 {
 495         /* Create a CBW with a SCSI command to write the given blocks to the device */
 496         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 497                 {
 498                         .Signature          = MS_CBW_SIGNATURE,
 499                         .DataTransferLength = ((uint32_t)Blocks * BlockSize),
 500                         .Flags              = MS_COMMAND_DIR_DATA_OUT,
 501                         .LUN                = LUNIndex,
 502                         .SCSICommandLength  = 10,
 503                         .SCSICommandData    =
 504                                 {
 505                                         SCSI_CMD_WRITE_10,
 506                                         0x00,                   // Unused (control bits, all off)
 507                                         (BlockAddress >> 24),   // MSB of Block Address
 508                                         (BlockAddress >> 16),
 509                                         (BlockAddress >> 8),
 510                                         (BlockAddress & 0xFF),  // LSB of Block Address
 511                                         0x00,                   // Unused (reserved)
 512                                         0x00,                   // MSB of Total Blocks to Write
 513                                         Blocks,                 // LSB of Total Blocks to Write
 514                                         0x00                    // Unused (control)
 515                                 }
 516                 };
 517
 518         /* Send the command and any data to the attached device */
 519         return MassStore_SendCommand(&SCSICommandBlock, BufferPtr);
 520 }
 521
 522 /** Issues a SCSI Device Test Unit Ready command to the attached device, to determine if the device is ready to accept
 523  *  other commands.
 524  *
 525  *  \param[in] LUNIndex      Index of the LUN inside the device the command is being addressed to
 526  *
 527  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 528  */
 529 uint8_t MassStore_TestUnitReady(const uint8_t LUNIndex)
 530 {
 531         /* Create a CBW with a SCSI command to issue TEST UNIT READY command */
 532         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 533                 {
 534                         .Signature          = MS_CBW_SIGNATURE,
 535                         .DataTransferLength = 0,
 536                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 537                         .LUN                = LUNIndex,
 538                         .SCSICommandLength  = 6,
 539                         .SCSICommandData    =
 540                                 {
 541                                         SCSI_CMD_TEST_UNIT_READY,
 542                                         0x00,                   // Reserved
 543                                         0x00,                   // Reserved
 544                                         0x00,                   // Reserved
 545                                         0x00,                   // Reserved
 546                                         0x00                    // Unused (control)
 547                                 }
 548                 };
 549
 550         /* Send the command and any data to the attached device */
 551         return MassStore_SendCommand(&SCSICommandBlock, NULL);
 552 }
 553
 554 /** Issues a SCSI Device Read Capacity command to the attached device, to determine the capacity of the
 555  *  given Logical Unit within the device.
 556  *
 557  *  \param[in] LUNIndex      Index of the LUN inside the device the command is being addressed to
 558  *  \param[out] CapacityPtr  Device capacity structure where the capacity data is to be stored
 559  *
 560  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 561  */
 562 uint8_t MassStore_ReadCapacity(const uint8_t LUNIndex,
 563                                SCSI_Capacity_t* const CapacityPtr)
 564 {
 565         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
 566
 567         /* Create a CBW with a SCSI command to issue READ CAPACITY command */
 568         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 569                 {
 570                         .Signature          = MS_CBW_SIGNATURE,
 571                         .DataTransferLength = sizeof(SCSI_Capacity_t),
 572                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 573                         .LUN                = LUNIndex,
 574                         .SCSICommandLength  = 10,
 575                         .SCSICommandData    =
 576                                 {
 577                                         SCSI_CMD_READ_CAPACITY_10,
 578                                         0x00,                   // Reserved
 579                                         0x00,                   // MSB of Logical block address
 580                                         0x00,
 581                                         0x00,
 582                                         0x00,                   // LSB of Logical block address
 583                                         0x00,                   // Reserved
 584                                         0x00,                   // Reserved
 585                                         0x00,                   // Partial Medium Indicator
 586                                         0x00                    // Unused (control)
 587                                 }
 588                 };
 589
 590         /* Send the command and any data to the attached device */
 591         if ((ErrorCode = MassStore_SendCommand(&SCSICommandBlock, CapacityPtr)) != PIPE_RWSTREAM_NoError)
 592           return ErrorCode;
 593
 594         /* Endian-correct the read data */
 595         CapacityPtr->Blocks    = SwapEndian_32(CapacityPtr->Blocks);
 596         CapacityPtr->BlockSize = SwapEndian_32(CapacityPtr->BlockSize);
 597
 598         return ErrorCode;
 599 }
 600
 601 /** Issues a SCSI Device Prevent/Allow Medium Removal command to the attached device, to lock the physical media from
 602  *  being removed. This is a legacy command for SCSI disks with removable storage (such as ZIP disks), but should still
 603  *  be issued before the first read or write command is sent.
 604  *
 605  *  \param[in] LUNIndex        Index of the LUN inside the device the command is being addressed to
 606  *  \param[in] PreventRemoval  Whether or not the LUN media should be locked to prevent removal or not
 607  *
 608  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 609  */
 610 uint8_t MassStore_PreventAllowMediumRemoval(const uint8_t LUNIndex,
 611                                             const bool PreventRemoval)
 612 {
 613         /* Create a CBW with a SCSI command to issue PREVENT ALLOW MEDIUM REMOVAL command */
 614         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 615                 {
 616                         .Signature          = MS_CBW_SIGNATURE,
 617                         .DataTransferLength = 0,
 618                         .Flags              = MS_COMMAND_DIR_DATA_OUT,
 619                         .LUN                = LUNIndex,
 620                         .SCSICommandLength  = 6,
 621                         .SCSICommandData    =
 622                                 {
 623                                         SCSI_CMD_PREVENT_ALLOW_MEDIUM_REMOVAL,
 624                                         0x00,                   // Reserved
 625                                         0x00,                   // Reserved
 626                                         PreventRemoval,         // Prevent flag
 627                                         0x00,                   // Reserved
 628                                         0x00                    // Unused (control)
 629                                 }
 630                 };
 631
 632         /* Send the command and any data to the attached device */
 633         return MassStore_SendCommand(&SCSICommandBlock, NULL);
 634 }
 635