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