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

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