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

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