Scrubbed part of the code.
authorjgong5 <jgong5@6f19259b-4bc3-4df7-8a09-765794883524>
Fri, 14 Nov 2008 09:16:11 +0000 (09:16 +0000)
committerjgong5 <jgong5@6f19259b-4bc3-4df7-8a09-765794883524>
Fri, 14 Nov 2008 09:16:11 +0000 (09:16 +0000)
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6548 6f19259b-4bc3-4df7-8a09-765794883524

MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Driver.c
MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Impl.c
MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Io.c
MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Io.h
MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Option.c
MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Option.h

index 360193e..c804172 100644 (file)
@@ -31,19 +31,23 @@ EFI_DRIVER_BINDING_PROTOCOL gDhcp4DriverBinding = {
   NULL\r
 };\r
 \r
-EFI_SERVICE_BINDING_PROTOCOL mDhcp4ServiceBindingTemplete = {\r
+EFI_SERVICE_BINDING_PROTOCOL mDhcp4ServiceBindingTemplate = {\r
   Dhcp4ServiceBindingCreateChild,\r
   Dhcp4ServiceBindingDestroyChild\r
 };\r
 \r
 /**\r
+  This is the declaration of an EFI image entry point. This entry point is\r
+  the same for UEFI Applications, UEFI OS Loaders, and UEFI Drivers including\r
+  both device drivers and bus drivers.\r
+  \r
   Entry point of the DHCP driver to install various protocols.\r
 \r
-  @param  ImageHandle            The image handle of the driver.\r
-  @param  SystemTable            The system table.\r
+  @param  ImageHandle           The firmware allocated handle for the UEFI image.\r
+  @param  SystemTable           A pointer to the EFI System Table.\r
 \r
-  @retval EFI_SUCCES             if the driver binding and component name protocols are successfully\r
-  @retval Others                 Failed to install the protocols.\r
+  @retval EFI_SUCCESS           The operation completed successfully.\r
+  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -65,15 +69,21 @@ Dhcp4DriverEntryPoint (
 \r
 \r
 /**\r
-  Test to see if DHCP driver supports the ControllerHandle.\r
-\r
-  @param  This                   Protocol instance pointer.\r
-  @param  ControllerHandle       Handle of device to test\r
-  @param  RemainingDevicePath    Optional parameter use to pick a specific child\r
-                                 device to start.\r
-\r
-  @retval EFI_SUCCES             This driver supports this device\r
-  @retval other                  This driver does not support this device\r
+  Test to see if this driver supports ControllerHandle. This service\r
+  is called by the EFI boot service ConnectController(). In\r
+  order to make drivers as small as possible, there are a few calling\r
+  restrictions for this service. ConnectController() must\r
+  follow these calling restrictions. If any other agent wishes to call\r
+  Supported() it must also follow these calling restrictions.\r
+\r
+  @param  This                Protocol instance pointer.\r
+  @param  ControllerHandle    Handle of device to test\r
+  @param  RemainingDevicePath Optional parameter use to pick a specific child\r
+                              device to start.\r
+\r
+  @retval EFI_SUCCESS         This driver supports this device\r
+  @retval EFI_ALREADY_STARTED This driver is already running on this device\r
+  @retval other               This driver does not support this device\r
 \r
 **/\r
 EFI_STATUS\r
@@ -144,12 +154,12 @@ DhcpConfigUdpIo (
 \r
 /**\r
   Destory the DHCP service. The Dhcp4 service may be partly initialized,\r
-  or partly destoried. If a resource is destoried, it is marked as so in\r
-  case the destory failed and being called again later.\r
+  or partly destroyed. If a resource is destroyed, it is marked as so in\r
+  case the destroy failed and being called again later.\r
 \r
   @param  DhcpSb                 The DHCP service instance to destory.\r
 \r
-  @retval EFI_SUCCESS            The DHCP service is successfully closed.\r
+  @retval EFI_SUCCESS            Always return success.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -187,6 +197,7 @@ Dhcp4CloseService (
 \r
   @retval EFI_OUT_OF_RESOURCES   Failed to allocate resource .\r
   @retval EFI_SUCCESS            The DHCP service instance is created.\r
+  @retval other                  Other error occurs.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -207,7 +218,6 @@ Dhcp4CreateService (
   }\r
 \r
   DhcpSb->Signature       = DHCP_SERVICE_SIGNATURE;\r
-  DhcpSb->ServiceBinding  = mDhcp4ServiceBindingTemplete;\r
   DhcpSb->ServiceState    = DHCP_UNCONFIGED;\r
   DhcpSb->InDestory       = FALSE;\r
   DhcpSb->Controller      = Controller;\r
@@ -215,7 +225,11 @@ Dhcp4CreateService (
   InitializeListHead (&DhcpSb->Children);\r
   DhcpSb->DhcpState       = Dhcp4Stopped;\r
   DhcpSb->Xid             = NET_RANDOM (NetRandomInitSeed ());\r
-\r
+  CopyMem (\r
+    &DhcpSb->ServiceBinding,\r
+    &mDhcp4ServiceBindingTemplate,\r
+    sizeof (EFI_SERVICE_BINDING_PROTOCOL)\r
+    );\r
   //\r
   // Create various resources, UdpIo, Timer, and get Mac address\r
   //\r
@@ -254,16 +268,21 @@ ON_ERROR:
 \r
 \r
 /**\r
-  Start this driver on ControllerHandle.\r
-\r
-  @param  This                   Protocol instance pointer.\r
-  @param  ControllerHandle       Handle of device to bind driver to\r
-  @param  RemainingDevicePath    Optional parameter use to pick a specific child\r
-                                 device to start.\r
-\r
-  @retval EFI_SUCCES             This driver is added to ControllerHandle\r
-  @retval EFI_ALREADY_STARTED    This driver is already running on ControllerHandle\r
-  @retval other                  This driver does not support this device\r
+  Start this driver on ControllerHandle. This service is called by the\r
+  EFI boot service ConnectController(). In order to make\r
+  drivers as small as possible, there are a few calling restrictions for\r
+  this service. ConnectController() must follow these\r
+  calling restrictions. If any other agent wishes to call Start() it\r
+  must also follow these calling restrictions.\r
+\r
+  @param  This                 Protocol instance pointer.\r
+  @param  ControllerHandle     Handle of device to bind driver to\r
+  @param  RemainingDevicePath  Optional parameter use to pick a specific child\r
+                               device to start.\r
+\r
+  @retval EFI_SUCCESS          This driver is added to ControllerHandle\r
+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle\r
+  @retval other                This driver does not support this device\r
 \r
 **/\r
 EFI_STATUS\r
@@ -329,16 +348,21 @@ ON_ERROR:
 \r
 \r
 /**\r
-  Stop this driver on ControllerHandle.\r
-\r
-  @param  This                   Protocol instance pointer.\r
-  @param  ControllerHandle       Handle of device to stop driver on\r
-  @param  NumberOfChildren       Number of Handles in ChildHandleBuffer. If number\r
-                                 of  children is zero stop the entire bus driver.\r
-  @param  ChildHandleBuffer      List of Child Handles to Stop.\r
-\r
-  @retval EFI_SUCCES             This driver is removed ControllerHandle\r
-  @retval other                  This driver was not removed from this device\r
+  Stop this driver on ControllerHandle. This service is called by the\r
+  EFI boot service DisconnectController(). In order to\r
+  make drivers as small as possible, there are a few calling\r
+  restrictions for this service. DisconnectController()\r
+  must follow these calling restrictions. If any other agent wishes\r
+  to call Stop() it must also follow these calling restrictions.\r
+  \r
+  @param  This              Protocol instance pointer.\r
+  @param  ControllerHandle  Handle of device to stop driver on\r
+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of\r
+                            children is zero stop the entire bus driver.\r
+  @param  ChildHandleBuffer List of Child Handles to Stop.\r
+\r
+  @retval EFI_SUCCESS       This driver is removed ControllerHandle\r
+  @retval other             This driver was not removed from this device\r
 \r
 **/\r
 EFI_STATUS\r
@@ -424,7 +448,7 @@ Dhcp4DriverBindingStop (
 \r
 \r
 /**\r
-  Initialize a new DHCP child.\r
+  Initialize a new DHCP instance.\r
 \r
   @param  DhcpSb                 The dhcp service instance\r
   @param  Instance               The dhcp instance to initialize\r
@@ -434,8 +458,8 @@ Dhcp4DriverBindingStop (
 **/\r
 VOID\r
 DhcpInitProtocol (\r
-  IN DHCP_SERVICE           *DhcpSb,\r
-  IN DHCP_PROTOCOL          *Instance\r
+  IN     DHCP_SERVICE           *DhcpSb,\r
+  IN OUT DHCP_PROTOCOL          *Instance\r
   )\r
 {\r
   Instance->Signature         = DHCP_PROTOCOL_SIGNATURE;\r
@@ -453,18 +477,18 @@ DhcpInitProtocol (
 \r
 \r
 /**\r
-  Creates a child handle with a set of DHCP4 services.\r
+  Creates a child handle with a set of I/O services.\r
 \r
-  @param  This                   Protocol instance pointer.\r
-  @param  ChildHandle            Pointer to the handle of the child to create.  If\r
-                                 it  is NULL, then a new handle is created.  If it\r
-                                 is not  NULL, then the DHCP4 services are added to\r
-                                 the existing  child handle.\r
+  @param  This        Protocol instance pointer.\r
+  @param  ChildHandle Pointer to the handle of the child to create.  If it is NULL,\r
+                      then a new handle is created.  If it is not NULL, then the\r
+                      I/O services are added to the existing child handle.\r
 \r
-  @retval EFI_SUCCES             The child handle was created with the DHCP4\r
-                                 services\r
-  @retval EFI_OUT_OF_RESOURCES   There are not enough resources to create the child\r
-  @retval other                  The child handle was not created\r
+  @retval EFI_SUCCES            The child handle was created with the I/O services\r
+  @retval EFI_INVALID_PARAMETER ChildHandle is NULL.\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough resources availabe to create\r
+                                the child\r
+  @retval other                 The child handle was not created\r
 \r
 **/\r
 EFI_STATUS\r
@@ -545,18 +569,18 @@ Dhcp4ServiceBindingCreateChild (
 \r
 \r
 /**\r
-  Destroys a child handle with a set of DHCP4 services.\r
+  Destroys a child handle with a set of I/O services.\r
 \r
-  @param  This                   Protocol instance pointer.\r
-  @param  ChildHandle            Handle of the child to destroy\r
+  @param  This        Protocol instance pointer.\r
+  @param  ChildHandle Handle of the child to destroy\r
 \r
-  @retval EFI_SUCCES             The DHCP4 service is removed from the child handle\r
-  @retval EFI_UNSUPPORTED        The child handle does not support the DHCP4\r
-                                 service\r
-  @retval EFI_INVALID_PARAMETER  Child handle is not a valid EFI Handle.\r
-  @retval EFI_ACCESS_DENIED      The child handle could not be destroyed because\r
-                                 its  DHCP4 services are being used.\r
-  @retval other                  The child handle was not destroyed\r
+  @retval EFI_SUCCES            The I/O services were removed from the child handle\r
+  @retval EFI_UNSUPPORTED       The child handle does not support the I/O services\r
+                                that are being removed.\r
+  @retval EFI_INVALID_PARAMETER Child handle is not a valid EFI Handle.\r
+  @retval EFI_ACCESS_DENIED     The child handle could not be destroyed because its\r
+                                I/O services are being used.\r
+  @retval other                 The child handle was not destroyed\r
 \r
 **/\r
 EFI_STATUS\r
@@ -600,8 +624,8 @@ Dhcp4ServiceBindingDestroyChild (
   }\r
 \r
   //\r
-  // A child can be destoried more than once. For example,\r
-  // Dhcp4DriverBindingStop will destory all of its children.\r
+  // A child can be destroyed more than once. For example,\r
+  // Dhcp4DriverBindingStop will destroy all of its children.\r
   // when caller driver is being stopped, it will destory the\r
   // dhcp child it opens.\r
   //\r
index 6097f0d..d4ca364 100644 (file)
@@ -23,16 +23,340 @@ Abstract:
 \r
 #include "Dhcp4Impl.h"\r
 \r
+/**\r
+  Returns the current operating mode and cached data packet for the EFI DHCPv4 Protocol driver.\r
+  \r
+  The GetModeData() function returns the current operating mode and cached data\r
+  packet for the EFI DHCPv4 Protocol driver.\r
+\r
+  @param  This          Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  Dhcp4ModeData Pointer to storage for the EFI_DHCP4_MODE_DATA structure.\r
+\r
+  @retval EFI_SUCCESS           The mode data was returned.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiDhcp4GetModeData (\r
+  IN  EFI_DHCP4_PROTOCOL    *This,\r
+  OUT EFI_DHCP4_MODE_DATA   *Dhcp4ModeData\r
+  );\r
+\r
+/**\r
+  Initializes, changes, or resets the operational settings for the EFI DHCPv4 Protocol driver.\r
+\r
+  The Configure() function is used to initialize, change, or reset the operational\r
+  settings of the EFI DHCPv4 Protocol driver for the communication device on which\r
+  the EFI DHCPv4 Service Binding Protocol is installed. This function can be\r
+  successfully called only if both of the following are true:\r
+  * This instance of the EFI DHCPv4 Protocol driver is in the Dhcp4Stopped, Dhcp4Init,\r
+    Dhcp4InitReboot, or Dhcp4Bound states.\r
+  * No other EFI DHCPv4 Protocol driver instance that is controlled by this EFI\r
+    DHCPv4 Service Binding Protocol driver instance has configured this EFI DHCPv4\r
+    Protocol driver.\r
+  When this driver is in the Dhcp4Stopped state, it can transfer into one of the\r
+  following two possible initial states:\r
+  * Dhcp4Init\r
+  * Dhcp4InitReboot\r
+  The driver can transfer into these states by calling Configure() with a non-NULL\r
+  Dhcp4CfgData. The driver will transfer into the appropriate state based on the\r
+  supplied client network address in the ClientAddress parameter and DHCP options\r
+  in the OptionList parameter as described in RFC 2131.\r
+  When Configure() is called successfully while Dhcp4CfgData is set to NULL, the\r
+  default configuring data will be reset in the EFI DHCPv4 Protocol driver and\r
+  the state of the EFI DHCPv4 Protocol driver will not be changed. If one instance\r
+  wants to make it possible for another instance to configure the EFI DHCPv4 Protocol\r
+  driver, it must call this function with Dhcp4CfgData set to NULL.\r
+\r
+  @param  This                   Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  Dhcp4CfgData           Pointer to the EFI_DHCP4_CONFIG_DATA.\r
+\r
+  @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Init or\r
+                                Dhcp4InitReboot state, if the original state of this driver\r
+                                was Dhcp4Stopped and the value of Dhcp4CfgData was\r
+                                not NULL. Otherwise, the state was left unchanged.\r
+  @retval EFI_ACCESS_DENIED     This instance of the EFI DHCPv4 Protocol driver was not in the\r
+                                Dhcp4Stopped, Dhcp4Init, Dhcp4InitReboot, or Dhcp4Bound state;\r
+                                Or onother instance of this EFI DHCPv4 Protocol driver is already\r
+                                in a valid configured state.\r
+  @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+  @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.\r
+  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiDhcp4Configure (\r
+  IN EFI_DHCP4_PROTOCOL     *This,\r
+  IN EFI_DHCP4_CONFIG_DATA  *Dhcp4CfgData       OPTIONAL\r
+  );  \r
+\r
+/**\r
+  Starts the DHCP configuration process.\r
+\r
+  The Start() function starts the DHCP configuration process. This function can\r
+  be called only when the EFI DHCPv4 Protocol driver is in the Dhcp4Init or\r
+  Dhcp4InitReboot state.\r
+  If the DHCP process completes successfully, the state of the EFI DHCPv4 Protocol\r
+  driver will be transferred through Dhcp4Selecting and Dhcp4Requesting to the\r
+  Dhcp4Bound state. The CompletionEvent will then be signaled if it is not NULL.\r
+  If the process aborts, either by the user or by some unexpected network error,\r
+  the state is restored to the Dhcp4Init state. The Start() function can be called\r
+  again to restart the process.\r
+  Refer to RFC 2131 for precise state transitions during this process. At the\r
+  time when each event occurs in this process, the callback function that was set\r
+  by EFI_DHCP4_PROTOCOL.Configure() will be called and the user can take this\r
+  opportunity to control the process.\r
+  \r
+  @param  This            Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  CompletionEvent If not NULL, indicates the event that will be signaled when the\r
+                          EFI DHCPv4 Protocol driver is transferred into the\r
+                          Dhcp4Bound state or when the DHCP process is aborted.\r
+                          EFI_DHCP4_PROTOCOL.GetModeData() can be called to\r
+                          check the completion status. If NULL,\r
+                          EFI_DHCP4_PROTOCOL.Start() will wait until the driver\r
+                          is transferred into the Dhcp4Bound state or the process fails.\r
+\r
+  @retval EFI_SUCCESS           The DHCP configuration process has started, or it has completed\r
+                                when CompletionEvent is NULL.\r
+  @retval EFI_NOT_STARTED       The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped\r
+                                state. EFI_DHCP4_PROTOCOL. Configure() needs to be called.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+  @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.\r
+  @retval EFI_TIMEOUT           The DHCP configuration process failed because no response was\r
+                                received from the server within the specified timeout value.\r
+  @retval EFI_ABORTED           The user aborted the DHCP process.\r
+  @retval EFI_ALREADY_STARTED   Some other EFI DHCPv4 Protocol instance already started the\r
+                                DHCP process.\r
+  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiDhcp4Start (\r
+  IN EFI_DHCP4_PROTOCOL     *This,\r
+  IN EFI_EVENT              CompletionEvent   OPTIONAL\r
+  );\r
+\r
+/**\r
+  Extends the lease time by sending a request packet.\r
+  \r
+  The RenewRebind() function is used to manually extend the lease time when the\r
+  EFI DHCPv4 Protocol driver is in the Dhcp4Bound state and the lease time has\r
+  not expired yet. This function will send a request packet to the previously\r
+  found server (or to any server when RebindRequest is TRUE) and transfer the\r
+  state into the Dhcp4Renewing state (or Dhcp4Rebinding when RebindingRequest is\r
+  TRUE). When a response is received, the state is returned to Dhcp4Bound.\r
+  If no response is received before the try count is exceeded (the RequestTryCount\r
+  field that is specified in EFI_DHCP4_CONFIG_DATA) but before the lease time that\r
+  was issued by the previous server expires, the driver will return to the Dhcp4Bound\r
+  state and the previous configuration is restored. The outgoing and incoming packets\r
+  can be captured by the EFI_DHCP4_CALLBACK function.\r
+\r
+  @param  This            Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  RebindRequest   If TRUE, this function broadcasts the request packets and enters\r
+                          the Dhcp4Rebinding state. Otherwise, it sends a unicast\r
+                          request packet and enters the Dhcp4Renewing state.\r
+  @param  CompletionEvent If not NULL, this event is signaled when the renew/rebind phase\r
+                          completes or some error occurs.\r
+                          EFI_DHCP4_PROTOCOL.GetModeData() can be called to\r
+                          check the completion status. If NULL,\r
+                          EFI_DHCP4_PROTOCOL.RenewRebind() will busy-wait\r
+                          until the DHCP process finishes.\r
+\r
+  @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the\r
+                                Dhcp4Renewing state or is back to the Dhcp4Bound state.\r
+  @retval EFI_NOT_STARTED       The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped\r
+                                state. EFI_DHCP4_PROTOCOL.Configure() needs to\r
+                                be called.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+  @retval EFI_TIMEOUT           There was no response from the server when the try count was\r
+                                exceeded.\r
+  @retval EFI_ACCESS_DENIED     The driver is not in the Dhcp4Bound state.\r
+  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiDhcp4RenewRebind (\r
+  IN EFI_DHCP4_PROTOCOL     *This,\r
+  IN BOOLEAN                RebindRequest,\r
+  IN EFI_EVENT              CompletionEvent   OPTIONAL\r
+  );\r
+\r
+/**\r
+  Releases the current address configuration.\r
+\r
+  The Release() function releases the current configured IP address by doing either\r
+  of the following:\r
+  * Sending a DHCPRELEASE packet when the EFI DHCPv4 Protocol driver is in the\r
+    Dhcp4Bound state\r
+  * Setting the previously assigned IP address that was provided with the\r
+    EFI_DHCP4_PROTOCOL.Configure() function to 0.0.0.0 when the driver is in\r
+    Dhcp4InitReboot state\r
+  After a successful call to this function, the EFI DHCPv4 Protocol driver returns\r
+  to the Dhcp4Init state and any subsequent incoming packets will be discarded silently.\r
+\r
+  @param  This                  Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+\r
+  @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Init phase.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+  @retval EFI_ACCESS_DENIED     The EFI DHCPv4 Protocol driver is not Dhcp4InitReboot state.\r
+  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiDhcp4Release (\r
+  IN EFI_DHCP4_PROTOCOL     *This\r
+  );\r
+\r
+/**\r
+  Stops the current address configuration.\r
+  \r
+  The Stop() function is used to stop the DHCP configuration process. After this\r
+  function is called successfully, the EFI DHCPv4 Protocol driver is transferred\r
+  into the Dhcp4Stopped state. EFI_DHCP4_PROTOCOL.Configure() needs to be called\r
+  before DHCP configuration process can be started again. This function can be\r
+  called when the EFI DHCPv4 Protocol driver is in any state.\r
+\r
+  @param  This                  Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+\r
+  @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Stopped phase.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiDhcp4Stop (\r
+  IN EFI_DHCP4_PROTOCOL     *This\r
+  );\r
+\r
+/**\r
+  Builds a DHCP packet, given the options to be appended or deleted or replaced.\r
+\r
+  The Build() function is used to assemble a new packet from the original packet\r
+  by replacing or deleting existing options or appending new options. This function\r
+  does not change any state of the EFI DHCPv4 Protocol driver and can be used at\r
+  any time.\r
+\r
+  @param  This        Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  SeedPacket  Initial packet to be used as a base for building new packet.\r
+  @param  DeleteCount Number of opcodes in the DeleteList.\r
+  @param  DeleteList  List of opcodes to be deleted from the seed packet.\r
+                      Ignored if DeleteCount is zero.\r
+  @param  AppendCount Number of entries in the OptionList.\r
+  @param  AppendList  Pointer to a DHCP option list to be appended to SeedPacket.\r
+                      If SeedPacket also contains options in this list, they are\r
+                      replaced by new options (except pad option). Ignored if\r
+                      AppendCount is zero. Type EFI_DHCP4_PACKET_OPTION\r
+  @param  NewPacket   Pointer to storage for the pointer to the new allocated packet.\r
+                      Use the EFI Boot Service FreePool() on the resulting pointer\r
+                      when done with the packet.\r
+\r
+  @retval EFI_SUCCESS           The new packet was built.\r
+  @retval EFI_OUT_OF_RESOURCES  Storage for the new packet could not be allocated.\r
+  @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiDhcp4Build (\r
+  IN EFI_DHCP4_PROTOCOL       *This,\r
+  IN EFI_DHCP4_PACKET         *SeedPacket,\r
+  IN UINT32                   DeleteCount,\r
+  IN UINT8                    *DeleteList OPTIONAL,\r
+  IN UINT32                   AppendCount,\r
+  IN EFI_DHCP4_PACKET_OPTION  *AppendList[] OPTIONAL,\r
+  OUT EFI_DHCP4_PACKET        **NewPacket\r
+  );\r
+  \r
+  /**\r
+  Transmits a DHCP formatted packet and optionally waits for responses.\r
+  \r
+  The TransmitReceive() function is used to transmit a DHCP packet and optionally\r
+  wait for the response from servers. This function does not change the state of\r
+  the EFI DHCPv4 Protocol driver and thus can be used at any time.\r
+\r
+  @param  This    Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  Token   Pointer to the EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN structure.\r
+\r
+  @retval EFI_SUCCESS           The packet was successfully queued for transmission.\r
+  @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+  @retval EFI_NOT_READY         The previous call to this function has not finished yet. Try to call\r
+                                this function after collection process completes.\r
+  @retval EFI_NO_MAPPING        The default station address is not available yet.\r
+  @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.\r
+  @retval Others                Some other unexpected error occurred.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiDhcp4TransmitReceive (\r
+  IN EFI_DHCP4_PROTOCOL                *This,\r
+  IN EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN  *Token\r
+  );\r
+\r
+/**\r
+  Parses the packed DHCP option data.\r
+  \r
+  The Parse() function is used to retrieve the option list from a DHCP packet.\r
+  If *OptionCount isn’t zero, and there is enough space for all the DHCP options\r
+  in the Packet, each element of PacketOptionList is set to point to somewhere in\r
+  the Packet->Dhcp4.Option where a new DHCP option begins. If RFC3396 is supported,\r
+  the caller should reassemble the parsed DHCP options to get the finial result.\r
+  If *OptionCount is zero or there isn’t enough space for all of them, the number\r
+  of DHCP options in the Packet is returned in OptionCount.\r
+\r
+  @param  This             Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  Packet           Pointer to packet to be parsed.\r
+  @param  OptionCount      On input, the number of entries in the PacketOptionList.\r
+                           On output, the number of entries that were written into the\r
+                           PacketOptionList.\r
+  @param  PacketOptionList List of packet option entries to be filled in. End option or pad\r
+                           options are not included.\r
+\r
+  @retval EFI_SUCCESS           The packet was successfully parsed.\r
+  @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+  @retval EFI_BUFFER_TOO_SMALL  One or more of the following conditions is TRUE:\r
+                                1) *OptionCount is smaller than the number of options that\r
+                                were found in the Packet.\r
+                                2) PacketOptionList is NULL.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiDhcp4Parse (\r
+  IN EFI_DHCP4_PROTOCOL       *This,\r
+  IN EFI_DHCP4_PACKET         *Packet,\r
+  IN OUT UINT32               *OptionCount,\r
+  OUT EFI_DHCP4_PACKET_OPTION *PacketOptionList[] OPTIONAL\r
+  );\r
+\r
+EFI_DHCP4_PROTOCOL  mDhcp4ProtocolTemplate = {\r
+  EfiDhcp4GetModeData,\r
+  EfiDhcp4Configure,\r
+  EfiDhcp4Start,\r
+  EfiDhcp4RenewRebind,\r
+  EfiDhcp4Release,\r
+  EfiDhcp4Stop,\r
+  EfiDhcp4Build,\r
+  EfiDhcp4TransmitReceive,\r
+  EfiDhcp4Parse\r
+};\r
 \r
 /**\r
-  Get the current operation parameter and lease for the network interface.\r
+  Returns the current operating mode and cached data packet for the EFI DHCPv4 Protocol driver.\r
+  \r
+  The GetModeData() function returns the current operating mode and cached data\r
+  packet for the EFI DHCPv4 Protocol driver.\r
 \r
-  @param  This                   The DHCP protocol instance\r
-  @param  Dhcp4ModeData          The variable to save the DHCP mode data.\r
+  @param  This          Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  Dhcp4ModeData Pointer to storage for the EFI_DHCP4_MODE_DATA structure.\r
 \r
-  @retval EFI_INVALID_PARAMETER  The parameter is invalid\r
-  @retval EFI_SUCCESS            The Dhcp4ModeData is updated with the current\r
-                                 operation parameter.\r
+  @retval EFI_SUCCESS           The mode data was returned.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -64,7 +388,7 @@ EfiDhcp4GetModeData (
   // Caller can use GetModeData to retrieve current DHCP states\r
   // no matter whether it is the active child or not.\r
   //\r
-  Dhcp4ModeData->State                     = (EFI_DHCP4_STATE) DhcpSb->DhcpState;\r
+  Dhcp4ModeData->State = (EFI_DHCP4_STATE) DhcpSb->DhcpState;\r
   CopyMem (&Dhcp4ModeData->ConfigData, &DhcpSb->ActiveConfig, sizeof (Dhcp4ModeData->ConfigData));\r
   CopyMem (&Dhcp4ModeData->ClientMacAddress, &DhcpSb->Mac, sizeof (Dhcp4ModeData->ClientMacAddress));\r
 \r
@@ -82,10 +406,10 @@ EfiDhcp4GetModeData (
   if (Para != NULL) {\r
     Ip = HTONL (Para->Router);\r
     CopyMem (&Dhcp4ModeData->RouterAddress, &Ip, sizeof (EFI_IPv4_ADDRESS));\r
-    Dhcp4ModeData->LeaseTime               = Para->Lease;\r
+    Dhcp4ModeData->LeaseTime = Para->Lease;\r
   } else {\r
     ZeroMem (&Dhcp4ModeData->RouterAddress, sizeof (EFI_IPv4_ADDRESS));\r
-    Dhcp4ModeData->LeaseTime               = 0xffffffff;\r
+    Dhcp4ModeData->LeaseTime = 0xffffffff;\r
   }\r
 \r
   Dhcp4ModeData->ReplyPacket = DhcpSb->Selected;\r
@@ -107,7 +431,7 @@ EfiDhcp4GetModeData (
 **/\r
 VOID\r
 DhcpCleanConfigure (\r
-  IN EFI_DHCP4_CONFIG_DATA  *Config\r
+  IN OUT EFI_DHCP4_CONFIG_DATA  *Config\r
   )\r
 {\r
   UINT32                    Index;\r
@@ -147,8 +471,8 @@ DhcpCleanConfigure (
 **/\r
 EFI_STATUS\r
 DhcpCopyConfigure (\r
-  IN EFI_DHCP4_CONFIG_DATA  *Dst,\r
-  IN EFI_DHCP4_CONFIG_DATA  *Src\r
+  OUT EFI_DHCP4_CONFIG_DATA  *Dst,\r
+  IN  EFI_DHCP4_CONFIG_DATA  *Src\r
   )\r
 {\r
   EFI_DHCP4_PACKET_OPTION   **DstOptions;\r
@@ -271,18 +595,45 @@ DhcpYieldControl (
 \r
 \r
 /**\r
-  Configure the DHCP protocol instance and its underlying DHCP service\r
-  for operation. If Dhcp4CfgData is NULL and the child is currently\r
-  controlling the DHCP service, release the control.\r
-\r
-  @param  This                   The DHCP protocol instance\r
-  @param  Dhcp4CfgData           The DHCP configure data.\r
-\r
-  @retval EFI_INVALID_PARAMETER  The parameters are invalid.\r
-  @retval EFI_ACCESS_DENIED      The service isn't in one of configurable states,\r
-                                 or there is already an active child.\r
-  @retval EFI_OUT_OF_RESOURCE    Failed to allocate some resources.\r
-  @retval EFI_SUCCESS            The child is configured.\r
+  Initializes, changes, or resets the operational settings for the EFI DHCPv4 Protocol driver.\r
+\r
+  The Configure() function is used to initialize, change, or reset the operational\r
+  settings of the EFI DHCPv4 Protocol driver for the communication device on which\r
+  the EFI DHCPv4 Service Binding Protocol is installed. This function can be\r
+  successfully called only if both of the following are true:\r
+  * This instance of the EFI DHCPv4 Protocol driver is in the Dhcp4Stopped, Dhcp4Init,\r
+    Dhcp4InitReboot, or Dhcp4Bound states.\r
+  * No other EFI DHCPv4 Protocol driver instance that is controlled by this EFI\r
+    DHCPv4 Service Binding Protocol driver instance has configured this EFI DHCPv4\r
+    Protocol driver.\r
+  When this driver is in the Dhcp4Stopped state, it can transfer into one of the\r
+  following two possible initial states:\r
+  * Dhcp4Init\r
+  * Dhcp4InitReboot\r
+  The driver can transfer into these states by calling Configure() with a non-NULL\r
+  Dhcp4CfgData. The driver will transfer into the appropriate state based on the\r
+  supplied client network address in the ClientAddress parameter and DHCP options\r
+  in the OptionList parameter as described in RFC 2131.\r
+  When Configure() is called successfully while Dhcp4CfgData is set to NULL, the\r
+  default configuring data will be reset in the EFI DHCPv4 Protocol driver and\r
+  the state of the EFI DHCPv4 Protocol driver will not be changed. If one instance\r
+  wants to make it possible for another instance to configure the EFI DHCPv4 Protocol\r
+  driver, it must call this function with Dhcp4CfgData set to NULL.\r
+\r
+  @param  This                   Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  Dhcp4CfgData           Pointer to the EFI_DHCP4_CONFIG_DATA.\r
+\r
+  @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Init or\r
+                                Dhcp4InitReboot state, if the original state of this driver\r
+                                was Dhcp4Stopped and the value of Dhcp4CfgData was\r
+                                not NULL. Otherwise, the state was left unchanged.\r
+  @retval EFI_ACCESS_DENIED     This instance of the EFI DHCPv4 Protocol driver was not in the\r
+                                Dhcp4Stopped, Dhcp4Init, Dhcp4InitReboot, or Dhcp4Bound state;\r
+                                Or onother instance of this EFI DHCPv4 Protocol driver is already\r
+                                in a valid configured state.\r
+  @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+  @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.\r
+  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -394,15 +745,43 @@ ON_EXIT:
 \r
 \r
 /**\r
-  Start the DHCP process.\r
-\r
-  @param  This                   The DHCP protocol instance\r
-  @param  CompletionEvent        The event to signal is address is acquired.\r
-\r
-  @retval EFI_INVALID_PARAMETER  The parameters are invalid.\r
-  @retval EFI_NOT_STARTED        The protocol hasn't been configured.\r
-  @retval EFI_ALREADY_STARTED    The DHCP process has already been started.\r
-  @retval EFI_SUCCESS            The DHCP process is started.\r
+  Starts the DHCP configuration process.\r
+\r
+  The Start() function starts the DHCP configuration process. This function can\r
+  be called only when the EFI DHCPv4 Protocol driver is in the Dhcp4Init or\r
+  Dhcp4InitReboot state.\r
+  If the DHCP process completes successfully, the state of the EFI DHCPv4 Protocol\r
+  driver will be transferred through Dhcp4Selecting and Dhcp4Requesting to the\r
+  Dhcp4Bound state. The CompletionEvent will then be signaled if it is not NULL.\r
+  If the process aborts, either by the user or by some unexpected network error,\r
+  the state is restored to the Dhcp4Init state. The Start() function can be called\r
+  again to restart the process.\r
+  Refer to RFC 2131 for precise state transitions during this process. At the\r
+  time when each event occurs in this process, the callback function that was set\r
+  by EFI_DHCP4_PROTOCOL.Configure() will be called and the user can take this\r
+  opportunity to control the process.\r
+  \r
+  @param  This            Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  CompletionEvent If not NULL, indicates the event that will be signaled when the\r
+                          EFI DHCPv4 Protocol driver is transferred into the\r
+                          Dhcp4Bound state or when the DHCP process is aborted.\r
+                          EFI_DHCP4_PROTOCOL.GetModeData() can be called to\r
+                          check the completion status. If NULL,\r
+                          EFI_DHCP4_PROTOCOL.Start() will wait until the driver\r
+                          is transferred into the Dhcp4Bound state or the process fails.\r
+\r
+  @retval EFI_SUCCESS           The DHCP configuration process has started, or it has completed\r
+                                when CompletionEvent is NULL.\r
+  @retval EFI_NOT_STARTED       The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped\r
+                                state. EFI_DHCP4_PROTOCOL. Configure() needs to be called.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+  @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.\r
+  @retval EFI_TIMEOUT           The DHCP configuration process failed because no response was\r
+                                received from the server within the specified timeout value.\r
+  @retval EFI_ABORTED           The user aborted the DHCP process.\r
+  @retval EFI_ALREADY_STARTED   Some other EFI DHCPv4 Protocol instance already started the\r
+                                DHCP process.\r
+  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -482,16 +861,41 @@ ON_ERROR:
 \r
 \r
 /**\r
-  Request an extra manual renew/rebind.\r
-\r
-  @param  This                   The DHCP protocol instance\r
-  @param  RebindRequest          TRUE if request a rebind, otherwise renew it\r
-  @param  CompletionEvent        Event to signal when complete\r
-\r
-  @retval EFI_INVALID_PARAMETER  The parameters are invalid\r
-  @retval EFI_NOT_STARTED        The DHCP protocol hasn't been started.\r
-  @retval EFI_ACCESS_DENIED      The DHCP protocol isn't in Bound state.\r
-  @retval EFI_SUCCESS            The DHCP is renewed/rebound.\r
+  Extends the lease time by sending a request packet.\r
+  \r
+  The RenewRebind() function is used to manually extend the lease time when the\r
+  EFI DHCPv4 Protocol driver is in the Dhcp4Bound state and the lease time has\r
+  not expired yet. This function will send a request packet to the previously\r
+  found server (or to any server when RebindRequest is TRUE) and transfer the\r
+  state into the Dhcp4Renewing state (or Dhcp4Rebinding when RebindingRequest is\r
+  TRUE). When a response is received, the state is returned to Dhcp4Bound.\r
+  If no response is received before the try count is exceeded (the RequestTryCount\r
+  field that is specified in EFI_DHCP4_CONFIG_DATA) but before the lease time that\r
+  was issued by the previous server expires, the driver will return to the Dhcp4Bound\r
+  state and the previous configuration is restored. The outgoing and incoming packets\r
+  can be captured by the EFI_DHCP4_CALLBACK function.\r
+\r
+  @param  This            Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  RebindRequest   If TRUE, this function broadcasts the request packets and enters\r
+                          the Dhcp4Rebinding state. Otherwise, it sends a unicast\r
+                          request packet and enters the Dhcp4Renewing state.\r
+  @param  CompletionEvent If not NULL, this event is signaled when the renew/rebind phase\r
+                          completes or some error occurs.\r
+                          EFI_DHCP4_PROTOCOL.GetModeData() can be called to\r
+                          check the completion status. If NULL,\r
+                          EFI_DHCP4_PROTOCOL.RenewRebind() will busy-wait\r
+                          until the DHCP process finishes.\r
+\r
+  @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the\r
+                                Dhcp4Renewing state or is back to the Dhcp4Bound state.\r
+  @retval EFI_NOT_STARTED       The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped\r
+                                state. EFI_DHCP4_PROTOCOL.Configure() needs to\r
+                                be called.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+  @retval EFI_TIMEOUT           There was no response from the server when the try count was\r
+                                exceeded.\r
+  @retval EFI_ACCESS_DENIED     The driver is not in the Dhcp4Bound state.\r
+  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -582,15 +986,24 @@ ON_ERROR:
 \r
 \r
 /**\r
-  Release the current acquired lease.\r
+  Releases the current address configuration.\r
+\r
+  The Release() function releases the current configured IP address by doing either\r
+  of the following:\r
+  * Sending a DHCPRELEASE packet when the EFI DHCPv4 Protocol driver is in the\r
+    Dhcp4Bound state\r
+  * Setting the previously assigned IP address that was provided with the\r
+    EFI_DHCP4_PROTOCOL.Configure() function to 0.0.0.0 when the driver is in\r
+    Dhcp4InitReboot state\r
+  After a successful call to this function, the EFI DHCPv4 Protocol driver returns\r
+  to the Dhcp4Init state and any subsequent incoming packets will be discarded silently.\r
 \r
-  @param  This                   The DHCP protocol instance\r
+  @param  This                  Pointer to the EFI_DHCP4_PROTOCOL instance.\r
 \r
-  @retval EFI_INVALID_PARAMETER  The parameter is invalid\r
-  @retval EFI_DEVICE_ERROR       Failed to transmit the DHCP release packet\r
-  @retval EFI_ACCESS_DENIED      The DHCP service isn't in one of the connected\r
-                                 state.\r
-  @retval EFI_SUCCESS            The lease is released.\r
+  @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Init phase.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+  @retval EFI_ACCESS_DENIED     The EFI DHCPv4 Protocol driver is not Dhcp4InitReboot state.\r
+  @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -650,13 +1063,18 @@ ON_EXIT:
 \r
 \r
 /**\r
-  Stop the current DHCP process. After this, other DHCP child\r
-  can gain control of the service, configure and use it.\r
+  Stops the current address configuration.\r
+  \r
+  The Stop() function is used to stop the DHCP configuration process. After this\r
+  function is called successfully, the EFI DHCPv4 Protocol driver is transferred\r
+  into the Dhcp4Stopped state. EFI_DHCP4_PROTOCOL.Configure() needs to be called\r
+  before DHCP configuration process can be started again. This function can be\r
+  called when the EFI DHCPv4 Protocol driver is in any state.\r
 \r
-  @param  This                   The DHCP protocol instance\r
+  @param  This                  Pointer to the EFI_DHCP4_PROTOCOL instance.\r
 \r
-  @retval EFI_INVALID_PARAMETER  The parameter is invalid.\r
-  @retval EFI_SUCCESS            The DHCP process is stopped.\r
+  @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Stopped phase.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -696,21 +1114,30 @@ EfiDhcp4Stop (
 \r
 \r
 /**\r
-  Build a new DHCP packet from the seed packet. Options may be deleted or\r
-  appended. The caller should free the NewPacket when finished using it.\r
-\r
-  @param  This                   The DHCP protocol instance.\r
-  @param  SeedPacket             The seed packet to start with\r
-  @param  DeleteCount            The number of options to delete\r
-  @param  DeleteList             The options to delete from the packet\r
-  @param  AppendCount            The number of options to append\r
-  @param  AppendList             The options to append to the packet\r
-  @param  NewPacket              The new packet, allocated and built by this\r
-                                 function.\r
-\r
-  @retval EFI_INVALID_PARAMETER  The parameters are invalid.\r
-  @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory\r
-  @retval EFI_SUCCESS            The packet is build.\r
+  Builds a DHCP packet, given the options to be appended or deleted or replaced.\r
+\r
+  The Build() function is used to assemble a new packet from the original packet\r
+  by replacing or deleting existing options or appending new options. This function\r
+  does not change any state of the EFI DHCPv4 Protocol driver and can be used at\r
+  any time.\r
+\r
+  @param  This        Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  SeedPacket  Initial packet to be used as a base for building new packet.\r
+  @param  DeleteCount Number of opcodes in the DeleteList.\r
+  @param  DeleteList  List of opcodes to be deleted from the seed packet.\r
+                      Ignored if DeleteCount is zero.\r
+  @param  AppendCount Number of entries in the OptionList.\r
+  @param  AppendList  Pointer to a DHCP option list to be appended to SeedPacket.\r
+                      If SeedPacket also contains options in this list, they are\r
+                      replaced by new options (except pad option). Ignored if\r
+                      AppendCount is zero. Type EFI_DHCP4_PACKET_OPTION\r
+  @param  NewPacket   Pointer to storage for the pointer to the new allocated packet.\r
+                      Use the EFI Boot Service FreePool() on the resulting pointer\r
+                      when done with the packet.\r
+\r
+  @retval EFI_SUCCESS           The new packet was built.\r
+  @retval EFI_OUT_OF_RESOURCES  Storage for the new packet could not be allocated.\r
+  @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -755,6 +1182,15 @@ EfiDhcp4Build (
            );\r
 }\r
 \r
+/**\r
+  Callback by UdpIoCreatePort() when creating UdpIo for this Dhcp4 instance.\r
+  \r
+  @param UdpIo      The UdpIo being created.\r
+  @param Context    Dhcp4 instance.\r
+  \r
+  @retval EFI_SUCCESS   UdpIo is configured successfully.\r
+  @retval other         Other error occurs.\r
+**/\r
 EFI_STATUS\r
 Dhcp4InstanceConfigUdpIo (\r
   IN UDP_IO_PORT  *UdpIo,\r
@@ -793,9 +1229,18 @@ Dhcp4InstanceConfigUdpIo (
   return UdpIo->Udp->Configure (UdpIo->Udp, &UdpConfigData);\r
 }\r
 \r
+/**\r
+  Create UdpIo for this Dhcp4 instance.\r
+  \r
+  @param Instance   The Dhcp4 instance.\r
+  \r
+  @retval EFI_SUCCESS                UdpIo is created successfully.\r
+  @retval EFI_OUT_OF_RESOURCES       Fails to create UdpIo because of limited\r
+                                     resources or configuration failure.\r
+**/\r
 EFI_STATUS\r
 Dhcp4InstanceCreateUdpIo (\r
-  IN DHCP_PROTOCOL  *Instance\r
+  IN OUT DHCP_PROTOCOL  *Instance\r
   )\r
 {\r
   DHCP_SERVICE  *DhcpSb;\r
@@ -811,28 +1256,34 @@ Dhcp4InstanceCreateUdpIo (
   }\r
 }\r
 \r
+/**\r
+  Callback of Dhcp packet. Does nothing.\r
+  \r
+  @param Arg           The context.\r
+  \r
+  @return  None.\r
+**/\r
 VOID\r
 DhcpDummyExtFree (\r
   IN VOID                   *Arg\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  Release the packet.\r
-\r
-Arguments:\r
-\r
-  Arg - The packet to release\r
-\r
-Returns:\r
-\r
-  None\r
-\r
---*/\r
 {\r
 }\r
 \r
+/**\r
+  Callback of UdpIoRecvDatagram() that handles a Dhcp4 packet.\r
+  \r
+  Only BOOTP responses will be handled that correspond to the Xid of the request\r
+  sent out. The packet will be queued to the response queue.\r
+  \r
+  @param UdpPacket        The Dhcp4 packet.\r
+  @param Points           Udp4 address pair.\r
+  @param IoStatus         Status of the input.\r
+  @param Context          Extra info for the input.\r
+  \r
+  @return None.\r
+  \r
+**/\r
 VOID\r
 PxeDhcpInput (\r
   NET_BUF                   *UdpPacket,\r
@@ -856,7 +1307,7 @@ PxeDhcpInput (
   DhcpSb   = Instance->Service;\r
 \r
   //\r
-  // Don't restart receive if error occurs or DHCP is destoried.\r
+  // Don't restart receive if error occurs or DHCP is destroyed.\r
   //\r
   if (EFI_ERROR (IoStatus)) {\r
     return ;\r
@@ -930,6 +1381,14 @@ RESTART:
   }\r
 }\r
 \r
+/**\r
+  Complete a Dhcp4 transaction and signal the upper layer.\r
+  \r
+  @param Instance      Dhcp4 instance.\r
+  \r
+  @return None.\r
+\r
+**/\r
 VOID\r
 PxeDhcpDone (\r
   IN DHCP_PROTOCOL  *Instance\r
@@ -948,7 +1407,7 @@ PxeDhcpDone (
     }\r
 \r
     //\r
-    // Copy the recieved DHCP responses.\r
+    // Copy the received DHCP responses.\r
     //\r
     NetbufQueCopy (&Instance->ResponseQueue, 0, Instance->ResponseQueue.BufSize, (UINT8 *) Token->ResponseList);\r
     Token->Status = EFI_SUCCESS;\r
@@ -959,7 +1418,7 @@ PxeDhcpDone (
 \r
 SIGNAL_USER:\r
   //\r
-  // Clean the resources dedicated for this transmit receive transaction.\r
+  // Clean up the resources dedicated for this transmit receive transaction.\r
   //\r
   NetbufQueFlush (&Instance->ResponseQueue);\r
   UdpIoCleanPort (Instance->UdpIo);\r
@@ -975,6 +1434,10 @@ SIGNAL_USER:
 \r
 /**\r
   Transmits a DHCP formatted packet and optionally waits for responses.\r
+  \r
+  The TransmitReceive() function is used to transmit a DHCP packet and optionally\r
+  wait for the response from servers. This function does not change the state of\r
+  the EFI DHCPv4 Protocol driver and thus can be used at any time.\r
 \r
   @param  This    Pointer to the EFI_DHCP4_PROTOCOL instance.\r
   @param  Token   Pointer to the EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN structure.\r
@@ -1020,16 +1483,17 @@ EfiDhcp4TransmitReceive (
     return EFI_NOT_READY;\r
   }\r
 \r
-  if ((Token->Packet->Dhcp4.Magik != DHCP_OPTION_MAGIC) ||\r
-    (NTOHL (Token->Packet->Dhcp4.Header.Xid) == Instance->Service->Xid) ||\r
-    (Token->TimeoutValue == 0) ||\r
-    ((Token->ListenPointCount != 0) && (Token->ListenPoints == NULL)) ||\r
-    EFI_ERROR (DhcpValidateOptions (Token->Packet, NULL)) ||\r
-    EFI_IP4_EQUAL (&Token->RemoteAddress, &mZeroIp4Addr)) {\r
+  if ((Token->Packet->Dhcp4.Magik != DHCP_OPTION_MAGIC)                   ||\r
+      (NTOHL (Token->Packet->Dhcp4.Header.Xid) == Instance->Service->Xid) ||\r
+      (Token->TimeoutValue == 0)                                          ||\r
+      ((Token->ListenPointCount != 0) && (Token->ListenPoints == NULL))   ||\r
+      EFI_ERROR (DhcpValidateOptions (Token->Packet, NULL))               ||\r
+      EFI_IP4_EQUAL (&Token->RemoteAddress, &mZeroIp4Addr)\r
+      ) {\r
     //\r
-    // The DHCP packet isn't well-formed, the Transaction ID is already used\r
-    // , the timeout value is zero, the ListenPoint is invalid,\r
-    // or the RemoteAddress is zero.\r
+    // The DHCP packet isn't well-formed, the Transaction ID is already used,\r
+    // the timeout value is zero, the ListenPoint is invalid, or the\r
+    // RemoteAddress is zero.\r
     //\r
     return EFI_INVALID_PARAMETER;\r
   }\r
@@ -1058,7 +1522,11 @@ EfiDhcp4TransmitReceive (
   //\r
   // Save the Client Address is sent out\r
   //\r
-  CopyMem (&DhcpSb->ClientAddressSendOut[0], &Token->Packet->Dhcp4.Header.ClientHwAddr[0], Token->Packet->Dhcp4.Header.HwAddrLen);\r
+  CopyMem (\r
+    &DhcpSb->ClientAddressSendOut[0],\r
+    &Token->Packet->Dhcp4.Header.ClientHwAddr[0],\r
+    Token->Packet->Dhcp4.Header.HwAddrLen\r
+    );\r
 \r
   //\r
   // Wrap the DHCP packet into a net buffer.\r
@@ -1147,7 +1615,7 @@ ON_ERROR:
   the individual DHCP option in the packet.\r
 \r
   @param  Tag                    The DHCP option type\r
-  @param  Len                    length of the DHCP option data\r
+  @param  Len                    Length of the DHCP option data\r
   @param  Data                   The DHCP option data\r
   @param  Context                The context, to pass several parameters in.\r
 \r
@@ -1181,18 +1649,30 @@ Dhcp4ParseCheckOption (
 \r
 \r
 /**\r
-  Parse the DHCP options in the Packet into the PacketOptionList.\r
-  User should allocate this array of EFI_DHCP4_PACKET_OPTION points.\r
-\r
-  @param  This                   The DHCP protocol instance\r
-  @param  Packet                 The DHCP packet to parse\r
-  @param  OptionCount            On input, the size of the PacketOptionList; On\r
-                                 output,  the actual number of options processed.\r
-  @param  PacketOptionList       The array of EFI_DHCP4_PACKET_OPTION points\r
-\r
-  @retval EFI_INVALID_PARAMETER  The parameters are invalid.\r
-  @retval EFI_BUFFER_TOO_SMALL   A bigger array of points is needed.\r
-  @retval EFI_SUCCESS            The options are parsed.\r
+  Parses the packed DHCP option data.\r
+  \r
+  The Parse() function is used to retrieve the option list from a DHCP packet.\r
+  If *OptionCount isn’t zero, and there is enough space for all the DHCP options\r
+  in the Packet, each element of PacketOptionList is set to point to somewhere in\r
+  the Packet->Dhcp4.Option where a new DHCP option begins. If RFC3396 is supported,\r
+  the caller should reassemble the parsed DHCP options to get the finial result.\r
+  If *OptionCount is zero or there isn’t enough space for all of them, the number\r
+  of DHCP options in the Packet is returned in OptionCount.\r
+\r
+  @param  This             Pointer to the EFI_DHCP4_PROTOCOL instance.\r
+  @param  Packet           Pointer to packet to be parsed.\r
+  @param  OptionCount      On input, the number of entries in the PacketOptionList.\r
+                           On output, the number of entries that were written into the\r
+                           PacketOptionList.\r
+  @param  PacketOptionList List of packet option entries to be filled in. End option or pad\r
+                           options are not included.\r
+\r
+  @retval EFI_SUCCESS           The packet was successfully parsed.\r
+  @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+  @retval EFI_BUFFER_TOO_SMALL  One or more of the following conditions is TRUE:\r
+                                1) *OptionCount is smaller than the number of options that\r
+                                were found in the Packet.\r
+                                2) PacketOptionList is NULL.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -1245,16 +1725,3 @@ EfiDhcp4Parse (
 \r
   return EFI_SUCCESS;\r
 }\r
-\r
-EFI_DHCP4_PROTOCOL  mDhcp4ProtocolTemplate = {\r
-  EfiDhcp4GetModeData,\r
-  EfiDhcp4Configure,\r
-  EfiDhcp4Start,\r
-  EfiDhcp4RenewRebind,\r
-  EfiDhcp4Release,\r
-  EfiDhcp4Stop,\r
-  EfiDhcp4Build,\r
-  EfiDhcp4TransmitReceive,\r
-  EfiDhcp4Parse\r
-};\r
-\r
index b09eb4f..da42e67 100644 (file)
@@ -33,6 +33,7 @@ UINT32  mDhcp4DefaultTimeout[4] = { 4, 8, 16, 32 };
   @param  DhcpSb                The DHCP service instance\r
 \r
   @retval EFI_SUCCESS           The request has been sent\r
+  @retval other                 Some error occurs when sending the request.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -140,7 +141,7 @@ DhcpCallUser (
   Notify the user about the operation result.\r
 \r
   @param  DhcpSb                DHCP service instance\r
-  @param  Which                 which notify function to signal\r
+  @param  Which                 Which notify function to signal\r
 \r
   @return None\r
 \r
@@ -158,14 +159,16 @@ DhcpNotifyUser (
   }\r
 \r
   if ((Child->CompletionEvent != NULL) &&\r
-     ((Which == DHCP_NOTIFY_COMPLETION) || (Which == DHCP_NOTIFY_ALL))) {\r
+      ((Which == DHCP_NOTIFY_COMPLETION) || (Which == DHCP_NOTIFY_ALL))\r
+      ) {\r
 \r
     gBS->SignalEvent (Child->CompletionEvent);\r
     Child->CompletionEvent = NULL;\r
   }\r
 \r
   if ((Child->RenewRebindEvent != NULL) &&\r
-     ((Which == DHCP_NOTIFY_RENEWREBIND) || (Which == DHCP_NOTIFY_ALL))) {\r
+      ((Which == DHCP_NOTIFY_RENEWREBIND) || (Which == DHCP_NOTIFY_ALL))\r
+      ) {\r
 \r
     gBS->SignalEvent (Child->RenewRebindEvent);\r
     Child->RenewRebindEvent = NULL;\r
@@ -191,9 +194,9 @@ DhcpNotifyUser (
 **/\r
 EFI_STATUS\r
 DhcpSetState (\r
-  IN DHCP_SERVICE           *DhcpSb,\r
-  IN INTN                   State,\r
-  IN BOOLEAN                CallUser\r
+  IN OUT DHCP_SERVICE           *DhcpSb,\r
+  IN     INTN                   State,\r
+  IN     BOOLEAN                CallUser\r
   )\r
 {\r
   EFI_STATUS                Status;\r
@@ -251,7 +254,7 @@ DhcpSetState (
 **/\r
 VOID\r
 DhcpSetTransmitTimer (\r
-  IN DHCP_SERVICE           *DhcpSb\r
+  IN OUT DHCP_SERVICE           *DhcpSb\r
   )\r
 {\r
   UINT32                    *Times;\r
@@ -287,8 +290,8 @@ DhcpSetTransmitTimer (
 **/\r
 VOID\r
 DhcpComputeLease (\r
-  IN DHCP_SERVICE           *DhcpSb,\r
-  IN DHCP_PARAMETER         *Para\r
+  IN OUT DHCP_SERVICE           *DhcpSb,\r
+  IN     DHCP_PARAMETER         *Para\r
   )\r
 {\r
   ASSERT (Para != NULL);\r
@@ -317,7 +320,7 @@ DhcpComputeLease (
   such as DHCP release.\r
 \r
   @param  UdpIo                 The UDP IO port to configure\r
-  @param  Context               The opaque parameter to the function.\r
+  @param  Context               Dhcp service instance.\r
 \r
   @retval EFI_SUCCESS           The UDP IO port is successfully configured.\r
   @retval Others                It failed to configure the port.\r
@@ -395,7 +398,7 @@ DhcpConfigLeaseIoPort (
 **/\r
 EFI_STATUS\r
 DhcpLeaseAcquired (\r
-  IN DHCP_SERVICE           *DhcpSb\r
+  IN OUT DHCP_SERVICE           *DhcpSb\r
   )\r
 {\r
   INTN                      Class;\r
@@ -635,7 +638,8 @@ DhcpHandleSelect (
   // Don't return a error for these two case otherwise the session is ended.\r
   //\r
   if (!DHCP_IS_BOOTP (Para) &&\r
-     ((Para->DhcpType != DHCP_MSG_OFFER) || (Para->ServerId == 0))) {\r
+      ((Para->DhcpType != DHCP_MSG_OFFER) || (Para->ServerId == 0))\r
+      ) {\r
     goto ON_EXIT;\r
   }\r
 \r
@@ -712,8 +716,9 @@ DhcpHandleRequest (
   // Ignore the BOOTP message and DHCP messages other than DHCP ACK/NACK.\r
   //\r
   if (DHCP_IS_BOOTP (Para) ||\r
-     (Para->ServerId != DhcpSb->Para->ServerId) ||\r
-     ((Para->DhcpType != DHCP_MSG_ACK) && (Para->DhcpType != DHCP_MSG_NAK))) {\r
+      (Para->ServerId != DhcpSb->Para->ServerId) ||\r
+      ((Para->DhcpType != DHCP_MSG_ACK) && (Para->DhcpType != DHCP_MSG_NAK))\r
+      ) {\r
 \r
     Status = EFI_SUCCESS;\r
     goto ON_EXIT;\r
@@ -803,8 +808,9 @@ DhcpHandleRenewRebind (
   // Ignore the BOOTP message and DHCP messages other than DHCP ACK/NACK\r
   //\r
   if (DHCP_IS_BOOTP (Para) ||\r
-     (Para->ServerId != DhcpSb->Para->ServerId) ||\r
-     ((Para->DhcpType != DHCP_MSG_ACK) && (Para->DhcpType != DHCP_MSG_NAK))) {\r
+      (Para->ServerId != DhcpSb->Para->ServerId) ||\r
+      ((Para->DhcpType != DHCP_MSG_ACK) && (Para->DhcpType != DHCP_MSG_NAK))\r
+      ) {\r
 \r
     Status = EFI_SUCCESS;\r
     goto ON_EXIT;\r
@@ -882,7 +888,8 @@ DhcpHandleReboot (
   // Ignore the BOOTP message and DHCP messages other than DHCP ACK/NACK\r
   //\r
   if (DHCP_IS_BOOTP (Para) ||\r
-     ((Para->DhcpType != DHCP_MSG_ACK) && (Para->DhcpType != DHCP_MSG_NAK))) {\r
+      ((Para->DhcpType != DHCP_MSG_ACK) && (Para->DhcpType != DHCP_MSG_NAK))\r
+      ) {\r
 \r
     Status = EFI_SUCCESS;\r
     goto ON_EXIT;\r
@@ -944,7 +951,7 @@ ON_EXIT:
 \r
 \r
 /**\r
-  Handle the received DHCP packets. This function drivers the DHCP\r
+  Handle the received DHCP packets. This function drives the DHCP\r
   state machine.\r
 \r
   @param  UdpPacket             The UDP packets received.\r
@@ -1158,6 +1165,7 @@ DhcpOnPacketSent (
   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resources for the packet\r
   @retval EFI_ACCESS_DENIED     Failed to transmit the packet through UDP\r
   @retval EFI_SUCCESS           The message is sent\r
+  @retval other                 Other error occurs\r
 \r
 **/\r
 EFI_STATUS\r
@@ -1239,7 +1247,8 @@ DhcpSendMessage (
   //   3. DHCP request to confirm one lease.\r
   //\r
   if ((Type == DHCP_MSG_DECLINE) || (Type == DHCP_MSG_RELEASE) ||\r
-      ((Type == DHCP_MSG_REQUEST) && (DhcpSb->DhcpState == Dhcp4Requesting))) {\r
+      ((Type == DHCP_MSG_REQUEST) && (DhcpSb->DhcpState == Dhcp4Requesting))\r
+      ) {\r
 \r
     ASSERT ((Para != NULL) && (Para->ServerId != 0));\r
 \r
@@ -1346,7 +1355,11 @@ DhcpSendMessage (
   //\r
   // Save the Client Address will be sent out\r
   //\r
-  CopyMem (&DhcpSb->ClientAddressSendOut[0], &Packet->Dhcp4.Header.ClientHwAddr[0], Packet->Dhcp4.Header.HwAddrLen);\r
+  CopyMem (\r
+    &DhcpSb->ClientAddressSendOut[0],\r
+    &Packet->Dhcp4.Header.ClientHwAddr[0],\r
+    Packet->Dhcp4.Header.HwAddrLen\r
+    );\r
 \r
 \r
   //\r
index c041ba8..4dab42e 100644 (file)
@@ -35,10 +35,10 @@ Abstract:
 \r
 \r
 \r
-#define DHCP_WAIT_OFFER                 3  // Time to wait the offers\r
-#define DHCP_DEFAULT_LEASE  7 *24 *60 *60  // Seven days as default.\r
-#define DHCP_SERVER_PORT               67\r
-#define DHCP_CLIENT_PORT               68\r
+#define DHCP_WAIT_OFFER                    3  // Time to wait the offers\r
+#define DHCP_DEFAULT_LEASE  7 * 24 * 60 * 60  // Seven days as default.\r
+#define DHCP_SERVER_PORT                  67\r
+#define DHCP_CLIENT_PORT                  68\r
 \r
 typedef enum {\r
   //\r
index 1453dfe..571c6bb 100644 (file)
@@ -22,11 +22,11 @@ Abstract:
 \r
 #include "Dhcp4Impl.h"\r
 \r
-//\r
-// A list of the format of DHCP Options sorted by option tag\r
-// to validate a dhcp message. Refere the comments of the\r
-// DHCP_OPTION_FORMAT structure.\r
-//\r
+///\r
+/// A list of the format of DHCP Options sorted by option tag\r
+/// to validate a dhcp message. Refere the comments of the\r
+/// DHCP_OPTION_FORMAT structure.\r
+///\r
 DHCP_OPTION_FORMAT DhcpOptionFormats[] = {\r
   {DHCP_TAG_NETMASK,        DHCP_OPTION_IP,     1, 1  , TRUE},\r
   {DHCP_TAG_TIME_OFFSET,    DHCP_OPTION_INT32,  1, 1  , FALSE},\r
@@ -147,7 +147,7 @@ DhcpFindOptionFormat (
     if (Tag < DhcpOptionFormats[Middle].Tag) {\r
       Right = Middle - 1;\r
     } else {\r
-      Left = Middle + 1;\r
+      Left  = Middle + 1;\r
     }\r
   }\r
 \r
@@ -162,7 +162,8 @@ DhcpFindOptionFormat (
   @param  OptValue               The value of the option\r
   @param  Len                    The length of the option value\r
 \r
-  @return TRUE is the option is valid, otherwise FALSE.\r
+  @retval TRUE     The option is valid.\r
+  @retval FALSE    Otherwise.\r
 \r
 **/\r
 BOOLEAN\r
@@ -213,7 +214,8 @@ DhcpOptionIsValid (
   Occur = Len / Unit;\r
 \r
   if (((Format->MinOccur != -1) && (Occur < Format->MinOccur)) ||\r
-      ((Format->MaxOccur != -1) && (Occur > Format->MaxOccur))) {\r
+      ((Format->MaxOccur != -1) && (Occur > Format->MaxOccur))\r
+      ) {\r
     return FALSE;\r
   }\r
 \r
@@ -247,10 +249,10 @@ DhcpOptionIsValid (
 **/\r
 EFI_STATUS\r
 DhcpGetParameter (\r
-  IN UINT8                  Tag,\r
-  IN INTN                   Len,\r
-  IN UINT8                  *Data,\r
-  IN DHCP_PARAMETER         *Para\r
+  IN  UINT8                  Tag,\r
+  IN  INTN                   Len,\r
+  IN  UINT8                  *Data,\r
+  OUT DHCP_PARAMETER         *Para\r
   )\r
 {\r
   switch (Tag) {\r
@@ -311,7 +313,7 @@ DhcpGetParameter (
   @param  BufLen                 The length of the buffer\r
   @param  Check                  The callback function for each option found\r
   @param  Context                The opaque parameter for the Check\r
-  @param  Overload               variable to save the value of DHCP_TAG_OVERLOAD\r
+  @param  Overload               Variable to save the value of DHCP_TAG_OVERLOAD\r
                                  option.\r
 \r
   @retval EFI_SUCCESS            All the options are valid\r
@@ -389,7 +391,7 @@ DhcpIterateBufferOptions (
   @param  Context                The opaque parameter for Check\r
 \r
   @retval EFI_SUCCESS            The DHCP packet's options are well formated\r
-  @retval Others                 The DHCP packet's options are not well formated\r
+  @retval EFI_INVALID_PARAMETER  The DHCP packet's options are not well formated\r
 \r
 **/\r
 EFI_STATUS\r
@@ -449,7 +451,7 @@ DhcpIterateOptions (
 \r
 \r
 /**\r
-  Call back function to DhcpiterateOptions to compute each option's\r
+  Call back function to DhcpIterateOptions to compute each option's\r
   length. It just adds the data length of all the occurances of this\r
   Tag. Context is an array of 256 DHCP_OPTION_COUNT.\r
 \r
@@ -480,8 +482,8 @@ DhcpGetOptionLen (
 \r
 \r
 /**\r
-  Call back function to DhcpiterateOptions to consolidate each option's\r
-  data. There are maybe several occurance of the same option.\r
+  Call back function to DhcpIterateOptions to consolidate each option's\r
+  data. There are maybe several occurrence of the same option.\r
 \r
   @param  Tag                    The option to consolidate its data\r
   @param  Len                    The length of option data\r
@@ -536,7 +538,7 @@ DhcpFillOption (
   as a UINT8. It then iterates the DHCP packet to get data length of\r
   each option by calling DhcpIterOptions with DhcpGetOptionLen. Now, it\r
   knows the number of present options and their length. It allocates a\r
-  array of DHCP_OPTION and a continous buffer after the array to put\r
+  array of DHCP_OPTION and a continuous buffer after the array to put\r
   all the options' data. Each option's data is pointed to by the Data\r
   field in DHCP_OPTION structure. At last, it call DhcpIterateOptions\r
   with DhcpFillOption to fill each option's data to its position in the\r
@@ -743,10 +745,10 @@ ON_EXIT:
 **/\r
 UINT8 *\r
 DhcpAppendOption (\r
-  IN UINT8                  *Buf,\r
-  IN UINT8                  Tag,\r
-  IN UINT16                 DataLen,\r
-  IN UINT8                  *Data\r
+  OUT UINT8                  *Buf,\r
+  IN  UINT8                  Tag,\r
+  IN  UINT16                 DataLen,\r
+  IN  UINT8                  *Data\r
   )\r
 {\r
   INTN                      Index;\r
@@ -781,6 +783,7 @@ DhcpAppendOption (
                                  function.\r
 \r
   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory\r
+  @retval EFI_INVALID_PARAMETER  The options in SeekPacket are mal-formated\r
   @retval EFI_SUCCESS            The packet is build.\r
 \r
 **/\r
index d3c596c..fe62e55 100644 (file)
@@ -24,9 +24,9 @@ Abstract:
 #ifndef __EFI_DHCP4_OPTION_H__\r
 #define __EFI_DHCP4_OPTION_H__\r
 \r
-//\r
-// DHCP option tags (types)\r
-//\r
+///\r
+/// DHCP option tags (types)\r
+///\r
 typedef enum {\r
   //\r
   // RFC1497 vendor extensions\r
@@ -158,19 +158,19 @@ typedef enum {
   DHCP_OVERLOAD_BOTH       = 3\r
 } DHCP_OVERLOAD_TYPE;\r
 \r
-//\r
-// The DHCP option structure. This structure extends the EFI_DHCP_OPTION\r
-// structure to support options longer than 255 bytes, such as classless route.\r
-//\r
+///\r
+/// The DHCP option structure. This structure extends the EFI_DHCP_OPTION\r
+/// structure to support options longer than 255 bytes, such as classless route.\r
+///\r
 typedef struct {\r
   UINT8                     Tag;\r
   UINT16                    Len;\r
   UINT8                     *Data;\r
 } DHCP_OPTION;\r
 \r
-//\r
-// Structures used to parse the DHCP options with RFC3396 support.\r
-//\r
+///\r
+/// Structures used to parse the DHCP options with RFC3396 support.\r
+///\r
 typedef struct {\r
   UINT8                     Index;\r
   UINT16                    Offset;\r
@@ -182,11 +182,11 @@ typedef struct {
   UINT8                     *Buf;\r
 } DHCP_OPTION_CONTEXT;\r
 \r
-//\r
-// The options that matters to DHCP driver itself. The user of\r
-// DHCP clients may be interested in other options, such as\r
-// classless route, who can parse the DHCP offer to get them.\r
-//\r
+///\r
+/// The options that matters to DHCP driver itself. The user of\r
+/// DHCP clients may be interested in other options, such as\r
+/// classless route, who can parse the DHCP offer to get them.\r
+///\r
 typedef struct {\r
   IP4_ADDR                  NetMask;  // DHCP_TAG_NETMASK\r
   IP4_ADDR                  Router;   // DHCP_TAG_ROUTER, only the first router is used\r
@@ -202,14 +202,14 @@ typedef struct {
   UINT32                    T2;       // DHCP_TAG_T2\r
 } DHCP_PARAMETER;\r
 \r
-//\r
-// Structure used to describe and validate the format of DHCP options.\r
-// Type is the options' data type, such as DHCP_OPTION_INT8. MinOccur\r
-// is the minium occurance of this data type. MaxOccur is defined\r
-// similarly. If MaxOccur is -1, it means that there is no limit on the\r
-// maximum occurance. Alert tells whether DHCP client should further\r
-// inspect the option to parse DHCP_PARAMETER.\r
-//\r
+///\r
+/// Structure used to describe and validate the format of DHCP options.\r
+/// Type is the options' data type, such as DHCP_OPTION_INT8. MinOccur\r
+/// is the minium occurance of this data type. MaxOccur is defined\r
+/// similarly. If MaxOccur is -1, it means that there is no limit on the\r
+/// maximum occurance. Alert tells whether DHCP client should further\r
+/// inspect the option to parse DHCP_PARAMETER.\r
+///\r
 typedef struct {\r
   UINT8                     Tag;\r
   INTN                      Type;\r