Update comments for Protocol definitions to match UEFI spec.

And add the missing comments for the data structure.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6635 6f19259b-4bc3-4df7-8a09-765794883524

9 files changed, 411 insertions, 78 deletions

diff --git a/MdePkg/Include/Protocol/Dhcp4.h b/MdePkg/Include/Protocol/Dhcp4.h
index b02918d7c4..9178e69bbb 100644
--- a/MdePkg/Include/Protocol/Dhcp4.h
+++ b/MdePkg/Include/Protocol/Dhcp4.h
@@ -33,41 +33,69 @@ typedef struct _EFI_DHCP4_PROTOCOL EFI_DHCP4_PROTOCOL;
 

 #pragma pack(1)

 typedef struct {

+  ///

+  /// DHCP option code.

+  ///

   UINT8               OpCode;

+  ///

+  /// Length of the DHCP option data. Not present if OpCode is 0 or 255.

+  ///

   UINT8               Length;

+  ///

+  /// Start of the DHCP option data. Not present if OpCode is 0 or 255 or if Length is zero.

+  ///

   UINT8               Data[1];

 } EFI_DHCP4_PACKET_OPTION;

 #pragma pack()

 

 

 #pragma pack(1)

+///

+/// EFI_DHCP4_PACKET defines the format of DHCPv4 packets. See RFC 2131 for more information.

+///

 typedef struct {

-    UINT8             OpCode;

-    UINT8             HwType;

-    UINT8             HwAddrLen;

-    UINT8             Hops;

-    UINT32            Xid;

-    UINT16            Seconds;

-    UINT16            Reserved;

-    EFI_IPv4_ADDRESS  ClientAddr;       ///< Client IP address from client

-    EFI_IPv4_ADDRESS  YourAddr;         ///< Client IP address from server

-    EFI_IPv4_ADDRESS  ServerAddr;       ///< IP address of next server in bootstrap

-    EFI_IPv4_ADDRESS  GatewayAddr;      ///< Relay agent IP address

-    UINT8             ClientHwAddr[16]; ///< Client hardware address

-    CHAR8             ServerName[64];

-    CHAR8             BootFileName[128];

+  UINT8             OpCode;

+  UINT8             HwType;

+  UINT8             HwAddrLen;

+  UINT8             Hops;

+  UINT32            Xid;

+  UINT16            Seconds;

+  UINT16            Reserved;

+  EFI_IPv4_ADDRESS  ClientAddr;       ///< Client IP address from client

+  EFI_IPv4_ADDRESS  YourAddr;         ///< Client IP address from server

+  EFI_IPv4_ADDRESS  ServerAddr;       ///< IP address of next server in bootstrap

+  EFI_IPv4_ADDRESS  GatewayAddr;      ///< Relay agent IP address

+  UINT8             ClientHwAddr[16]; ///< Client hardware address

+  CHAR8             ServerName[64];

+  CHAR8             BootFileName[128];

 }EFI_DHCP4_HEADER;

 #pragma pack()

 

 

 #pragma pack(1)

 typedef struct {

+  ///

+  /// Size of the EFI_DHCP4_PACKET buffer.

+  ///

   UINT32              Size;

+  ///

+  /// Length of the EFI_DHCP4_PACKET from the first byte of the Header field 

+  /// to the last byte of the Option[] field.

+  ///

   UINT32              Length;

 

   struct {

+    ///

+    /// DHCP packet header.

+    ///

     EFI_DHCP4_HEADER  Header;

+    ///

+    /// DHCP magik cookie in network byte order.

+    ///

     UINT32            Magik;

+    ///

+    /// Start of the DHCP packed option data.

+    ///

     UINT8             Option[1];

   } Dhcp4;

 } EFI_DHCP4_PACKET;

