1 /** @file 2 The EMU_SNP_PROTOCOL provides services to initialize a network interface, 3 transmit packets, receive packets, and close a network interface. 4 5 6 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> 7 Portitions copyright (c) 2011, Apple Inc. All rights reserved. 8 This program and the accompanying materials are licensed and made available under 9 the terms and conditions of the BSD License that accompanies this distribution. 10 The full text of the license may be found at 11 http://opensource.org/licenses/bsd-license.php. 12 13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 15 16 **/ 17 18 #ifndef __EMU_SNP_H__ 19 #define __EMU_SNP_H__ 20 21 #include <Protocol/SimpleNetwork.h> 22 23 #define EMU_SNP_PROTOCOL_GUID \ 24 { 0xFD5FBE54, 0x8C35, 0xB345, { 0x8A, 0x0F, 0x7A, 0xC8, 0xA5, 0xFD, 0x05, 0x21 } } 25 26 typedef struct _EMU_SNP_PROTOCOL EMU_SNP_PROTOCOL; 27 28 29 /** 30 Register storage for SNP Mode. 31 32 @param This Protocol instance pointer. 33 @param Mode SimpleNetworkProtocol Mode structure passed into driver. 34 35 @retval EFI_SUCCESS The network interface was started. 36 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 37 38 **/ 39 typedef 40 EFI_STATUS 41 (EFIAPI *EMU_SNP_CREATE_MAPPING)( 42 IN EMU_SNP_PROTOCOL *This, 43 IN EFI_SIMPLE_NETWORK_MODE *Mode 44 ); 45 46 47 /** 48 Changes the state of a network interface from "stopped" to "started". 49 50 @param This Protocol instance pointer. 51 52 @retval EFI_SUCCESS The network interface was started. 53 @retval EFI_ALREADY_STARTED The network interface is already in the started state. 54 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 55 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 56 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 57 58 **/ 59 typedef 60 EFI_STATUS 61 (EFIAPI *EMU_SNP_START)( 62 IN EMU_SNP_PROTOCOL *This 63 ); 64 65 /** 66 Changes the state of a network interface from "started" to "stopped". 67 68 @param This Protocol instance pointer. 69 70 @retval EFI_SUCCESS The network interface was stopped. 71 @retval EFI_ALREADY_STARTED The network interface is already in the stopped state. 72 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 73 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 74 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 75 76 **/ 77 typedef 78 EFI_STATUS 79 (EFIAPI *EMU_SNP_STOP)( 80 IN EMU_SNP_PROTOCOL *This 81 ); 82 83 /** 84 Resets a network adapter and allocates the transmit and receive buffers 85 required by the network interface; optionally, also requests allocation 86 of additional transmit and receive buffers. 87 88 @param This The protocol instance pointer. 89 @param ExtraRxBufferSize The size, in bytes, of the extra receive buffer space 90 that the driver should allocate for the network interface. 91 Some network interfaces will not be able to use the extra 92 buffer, and the caller will not know if it is actually 93 being used. 94 @param ExtraTxBufferSize The size, in bytes, of the extra transmit buffer space 95 that the driver should allocate for the network interface. 96 Some network interfaces will not be able to use the extra 97 buffer, and the caller will not know if it is actually 98 being used. 99 100 @retval EFI_SUCCESS The network interface was initialized. 101 @retval EFI_NOT_STARTED The network interface has not been started. 102 @retval EFI_OUT_OF_RESOURCES There was not enough memory for the transmit and 103 receive buffers. 104 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 105 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 106 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 107 108 **/ 109 typedef 110 EFI_STATUS 111 (EFIAPI *EMU_SNP_INITIALIZE)( 112 IN EMU_SNP_PROTOCOL *This, 113 IN UINTN ExtraRxBufferSize OPTIONAL, 114 IN UINTN ExtraTxBufferSize OPTIONAL 115 ); 116 117 /** 118 Resets a network adapter and re-initializes it with the parameters that were 119 provided in the previous call to Initialize(). 120 121 @param This The protocol instance pointer. 122 @param ExtendedVerification Indicates that the driver may perform a more 123 exhaustive verification operation of the device 124 during reset. 125 126 @retval EFI_SUCCESS The network interface was reset. 127 @retval EFI_NOT_STARTED The network interface has not been started. 128 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 129 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 130 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 131 132 **/ 133 typedef 134 EFI_STATUS 135 (EFIAPI *EMU_SNP_RESET)( 136 IN EMU_SNP_PROTOCOL *This, 137 IN BOOLEAN ExtendedVerification 138 ); 139 140 /** 141 Resets a network adapter and leaves it in a state that is safe for 142 another driver to initialize. 143 144 @param This Protocol instance pointer. 145 146 @retval EFI_SUCCESS The network interface was shutdown. 147 @retval EFI_NOT_STARTED The network interface has not been started. 148 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 149 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 150 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 151 152 **/ 153 typedef 154 EFI_STATUS 155 (EFIAPI *EMU_SNP_SHUTDOWN)( 156 IN EMU_SNP_PROTOCOL *This 157 ); 158 159 /** 160 Manages the multicast receive filters of a network interface. 161 162 @param This The protocol instance pointer. 163 @param Enable A bit mask of receive filters to enable on the network interface. 164 @param Disable A bit mask of receive filters to disable on the network interface. 165 @param ResetMCastFilter Set to TRUE to reset the contents of the multicast receive 166 filters on the network interface to their default values. 167 @param McastFilterCnt Number of multicast HW MAC addresses in the new 168 MCastFilter list. This value must be less than or equal to 169 the MCastFilterCnt field of EMU_SNP_MODE. This 170 field is optional if ResetMCastFilter is TRUE. 171 @param MCastFilter A pointer to a list of new multicast receive filter HW MAC 172 addresses. This list will replace any existing multicast 173 HW MAC address list. This field is optional if 174 ResetMCastFilter is TRUE. 175 176 @retval EFI_SUCCESS The multicast receive filter list was updated. 177 @retval EFI_NOT_STARTED The network interface has not been started. 178 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 179 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 180 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 181 182 **/ 183 typedef 184 EFI_STATUS 185 (EFIAPI *EMU_SNP_RECEIVE_FILTERS)( 186 IN EMU_SNP_PROTOCOL *This, 187 IN UINT32 Enable, 188 IN UINT32 Disable, 189 IN BOOLEAN ResetMCastFilter, 190 IN UINTN MCastFilterCnt OPTIONAL, 191 IN EFI_MAC_ADDRESS *MCastFilter OPTIONAL 192 ); 193 194 /** 195 Modifies or resets the current station address, if supported. 196 197 @param This The protocol instance pointer. 198 @param Reset Flag used to reset the station address to the network interfaces 199 permanent address. 200 @param New The new station address to be used for the network interface. 201 202 @retval EFI_SUCCESS The network interfaces station address was updated. 203 @retval EFI_NOT_STARTED The network interface has not been started. 204 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 205 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 206 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 207 208 **/ 209 typedef 210 EFI_STATUS 211 (EFIAPI *EMU_SNP_STATION_ADDRESS)( 212 IN EMU_SNP_PROTOCOL *This, 213 IN BOOLEAN Reset, 214 IN EFI_MAC_ADDRESS *New OPTIONAL 215 ); 216 217 /** 218 Resets or collects the statistics on a network interface. 219 220 @param This Protocol instance pointer. 221 @param Reset Set to TRUE to reset the statistics for the network interface. 222 @param StatisticsSize On input the size, in bytes, of StatisticsTable. On 223 output the size, in bytes, of the resulting table of 224 statistics. 225 @param StatisticsTable A pointer to the EFI_NETWORK_STATISTICS structure that 226 contains the statistics. 227 228 @retval EFI_SUCCESS The statistics were collected from the network interface. 229 @retval EFI_NOT_STARTED The network interface has not been started. 230 @retval EFI_BUFFER_TOO_SMALL The Statistics buffer was too small. The current buffer 231 size needed to hold the statistics is returned in 232 StatisticsSize. 233 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 234 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 235 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 236 237 **/ 238 typedef 239 EFI_STATUS 240 (EFIAPI *EMU_SNP_STATISTICS)( 241 IN EMU_SNP_PROTOCOL *This, 242 IN BOOLEAN Reset, 243 IN OUT UINTN *StatisticsSize OPTIONAL, 244 OUT EFI_NETWORK_STATISTICS *StatisticsTable OPTIONAL 245 ); 246 247 /** 248 Converts a multicast IP address to a multicast HW MAC address. 249 250 @param This The protocol instance pointer. 251 @param IPv6 Set to TRUE if the multicast IP address is IPv6 [RFC 2460]. Set 252 to FALSE if the multicast IP address is IPv4 [RFC 791]. 253 @param IP The multicast IP address that is to be converted to a multicast 254 HW MAC address. 255 @param MAC The multicast HW MAC address that is to be generated from IP. 256 257 @retval EFI_SUCCESS The multicast IP address was mapped to the multicast 258 HW MAC address. 259 @retval EFI_NOT_STARTED The network interface has not been started. 260 @retval EFI_BUFFER_TOO_SMALL The Statistics buffer was too small. The current buffer 261 size needed to hold the statistics is returned in 262 StatisticsSize. 263 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 264 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 265 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 266 267 **/ 268 typedef 269 EFI_STATUS 270 (EFIAPI *EMU_SNP_MCAST_IP_TO_MAC)( 271 IN EMU_SNP_PROTOCOL *This, 272 IN BOOLEAN IPv6, 273 IN EFI_IP_ADDRESS *IP, 274 OUT EFI_MAC_ADDRESS *MAC 275 ); 276 277 /** 278 Performs read and write operations on the NVRAM device attached to a 279 network interface. 280 281 @param This The protocol instance pointer. 282 @param ReadWrite TRUE for read operations, FALSE for write operations. 283 @param Offset Byte offset in the NVRAM device at which to start the read or 284 write operation. This must be a multiple of NvRamAccessSize and 285 less than NvRamSize. 286 @param BufferSize The number of bytes to read or write from the NVRAM device. 287 This must also be a multiple of NvramAccessSize. 288 @param Buffer A pointer to the data buffer. 289 290 @retval EFI_SUCCESS The NVRAM access was performed. 291 @retval EFI_NOT_STARTED The network interface has not been started. 292 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 293 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 294 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 295 296 **/ 297 typedef 298 EFI_STATUS 299 (EFIAPI *EMU_SNP_NVDATA)( 300 IN EMU_SNP_PROTOCOL *This, 301 IN BOOLEAN ReadWrite, 302 IN UINTN Offset, 303 IN UINTN BufferSize, 304 IN OUT VOID *Buffer 305 ); 306 307 /** 308 Reads the current interrupt status and recycled transmit buffer status from 309 a network interface. 310 311 @param This The protocol instance pointer. 312 @param InterruptStatus A pointer to the bit mask of the currently active interrupts 313 If this is NULL, the interrupt status will not be read from 314 the device. If this is not NULL, the interrupt status will 315 be read from the device. When the interrupt status is read, 316 it will also be cleared. Clearing the transmit interrupt 317 does not empty the recycled transmit buffer array. 318 @param TxBuf Recycled transmit buffer address. The network interface will 319 not transmit if its internal recycled transmit buffer array 320 is full. Reading the transmit buffer does not clear the 321 transmit interrupt. If this is NULL, then the transmit buffer 322 status will not be read. If there are no transmit buffers to 323 recycle and TxBuf is not NULL, * TxBuf will be set to NULL. 324 325 @retval EFI_SUCCESS The status of the network interface was retrieved. 326 @retval EFI_NOT_STARTED The network interface has not been started. 327 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 328 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 329 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 330 331 **/ 332 typedef 333 EFI_STATUS 334 (EFIAPI *EMU_SNP_GET_STATUS)( 335 IN EMU_SNP_PROTOCOL *This, 336 OUT UINT32 *InterruptStatus OPTIONAL, 337 OUT VOID **TxBuf OPTIONAL 338 ); 339 340 /** 341 Places a packet in the transmit queue of a network interface. 342 343 @param This The protocol instance pointer. 344 @param HeaderSize The size, in bytes, of the media header to be filled in by 345 the Transmit() function. If HeaderSize is non-zero, then it 346 must be equal to This->Mode->MediaHeaderSize and the DestAddr 347 and Protocol parameters must not be NULL. 348 @param BufferSize The size, in bytes, of the entire packet (media header and 349 data) to be transmitted through the network interface. 350 @param Buffer A pointer to the packet (media header followed by data) to be 351 transmitted. This parameter cannot be NULL. If HeaderSize is zero, 352 then the media header in Buffer must already be filled in by the 353 caller. If HeaderSize is non-zero, then the media header will be 354 filled in by the Transmit() function. 355 @param SrcAddr The source HW MAC address. If HeaderSize is zero, then this parameter 356 is ignored. If HeaderSize is non-zero and SrcAddr is NULL, then 357 This->Mode->CurrentAddress is used for the source HW MAC address. 358 @param DestAddr The destination HW MAC address. If HeaderSize is zero, then this 359 parameter is ignored. 360 @param Protocol The type of header to build. If HeaderSize is zero, then this 361 parameter is ignored. See RFC 1700, section "Ether Types", for 362 examples. 363 364 @retval EFI_SUCCESS The packet was placed on the transmit queue. 365 @retval EFI_NOT_STARTED The network interface has not been started. 366 @retval EFI_NOT_READY The network interface is too busy to accept this transmit request. 367 @retval EFI_BUFFER_TOO_SMALL The BufferSize parameter is too small. 368 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 369 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 370 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 371 372 **/ 373 typedef 374 EFI_STATUS 375 (EFIAPI *EMU_SNP_TRANSMIT)( 376 IN EMU_SNP_PROTOCOL *This, 377 IN UINTN HeaderSize, 378 IN UINTN BufferSize, 379 IN VOID *Buffer, 380 IN EFI_MAC_ADDRESS *SrcAddr OPTIONAL, 381 IN EFI_MAC_ADDRESS *DestAddr OPTIONAL, 382 IN UINT16 *Protocol OPTIONAL 383 ); 384 385 /** 386 Receives a packet from a network interface. 387 388 @param This The protocol instance pointer. 389 @param HeaderSize The size, in bytes, of the media header received on the network 390 interface. If this parameter is NULL, then the media header size 391 will not be returned. 392 @param BufferSize On entry, the size, in bytes, of Buffer. On exit, the size, in 393 bytes, of the packet that was received on the network interface. 394 @param Buffer A pointer to the data buffer to receive both the media header and 395 the data. 396 @param SrcAddr The source HW MAC address. If this parameter is NULL, the 397 HW MAC source address will not be extracted from the media 398 header. 399 @param DestAddr The destination HW MAC address. If this parameter is NULL, 400 the HW MAC destination address will not be extracted from the 401 media header. 402 @param Protocol The media header type. If this parameter is NULL, then the 403 protocol will not be extracted from the media header. See 404 RFC 1700 section "Ether Types" for examples. 405 406 @retval EFI_SUCCESS The received data was stored in Buffer, and BufferSize has 407 been updated to the number of bytes received. 408 @retval EFI_NOT_STARTED The network interface has not been started. 409 @retval EFI_NOT_READY The network interface is too busy to accept this transmit 410 request. 411 @retval EFI_BUFFER_TOO_SMALL The BufferSize parameter is too small. 412 @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. 413 @retval EFI_DEVICE_ERROR The command could not be sent to the network interface. 414 @retval EFI_UNSUPPORTED This function is not supported by the network interface. 415 416 **/ 417 typedef 418 EFI_STATUS 419 (EFIAPI *EMU_SNP_RECEIVE)( 420 IN EMU_SNP_PROTOCOL *This, 421 OUT UINTN *HeaderSize OPTIONAL, 422 IN OUT UINTN *BufferSize, 423 OUT VOID *Buffer, 424 OUT EFI_MAC_ADDRESS *SrcAddr OPTIONAL, 425 OUT EFI_MAC_ADDRESS *DestAddr OPTIONAL, 426 OUT UINT16 *Protocol OPTIONAL 427 ); 428 429 #define EMU_SNP_PROTOCOL_REVISION 0x00010000 430 431 // 432 // Revision defined in EFI1.1 433 // 434 #define EMU_SNP_INTERFACE_REVISION EMU_SNP_PROTOCOL_REVISION 435 436 /// 437 /// The EMU_SNP_PROTOCOL protocol abstracts OS network sercices 438 /// from the EFI driver that produces EFI Simple Network Protocol. 439 /// 440 struct _EMU_SNP_PROTOCOL { 441 EMU_SNP_CREATE_MAPPING CreateMapping; 442 EMU_SNP_START Start; 443 EMU_SNP_STOP Stop; 444 EMU_SNP_INITIALIZE Initialize; 445 EMU_SNP_RESET Reset; 446 EMU_SNP_SHUTDOWN Shutdown; 447 EMU_SNP_RECEIVE_FILTERS ReceiveFilters; 448 EMU_SNP_STATION_ADDRESS StationAddress; 449 EMU_SNP_STATISTICS Statistics; 450 EMU_SNP_MCAST_IP_TO_MAC MCastIpToMac; 451 EMU_SNP_NVDATA NvData; 452 EMU_SNP_GET_STATUS GetStatus; 453 EMU_SNP_TRANSMIT Transmit; 454 EMU_SNP_RECEIVE Receive; 455 }; 456 457 extern EFI_GUID gEmuSnpProtocolGuid; 458 459 #endif 460