NetworkPkg/SnpDxe/Receive_filters.c

   1 /** @file
   2     Implementation of managing the multicast receive filters of a network
   3     interface.
   4
   5 Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10
  11
  12 #include "Snp.h"
  13
  14 /**
  15   Call undi to enable the receive filters.
  16
  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
  20                              list.
  21   @param  MCastAddressList   List of new multicast addresses.
  22
  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.
  27
  28 **/
  29 EFI_STATUS
  30 PxeRecvFilterEnable (
  31   SNP_DRIVER      *Snp,
  32   UINT32          EnableFlags,
  33   UINTN           MCastAddressCount,
  34   EFI_MAC_ADDRESS *MCastAddressList
  35   )
  36 {
  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;
  47
  48   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_UNICAST) != 0) {
  49     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_UNICAST;
  50   }
  51
  52   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST) != 0) {
  53     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_BROADCAST;
  54   }
  55
  56   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS) != 0) {
  57     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_PROMISCUOUS;
  58   }
  59
  60   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST) != 0) {
  61     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_ALL_MULTICAST;
  62   }
  63
  64   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST) != 0) {
  65     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_FILTERED_MULTICAST;
  66   }
  67
  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);
  72   }
  73   //
  74   // Issue UNDI command and check result.
  75   //
  76   DEBUG ((EFI_D_NET, "\nsnp->undi.receive_filters()  "));
  77
  78   (*Snp->IssueUndi32Command) ((UINT64)(UINTN) &Snp->Cdb);
  79
  80   if (Snp->Cdb.StatCode != PXE_STATCODE_SUCCESS) {
  81     //
  82     // UNDI command failed.  Return UNDI status to caller.
  83     //
  84     DEBUG (
  85       (EFI_D_ERROR,
  86       "\nsnp->undi.receive_filters()  %xh:%xh\n",
  87       Snp->Cdb.StatFlags,
  88       Snp->Cdb.StatCode)
  89       );
  90
  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;
  96
  97     case PXE_STATCODE_UNSUPPORTED:
  98       return EFI_UNSUPPORTED;
  99     }
 100
 101     return EFI_DEVICE_ERROR;
 102   }
 103
 104   return EFI_SUCCESS;
 105 }
 106
 107 /**
 108   Call undi to disable the receive filters.
 109
 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
 113                           list.
 114
 115   @retval EFI_SUCCESS           The multicast receive filter list was updated.
 116   @retval EFI_DEVICE_ERROR      Fail to execute UNDI command.
 117
 118 **/
 119 EFI_STATUS
 120 PxeRecvFilterDisable (
 121   SNP_DRIVER *Snp,
 122   UINT32     DisableFlags,
 123   BOOLEAN    ResetMCastList
 124   )
 125 {
 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;
 135
 136   Snp->Cdb.OpFlags    = (UINT16) ((DisableFlags != 0) ? PXE_OPFLAGS_RECEIVE_FILTER_DISABLE : PXE_OPFLAGS_NOT_USED);
 137
 138   if (ResetMCastList) {
 139     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_RESET_MCAST_LIST;
 140   }
 141
 142   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_UNICAST) != 0) {
 143     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_UNICAST;
 144   }
 145
 146   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST) != 0) {
 147     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_BROADCAST;
 148   }
 149
 150   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS) != 0) {
 151     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_PROMISCUOUS;
 152   }
 153
 154   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST) != 0) {
 155     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_ALL_MULTICAST;
 156   }
 157
 158   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST) != 0) {
 159     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_FILTERED_MULTICAST;
 160   }
 161   //
 162   // Issue UNDI command and check result.
 163   //
 164   DEBUG ((EFI_D_NET, "\nsnp->undi.receive_filters()  "));
 165
 166   (*Snp->IssueUndi32Command) ((UINT64)(UINTN) &Snp->Cdb);
 167
 168   if (Snp->Cdb.StatCode != PXE_STATCODE_SUCCESS) {
 169     //
 170     // UNDI command failed.  Return UNDI status to caller.
 171     //
 172     DEBUG (
 173       (EFI_D_ERROR,
 174       "\nsnp->undi.receive_filters()  %xh:%xh\n",
 175       Snp->Cdb.StatFlags,
 176       Snp->Cdb.StatCode)
 177       );
 178
 179     return EFI_DEVICE_ERROR;
 180   }
 181
 182   return EFI_SUCCESS;
 183 }
 184
 185 /**
 186   Call undi to read the receive filters.
 187
 188   @param  Snp                Pointer to snp driver structure.
 189
 190   @retval EFI_SUCCESS           The receive filter was read.
 191   @retval EFI_DEVICE_ERROR      Fail to execute UNDI command.
 192
 193 **/
 194 EFI_STATUS
 195 PxeRecvFilterRead (
 196   SNP_DRIVER *Snp
 197   )
 198 {
 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;
 206   } else {
 207     Snp->Cdb.DBaddr = (UINT64)(UINTN) Snp->Db;
 208     ZeroMem (Snp->Db, Snp->Cdb.DBsize);
 209   }
 210
 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;
 215
 216   DEBUG ((EFI_D_NET, "\nsnp->undi.receive_filters()  "));
 217
 218   (*Snp->IssueUndi32Command) ((UINT64)(UINTN) &Snp->Cdb);
 219
 220   if (Snp->Cdb.StatCode != PXE_STATCODE_SUCCESS) {
 221     //
 222     // UNDI command failed.  Return UNDI status to caller.
 223     //
 224     DEBUG (
 225       (EFI_D_ERROR,
 226       "\nsnp->undi.receive_filters()  %xh:%xh\n",
 227       Snp->Cdb.StatFlags,
 228       Snp->Cdb.StatCode)
 229       );
 230
 231     return EFI_DEVICE_ERROR;
 232   }
 233   //
 234   // Convert UNDI32 StatFlags to EFI SNP filter flags.
 235   //
 236   Snp->Mode.ReceiveFilterSetting = 0;
 237
 238   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_UNICAST) != 0) {
 239     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_UNICAST;
 240   }
 241
 242   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_BROADCAST) != 0) {
 243     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST;
 244   }
 245
 246   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_PROMISCUOUS) != 0) {
 247     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS;
 248   }
 249
 250   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_ALL_MULTICAST) != 0) {
 251     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST;
 252   }
 253
 254   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_FILTERED_MULTICAST) != 0) {
 255     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST;
 256   }
 257
 258   CopyMem (Snp->Mode.MCastFilter, Snp->Db, Snp->Cdb.DBsize);
 259
 260   //
 261   // Count number of active entries in multicast filter list.
 262   //
 263   {
 264     EFI_MAC_ADDRESS ZeroMacAddr;
 265
 266     SetMem (&ZeroMacAddr, sizeof ZeroMacAddr, 0);
 267
 268     for (Snp->Mode.MCastFilterCount = 0;
 269          Snp->Mode.MCastFilterCount < Snp->Mode.MaxMCastFilterCount;
 270          Snp->Mode.MCastFilterCount++
 271         ) {
 272       if (CompareMem (
 273             &Snp->Mode.MCastFilter[Snp->Mode.MCastFilterCount],
 274             &ZeroMacAddr,
 275             sizeof ZeroMacAddr
 276             ) == 0) {
 277         break;
 278       }
 279     }
 280   }
 281
 282   return EFI_SUCCESS;
 283 }
 284
 285
 286 /**
 287   Manages the multicast receive filters of a network interface.
 288
 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
 313     receive filters.
 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.
 332
 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
 335                           interface.
 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
 342                           default values.
 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.
 351
 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:
 355                                  * This is NULL
 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
 364                                    is zero
 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
 373                                    not been initialized
 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
 377                                  interface.
 378
 379 **/
 380 EFI_STATUS
 381 EFIAPI
 382 SnpUndi32ReceiveFilters (
 383   IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
 384   IN UINT32                      Enable,
 385   IN UINT32                      Disable,
 386   IN BOOLEAN                     ResetMCastFilter,
 387   IN UINTN                       MCastFilterCnt,  OPTIONAL
 388   IN EFI_MAC_ADDRESS             *MCastFilter     OPTIONAL
 389   )
 390 {
 391   SNP_DRIVER  *Snp;
 392   EFI_STATUS  Status;
 393   EFI_TPL     OldTpl;
 394
 395   if (This == NULL) {
 396     return EFI_INVALID_PARAMETER;
 397   }
 398
 399   Snp = EFI_SIMPLE_NETWORK_DEV_FROM_THIS (This);
 400
 401   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 402
 403   switch (Snp->Mode.State) {
 404   case EfiSimpleNetworkInitialized:
 405     break;
 406
 407   case EfiSimpleNetworkStopped:
 408     Status = EFI_NOT_STARTED;
 409     goto ON_EXIT;
 410
 411   default:
 412     Status = EFI_DEVICE_ERROR;
 413     goto ON_EXIT;
 414   }
 415   //
 416   // check if we are asked to enable or disable something that the UNDI
 417   // does not even support!
 418   //
 419   if (((Enable &~Snp->Mode.ReceiveFilterMask) != 0) ||
 420     ((Disable &~Snp->Mode.ReceiveFilterMask) != 0)) {
 421     Status = EFI_INVALID_PARAMETER;
 422     goto ON_EXIT;
 423   }
 424
 425   if (ResetMCastFilter) {
 426
 427     Disable |= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST & Snp->Mode.ReceiveFilterMask;
 428     MCastFilterCnt = 0;
 429     MCastFilter    = NULL;
 430   } else {
 431     if (MCastFilterCnt != 0) {
 432       if ((MCastFilterCnt > Snp->Mode.MaxMCastFilterCount) ||
 433           (MCastFilter == NULL)) {
 434
 435         Status = EFI_INVALID_PARAMETER;
 436         goto ON_EXIT;
 437       }
 438     }
 439   }
 440
 441   if (Enable == 0 && Disable == 0 && !ResetMCastFilter && MCastFilterCnt == 0) {
 442     Status = EFI_SUCCESS;
 443     goto ON_EXIT;
 444   }
 445
 446   if ((Enable & EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST) != 0 && MCastFilterCnt == 0) {
 447     Status = EFI_INVALID_PARAMETER;
 448     goto ON_EXIT;
 449   }
 450
 451   if ((Enable != 0) || (MCastFilterCnt != 0)) {
 452     Status = PxeRecvFilterEnable (
 453                Snp,
 454                Enable,
 455                MCastFilterCnt,
 456                MCastFilter
 457                );
 458
 459     if (EFI_ERROR (Status)) {
 460       goto ON_EXIT;
 461     }
 462   }
 463
 464   if ((Disable != 0) || ResetMCastFilter) {
 465     Status = PxeRecvFilterDisable (Snp, Disable, ResetMCastFilter);
 466
 467     if (EFI_ERROR (Status)) {
 468       goto ON_EXIT;
 469     }
 470   }
 471
 472   Status = PxeRecvFilterRead (Snp);
 473
 474 ON_EXIT:
 475   gBS->RestoreTPL (OldTpl);
 476
 477   return Status;
 478 }