EmulatorPkg/EmuSnpDxe/EmuSnpDxe.h

   1 /** @file
   2
   3  Copyright (c) 2010, Apple, Inc. All rights reserved.<BR>
   4
   5     SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 Module Name:
   8
   9   EmuSnp.h
  10
  11 Abstract:
  12
  13 -**/
  14
  15 #ifndef _EMU_SNP_H_
  16 #define _EMU_SNP_H_
  17
  18 #include <Uefi.h>
  19
  20 #include <Protocol/SimpleNetwork.h>
  21 #include <Protocol/DevicePath.h>
  22 #include <Protocol/EmuIoThunk.h>
  23 #include <Protocol/EmuSnp.h>
  24
  25 #include <Library/BaseLib.h>
  26 #include <Library/DebugLib.h>
  27 #include <Library/BaseMemoryLib.h>
  28 #include <Library/UefiBootServicesTableLib.h>
  29 #include <Library/UefiLib.h>
  30 #include <Library/DevicePathLib.h>
  31 #include <Library/MemoryAllocationLib.h>
  32 #include <Library/NetLib.h>
  33
  34 #define NET_ETHER_HEADER_SIZE  14
  35
  36 //
  37 //  Private data for driver.
  38 //
  39 #define EMU_SNP_PRIVATE_DATA_SIGNATURE  SIGNATURE_32( 'U', 'S', 'N', 'P' )
  40
  41 typedef struct {
  42   UINTN                          Signature;
  43   EMU_IO_THUNK_PROTOCOL          *IoThunk;
  44   EMU_SNP_PROTOCOL               *Io;
  45   EFI_DEVICE_PATH_PROTOCOL       *DevicePath;
  46
  47   EFI_HANDLE                     EfiHandle;
  48   EFI_HANDLE                     DeviceHandle;
  49
  50   EFI_SIMPLE_NETWORK_PROTOCOL    Snp;
  51   EFI_SIMPLE_NETWORK_MODE        Mode;
  52
  53   EFI_UNICODE_STRING_TABLE       *ControllerNameTable;
  54 } EMU_SNP_PRIVATE_DATA;
  55
  56 #define EMU_SNP_PRIVATE_DATA_FROM_SNP_THIS(a) \
  57       CR( a, EMU_SNP_PRIVATE_DATA, Snp, EMU_SNP_PRIVATE_DATA_SIGNATURE )
  58
  59 extern EFI_DRIVER_BINDING_PROTOCOL   gEmuSnpDriverBinding;
  60 extern EFI_COMPONENT_NAME_PROTOCOL   gEmuSnpDriverComponentName;
  61 extern EFI_COMPONENT_NAME2_PROTOCOL  gEmuSnpDriverComponentName2;
  62
  63 /**
  64   Test to see if this driver supports ControllerHandle. This service
  65   is called by the EFI boot service ConnectController(). In
  66   order to make drivers as small as possible, there are a few calling
  67   restrictions for this service. ConnectController() must
  68   follow these calling restrictions. If any other agent wishes to call
  69   Supported() it must also follow these calling restrictions.
  70
  71   @param  This                Protocol instance pointer.
  72   @param  ControllerHandle    Handle of device to test
  73   @param  RemainingDevicePath Optional parameter use to pick a specific child
  74                               device to start.
  75
  76   @retval EFI_SUCCESS         This driver supports this device
  77   @retval EFI_UNSUPPORTED     This driver does not support this device
  78
  79 **/
  80 EFI_STATUS
  81 EFIAPI
  82 EmuSnpDriverBindingSupported (
  83   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  84   IN EFI_HANDLE                   ControllerHandle,
  85   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
  86   );
  87
  88 /**
  89   Start this driver on ControllerHandle. This service is called by the
  90   EFI boot service ConnectController(). In order to make
  91   drivers as small as possible, there are a few calling restrictions for
  92   this service. ConnectController() must follow these
  93   calling restrictions. If any other agent wishes to call Start() it
  94   must also follow these calling restrictions.
  95
  96   @param  This                 Protocol instance pointer.
  97   @param  ControllerHandle     Handle of device to bind driver to
  98   @param  RemainingDevicePath  Optional parameter use to pick a specific child
  99                                device to start.
 100
 101   @retval EFI_SUCCESS          Always succeeds.
 102
 103 **/
 104 EFI_STATUS
 105 EFIAPI
 106 EmuSnpDriverBindingStart (
 107   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 108   IN EFI_HANDLE                   ControllerHandle,
 109   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 110   );
 111
 112 /**
 113   Stop this driver on ControllerHandle. This service is called by the
 114   EFI boot service DisconnectController(). In order to
 115   make drivers as small as possible, there are a few calling
 116   restrictions for this service. DisconnectController()
 117   must follow these calling restrictions. If any other agent wishes
 118   to call Stop() it must also follow these calling restrictions.
 119
 120   @param  This              Protocol instance pointer.
 121   @param  ControllerHandle  Handle of device to stop driver on
 122   @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of
 123                             children is zero stop the entire bus driver.
 124   @param  ChildHandleBuffer List of Child Handles to Stop.
 125
 126   @retval EFI_SUCCESS       Always succeeds.
 127
 128 **/
 129 EFI_STATUS
 130 EFIAPI
 131 EmuSnpDriverBindingStop (
 132   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,
 133   IN  EFI_HANDLE                   ControllerHandle,
 134   IN  UINTN                        NumberOfChildren,
 135   IN  EFI_HANDLE                   *ChildHandleBuffer
 136   );
 137
 138 /**
 139   Changes the state of a network interface from "stopped" to "started".
 140
 141   @param  This Protocol instance pointer.
 142
 143   @retval EFI_SUCCESS           Always succeeds.
 144
 145 **/
 146 EFI_STATUS
 147 EFIAPI
 148 EmuSnpStart (
 149   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This
 150   );
 151
 152 /**
 153   Changes the state of a network interface from "started" to "stopped".
 154
 155   @param  This Protocol instance pointer.
 156
 157   @retval EFI_SUCCESS           Always succeeds.
 158
 159 **/
 160 EFI_STATUS
 161 EFIAPI
 162 EmuSnpStop (
 163   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This
 164   );
 165
 166 /**
 167   Resets a network adapter and allocates the transmit and receive buffers
 168   required by the network interface; optionally, also requests allocation
 169   of additional transmit and receive buffers.
 170
 171   @param  This              Protocol instance pointer.
 172   @param  ExtraRxBufferSize The size, in bytes, of the extra receive buffer space
 173                             that the driver should allocate for the network interface.
 174                             Some network interfaces will not be able to use the extra
 175                             buffer, and the caller will not know if it is actually
 176                             being used.
 177   @param  ExtraTxBufferSize The size, in bytes, of the extra transmit buffer space
 178                             that the driver should allocate for the network interface.
 179                             Some network interfaces will not be able to use the extra
 180                             buffer, and the caller will not know if it is actually
 181                             being used.
 182
 183   @retval EFI_SUCCESS           Always succeeds.
 184
 185 **/
 186 EFI_STATUS
 187 EFIAPI
 188 EmuSnpInitialize (
 189   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 190   IN UINTN                        ExtraRxBufferSize OPTIONAL,
 191   IN UINTN                        ExtraTxBufferSize OPTIONAL
 192   );
 193
 194 /**
 195   Resets a network adapter and re-initializes it with the parameters that were
 196   provided in the previous call to Initialize().
 197
 198   @param  This                 Protocol instance pointer.
 199   @param  ExtendedVerification Indicates that the driver may perform a more
 200                                exhaustive verification operation of the device
 201                                during reset.
 202
 203   @retval EFI_SUCCESS           Always succeeds.
 204
 205 **/
 206 EFI_STATUS
 207 EFIAPI
 208 EmuSnpReset (
 209   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 210   IN BOOLEAN                      ExtendedVerification
 211   );
 212
 213 /**
 214   Resets a network adapter and leaves it in a state that is safe for
 215   another driver to initialize.
 216
 217   @param  This Protocol instance pointer.
 218
 219   @retval EFI_SUCCESS           Always succeeds.
 220
 221 **/
 222 EFI_STATUS
 223 EFIAPI
 224 EmuSnpShutdown (
 225   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This
 226   );
 227
 228 /**
 229   Manages the multicast receive filters of a network interface.
 230
 231   @param  This               Protocol instance pointer.
 232   @param  EnableBits         A bit mask of receive filters to enable on the network interface.
 233   @param  DisableBits        A bit mask of receive filters to disable on the network interface.
 234   @param  ResetMcastFilter   Set to TRUE to reset the contents of the multicast receive
 235                              filters on the network interface to their default values.
 236   @param  McastFilterCount   Number of multicast HW MAC addresses in the new
 237                              MCastFilter list. This value must be less than or equal to
 238                              the MCastFilterCnt field of EFI_SIMPLE_NETWORK_MODE. This
 239                              field is optional if ResetMCastFilter is TRUE.
 240   @param  McastFilter        A pointer to a list of new multicast receive filter HW MAC
 241                              addresses. This list will replace any existing multicast
 242                              HW MAC address list. This field is optional if
 243                              ResetMCastFilter is TRUE.
 244
 245   @retval EFI_SUCCESS           The multicast receive filter list was updated.
 246   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
 247
 248 **/
 249 EFI_STATUS
 250 EFIAPI
 251 EmuSnpReceiveFilters (
 252   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 253   IN UINT32                       EnableBits,
 254   IN UINT32                       DisableBits,
 255   IN BOOLEAN                      ResetMcastFilter,
 256   IN UINTN                        McastFilterCount OPTIONAL,
 257   IN EFI_MAC_ADDRESS              *McastFilter OPTIONAL
 258   );
 259
 260 /**
 261   Modifies or resets the current station address, if supported.
 262
 263   @param  This         Protocol instance pointer.
 264   @param  Reset        Flag used to reset the station address to the network interfaces
 265                        permanent address.
 266   @param  NewMacAddr   New station address to be used for the network interface.
 267
 268   @retval EFI_UNSUPPORTED       Not supported yet.
 269
 270 **/
 271 EFI_STATUS
 272 EFIAPI
 273 EmuSnpStationAddress (
 274   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 275   IN BOOLEAN                      Reset,
 276   IN EFI_MAC_ADDRESS              *NewMacAddr OPTIONAL
 277   );
 278
 279 /**
 280   Resets or collects the statistics on a network interface.
 281
 282   @param  This            Protocol instance pointer.
 283   @param  Reset           Set to TRUE to reset the statistics for the network interface.
 284   @param  StatisticsSize  On input the size, in bytes, of StatisticsTable. On
 285                           output the size, in bytes, of the resulting table of
 286                           statistics.
 287   @param  StatisticsTable A pointer to the EFI_NETWORK_STATISTICS structure that
 288                           contains the statistics.
 289
 290   @retval EFI_SUCCESS           The statistics were collected from the network interface.
 291   @retval EFI_NOT_STARTED       The network interface has not been started.
 292   @retval EFI_BUFFER_TOO_SMALL  The Statistics buffer was too small. The current buffer
 293                                 size needed to hold the statistics is returned in
 294                                 StatisticsSize.
 295   @retval EFI_UNSUPPORTED       Not supported yet.
 296
 297 **/
 298 EFI_STATUS
 299 EFIAPI
 300 EmuSnpStatistics (
 301   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 302   IN BOOLEAN                      Reset,
 303   IN OUT UINTN                    *StatisticsSize OPTIONAL,
 304   OUT EFI_NETWORK_STATISTICS      *StatisticsTable OPTIONAL
 305   );
 306
 307 /**
 308   Converts a multicast IP address to a multicast HW MAC address.
 309
 310   @param  This  Protocol instance pointer.
 311   @param  Ipv6  Set to TRUE if the multicast IP address is IPv6 [RFC 2460]. Set
 312                 to FALSE if the multicast IP address is IPv4 [RFC 791].
 313   @param  Ip    The multicast IP address that is to be converted to a multicast
 314                 HW MAC address.
 315   @param  Mac   The multicast HW MAC address that is to be generated from IP.
 316
 317   @retval EFI_SUCCESS           The multicast IP address was mapped to the multicast
 318                                 HW MAC address.
 319   @retval EFI_NOT_STARTED       The network interface has not been started.
 320   @retval EFI_BUFFER_TOO_SMALL  The Statistics buffer was too small. The current buffer
 321                                 size needed to hold the statistics is returned in
 322                                 StatisticsSize.
 323   @retval EFI_UNSUPPORTED       Not supported yet.
 324
 325 **/
 326 EFI_STATUS
 327 EFIAPI
 328 EmuSnpMcastIptoMac (
 329   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 330   IN BOOLEAN                      Ipv6,
 331   IN EFI_IP_ADDRESS               *Ip,
 332   OUT EFI_MAC_ADDRESS             *Mac
 333   );
 334
 335 /**
 336   Performs read and write operations on the NVRAM device attached to a
 337   network interface.
 338
 339   @param  This         Protocol instance pointer.
 340   @param  ReadOrWrite  TRUE for read operations, FALSE for write operations.
 341   @param  Offset       Byte offset in the NVRAM device at which to start the read or
 342                        write operation. This must be a multiple of NvRamAccessSize and
 343                        less than NvRamSize.
 344   @param  BufferSize   The number of bytes to read or write from the NVRAM device.
 345                        This must also be a multiple of NvramAccessSize.
 346   @param  Buffer       A pointer to the data buffer.
 347
 348   @retval EFI_UNSUPPORTED       Not supported yet.
 349
 350 **/
 351 EFI_STATUS
 352 EFIAPI
 353 EmuSnpNvdata (
 354   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 355   IN BOOLEAN                      ReadOrWrite,
 356   IN UINTN                        Offset,
 357   IN UINTN                        BufferSize,
 358   IN OUT VOID                     *Buffer
 359   );
 360
 361 /**
 362   Reads the current interrupt status and recycled transmit buffer status from
 363   a network interface.
 364
 365   @param  This            Protocol instance pointer.
 366   @param  InterruptStatus A pointer to the bit mask of the currently active interrupts
 367                           If this is NULL, the interrupt status will not be read from
 368                           the device. If this is not NULL, the interrupt status will
 369                           be read from the device. When the  interrupt status is read,
 370                           it will also be cleared. Clearing the transmit  interrupt
 371                           does not empty the recycled transmit buffer array.
 372   @param  TxBuffer        Recycled transmit buffer address. The network interface will
 373                           not transmit if its internal recycled transmit buffer array
 374                           is full. Reading the transmit buffer does not clear the
 375                           transmit interrupt. If this is NULL, then the transmit buffer
 376                           status will not be read. If there are no transmit buffers to
 377                           recycle and TxBuf is not NULL, * TxBuf will be set to NULL.
 378
 379   @retval EFI_SUCCESS           Always succeeds.
 380
 381 **/
 382 EFI_STATUS
 383 EFIAPI
 384 EmuSnpGetStatus (
 385   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 386   OUT UINT32                      *InterruptStatus,
 387   OUT VOID                        **TxBuffer
 388   );
 389
 390 /**
 391   Places a packet in the transmit queue of a network interface.
 392
 393   @param  This       Protocol instance pointer.
 394   @param  HeaderSize The size, in bytes, of the media header to be filled in by
 395                      the Transmit() function. If HeaderSize is non-zero, then it
 396                      must be equal to This->Mode->MediaHeaderSize and the DestAddr
 397                      and Protocol parameters must not be NULL.
 398   @param  BufferSize The size, in bytes, of the entire packet (media header and
 399                      data) to be transmitted through the network interface.
 400   @param  Buffer     A pointer to the packet (media header followed by data) to be
 401                      transmitted. This parameter cannot be NULL. If HeaderSize is zero,
 402                      then the media header in Buffer must already be filled in by the
 403                      caller. If HeaderSize is non-zero, then the media header will be
 404                      filled in by the Transmit() function.
 405   @param  SrcAddr    The source HW MAC address. If HeaderSize is zero, then this parameter
 406                      is ignored. If HeaderSize is non-zero and SrcAddr is NULL, then
 407                      This->Mode->CurrentAddress is used for the source HW MAC address.
 408   @param  DestAddr   The destination HW MAC address. If HeaderSize is zero, then this
 409                      parameter is ignored.
 410   @param  Protocol   The type of header to build. If HeaderSize is zero, then this
 411                      parameter is ignored. See RFC 1700, section "Ether Types", for
 412                      examples.
 413
 414   @retval EFI_SUCCESS           The packet was placed on the transmit queue.
 415   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
 416   @retval EFI_ACCESS_DENIED     Error acquire global lock for operation.
 417
 418 **/
 419 EFI_STATUS
 420 EFIAPI
 421 EmuSnpTransmit (
 422   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 423   IN UINTN                        HeaderSize,
 424   IN UINTN                        BufferSize,
 425   IN VOID                         *Buffer,
 426   IN EFI_MAC_ADDRESS              *SrcAddr OPTIONAL,
 427   IN EFI_MAC_ADDRESS              *DestAddr OPTIONAL,
 428   IN UINT16                       *Protocol OPTIONAL
 429   );
 430
 431 /**
 432   Receives a packet from a network interface.
 433
 434   @param  This             Protocol instance pointer.
 435   @param  HeaderSize       The size, in bytes, of the media header received on the network
 436                            interface. If this parameter is NULL, then the media header size
 437                            will not be returned.
 438   @param  BuffSize         On entry, the size, in bytes, of Buffer. On exit, the size, in
 439                            bytes, of the packet that was received on the network interface.
 440   @param  Buffer           A pointer to the data buffer to receive both the media header and
 441                            the data.
 442   @param  SourceAddr       The source HW MAC address. If this parameter is NULL, the
 443                            HW MAC source address will not be extracted from the media
 444                            header.
 445   @param  DestinationAddr  The destination HW MAC address. If this parameter is NULL,
 446                            the HW MAC destination address will not be extracted from the
 447                            media header.
 448   @param  Protocol         The media header type. If this parameter is NULL, then the
 449                            protocol will not be extracted from the media header. See
 450                            RFC 1700 section "Ether Types" for examples.
 451
 452   @retval  EFI_SUCCESS           The received data was stored in Buffer, and BufferSize has
 453                                  been updated to the number of bytes received.
 454   @retval  EFI_NOT_READY         The network interface is too busy to accept this transmit
 455                                  request.
 456   @retval  EFI_BUFFER_TOO_SMALL  The BufferSize parameter is too small.
 457   @retval  EFI_DEVICE_ERROR      The command could not be sent to the network interface.
 458   @retval  EFI_ACCESS_DENIED     Error acquire global lock for operation.
 459
 460 **/
 461 EFI_STATUS
 462 EFIAPI
 463 EmuSnpReceive (
 464   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This,
 465   OUT UINTN                       *HeaderSize OPTIONAL,
 466   IN OUT UINTN                    *BuffSize,
 467   OUT VOID                        *Buffer,
 468   OUT EFI_MAC_ADDRESS             *SourceAddr OPTIONAL,
 469   OUT EFI_MAC_ADDRESS             *DestinationAddr OPTIONAL,
 470   OUT UINT16                      *Protocol OPTIONAL
 471   );
 472
 473 VOID
 474 EFIAPI
 475 EmuSnpWaitForPacketNotify (
 476   IN EFI_EVENT  Event,
 477   IN VOID       *Private
 478   );
 479
 480 #endif // _EMU_SNP_H_