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 #include "Snp.h"
  11
  12 /**
  13   Call undi to enable the receive filters.
  14
  15   @param  Snp                Pointer to snp driver structure.
  16   @param  EnableFlags        Bit mask for enabling the receive filters.
  17   @param  MCastAddressCount  Multicast address count for a new multicast address
  18                              list.
  19   @param  MCastAddressList   List of new multicast addresses.
  20
  21   @retval EFI_SUCCESS           The multicast receive filter list was updated.
  22   @retval EFI_INVALID_PARAMETER Invalid UNDI command.
  23   @retval EFI_UNSUPPORTED       Command is not supported by UNDI.
  24   @retval EFI_DEVICE_ERROR      Fail to execute UNDI command.
  25
  26 **/
  27 EFI_STATUS
  28 PxeRecvFilterEnable (
  29   SNP_DRIVER       *Snp,
  30   UINT32           EnableFlags,
  31   UINTN            MCastAddressCount,
  32   EFI_MAC_ADDRESS  *MCastAddressList
  33   )
  34 {
  35   Snp->Cdb.OpCode    = PXE_OPCODE_RECEIVE_FILTERS;
  36   Snp->Cdb.OpFlags   = PXE_OPFLAGS_RECEIVE_FILTER_ENABLE;
  37   Snp->Cdb.CPBsize   = PXE_CPBSIZE_NOT_USED;
  38   Snp->Cdb.DBsize    = PXE_DBSIZE_NOT_USED;
  39   Snp->Cdb.CPBaddr   = PXE_CPBADDR_NOT_USED;
  40   Snp->Cdb.DBaddr    = PXE_DBADDR_NOT_USED;
  41   Snp->Cdb.StatCode  = PXE_STATCODE_INITIALIZE;
  42   Snp->Cdb.StatFlags = PXE_STATFLAGS_INITIALIZE;
  43   Snp->Cdb.IFnum     = Snp->IfNum;
  44   Snp->Cdb.Control   = PXE_CONTROL_LAST_CDB_IN_LIST;
  45
  46   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_UNICAST) != 0) {
  47     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_UNICAST;
  48   }
  49
  50   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST) != 0) {
  51     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_BROADCAST;
  52   }
  53
  54   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS) != 0) {
  55     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_PROMISCUOUS;
  56   }
  57
  58   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST) != 0) {
  59     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_ALL_MULTICAST;
  60   }
  61
  62   if ((EnableFlags & EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST) != 0) {
  63     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_FILTERED_MULTICAST;
  64   }
  65
  66   if (MCastAddressCount != 0) {
  67     Snp->Cdb.CPBsize = (UINT16)(MCastAddressCount * sizeof (EFI_MAC_ADDRESS));
  68     Snp->Cdb.CPBaddr = (UINT64)(UINTN)Snp->Cpb;
  69     CopyMem (Snp->Cpb, MCastAddressList, Snp->Cdb.CPBsize);
  70   }
  71
  72   //
  73   // Issue UNDI command and check result.
  74   //
  75   DEBUG ((DEBUG_NET, "\nsnp->undi.receive_filters()  "));
  76
  77   (*Snp->IssueUndi32Command)((UINT64)(UINTN)&Snp->Cdb);
  78
  79   if (Snp->Cdb.StatCode != PXE_STATCODE_SUCCESS) {
  80     //
  81     // UNDI command failed.  Return UNDI status to caller.
  82     //
  83     DEBUG (
  84       (DEBUG_ERROR,
  85        "\nsnp->undi.receive_filters()  %xh:%xh\n",
  86        Snp->Cdb.StatFlags,
  87        Snp->Cdb.StatCode)
  88       );
  89
  90     switch (Snp->Cdb.StatCode) {
  91       case PXE_STATCODE_INVALID_CDB:
  92       case PXE_STATCODE_INVALID_CPB:
  93       case PXE_STATCODE_INVALID_PARAMETER:
  94         return EFI_INVALID_PARAMETER;
  95
  96       case PXE_STATCODE_UNSUPPORTED:
  97         return EFI_UNSUPPORTED;
  98     }
  99
 100     return EFI_DEVICE_ERROR;
 101   }
 102
 103   return EFI_SUCCESS;
 104 }
 105
 106 /**
 107   Call undi to disable the receive filters.
 108
 109   @param  Snp             Pointer to snp driver structure
 110   @param  DisableFlags    Bit mask for disabling the receive filters
 111   @param  ResetMCastList  Boolean flag to reset/delete the multicast filter
 112                           list.
 113
 114   @retval EFI_SUCCESS           The multicast receive filter list was updated.
 115   @retval EFI_DEVICE_ERROR      Fail to execute UNDI command.
 116
 117 **/
 118 EFI_STATUS
 119 PxeRecvFilterDisable (
 120   SNP_DRIVER  *Snp,
 121   UINT32      DisableFlags,
 122   BOOLEAN     ResetMCastList
 123   )
 124 {
 125   Snp->Cdb.OpCode    = PXE_OPCODE_RECEIVE_FILTERS;
 126   Snp->Cdb.CPBsize   = PXE_CPBSIZE_NOT_USED;
 127   Snp->Cdb.DBsize    = PXE_DBSIZE_NOT_USED;
 128   Snp->Cdb.CPBaddr   = PXE_CPBADDR_NOT_USED;
 129   Snp->Cdb.DBaddr    = PXE_DBADDR_NOT_USED;
 130   Snp->Cdb.StatCode  = PXE_STATCODE_INITIALIZE;
 131   Snp->Cdb.StatFlags = PXE_STATFLAGS_INITIALIZE;
 132   Snp->Cdb.IFnum     = Snp->IfNum;
 133   Snp->Cdb.Control   = PXE_CONTROL_LAST_CDB_IN_LIST;
 134
 135   Snp->Cdb.OpFlags = (UINT16)((DisableFlags != 0) ? PXE_OPFLAGS_RECEIVE_FILTER_DISABLE : PXE_OPFLAGS_NOT_USED);
 136
 137   if (ResetMCastList) {
 138     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_RESET_MCAST_LIST;
 139   }
 140
 141   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_UNICAST) != 0) {
 142     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_UNICAST;
 143   }
 144
 145   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST) != 0) {
 146     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_BROADCAST;
 147   }
 148
 149   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS) != 0) {
 150     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_PROMISCUOUS;
 151   }
 152
 153   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST) != 0) {
 154     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_ALL_MULTICAST;
 155   }
 156
 157   if ((DisableFlags & EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST) != 0) {
 158     Snp->Cdb.OpFlags |= PXE_OPFLAGS_RECEIVE_FILTER_FILTERED_MULTICAST;
 159   }
 160
 161   //
 162   // Issue UNDI command and check result.
 163   //
 164   DEBUG ((DEBUG_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       (DEBUG_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 ((DEBUG_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       (DEBUG_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   //
 235   // Convert UNDI32 StatFlags to EFI SNP filter flags.
 236   //
 237   Snp->Mode.ReceiveFilterSetting = 0;
 238
 239   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_UNICAST) != 0) {
 240     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_UNICAST;
 241   }
 242
 243   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_BROADCAST) != 0) {
 244     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST;
 245   }
 246
 247   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_PROMISCUOUS) != 0) {
 248     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS;
 249   }
 250
 251   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_ALL_MULTICAST) != 0) {
 252     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST;
 253   }
 254
 255   if ((Snp->Cdb.StatFlags & PXE_STATFLAGS_RECEIVE_FILTER_FILTERED_MULTICAST) != 0) {
 256     Snp->Mode.ReceiveFilterSetting |= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST;
 257   }
 258
 259   CopyMem (Snp->Mode.MCastFilter, Snp->Db, Snp->Cdb.DBsize);
 260
 261   //
 262   // Count number of active entries in multicast filter list.
 263   //
 264   {
 265     EFI_MAC_ADDRESS  ZeroMacAddr;
 266
 267     SetMem (&ZeroMacAddr, sizeof ZeroMacAddr, 0);
 268
 269     for (Snp->Mode.MCastFilterCount = 0;
 270          Snp->Mode.MCastFilterCount < Snp->Mode.MaxMCastFilterCount;
 271          Snp->Mode.MCastFilterCount++
 272          )
 273     {
 274       if (CompareMem (
 275             &Snp->Mode.MCastFilter[Snp->Mode.MCastFilterCount],
 276             &ZeroMacAddr,
 277             sizeof ZeroMacAddr
 278             ) == 0)
 279       {
 280         break;
 281       }
 282     }
 283   }
 284
 285   return EFI_SUCCESS;
 286 }
 287
 288 /**
 289   Manages the multicast receive filters of a network interface.
 290
 291   This function is used enable and disable the hardware and software receive
 292   filters for the underlying network device.
 293   The receive filter change is broken down into three steps:
 294   * The filter mask bits that are set (ON) in the Enable parameter are added to
 295     the current receive filter settings.
 296   * The filter mask bits that are set (ON) in the Disable parameter are subtracted
 297     from the updated receive filter settings.
 298   * If the resulting receive filter setting is not supported by the hardware a
 299     more liberal setting is selected.
 300   If the same bits are set in the Enable and Disable parameters, then the bits
 301   in the Disable parameter takes precedence.
 302   If the ResetMCastFilter parameter is TRUE, then the multicast address list
 303   filter is disabled (irregardless of what other multicast bits are set in the
 304   Enable and Disable parameters). The SNP->Mode->MCastFilterCount field is set
 305   to zero. The Snp->Mode->MCastFilter contents are undefined.
 306   After enabling or disabling receive filter settings, software should verify
 307   the new settings by checking the Snp->Mode->ReceiveFilterSettings,
 308   Snp->Mode->MCastFilterCount and Snp->Mode->MCastFilter fields.
 309   Note: Some network drivers and/or devices will automatically promote receive
 310     filter settings if the requested setting can not be honored. For example, if
 311     a request for four multicast addresses is made and the underlying hardware
 312     only supports two multicast addresses the driver might set the promiscuous
 313     or promiscuous multicast receive filters instead. The receiving software is
 314     responsible for discarding any extra packets that get through the hardware
 315     receive filters.
 316     Note: Note: To disable all receive filter hardware, the network driver must
 317       be Shutdown() and Stopped(). Calling ReceiveFilters() with Disable set to
 318       Snp->Mode->ReceiveFilterSettings will make it so no more packets are
 319       returned by the Receive() function, but the receive hardware may still be
 320       moving packets into system memory before inspecting and discarding them.
 321       Unexpected system errors, reboots and hangs can occur if an OS is loaded
 322       and the network devices are not Shutdown() and Stopped().
 323   If ResetMCastFilter is TRUE, then the multicast receive filter list on the
 324   network interface will be reset to the default multicast receive filter list.
 325   If ResetMCastFilter is FALSE, and this network interface allows the multicast
 326   receive filter list to be modified, then the MCastFilterCnt and MCastFilter
 327   are used to update the current multicast receive filter list. The modified
 328   receive filter list settings can be found in the MCastFilter field of
 329   EFI_SIMPLE_NETWORK_MODE. If the network interface does not allow the multicast
 330   receive filter list to be modified, then EFI_INVALID_PARAMETER will be returned.
 331   If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
 332   If the receive filter mask and multicast receive filter list have been
 333   successfully updated on the network interface, EFI_SUCCESS will be returned.
 334
 335   @param This             A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
 336   @param Enable           A bit mask of receive filters to enable on the network
 337                           interface.
 338   @param Disable          A bit mask of receive filters to disable on the network
 339                           interface. For backward compatibility with EFI 1.1
 340                           platforms, the EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit
 341                           must be set when the ResetMCastFilter parameter is TRUE.
 342   @param ResetMCastFilter Set to TRUE to reset the contents of the multicast
 343                           receive filters on the network interface to their
 344                           default values.
 345   @param MCastFilterCnt   Number of multicast HW MAC addresses in the new MCastFilter
 346                           list. This value must be less than or equal to the
 347                           MCastFilterCnt field of EFI_SIMPLE_NETWORK_MODE.
 348                           This field is optional if ResetMCastFilter is TRUE.
 349   @param MCastFilter      A pointer to a list of new multicast receive filter HW
 350                           MAC addresses. This list will replace any existing
 351                           multicast HW MAC address list. This field is optional
 352                           if ResetMCastFilter is TRUE.
 353
 354   @retval EFI_SUCCESS            The multicast receive filter list was updated.
 355   @retval EFI_NOT_STARTED        The network interface has not been started.
 356   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 357                                  * This is NULL
 358                                  * There are bits set in Enable that are not set
 359                                    in Snp->Mode->ReceiveFilterMask
 360                                  * There are bits set in Disable that are not set
 361                                    in Snp->Mode->ReceiveFilterMask
 362                                  * Multicast is being enabled (the
 363                                    EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit is
 364                                    set in Enable, it is not set in Disable, and
 365                                    ResetMCastFilter is FALSE) and MCastFilterCount
 366                                    is zero
 367                                  * Multicast is being enabled and MCastFilterCount
 368                                    is greater than Snp->Mode->MaxMCastFilterCount
 369                                  * Multicast is being enabled and MCastFilter is NULL
 370                                  * Multicast is being enabled and one or more of
 371                                    the addresses in the MCastFilter list are not
 372                                    valid multicast MAC addresses
 373   @retval EFI_DEVICE_ERROR       One or more of the following conditions is TRUE:
 374                                  * The network interface has been started but has
 375                                    not been initialized
 376                                  * An unexpected error was returned by the
 377                                    underlying network driver or device
 378   @retval EFI_UNSUPPORTED        This function is not supported by the network
 379                                  interface.
 380
 381 **/
 382 EFI_STATUS
 383 EFIAPI
 384 SnpUndi32ReceiveFilters (
 385   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 386   IN UINT32                       Enable,
 387   IN UINT32                       Disable,
 388   IN BOOLEAN                      ResetMCastFilter,
 389   IN UINTN                        MCastFilterCnt   OPTIONAL,
 390   IN EFI_MAC_ADDRESS              *MCastFilter     OPTIONAL
 391   )
 392 {
 393   SNP_DRIVER  *Snp;
 394   EFI_STATUS  Status;
 395   EFI_TPL     OldTpl;
 396
 397   if (This == NULL) {
 398     return EFI_INVALID_PARAMETER;
 399   }
 400
 401   Snp = EFI_SIMPLE_NETWORK_DEV_FROM_THIS (This);
 402
 403   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 404
 405   switch (Snp->Mode.State) {
 406     case EfiSimpleNetworkInitialized:
 407       break;
 408
 409     case EfiSimpleNetworkStopped:
 410       Status = EFI_NOT_STARTED;
 411       goto ON_EXIT;
 412
 413     default:
 414       Status = EFI_DEVICE_ERROR;
 415       goto ON_EXIT;
 416   }
 417
 418   //
 419   // check if we are asked to enable or disable something that the UNDI
 420   // does not even support!
 421   //
 422   if (((Enable &~Snp->Mode.ReceiveFilterMask) != 0) ||
 423       ((Disable &~Snp->Mode.ReceiveFilterMask) != 0))
 424   {
 425     Status = EFI_INVALID_PARAMETER;
 426     goto ON_EXIT;
 427   }
 428
 429   if (ResetMCastFilter) {
 430     Disable       |= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST & Snp->Mode.ReceiveFilterMask;
 431     MCastFilterCnt = 0;
 432     MCastFilter    = NULL;
 433   } else {
 434     if (MCastFilterCnt != 0) {
 435       if ((MCastFilterCnt > Snp->Mode.MaxMCastFilterCount) ||
 436           (MCastFilter == NULL))
 437       {
 438         Status = EFI_INVALID_PARAMETER;
 439         goto ON_EXIT;
 440       }
 441     }
 442   }
 443
 444   if ((Enable == 0) && (Disable == 0) && !ResetMCastFilter && (MCastFilterCnt == 0)) {
 445     Status = EFI_SUCCESS;
 446     goto ON_EXIT;
 447   }
 448
 449   if (((Enable & EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST) != 0) && (MCastFilterCnt == 0)) {
 450     Status = EFI_INVALID_PARAMETER;
 451     goto ON_EXIT;
 452   }
 453
 454   if ((Enable != 0) || (MCastFilterCnt != 0)) {
 455     Status = PxeRecvFilterEnable (
 456                Snp,
 457                Enable,
 458                MCastFilterCnt,
 459                MCastFilter
 460                );
 461
 462     if (EFI_ERROR (Status)) {
 463       goto ON_EXIT;
 464     }
 465   }
 466
 467   if ((Disable != 0) || ResetMCastFilter) {
 468     Status = PxeRecvFilterDisable (Snp, Disable, ResetMCastFilter);
 469
 470     if (EFI_ERROR (Status)) {
 471       goto ON_EXIT;
 472     }
 473   }
 474
 475   Status = PxeRecvFilterRead (Snp);
 476
 477 ON_EXIT:
 478   gBS->RestoreTPL (OldTpl);
 479
 480   return Status;
 481 }