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