@@ -75,30 +103,103 @@ typedef struct {
 

 

 typedef enum {

+  ///

+  /// The EFI DHCPv4 Protocol driver is stopped

+  ///

   Dhcp4Stopped        = 0x0,

+  ///

+  /// The EFI DHCPv4 Protocol driver is inactive

+  ///

   Dhcp4Init           = 0x1,

+  ///

+  /// The EFI DHCPv4 Protocol driver is collecting DHCP offer packets from DHCP servers.

+  ///

   Dhcp4Selecting      = 0x2,

+  ///

+  /// The EFI DHCPv4 Protocol driver has sent the request to the DHCP server and is waiting for a response.

+  ///

   Dhcp4Requesting     = 0x3,

+  ///

+  /// The DHCP configuration has completed.

+  ///

   Dhcp4Bound          = 0x4,

+  ///

+  /// The DHCP configuration is being renewed and another request has

+  /// been sent out, but it has not received a response from the server yet.

+  ///

   Dhcp4Renewing       = 0x5,

+  ///

+  /// The DHCP configuration has timed out and the EFI DHCPv4

+  /// Protocol driver is trying to extend the lease time.

+  ///

   Dhcp4Rebinding      = 0x6,

+  ///

+  /// The EFI DHCPv4 Protocol driver is initialized with a previously

+  /// allocated or known IP address.

+  ///

   Dhcp4InitReboot     = 0x7,

+  ///

+  /// The EFI DHCPv4 Protocol driver is seeking to reuse the previously

+  /// allocated IP address by sending a request to the DHCP server.

+  ///

   Dhcp4Rebooting      = 0x8

 } EFI_DHCP4_STATE;

 

 

 typedef enum{

+  ///

+  /// A DHCPDISCOVER packet is about to be sent.

+  ///

   Dhcp4SendDiscover   = 0x01,

+  ///

+  /// A DHCPOFFER packet was just received.

+  ///

   Dhcp4RcvdOffer      = 0x02,

+  ///

+  /// It is time for Dhcp4Callback to select an offer.

+  ///

   Dhcp4SelectOffer    = 0x03,

+  ///

+  /// A request packet is about to be sent.

+  ///

   Dhcp4SendRequest    = 0x04,

+  ///

+  /// A DHCPACK packet was received and will be passed to Dhcp4Callback.

+  ///

   Dhcp4RcvdAck        = 0x05,

+  ///

+  /// A DHCPNAK packet was received and will be passed to Dhcp4Callback.

+  ///

   Dhcp4RcvdNak        = 0x06,

+  ///

+  /// A decline packet is about to be sent.

+  ///

   Dhcp4SendDecline    = 0x07,

+  ///

+  /// The DHCP configuration process has completed. No packet is associated with this event.

+  ///

   Dhcp4BoundCompleted = 0x08,

+  ///

+  /// It is time to enter the Dhcp4Renewing state and to contact the server 

+  /// that originally issued the network address. No packet is associated with this event.

+  ///

   Dhcp4EnterRenewing  = 0x09,

+  ///

+  /// It is time to enter the Dhcp4Rebinding state and to contact any server. 

+  /// No packet is associated with this event.

+  ///

   Dhcp4EnterRebinding = 0x0a,

+  ///

+  /// The configured IP address was lost either because the lease has expired, 

+  /// the user released the configuration, or a DHCPNAK packet was received in 

+  /// the Dhcp4Renewing or Dhcp4Rebinding state. No packet is associated with this event.

+  ///

   Dhcp4AddressLost    = 0x0b,

+  ///

+  /// The DHCP process failed because a DHCPNAK packet was received or the user 

+  /// aborted the DHCP process at a time when the configuration was not available yet. 

+  /// No packet is associated with this event.

+  ///

   Dhcp4Fail           = 0x0c

 } EFI_DHCP4_EVENT;

 

@@ -142,51 +243,165 @@ EFI_STATUS
   OUT EFI_DHCP4_PACKET           **NewPacket OPTIONAL

   );

 

