1. Set the Target array to zero before fill the target id.

[mirror_edk2.git] / MdeModulePkg / Bus / Scsi / ScsiDiskDxe / ScsiDisk.h

diff --git a/MdeModulePkg/Bus/Scsi/ScsiDiskDxe/ScsiDisk.h b/MdeModulePkg/Bus/Scsi/ScsiDiskDxe/ScsiDisk.h
index 675c643eff1c33b96dfe299b4fee7615d0657e33..971df28a2bd92ecb5441ac66688500d49f12feef 100644 (file)
--- a/MdeModulePkg/Bus/Scsi/ScsiDiskDxe/ScsiDisk.h
+++ b/MdeModulePkg/Bus/Scsi/ScsiDiskDxe/ScsiDisk.h
@@ -1,6 +1,6 @@
 /*++\r
 \r
-Copyright (c) 2006, Intel Corporation                                                         \r
+Copyright (c) 2004 - 2007, Intel Corporation                                                         \r
 All rights reserved. This program and the accompanying materials                          \r
 are licensed and made available under the terms and conditions of the BSD License         \r
 which accompanies this distribution.  The full text of the license may be found at        \r
@@ -119,16 +119,16 @@ ScsiDiskReset (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Reset SCSI Disk  \r
 \r
 Arguments:\r
 \r
-  This                  - TODO: add argument description\r
-  ExtendedVerification  - TODO: add argument description\r
+  This                  - The pointer of EFI_BLOCK_IO_PROTOCOL\r
+  ExtendedVerification  - The flag about if extend verificate\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_STATUS\r
 \r
 --*/\r
 ;\r
