2 Implementation of managing the multicast receive filters of a network
5 Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
15 Call undi to enable the receive filters.
17 @param Snp Pointer to snp driver structure.
18 @param EnableFlags Bit mask for enabling the receive filters.
19 @param MCastAddressCount Multicast address count for a new multicast address
21 @param MCastAddressList List of new multicast addresses.
23 @retval EFI_SUCCESS The multicast receive filter list was updated.
24 @retval EFI_INVALID_PARAMETER Invalid UNDI command.
25 @retval EFI_UNSUPPORTED Command is not supported by UNDI.
26 @retval EFI_DEVICE_ERROR Fail to execute UNDI command.
33 UINTN MCastAddressCount
,
34 EFI_MAC_ADDRESS
*MCastAddressList
37 Snp
->Cdb
.OpCode
= PXE_OPCODE_RECEIVE_FILTERS
;
38 Snp
->Cdb
.OpFlags
= PXE_OPFLAGS_RECEIVE_FILTER_ENABLE
;
39 Snp
->Cdb
.CPBsize
= PXE_CPBSIZE_NOT_USED
;
40 Snp
->Cdb
.DBsize
= PXE_DBSIZE_NOT_USED
;
41 Snp
->Cdb
.CPBaddr
= PXE_CPBADDR_NOT_USED
;
42 Snp
->Cdb
.DBaddr
= PXE_DBADDR_NOT_USED
;
43 Snp
->Cdb
.StatCode
= PXE_STATCODE_INITIALIZE
;
44 Snp
->Cdb
.StatFlags
= PXE_STATFLAGS_INITIALIZE
;
45 Snp
->Cdb
.IFnum
= Snp
->IfNum
;
46 Snp
->Cdb
.Control
= PXE_CONTROL_LAST_CDB_IN_LIST
;
48 if ((EnableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_UNICAST
) != 0) {
49 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_UNICAST
;
52 if ((EnableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST
) != 0) {
53 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_BROADCAST
;
56 if ((EnableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS
) != 0) {
57 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_PROMISCUOUS
;
60 if ((EnableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST
) != 0) {
61 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_ALL_MULTICAST
;
64 if ((EnableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST
) != 0) {
65 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_FILTERED_MULTICAST
;
68 if (MCastAddressCount
!= 0) {
69 Snp
->Cdb
.CPBsize
= (UINT16
) (MCastAddressCount
* sizeof (EFI_MAC_ADDRESS
));
70 Snp
->Cdb
.CPBaddr
= (UINT64
)(UINTN
)Snp
->Cpb
;
71 CopyMem (Snp
->Cpb
, MCastAddressList
, Snp
->Cdb
.CPBsize
);
74 // Issue UNDI command and check result.
76 DEBUG ((EFI_D_NET
, "\nsnp->undi.receive_filters() "));
78 (*Snp
->IssueUndi32Command
) ((UINT64
)(UINTN
) &Snp
->Cdb
);
80 if (Snp
->Cdb
.StatCode
!= PXE_STATCODE_SUCCESS
) {
82 // UNDI command failed. Return UNDI status to caller.
86 "\nsnp->undi.receive_filters() %xh:%xh\n",
91 switch (Snp
->Cdb
.StatCode
) {
92 case PXE_STATCODE_INVALID_CDB
:
93 case PXE_STATCODE_INVALID_CPB
:
94 case PXE_STATCODE_INVALID_PARAMETER
:
95 return EFI_INVALID_PARAMETER
;
97 case PXE_STATCODE_UNSUPPORTED
:
98 return EFI_UNSUPPORTED
;
101 return EFI_DEVICE_ERROR
;
108 Call undi to disable the receive filters.
110 @param Snp Pointer to snp driver structure
111 @param DisableFlags Bit mask for disabling the receive filters
112 @param ResetMCastList Boolean flag to reset/delete the multicast filter
115 @retval EFI_SUCCESS The multicast receive filter list was updated.
116 @retval EFI_DEVICE_ERROR Fail to execute UNDI command.
120 PxeRecvFilterDisable (
123 BOOLEAN ResetMCastList
126 Snp
->Cdb
.OpCode
= PXE_OPCODE_RECEIVE_FILTERS
;
127 Snp
->Cdb
.CPBsize
= PXE_CPBSIZE_NOT_USED
;
128 Snp
->Cdb
.DBsize
= PXE_DBSIZE_NOT_USED
;
129 Snp
->Cdb
.CPBaddr
= PXE_CPBADDR_NOT_USED
;
130 Snp
->Cdb
.DBaddr
= PXE_DBADDR_NOT_USED
;
131 Snp
->Cdb
.StatCode
= PXE_STATCODE_INITIALIZE
;
132 Snp
->Cdb
.StatFlags
= PXE_STATFLAGS_INITIALIZE
;
133 Snp
->Cdb
.IFnum
= Snp
->IfNum
;
134 Snp
->Cdb
.Control
= PXE_CONTROL_LAST_CDB_IN_LIST
;
136 Snp
->Cdb
.OpFlags
= (UINT16
) ((DisableFlags
!= 0) ? PXE_OPFLAGS_RECEIVE_FILTER_DISABLE
: PXE_OPFLAGS_NOT_USED
);
138 if (ResetMCastList
) {
139 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_RESET_MCAST_LIST
;
142 if ((DisableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_UNICAST
) != 0) {
143 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_UNICAST
;
146 if ((DisableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST
) != 0) {
147 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_BROADCAST
;
150 if ((DisableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS
) != 0) {
151 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_PROMISCUOUS
;
154 if ((DisableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST
) != 0) {
155 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_ALL_MULTICAST
;
158 if ((DisableFlags
& EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST
) != 0) {
159 Snp
->Cdb
.OpFlags
|= PXE_OPFLAGS_RECEIVE_FILTER_FILTERED_MULTICAST
;
162 // Issue UNDI command and check result.
164 DEBUG ((EFI_D_NET
, "\nsnp->undi.receive_filters() "));
166 (*Snp
->IssueUndi32Command
) ((UINT64
)(UINTN
) &Snp
->Cdb
);
168 if (Snp
->Cdb
.StatCode
!= PXE_STATCODE_SUCCESS
) {
170 // UNDI command failed. Return UNDI status to caller.
174 "\nsnp->undi.receive_filters() %xh:%xh\n",
179 return EFI_DEVICE_ERROR
;
186 Call undi to read the receive filters.
188 @param Snp Pointer to snp driver structure.
190 @retval EFI_SUCCESS The receive filter was read.
191 @retval EFI_DEVICE_ERROR Fail to execute UNDI command.
199 Snp
->Cdb
.OpCode
= PXE_OPCODE_RECEIVE_FILTERS
;
200 Snp
->Cdb
.OpFlags
= PXE_OPFLAGS_RECEIVE_FILTER_READ
;
201 Snp
->Cdb
.CPBsize
= PXE_CPBSIZE_NOT_USED
;
202 Snp
->Cdb
.DBsize
= (UINT16
) (Snp
->Mode
.MaxMCastFilterCount
* sizeof (EFI_MAC_ADDRESS
));
203 Snp
->Cdb
.CPBaddr
= PXE_CPBADDR_NOT_USED
;
204 if (Snp
->Cdb
.DBsize
== 0) {
205 Snp
->Cdb
.DBaddr
= (UINT64
)(UINTN
) NULL
;
207 Snp
->Cdb
.DBaddr
= (UINT64
)(UINTN
) Snp
->Db
;
208 ZeroMem (Snp
->Db
, Snp
->Cdb
.DBsize
);
211 Snp
->Cdb
.StatCode
= PXE_STATCODE_INITIALIZE
;
212 Snp
->Cdb
.StatFlags
= PXE_STATFLAGS_INITIALIZE
;
213 Snp
->Cdb
.IFnum
= Snp
->IfNum
;
214 Snp
->Cdb
.Control
= PXE_CONTROL_LAST_CDB_IN_LIST
;
216 DEBUG ((EFI_D_NET
, "\nsnp->undi.receive_filters() "));
218 (*Snp
->IssueUndi32Command
) ((UINT64
)(UINTN
) &Snp
->Cdb
);
220 if (Snp
->Cdb
.StatCode
!= PXE_STATCODE_SUCCESS
) {
222 // UNDI command failed. Return UNDI status to caller.
226 "\nsnp->undi.receive_filters() %xh:%xh\n",
231 return EFI_DEVICE_ERROR
;
234 // Convert UNDI32 StatFlags to EFI SNP filter flags.
236 Snp
->Mode
.ReceiveFilterSetting
= 0;
238 if ((Snp
->Cdb
.StatFlags
& PXE_STATFLAGS_RECEIVE_FILTER_UNICAST
) != 0) {
239 Snp
->Mode
.ReceiveFilterSetting
|= EFI_SIMPLE_NETWORK_RECEIVE_UNICAST
;
242 if ((Snp
->Cdb
.StatFlags
& PXE_STATFLAGS_RECEIVE_FILTER_BROADCAST
) != 0) {
243 Snp
->Mode
.ReceiveFilterSetting
|= EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST
;
246 if ((Snp
->Cdb
.StatFlags
& PXE_STATFLAGS_RECEIVE_FILTER_PROMISCUOUS
) != 0) {
247 Snp
->Mode
.ReceiveFilterSetting
|= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS
;
250 if ((Snp
->Cdb
.StatFlags
& PXE_STATFLAGS_RECEIVE_FILTER_ALL_MULTICAST
) != 0) {
251 Snp
->Mode
.ReceiveFilterSetting
|= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST
;
254 if ((Snp
->Cdb
.StatFlags
& PXE_STATFLAGS_RECEIVE_FILTER_FILTERED_MULTICAST
) != 0) {
255 Snp
->Mode
.ReceiveFilterSetting
|= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST
;
258 CopyMem (Snp
->Mode
.MCastFilter
, Snp
->Db
, Snp
->Cdb
.DBsize
);
261 // Count number of active entries in multicast filter list.
264 EFI_MAC_ADDRESS ZeroMacAddr
;
266 SetMem (&ZeroMacAddr
, sizeof ZeroMacAddr
, 0);
268 for (Snp
->Mode
.MCastFilterCount
= 0;
269 Snp
->Mode
.MCastFilterCount
< Snp
->Mode
.MaxMCastFilterCount
;
270 Snp
->Mode
.MCastFilterCount
++
273 &Snp
->Mode
.MCastFilter
[Snp
->Mode
.MCastFilterCount
],
287 Manages the multicast receive filters of a network interface.
289 This function is used enable and disable the hardware and software receive
290 filters for the underlying network device.
291 The receive filter change is broken down into three steps:
292 * The filter mask bits that are set (ON) in the Enable parameter are added to
293 the current receive filter settings.
294 * The filter mask bits that are set (ON) in the Disable parameter are subtracted
295 from the updated receive filter settings.
296 * If the resulting receive filter setting is not supported by the hardware a
297 more liberal setting is selected.
298 If the same bits are set in the Enable and Disable parameters, then the bits
299 in the Disable parameter takes precedence.
300 If the ResetMCastFilter parameter is TRUE, then the multicast address list
301 filter is disabled (irregardless of what other multicast bits are set in the
302 Enable and Disable parameters). The SNP->Mode->MCastFilterCount field is set
303 to zero. The Snp->Mode->MCastFilter contents are undefined.
304 After enabling or disabling receive filter settings, software should verify
305 the new settings by checking the Snp->Mode->ReceiveFilterSettings,
306 Snp->Mode->MCastFilterCount and Snp->Mode->MCastFilter fields.
307 Note: Some network drivers and/or devices will automatically promote receive
308 filter settings if the requested setting can not be honored. For example, if
309 a request for four multicast addresses is made and the underlying hardware
310 only supports two multicast addresses the driver might set the promiscuous
311 or promiscuous multicast receive filters instead. The receiving software is
312 responsible for discarding any extra packets that get through the hardware
314 Note: Note: To disable all receive filter hardware, the network driver must
315 be Shutdown() and Stopped(). Calling ReceiveFilters() with Disable set to
316 Snp->Mode->ReceiveFilterSettings will make it so no more packets are
317 returned by the Receive() function, but the receive hardware may still be
318 moving packets into system memory before inspecting and discarding them.
319 Unexpected system errors, reboots and hangs can occur if an OS is loaded
320 and the network devices are not Shutdown() and Stopped().
321 If ResetMCastFilter is TRUE, then the multicast receive filter list on the
322 network interface will be reset to the default multicast receive filter list.
323 If ResetMCastFilter is FALSE, and this network interface allows the multicast
324 receive filter list to be modified, then the MCastFilterCnt and MCastFilter
325 are used to update the current multicast receive filter list. The modified
326 receive filter list settings can be found in the MCastFilter field of
327 EFI_SIMPLE_NETWORK_MODE. If the network interface does not allow the multicast
328 receive filter list to be modified, then EFI_INVALID_PARAMETER will be returned.
329 If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
330 If the receive filter mask and multicast receive filter list have been
331 successfully updated on the network interface, EFI_SUCCESS will be returned.
333 @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
334 @param Enable A bit mask of receive filters to enable on the network
336 @param Disable A bit mask of receive filters to disable on the network
337 interface. For backward compatibility with EFI 1.1
338 platforms, the EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit
339 must be set when the ResetMCastFilter parameter is TRUE.
340 @param ResetMCastFilter Set to TRUE to reset the contents of the multicast
341 receive filters on the network interface to their
343 @param MCastFilterCnt Number of multicast HW MAC addresses in the new MCastFilter
344 list. This value must be less than or equal to the
345 MCastFilterCnt field of EFI_SIMPLE_NETWORK_MODE.
346 This field is optional if ResetMCastFilter is TRUE.
347 @param MCastFilter A pointer to a list of new multicast receive filter HW
348 MAC addresses. This list will replace any existing
349 multicast HW MAC address list. This field is optional
350 if ResetMCastFilter is TRUE.
352 @retval EFI_SUCCESS The multicast receive filter list was updated.
353 @retval EFI_NOT_STARTED The network interface has not been started.
354 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
356 * There are bits set in Enable that are not set
357 in Snp->Mode->ReceiveFilterMask
358 * There are bits set in Disable that are not set
359 in Snp->Mode->ReceiveFilterMask
360 * Multicast is being enabled (the
361 EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit is
362 set in Enable, it is not set in Disable, and
363 ResetMCastFilter is FALSE) and MCastFilterCount
365 * Multicast is being enabled and MCastFilterCount
366 is greater than Snp->Mode->MaxMCastFilterCount
367 * Multicast is being enabled and MCastFilter is NULL
368 * Multicast is being enabled and one or more of
369 the addresses in the MCastFilter list are not
370 valid multicast MAC addresses
371 @retval EFI_DEVICE_ERROR One or more of the following conditions is TRUE:
372 * The network interface has been started but has
374 * An unexpected error was returned by the
375 underlying network driver or device
376 @retval EFI_UNSUPPORTED This function is not supported by the network
382 SnpUndi32ReceiveFilters (
383 IN EFI_SIMPLE_NETWORK_PROTOCOL
*This
,
386 IN BOOLEAN ResetMCastFilter
,
387 IN UINTN MCastFilterCnt
, OPTIONAL
388 IN EFI_MAC_ADDRESS
*MCastFilter OPTIONAL
396 return EFI_INVALID_PARAMETER
;
399 Snp
= EFI_SIMPLE_NETWORK_DEV_FROM_THIS (This
);
401 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
403 switch (Snp
->Mode
.State
) {
404 case EfiSimpleNetworkInitialized
:
407 case EfiSimpleNetworkStopped
:
408 Status
= EFI_NOT_STARTED
;
412 Status
= EFI_DEVICE_ERROR
;
416 // check if we are asked to enable or disable something that the UNDI
417 // does not even support!
419 if (((Enable
&~Snp
->Mode
.ReceiveFilterMask
) != 0) ||
420 ((Disable
&~Snp
->Mode
.ReceiveFilterMask
) != 0)) {
421 Status
= EFI_INVALID_PARAMETER
;
425 if (ResetMCastFilter
) {
427 Disable
|= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST
& Snp
->Mode
.ReceiveFilterMask
;
431 if (MCastFilterCnt
!= 0) {
432 if ((MCastFilterCnt
> Snp
->Mode
.MaxMCastFilterCount
) ||
433 (MCastFilter
== NULL
)) {
435 Status
= EFI_INVALID_PARAMETER
;
441 if (Enable
== 0 && Disable
== 0 && !ResetMCastFilter
&& MCastFilterCnt
== 0) {
442 Status
= EFI_SUCCESS
;
446 if ((Enable
& EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST
) != 0 && MCastFilterCnt
== 0) {
447 Status
= EFI_INVALID_PARAMETER
;
451 if ((Enable
!= 0) || (MCastFilterCnt
!= 0)) {
452 Status
= PxeRecvFilterEnable (
459 if (EFI_ERROR (Status
)) {
464 if ((Disable
!= 0) || ResetMCastFilter
) {
465 Status
= PxeRecvFilterDisable (Snp
, Disable
, ResetMCastFilter
);
467 if (EFI_ERROR (Status
)) {
472 Status
= PxeRecvFilterRead (Snp
);
475 gBS
->RestoreTPL (OldTpl
);