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         /* Each transmission should have a unique tag value, increment before use */
  72         SCSICommandBlock->Tag = ++MassStore_Tag;
  73
  74         /* Wrap Tag value when invalid - MS class defines tag values of 0 and 0xFFFFFFFF to be invalid */
  75         if (MassStore_Tag == 0xFFFFFFFF)
  76           MassStore_Tag = 1;
  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 */
  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_ClearPipeStall(MASS_STORE_DATA_OUT_PIPE);
 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_ClearPipeStall(MASS_STORE_DATA_IN_PIPE);
 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.
 278  *
 279  *  \return A value from the USB_Host_SendControlErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 280  */
 281 uint8_t MassStore_MassStorageReset(void)
 282 {
 283         USB_ControlRequest = (USB_Request_Header_t)
 284                 {
 285                         .bmRequestType = (REQDIR_HOSTTODEVICE | REQTYPE_CLASS | REQREC_INTERFACE),
 286                         .bRequest      = MS_REQ_MassStorageReset,
 287                         .wValue        = 0,
 288                         .wIndex        = 0,
 289                         .wLength       = 0,
 290                 };
 291
 292         /* Select the control pipe for the request transfer */
 293         Pipe_SelectPipe(PIPE_CONTROLPIPE);
 294
 295         return USB_Host_SendControlRequest(NULL);
 296 }
 297
 298 /** Issues a Mass Storage class specific request to determine the index of the highest numbered Logical
 299  *  Unit in the attached device.
 300  *
 301  *  \note Some devices do not support this request, and will STALL it when issued. To get around this,
 302  *        on unsupported devices the max LUN index will be reported as zero and no error will be returned
 303  *        if the device STALLs the request.
 304  *
 305  *  \param[out] MaxLUNIndex  Pointer to the location that the maximum LUN index value should be stored
 306  *
 307  *  \return A value from the USB_Host_SendControlErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 308  */
 309 uint8_t MassStore_GetMaxLUN(uint8_t* const MaxLUNIndex)
 310 {
 311         uint8_t ErrorCode = HOST_SENDCONTROL_Successful;
 312
 313         USB_ControlRequest = (USB_Request_Header_t)
 314                 {
 315                         .bmRequestType = (REQDIR_DEVICETOHOST | REQTYPE_CLASS | REQREC_INTERFACE),
 316                         .bRequest      = MS_REQ_GetMaxLUN,
 317                         .wValue        = 0,
 318                         .wIndex        = 0,
 319                         .wLength       = 1,
 320                 };
 321
 322         /* Select the control pipe for the request transfer */
 323         Pipe_SelectPipe(PIPE_CONTROLPIPE);
 324
 325         if ((ErrorCode = USB_Host_SendControlRequest(MaxLUNIndex)) == HOST_SENDCONTROL_SetupStalled)
 326         {
 327                 /* Clear the pipe stall */
 328                 Pipe_ClearStall();
 329
 330                 /* Some faulty Mass Storage devices don't implement the GET_MAX_LUN request, so assume a single LUN */
 331                 *MaxLUNIndex = 0;
 332
 333                 /* Clear the error, and pretend the request executed correctly if the device STALLed it */
 334                 ErrorCode = HOST_SENDCONTROL_Successful;
 335         }
 336
 337         return ErrorCode;
 338 }
 339
 340 /** Issues a SCSI Inquiry command to the attached device, to determine the device's information. This
 341  *  gives information on the device's capabilities.
 342  *
 343  *  \param[in] LUNIndex    Index of the LUN inside the device the command is being addressed to
 344  *  \param[out] InquiryPtr  Pointer to the inquiry data structure where the inquiry data from the device is to be stored
 345  *
 346  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 347  */
 348 uint8_t MassStore_Inquiry(const uint8_t LUNIndex,
 349                           SCSI_Inquiry_Response_t* const InquiryPtr)
 350 {
 351         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
 352
 353         /* Create a CBW with a SCSI command to issue INQUIRY command */
 354         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 355                 {
 356                         .Signature          = MS_CBW_SIGNATURE,
 357                         .DataTransferLength = sizeof(SCSI_Inquiry_Response_t),
 358                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 359                         .LUN                = LUNIndex,
 360                         .SCSICommandLength  = 6,
 361                         .SCSICommandData    =
 362                                 {
 363                                         SCSI_CMD_INQUIRY,
 364                                         0x00,                   // Reserved
 365                                         0x00,                   // Reserved
 366                                         0x00,                   // Reserved
 367                                         sizeof(SCSI_Inquiry_Response_t), // Allocation Length
 368                                         0x00                    // Unused (control)
 369                                 }
 370                 };
 371
 372         MS_CommandStatusWrapper_t SCSICommandStatus;
 373
 374         /* Send the command and any data to the attached device */
 375         if ((ErrorCode = MassStore_SendCommand(&SCSICommandBlock, InquiryPtr)) != PIPE_RWSTREAM_NoError)
 376         {
 377                 Pipe_Freeze();
 378                 return ErrorCode;
 379         }
 380
 381         /* Retrieve status information from the attached device */
 382         if ((ErrorCode = MassStore_GetReturnedStatus(&SCSICommandStatus)) != PIPE_RWSTREAM_NoError)
 383         {
 384                 Pipe_Freeze();
 385                 return ErrorCode;
 386         }
 387
 388         return ErrorCode;
 389 }
 390
 391 /** Issues a SCSI Request Sense command to the attached device, to determine the current SCSI sense information. This
 392  *  gives error codes for the last issued SCSI command to the device.
 393  *
 394  *  \param[in] LUNIndex   Index of the LUN inside the device the command is being addressed to
 395  *  \param[out] SensePtr  Pointer to the sense data structure where the sense data from the device is to be stored
 396  *
 397  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 398  */
 399 uint8_t MassStore_RequestSense(const uint8_t LUNIndex,
 400                                SCSI_Request_Sense_Response_t* const SensePtr)
 401 {
 402         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
 403
 404         /* Create a CBW with a SCSI command to issue REQUEST SENSE command */
 405         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 406                 {
 407                         .Signature          = MS_CBW_SIGNATURE,
 408                         .DataTransferLength = sizeof(SCSI_Request_Sense_Response_t),
 409                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 410                         .LUN                = LUNIndex,
 411                         .SCSICommandLength  = 6,
 412                         .SCSICommandData =
 413                                 {
 414                                         SCSI_CMD_REQUEST_SENSE,
 415                                         0x00,                   // Reserved
 416                                         0x00,                   // Reserved
 417                                         0x00,                   // Reserved
 418                                         sizeof(SCSI_Request_Sense_Response_t), // Allocation Length
 419                                         0x00                    // Unused (control)
 420                                 }
 421                 };
 422
 423         MS_CommandStatusWrapper_t SCSICommandStatus;
 424
 425         /* Send the command and any data to the attached device */
 426         if ((ErrorCode = MassStore_SendCommand(&SCSICommandBlock, SensePtr)) != PIPE_RWSTREAM_NoError)
 427         {
 428                 Pipe_Freeze();
 429                 return ErrorCode;
 430         }
 431
 432         /* Retrieve status information from the attached device */
 433         if ((ErrorCode = MassStore_GetReturnedStatus(&SCSICommandStatus)) != PIPE_RWSTREAM_NoError)
 434         {
 435                 Pipe_Freeze();
 436                 return ErrorCode;
 437         }
 438
 439         return ErrorCode;
 440 }
 441
 442 /** Issues a SCSI Device Block Read command to the attached device, to read in one or more data blocks from the
 443  *  storage medium into a buffer.
 444  *
 445  *  \param[in] LUNIndex      Index of the LUN inside the device the command is being addressed to
 446  *  \param[in] BlockAddress  Start block address to read from
 447  *  \param[in] Blocks        Number of blocks to read from the device
 448  *  \param[in] BlockSize     Size in bytes of each block to read
 449  *  \param[out] BufferPtr    Pointer to the buffer where the read data is to be written to
 450  *
 451  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 452  */
 453 uint8_t MassStore_ReadDeviceBlock(const uint8_t LUNIndex,
 454                                   const uint32_t BlockAddress,
 455                                   const uint8_t Blocks,
 456                                   const uint16_t BlockSize,
 457                                   void* BufferPtr)
 458 {
 459         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
 460
 461         /* Create a CBW with a SCSI command to read in the given blocks from the device */
 462         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 463                 {
 464                         .Signature          = MS_CBW_SIGNATURE,
 465                         .DataTransferLength = ((uint32_t)Blocks * BlockSize),
 466                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 467                         .LUN                = LUNIndex,
 468                         .SCSICommandLength  = 10,
 469                         .SCSICommandData    =
 470                                 {
 471                                         SCSI_CMD_READ_10,
 472                                         0x00,                   // Unused (control bits, all off)
 473                                         (BlockAddress >> 24),   // MSB of Block Address
 474                                         (BlockAddress >> 16),
 475                                         (BlockAddress >> 8),
 476                                         (BlockAddress & 0xFF),  // LSB of Block Address
 477                                         0x00,                   // Reserved
 478                                         0x00,                   // MSB of Total Blocks to Read
 479                                         Blocks,                 // LSB of Total Blocks to Read
 480                                         0x00                    // Unused (control)
 481                                 }
 482                 };
 483
 484         MS_CommandStatusWrapper_t SCSICommandStatus;
 485
 486         /* Send the command and any data to the attached device */
 487         if ((ErrorCode = MassStore_SendCommand(&SCSICommandBlock, BufferPtr)) != PIPE_RWSTREAM_NoError)
 488         {
 489                 Pipe_Freeze();
 490                 return ErrorCode;
 491         }
 492
 493         /* Retrieve status information from the attached device */
 494         if ((ErrorCode = MassStore_GetReturnedStatus(&SCSICommandStatus)) != PIPE_RWSTREAM_NoError)
 495         {
 496                 Pipe_Freeze();
 497                 return ErrorCode;
 498         }
 499
 500         return ErrorCode;
 501 }
 502
 503 /** Issues a SCSI Device Block Write command to the attached device, to write one or more data blocks to the
 504  *  storage medium from a buffer.
 505  *
 506  *  \param[in] LUNIndex      Index of the LUN inside the device the command is being addressed to
 507  *  \param[in] BlockAddress  Start block address to write to
 508  *  \param[in] Blocks        Number of blocks to write to in the device
 509  *  \param[in] BlockSize     Size in bytes of each block to write
 510  *  \param[in] BufferPtr     Pointer to the buffer where the write data is to be sourced from
 511  *
 512  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 513  */
 514 uint8_t MassStore_WriteDeviceBlock(const uint8_t LUNIndex,
 515                                    const uint32_t BlockAddress,
 516                                    const uint8_t Blocks,
 517                                    const uint16_t BlockSize,
 518                                    void* BufferPtr)
 519 {
 520         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
 521
 522         /* Create a CBW with a SCSI command to write the given blocks to the device */
 523         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 524                 {
 525                         .Signature          = MS_CBW_SIGNATURE,
 526                         .DataTransferLength = ((uint32_t)Blocks * BlockSize),
 527                         .Flags              = MS_COMMAND_DIR_DATA_OUT,
 528                         .LUN                = LUNIndex,
 529                         .SCSICommandLength  = 10,
 530                         .SCSICommandData    =
 531                                 {
 532                                         SCSI_CMD_WRITE_10,
 533                                         0x00,                   // Unused (control bits, all off)
 534                                         (BlockAddress >> 24),   // MSB of Block Address
 535                                         (BlockAddress >> 16),
 536                                         (BlockAddress >> 8),
 537                                         (BlockAddress & 0xFF),  // LSB of Block Address
 538                                         0x00,                   // Unused (reserved)
 539                                         0x00,                   // MSB of Total Blocks to Write
 540                                         Blocks,                 // LSB of Total Blocks to Write
 541                                         0x00                    // Unused (control)
 542                                 }
 543                 };
 544
 545         MS_CommandStatusWrapper_t SCSICommandStatus;
 546
 547         /* Send the command and any data to the attached device */
 548         if ((ErrorCode = MassStore_SendCommand(&SCSICommandBlock, BufferPtr)) != PIPE_RWSTREAM_NoError)
 549         {
 550                 Pipe_Freeze();
 551                 return ErrorCode;
 552         }
 553
 554         /* Retrieve status information from the attached device */
 555         if ((ErrorCode = MassStore_GetReturnedStatus(&SCSICommandStatus)) != PIPE_RWSTREAM_NoError)
 556         {
 557                 Pipe_Freeze();
 558                 return ErrorCode;
 559         }
 560
 561         return ErrorCode;
 562 }
 563
 564 /** Issues a SCSI Device Test Unit Ready command to the attached device, to determine if the device is ready to accept
 565  *  other commands.
 566  *
 567  *  \param[in] LUNIndex      Index of the LUN inside the device the command is being addressed to
 568  *
 569  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 570  */
 571 uint8_t MassStore_TestUnitReady(const uint8_t LUNIndex)
 572 {
 573         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
 574
 575         /* Create a CBW with a SCSI command to issue TEST UNIT READY command */
 576         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 577                 {
 578                         .Signature          = MS_CBW_SIGNATURE,
 579                         .DataTransferLength = 0,
 580                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 581                         .LUN                = LUNIndex,
 582                         .SCSICommandLength  = 6,
 583                         .SCSICommandData    =
 584                                 {
 585                                         SCSI_CMD_TEST_UNIT_READY,
 586                                         0x00,                   // Reserved
 587                                         0x00,                   // Reserved
 588                                         0x00,                   // Reserved
 589                                         0x00,                   // Reserved
 590                                         0x00                    // Unused (control)
 591                                 }
 592                 };
 593
 594         MS_CommandStatusWrapper_t SCSICommandStatus;
 595
 596         /* Send the command and any data to the attached device */
 597         if ((ErrorCode = MassStore_SendCommand(&SCSICommandBlock, NULL)) != PIPE_RWSTREAM_NoError)
 598         {
 599                 Pipe_Freeze();
 600                 return ErrorCode;
 601         }
 602
 603         /* Retrieve status information from the attached device */
 604         if ((ErrorCode = MassStore_GetReturnedStatus(&SCSICommandStatus)) != PIPE_RWSTREAM_NoError)
 605         {
 606                 Pipe_Freeze();
 607                 return ErrorCode;
 608         }
 609
 610         return ErrorCode;
 611 }
 612
 613 /** Issues a SCSI Device Read Capacity command to the attached device, to determine the capacity of the
 614  *  given Logical Unit within the device.
 615  *
 616  *  \param[in] LUNIndex      Index of the LUN inside the device the command is being addressed to
 617  *  \param[out] CapacityPtr  Device capacity structure where the capacity data is to be stored
 618  *
 619  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 620  */
 621 uint8_t MassStore_ReadCapacity(const uint8_t LUNIndex,
 622                                SCSI_Capacity_t* const CapacityPtr)
 623 {
 624         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
 625
 626         /* Create a CBW with a SCSI command to issue READ CAPACITY command */
 627         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 628                 {
 629                         .Signature          = MS_CBW_SIGNATURE,
 630                         .DataTransferLength = sizeof(SCSI_Capacity_t),
 631                         .Flags              = MS_COMMAND_DIR_DATA_IN,
 632                         .LUN                = LUNIndex,
 633                         .SCSICommandLength  = 10,
 634                         .SCSICommandData    =
 635                                 {
 636                                         SCSI_CMD_READ_CAPACITY_10,
 637                                         0x00,                   // Reserved
 638                                         0x00,                   // MSB of Logical block address
 639                                         0x00,
 640                                         0x00,
 641                                         0x00,                   // LSB of Logical block address
 642                                         0x00,                   // Reserved
 643                                         0x00,                   // Reserved
 644                                         0x00,                   // Partial Medium Indicator
 645                                         0x00                    // Unused (control)
 646                                 }
 647                 };
 648
 649         MS_CommandStatusWrapper_t SCSICommandStatus;
 650
 651         /* Send the command and any data to the attached device */
 652         if ((ErrorCode = MassStore_SendCommand(&SCSICommandBlock, CapacityPtr)) != PIPE_RWSTREAM_NoError)
 653         {
 654                 Pipe_Freeze();
 655                 return ErrorCode;
 656         }
 657
 658         /* Endian-correct the read data */
 659         CapacityPtr->Blocks    = SwapEndian_32(CapacityPtr->Blocks);
 660         CapacityPtr->BlockSize = SwapEndian_32(CapacityPtr->BlockSize);
 661
 662         /* Retrieve status information from the attached device */
 663         if ((ErrorCode = MassStore_GetReturnedStatus(&SCSICommandStatus)) != PIPE_RWSTREAM_NoError)
 664         {
 665                 Pipe_Freeze();
 666                 return ErrorCode;
 667         }
 668
 669         return ErrorCode;
 670 }
 671
 672 /** Issues a SCSI Device Prevent/Allow Medium Removal command to the attached device, to lock the physical media from
 673  *  being removed. This is a legacy command for SCSI disks with removable storage (such as ZIP disks), but should still
 674  *  be issued before the first read or write command is sent.
 675  *
 676  *  \param[in] LUNIndex        Index of the LUN inside the device the command is being addressed to
 677  *  \param[in] PreventRemoval  Whether or not the LUN media should be locked to prevent removal or not
 678  *
 679  *  \return A value from the Pipe_Stream_RW_ErrorCodes_t enum, or MASS_STORE_SCSI_COMMAND_FAILED if the SCSI command fails
 680  */
 681 uint8_t MassStore_PreventAllowMediumRemoval(const uint8_t LUNIndex,
 682                                             const bool PreventRemoval)
 683 {
 684         uint8_t ErrorCode = PIPE_RWSTREAM_NoError;
 685
 686         /* Create a CBW with a SCSI command to issue PREVENT ALLOW MEDIUM REMOVAL command */
 687         MS_CommandBlockWrapper_t SCSICommandBlock = (MS_CommandBlockWrapper_t)
 688                 {
 689                         .Signature          = MS_CBW_SIGNATURE,
 690                         .DataTransferLength = 0,
 691                         .Flags              = MS_COMMAND_DIR_DATA_OUT,
 692                         .LUN                = LUNIndex,
 693                         .SCSICommandLength  = 6,
 694                         .SCSICommandData    =
 695                                 {
 696                                         SCSI_CMD_PREVENT_ALLOW_MEDIUM_REMOVAL,
 697                                         0x00,                   // Reserved
 698                                         0x00,                   // Reserved
 699                                         PreventRemoval,         // Prevent flag
 700                                         0x00,                   // Reserved
 701                                         0x00                    // Unused (control)
 702                                 }
 703                 };
 704
 705         MS_CommandStatusWrapper_t SCSICommandStatus;
 706
 707         /* Send the command and any data to the attached device */
 708         if ((ErrorCode = MassStore_SendCommand(&SCSICommandBlock, NULL)) != PIPE_RWSTREAM_NoError)
 709         {
 710                 Pipe_Freeze();
 711                 return ErrorCode;
 712         }
 713
 714         /* Retrieve status information from the attached device */
 715         if ((ErrorCode = MassStore_GetReturnedStatus(&SCSICommandStatus)) != PIPE_RWSTREAM_NoError)
 716         {
 717                 Pipe_Freeze();
 718                 return ErrorCode;
 719         }
 720
 721         return ErrorCode;
 722 }
 723