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