MdeModulePkg/Universal/Network/MnpDxe/MnpImpl.h

   1 /** @file
   2   Declaration of structures and functions of MnpDxe driver.
   3
   4 Copyright (c) 2005 - 2016, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions
   7 of the BSD License which accompanies this distribution.  The full
   8 text of the license may be found at<BR>
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _MNP_IMPL_H_
  17 #define _MNP_IMPL_H_
  18
  19 #include "MnpDriver.h"
  20
  21 #define NET_ETHER_FCS_SIZE            4
  22
  23 #define MNP_SYS_POLL_INTERVAL         (10 * TICKS_PER_MS)   // 10 milliseconds
  24 #define MNP_TIMEOUT_CHECK_INTERVAL    (50 * TICKS_PER_MS)   // 50 milliseconds
  25 #define MNP_MEDIA_DETECT_INTERVAL     (500 * TICKS_PER_MS)  // 500 milliseconds
  26 #define MNP_TX_TIMEOUT_TIME           (500 * TICKS_PER_MS)  // 500 milliseconds
  27 #define MNP_INIT_NET_BUFFER_NUM       512
  28 #define MNP_NET_BUFFER_INCREASEMENT   64
  29 #define MNP_MAX_NET_BUFFER_NUM        65536
  30 #define MNP_TX_BUFFER_INCREASEMENT    64
  31 #define MNP_MAX_TX_BUFFER_NUM         65536
  32
  33 #define MNP_MAX_RCVD_PACKET_QUE_SIZE  256
  34
  35 #define MNP_RECEIVE_UNICAST           0x01
  36 #define MNP_RECEIVE_BROADCAST         0x02
  37
  38 #define UNICAST_PACKET                MNP_RECEIVE_UNICAST
  39 #define BROADCAST_PACKET              MNP_RECEIVE_BROADCAST
  40
  41 #define MNP_INSTANCE_DATA_SIGNATURE   SIGNATURE_32 ('M', 'n', 'p', 'I')
  42
  43 #define MNP_INSTANCE_DATA_FROM_THIS(a) \
  44   CR ( \
  45   (a), \
  46   MNP_INSTANCE_DATA, \
  47   ManagedNetwork, \
  48   MNP_INSTANCE_DATA_SIGNATURE \
  49   )
  50
  51 typedef struct {
  52   UINT32                          Signature;
  53
  54   MNP_SERVICE_DATA                *MnpServiceData;
  55
  56   EFI_HANDLE                      Handle;
  57
  58   LIST_ENTRY                      InstEntry;
  59
  60   EFI_MANAGED_NETWORK_PROTOCOL    ManagedNetwork;
  61
  62   BOOLEAN                         Configured;
  63   BOOLEAN                         Destroyed;
  64
  65   LIST_ENTRY                      GroupCtrlBlkList;
  66
  67   NET_MAP                         RxTokenMap;
  68
  69   LIST_ENTRY                      RxDeliveredPacketQueue;
  70   LIST_ENTRY                      RcvdPacketQueue;
  71   UINTN                           RcvdPacketQueueSize;
  72
  73   EFI_MANAGED_NETWORK_CONFIG_DATA ConfigData;
  74
  75   UINT8                           ReceiveFilter;
  76 } MNP_INSTANCE_DATA;
  77
  78 typedef struct {
  79   LIST_ENTRY      AddrEntry;
  80   EFI_MAC_ADDRESS Address;
  81   INTN            RefCnt;
  82 } MNP_GROUP_ADDRESS;
  83
  84 typedef struct {
  85   LIST_ENTRY        CtrlBlkEntry;
  86   MNP_GROUP_ADDRESS *GroupAddress;
  87 } MNP_GROUP_CONTROL_BLOCK;
  88
  89 typedef struct {
  90   LIST_ENTRY                        WrapEntry;
  91   MNP_INSTANCE_DATA                 *Instance;
  92   EFI_MANAGED_NETWORK_RECEIVE_DATA  RxData;
  93   NET_BUF                           *Nbuf;
  94   UINT64                            TimeoutTick;
  95 } MNP_RXDATA_WRAP;
  96
  97 #define MNP_TX_BUF_WRAP_SIGNATURE   SIGNATURE_32 ('M', 'T', 'B', 'W')
  98
  99 typedef struct {
 100   UINT32                  Signature;
 101   LIST_ENTRY              WrapEntry;  // Link to FreeTxBufList
 102   LIST_ENTRY              AllEntry;   // Link to AllTxBufList
 103   BOOLEAN                 InUse;
 104   UINT8                   TxBuf[1];
 105 } MNP_TX_BUF_WRAP;
 106
 107 /**
 108   Initialize the mnp device context data.
 109
 110   @param[in, out]  MnpDeviceData      Pointer to the mnp device context data.
 111   @param[in]       ImageHandle        The driver image handle.
 112   @param[in]       ControllerHandle   Handle of device to bind driver to.
 113
 114   @retval EFI_SUCCESS           The mnp service context is initialized.
 115   @retval EFI_UNSUPPORTED       ControllerHandle does not support Simple Network Protocol.
 116   @retval Others                Other errors as indicated.
 117
 118 **/
 119 EFI_STATUS
 120 MnpInitializeDeviceData (
 121   IN OUT MNP_DEVICE_DATA   *MnpDeviceData,
 122   IN     EFI_HANDLE        ImageHandle,
 123   IN     EFI_HANDLE        ControllerHandle
 124   );
 125
 126 /**
 127   Destroy the MNP device context data.
 128
 129   @param[in, out]  MnpDeviceData      Pointer to the mnp device context data.
 130   @param[in]       ImageHandle        The driver image handle.
 131
 132 **/
 133 VOID
 134 MnpDestroyDeviceData (
 135   IN OUT MNP_DEVICE_DATA   *MnpDeviceData,
 136   IN     EFI_HANDLE        ImageHandle
 137   );
 138
 139 /**
 140   Create mnp service context data.
 141
 142   @param[in]       MnpDeviceData      Pointer to the mnp device context data.
 143   @param[in]       VlanId             The VLAN ID.
 144   @param[in]       Priority           The VLAN priority. If VlanId is 0,
 145                                       Priority is ignored.
 146
 147   @return A pointer to MNP_SERVICE_DATA or NULL if failed to create MNP service context.
 148
 149 **/
 150 MNP_SERVICE_DATA *
 151 MnpCreateServiceData (
 152   IN MNP_DEVICE_DATA     *MnpDeviceData,
 153   IN UINT16              VlanId,
 154   IN UINT8                Priority OPTIONAL
 155   );
 156
 157 /**
 158   Initialize the mnp service context data.
 159
 160   @param[in, out]  MnpServiceData     Pointer to the mnp service context data.
 161   @param[in]       ImageHandle        The driver image handle.
 162   @param[in]       ControllerHandle   Handle of device to bind driver to.
 163
 164   @retval EFI_SUCCESS           The mnp service context is initialized.
 165   @retval EFI_UNSUPPORTED       ControllerHandle does not support Simple Network Protocol.
 166   @retval Others                Other errors as indicated.
 167
 168 **/
 169 EFI_STATUS
 170 MnpInitializeServiceData (
 171   IN OUT MNP_SERVICE_DATA    *MnpServiceData,
 172   IN     EFI_HANDLE          ImageHandle,
 173   IN     EFI_HANDLE          ControllerHandle
 174   );
 175
 176 /**
 177   Destroy the MNP service context data.
 178
 179   @param[in, out]  MnpServiceData    Pointer to the mnp service context data.
 180
 181   @retval EFI_SUCCESS           The mnp service context is destroyed.
 182   @retval Others                Errors as indicated.
 183
 184 **/
 185 EFI_STATUS
 186 MnpDestroyServiceData (
 187   IN OUT MNP_SERVICE_DATA    *MnpServiceData
 188   );
 189
 190 /**
 191   Destroy all child of the MNP service data.
 192
 193   @param[in, out]  MnpServiceData    Pointer to the mnp service context data.
 194
 195   @retval EFI_SUCCESS           All child are destroyed.
 196   @retval Others                Failed to destroy all child.
 197
 198 **/
 199 EFI_STATUS
 200 MnpDestroyServiceChild (
 201   IN OUT MNP_SERVICE_DATA    *MnpServiceData
 202   );
 203
 204 /**
 205   Find the MNP Service Data for given VLAN ID.
 206
 207   @param[in]  MnpDeviceData      Pointer to the mnp device context data.
 208   @param[in]  VlanId             The VLAN ID.
 209
 210   @return A pointer to MNP_SERVICE_DATA or NULL if not found.
 211
 212 **/
 213 MNP_SERVICE_DATA *
 214 MnpFindServiceData (
 215   IN MNP_DEVICE_DATA     *MnpDeviceData,
 216   IN UINT16              VlanId
 217   );
 218
 219 /**
 220   Initialize the mnp instance context data.
 221
 222   @param[in]       MnpServiceData   Pointer to the mnp service context data.
 223   @param[in, out]  Instance         Pointer to the mnp instance context data
 224                                     to initialize.
 225
 226 **/
 227 VOID
 228 MnpInitializeInstanceData (
 229   IN     MNP_SERVICE_DATA    *MnpServiceData,
 230   IN OUT MNP_INSTANCE_DATA   *Instance
 231   );
 232
 233 /**
 234   Check whether the token specified by Arg matches the token in Item.
 235
 236   @param[in]  Map               Pointer to the NET_MAP.
 237   @param[in]  Item              Pointer to the NET_MAP_ITEM.
 238   @param[in]  Arg               Pointer to the Arg, it's a pointer to the token to
 239                                 check.
 240
 241   @retval EFI_SUCCESS           The token specified by Arg is different from the
 242                                 token in Item.
 243   @retval EFI_ACCESS_DENIED     The token specified by Arg is the same as that in
 244                                 Item.
 245
 246 **/
 247 EFI_STATUS
 248 EFIAPI
 249 MnpTokenExist (
 250   IN NET_MAP         *Map,
 251   IN NET_MAP_ITEM    *Item,
 252   IN VOID            *Arg
 253   );
 254
 255 /**
 256   Cancel the token specified by Arg if it matches the token in Item.
 257
 258   @param[in, out]  Map               Pointer to the NET_MAP.
 259   @param[in, out]  Item              Pointer to the NET_MAP_ITEM.
 260   @param[in]       Arg               Pointer to the Arg, it's a pointer to the
 261                                      token to cancel.
 262
 263   @retval EFI_SUCCESS       The Arg is NULL, and the token in Item is cancelled,
 264                             or the Arg isn't NULL, and the token in Item is
 265                             different from the Arg.
 266   @retval EFI_ABORTED       The Arg isn't NULL, the token in Item mathces the
 267                             Arg, and the token is cancelled.
 268
 269 **/
 270 EFI_STATUS
 271 EFIAPI
 272 MnpCancelTokens (
 273   IN OUT NET_MAP         *Map,
 274   IN OUT NET_MAP_ITEM    *Item,
 275   IN     VOID            *Arg
 276   );
 277
 278 /**
 279   Flush the instance's received data.
 280
 281   @param[in, out]  Instance              Pointer to the mnp instance context data.
 282
 283 **/
 284 VOID
 285 MnpFlushRcvdDataQueue (
 286   IN OUT MNP_INSTANCE_DATA   *Instance
 287   );
 288
 289 /**
 290   Configure the Instance using ConfigData.
 291
 292   @param[in, out]  Instance     Pointer to the mnp instance context data.
 293   @param[in]       ConfigData   Pointer to the configuration data used to configure
 294                                 the isntance.
 295
 296   @retval EFI_SUCCESS           The Instance is configured.
 297   @retval EFI_UNSUPPORTED       EnableReceiveTimestamps is on and the
 298                                 implementation doesn't support it.
 299   @retval Others                Other errors as indicated.
 300
 301 **/
 302 EFI_STATUS
 303 MnpConfigureInstance (
 304   IN OUT MNP_INSTANCE_DATA                 *Instance,
 305   IN     EFI_MANAGED_NETWORK_CONFIG_DATA   *ConfigData OPTIONAL
 306   );
 307
 308 /**
 309   Do the group operations for this instance.
 310
 311   @param[in, out]  Instance        Pointer to the instance context data.
 312   @param[in]       JoinFlag        Set to TRUE to join a group. Set to TRUE to
 313                                    leave a group/groups.
 314   @param[in]       MacAddress      Pointer to the group address to join or leave.
 315   @param[in]       CtrlBlk         Pointer to the group control block if JoinFlag
 316                                    is FALSE.
 317
 318   @retval EFI_SUCCESS              The group operation finished.
 319   @retval EFI_OUT_OF_RESOURCES     Failed due to lack of memory resources.
 320   @retval Others                   Other errors as indicated.
 321
 322 **/
 323 EFI_STATUS
 324 MnpGroupOp (
 325   IN OUT MNP_INSTANCE_DATA         *Instance,
 326   IN     BOOLEAN                   JoinFlag,
 327   IN     EFI_MAC_ADDRESS           *MacAddress OPTIONAL,
 328   IN     MNP_GROUP_CONTROL_BLOCK   *CtrlBlk OPTIONAL
 329   );
 330
 331 /**
 332   Validates the Mnp transmit token.
 333
 334   @param[in]  Instance            Pointer to the Mnp instance context data.
 335   @param[in]  Token               Pointer to the transmit token to check.
 336
 337   @return The Token is valid or not.
 338
 339 **/
 340 BOOLEAN
 341 MnpIsValidTxToken (
 342   IN MNP_INSTANCE_DATA                       *Instance,
 343   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN    *Token
 344   );
 345
 346 /**
 347   Build the packet to transmit from the TxData passed in.
 348
 349   @param[in]   MnpServiceData      Pointer to the mnp service context data.
 350   @param[in]   TxData              Pointer to the transmit data containing the information
 351                                    to build the packet.
 352   @param[out]  PktBuf              Pointer to record the address of the packet.
 353   @param[out]  PktLen              Pointer to a UINT32 variable used to record the packet's
 354                                    length.
 355
 356   @retval EFI_SUCCESS           TxPackage is built.
 357   @retval EFI_OUT_OF_RESOURCES  The deliver fails due to lack of memory resource.
 358
 359 **/
 360 EFI_STATUS
 361 MnpBuildTxPacket (
 362   IN     MNP_SERVICE_DATA                    *MnpServiceData,
 363   IN     EFI_MANAGED_NETWORK_TRANSMIT_DATA   *TxData,
 364      OUT UINT8                               **PktBuf,
 365      OUT UINT32                              *PktLen
 366   );
 367
 368 /**
 369   Synchronously send out the packet.
 370
 371   This functon places the packet buffer to SNP driver's tansmit queue. The packet
 372   can be considered successfully sent out once SNP acccetp the packet, while the
 373   packet buffer recycle is deferred for better performance.
 374
 375   @param[in]       MnpServiceData      Pointer to the mnp service context data.
 376   @param[in]       Packet              Pointer to the pakcet buffer.
 377   @param[in]       Length              The length of the packet.
 378   @param[in, out]  Token               Pointer to the token the packet generated from.
 379
 380   @retval EFI_SUCCESS                  The packet is sent out.
 381   @retval EFI_TIMEOUT                  Time out occurs, the packet isn't sent.
 382   @retval EFI_DEVICE_ERROR             An unexpected network error occurs.
 383
 384 **/
 385 EFI_STATUS
 386 MnpSyncSendPacket (
 387   IN     MNP_SERVICE_DATA                        *MnpServiceData,
 388   IN     UINT8                                   *Packet,
 389   IN     UINT32                                  Length,
 390   IN OUT EFI_MANAGED_NETWORK_COMPLETION_TOKEN    *Token
 391   );
 392
 393 /**
 394   Try to deliver the received packet to the instance.
 395
 396   @param[in, out]  Instance     Pointer to the mnp instance context data.
 397
 398   @retval EFI_SUCCESS           The received packet is delivered, or there is no
 399                                 packet to deliver, or there is no available receive
 400                                 token.
 401   @retval EFI_OUT_OF_RESOURCES  The deliver fails due to lack of memory resource.
 402
 403 **/
 404 EFI_STATUS
 405 MnpInstanceDeliverPacket (
 406   IN OUT MNP_INSTANCE_DATA   *Instance
 407   );
 408
 409 /**
 410   Recycle the RxData and other resources used to hold and deliver the received
 411   packet.
 412
 413   @param[in]  Event               The event this notify function registered to.
 414   @param[in]  Context             Pointer to the context data registerd to the Event.
 415
 416 **/
 417 VOID
 418 EFIAPI
 419 MnpRecycleRxData (
 420   IN EFI_EVENT     Event,
 421   IN VOID          *Context
 422   );
 423
 424 /**
 425   Try to receive a packet and deliver it.
 426
 427   @param[in, out]  MnpDeviceData        Pointer to the mnp device context data.
 428
 429   @retval EFI_SUCCESS           add return value to function comment
 430   @retval EFI_NOT_STARTED       The simple network protocol is not started.
 431   @retval EFI_NOT_READY         No packet received.
 432   @retval EFI_DEVICE_ERROR      An unexpected error occurs.
 433
 434 **/
 435 EFI_STATUS
 436 MnpReceivePacket (
 437   IN OUT MNP_DEVICE_DATA   *MnpDeviceData
 438   );
 439
 440 /**
 441   Allocate a free NET_BUF from MnpDeviceData->FreeNbufQue. If there is none
 442   in the queue, first try to allocate some and add them into the queue, then
 443   fetch the NET_BUF from the updated FreeNbufQue.
 444
 445   @param[in, out]  MnpDeviceData        Pointer to the MNP_DEVICE_DATA.
 446
 447   @return     Pointer to the allocated free NET_BUF structure, if NULL the
 448               operation is failed.
 449
 450 **/
 451 NET_BUF *
 452 MnpAllocNbuf (
 453   IN OUT MNP_DEVICE_DATA   *MnpDeviceData
 454   );
 455
 456 /**
 457   Try to reclaim the Nbuf into the buffer pool.
 458
 459   @param[in, out]  MnpDeviceData         Pointer to the mnp device context data.
 460   @param[in, out]  Nbuf                  Pointer to the NET_BUF to free.
 461
 462 **/
 463 VOID
 464 MnpFreeNbuf (
 465   IN OUT MNP_DEVICE_DATA   *MnpDeviceData,
 466   IN OUT NET_BUF           *Nbuf
 467   );
 468
 469 /**
 470   Allocate a free TX buffer from MnpDeviceData->FreeTxBufList. If there is none
 471   in the queue, first try to recycle some from SNP, then try to allocate some and add
 472   them into the queue, then fetch the NET_BUF from the updated FreeTxBufList.
 473
 474   @param[in, out]  MnpDeviceData        Pointer to the MNP_DEVICE_DATA.
 475
 476   @return     Pointer to the allocated free NET_BUF structure, if NULL the
 477               operation is failed.
 478
 479 **/
 480 UINT8 *
 481 MnpAllocTxBuf (
 482   IN OUT MNP_DEVICE_DATA   *MnpDeviceData
 483   );
 484
 485 /**
 486   Try to recycle all the transmitted buffer address from SNP.
 487
 488   @param[in, out]  MnpDeviceData     Pointer to the mnp device context data.
 489
 490   @retval EFI_SUCCESS             Successed to recyclethe transmitted buffer address.
 491   @retval Others                  Failed to recyclethe transmitted buffer address.
 492
 493 **/
 494 EFI_STATUS
 495 MnpRecycleTxBuf (
 496   IN OUT MNP_DEVICE_DATA   *MnpDeviceData
 497   );
 498
 499 /**
 500   Remove the received packets if timeout occurs.
 501
 502   @param[in]  Event        The event this notify function registered to.
 503   @param[in]  Context      Pointer to the context data registered to the event.
 504
 505 **/
 506 VOID
 507 EFIAPI
 508 MnpCheckPacketTimeout (
 509   IN EFI_EVENT     Event,
 510   IN VOID          *Context
 511   );
 512
 513 /**
 514   Poll to update MediaPresent field in SNP ModeData by Snp.GetStatus().
 515
 516   @param[in]  Event        The event this notify function registered to.
 517   @param[in]  Context      Pointer to the context data registered to the event.
 518
 519 **/
 520 VOID
 521 EFIAPI
 522 MnpCheckMediaStatus (
 523   IN EFI_EVENT     Event,
 524   IN VOID          *Context
 525   );
 526
 527 /**
 528   Poll to receive the packets from Snp. This function is either called by upperlayer
 529   protocols/applications or the system poll timer notify mechanism.
 530
 531   @param[in]  Event        The event this notify function registered to.
 532   @param[in]  Context      Pointer to the context data registered to the event.
 533
 534 **/
 535 VOID
 536 EFIAPI
 537 MnpSystemPoll (
 538   IN EFI_EVENT     Event,
 539   IN VOID          *Context
 540   );
 541
 542 /**
 543   Returns the operational parameters for the current MNP child driver. May also
 544   support returning the underlying SNP driver mode data.
 545
 546   The GetModeData() function is used to read the current mode data (operational
 547   parameters) from the MNP or the underlying SNP.
 548
 549   @param[in]  This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 550   @param[out] MnpConfigData Pointer to storage for MNP operational parameters. Type
 551                             EFI_MANAGED_NETWORK_CONFIG_DATA is defined in "Related
 552                             Definitions" below.
 553   @param[out] SnpModeData   Pointer to storage for SNP operational parameters. This
 554                             feature may be unsupported. Type EFI_SIMPLE_NETWORK_MODE
 555                             is defined in the EFI_SIMPLE_NETWORK_PROTOCOL.
 556
 557   @retval EFI_SUCCESS           The operation completed successfully.
 558   @retval EFI_INVALID_PARAMETER This is NULL.
 559   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this
 560                                 MNP implementation.
 561   @retval EFI_NOT_STARTED       This MNP child driver instance has not been
 562                                 configured. The default values are returned in
 563                                 MnpConfigData if it is not NULL.
 564   @retval Others                The mode data could not be read.
 565
 566 **/
 567 EFI_STATUS
 568 EFIAPI
 569 MnpGetModeData (
 570   IN     EFI_MANAGED_NETWORK_PROTOCOL      *This,
 571      OUT EFI_MANAGED_NETWORK_CONFIG_DATA   *MnpConfigData OPTIONAL,
 572      OUT EFI_SIMPLE_NETWORK_MODE           *SnpModeData OPTIONAL
 573   );
 574
 575 /**
 576   Sets or clears the operational parameters for the MNP child driver.
 577
 578   The Configure() function is used to set, change, or reset the operational
 579   parameters for the MNP child driver instance. Until the operational parameters
 580   have been set, no network traffic can be sent or received by this MNP child
 581   driver instance. Once the operational parameters have been reset, no more
 582   traffic can be sent or received until the operational parameters have been set
 583   again.
 584   Each MNP child driver instance can be started and stopped independently of
 585   each other by setting or resetting their receive filter settings with the
 586   Configure() function.
 587   After any successful call to Configure(), the MNP child driver instance is
 588   started. The internal periodic timer (if supported) is enabled. Data can be
 589   transmitted and may be received if the receive filters have also been enabled.
 590   Note: If multiple MNP child driver instances will receive the same packet
 591   because of overlapping receive filter settings, then the first MNP child
 592   driver instance will receive the original packet and additional instances will
 593   receive copies of the original packet.
 594   Note: Warning: Receive filter settings that overlap will consume extra
 595   processor and/or DMA resources and degrade system and network performance.
 596
 597   @param[in]  This           Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 598   @param[in]  MnpConfigData  Pointer to configuration data that will be assigned
 599                              to the MNP child driver instance. If NULL, the MNP
 600                              child driver instance is reset to startup defaults
 601                              and all pending transmit and receive requests are
 602                              flushed. Type EFI_MANAGED_NETWORK_CONFIG_DATA is
 603                              defined in EFI_MANAGED_NETWORK_PROTOCOL.GetModeData().
 604
 605   @retval EFI_SUCCESS            The operation completed successfully.
 606   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is
 607                                  TRUE:
 608                                  * This is NULL.
 609                                  * MnpConfigData.ProtocolTypeFilter is not
 610                                    valid.
 611                                  The operational data for the MNP child driver
 612                                  instance is unchanged.
 613   @retval EFI_OUT_OF_RESOURCES   Required system resources (usually memory)
 614                                  could not be allocated.
 615                                  The MNP child driver instance has been reset to
 616                                  startup defaults.
 617   @retval EFI_UNSUPPORTED        The requested feature is unsupported in
 618                                  this [MNP] implementation. The operational data
 619                                  for the MNP child driver instance is unchanged.
 620   @retval EFI_DEVICE_ERROR       An unexpected network or system error
 621                                  occurred. The MNP child driver instance has
 622                                  been reset to startup defaults.
 623   @retval Others                 The MNP child driver instance has been reset to
 624                                  startup defaults.
 625
 626 **/
 627 EFI_STATUS
 628 EFIAPI
 629 MnpConfigure (
 630   IN EFI_MANAGED_NETWORK_PROTOCOL        *This,
 631   IN EFI_MANAGED_NETWORK_CONFIG_DATA     *MnpConfigData OPTIONAL
 632   );
 633
 634 /**
 635   Translates an IP multicast address to a hardware (MAC) multicast address. This
 636   function may be unsupported in some MNP implementations.
 637
 638   The McastIpToMac() function translates an IP multicast address to a hardware
 639   (MAC) multicast address. This function may be implemented by calling the
 640   underlying EFI_SIMPLE_NETWORK. MCastIpToMac() function, which may also be
 641   unsupported in some MNP implementations.
 642
 643   @param[in]  This        Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 644   @param[in]  Ipv6Flag    Set to TRUE to if IpAddress is an IPv6 multicast address.
 645                           Set to FALSE if IpAddress is an IPv4 multicast address.
 646   @param[in]  IpAddress   Pointer to the multicast IP address (in network byte
 647                           order) to convert.
 648   @param[out] MacAddress  Pointer to the resulting multicast MAC address.
 649
 650   @retval EFI_SUCCESS           The operation completed successfully.
 651   @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:
 652                                  * This is NULL.
 653                                  * IpAddress is NULL.
 654                                  * IpAddress is not a valid multicast IP
 655                                    address.
 656                                  * MacAddress is NULL.
 657   @retval EFI_NOT_STARTED       This MNP child driver instance has not been
 658                                 configured.
 659   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this
 660                                 MNP implementation.
 661   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 662   @retval Others                The address could not be converted.
 663 **/
 664 EFI_STATUS
 665 EFIAPI
 666 MnpMcastIpToMac (
 667   IN     EFI_MANAGED_NETWORK_PROTOCOL    *This,
 668   IN     BOOLEAN                         Ipv6Flag,
 669   IN     EFI_IP_ADDRESS                  *IpAddress,
 670      OUT EFI_MAC_ADDRESS                 *MacAddress
 671   );
 672
 673 /**
 674   Enables and disables receive filters for multicast address. This function may
 675   be unsupported in some MNP implementations.
 676
 677   The Groups() function only adds and removes multicast MAC addresses from the
 678   filter list. The MNP driver does not transmit or process Internet Group
 679   Management Protocol (IGMP) packets. If JoinFlag is FALSE and MacAddress is
 680   NULL, then all joined groups are left.
 681
 682   @param[in]  This        Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 683   @param[in]  JoinFlag    Set to TRUE to join this multicast group.
 684                           Set to FALSE to leave this multicast group.
 685   @param[in]  MacAddress  Pointer to the multicast MAC group (address) to join or
 686                           leave.
 687
 688   @retval EFI_SUCCESS           The requested operation completed successfully.
 689   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 690                                 * This is NULL.
 691                                 * JoinFlag is TRUE and MacAddress is NULL.
 692                                 * MacAddress is not a valid multicast MAC
 693                                   address.
 694                                 * The MNP multicast group settings are
 695                                   unchanged.
 696   @retval EFI_NOT_STARTED       This MNP child driver instance has not been
 697                                 configured.
 698   @retval EFI_ALREADY_STARTED   The supplied multicast group is already joined.
 699   @retval EFI_NOT_FOUND         The supplied multicast group is not joined.
 700   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 701                                 The MNP child driver instance has been reset to
 702                                 startup defaults.
 703   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP
 704                                 implementation.
 705   @retval Others                The requested operation could not be completed.
 706                                 The MNP multicast group settings are unchanged.
 707
 708 **/
 709 EFI_STATUS
 710 EFIAPI
 711 MnpGroups (
 712   IN EFI_MANAGED_NETWORK_PROTOCOL    *This,
 713   IN BOOLEAN                         JoinFlag,
 714   IN EFI_MAC_ADDRESS                 *MacAddress OPTIONAL
 715   );
 716
 717 /**
 718   Places asynchronous outgoing data packets into the transmit queue.
 719
 720   The Transmit() function places a completion token into the transmit packet
 721   queue. This function is always asynchronous.
 722   The caller must fill in the Token.Event and Token.TxData fields in the
 723   completion token, and these fields cannot be NULL. When the transmit operation
 724   completes, the MNP updates the Token.Status field and the Token.Event is
 725   signaled.
 726   Note: There may be a performance penalty if the packet needs to be
 727   defragmented before it can be transmitted by the network device. Systems in
 728   which performance is critical should review the requirements and features of
 729   the underlying communications device and drivers.
 730
 731
 732   @param[in]  This    Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 733   @param[in]  Token   Pointer to a token associated with the transmit data
 734                       descriptor. Type EFI_MANAGED_NETWORK_COMPLETION_TOKEN
 735                       is defined in "Related Definitions" below.
 736
 737   @retval EFI_SUCCESS            The transmit completion token was cached.
 738   @retval EFI_NOT_STARTED        This MNP child driver instance has not been
 739                                  configured.
 740   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is
 741                                  TRUE:
 742                                  * This is NULL.
 743                                  * Token is NULL.
 744                                  * Token.Event is NULL.
 745                                  * Token.TxData is NULL.
 746                                  * Token.TxData.DestinationAddress is not
 747                                    NULL and Token.TxData.HeaderLength is zero.
 748                                  * Token.TxData.FragmentCount is zero.
 749                                  * (Token.TxData.HeaderLength +
 750                                    Token.TxData.DataLength) is not equal to the
 751                                    sum of the
 752                                    Token.TxData.FragmentTable[].FragmentLength
 753                                    fields.
 754                                  * One or more of the
 755                                    Token.TxData.FragmentTable[].FragmentLength
 756                                    fields is zero.
 757                                  * One or more of the
 758                                    Token.TxData.FragmentTable[].FragmentBufferfields
 759                                    is NULL.
 760                                  * Token.TxData.DataLength is greater than MTU.
 761   @retval EFI_ACCESS_DENIED      The transmit completion token is already in the
 762                                  transmit queue.
 763   @retval EFI_OUT_OF_RESOURCES   The transmit data could not be queued due to a
 764                                  lack of system resources (usually memory).
 765   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
 766                                  The MNP child driver instance has been reset to
 767                                  startup defaults.
 768   @retval EFI_NOT_READY          The transmit request could not be queued because
 769                                  the transmit queue is full.
 770
 771 **/
 772 EFI_STATUS
 773 EFIAPI
 774 MnpTransmit (
 775   IN EFI_MANAGED_NETWORK_PROTOCOL            *This,
 776   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN    *Token
 777   );
 778
 779 /**
 780   Aborts an asynchronous transmit or receive request.
 781
 782   The Cancel() function is used to abort a pending transmit or receive request.
 783   If the token is in the transmit or receive request queues, after calling this
 784   function, Token.Status will be set to EFI_ABORTED and then Token.Event will be
 785   signaled. If the token is not in one of the queues, which usually means that
 786   the asynchronous operation has completed, this function will not signal the
 787   token and EFI_NOT_FOUND is returned.
 788
 789   @param[in]  This     Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 790   @param[in]  Token    Pointer to a token that has been issued by
 791                        EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or
 792                        EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, all
 793                        pending tokens are aborted.
 794
 795   @retval EFI_SUCCESS            The asynchronous I/O request was aborted and
 796                                  Token.Event was signaled. When Token is NULL,
 797                                  all pending requests were aborted and their
 798                                  events were signaled.
 799   @retval EFI_NOT_STARTED        This MNP child driver instance has not been
 800                                  configured.
 801   @retval EFI_INVALID_PARAMETER  This is NULL.
 802   @retval EFI_NOT_FOUND          When Token is not NULL, the asynchronous I/O
 803                                  request was not found in the transmit or
 804                                  receive queue. It has either completed or was
 805                                  not issued by Transmit() and Receive().
 806
 807 **/
 808 EFI_STATUS
 809 EFIAPI
 810 MnpCancel (
 811   IN EFI_MANAGED_NETWORK_PROTOCOL            *This,
 812   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN    *Token OPTIONAL
 813   );
 814
 815 /**
 816   Places an asynchronous receiving request into the receiving queue.
 817
 818   The Receive() function places a completion token into the receive packet
 819   queue. This function is always asynchronous.
 820   The caller must fill in the Token.Event field in the completion token, and
 821   this field cannot be NULL. When the receive operation completes, the MNP
 822   updates the Token.Status and Token.RxData fields and the Token.Event is
 823   signaled.
 824
 825   @param[in]  This      Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 826   @param[in]  Token     Pointer to a token associated with the receive
 827                         data descriptor. Type
 828                         EFI_MANAGED_NETWORK_COMPLETION_TOKEN is defined in
 829                         EFI_MANAGED_NETWORK_PROTOCOL.Transmit().
 830
 831   @retval EFI_SUCCESS            The receive completion token was cached.
 832   @retval EFI_NOT_STARTED        This MNP child driver instance has not been
 833                                  configured.
 834   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is
 835                                  TRUE:
 836                                  * This is NULL.
 837                                  * Token is NULL.
 838                                  * Token.Event is NULL
 839   @retval EFI_OUT_OF_RESOURCES   The transmit data could not be queued due to a
 840                                  lack of system resources (usually memory).
 841   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
 842                                  The MNP child driver instance has been reset to
 843                                  startup defaults.
 844   @retval EFI_ACCESS_DENIED      The receive completion token was already in the
 845                                  receive queue.
 846   @retval EFI_NOT_READY          The receive request could not be queued because
 847                                  the receive queue is full.
 848
 849 **/
 850 EFI_STATUS
 851 EFIAPI
 852 MnpReceive (
 853   IN EFI_MANAGED_NETWORK_PROTOCOL            *This,
 854   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN    *Token
 855   );
 856
 857 /**
 858   Polls for incoming data packets and processes outgoing data packets.
 859
 860   The Poll() function can be used by network drivers and applications to
 861   increase the rate that data packets are moved between the communications
 862   device and the transmit and receive queues.
 863   Normally, a periodic timer event internally calls the Poll() function. But, in
 864   some systems, the periodic timer event may not call Poll() fast enough to
 865   transmit and/or receive all data packets without missing packets. Drivers and
 866   applications that are experiencing packet loss should try calling the Poll()
 867   function more often.
 868
 869   @param[in]  This         Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 870
 871   @retval EFI_SUCCESS      Incoming or outgoing data was processed.
 872   @retval EFI_NOT_STARTED  This MNP child driver instance has not been
 873                            configured.
 874   @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The
 875                            MNP child driver instance has been reset to startup
 876                            defaults.
 877   @retval EFI_NOT_READY    No incoming or outgoing data was processed. Consider
 878                            increasing the polling rate.
 879   @retval EFI_TIMEOUT      Data was dropped out of the transmit and/or receive
 880                            queue. Consider increasing the polling rate.
 881
 882 **/
 883 EFI_STATUS
 884 EFIAPI
 885 MnpPoll (
 886   IN EFI_MANAGED_NETWORK_PROTOCOL    *This
 887   );
 888
 889 /**
 890   Configure the Snp receive filters according to the instances' receive filter
 891   settings.
 892
 893   @param[in]  MnpDeviceData         Pointer to the mnp device context data.
 894
 895   @retval     EFI_SUCCESS           The receive filters is configured.
 896   @retval     EFI_OUT_OF_RESOURCES  The receive filters can't be configured due
 897                                     to lack of memory resource.
 898
 899 **/
 900 EFI_STATUS
 901 MnpConfigReceiveFilters (
 902   IN MNP_DEVICE_DATA     *MnpDeviceData
 903   );
 904
 905 #endif