Formalize comments for Protocols and PPIs.

[mirror_edk2.git] / MdePkg / Include / Protocol / ScsiPassThru.h

diff --git a/MdePkg/Include/Protocol/ScsiPassThru.h b/MdePkg/Include/Protocol/ScsiPassThru.h
index a5aa6c47c0e25530ec41b238efb01a79ae2bade5..ee498e0ec32e35b9a788d691a94e6aba1de455c2 100644 (file)
--- a/MdePkg/Include/Protocol/ScsiPassThru.h
+++ b/MdePkg/Include/Protocol/ScsiPassThru.h
@@ -1,7 +1,14 @@
 /** @file\r
-  SCSI Pass Through protocol.\r
-\r
-  Copyright (c) 2006, Intel Corporation                                                         \r
+  SCSI Pass Through protocol as defined in EFI 1.1.\r
+  This protocol allows information about a SCSI channel to be collected, \r
+  and allows SCSI Request Packets to be sent to any SCSI devices on a SCSI\r
+  channel even if those devices are not boot devices. This protocol is attached \r
+  to the device handle of each SCSI channel in a system that the protocol \r
+  supports, and can be used for diagnostics. It may also be used to build \r
+  a Block I/O driver for SCSI hard drives and SCSI CD-ROM or DVD drives to\r
+  allow those devices to become boot devices.\r
+\r
+  Copyright (c) 2006 - 2008, 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
@@ -10,8 +17,6 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
 \r
-  Module Name:  ScsiPassThru.h\r
-\r
 **/\r
 \r
 #ifndef __SCSI_PASS_THROUGH_H__\r
@@ -22,9 +27,9 @@
     0xa59e8fcf, 0xbda0, 0x43bb, {0x90, 0xb1, 0xd3, 0x73, 0x2e, 0xca, 0xa8, 0x77 } \\r
   }\r
 \r
-//\r
-// Forward reference for pure ANSI compatability\r
-//\r
+///\r
+/// Forward reference for pure ANSI compatability\r
+///\r
 typedef struct _EFI_SCSI_PASS_THRU_PROTOCOL  EFI_SCSI_PASS_THRU_PROTOCOL;\r
 \r
 #define EFI_SCSI_PASS_THRU_ATTRIBUTES_PHYSICAL    0x0001\r
@@ -107,7 +112,7 @@ typedef struct {
                                     DataBuffer.See HostAdapterStatus, TargetStatus,\r
                                     SenseDataLength,and SenseData in that order\r
                                     for additional status information.\r
-  @retval EFI_WARN_BUFFER_TOO_SMALL The SCSI Request Packet was executed, but the\r
+  @retval EFI_BAD_BUFFER_SIZE       The SCSI Request Packet was executed, but the\r
                                     entire DataBuffer could not be transferred.\r
                                     The actual number of bytes transferred is returned\r
                                     in TransferLength. See HostAdapterStatus,\r
@@ -135,14 +140,13 @@ typedef struct {
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_SCSI_PASS_THRU_PASSTHRU) (\r
+(EFIAPI *EFI_SCSI_PASS_THRU_PASSTHRU)(\r
   IN EFI_SCSI_PASS_THRU_PROTOCOL                          *This,\r
   IN UINT32                                               Target,\r
   IN UINT64                                               Lun,\r
   IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET           *Packet,\r
   IN EFI_EVENT                                            Event   OPTIONAL\r
-  )\r
-;\r
+  );\r
 \r
 /**\r
   Used to retrieve the list of legal Target IDs for SCSI devices \r
@@ -170,12 +174,11 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE) (\r
+(EFIAPI *EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE)(\r
   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,\r
   IN OUT UINT32                             *Target,\r
   IN OUT UINT64                             *Lun\r
-  )\r
-;\r
+  );\r
 \r
 /**\r
   Used to allocate and build a device path node for a SCSI device \r
@@ -206,13 +209,12 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH) (\r
+(EFIAPI *EFI_SCSI_PASS_THRU_BUILD_DEVICE_PATH)(\r
   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,\r
   IN     UINT32                             Target,\r
   IN     UINT64                             Lun,\r
   IN OUT EFI_DEVICE_PATH_PROTOCOL           **DevicePath\r
-  )\r
-;\r
+  );\r
 \r
 /**\r
   Used to translate a device path node to a Target ID and LUN.\r
@@ -239,13 +241,12 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_SCSI_PASS_THRU_GET_TARGET_LUN) (\r
+(EFIAPI *EFI_SCSI_PASS_THRU_GET_TARGET_LUN)(\r
   IN EFI_SCSI_PASS_THRU_PROTOCOL            *This,\r
   IN  EFI_DEVICE_PATH_PROTOCOL              *DevicePath,\r
   OUT UINT32                                *Target,\r
   OUT UINT64                                *Lun\r
-  )\r
-;\r
+  );\r
 \r
 /**\r
   Resets a SCSI channel.This operation resets all the \r
@@ -264,10 +265,9 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_SCSI_PASS_THRU_RESET_CHANNEL) (\r
+(EFIAPI *EFI_SCSI_PASS_THRU_RESET_CHANNEL)(\r
   IN EFI_SCSI_PASS_THRU_PROTOCOL             *This\r
-  )\r
-;\r
+  );\r
 \r
 /**\r
   Resets a SCSI device that is connected to a SCSI channel.\r
@@ -290,14 +290,23 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_SCSI_PASS_THRU_RESET_TARGET) (\r
+(EFIAPI *EFI_SCSI_PASS_THRU_RESET_TARGET)(\r
   IN EFI_SCSI_PASS_THRU_PROTOCOL             *This,\r
   IN UINT32                                  Target,\r
   IN UINT64                                  Lun\r
-  )\r
-;\r
-\r
+  );\r
+\r
+///\r
+/// The EFI_SCSI_PASS_THRU_PROTOCOL provides information about a SCSI channel and\r
+/// the ability to send SCI Request Packets to any SCSI device attached to that SCSI channel. The\r
+/// information includes the Target ID of the host controller on the SCSI channel, the attributes of\r
+/// the SCSI channel, the printable name for the SCSI controller, and the printable name of the\r
+/// SCSI channel.\r
+///\r
 struct _EFI_SCSI_PASS_THRU_PROTOCOL {\r
+  ///\r
+  /// A pointer to the EFI_SCSI_PASS_THRU_MODE data for this SCSI channel.\r
+  ///\r
   EFI_SCSI_PASS_THRU_MODE               *Mode;\r
   EFI_SCSI_PASS_THRU_PASSTHRU           PassThru;\r
   EFI_SCSI_PASS_THRU_GET_NEXT_DEVICE    GetNextDevice;\r