-

 typedef struct {

+  ///

+  /// Number of times to try sending DHCPDISCOVER packets and 

+  /// waiting for DHCPOFFER packets before accepting failure.

+  /// Set to zero to use the default try counts and timeout values.

+  ///

   UINT32                      DiscoverTryCount;

+  ///

+  /// Maximum amount of time (in seconds) to wait for DHCPOFFER packets in each 

+  /// of the retries. Timeout values of zero will default to a timeout value 

+  /// of one second. Set to NULL to use default timeout values.

+  ///

   UINT32                      *DiscoverTimeout;

+  ///

+  /// Number of times to try sending DHCPREQUEST packets and waiting for DHCPACK 

+  /// packets before accepting failure. Set to zero to use the default try counts and timeout values.

+  ///

   UINT32                      RequestTryCount;

+  ///

+  /// Maximum amount of time (in seconds) to wait for DHCPACK packets in each of the retries. 

+  /// Timeout values of zero will default to a timeout value of one second. 

+  /// Set to NULL to use default timeout values.

+  ///

   UINT32                      *RequestTimeout;

+  ///

+  /// Setting this parameter to the previously allocated IP address will cause 

+  /// the EFI DHCPv4 Protocol driver to enter the Dhcp4InitReboot state. 

+  /// Set this field to 0.0.0.0 to enter the Dhcp4Init state.

+  ///

   EFI_IPv4_ADDRESS            ClientAddress;

+  ///

+  /// The callback function to intercept various events that occurred in 

+  /// the DHCP configuration process. Set to NULL to ignore all those events.

+  ///

   EFI_DHCP4_CALLBACK          Dhcp4Callback;

-  void                        *CallbackContext;

+  ///

+  /// Pointer to the context that will be passed to Dhcp4Callback when it is called.

+  ///

+  VOID                        *CallbackContext;

+  ///

+  /// Number of DHCP options in the OptionList.

+  ///

   UINT32                      OptionCount;

+  ///

+  /// List of DHCP options to be included in every DHCPDISCOVER packet and 

+  /// subsequent DHCPREQUEST packet that is generated from DHCPOFFER packets.

+  ///

   EFI_DHCP4_PACKET_OPTION     **OptionList;

 } EFI_DHCP4_CONFIG_DATA;

 

 

 typedef struct {

+  ///

+  /// The EFI DHCPv4 Protocol driver operating state. 

+  ///

   EFI_DHCP4_STATE             State;

+  ///

+  /// The configuration data of the current EFI DHCPv4 Protocol driver instance.

+  ///

   EFI_DHCP4_CONFIG_DATA       ConfigData;

+  ///

+  /// The client IP address that was acquired from the DHCP server. If it is zero,

+  /// the DHCP acquisition has not completed yet and the following fields in this structure are undefined.

+  ///

   EFI_IPv4_ADDRESS            ClientAddress;

+  ///

+  /// The local hardware address.

+  ///

   EFI_MAC_ADDRESS             ClientMacAddress;

+  ///

+  /// The server IP address that is providing the DHCP service to this client.

+  ///

   EFI_IPv4_ADDRESS            ServerAddress;

+  ///

+  /// The router IP address that was acquired from the DHCP server. 

+  /// May be zero if the server does not offer this address.

+  ///

   EFI_IPv4_ADDRESS            RouterAddress;

+  ///

+  /// The subnet mask of the connected network that was acquired from the DHCP server.

+  ///

   EFI_IPv4_ADDRESS            SubnetMask;

+  ///

+  /// The lease time (in 1-second units) of the configured IP address. 

+  /// The value 0xFFFFFFFF means that the lease time is infinite. 

+  /// A default lease of 7 days is used if the DHCP server does not provide a value.

+  ///

   UINT32                      LeaseTime;

+  ///

+  /// The cached latest DHCPACK or DHCPNAK or BOOTP REPLY packet. May be NULL if no packet is cached.

+  ///

   EFI_DHCP4_PACKET            *ReplyPacket;

 } EFI_DHCP4_MODE_DATA;

 

 

 typedef struct {

+  ///

+  /// Alternate listening address. It can be a unicast, multicast, or broadcast address.

+  ///

   EFI_IPv4_ADDRESS            ListenAddress;

+  ///

+  /// The subnet mask of above listening unicast/broadcast IP address. 

+  /// Ignored if ListenAddress is a multicast address.

+  ///

   EFI_IPv4_ADDRESS            SubnetMask;

+  ///

+  /// Alternate station source (or listening) port number. 

+  /// If zero, then the default station port number (68) will be used.

+  ///

   UINT16                      ListenPort;

 } EFI_DHCP4_LISTEN_POINT;

 

 

 typedef struct {

+  ///

+  /// The completion status of transmitting and receiving.

+  ///

   EFI_STATUS              Status;

+  ///

+  /// If not NULL, the event that will be signaled when the collection process 

+  /// completes. If NULL, this function will busy-wait until the collection process competes.

+  ///

   EFI_EVENT               CompletionEvent;

+  ///

+  /// Pointer to the server IP address. This address may be a unicast, multicast, or broadcast address.

+  ///

   EFI_IPv4_ADDRESS        RemoteAddress;

+  ///

+  /// Server listening port number. If zero, the default server listening port number (67) will be used.

+  ///

   UINT16                  RemotePort;

+  ///

+  /// Pointer to the gateway address to override the existing setting.

+  ///

   EFI_IPv4_ADDRESS        GatewayAddress;

+  ///

+  /// The number of entries in ListenPoints. If zero, the default station address and port number 68 are used.

+  ///

   UINT32                  ListenPointCount;

+  ///

+  /// An array of station address and port number pairs that are used as receiving filters. 

+  /// The first entry is also used as the source address and source port of the outgoing packet.

+  ///

   EFI_DHCP4_LISTEN_POINT  *ListenPoints;

+  ///

+  /// Number of seconds to collect responses. Zero is invalid.

+  ///

   UINT32                  TimeoutValue;

+  ///

+  /// Pointer to the packet to be transmitted.

+  ///

   EFI_DHCP4_PACKET        *Packet;

+  ///

+  /// Number of received packets.

+  ///

   UINT32                  ResponseCount;

+  ///

+  /// Pointer to the allocated list of received packets.

+  ///

   EFI_DHCP4_PACKET        *ResponseList;

 } EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN;

 

