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