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