MdePkg/Include/Protocol/Arp.h

   1 /** @file
   2   EFI ARP Protocol Definition
   3
   4   The EFI ARP Service Binding Protocol is used to locate EFI
   5   ARP Protocol drivers to create and destroy child of the
   6   driver to communicate with other host using ARP protocol.
   7   The EFI ARP Protocol provides services to map IP network
   8   address to hardware address used by a data link protocol.
   9
  10 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
  11 SPDX-License-Identifier: BSD-2-Clause-Patent
  12
  13   @par Revision Reference:
  14   This Protocol was introduced in UEFI Specification 2.0.
  15
  16 **/
  17
  18 #ifndef __EFI_ARP_PROTOCOL_H__
  19 #define __EFI_ARP_PROTOCOL_H__
  20
  21 #define EFI_ARP_SERVICE_BINDING_PROTOCOL_GUID \
  22   { \
  23     0xf44c00ee, 0x1f2c, 0x4a00, {0xaa, 0x9, 0x1c, 0x9f, 0x3e, 0x8, 0x0, 0xa3 } \
  24   }
  25
  26 #define EFI_ARP_PROTOCOL_GUID \
  27   { \
  28     0xf4b427bb, 0xba21, 0x4f16, {0xbc, 0x4e, 0x43, 0xe4, 0x16, 0xab, 0x61, 0x9c } \
  29   }
  30
  31 typedef struct _EFI_ARP_PROTOCOL EFI_ARP_PROTOCOL;
  32
  33 typedef struct {
  34   ///
  35   /// Length in bytes of this entry.
  36   ///
  37   UINT32     Size;
  38
  39   ///
  40   /// Set to TRUE if this entry is a "deny" entry.
  41   /// Set to FALSE if this entry is a "normal" entry.
  42   ///
  43   BOOLEAN    DenyFlag;
  44
  45   ///
  46   /// Set to TRUE if this entry will not time out.
  47   /// Set to FALSE if this entry will time out.
  48   ///
  49   BOOLEAN    StaticFlag;
  50
  51   ///
  52   /// 16-bit ARP hardware identifier number.
  53   ///
  54   UINT16     HwAddressType;
  55
  56   ///
  57   /// 16-bit protocol type number.
  58   ///
  59   UINT16     SwAddressType;
  60
  61   ///
  62   /// The length of the hardware address.
  63   ///
  64   UINT8      HwAddressLength;
  65
  66   ///
  67   /// The length of the protocol address.
  68   ///
  69   UINT8      SwAddressLength;
  70 } EFI_ARP_FIND_DATA;
  71
  72 typedef struct {
  73   ///
  74   /// 16-bit protocol type number in host byte order.
  75   ///
  76   UINT16    SwAddressType;
  77
  78   ///
  79   /// The length in bytes of the station's protocol address to register.
  80   ///
  81   UINT8     SwAddressLength;
  82
  83   ///
  84   /// The pointer to the first byte of the protocol address to register. For
  85   /// example, if SwAddressType is 0x0800 (IP), then
  86   /// StationAddress points to the first byte of this station's IP
  87   /// address stored in network byte order.
  88   ///
  89   VOID      *StationAddress;
  90
  91   ///
  92   /// The timeout value in 100-ns units that is associated with each
  93   /// new dynamic ARP cache entry. If it is set to zero, the value is
  94   /// implementation-specific.
  95   ///
  96   UINT32    EntryTimeOut;
  97
  98   ///
  99   /// The number of retries before a MAC address is resolved. If it is
 100   /// set to zero, the value is implementation-specific.
 101   ///
 102   UINT32    RetryCount;
 103
 104   ///
 105   /// The timeout value in 100-ns units that is used to wait for the ARP
 106   /// reply packet or the timeout value between two retries. Set to zero
 107   /// to use implementation-specific value.
 108   ///
 109   UINT32    RetryTimeOut;
 110 } EFI_ARP_CONFIG_DATA;
 111
 112 /**
 113   This function is used to assign a station address to the ARP cache for this instance
 114   of the ARP driver.
 115
 116   Each ARP instance has one station address. The EFI_ARP_PROTOCOL driver will
 117   respond to ARP requests that match this registered station address. A call to
 118   this function with the ConfigData field set to NULL will reset this ARP instance.
 119
 120   Once a protocol type and station address have been assigned to this ARP instance,
 121   all the following ARP functions will use this information. Attempting to change
 122   the protocol type or station address to a configured ARP instance will result in errors.
 123
 124   @param  This                   The pointer to the EFI_ARP_PROTOCOL instance.
 125   @param  ConfigData             The pointer to the EFI_ARP_CONFIG_DATA structure.
 126
 127   @retval EFI_SUCCESS            The new station address was successfully
 128                                  registered.
 129   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 130                                  * This is NULL.
 131                                  * SwAddressLength is zero when ConfigData is not NULL.
 132                                  * StationAddress is NULL when ConfigData is not NULL.
 133   @retval EFI_ACCESS_DENIED      The SwAddressType, SwAddressLength, or
 134                                  StationAddress is different from the one that is
 135                                  already registered.
 136   @retval EFI_OUT_OF_RESOURCES   Storage for the new StationAddress could not be
 137                                  allocated.
 138
 139 **/
 140 typedef
 141 EFI_STATUS
 142 (EFIAPI *EFI_ARP_CONFIGURE)(
 143   IN EFI_ARP_PROTOCOL       *This,
 144   IN EFI_ARP_CONFIG_DATA    *ConfigData   OPTIONAL
 145   );
 146
 147 /**
 148   This function is used to insert entries into the ARP cache.
 149
 150   ARP cache entries are typically inserted and updated by network protocol drivers
 151   as network traffic is processed. Most ARP cache entries will time out and be
 152   deleted if the network traffic stops. ARP cache entries that were inserted
 153   by the Add() function may be static (will not time out) or dynamic (will time out).
 154   Default ARP cache timeout values are not covered in most network protocol
 155   specifications (although RFC 1122 comes pretty close) and will only be
 156   discussed in general terms in this specification. The timeout values that are
 157   used in the EFI Sample Implementation should be used only as a guideline.
 158   Final product implementations of the EFI network stack should be tuned for
 159   their expected network environments.
 160
 161   @param  This                   Pointer to the EFI_ARP_PROTOCOL instance.
 162   @param  DenyFlag               Set to TRUE if this entry is a deny entry. Set to
 163                                  FALSE if this  entry is a normal entry.
 164   @param  TargetSwAddress        Pointer to a protocol address to add (or deny).
 165                                  May be set to NULL if DenyFlag is TRUE.
 166   @param  TargetHwAddress        Pointer to a hardware address to add (or deny).
 167                                  May be set to NULL if DenyFlag is TRUE.
 168   @param  TimeoutValue           Time in 100-ns units that this entry will remain
 169                                  in the ARP cache. A value of zero means that the
 170                                  entry is permanent. A nonzero value will override
 171                                  the one given by Configure() if the entry to be
 172                                  added is a dynamic entry.
 173   @param  Overwrite              If TRUE, the matching cache entry will be
 174                                  overwritten with the supplied parameters. If
 175                                  FALSE, EFI_ACCESS_DENIED is returned if the
 176                                  corresponding cache entry already exists.
 177
 178   @retval EFI_SUCCESS            The entry has been added or updated.
 179   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 180                                  * This is NULL.
 181                                  * DenyFlag is FALSE and TargetHwAddress is NULL.
 182                                  * DenyFlag is FALSE and TargetSwAddress is NULL.
 183                                  * TargetHwAddress is NULL and TargetSwAddress is NULL.
 184                                  * Neither TargetSwAddress nor TargetHwAddress are NULL when DenyFlag is
 185                                  TRUE.
 186   @retval EFI_OUT_OF_RESOURCES   The new ARP cache entry could not be allocated.
 187   @retval EFI_ACCESS_DENIED      The ARP cache entry already exists and Overwrite
 188                                  is not true.
 189   @retval EFI_NOT_STARTED        The ARP driver instance has not been configured.
 190
 191 **/
 192 typedef
 193 EFI_STATUS
 194 (EFIAPI *EFI_ARP_ADD)(
 195   IN EFI_ARP_PROTOCOL       *This,
 196   IN BOOLEAN                DenyFlag,
 197   IN VOID                   *TargetSwAddress  OPTIONAL,
 198   IN VOID                   *TargetHwAddress  OPTIONAL,
 199   IN UINT32                 TimeoutValue,
 200   IN BOOLEAN                Overwrite
 201   );
 202
 203 /**
 204   This function searches the ARP cache for matching entries and allocates a buffer into
 205   which those entries are copied.
 206
 207   The first part of the allocated buffer is EFI_ARP_FIND_DATA, following which
 208   are protocol address pairs and hardware address pairs.
 209   When finding a specific protocol address (BySwAddress is TRUE and AddressBuffer
 210   is not NULL), the ARP cache timeout for the found entry is reset if Refresh is
 211   set to TRUE. If the found ARP cache entry is a permanent entry, it is not
 212   affected by Refresh.
 213
 214   @param  This                   The pointer to the EFI_ARP_PROTOCOL instance.
 215   @param  BySwAddress            Set to TRUE to look for matching software protocol
 216                                  addresses. Set to FALSE to look for matching
 217                                  hardware protocol addresses.
 218   @param  AddressBuffer          The pointer to the address buffer. Set to NULL
 219                                  to match all addresses.
 220   @param  EntryLength            The size of an entry in the entries buffer.
 221   @param  EntryCount             The number of ARP cache entries that are found by
 222                                  the specified criteria.
 223   @param  Entries                The pointer to the buffer that will receive the ARP
 224                                  cache entries.
 225   @param  Refresh                Set to TRUE to refresh the timeout value of the
 226                                  matching ARP cache entry.
 227
 228   @retval EFI_SUCCESS            The requested ARP cache entries were copied into
 229                                  the buffer.
 230   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 231                                  This is NULL. Both EntryCount and EntryLength are
 232                                  NULL, when Refresh is FALSE.
 233   @retval EFI_NOT_FOUND          No matching entries were found.
 234   @retval EFI_NOT_STARTED        The ARP driver instance has not been configured.
 235
 236 **/
 237 typedef
 238 EFI_STATUS
 239 (EFIAPI *EFI_ARP_FIND)(
 240   IN EFI_ARP_PROTOCOL       *This,
 241   IN BOOLEAN                BySwAddress,
 242   IN VOID                   *AddressBuffer    OPTIONAL,
 243   OUT UINT32                *EntryLength      OPTIONAL,
 244   OUT UINT32                *EntryCount       OPTIONAL,
 245   OUT EFI_ARP_FIND_DATA     **Entries         OPTIONAL,
 246   IN BOOLEAN                Refresh
 247   );
 248
 249 /**
 250   This function removes specified ARP cache entries.
 251
 252   @param  This                   The pointer to the EFI_ARP_PROTOCOL instance.
 253   @param  BySwAddress            Set to TRUE to delete matching protocol addresses.
 254                                  Set to FALSE to delete matching hardware
 255                                  addresses.
 256   @param  AddressBuffer          The pointer to the address buffer that is used as a
 257                                  key to look for the cache entry. Set to NULL to
 258                                  delete all entries.
 259
 260   @retval EFI_SUCCESS            The entry was removed from the ARP cache.
 261   @retval EFI_INVALID_PARAMETER  This is NULL.
 262   @retval EFI_NOT_FOUND          The specified deletion key was not found.
 263   @retval EFI_NOT_STARTED        The ARP driver instance has not been configured.
 264
 265 **/
 266 typedef
 267 EFI_STATUS
 268 (EFIAPI *EFI_ARP_DELETE)(
 269   IN EFI_ARP_PROTOCOL       *This,
 270   IN BOOLEAN                BySwAddress,
 271   IN VOID                   *AddressBuffer   OPTIONAL
 272   );
 273
 274 /**
 275   This function delete all dynamic entries from the ARP cache that match the specified
 276   software protocol type.
 277
 278   @param  This                   The pointer to the EFI_ARP_PROTOCOL instance.
 279
 280   @retval EFI_SUCCESS            The cache has been flushed.
 281   @retval EFI_INVALID_PARAMETER  This is NULL.
 282   @retval EFI_NOT_FOUND          There are no matching dynamic cache entries.
 283   @retval EFI_NOT_STARTED        The ARP driver instance has not been configured.
 284
 285 **/
 286 typedef
 287 EFI_STATUS
 288 (EFIAPI *EFI_ARP_FLUSH)(
 289   IN EFI_ARP_PROTOCOL       *This
 290   );
 291
 292 /**
 293   This function tries to resolve the TargetSwAddress and optionally returns a
 294   TargetHwAddress if it already exists in the ARP cache.
 295
 296   @param  This                   The pointer to the EFI_ARP_PROTOCOL instance.
 297   @param  TargetSwAddress        The pointer to the protocol address to resolve.
 298   @param  ResolvedEvent          The pointer to the event that will be signaled when
 299                                  the address is resolved or some error occurs.
 300   @param  TargetHwAddress        The pointer to the buffer for the resolved hardware
 301                                  address in network byte order.
 302
 303   @retval EFI_SUCCESS            The data is copied from the ARP cache into the
 304                                  TargetHwAddress buffer.
 305   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 306                                  This is NULL. TargetHwAddress is NULL.
 307   @retval EFI_ACCESS_DENIED      The requested address is not present in the normal
 308                                  ARP cache but is present in the deny address list.
 309                                  Outgoing traffic to that address is forbidden.
 310   @retval EFI_NOT_STARTED        The ARP driver instance has not been configured.
 311   @retval EFI_NOT_READY          The request has been started and is not finished.
 312
 313 **/
 314 typedef
 315 EFI_STATUS
 316 (EFIAPI *EFI_ARP_REQUEST)(
 317   IN EFI_ARP_PROTOCOL       *This,
 318   IN VOID                   *TargetSwAddress  OPTIONAL,
 319   IN EFI_EVENT              ResolvedEvent     OPTIONAL,
 320   OUT VOID                  *TargetHwAddress
 321   );
 322
 323 /**
 324   This function aborts the previous ARP request (identified by This, TargetSwAddress
 325   and ResolvedEvent) that is issued by EFI_ARP_PROTOCOL.Request().
 326
 327   If the request is in the internal ARP request queue, the request is aborted
 328   immediately and its ResolvedEvent is signaled. Only an asynchronous address
 329   request needs to be canceled. If TargeSwAddress and ResolveEvent are both
 330   NULL, all the pending asynchronous requests that have been issued by This
 331   instance will be cancelled and their corresponding events will be signaled.
 332
 333   @param  This                   The pointer to the EFI_ARP_PROTOCOL instance.
 334   @param  TargetSwAddress        The pointer to the protocol address in previous
 335                                  request session.
 336   @param  ResolvedEvent          Pointer to the event that is used as the
 337                                  notification event in previous request session.
 338
 339   @retval EFI_SUCCESS            The pending request session(s) is/are aborted and
 340                                  corresponding event(s) is/are signaled.
 341   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 342                                  This is NULL. TargetSwAddress is not NULL and
 343                                  ResolvedEvent is NULL. TargetSwAddress is NULL and
 344                                  ResolvedEvent is not NULL.
 345   @retval EFI_NOT_STARTED        The ARP driver instance has not been configured.
 346   @retval EFI_NOT_FOUND          The request is not issued by
 347                                  EFI_ARP_PROTOCOL.Request().
 348
 349
 350 **/
 351 typedef
 352 EFI_STATUS
 353 (EFIAPI *EFI_ARP_CANCEL)(
 354   IN EFI_ARP_PROTOCOL       *This,
 355   IN VOID                   *TargetSwAddress  OPTIONAL,
 356   IN EFI_EVENT              ResolvedEvent     OPTIONAL
 357   );
 358
 359 ///
 360 /// ARP is used to resolve local network protocol addresses into
 361 /// network hardware addresses.
 362 ///
 363 struct _EFI_ARP_PROTOCOL {
 364   EFI_ARP_CONFIGURE    Configure;
 365   EFI_ARP_ADD          Add;
 366   EFI_ARP_FIND         Find;
 367   EFI_ARP_DELETE       Delete;
 368   EFI_ARP_FLUSH        Flush;
 369   EFI_ARP_REQUEST      Request;
 370   EFI_ARP_CANCEL       Cancel;
 371 };
 372
 373 extern EFI_GUID  gEfiArpServiceBindingProtocolGuid;
 374 extern EFI_GUID  gEfiArpProtocolGuid;
 375
 376 #endif