From: niry Date: Tue, 18 Nov 2008 04:52:51 +0000 (+0000) Subject: fix code style issue and add function header X-Git-Tag: edk2-stable201903~19675 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=b6c4ecad36684d6d83c36dbf0db6d383eb2fdded fix code style issue and add function header git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6570 6f19259b-4bc3-4df7-8a09-765794883524 --- diff --git a/MdeModulePkg/Universal/Network/MnpDxe/MnpConfig.c b/MdeModulePkg/Universal/Network/MnpDxe/MnpConfig.c index fd03ed5417..e29f0978f1 100644 --- a/MdeModulePkg/Universal/Network/MnpDxe/MnpConfig.c +++ b/MdeModulePkg/Universal/Network/MnpDxe/MnpConfig.c @@ -52,54 +52,162 @@ EFI_MANAGED_NETWORK_CONFIG_DATA mMnpDefaultConfigData = { FALSE }; -EFI_STATUS -MnpAddFreeNbuf ( - IN MNP_SERVICE_DATA *MnpServiceData, - IN UINTN Count - ); - -EFI_STATUS -MnpStartSnp ( - IN EFI_SIMPLE_NETWORK_PROTOCOL *Snp - ); - -EFI_STATUS -MnpStopSnp ( - IN EFI_SIMPLE_NETWORK_PROTOCOL *Snp - ); +/** + Configure the Snp receive filters according to the instances' receive filter + settings. -EFI_STATUS -MnpStart ( - IN MNP_SERVICE_DATA *MnpServiceData, - IN BOOLEAN IsConfigUpdate, - IN BOOLEAN EnableSystemPoll - ); + @param MnpServiceData Pointer to the mnp service context data. -EFI_STATUS -MnpStop ( - IN MNP_SERVICE_DATA *MnpServiceData - ); + @retval EFI_SUCCESS The receive filters is configured. + @retval EFI_OUT_OF_RESOURCES The receive filters can't be configured due to lack + of memory resource. +**/ EFI_STATUS MnpConfigReceiveFilters ( IN MNP_SERVICE_DATA *MnpServiceData - ); + ) +{ + EFI_STATUS Status; + EFI_SIMPLE_NETWORK_PROTOCOL *Snp; + EFI_MAC_ADDRESS *MCastFilter; + UINT32 MCastFilterCnt; + UINT32 EnableFilterBits; + UINT32 DisableFilterBits; + BOOLEAN ResetMCastFilters; + LIST_ENTRY *Entry; + UINT32 Index; + MNP_GROUP_ADDRESS *GroupAddress; -EFI_STATUS -MnpGroupOpAddCtrlBlk ( - IN MNP_INSTANCE_DATA *Instance, - IN MNP_GROUP_CONTROL_BLOCK *CtrlBlk, - IN MNP_GROUP_ADDRESS *GroupAddress OPTIONAL, - IN EFI_MAC_ADDRESS *MacAddress, - IN UINT32 HwAddressSize - ); + NET_CHECK_SIGNATURE (MnpServiceData, MNP_SERVICE_DATA_SIGNATURE); -BOOLEAN -MnpGroupOpDelCtrlBlk ( - IN MNP_INSTANCE_DATA *Instance, - IN MNP_GROUP_CONTROL_BLOCK *CtrlBlk + Snp = MnpServiceData->Snp; + + // + // Initialize the enable filter and disable filter. + // + EnableFilterBits = 0; + DisableFilterBits = Snp->Mode->ReceiveFilterMask; + + if (MnpServiceData->UnicastCount != 0) { + // + // Enable unicast if any instance wants to receive unicast. + // + EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_UNICAST; + } + + if (MnpServiceData->BroadcastCount != 0) { + // + // Enable broadcast if any instance wants to receive broadcast. + // + EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST; + } + + MCastFilter = NULL; + MCastFilterCnt = 0; + ResetMCastFilters = TRUE; + + if ((MnpServiceData->MulticastCount != 0) && (MnpServiceData->GroupAddressCount != 0)) { + // + // There are instances configured to receive multicast and already some group + // addresses are joined. + // + + ResetMCastFilters = FALSE; + + if (MnpServiceData->GroupAddressCount <= Snp->Mode->MaxMCastFilterCount) { + // + // The joind group address is less than simple network's maximum count. + // Just configure the snp to do the multicast filtering. + // + + EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST; + + // + // Allocate pool for the mulicast addresses. + // + MCastFilterCnt = MnpServiceData->GroupAddressCount; + MCastFilter = AllocatePool (sizeof (EFI_MAC_ADDRESS) * MCastFilterCnt); + if (MCastFilter == NULL) { + + DEBUG ((EFI_D_ERROR, "MnpConfigReceiveFilters: Failed to allocate memory resource for MCastFilter.\n")); + return EFI_OUT_OF_RESOURCES; + } + + // + // Fill the multicast HW address buffer. + // + Index = 0; + NET_LIST_FOR_EACH (Entry, &MnpServiceData->GroupAddressList) { + + GroupAddress = NET_LIST_USER_STRUCT (Entry, MNP_GROUP_ADDRESS, AddrEntry); + CopyMem (MCastFilter + Index, &GroupAddress->Address, sizeof (*(MCastFilter + Index))); + Index++; + + ASSERT (Index <= MCastFilterCnt); + } + } else { + // + // The maximum multicast is reached, set the filter to be promiscuous + // multicast. + // + + if (Snp->Mode->ReceiveFilterMask & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST) { + EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST; + } else { + // + // Either MULTICAST or PROMISCUOUS_MULTICAST is not supported by Snp, + // set the NIC to be promiscuous although this will tremendously degrade + // the performance. + // + EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS; + } + } + } + + if (MnpServiceData->PromiscuousCount != 0) { + // + // Enable promiscuous if any instance wants to receive promiscuous. + // + EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS; + } + + // + // Set the disable filter. + // + DisableFilterBits ^= EnableFilterBits; + + // + // Configure the receive filters of SNP. + // + Status = Snp->ReceiveFilters ( + Snp, + EnableFilterBits, + DisableFilterBits, + ResetMCastFilters, + MCastFilterCnt, + MCastFilter + ); + DEBUG_CODE ( + if (EFI_ERROR (Status)) { + + DEBUG ( + (EFI_D_ERROR, + "MnpConfigReceiveFilters: Snp->ReceiveFilters failed, %r.\n", + Status) + ); + } ); + if (MCastFilter != NULL) { + // + // Free the buffer used to hold the group addresses. + // + gBS->FreePool (MCastFilter); + } + + return Status; +} /** Add some NET_BUF into MnpServiceData->FreeNbufQue. The buffer length of @@ -235,8 +343,6 @@ ON_EXIT: @param MnpServiceData Pointer to the mnp service context data. @param Nbuf Pointer to the NET_BUF to free. - @return None. - **/ VOID MnpFreeNbuf ( @@ -269,7 +375,8 @@ MnpFreeNbuf ( Initialize the mnp service context data. @param MnpServiceData Pointer to the mnp service context data. - @param Snp Pointer to the simple network protocol. + @param ImageHandle The driver image handle. + @param ControllerHandle Handle of device to bind driver to. @retval EFI_SUCCESS The mnp service context is initialized. @retval Other Some error occurs. @@ -454,8 +561,7 @@ ERROR: Flush the mnp service context data. @param MnpServiceData Pointer to the mnp service context data. - - @return None. + @param ImageHandle The driver image handle. **/ VOID @@ -521,8 +627,6 @@ MnpFlushServiceData ( @param Instance Pointer to the mnp instance context data to initialize. - @return None. - **/ VOID MnpInitializeInstanceData ( @@ -605,7 +709,6 @@ MnpTokenExist ( return EFI_SUCCESS; } - /** Cancel the token specified by Arg if it matches the token in Item. @@ -890,8 +993,6 @@ MnpStop ( @param Instance Pointer to the mnp instance context data. - @return None. - **/ VOID MnpFlushRcvdDataQueue ( @@ -1063,163 +1164,6 @@ MnpConfigureInstance ( } -/** - Configure the Snp receive filters according to the instances' receive filter - settings. - - @param MnpServiceData Pointer to the mnp service context data. - - @retval EFI_SUCCESS The receive filters is configured. - @retval EFI_OUT_OF_RESOURCES The receive filters can't be configured due to lack - of memory resource. - -**/ -EFI_STATUS -MnpConfigReceiveFilters ( - IN MNP_SERVICE_DATA *MnpServiceData - ) -{ - EFI_STATUS Status; - EFI_SIMPLE_NETWORK_PROTOCOL *Snp; - EFI_MAC_ADDRESS *MCastFilter; - UINT32 MCastFilterCnt; - UINT32 EnableFilterBits; - UINT32 DisableFilterBits; - BOOLEAN ResetMCastFilters; - LIST_ENTRY *Entry; - UINT32 Index; - MNP_GROUP_ADDRESS *GroupAddress; - - NET_CHECK_SIGNATURE (MnpServiceData, MNP_SERVICE_DATA_SIGNATURE); - - Snp = MnpServiceData->Snp; - - // - // Initialize the enable filter and disable filter. - // - EnableFilterBits = 0; - DisableFilterBits = Snp->Mode->ReceiveFilterMask; - - if (MnpServiceData->UnicastCount != 0) { - // - // Enable unicast if any instance wants to receive unicast. - // - EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_UNICAST; - } - - if (MnpServiceData->BroadcastCount != 0) { - // - // Enable broadcast if any instance wants to receive broadcast. - // - EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST; - } - - MCastFilter = NULL; - MCastFilterCnt = 0; - ResetMCastFilters = TRUE; - - if ((MnpServiceData->MulticastCount != 0) && (MnpServiceData->GroupAddressCount != 0)) { - // - // There are instances configured to receive multicast and already some group - // addresses are joined. - // - - ResetMCastFilters = FALSE; - - if (MnpServiceData->GroupAddressCount <= Snp->Mode->MaxMCastFilterCount) { - // - // The joind group address is less than simple network's maximum count. - // Just configure the snp to do the multicast filtering. - // - - EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST; - - // - // Allocate pool for the mulicast addresses. - // - MCastFilterCnt = MnpServiceData->GroupAddressCount; - MCastFilter = AllocatePool (sizeof (EFI_MAC_ADDRESS) * MCastFilterCnt); - if (MCastFilter == NULL) { - - DEBUG ((EFI_D_ERROR, "MnpConfigReceiveFilters: Failed to allocate memory resource for MCastFilter.\n")); - return EFI_OUT_OF_RESOURCES; - } - - // - // Fill the multicast HW address buffer. - // - Index = 0; - NET_LIST_FOR_EACH (Entry, &MnpServiceData->GroupAddressList) { - - GroupAddress = NET_LIST_USER_STRUCT (Entry, MNP_GROUP_ADDRESS, AddrEntry); - CopyMem (MCastFilter + Index, &GroupAddress->Address, sizeof (*(MCastFilter + Index))); - Index++; - - ASSERT (Index <= MCastFilterCnt); - } - } else { - // - // The maximum multicast is reached, set the filter to be promiscuous - // multicast. - // - - if (Snp->Mode->ReceiveFilterMask & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST) { - EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST; - } else { - // - // Either MULTICAST or PROMISCUOUS_MULTICAST is not supported by Snp, - // set the NIC to be promiscuous although this will tremendously degrade - // the performance. - // - EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS; - } - } - } - - if (MnpServiceData->PromiscuousCount != 0) { - // - // Enable promiscuous if any instance wants to receive promiscuous. - // - EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS; - } - - // - // Set the disable filter. - // - DisableFilterBits ^= EnableFilterBits; - - // - // Configure the receive filters of SNP. - // - Status = Snp->ReceiveFilters ( - Snp, - EnableFilterBits, - DisableFilterBits, - ResetMCastFilters, - MCastFilterCnt, - MCastFilter - ); - DEBUG_CODE ( - if (EFI_ERROR (Status)) { - - DEBUG ( - (EFI_D_ERROR, - "MnpConfigReceiveFilters: Snp->ReceiveFilters failed, %r.\n", - Status) - ); - } - ); - - if (MCastFilter != NULL) { - // - // Free the buffer used to hold the group addresses. - // - gBS->FreePool (MCastFilter); - } - - return Status; -} - /** Add a group address control block which controls the MacAddress for diff --git a/MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.c b/MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.c index dd1fcd8289..b6c0138b51 100644 --- a/MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.c +++ b/MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.c @@ -31,18 +31,22 @@ EFI_DRIVER_BINDING_PROTOCOL gMnpDriverBinding = { NULL }; - /** - Test to see if this driver supports 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 EFI_ALREADY_STARTED This driver is already running on 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 @@ -102,17 +106,21 @@ MnpDriverBindingSupported ( /** - 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 @@ -175,18 +183,22 @@ ErrorExit: return Status; } - /** - 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 @@ -505,31 +517,24 @@ MnpServiceBindingDestroyChild ( return Status; } +/** + The entry point for Mnp driver which installs the driver binding and component + name protocol on its ImageHandle. + + @param ImageHandle The image handle of the driver. + @param SystemTable The system table. + + @retval EFI_SUCCES the driver binding and component name protocols are + successfully installed. + @retval other failed. +**/ EFI_STATUS EFIAPI MnpDriverEntryPoint ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ) -/*++ - -Routine Description: - - The entry point for Mnp driver which installs the driver binding and component name - protocol on its ImageHandle. - -Arguments: - - ImageHandle - The image handle of the driver. - SystemTable - The system table. - -Returns: - - EFI_SUCCESS - If the driver binding and component name protocols are successfully - installed, otherwise if failed. - ---*/ { return EfiLibInstallDriverBindingComponentName2 ( ImageHandle, diff --git a/MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.h b/MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.h index 050b9e0fec..198c914051 100644 --- a/MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.h +++ b/MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.h @@ -94,22 +94,77 @@ typedef struct _MNP_SERVICE_DATA { MNP_SERVICE_DATA_SIGNATURE \ ) +/** + 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 EFIAPI MnpDriverBindingSupported ( - IN EFI_DRIVER_BINDING_PROTOCOL * This, + IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_HANDLE ControllerHandle, - IN EFI_DEVICE_PATH_PROTOCOL * RemainingDevicePath OPTIONAL + IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL ); +/** + 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 EFIAPI MnpDriverBindingStart ( - IN EFI_DRIVER_BINDING_PROTOCOL * This, + IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_HANDLE ControllerHandle, - IN EFI_DEVICE_PATH_PROTOCOL * RemainingDevicePath OPTIONAL + IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL ); + +/** + 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 EFIAPI MnpDriverBindingStop ( @@ -119,6 +174,22 @@ MnpDriverBindingStop ( IN EFI_HANDLE *ChildHandleBuffer ); +/** + 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 I/O services are added to the + existing child handle. + + @retval EFI_SUCCES The child handle was created with the I/O + services. + @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 EFIAPI MnpServiceBindingCreateChild ( @@ -126,6 +197,22 @@ MnpServiceBindingCreateChild ( IN EFI_HANDLE *ChildHandle ); +/** + Destroys a child handle with a set of I/O services. + + @param This Protocol instance pointer. + @param ChildHandle Handle of the child to destroy. + + @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 EFIAPI MnpServiceBindingDestroyChild ( diff --git a/MdeModulePkg/Universal/Network/MnpDxe/MnpImpl.h b/MdeModulePkg/Universal/Network/MnpDxe/MnpImpl.h index 4b62967902..417b72f38a 100644 --- a/MdeModulePkg/Universal/Network/MnpDxe/MnpImpl.h +++ b/MdeModulePkg/Universal/Network/MnpDxe/MnpImpl.h @@ -96,6 +96,17 @@ typedef struct _MNP_RXDATA_WRAP { UINT64 TimeoutTick; } MNP_RXDATA_WRAP; +/** + Initialize the mnp service context data. + + @param MnpServiceData Pointer to the mnp service context data. + @param ImageHandle The driver image handle. + @param ControllerHandle Handle of device to bind driver to. + + @retval EFI_SUCCESS The mnp service context is initialized. + @retval Other Some error occurs. + +**/ EFI_STATUS MnpInitializeServiceData ( IN MNP_SERVICE_DATA *MnpServiceData, @@ -103,18 +114,47 @@ MnpInitializeServiceData ( IN EFI_HANDLE ControllerHandle ); +/** + Flush the mnp service context data. + + @param MnpServiceData Pointer to the mnp service context data. + @param ImageHandle The driver image handle. + +**/ VOID MnpFlushServiceData ( IN MNP_SERVICE_DATA *MnpServiceData, IN EFI_HANDLE ImageHandle ); +/** + Initialize the mnp instance context data. + + @param MnpServiceData Pointer to the mnp service context data. + @param Instance Pointer to the mnp instance context data to + initialize. + +**/ VOID MnpInitializeInstanceData ( IN MNP_SERVICE_DATA *MnpServiceData, IN MNP_INSTANCE_DATA *Instance ); +/** + Check whether the token specified by Arg maches the token in Item. + + @param Map Pointer to the NET_MAP. + @param Item Pointer to the NET_MAP_ITEM + @param Arg Pointer to the Arg, it's a pointer to the token to + check. + + @retval EFI_SUCCESS The token specified by Arg is different from the + token in Item. + @retval EFI_ACCESS_DENIED The token specified by Arg is the same as that in + Item. + +**/ EFI_STATUS MnpTokenExist ( IN NET_MAP *Map, @@ -122,6 +162,21 @@ MnpTokenExist ( IN VOID *Arg ); +/** + Cancel the token specified by Arg if it matches the token in Item. + + @param Map Pointer to the NET_MAP. + @param Item Pointer to the NET_MAP_ITEM + @param Arg Pointer to the Arg, it's a pointer to the token to + cancel. + + @retval EFI_SUCCESS The Arg is NULL, and the token in Item is + cancelled, or the Arg isn't NULL, and the token in + Item is different from the Arg. + @retval EFI_ABORTED The Arg isn't NULL, the token in Item mathces the + Arg, and the token is cancelled. + +**/ EFI_STATUS MnpCancelTokens ( IN NET_MAP *Map, @@ -129,17 +184,50 @@ MnpCancelTokens ( IN VOID *Arg ); +/** + Flush the instance's received data. + + @param Instance Pointer to the mnp instance context data. + +**/ VOID MnpFlushRcvdDataQueue ( IN MNP_INSTANCE_DATA *Instance ); +/** + Configure the Instance using ConfigData. + + @param Instance Pointer to the mnp instance context data. + @param ConfigData Pointer to the configuration data used to configure + the isntance. + + @retval EFI_SUCCESS The Instance is configured. + @retval EFI_UNSUPPORTED EnableReceiveTimestamps is on and the + implementation doesn't support it. + @retval Other Some error occurs. + +**/ EFI_STATUS MnpConfigureInstance ( IN MNP_INSTANCE_DATA *Instance, IN EFI_MANAGED_NETWORK_CONFIG_DATA *ConfigData OPTIONAL ); +/** + Do the group operations for this instance. + + @param Instance Pointer to the instance context data. + @param JoinFlag Set to TRUE to join a group. Set to TRUE to leave a + group/groups. + @param MacAddress Pointer to the group address to join or leave. + @param CtrlBlk Pointer to the group control block if JoinFlag if + FALSE. + + @retval EFI_SUCCESS The group operation finished. + @retval Other Some error occurs. + +**/ EFI_STATUS MnpGroupOp ( IN MNP_INSTANCE_DATA *Instance, @@ -148,12 +236,32 @@ MnpGroupOp ( IN MNP_GROUP_CONTROL_BLOCK *CtrlBlk OPTIONAL ); +/** + Validates the Mnp transmit token. + + @param Instance Pointer to the Mnp instance context data. + @param Token Pointer to the transmit token to check. + + @return The Token is valid or not. + +**/ BOOLEAN MnpIsValidTxToken ( IN MNP_INSTANCE_DATA *Instance, IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token ); +/** + Build the packet to transmit from the TxData passed in. + + @param MnpServiceData Pointer to the mnp service context data. + @param TxData Pointer to the transmit data containing the + information to build the packet. + @param PktBuf Pointer to record the address of the packet. + @param PktLen Pointer to a UINT32 variable used to record the + packet's length. + +**/ VOID MnpBuildTxPacket ( IN MNP_SERVICE_DATA *MnpServiceData, @@ -162,6 +270,19 @@ MnpBuildTxPacket ( OUT UINT32 *PktLen ); +/** + Synchronously send out the packet. + + @param MnpServiceData Pointer to the mnp service context data. + @param Packet Pointer to the pakcet buffer. + @param Length The length of the packet. + @param Token Pointer to the token the packet generated from. + + @retval EFI_SUCCESS The packet is sent out. + @retval EFI_TIMEOUT Time out occurs, the packet isn't sent. + @retval EFI_DEVICE_ERROR An unexpected network error occurs. + +**/ EFI_STATUS MnpSyncSendPacket ( IN MNP_SERVICE_DATA *MnpServiceData, @@ -170,11 +291,30 @@ MnpSyncSendPacket ( IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token ); +/** + Try to deliver the received packet to the instance. + + @param Instance Pointer to the mnp instance context data. + + @retval EFI_SUCCESS The received packet is delivered, or there is no + packet to deliver, or there is no available receive + token. + @retval EFI_OUT_OF_RESOURCES The deliver fails due to lack of memory resource. + +**/ EFI_STATUS MnpInstanceDeliverPacket ( IN MNP_INSTANCE_DATA *Instance ); +/** + Recycle the RxData and other resources used to hold and deliver the received + packet. + + @param Event The event this notify function registered to. + @param Context Pointer to the context data registerd to the Event. + +**/ VOID EFIAPI MnpRecycleRxData ( @@ -182,22 +322,58 @@ MnpRecycleRxData ( IN VOID *Context ); +/** + Try to receive a packet and deliver it. + + @param MnpServiceData Pointer to the mnp service context data. + + @retval EFI_SUCCESS add return value to function comment + @retval EFI_NOT_STARTED The simple network protocol is not started. + @retval EFI_NOT_READY No packet received. + @retval EFI_DEVICE_ERROR An unexpected error occurs. + +**/ EFI_STATUS MnpReceivePacket ( IN MNP_SERVICE_DATA *MnpServiceData ); +/** + Allocate a free NET_BUF from MnpServiceData->FreeNbufQue. If there is none + in the queue, first try to allocate some and add them into the queue, then + fetch the NET_BUF from the updated FreeNbufQue. + + @param MnpServiceData Pointer to the MNP_SERVICE_DATA. + + @return Pointer to the allocated free NET_BUF structure, if NULL the operation is failed. + +**/ NET_BUF * MnpAllocNbuf ( IN MNP_SERVICE_DATA *MnpServiceData ); +/** + Try to reclaim the Nbuf into the buffer pool. + + @param MnpServiceData Pointer to the mnp service context data. + @param Nbuf Pointer to the NET_BUF to free. + +**/ VOID MnpFreeNbuf ( IN MNP_SERVICE_DATA *MnpServiceData, IN NET_BUF *Nbuf ); +/** + Remove the received packets if timeout occurs. + + @param Event The event this notify function registered to. + @param Context Pointer to the context data registered to the + event. + +**/ VOID EFIAPI MnpCheckPacketTimeout ( @@ -205,6 +381,15 @@ MnpCheckPacketTimeout ( IN VOID *Context ); +/** + Poll to receive the packets from Snp. This function is either called by upperlayer + protocols/applications or the system poll timer notify mechanism. + + @param Event The event this notify function registered to. + @param Context Pointer to the context data registered to the + event. + +**/ VOID EFIAPI MnpSystemPoll ( @@ -212,14 +397,92 @@ MnpSystemPoll ( IN VOID *Context ); +/** + Returns the operational parameters for the current MNP child driver. May also + support returning the underlying SNP driver mode data. + + The GetModeData() function is used to read the current mode data (operational + parameters) from the MNP or the underlying SNP. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param MnpConfigData Pointer to storage for MNP operational parameters. Type + EFI_MANAGED_NETWORK_CONFIG_DATA is defined in "Related + Definitions" below. + @param SnpModeData Pointer to storage for SNP operational parameters. This + feature may be unsupported. Type EFI_SIMPLE_NETWORK_MODE + is defined in the EFI_SIMPLE_NETWORK_PROTOCOL. + + @retval EFI_SUCCESS The operation completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_UNSUPPORTED The requested feature is unsupported in this + MNP implementation. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. The default values are returned in + MnpConfigData if it is not NULL. + @retval Other The mode data could not be read. + +**/ EFI_STATUS EFIAPI MnpGetModeData ( IN EFI_MANAGED_NETWORK_PROTOCOL *This, - OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL, - OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL + OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData, OPTIONAL + OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL ); +/** + Sets or clears the operational parameters for the MNP child driver. + + The Configure() function is used to set, change, or reset the operational + parameters for the MNP child driver instance. Until the operational parameters + have been set, no network traffic can be sent or received by this MNP child + driver instance. Once the operational parameters have been reset, no more + traffic can be sent or received until the operational parameters have been set + again. + Each MNP child driver instance can be started and stopped independently of + each other by setting or resetting their receive filter settings with the + Configure() function. + After any successful call to Configure(), the MNP child driver instance is + started. The internal periodic timer (if supported) is enabled. Data can be + transmitted and may be received if the receive filters have also been enabled. + Note: If multiple MNP child driver instances will receive the same packet + because of overlapping receive filter settings, then the first MNP child + driver instance will receive the original packet and additional instances will + receive copies of the original packet. + Note: Warning: Receive filter settings that overlap will consume extra + processor and/or DMA resources and degrade system and network performance. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param MnpConfigData Pointer to configuration data that will be assigned + to the MNP child driver instance. If NULL, the MNP + child driver instance is reset to startup defaults + and all pending transmit and receive requests are + flushed. Type EFI_MANAGED_NETWORK_CONFIG_DATA is + defined in + EFI_MANAGED_NETWORK_PROTOCOL.GetModeData(). + + @retval EFI_SUCCESS The operation completed successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is + TRUE: + * This is NULL. + * MnpConfigData.ProtocolTypeFilter is not + valid. + The operational data for the MNP child driver + instance is unchanged. + @retval EFI_OUT_OF_RESOURCES Required system resources (usually memory) + could not be allocated. + The MNP child driver instance has been reset to + startup defaults. + @retval EFI_UNSUPPORTED The requested feature is unsupported in + this [MNP] implementation. The operational data + for the MNP child driver instance is unchanged. + @retval EFI_DEVICE_ERROR An unexpected network or system error + occurred. The MNP child driver instance has + been reset to startup defaults. + @retval Other The MNP child driver instance has been reset to + startup defaults. + +**/ EFI_STATUS EFIAPI MnpConfigure ( @@ -227,6 +490,36 @@ MnpConfigure ( IN EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL ); +/** + Translates an IP multicast address to a hardware (MAC) multicast address. This + function may be unsupported in some MNP implementations. + + The McastIpToMac() function translates an IP multicast address to a hardware + (MAC) multicast address. This function may be implemented by calling the + underlying EFI_SIMPLE_NETWORK.MCastIpToMac() function, which may also be + unsupported in some MNP implementations. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param Ipv6Flag Set to TRUE to if IpAddress is an IPv6 multicast address. + Set to FALSE if IpAddress is an IPv4 multicast address. + @param IpAddress Pointer to the multicast IP address (in network byte order) + to convert. + @param MacAddress Pointer to the resulting multicast MAC address. + + @retval EFI_SUCCESS The operation completed successfully. + @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE: + * This is NULL. + * IpAddress is NULL. + * IpAddress is not a valid multicast IP + address. + * MacAddress is NULL. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. + @retval EFI_UNSUPPORTED The requested feature is unsupported in this + MNP implementation. + @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. + @retval Other The address could not be converted. +**/ EFI_STATUS EFIAPI MnpMcastIpToMac ( @@ -236,6 +529,42 @@ MnpMcastIpToMac ( OUT EFI_MAC_ADDRESS *MacAddress ); +/** + Enables and disables receive filters for multicast address. This function may + be unsupported in some MNP implementations. + + The Groups() function only adds and removes multicast MAC addresses from the + filter list. The MNP driver does not transmit or process Internet Group + Management Protocol (IGMP) packets. If JoinFlag is FALSE and MacAddress is + NULL, then all joined groups are left. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param JoinFlag Set to TRUE to join this multicast group. + Set to FALSE to leave this multicast group. + @param MacAddress Pointer to the multicast MAC group (address) to join or + leave. + + @retval EFI_SUCCESS The requested operation completed successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + * This is NULL. + * JoinFlag is TRUE and MacAddress is NULL. + * MacAddress is not a valid multicast MAC + address. + * The MNP multicast group settings are + unchanged. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. + @retval EFI_ALREADY_STARTED The supplied multicast group is already joined. + @retval EFI_NOT_FOUND The supplied multicast group is not joined. + @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. + The MNP child driver instance has been reset to + startup defaults. + @retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP + implementation. + @retval Other The requested operation could not be completed. + The MNP multicast group settings are unchanged. + +**/ EFI_STATUS EFIAPI MnpGroups ( @@ -244,6 +573,61 @@ MnpGroups ( IN EFI_MAC_ADDRESS *MacAddress OPTIONAL ); +/** + Places asynchronous outgoing data packets into the transmit queue. + + The Transmit() function places a completion token into the transmit packet + queue. This function is always asynchronous. + The caller must fill in the Token.Event and Token.TxData fields in the + completion token, and these fields cannot be NULL. When the transmit operation + completes, the MNP updates the Token.Status field and the Token.Event is + signaled. + Note: There may be a performance penalty if the packet needs to be + defragmented before it can be transmitted by the network device. Systems in + which performance is critical should review the requirements and features of + the underlying communications device and drivers. + + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param Token Pointer to a token associated with the transmit data + descriptor. Type EFI_MANAGED_NETWORK_COMPLETION_TOKEN is + defined in "Related Definitions" below. + + @retval EFI_SUCCESS The transmit completion token was cached. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is + TRUE: + * This is NULL. + * Token is NULL. + * Token.Event is NULL. + * Token.TxData is NULL. + * Token.TxData.DestinationAddress is not + NULL and Token.TxData.HeaderLength is zero. + * Token.TxData.FragmentCount is zero. + * (Token.TxData.HeaderLength + + Token.TxData.DataLength) is not equal to the + sum of the + Token.TxData.FragmentTable[].FragmentLength + fields. + * One or more of the + Token.TxData.FragmentTable[].FragmentLength + fields is zero. + * One or more of the + Token.TxData.FragmentTable[].FragmentBufferfields + is NULL. + * Token.TxData.DataLength is greater than MTU. + @retval EFI_ACCESS_DENIED The transmit completion token is already in the + transmit queue. + @retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a + lack of system resources (usually memory). + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. + The MNP child driver instance has been reset to + startup defaults. + @retval EFI_NOT_READY The transmit request could not be queued because + the transmit queue is full. + +**/ EFI_STATUS EFIAPI MnpTransmit ( @@ -251,6 +635,35 @@ MnpTransmit ( IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token ); +/** + Aborts an asynchronous transmit or receive request. + + The Cancel() function is used to abort a pending transmit or receive request. + If the token is in the transmit or receive request queues, after calling this + function, Token.Status will be set to EFI_ABORTED and then Token.Event will be + signaled. If the token is not in one of the queues, which usually means that + the asynchronous operation has completed, this function will not signal the + token and EFI_NOT_FOUND is returned. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param Token Pointer to a token that has been issued by + EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or + EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, all pending + tokens are aborted. + + @retval EFI_SUCCESS The asynchronous I/O request was aborted and + Token.Event was signaled. When Token is NULL, + all pending requests were aborted and their + events were signaled. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_NOT_FOUND When Token is not NULL, the asynchronous I/O + request was not found in the transmit or + receive queue. It has either completed or was + not issued by Transmit() and Receive(). + +**/ EFI_STATUS EFIAPI MnpCancel ( @@ -258,6 +671,41 @@ MnpCancel ( IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token OPTIONAL ); +/** + Places an asynchronous receiving request into the receiving queue. + + The Receive() function places a completion token into the receive packet + queue. This function is always asynchronous. + The caller must fill in the Token.Event field in the completion token, and + this field cannot be NULL. When the receive operation completes, the MNP + updates the Token.Status and Token.RxData fields and the Token.Event is + signaled. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param Token Pointer to a token associated with the receive + data descriptor. Type + EFI_MANAGED_NETWORK_COMPLETION_TOKEN is defined in + EFI_MANAGED_NETWORK_PROTOCOL.Transmit(). + + @retval EFI_SUCCESS The receive completion token was cached. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is + TRUE: + * This is NULL. + * Token is NULL. + * Token.Event is NULL + @retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a + lack of system resources (usually memory). + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. + The MNP child driver instance has been reset to + startup defaults. + @retval EFI_ACCESS_DENIED The receive completion token was already in the + receive queue. + @retval EFI_NOT_READY The receive request could not be queued because + the receive queue is full. + +**/ EFI_STATUS EFIAPI MnpReceive ( @@ -265,6 +713,32 @@ MnpReceive ( IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token ); +/** + Polls for incoming data packets and processes outgoing data packets. + + The Poll() function can be used by network drivers and applications to + increase the rate that data packets are moved between the communications + device and the transmit and receive queues. + Normally, a periodic timer event internally calls the Poll() function. But, in + some systems, the periodic timer event may not call Poll() fast enough to + transmit and/or receive all data packets without missing packets. Drivers and + applications that are experiencing packet loss should try calling the Poll() + function more often. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + + @retval EFI_SUCCESS Incoming or outgoing data was processed. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The + MNP child driver instance has been reset to startup + defaults. + @retval EFI_NOT_READY No incoming or outgoing data was processed. Consider + increasing the polling rate. + @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive + queue. Consider increasing the polling rate. + +**/ EFI_STATUS EFIAPI MnpPoll ( diff --git a/MdeModulePkg/Universal/Network/MnpDxe/MnpIo.c b/MdeModulePkg/Universal/Network/MnpDxe/MnpIo.c index 13bf552339..0945c64694 100644 --- a/MdeModulePkg/Universal/Network/MnpDxe/MnpIo.c +++ b/MdeModulePkg/Universal/Network/MnpDxe/MnpIo.c @@ -124,8 +124,6 @@ MnpIsValidTxToken ( @param PktLen Pointer to a UINT32 variable used to record the packet's length. - @return None. - **/ VOID MnpBuildTxPacket ( @@ -434,8 +432,6 @@ MnpDeliverPacket ( @param Event The event this notify function registered to. @param Context Pointer to the context data registerd to the Event. - @return None. - **/ VOID EFIAPI @@ -1007,9 +1003,7 @@ EXIT: @param Event The event this notify function registered to. @param Context Pointer to the context data registered to the event. - - @return None. - + **/ VOID EFIAPI diff --git a/MdeModulePkg/Universal/Network/MnpDxe/MnpMain.c b/MdeModulePkg/Universal/Network/MnpDxe/MnpMain.c index 95a4b675bb..ea055323cd 100644 --- a/MdeModulePkg/Universal/Network/MnpDxe/MnpMain.c +++ b/MdeModulePkg/Universal/Network/MnpDxe/MnpMain.c @@ -27,27 +27,36 @@ Abstract: /** - Get configuration data of this instance. - - @param This Pointer to the Managed Network Protocol. - @param MnpConfigData Pointer to strorage for MNP operational - parameters. - @param SnpModeData Pointer to strorage for SNP operational - parameters. - - @retval EFI_SUCCESS The operation completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_NOT_STARTED This MNP child driver instance has not been - configured The default values are returned in - MnpConfigData if it is not NULL. + Returns the operational parameters for the current MNP child driver. May also + support returning the underlying SNP driver mode data. + + The GetModeData() function is used to read the current mode data (operational + parameters) from the MNP or the underlying SNP. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param MnpConfigData Pointer to storage for MNP operational parameters. Type + EFI_MANAGED_NETWORK_CONFIG_DATA is defined in "Related + Definitions" below. + @param SnpModeData Pointer to storage for SNP operational parameters. This + feature may be unsupported. Type EFI_SIMPLE_NETWORK_MODE + is defined in the EFI_SIMPLE_NETWORK_PROTOCOL. + + @retval EFI_SUCCESS The operation completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_UNSUPPORTED The requested feature is unsupported in this + MNP implementation. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. The default values are returned in + MnpConfigData if it is not NULL. + @retval Other The mode data could not be read. **/ EFI_STATUS EFIAPI MnpGetModeData ( IN EFI_MANAGED_NETWORK_PROTOCOL *This, - OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL, - OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL + OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData, OPTIONAL + OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL ) { MNP_INSTANCE_DATA *Instance; @@ -92,22 +101,54 @@ MnpGetModeData ( /** - Set or clear the operational parameters for the MNP child driver. - - @param This Pointer to the Managed Network Protocol. - @param MnpConfigData Pointer to the configuration data that will be - assigned to the MNP child driver instance. If - NULL, the MNP child driver instance is reset to - startup defaults and all pending transmit and - receive requests are flushed. + Sets or clears the operational parameters for the MNP child driver. + + The Configure() function is used to set, change, or reset the operational + parameters for the MNP child driver instance. Until the operational parameters + have been set, no network traffic can be sent or received by this MNP child + driver instance. Once the operational parameters have been reset, no more + traffic can be sent or received until the operational parameters have been set + again. + Each MNP child driver instance can be started and stopped independently of + each other by setting or resetting their receive filter settings with the + Configure() function. + After any successful call to Configure(), the MNP child driver instance is + started. The internal periodic timer (if supported) is enabled. Data can be + transmitted and may be received if the receive filters have also been enabled. + Note: If multiple MNP child driver instances will receive the same packet + because of overlapping receive filter settings, then the first MNP child + driver instance will receive the original packet and additional instances will + receive copies of the original packet. + Note: Warning: Receive filter settings that overlap will consume extra + processor and/or DMA resources and degrade system and network performance. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param MnpConfigData Pointer to configuration data that will be assigned + to the MNP child driver instance. If NULL, the MNP + child driver instance is reset to startup defaults + and all pending transmit and receive requests are + flushed. Type EFI_MANAGED_NETWORK_CONFIG_DATA is + defined in + EFI_MANAGED_NETWORK_PROTOCOL.GetModeData(). @retval EFI_SUCCESS The operation completed successfully. - @retval EFI_INVALID_PARAMETER One or more parameter is invalid. - @retval EFI_OUT_OF_RESOURCES Required system resources (usually memory) could - not be allocated. - @retval EFI_UNSUPPORTED EnableReceiveTimestamps is TRUE, this - implementation doesn't support it. - @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is + TRUE: + * This is NULL. + * MnpConfigData.ProtocolTypeFilter is not + valid. + The operational data for the MNP child driver + instance is unchanged. + @retval EFI_OUT_OF_RESOURCES Required system resources (usually memory) + could not be allocated. + The MNP child driver instance has been reset to + startup defaults. + @retval EFI_UNSUPPORTED The requested feature is unsupported in + this [MNP] implementation. The operational data + for the MNP child driver instance is unchanged. + @retval EFI_DEVICE_ERROR An unexpected network or system error + occurred. The MNP child driver instance has + been reset to startup defaults. @retval Other The MNP child driver instance has been reset to startup defaults. @@ -156,24 +197,34 @@ ON_EXIT: /** - Translate a multicast IP address to a multicast hardware (MAC) address. - - @param This Pointer to the Managed Network Protocol. - @param Ipv6Flag Set to TRUE if IpAddress is an IPv6 multicast - address. Set to FALSE if IpAddress is an IPv4 - multicast address. - @param IpAddress Pointer to the multicast IP address to convert. - @param MacAddress Pointer to the resulting multicast MAC address. - - @retval EFI_SUCCESS The operation completed successfully. - @retval EFI_INVALID_PARAMETER One or more parameter is invalid. - @retval EFI_NOT_STARTED This MNP child driver instance has not been - configured. - @retval EFI_UNSUPPORTED Ipv6Flag is TRUE, this implementation doesn't - supported it. - @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. - @retval Other The address could not be converted. - + Translates an IP multicast address to a hardware (MAC) multicast address. This + function may be unsupported in some MNP implementations. + + The McastIpToMac() function translates an IP multicast address to a hardware + (MAC) multicast address. This function may be implemented by calling the + underlying EFI_SIMPLE_NETWORK.MCastIpToMac() function, which may also be + unsupported in some MNP implementations. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param Ipv6Flag Set to TRUE to if IpAddress is an IPv6 multicast address. + Set to FALSE if IpAddress is an IPv4 multicast address. + @param IpAddress Pointer to the multicast IP address (in network byte order) + to convert. + @param MacAddress Pointer to the resulting multicast MAC address. + + @retval EFI_SUCCESS The operation completed successfully. + @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE: + * This is NULL. + * IpAddress is NULL. + * IpAddress is not a valid multicast IP + address. + * MacAddress is NULL. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. + @retval EFI_UNSUPPORTED The requested feature is unsupported in this + MNP implementation. + @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. + @retval Other The address could not be converted. **/ EFI_STATUS EFIAPI @@ -252,25 +303,40 @@ ON_EXIT: return Status; } - /** - Enable or disable receie filters for multicast address. - - @param This Pointer to the Managed Network Protocol. - @param JoinFlag Set to TRUE to join this multicast group. Set to - FALSE to leave this multicast group. - @param MacAddress Pointer to the multicast MAC group (address) to - join or leave. - - @retval EFI_SUCCESS The operation completed successfully. - @retval EFI_INVALID_PARAMETER One or more parameter is invalid - @retval EFI_NOT_STARTED This MNP child driver instance has not been - configured. - @retval EFI_ALREADY_STARTED The supplied multicast group is already joined. - @retval EFI_NOT_FOUND The supplied multicast group is not joined. - @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. - @retval Other The requested operation could not be completed. - The MNP multicast group settings are unchanged. + Enables and disables receive filters for multicast address. This function may + be unsupported in some MNP implementations. + + The Groups() function only adds and removes multicast MAC addresses from the + filter list. The MNP driver does not transmit or process Internet Group + Management Protocol (IGMP) packets. If JoinFlag is FALSE and MacAddress is + NULL, then all joined groups are left. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param JoinFlag Set to TRUE to join this multicast group. + Set to FALSE to leave this multicast group. + @param MacAddress Pointer to the multicast MAC group (address) to join or + leave. + + @retval EFI_SUCCESS The requested operation completed successfully. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: + * This is NULL. + * JoinFlag is TRUE and MacAddress is NULL. + * MacAddress is not a valid multicast MAC + address. + * The MNP multicast group settings are + unchanged. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. + @retval EFI_ALREADY_STARTED The supplied multicast group is already joined. + @retval EFI_NOT_FOUND The supplied multicast group is not joined. + @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. + The MNP child driver instance has been reset to + startup defaults. + @retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP + implementation. + @retval Other The requested operation could not be completed. + The MNP multicast group settings are unchanged. **/ EFI_STATUS @@ -383,22 +449,54 @@ ON_EXIT: return Status; } - /** - Place an outgoing packet into the transmit queue. - - @param This Pointer to the Managed Network Protocol. - @param Token Pointer to a token associated with the transmit - data descriptor. - - @retval EFI_SUCCESS The operation completed successfully. - @retval EFI_INVALID_PARAMETER One or more parameter is invalid + Places asynchronous outgoing data packets into the transmit queue. + + The Transmit() function places a completion token into the transmit packet + queue. This function is always asynchronous. + The caller must fill in the Token.Event and Token.TxData fields in the + completion token, and these fields cannot be NULL. When the transmit operation + completes, the MNP updates the Token.Status field and the Token.Event is + signaled. + Note: There may be a performance penalty if the packet needs to be + defragmented before it can be transmitted by the network device. Systems in + which performance is critical should review the requirements and features of + the underlying communications device and drivers. + + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param Token Pointer to a token associated with the transmit data + descriptor. Type EFI_MANAGED_NETWORK_COMPLETION_TOKEN is + defined in "Related Definitions" below. + + @retval EFI_SUCCESS The transmit completion token was cached. @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is + TRUE: + * This is NULL. + * Token is NULL. + * Token.Event is NULL. + * Token.TxData is NULL. + * Token.TxData.DestinationAddress is not + NULL and Token.TxData.HeaderLength is zero. + * Token.TxData.FragmentCount is zero. + * (Token.TxData.HeaderLength + + Token.TxData.DataLength) is not equal to the + sum of the + Token.TxData.FragmentTable[].FragmentLength + fields. + * One or more of the + Token.TxData.FragmentTable[].FragmentLength + fields is zero. + * One or more of the + Token.TxData.FragmentTable[].FragmentBufferfields + is NULL. + * Token.TxData.DataLength is greater than MTU. @retval EFI_ACCESS_DENIED The transmit completion token is already in the transmit queue. @retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a - lack of system resources (usually memory). + lack of system resources (usually memory). @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The MNP child driver instance has been reset to startup defaults. @@ -464,17 +562,29 @@ ON_EXIT: /** - Place an asynchronous receiving request into the receiving queue. - - @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL - instance. - @param Token Pointer to a token associated with the receive - data descriptor. + Places an asynchronous receiving request into the receiving queue. + + The Receive() function places a completion token into the receive packet + queue. This function is always asynchronous. + The caller must fill in the Token.Event field in the completion token, and + this field cannot be NULL. When the receive operation completes, the MNP + updates the Token.Status and Token.RxData fields and the Token.Event is + signaled. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param Token Pointer to a token associated with the receive + data descriptor. Type + EFI_MANAGED_NETWORK_COMPLETION_TOKEN is defined in + EFI_MANAGED_NETWORK_PROTOCOL.Transmit(). @retval EFI_SUCCESS The receive completion token was cached. @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. - @retval EFI_INVALID_PARAMETER One or more parameter is invalid. + @retval EFI_INVALID_PARAMETER One or more of the following conditions is + TRUE: + * This is NULL. + * Token is NULL. + * Token.Event is NULL @retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a lack of system resources (usually memory). @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. @@ -544,25 +654,33 @@ ON_EXIT: return Status; } - /** - Abort a pending transmit or receive request. - - @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL - instance. - @param Token Pointer to a token that has been issued by - EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or - EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, - all pending tokens are aborted. + Aborts an asynchronous transmit or receive request. + + The Cancel() function is used to abort a pending transmit or receive request. + If the token is in the transmit or receive request queues, after calling this + function, Token.Status will be set to EFI_ABORTED and then Token.Event will be + signaled. If the token is not in one of the queues, which usually means that + the asynchronous operation has completed, this function will not signal the + token and EFI_NOT_FOUND is returned. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + @param Token Pointer to a token that has been issued by + EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or + EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, all pending + tokens are aborted. @retval EFI_SUCCESS The asynchronous I/O request was aborted and - Token->Event was signaled. + Token.Event was signaled. When Token is NULL, + all pending requests were aborted and their + events were signaled. @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_NOT_FOUND The asynchronous I/O request was not found in the - transmit or receive queue. It has either completed - or was not issued by Transmit() and Receive(). + @retval EFI_NOT_FOUND When Token is not NULL, the asynchronous I/O + request was not found in the transmit or + receive queue. It has either completed or was + not issued by Transmit() and Receive(). **/ EFI_STATUS @@ -612,22 +730,30 @@ ON_EXIT: return Status; } - /** - Poll the network interface to do transmit/receive work. - - @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL - instance. - - @retval EFI_SUCCESS Incoming or outgoing data was processed. - @retval EFI_NOT_STARTED This MNP child driver instance has not been - configured. - @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. - The MNP child driver instance has been reset to - startup defaults. - @retval EFI_NOT_READY No incoming or outgoing data was processed. - @retval EFI_TIMEOUT Data was dropped out of the transmit and/or - receive queue. + Polls for incoming data packets and processes outgoing data packets. + + The Poll() function can be used by network drivers and applications to + increase the rate that data packets are moved between the communications + device and the transmit and receive queues. + Normally, a periodic timer event internally calls the Poll() function. But, in + some systems, the periodic timer event may not call Poll() fast enough to + transmit and/or receive all data packets without missing packets. Drivers and + applications that are experiencing packet loss should try calling the Poll() + function more often. + + @param This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. + + @retval EFI_SUCCESS Incoming or outgoing data was processed. + @retval EFI_NOT_STARTED This MNP child driver instance has not been + configured. + @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The + MNP child driver instance has been reset to startup + defaults. + @retval EFI_NOT_READY No incoming or outgoing data was processed. Consider + increasing the polling rate. + @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive + queue. Consider increasing the polling rate. **/ EFI_STATUS