@@ -146,19 +146,24 @@ ScsiDiskReadBlocks (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  The function is to Read Block from SCSI Disk\r
 \r
 Arguments:\r
 \r
-  This        - TODO: add argument description\r
-  MediaId     - TODO: add argument description\r
-  LBA         - TODO: add argument description\r
-  BufferSize  - TODO: add argument description\r
-  Buffer      - TODO: add argument description\r
+  This        - The pointer of EFI_BLOCK_IO_PROTOCOL\r
+  MediaId     - The Id of Media detected\r
+  LBA         - The logic block address\r
+  BufferSize  - The size of Buffer\r
+  Buffer      - The buffer to fill the read out data\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_INVALID_PARAMETER - Invalid parameter passed in.\r
+  EFI_SUCCESS           - Successfully to read out block.\r
+  EFI_DEVICE_ERROR      - Fail to detect media.\r
+  EFI_NO_MEDIA          - Media is not present.\r
+  EFI_MEDIA_CHANGED     - Media has changed.\r
+  EFI_BAD_BUFFER_SIZE   - The buffer size is not multiple of BlockSize.\r
 \r
 --*/\r
 ;\r
@@ -176,19 +181,24 @@ ScsiDiskWriteBlocks (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  The function is to Write Block to SCSI Disk\r
 \r
 Arguments:\r
 \r
-  This        - TODO: add argument description\r
-  MediaId     - TODO: add argument description\r
-  LBA         - TODO: add argument description\r
-  BufferSize  - TODO: add argument description\r
-  Buffer      - TODO: add argument description\r
+  This        - The pointer of EFI_BLOCK_IO_PROTOCOL\r
+  MediaId     - The Id of Media detected\r
+  LBA         - The logic block address\r
+  BufferSize  - The size of Buffer\r
+  Buffer      - The buffer to fill the read out data\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_INVALID_PARAMETER - Invalid parameter passed in.\r
+  EFI_SUCCESS           - Successfully to read out block.\r
+  EFI_DEVICE_ERROR      - Fail to detect media.\r
+  EFI_NO_MEDIA          - Media is not present.\r
+  EFI_MEDIA_CHANGED     - Media has changed.\r
+  EFI_BAD_BUFFER_SIZE   - The buffer size is not multiple of BlockSize.\r
 \r
 --*/\r
 ;\r
@@ -202,15 +212,15 @@ ScsiDiskFlushBlocks (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Flush Block to Disk\r
 \r
 Arguments:\r
 \r
-  This  - TODO: add argument description\r
+  This  - The pointer of EFI_BLOCK_IO_PROTOCOL\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_SUCCESS \r
 \r
 --*/\r
 ;\r
@@ -225,44 +235,48 @@ ScsiDiskDetectMedia (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Dectect Device and read out capacity ,if error occurs, parse the sense key.\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice  - TODO: add argument description\r
-  MustReadCap     - TODO: add argument description\r
-  MediaChange     - TODO: add argument description\r
+  ScsiDiskDevice     - The pointer of SCSI_DISK_DEV\r
+  MustReadCapacity   - The flag about reading device capacity\r
+  MediaChange        - The pointer of flag indicates if media has changed \r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_DEVICE_ERROR   - Indicates that error occurs\r
+  EFI_SUCCESS        - Successfully to detect media\r
 \r
 --*/\r
 ;\r
-  \r
+\r
 EFI_STATUS\r
 ScsiDiskTestUnitReady (\r
-  SCSI_DISK_DEV        *ScsiDiskDevice,\r
-  BOOLEAN              *NeedRetry,\r
-  EFI_SCSI_SENSE_DATA  **SenseDataArray,\r
-  UINTN                *NumberOfSenseKeys\r
+  SCSI_DISK_DEV       *ScsiDiskDevice,\r
+  BOOLEAN             *NeedRetry,\r
+  EFI_SCSI_SENSE_DATA **SenseDataArray,\r
+  UINTN               *NumberOfSenseKeys\r
   )\r
 /*++\r
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
-\r
+  When Test Unit Ready command succeeds, retrieve Sense Keys via Request Sense;\r
+  When Test Unit Ready command encounters any error caused by host adapter or\r
+  target, return error without retrieving Sense Keys.\r
+  \r
 Arguments:\r
 \r
-  ScsiDiskDevice    - TODO: add argument description\r
-  NeedRetry         - TODO: add argument description\r
-  SenseDataArray    - TODO: add argument description\r
-  NumberOfSenseKeys - TODO: add argument description\r
-\r
+  ScsiDiskDevice  - The pointer of SCSI_DISK_DEV\r
+  NeedRetry       - The pointer of flag indicates try again\r
+  SenseDataArray  - The pointer of an array of sense data\r
+  NumberOfSenseKeys - The pointer of the number of sense data array\r
+  \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_DEVICE_ERROR   - Indicates that error occurs\r
+  EFI_SUCCESS        - Successfully to test unit\r
 \r
 --*/\r
 ;\r
@@ -278,45 +292,47 @@ DetectMediaParsingSenseKeys (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
-\r
+  Parsing Sense Keys which got from request sense command.\r
+  \r
 Arguments:\r
 \r
-  ScsiDiskDevice    - TODO: add argument description\r
-  SenseData         - TODO: add argument description\r
-  NumberOfSenseKeys - TODO: add argument description\r
-  Action            - TODO: add argument description\r
+  ScsiDiskDevice    - The pointer of SCSI_DISK_DEV\r
+  SenseData         - The pointer of EFI_SCSI_SENSE_DATA\r
+  NumberOfSenseKeys - The number of sense key  \r
+  Action            - The pointer of action which indicates what is need to do next\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_DEVICE_ERROR   - Indicates that error occurs\r
+  EFI_SUCCESS        - Successfully to complete the parsing\r
 \r
 --*/\r
 ;\r
 \r
 EFI_STATUS\r
 ScsiDiskReadCapacity (\r
-  SCSI_DISK_DEV           *ScsiDiskDevice,\r
-  BOOLEAN                 *NeedRetry,\r
-  EFI_SCSI_SENSE_DATA     **SenseDataArray,\r
-  UINTN                   *NumberOfSenseKeys\r
+  SCSI_DISK_DEV       *ScsiDiskDevice,\r
+  BOOLEAN             *NeedRetry,\r
+  EFI_SCSI_SENSE_DATA **SenseDataArray,\r
+  UINTN               *NumberOfSenseKeys\r
   )\r
 /*++\r
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Send read capacity command to device and get the device parameter\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice    - TODO: add argument description\r
-  NeedRetry         - TODO: add argument description\r
-  SenseDataArray    - TODO: add argument description\r
-  NumberOfSenseKeys - TODO: add argument description\r
+  ScsiDiskDevice     -  The pointer of SCSI_DISK_DEV\r
+  NeedRetry          -  The pointer of flag indicates if need a retry\r
+  SenseDataArray     -  The pointer of an array of sense data\r
+  NumberOfSenseKeys  -  The number of sense key\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_DEVICE_ERROR   - Indicates that error occurs\r
+  EFI_SUCCESS        - Successfully to read capacity\r
 \r
 --*/\r
 ;\r
@@ -329,15 +345,18 @@ CheckHostAdapterStatus (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
-\r
+  Check the HostAdapter status\r
+  \r
 Arguments:\r
 \r
-  HostAdapterStatus - TODO: add argument description\r
+  HostAdapterStatus - Host Adapter status\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_SUCCESS       \r
+  EFI_TIMEOUT       \r
+  EFI_NOT_READY     \r
+  EFI_DEVICE_ERROR  \r
 \r
 --*/\r
 ;\r
@@ -350,15 +369,17 @@ CheckTargetStatus (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
-\r
+  Check the target status\r
+  \r
 Arguments:\r
 \r
-  TargetStatus  - TODO: add argument description\r
+  TargetStatus  - Target status\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_NOT_READY  \r
+  EFI_DEVICE_ERROR \r
+  EFI_SUCCESS\r
 \r
 --*/\r
 ;\r
@@ -375,19 +396,25 @@ ScsiDiskRequestSenseKeys (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Retrieve all sense keys from the device.\r
+  When encountering error during the process,\r
+  if retrieve sense keys before error encounterred,\r
+  return the sense keys with return status set to EFI_SUCCESS,\r
+  and NeedRetry set to FALSE; otherwize, return the proper return\r
+  status.\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice    - TODO: add argument description\r
-  NeedRetry         - TODO: add argument description\r
-  SenseDataArray    - TODO: add argument description\r
-  NumberOfSenseKeys - TODO: add argument description\r
-  AskResetIfError   - TODO: add argument description\r
-\r
+  ScsiDiskDevice     -  The pointer of SCSI_DISK_DEV\r
+  NeedRetry          -  The pointer of flag indicates if need a retry\r
+  SenseDataArray     -  The pointer of an array of sense data\r
+  NumberOfSenseKeys  -  The number of sense key\r
+  AskResetIfError    -  The flag indicates if need reset when error occurs\r
+  \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_DEVICE_ERROR   - Indicates that error occurs\r
+  EFI_SUCCESS        - Successfully to request sense key\r
 \r
 --*/\r
 ;\r
@@ -401,16 +428,17 @@ ScsiDiskInquiryDevice (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Send out Inquiry command to Device\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice  - TODO: add argument description\r
-  NeedRetry       - TODO: add argument description\r
+  ScsiDiskDevice  - The pointer of SCSI_DISK_DEV\r
+  NeedRetry       - Indicates if needs try again when error happens\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_DEVICE_ERROR   - Indicates that error occurs\r
+  EFI_SUCCESS        - Successfully to detect media\r
 \r
 --*/\r
 ;\r
@@ -423,15 +451,15 @@ ParseInquiryData (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Parse Inquiry data\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice  - TODO: add argument description\r
+  ScsiDiskDevice  - The pointer of SCSI_DISK_DEV\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  NONE\r
 \r
 --*/\r
 ;\r
@@ -447,18 +475,19 @@ ScsiDiskReadSectors (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Read sector from SCSI Disk\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice  - TODO: add argument description\r
-  Buffer          - TODO: add argument description\r
-  Lba             - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
+  ScsiDiskDevice  - The poiniter of SCSI_DISK_DEV\r
+  Buffer          - The buffer to fill in the read out data\r
+  Lba             - Logic block address\r
+  NumberOfBlocks  - The number of blocks to read\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_DEVICE_ERROR\r
+  EFI_SUCCESS\r
 \r
 --*/\r
 ;\r
@@ -474,18 +503,19 @@ ScsiDiskWriteSectors (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Write SCSI Disk sectors\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice  - TODO: add argument description\r
-  Buffer          - TODO: add argument description\r
-  Lba             - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
+  ScsiDiskDevice  - The pointer of SCSI_DISK_DEV\r
+  Buffer          - The data buffer to write sector\r
+  Lba             - Logic block address\r
+  NumberOfBlocks  - The number of blocks to write\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_DEVICE_ERROR \r
+  EFI_SUCCESS\r
 \r
 --*/\r
 ;\r
@@ -506,23 +536,23 @@ ScsiDiskRead10 (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Sumbmit Read command \r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice    - TODO: add argument description\r
-  NeedRetry         - TODO: add argument description\r
-  SenseDataArray    - TODO: add argument description\r
-  NumberOfSenseKeys - TODO: add argument description\r
-  Timeout           - TODO: add argument description\r
-  DataBuffer        - TODO: add argument description\r
-  DataLength        - TODO: add argument description\r
-  StartLba          - TODO: add argument description\r
-  SectorSize        - TODO: add argument description\r
+  ScsiDiskDevice    - The pointer of ScsiDiskDevice\r
+  NeedRetry         - The pointer of flag indicates if needs retry if error happens\r
+  SenseDataArray    - The pointer of an array of sense data\r
+  NumberOfSenseKeys - The number of sense key\r
+  Timeout           - The time to complete the command\r
+  DataBuffer        - The buffer to fill with the read out data\r
+  DataLength        - The length of buffer\r
+  StartLba          - The start logic block address\r
+  SectorSize        - The size of sector\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_STATUS\r
 \r
 --*/\r
 ;\r
@@ -543,23 +573,23 @@ ScsiDiskWrite10 (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Submit Write Command\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice    - TODO: add argument description\r
-  NeedRetry         - TODO: add argument description\r
-  SenseDataArray    - TODO: add argument description\r
-  NumberOfSenseKeys - TODO: add argument description\r
-  Timeout           - TODO: add argument description\r
-  DataBuffer        - TODO: add argument description\r
-  DataLength        - TODO: add argument description\r
-  StartLba          - TODO: add argument description\r
-  SectorSize        - TODO: add argument description\r
+  ScsiDiskDevice    - The pointer of ScsiDiskDevice\r
+  NeedRetry         - The pointer of flag indicates if needs retry if error happens\r
+  SenseDataArray    - The pointer of an array of sense data\r
+  NumberOfSenseKeys - The number of sense key\r
+  Timeout           - The time to complete the command\r
+  DataBuffer        - The buffer to fill with the read out data\r
+  DataLength        - The length of buffer\r
+  StartLba          - The start logic block address\r
+  SectorSize        - The size of sector\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  EFI_STATUS\r
 \r
 --*/\r
 ;\r
@@ -573,16 +603,16 @@ GetMediaInfo (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Get information from media read capacity command\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice  - TODO: add argument description\r
-  Capacity        - TODO: add argument description\r
+  ScsiDiskDevice  - The pointer of SCSI_DISK_DEV\r
+  Capacity        - The pointer of EFI_SCSI_DISK_CAPACITY_DATA\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  NONE\r
 \r
 --*/\r
 ;\r
@@ -596,16 +626,16 @@ ScsiDiskIsNoMedia (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Check sense key to find if media presents\r
 \r
 Arguments:\r
 \r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
+  SenseData   - The pointer of EFI_SCSI_SENSE_DATA\r
+  SenseCounts - The number of sense key\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  BOOLEAN\r
 \r
 --*/\r
 ;\r
@@ -619,16 +649,16 @@ ScsiDiskIsMediaError (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Parse sense key\r
 \r
 Arguments:\r
 \r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
+  SenseData   - The pointer of EFI_SCSI_SENSE_DATA\r
+  SenseCounts - The number of sense key\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  BOOLEAN\r
 \r
 --*/\r
 ;\r
@@ -642,16 +672,16 @@ ScsiDiskIsHardwareError (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Check sense key to find if hardware error happens\r
 \r
 Arguments:\r
 \r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
+  SenseData   - The pointer of EFI_SCSI_SENSE_DATA\r
+  SenseCounts - The number of sense key\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  BOOLEAN\r
 \r
 --*/\r
 ;\r
@@ -665,16 +695,18 @@ ScsiDiskIsMediaChange (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+Routine Description:\r
+\r
+ Check sense key to find if media has changed\r
 \r
 Arguments:\r
 \r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
+  SenseData   - The pointer of EFI_SCSI_SENSE_DATA\r
+  SenseCounts - The number of sense key\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  BOOLEAN\r
 \r
 --*/\r
 ;\r
@@ -688,16 +720,16 @@ ScsiDiskIsResetBefore (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Check sense key to find if reset happens\r
 \r
 Arguments:\r
 \r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
+  SenseData   - The pointer of EFI_SCSI_SENSE_DATA\r
+  SenseCounts - The number of sense key\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  BOOLEAN\r
 \r
 --*/\r
 ;\r
@@ -712,17 +744,17 @@ ScsiDiskIsDriveReady (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Check sense key to find if the drive is ready\r
 \r
 Arguments:\r
 \r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-  NeedRetry   - TODO: add argument description\r
+  SenseData   - The pointer of EFI_SCSI_SENSE_DATA\r
+  SenseCounts - The number of sense key\r
+  RetryLater  - The flag means if need a retry \r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  BOOLEAN\r
 \r
 --*/\r
 ;\r
@@ -736,16 +768,16 @@ ScsiDiskHaveSenseKey (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Check sense key to find if it has sense key\r
 \r
 Arguments:\r
 \r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
+  SenseData   - The pointer of EFI_SCSI_SENSE_DATA\r
+  SenseCounts - The number of sense key\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  BOOLEAN\r
 \r
 --*/\r
 ;\r
@@ -758,15 +790,15 @@ ReleaseScsiDiskDeviceResources (
 \r
 Routine Description:\r
 \r
-  TODO: Add function description\r
+  Release resource about disk device\r
 \r
 Arguments:\r
 \r
-  ScsiDiskDevice  - TODO: add argument description\r
+  ScsiDiskDevice  - The pointer of SCSI_DISK_DEV\r
 \r
 Returns:\r
 \r
-  TODO: add return values\r
+  NONE\r
 \r
 --*/\r
 ;\r