Ronak Kanabar | 1ae366f | 2023-06-07 01:21:56 +0530 | [diff] [blame^] | 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 |