Demos/Host/LowLevel/MassStorageHost/Lib/MassStoreCommands.c

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