@@ -248,7 +463,12 @@ EFI_STATUS
                                 Dhcp4Stopped, Dhcp4Init, Dhcp4InitReboot, or Dhcp4Bound state;

                                 Or onother instance of this EFI DHCPv4 Protocol driver is already

                                 in a valid configured state.

-  @retval EFI_INVALID_PARAMETER Some parameter is NULL.

+  @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:

+                                This is NULL.

+                                DiscoverTryCount > 0 and DiscoverTimeout is NULL

+                                RequestTryCount > 0 and RequestTimeout is NULL.

+                                OptionCount >0 and OptionList is NULL.

+                                ClientAddress is not a valid unicast address.

   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.

   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.

 

@@ -426,7 +646,15 @@ EFI_STATUS
 

   @retval EFI_SUCCESS           The new packet was built.

   @retval EFI_OUT_OF_RESOURCES  Storage for the new packet could not be allocated.

-  @retval EFI_INVALID_PARAMETER Some parameter is NULL.

+  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:

+                                This is NULL.

+                                SeedPacket is NULL.

+                                SeedPacket is not a well-formed DHCP packet.

+                                AppendCount is not zero and AppendList is NULL.

+                                DeleteCount is not zero and DeleteList is NULL.

+                                NewPacket is NULL

+                                Both DeleteCount and AppendCount are zero and

+                                NewPacket is not NULL.

 

 **/

 typedef

@@ -453,11 +681,17 @@ EFI_STATUS
   @param  Token   Pointer to the EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN structure.

 

   @retval EFI_SUCCESS           The packet was successfully queued for transmission.

-  @retval EFI_INVALID_PARAMETER Some parameter is NULL.

+  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:

+                                This is NULL.

+                                Token.RemoteAddress is zero.

+                                Token.Packet is NULL.

+                                Token.Packet is not a well-formed DHCP packet.

+                                The transaction ID in Token.Packet is in use by another DHCP process.

   @retval EFI_NOT_READY         The previous call to this function has not finished yet. Try to call

                                 this function after collection process completes.

   @retval EFI_NO_MAPPING        The default station address is not available yet.

   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.

+  @retval EFI_UNSUPPORTED       The implementation doesn’t support this function

   @retval Others                Some other unexpected error occurred.

 

 **/

@@ -489,11 +723,16 @@ EFI_STATUS
                            options are not included.

 

   @retval EFI_SUCCESS           The packet was successfully parsed.

