iPXE
SimpleNetwork.h
Go to the documentation of this file.
00001 /** @file
00002   The EFI_SIMPLE_NETWORK_PROTOCOL provides services to initialize a network interface,
00003   transmit packets, receive packets, and close a network interface.
00004 
00005   Basic network device abstraction.
00006 
00007   Rx    - Received
00008   Tx    - Transmit
00009   MCast - MultiCast
00010   ...
00011 
00012 Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>
00013 This program and the accompanying materials are licensed and made available under
00014 the terms and conditions of the BSD License that accompanies this distribution.
00015 The full text of the license may be found at
00016 http://opensource.org/licenses/bsd-license.php.
00017 
00018 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00019 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00020 
00021   @par Revision Reference:
00022   This Protocol is introduced in EFI Specification 1.10.
00023 
00024 **/
00025 
00026 #ifndef __SIMPLE_NETWORK_H__
00027 #define __SIMPLE_NETWORK_H__
00028 
00029 FILE_LICENCE ( BSD3 );
00030 
00031 #define EFI_SIMPLE_NETWORK_PROTOCOL_GUID \
00032   { \
00033     0xA19832B9, 0xAC25, 0x11D3, {0x9A, 0x2D, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D } \
00034   }
00035 
00036 typedef struct _EFI_SIMPLE_NETWORK_PROTOCOL  EFI_SIMPLE_NETWORK_PROTOCOL;
00037 
00038 
00039 ///
00040 /// Protocol defined in EFI1.1.
00041 ///
00042 typedef EFI_SIMPLE_NETWORK_PROTOCOL   EFI_SIMPLE_NETWORK;
00043 
00044 ///
00045 /// Simple Network Protocol data structures.
00046 ///
00047 typedef struct {
00048   ///
00049   /// Total number of frames received.  Includes frames with errors and
00050   /// dropped frames.
00051   ///
00052   UINT64  RxTotalFrames;
00053 
00054   ///
00055   /// Number of valid frames received and copied into receive buffers.
00056   ///
00057   UINT64  RxGoodFrames;
00058 
00059   ///
00060   /// Number of frames below the minimum length for the media.
00061   /// This would be <64 for ethernet.
00062   ///
00063   UINT64  RxUndersizeFrames;
00064 
00065   ///
00066   /// Number of frames longer than the maxminum length for the
00067   /// media.  This would be >1500 for ethernet.
00068   ///
00069   UINT64  RxOversizeFrames;
00070 
00071   ///
00072   /// Valid frames that were dropped because receive buffers were full.
00073   ///
00074   UINT64  RxDroppedFrames;
00075 
00076   ///
00077   /// Number of valid unicast frames received and not dropped.
00078   ///
00079   UINT64  RxUnicastFrames;
00080 
00081   ///
00082   /// Number of valid broadcast frames received and not dropped.
00083   ///
00084   UINT64  RxBroadcastFrames;
00085 
00086   ///
00087   /// Number of valid mutlicast frames received and not dropped.
00088   ///
00089   UINT64  RxMulticastFrames;
00090 
00091   ///
00092   /// Number of frames w/ CRC or alignment errors.
00093   ///
00094   UINT64  RxCrcErrorFrames;
00095 
00096   ///
00097   /// Total number of bytes received.  Includes frames with errors
00098   /// and dropped frames.
00099   //
00100   UINT64  RxTotalBytes;
00101 
00102   ///
00103   /// Transmit statistics.
00104   ///
00105   UINT64  TxTotalFrames;
00106   UINT64  TxGoodFrames;
00107   UINT64  TxUndersizeFrames;
00108   UINT64  TxOversizeFrames;
00109   UINT64  TxDroppedFrames;
00110   UINT64  TxUnicastFrames;
00111   UINT64  TxBroadcastFrames;
00112   UINT64  TxMulticastFrames;
00113   UINT64  TxCrcErrorFrames;
00114   UINT64  TxTotalBytes;
00115 
00116   ///
00117   /// Number of collisions detection on this subnet.
00118   ///
00119   UINT64  Collisions;
00120 
00121   ///
00122   /// Number of frames destined for unsupported protocol.
00123   ///
00124   UINT64  UnsupportedProtocol;
00125 
00126   ///
00127   /// Number of valid frames received that were duplicated.
00128   ///
00129   UINT64  RxDuplicatedFrames;
00130 
00131   ///
00132   /// Number of encrypted frames received that failed to decrypt.
00133   ///
00134   UINT64  RxDecryptErrorFrames;
00135 
00136   ///
00137   /// Number of frames that failed to transmit after exceeding the retry limit.
00138   ///
00139   UINT64  TxErrorFrames;
00140 
00141   ///
00142   /// Number of frames transmitted successfully after more than one attempt.
00143   ///
00144   UINT64  TxRetryFrames;
00145 } EFI_NETWORK_STATISTICS;
00146 
00147 ///
00148 /// The state of the network interface.
00149 /// When an EFI_SIMPLE_NETWORK_PROTOCOL driver initializes a
00150 /// network interface, the network interface is left in the EfiSimpleNetworkStopped state.
00151 ///
00152 typedef enum {
00153   EfiSimpleNetworkStopped,
00154   EfiSimpleNetworkStarted,
00155   EfiSimpleNetworkInitialized,
00156   EfiSimpleNetworkMaxState
00157 } EFI_SIMPLE_NETWORK_STATE;
00158 
00159 #define EFI_SIMPLE_NETWORK_RECEIVE_UNICAST                0x01
00160 #define EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST              0x02
00161 #define EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST              0x04
00162 #define EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS            0x08
00163 #define EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST  0x10
00164 
00165 #define EFI_SIMPLE_NETWORK_RECEIVE_INTERRUPT              0x01
00166 #define EFI_SIMPLE_NETWORK_TRANSMIT_INTERRUPT             0x02
00167 #define EFI_SIMPLE_NETWORK_COMMAND_INTERRUPT              0x04
00168 #define EFI_SIMPLE_NETWORK_SOFTWARE_INTERRUPT             0x08
00169 
00170 #define MAX_MCAST_FILTER_CNT                              16
00171 typedef struct {
00172   ///
00173   /// Reports the current state of the network interface.
00174   ///
00175   UINT32          State;
00176   ///
00177   /// The size, in bytes, of the network interface's HW address.
00178   ///
00179   UINT32          HwAddressSize;
00180   ///
00181   /// The size, in bytes, of the network interface's media header.
00182   ///
00183   UINT32          MediaHeaderSize;
00184   ///
00185   /// The maximum size, in bytes, of the packets supported by the network interface.
00186   ///
00187   UINT32          MaxPacketSize;
00188   ///
00189   /// The size, in bytes, of the NVRAM device attached to the network interface.
00190   ///
00191   UINT32          NvRamSize;
00192   ///
00193   /// The size that must be used for all NVRAM reads and writes. The
00194   /// start address for NVRAM read and write operations and the total
00195   /// length of those operations, must be a multiple of this value. The
00196   /// legal values for this field are 0, 1, 2, 4, and 8.
00197   ///
00198   UINT32          NvRamAccessSize;
00199   ///
00200   /// The multicast receive filter settings supported by the network interface.
00201   ///
00202   UINT32          ReceiveFilterMask;
00203   ///
00204   /// The current multicast receive filter settings.
00205   ///
00206   UINT32          ReceiveFilterSetting;
00207   ///
00208   /// The maximum number of multicast address receive filters supported by the driver.
00209   ///
00210   UINT32          MaxMCastFilterCount;
00211   ///
00212   /// The current number of multicast address receive filters.
00213   ///
00214   UINT32          MCastFilterCount;
00215   ///
00216   /// Array containing the addresses of the current multicast address receive filters.
00217   ///
00218   EFI_MAC_ADDRESS MCastFilter[MAX_MCAST_FILTER_CNT];
00219   ///
00220   /// The current HW MAC address for the network interface.
00221   ///
00222   EFI_MAC_ADDRESS CurrentAddress;
00223   ///
00224   /// The current HW MAC address for broadcast packets.
00225   ///
00226   EFI_MAC_ADDRESS BroadcastAddress;
00227   ///
00228   /// The permanent HW MAC address for the network interface.
00229   ///
00230   EFI_MAC_ADDRESS PermanentAddress;
00231   ///
00232   /// The interface type of the network interface.
00233   ///
00234   UINT8           IfType;
00235   ///
00236   /// TRUE if the HW MAC address can be changed.
00237   ///
00238   BOOLEAN         MacAddressChangeable;
00239   ///
00240   /// TRUE if the network interface can transmit more than one packet at a time.
00241   ///
00242   BOOLEAN         MultipleTxSupported;
00243   ///
00244   /// TRUE if the presence of media can be determined; otherwise FALSE.
00245   ///
00246   BOOLEAN         MediaPresentSupported;
00247   ///
00248   /// TRUE if media are connected to the network interface; otherwise FALSE.
00249   ///
00250   BOOLEAN         MediaPresent;
00251 } EFI_SIMPLE_NETWORK_MODE;
00252 
00253 //
00254 // Protocol Member Functions
00255 //
00256 /**
00257   Changes the state of a network interface from "stopped" to "started".
00258 
00259   @param  This Protocol instance pointer.
00260 
00261   @retval EFI_SUCCESS           The network interface was started.
00262   @retval EFI_ALREADY_STARTED   The network interface is already in the started state.
00263   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00264   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00265   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00266 
00267 **/
00268 typedef
00269 EFI_STATUS
00270 (EFIAPI *EFI_SIMPLE_NETWORK_START)(
00271   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This
00272   );
00273 
00274 /**
00275   Changes the state of a network interface from "started" to "stopped".
00276 
00277   @param  This Protocol instance pointer.
00278 
00279   @retval EFI_SUCCESS           The network interface was stopped.
00280   @retval EFI_ALREADY_STARTED   The network interface is already in the stopped state.
00281   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00282   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00283   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00284 
00285 **/
00286 typedef
00287 EFI_STATUS
00288 (EFIAPI *EFI_SIMPLE_NETWORK_STOP)(
00289   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This
00290   );
00291 
00292 /**
00293   Resets a network adapter and allocates the transmit and receive buffers
00294   required by the network interface; optionally, also requests allocation
00295   of additional transmit and receive buffers.
00296 
00297   @param  This              The protocol instance pointer.
00298   @param  ExtraRxBufferSize The size, in bytes, of the extra receive buffer space
00299                             that the driver should allocate for the network interface.
00300                             Some network interfaces will not be able to use the extra
00301                             buffer, and the caller will not know if it is actually
00302                             being used.
00303   @param  ExtraTxBufferSize The size, in bytes, of the extra transmit buffer space
00304                             that the driver should allocate for the network interface.
00305                             Some network interfaces will not be able to use the extra
00306                             buffer, and the caller will not know if it is actually
00307                             being used.
00308 
00309   @retval EFI_SUCCESS           The network interface was initialized.
00310   @retval EFI_NOT_STARTED       The network interface has not been started.
00311   @retval EFI_OUT_OF_RESOURCES  There was not enough memory for the transmit and
00312                                 receive buffers.
00313   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00314   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00315   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00316 
00317 **/
00318 typedef
00319 EFI_STATUS
00320 (EFIAPI *EFI_SIMPLE_NETWORK_INITIALIZE)(
00321   IN EFI_SIMPLE_NETWORK_PROTOCOL                    *This,
00322   IN UINTN                                          ExtraRxBufferSize  OPTIONAL,
00323   IN UINTN                                          ExtraTxBufferSize  OPTIONAL
00324   );
00325 
00326 /**
00327   Resets a network adapter and re-initializes it with the parameters that were
00328   provided in the previous call to Initialize().
00329 
00330   @param  This                 The protocol instance pointer.
00331   @param  ExtendedVerification Indicates that the driver may perform a more
00332                                exhaustive verification operation of the device
00333                                during reset.
00334 
00335   @retval EFI_SUCCESS           The network interface was reset.
00336   @retval EFI_NOT_STARTED       The network interface has not been started.
00337   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00338   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00339   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00340 
00341 **/
00342 typedef
00343 EFI_STATUS
00344 (EFIAPI *EFI_SIMPLE_NETWORK_RESET)(
00345   IN EFI_SIMPLE_NETWORK_PROTOCOL   *This,
00346   IN BOOLEAN                       ExtendedVerification
00347   );
00348 
00349 /**
00350   Resets a network adapter and leaves it in a state that is safe for
00351   another driver to initialize.
00352 
00353   @param  This Protocol instance pointer.
00354 
00355   @retval EFI_SUCCESS           The network interface was shutdown.
00356   @retval EFI_NOT_STARTED       The network interface has not been started.
00357   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00358   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00359   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00360 
00361 **/
00362 typedef
00363 EFI_STATUS
00364 (EFIAPI *EFI_SIMPLE_NETWORK_SHUTDOWN)(
00365   IN EFI_SIMPLE_NETWORK_PROTOCOL  *This
00366   );
00367 
00368 /**
00369   Manages the multicast receive filters of a network interface.
00370 
00371   @param  This             The protocol instance pointer.
00372   @param  Enable           A bit mask of receive filters to enable on the network interface.
00373   @param  Disable          A bit mask of receive filters to disable on the network interface.
00374   @param  ResetMCastFilter Set to TRUE to reset the contents of the multicast receive
00375                            filters on the network interface to their default values.
00376   @param  McastFilterCnt   Number of multicast HW MAC addresses in the new
00377                            MCastFilter list. This value must be less than or equal to
00378                            the MCastFilterCnt field of EFI_SIMPLE_NETWORK_MODE. This
00379                            field is optional if ResetMCastFilter is TRUE.
00380   @param  MCastFilter      A pointer to a list of new multicast receive filter HW MAC
00381                            addresses. This list will replace any existing multicast
00382                            HW MAC address list. This field is optional if
00383                            ResetMCastFilter is TRUE.
00384 
00385   @retval EFI_SUCCESS           The multicast receive filter list was updated.
00386   @retval EFI_NOT_STARTED       The network interface has not been started.
00387   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00388   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00389   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00390 
00391 **/
00392 typedef
00393 EFI_STATUS
00394 (EFIAPI *EFI_SIMPLE_NETWORK_RECEIVE_FILTERS)(
00395   IN EFI_SIMPLE_NETWORK_PROTOCOL                             *This,
00396   IN UINT32                                                  Enable,
00397   IN UINT32                                                  Disable,
00398   IN BOOLEAN                                                 ResetMCastFilter,
00399   IN UINTN                                                   MCastFilterCnt     OPTIONAL,
00400   IN EFI_MAC_ADDRESS                                         *MCastFilter OPTIONAL
00401   );
00402 
00403 /**
00404   Modifies or resets the current station address, if supported.
00405 
00406   @param  This  The protocol instance pointer.
00407   @param  Reset Flag used to reset the station address to the network interfaces
00408                 permanent address.
00409   @param  New   The new station address to be used for the network interface.
00410 
00411   @retval EFI_SUCCESS           The network interfaces station address was updated.
00412   @retval EFI_NOT_STARTED       The network interface has not been started.
00413   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00414   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00415   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00416 
00417 **/
00418 typedef
00419 EFI_STATUS
00420 (EFIAPI *EFI_SIMPLE_NETWORK_STATION_ADDRESS)(
00421   IN EFI_SIMPLE_NETWORK_PROTOCOL            *This,
00422   IN BOOLEAN                                Reset,
00423   IN EFI_MAC_ADDRESS                        *New OPTIONAL
00424   );
00425 
00426 /**
00427   Resets or collects the statistics on a network interface.
00428 
00429   @param  This            Protocol instance pointer.
00430   @param  Reset           Set to TRUE to reset the statistics for the network interface.
00431   @param  StatisticsSize  On input the size, in bytes, of StatisticsTable. On
00432                           output the size, in bytes, of the resulting table of
00433                           statistics.
00434   @param  StatisticsTable A pointer to the EFI_NETWORK_STATISTICS structure that
00435                           contains the statistics.
00436 
00437   @retval EFI_SUCCESS           The statistics were collected from the network interface.
00438   @retval EFI_NOT_STARTED       The network interface has not been started.
00439   @retval EFI_BUFFER_TOO_SMALL  The Statistics buffer was too small. The current buffer
00440                                 size needed to hold the statistics is returned in
00441                                 StatisticsSize.
00442   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00443   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00444   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00445 
00446 **/
00447 typedef
00448 EFI_STATUS
00449 (EFIAPI *EFI_SIMPLE_NETWORK_STATISTICS)(
00450   IN EFI_SIMPLE_NETWORK_PROTOCOL          *This,
00451   IN BOOLEAN                              Reset,
00452   IN OUT UINTN                            *StatisticsSize   OPTIONAL,
00453   OUT EFI_NETWORK_STATISTICS              *StatisticsTable  OPTIONAL
00454   );
00455 
00456 /**
00457   Converts a multicast IP address to a multicast HW MAC address.
00458 
00459   @param  This The protocol instance pointer.
00460   @param  IPv6 Set to TRUE if the multicast IP address is IPv6 [RFC 2460]. Set
00461                to FALSE if the multicast IP address is IPv4 [RFC 791].
00462   @param  IP   The multicast IP address that is to be converted to a multicast
00463                HW MAC address.
00464   @param  MAC  The multicast HW MAC address that is to be generated from IP.
00465 
00466   @retval EFI_SUCCESS           The multicast IP address was mapped to the multicast
00467                                 HW MAC address.
00468   @retval EFI_NOT_STARTED       The network interface has not been started.
00469   @retval EFI_BUFFER_TOO_SMALL  The Statistics buffer was too small. The current buffer
00470                                 size needed to hold the statistics is returned in
00471                                 StatisticsSize.
00472   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00473   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00474   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00475 
00476 **/
00477 typedef
00478 EFI_STATUS
00479 (EFIAPI *EFI_SIMPLE_NETWORK_MCAST_IP_TO_MAC)(
00480   IN EFI_SIMPLE_NETWORK_PROTOCOL          *This,
00481   IN BOOLEAN                              IPv6,
00482   IN EFI_IP_ADDRESS                       *IP,
00483   OUT EFI_MAC_ADDRESS                     *MAC
00484   );
00485 
00486 /**
00487   Performs read and write operations on the NVRAM device attached to a
00488   network interface.
00489 
00490   @param  This       The protocol instance pointer.
00491   @param  ReadWrite  TRUE for read operations, FALSE for write operations.
00492   @param  Offset     Byte offset in the NVRAM device at which to start the read or
00493                      write operation. This must be a multiple of NvRamAccessSize and
00494                      less than NvRamSize.
00495   @param  BufferSize The number of bytes to read or write from the NVRAM device.
00496                      This must also be a multiple of NvramAccessSize.
00497   @param  Buffer     A pointer to the data buffer.
00498 
00499   @retval EFI_SUCCESS           The NVRAM access was performed.
00500   @retval EFI_NOT_STARTED       The network interface has not been started.
00501   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00502   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00503   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00504 
00505 **/
00506 typedef
00507 EFI_STATUS
00508 (EFIAPI *EFI_SIMPLE_NETWORK_NVDATA)(
00509   IN EFI_SIMPLE_NETWORK_PROTOCOL          *This,
00510   IN BOOLEAN                              ReadWrite,
00511   IN UINTN                                Offset,
00512   IN UINTN                                BufferSize,
00513   IN OUT VOID                             *Buffer
00514   );
00515 
00516 /**
00517   Reads the current interrupt status and recycled transmit buffer status from
00518   a network interface.
00519 
00520   @param  This            The protocol instance pointer.
00521   @param  InterruptStatus A pointer to the bit mask of the currently active interrupts
00522                           If this is NULL, the interrupt status will not be read from
00523                           the device. If this is not NULL, the interrupt status will
00524                           be read from the device. When the  interrupt status is read,
00525                           it will also be cleared. Clearing the transmit  interrupt
00526                           does not empty the recycled transmit buffer array.
00527   @param  TxBuf           Recycled transmit buffer address. The network interface will
00528                           not transmit if its internal recycled transmit buffer array
00529                           is full. Reading the transmit buffer does not clear the
00530                           transmit interrupt. If this is NULL, then the transmit buffer
00531                           status will not be read. If there are no transmit buffers to
00532                           recycle and TxBuf is not NULL, * TxBuf will be set to NULL.
00533 
00534   @retval EFI_SUCCESS           The status of the network interface was retrieved.
00535   @retval EFI_NOT_STARTED       The network interface has not been started.
00536   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00537   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00538   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00539 
00540 **/
00541 typedef
00542 EFI_STATUS
00543 (EFIAPI *EFI_SIMPLE_NETWORK_GET_STATUS)(
00544   IN EFI_SIMPLE_NETWORK_PROTOCOL          *This,
00545   OUT UINT32                              *InterruptStatus OPTIONAL,
00546   OUT VOID                                **TxBuf OPTIONAL
00547   );
00548 
00549 /**
00550   Places a packet in the transmit queue of a network interface.
00551 
00552   @param  This       The protocol instance pointer.
00553   @param  HeaderSize The size, in bytes, of the media header to be filled in by
00554                      the Transmit() function. If HeaderSize is non-zero, then it
00555                      must be equal to This->Mode->MediaHeaderSize and the DestAddr
00556                      and Protocol parameters must not be NULL.
00557   @param  BufferSize The size, in bytes, of the entire packet (media header and
00558                      data) to be transmitted through the network interface.
00559   @param  Buffer     A pointer to the packet (media header followed by data) to be
00560                      transmitted. This parameter cannot be NULL. If HeaderSize is zero,
00561                      then the media header in Buffer must already be filled in by the
00562                      caller. If HeaderSize is non-zero, then the media header will be
00563                      filled in by the Transmit() function.
00564   @param  SrcAddr    The source HW MAC address. If HeaderSize is zero, then this parameter
00565                      is ignored. If HeaderSize is non-zero and SrcAddr is NULL, then
00566                      This->Mode->CurrentAddress is used for the source HW MAC address.
00567   @param  DestAddr   The destination HW MAC address. If HeaderSize is zero, then this
00568                      parameter is ignored.
00569   @param  Protocol   The type of header to build. If HeaderSize is zero, then this
00570                      parameter is ignored. See RFC 1700, section "Ether Types", for
00571                      examples.
00572 
00573   @retval EFI_SUCCESS           The packet was placed on the transmit queue.
00574   @retval EFI_NOT_STARTED       The network interface has not been started.
00575   @retval EFI_NOT_READY         The network interface is too busy to accept this transmit request.
00576   @retval EFI_BUFFER_TOO_SMALL  The BufferSize parameter is too small.
00577   @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00578   @retval EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00579   @retval EFI_UNSUPPORTED       This function is not supported by the network interface.
00580 
00581 **/
00582 typedef
00583 EFI_STATUS
00584 (EFIAPI *EFI_SIMPLE_NETWORK_TRANSMIT)(
00585   IN EFI_SIMPLE_NETWORK_PROTOCOL          *This,
00586   IN UINTN                                HeaderSize,
00587   IN UINTN                                BufferSize,
00588   IN VOID                                 *Buffer,
00589   IN EFI_MAC_ADDRESS                      *SrcAddr  OPTIONAL,
00590   IN EFI_MAC_ADDRESS                      *DestAddr OPTIONAL,
00591   IN UINT16                               *Protocol OPTIONAL
00592   );
00593 
00594 /**
00595   Receives a packet from a network interface.
00596 
00597   @param  This       The protocol instance pointer.
00598   @param  HeaderSize The size, in bytes, of the media header received on the network
00599                      interface. If this parameter is NULL, then the media header size
00600                      will not be returned.
00601   @param  BufferSize On entry, the size, in bytes, of Buffer. On exit, the size, in
00602                      bytes, of the packet that was received on the network interface.
00603   @param  Buffer     A pointer to the data buffer to receive both the media header and
00604                      the data.
00605   @param  SrcAddr    The source HW MAC address. If this parameter is NULL, the
00606                      HW MAC source address will not be extracted from the media
00607                      header.
00608   @param  DestAddr   The destination HW MAC address. If this parameter is NULL,
00609                      the HW MAC destination address will not be extracted from the
00610                      media header.
00611   @param  Protocol   The media header type. If this parameter is NULL, then the
00612                      protocol will not be extracted from the media header. See
00613                      RFC 1700 section "Ether Types" for examples.
00614 
00615   @retval  EFI_SUCCESS           The received data was stored in Buffer, and BufferSize has
00616                                  been updated to the number of bytes received.
00617   @retval  EFI_NOT_STARTED       The network interface has not been started.
00618   @retval  EFI_NOT_READY         The network interface is too busy to accept this transmit
00619                                  request.
00620   @retval  EFI_BUFFER_TOO_SMALL  The BufferSize parameter is too small.
00621   @retval  EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
00622   @retval  EFI_DEVICE_ERROR      The command could not be sent to the network interface.
00623   @retval  EFI_UNSUPPORTED       This function is not supported by the network interface.
00624 
00625 **/
00626 typedef
00627 EFI_STATUS
00628 (EFIAPI *EFI_SIMPLE_NETWORK_RECEIVE)(
00629   IN EFI_SIMPLE_NETWORK_PROTOCOL          *This,
00630   OUT UINTN                               *HeaderSize OPTIONAL,
00631   IN OUT UINTN                            *BufferSize,
00632   OUT VOID                                *Buffer,
00633   OUT EFI_MAC_ADDRESS                     *SrcAddr    OPTIONAL,
00634   OUT EFI_MAC_ADDRESS                     *DestAddr   OPTIONAL,
00635   OUT UINT16                              *Protocol   OPTIONAL
00636   );
00637 
00638 #define EFI_SIMPLE_NETWORK_PROTOCOL_REVISION  0x00010000
00639 
00640 //
00641 // Revision defined in EFI1.1
00642 //
00643 #define EFI_SIMPLE_NETWORK_INTERFACE_REVISION   EFI_SIMPLE_NETWORK_PROTOCOL_REVISION
00644 
00645 ///
00646 /// The EFI_SIMPLE_NETWORK_PROTOCOL protocol is used to initialize access
00647 /// to a network adapter. Once the network adapter initializes,
00648 /// the EFI_SIMPLE_NETWORK_PROTOCOL protocol provides services that
00649 /// allow packets to be transmitted and received.
00650 ///
00651 struct _EFI_SIMPLE_NETWORK_PROTOCOL {
00652   ///
00653   /// Revision of the EFI_SIMPLE_NETWORK_PROTOCOL. All future revisions must
00654   /// be backwards compatible. If a future version is not backwards compatible
00655   /// it is not the same GUID.
00656   ///
00657   UINT64                              Revision;
00658   EFI_SIMPLE_NETWORK_START            Start;
00659   EFI_SIMPLE_NETWORK_STOP             Stop;
00660   EFI_SIMPLE_NETWORK_INITIALIZE       Initialize;
00661   EFI_SIMPLE_NETWORK_RESET            Reset;
00662   EFI_SIMPLE_NETWORK_SHUTDOWN         Shutdown;
00663   EFI_SIMPLE_NETWORK_RECEIVE_FILTERS  ReceiveFilters;
00664   EFI_SIMPLE_NETWORK_STATION_ADDRESS  StationAddress;
00665   EFI_SIMPLE_NETWORK_STATISTICS       Statistics;
00666   EFI_SIMPLE_NETWORK_MCAST_IP_TO_MAC  MCastIpToMac;
00667   EFI_SIMPLE_NETWORK_NVDATA           NvData;
00668   EFI_SIMPLE_NETWORK_GET_STATUS       GetStatus;
00669   EFI_SIMPLE_NETWORK_TRANSMIT         Transmit;
00670   EFI_SIMPLE_NETWORK_RECEIVE          Receive;
00671   ///
00672   /// Event used with WaitForEvent() to wait for a packet to be received.
00673   ///
00674   EFI_EVENT                           WaitForPacket;
00675   ///
00676   /// Pointer to the EFI_SIMPLE_NETWORK_MODE data for the device.
00677   ///
00678   EFI_SIMPLE_NETWORK_MODE             *Mode;
00679 };
00680 
00681 extern EFI_GUID gEfiSimpleNetworkProtocolGuid;
00682 
00683 #endif