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

1 files changed, 259 insertions, 20 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