-  @retval EFI_INVALID_PARAMETER Some parameter is NULL.

+  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:

+                                This is NULL.

+                                Packet is NULL.

+                                Packet is not a well-formed DHCP packet.

+                                OptionCount is NULL.

   @retval EFI_BUFFER_TOO_SMALL  One or more of the following conditions is TRUE:

                                 1) *OptionCount is smaller than the number of options that

                                 were found in the Packet.

                                 2) PacketOptionList is NULL.

+  @retval EFI_OUT_OF_RESOURCE   The packet is failed to parse because of resource shortage.

 

 **/

 typedef

diff --git a/MdePkg/Include/Protocol/DiskIo.h b/MdePkg/Include/Protocol/DiskIo.h
index 75978d18bf..77517cb672 100644
--- a/MdePkg/Include/Protocol/DiskIo.h
+++ b/MdePkg/Include/Protocol/DiskIo.h
@@ -64,13 +64,13 @@ EFI_STATUS
   );

 

 /**

-  Read BufferSize bytes from Offset into Buffer.

+  Writes a specified number of bytes to a device.

 

-  @param  This       Protocol instance pointer.

-  @param  MediaId    Id of the media, changes every time the media is replaced.

-  @param  Offset     The starting byte offset to read from

-  @param  BufferSize Size of Buffer

-  @param  Buffer     Buffer containing read data

+  @param  This       Indicates a pointer to the calling context.

+  @param  MediaId    ID of the medium to be written.

+  @param  Offset     The starting byte offset on the logical block I/O device to write.

+  @param  BufferSize The size in bytes of Buffer. The number of bytes to write to the device.

+  @param  Buffer     A pointer to the buffer containing the data to be written.

 

   @retval EFI_SUCCESS           The data was written correctly to the device.

   @retval EFI_WRITE_PROTECTED   The device can not be written to.

diff --git a/MdePkg/Include/Protocol/DriverBinding.h b/MdePkg/Include/Protocol/DriverBinding.h
index 9377891519..e5645f32e4 100644
--- a/MdePkg/Include/Protocol/DriverBinding.h
+++ b/MdePkg/Include/Protocol/DriverBinding.h
@@ -30,22 +30,27 @@
 typedef struct _EFI_DRIVER_BINDING_PROTOCOL  EFI_DRIVER_BINDING_PROTOCOL;

 

 /**

-  Test to see if this driver supports ControllerHandle. This service

-  is called by the EFI boot service ConnectController(). In

-  order to make drivers as small as possible, there are a few calling

-  restrictions for this service. ConnectController() must

-  follow these calling restrictions. If any other agent wishes to call

-  Supported() it must also follow these calling restrictions.

-

-  @param  This                Protocol instance pointer.

-  @param  ControllerHandle    Handle of device to test

-  @param  RemainingDevicePath Optional parameter use to pick a specific child

-                              device to start.

-

-  @retval EFI_SUCCESS         This driver supports this device

-  @retval EFI_ALREADY_STARTED This driver is already running on this device

-  @retval other               This driver does not support this device

-

+  Tests to see if this driver supports a given controller. If a child device is provided, 

+  it further tests to see if this driver supports creating a handle for the specified child device.

+

+  @param  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.

+  @param  ControllerHandle     The handle of the controller to test. This handle 

+                               must support a protocol interface that supplies 

+                               an I/O abstraction to the driver.

+  @param  RemainingDevicePath  A pointer to the remaining portion of a device path. 

+                               This parameter is ignored by device drivers, and is optional for bus drivers.

+

+

+  @retval EFI_SUCCESS         The device specified by ControllerHandle and

+                              RemainingDevicePath is supported by the driver specified by This.

+  @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and

+                              RemainingDevicePath is already being managed by the driver

+                              specified by This.

+  @retval EFI_ACCESS_DENIED   The device specified by ControllerHandle and

+                              RemainingDevicePath is already being managed by a different

+                              driver or an application that requires exclusive acces.

+  @retval EFI_UNSUPPORTED     The device specified by ControllerHandle and

+                              RemainingDevicePath is not supported by the driver specified by This.

 **/

 typedef

 EFI_STATUS

