+ Manages the multicast receive filters of a network interface.\r
+ \r
+ This function is used enable and disable the hardware and software receive \r
+ filters for the underlying network device.\r
+ The receive filter change is broken down into three steps: \r
+ * The filter mask bits that are set (ON) in the Enable parameter are added to \r
+ the current receive filter settings. \r
+ * The filter mask bits that are set (ON) in the Disable parameter are subtracted\r
+ from the updated receive filter settings.\r
+ * If the resulting receive filter setting is not supported by the hardware a\r
+ more liberal setting is selected.\r
+ If the same bits are set in the Enable and Disable parameters, then the bits \r
+ in the Disable parameter takes precedence.\r
+ If the ResetMCastFilter parameter is TRUE, then the multicast address list \r
+ filter is disabled (irregardless of what other multicast bits are set in the \r
+ Enable and Disable parameters). The SNP->Mode->MCastFilterCount field is set \r
+ to zero. The Snp->Mode->MCastFilter contents are undefined.\r
+ After enabling or disabling receive filter settings, software should verify \r
+ the new settings by checking the Snp->Mode->ReceiveFilterSettings, \r
+ Snp->Mode->MCastFilterCount and Snp->Mode->MCastFilter fields.\r
+ Note: Some network drivers and/or devices will automatically promote receive \r
+ filter settings if the requested setting can not be honored. For example, if\r
+ a request for four multicast addresses is made and the underlying hardware \r
+ only supports two multicast addresses the driver might set the promiscuous \r
+ or promiscuous multicast receive filters instead. The receiving software is\r
+ responsible for discarding any extra packets that get through the hardware \r
+ receive filters.\r
+ Note: Note: To disable all receive filter hardware, the network driver must \r
+ be Shutdown() and Stopped(). Calling ReceiveFilters() with Disable set to\r
+ Snp->Mode->ReceiveFilterSettings will make it so no more packets are \r
+ returned by the Receive() function, but the receive hardware may still be \r
+ moving packets into system memory before inspecting and discarding them.\r
+ Unexpected system errors, reboots and hangs can occur if an OS is loaded \r
+ and the network devices are not Shutdown() and Stopped().\r
+ If ResetMCastFilter is TRUE, then the multicast receive filter list on the \r
+ network interface will be reset to the default multicast receive filter list.\r
+ If ResetMCastFilter is FALSE, and this network interface allows the multicast \r
+ receive filter list to be modified, then the MCastFilterCnt and MCastFilter \r
+ are used to update the current multicast receive filter list. The modified \r
+ receive filter list settings can be found in the MCastFilter field of \r
+ EFI_SIMPLE_NETWORK_MODE. If the network interface does not allow the multicast\r
+ receive filter list to be modified, then EFI_INVALID_PARAMETER will be returned.\r
+ If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.\r
+ If the receive filter mask and multicast receive filter list have been \r
+ successfully updated on the network interface, EFI_SUCCESS will be returned.\r
+\r
+ @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.\r
+ @param Enable A bit mask of receive filters to enable on the network\r
+ interface.\r
+ @param Disable A bit mask of receive filters to disable on the network\r
+ interface. For backward compatibility with EFI 1.1 \r
+ platforms, the EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit\r
+ must be set when the ResetMCastFilter parameter is TRUE.\r
+ @param ResetMCastFilter Set to TRUE to reset the contents of the multicast \r
+ receive filters on the network interface to their \r
+ default values. \r
+ @param MCastFilterCnt Number of multicast HW MAC addresses in the new MCastFilter\r
+ list. This value must be less than or equal to the \r
+ MCastFilterCnt field of EFI_SIMPLE_NETWORK_MODE. \r
+ This field is optional if ResetMCastFilter is TRUE.\r
+ @param MCastFilter A pointer to a list of new multicast receive filter HW\r
+ MAC addresses. This list will replace any existing \r
+ multicast HW MAC address list. This field is optional \r
+ if ResetMCastFilter is TRUE.\r
+ \r
+ @retval EFI_SUCCESS The multicast receive filter list was updated.\r
+ @retval EFI_NOT_STARTED The network interface has not been started.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ * This is NULL\r
+ * There are bits set in Enable that are not set\r
+ in Snp->Mode->ReceiveFilterMask\r
+ * There are bits set in Disable that are not set\r
+ in Snp->Mode->ReceiveFilterMask\r
+ * Multicast is being enabled (the \r
+ EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit is \r
+ set in Enable, it is not set in Disable, and \r
+ ResetMCastFilter is FALSE) and MCastFilterCount\r
+ is zero\r
+ * Multicast is being enabled and MCastFilterCount\r
+ is greater than Snp->Mode->MaxMCastFilterCount\r
+ * Multicast is being enabled and MCastFilter is NULL\r
+ * Multicast is being enabled and one or more of\r
+ the addresses in the MCastFilter list are not\r
+ valid multicast MAC addresses\r
+ @retval EFI_DEVICE_ERROR One or more of the following conditions is TRUE:\r
+ * The network interface has been started but has\r
+ not been initialized\r
+ * An unexpected error was returned by the \r
+ underlying network driver or device\r
+ @retval EFI_UNSUPPORTED This function is not supported by the network\r
+ interface.\r
projects / mirror_edk2.git / blobdiff