@@ -56,21 +61,27 @@ EFI_STATUS
   );

 

 /**

-  Start this driver on ControllerHandle. This service is called by the

-  EFI boot service ConnectController(). In order to make

-  drivers as small as possible, there are a few calling restrictions for

-  this service. ConnectController() must follow these

-  calling restrictions. If any other agent wishes to call Start() it

-  must also follow these calling restrictions.

-

-  @param  This                 Protocol instance pointer.

-  @param  ControllerHandle     Handle of device to bind driver to

-  @param  RemainingDevicePath  Optional parameter use to pick a specific child

-                               device to start.

-

-  @retval EFI_SUCCESS          This driver is added to ControllerHandle

-  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle

-  @retval other                This driver does not support this device

+  Start this driver on ControllerHandle. The Start() function is designed to be 

+  invoked from the EFI boot service ConnectController(). As a result, much of 

+  the error checking on the parameters to Start() has been moved into this 

+  common boot service. It is legal to call Start() from other locations, 

+  but the following calling restrictions must be followed or the system behavior will not be deterministic.

+  1. ControllerHandle must be a valid EFI_HANDLE.

+  2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned

+     EFI_DEVICE_PATH_PROTOCOL.

+  3. Prior to calling Start(), the Supported() function for the driver specified by This must

+     have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.  

+

+  @param  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.

+  @param  ControllerHandle     The handle of the controller to start. This handle 

+                               must support a protocol interface that supplies 

+                               an I/O abstraction to the driver.

+  @param  RemainingDevicePath  A pointer to the remaining portion of a device path. 

+                               This parameter is ignored by device drivers, and is optional for bus drivers.

+

+  @retval EFI_SUCCESS          The device was started.

+  @retval EFI_ALREADY_STARTED  The device could not be started due to a device error.

+  @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

 

 **/

 typedef

@@ -82,21 +93,27 @@ EFI_STATUS
   );

 

 /**

-  Stop this driver on ControllerHandle. This service is called by the

-  EFI boot service DisconnectController(). In order to

-  make drivers as small as possible, there are a few calling

-  restrictions for this service. DisconnectController()

-  must follow these calling restrictions. If any other agent wishes

-  to call Stop() it must also follow these calling restrictions.

+  Stop this driver on ControllerHandle. 

+  The Stop() function is designed to be invoked from the EFI boot service DisconnectController(). 

+  As a result, much of the error checking on the parameters to Stop() has been moved 

+  into this common boot service. It is legal to call Stop() from other locations, 

+  but the following calling restrictions must be followed or the system behavior will not be deterministic.

+  1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this

+     same driver's Start() function.

+  2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid

+     EFI_HANDLE. In addition, all of these handles must have been created in this driver’s

+     Start() function, and the Start() function must have called OpenProtocol() on

+     ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.

   

-  @param  This              Protocol instance pointer.

-  @param  ControllerHandle  Handle of device to stop driver on

-  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of

-                            children is zero stop the entire bus driver.

-  @param  ChildHandleBuffer List of Child Handles to Stop.

-

-  @retval EFI_SUCCESS       This driver is removed ControllerHandle

-  @retval other             This driver was not removed from this device

+  @param  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.

+  @param  ControllerHandle  A handle to the device being stopped. The handle must 

+                            support a bus specific I/O protocol for the driver 

+                            to use to stop the device.

+  @param  NumberOfChildren  The number of child device handles in ChildHandleBuffer.

+  @param  ChildHandleBuffer An array of child handles to be freed. May be NULL if NumberOfChildren is 0.

+

+  @retval EFI_SUCCESS       The device was stopped.

+  @retval EFI_DEVICE_ERROR  The device could not be stopped due to a device error.

 

 **/

 typedef

diff --git a/MdePkg/Include/Protocol/DriverConfiguration.h b/MdePkg/Include/Protocol/DriverConfiguration.h
index 547fd8e557..f02c5321d7 100644
--- a/MdePkg/Include/Protocol/DriverConfiguration.h
+++ b/MdePkg/Include/Protocol/DriverConfiguration.h
@@ -18,7 +18,7 @@
 #include <Protocol/DriverConfiguration2.h>

 

 ///

-/// Global ID for the Driver Configuration Protocol defined in UEFI 2.0

+/// Global ID for the Driver Configuration Protocol defined in EFI 1.1

 ///

 #define EFI_DRIVER_CONFIGURATION_PROTOCOL_GUID \

   { \

diff --git a/MdePkg/Include/Protocol/DriverDiagnostics.h b/MdePkg/Include/Protocol/DriverDiagnostics.h
index 87d077f234..4c62f42c87 100644
--- a/MdePkg/Include/Protocol/DriverDiagnostics.h
+++ b/MdePkg/Include/Protocol/DriverDiagnostics.h
@@ -16,7 +16,7 @@
 #define __EFI_DRIVER_DIAGNOSTICS_H__

 

 ///

-/// Global ID for the Driver Diagnostics Protocol as defined in UEFI 2.0.

+/// Global ID for the Driver Diagnostics Protocol as defined in EFI 1.1.

 ///

 #define EFI_DRIVER_DIAGNOSTICS_PROTOCOL_GUID \

   { \

diff --git a/MdePkg/Include/Protocol/Ebc.h b/MdePkg/Include/Protocol/Ebc.h
index b67cda97c0..a516f5439e 100644
--- a/MdePkg/Include/Protocol/Ebc.h
+++ b/MdePkg/Include/Protocol/Ebc.h
@@ -96,9 +96,8 @@ EFI_STATUS
   );

 

 /**

-  This routine is called by the core firmware to provide the EBC driver with

-  a function to call to flush the CPU's instruction cache following creation

-  of a thunk. It is not required.

+  Registers a callback function that the EBC interpreter calls to flush 

+  the processor instruction cache following creation of thunks.

 

   @param  This       A pointer to the EFI_EBC_PROTOCOL instance.

   @param  Flush      Pointer to a function of type EBC_ICACH_FLUSH.

diff --git a/MdePkg/Include/Protocol/EdidOverride.h b/MdePkg/Include/Protocol/EdidOverride.h
index 27f42f1154..f2076b252e 100644
--- a/MdePkg/Include/Protocol/EdidOverride.h
+++ b/MdePkg/Include/Protocol/EdidOverride.h
@@ -29,9 +29,9 @@ typedef struct _EFI_EDID_OVERRIDE_PROTOCOL EFI_EDID_OVERRIDE_PROTOCOL;
 #define EFI_EDID_OVERRIDE_ENABLE_HOT_PLUG 0x02

 

 /**

-  Return the current video mode information.

+  Returns policy information and potentially a replacement EDID for the specified video output device.

 

-  @param  This              Protocol instance pointer.

+  @param  This              The EFI_EDID_OVERRIDE_PROTOCOL instance.

   @param  ChildHandle       A child handle produced by the Graphics Output EFI

                             driver that represents a video output device.

   @param  Attributes        The attributes associated with ChildHandle video output device.

diff --git a/MdePkg/Include/Protocol/FirmwareVolume2.h b/MdePkg/Include/Protocol/FirmwareVolume2.h
index 0d5e5481fb..360acbf5e7 100644
--- a/MdePkg/Include/Protocol/FirmwareVolume2.h
+++ b/MdePkg/Include/Protocol/FirmwareVolume2.h
@@ -429,10 +429,25 @@ typedef UINT32 EFI_FV_WRITE_POLICY;
 // EFI_FV_WRITE_FILE_DATA

 //

 typedef struct {

+  ///

+  /// Pointer to a GUID, which is the file name to be written.

+  ///

   EFI_GUID                *NameGuid;

+  ///

+  /// Indicates the type of file to be written.

+  ///

   EFI_FV_FILETYPE         Type;

+  ///

+  /// Indicates the attributes for the file to be written.

+  ///

   EFI_FV_FILE_ATTRIBUTES  FileAttributes;

+  ///

+  /// Pointer to a buffer containing the file to be written.

+  ///

   VOID                    *Buffer;

+  ///

+  /// Indicates the size of the file image contained in Buffer.

+  ///

   UINT32                  BufferSize;

 } EFI_FV_WRITE_FILE_DATA;

 

diff --git a/MdePkg/Include/Protocol/GraphicsOutput.h b/MdePkg/Include/Protocol/GraphicsOutput.h
index 8e701c21ca..7782f5d7c3 100644
--- a/MdePkg/Include/Protocol/GraphicsOutput.h
+++ b/MdePkg/Include/Protocol/GraphicsOutput.h
@@ -32,19 +32,63 @@ typedef struct {
 } EFI_PIXEL_BITMASK;

 

 typedef enum {

+  ///

+  /// A pixel is 32-bits and byte zero represents red, byte one represents green, 

+  /// byte two represents blue, and byte three is reserved. This is the definition 

+  /// for the physical frame buffer. The byte values for the red, green, and blue 

+  /// components represent the color intensity. This color intensity value range 

+  /// from a minimum intensity of 0 to maximum intensity of 255.

+  ///

   PixelRedGreenBlueReserved8BitPerColor,

+  ///

+  /// A pixel is 32-bits and byte zero represents blue, byte one represents green, 

+  /// byte two represents red, and byte three is reserved. This is the definition 

+  /// for the physical frame buffer. The byte values for the red, green, and blue 

+  /// components represent the color intensity. This color intensity value range 

+  /// from a minimum intensity of 0 to maximum intensity of 255.

+  ///

   PixelBlueGreenRedReserved8BitPerColor,

+  ///

+  /// The Pixel definition of the physical frame buffer.

+  ///

   PixelBitMask,

+  ///

+  /// This mode does not support a physical frame buffer.

+  ///

   PixelBltOnly,

+  ///

+  /// Valid EFI_GRAPHICS_PIXEL_FORMAT enum values are less than this value.

+  ///

   PixelFormatMax

 } EFI_GRAPHICS_PIXEL_FORMAT;

 

 typedef struct {

+  ///

+  /// The version of this data structure. A value of zero represents the 

+  /// EFI_GRAPHICS_OUTPUT_MODE_INFORMATION structure as defined in this specification.

+  ///

   UINT32                     Version;

+  ///

+  /// The size of video screen in pixels in the X dimension.

+  ///

   UINT32                     HorizontalResolution;

+  ///

+  /// The size of video screen in pixels in the Y dimension.

+  ///

   UINT32                     VerticalResolution;

+  ///

+  /// Enumeration that defines the physical format of the pixel. A value of PixelBltOnly 

+  /// implies that a linear frame buffer is not available for this mode.

+  ///

   EFI_GRAPHICS_PIXEL_FORMAT  PixelFormat;

+  ///

+  /// This bit-mask is only valid if PixelFormat is set to PixelPixelBitMask. 

+  /// A bit being set defines what bits are used for what purpose such as Red, Green, Blue, or Reserved.

+  ///

   EFI_PIXEL_BITMASK          PixelInformation;

+  ///

+  /// Defines the number of pixel elements per video memory line.

+  /// 

   UINT32                     PixelsPerScanLine;

 } EFI_GRAPHICS_OUTPUT_MODE_INFORMATION;

 

@@ -182,11 +226,30 @@ EFI_STATUS
   );

 

 typedef struct {

+  ///

+  /// The number of modes supported by QueryMode() and SetMode().

+  ///

   UINT32                                 MaxMode;

+  ///

+  /// Current Mode of the graphics device. Valid mode numbers are 0 to MaxMode -1.

+  ///

   UINT32                                 Mode;

+  ///

+  /// Pointer to read-only EFI_GRAPHICS_OUTPUT_MODE_INFORMATION data.

+  ///

   EFI_GRAPHICS_OUTPUT_MODE_INFORMATION   *Info;

+  ///

+  /// Size of Info structure in bytes.

+  ///

   UINTN                                  SizeOfInfo;

+  ///

+  /// Base address of graphics linear frame buffer.

+  /// Offset zero in FrameBufferBase represents the upper left pixel of the display.

+  ///

   EFI_PHYSICAL_ADDRESS                   FrameBufferBase;

+  ///

+  /// Size of the frame buffer represented by FrameBufferBase in bytes.

+  ///

   UINTN                                  FrameBufferSize;

 } EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE;