/** @file\r
+ EFI Address Resolution Protocol (ARP) Protocol interface header file.\r
\r
-Copyright (c) 2006 - 2008, Intel Corporation\r
+Copyright (c) 2006 - 2008, Intel Corporation.<BR>\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
-which accompanies this distribution. The full text of the license may be found at\r
+which accompanies this distribution. The full text of the license may be found at<BR>\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
-Module Name:\r
-\r
- ArpImpl.h\r
-\r
-Abstract:\r
-\r
-\r
**/\r
\r
#ifndef _ARP_IMPL_H_\r
#define _ARP_IMPL_H_\r
\r
\r
-#include <PiDxe.h>\r
+#include <Uefi.h>\r
\r
#include <Protocol/Arp.h>\r
#include <Protocol/ManagedNetwork.h>\r
#include <Library/BaseMemoryLib.h>\r
#include <Library/MemoryAllocationLib.h>\r
\r
-\r
+//\r
+// Ethernet protocol type definitions.\r
+//\r
#define ARP_ETHER_PROTO_TYPE 0x0806\r
#define IPV4_ETHER_PROTO_TYPE 0x0800\r
#define IPV6_ETHER_PROTO_TYPE 0x86DD\r
\r
+//\r
+// ARP opcode definitions.\r
+//\r
#define ARP_OPCODE_REQUEST 0x0001\r
#define ARP_OPCODE_REPLY 0x0002\r
\r
+//\r
+// ARP timeout, retry count and interval definitions.\r
+//\r
#define ARP_DEFAULT_TIMEOUT_VALUE (400 * TICKS_PER_SECOND)\r
#define ARP_DEFAULT_RETRY_COUNT 2\r
#define ARP_DEFAULT_RETRY_INTERVAL (5 * TICKS_PER_MS)\r
#define ARP_PERIODIC_TIMER_INTERVAL (500 * TICKS_PER_MS)\r
\r
+//\r
+// ARP packet head definition.\r
+//\r
#pragma pack(1)\r
-typedef struct _ARP_HEAD {\r
+typedef struct {\r
UINT16 HwType;\r
UINT16 ProtoType;\r
UINT8 HwAddrLen;\r
} ARP_HEAD;\r
#pragma pack()\r
\r
-typedef struct _ARP_ADDRESS {\r
+//\r
+// ARP Address definition for internal use.\r
+//\r
+typedef struct {\r
UINT8 *SenderHwAddr;\r
UINT8 *SenderProtoAddr;\r
UINT8 *TargetHwAddr;\r
#define MATCH_SW_ADDRESS 0x1\r
#define MATCH_HW_ADDRESS 0x2\r
\r
+//\r
+// Enumeration for the search type. A search type is specified as the keyword to find\r
+// a cache entry in the cache table.\r
+//\r
typedef enum {\r
ByNone = 0,\r
ByProtoAddress = MATCH_SW_ADDRESS,\r
ByBoth = MATCH_SW_ADDRESS | MATCH_HW_ADDRESS\r
} FIND_OPTYPE;\r
\r
-#define ARP_INSTANCE_DATA_SIGNATURE EFI_SIGNATURE_32('A', 'R', 'P', 'I')\r
+#define ARP_INSTANCE_DATA_SIGNATURE SIGNATURE_32('A', 'R', 'P', 'I')\r
\r
+/**\r
+ Returns a pointer to the ARP_INSTANCE_DATA structure from the input a.\r
+ \r
+ If the signatures matches, then a pointer to the data structure that contains \r
+ a specified field of that data structure is returned.\r
+ \r
+ @param a Pointer to the field specified by ArpProto within a data \r
+ structure of type ARP_INSTANCE_DATA.\r
+ \r
+**/\r
#define ARP_INSTANCE_DATA_FROM_THIS(a) \\r
CR ( \\r
(a), \\r
\r
typedef struct _ARP_SERVICE_DATA ARP_SERVICE_DATA;\r
\r
-typedef struct _ARP_INSTANCE_DATA {\r
+//\r
+// ARP instance context data structure.\r
+//\r
+typedef struct {\r
UINT32 Signature;\r
ARP_SERVICE_DATA *ArpService;\r
EFI_HANDLE Handle;\r
BOOLEAN Destroyed;\r
} ARP_INSTANCE_DATA;\r
\r
-#define ARP_SERVICE_DATA_SIGNATURE EFI_SIGNATURE_32('A', 'R', 'P', 'S')\r
+#define ARP_SERVICE_DATA_SIGNATURE SIGNATURE_32('A', 'R', 'P', 'S')\r
\r
+/**\r
+ Returns a pointer to the ARP_SERVICE_DATA structure from the input a.\r
+ \r
+ If the signatures matches, then a pointer to the data structure that contains \r
+ a specified field of that data structure is returned.\r
+ \r
+ @param a Pointer to the field specified by ServiceBinding within \r
+ a data structure of type ARP_SERVICE_DATA.\r
+ \r
+**/\r
#define ARP_SERVICE_DATA_FROM_THIS(a) \\r
CR ( \\r
(a), \\r
ARP_SERVICE_DATA_SIGNATURE \\r
)\r
\r
+//\r
+// ARP service data structure.\r
+//\r
struct _ARP_SERVICE_DATA {\r
UINT32 Signature;\r
EFI_SERVICE_BINDING_PROTOCOL ServiceBinding;\r
EFI_EVENT PeriodicTimer;\r
};\r
\r
-typedef struct _USER_REQUEST_CONTEXT {\r
+//\r
+// User request context structure.\r
+//\r
+typedef struct {\r
LIST_ENTRY List;\r
ARP_INSTANCE_DATA *Instance;\r
EFI_EVENT UserRequestEvent;\r
#define ARP_MAX_PROTOCOL_ADDRESS_LEN sizeof(EFI_IP_ADDRESS)\r
#define ARP_MAX_HARDWARE_ADDRESS_LEN sizeof(EFI_MAC_ADDRESS)\r
\r
-typedef struct _NET_ARP_ADDRESS {\r
+//\r
+// ARP address structure in an ARP packet.\r
+//\r
+typedef struct {\r
UINT16 Type;\r
UINT8 Length;\r
UINT8 *AddressPtr;\r
} Buffer;\r
} NET_ARP_ADDRESS;\r
\r
+//\r
+// Enumeration for ARP address type.\r
+//\r
typedef enum {\r
Hardware,\r
Protocol\r
} ARP_ADDRESS_TYPE;\r
\r
-typedef struct _ARP_CACHE_ENTRY {\r
+//\r
+// ARP cache entry definition.\r
+//\r
+typedef struct {\r
LIST_ENTRY List;\r
\r
UINT32 RetryCount;\r
\r
/**\r
This function is used to assign a station address to the ARP cache for this instance\r
- of the ARP driver. A call to this function with the ConfigData field set to NULL\r
- will reset this ARP instance.\r
+ of the ARP driver.\r
+ \r
+ Each ARP instance has one station address. The EFI_ARP_PROTOCOL driver will \r
+ respond to ARP requests that match this registered station address. A call to \r
+ this function with the ConfigData field set to NULL will reset this ARP instance.\r
+ \r
+ Once a protocol type and station address have been assigned to this ARP instance, \r
+ all the following ARP functions will use this information. Attempting to change \r
+ the protocol type or station address to a configured ARP instance will result in errors.\r
\r
@param This Pointer to the EFI_ARP_PROTOCOL instance.\r
@param ConfigData Pointer to the EFI_ARP_CONFIG_DATA structure.\r
/**\r
This function is used to insert entries into the ARP cache.\r
\r
+ ARP cache entries are typically inserted and updated by network protocol drivers \r
+ as network traffic is processed. Most ARP cache entries will time out and be \r
+ deleted if the network traffic stops. ARP cache entries that were inserted \r
+ by the Add() function may be static (will not time out) or dynamic (will time out).\r
+ Default ARP cache timeout values are not covered in most network protocol \r
+ specifications (although RFC 1122 comes pretty close) and will only be \r
+ discussed in general in this specification. The timeout values that are \r
+ used in the EFI Sample Implementation should be used only as a guideline. \r
+ Final product implementations of the EFI network stack should be tuned for \r
+ their expected network environments.\r
+ \r
@param This Pointer to the EFI_ARP_PROTOCOL instance.\r
@param DenyFlag Set to TRUE if this entry is a deny entry. Set to\r
FALSE if this entry is a normal entry.\r
/**\r
This function searches the ARP cache for matching entries and allocates a buffer into\r
which those entries are copied.\r
-\r
+ \r
+ The first part of the allocated buffer is EFI_ARP_FIND_DATA, following which \r
+ are protocol address pairs and hardware address pairs.\r
+ When finding a specific protocol address (BySwAddress is TRUE and AddressBuffer \r
+ is not NULL), the ARP cache timeout for the found entry is reset if Refresh is \r
+ set to TRUE. If the found ARP cache entry is a permanent entry, it is not \r
+ affected by Refresh.\r
+ \r
@param This Pointer to the EFI_ARP_PROTOCOL instance.\r
@param BySwAddress Set to TRUE to look for matching software protocol\r
addresses. Set to FALSE to look for matching\r
/**\r
This function aborts the previous ARP request (identified by This, TargetSwAddress\r
and ResolvedEvent) that is issued by EFI_ARP_PROTOCOL.Request().\r
-\r
+ \r
+ If the request is in the internal ARP request queue, the request is aborted \r
+ immediately and its ResolvedEvent is signaled. Only an asynchronous address \r
+ request needs to be canceled. If TargeSwAddress and ResolveEvent are both \r
+ NULL, all the pending asynchronous requests that have been issued by This \r
+ instance will be cancelled and their corresponding events will be signaled.\r
+ \r
@param This Pointer to the EFI_ARP_PROTOCOL instance.\r
@param TargetSwAddress Pointer to the protocol address in previous\r
request session.\r
/**\r
Configure the instance using the ConfigData. ConfigData is already validated.\r
\r
- @param Instance Pointer to the instance context data to be\r
+ @param[in] Instance Pointer to the instance context data to be\r
configured.\r
- @param ConfigData Pointer to the configuration data used to\r
+ @param[in] ConfigData Pointer to the configuration data used to\r
configure the instance.\r
\r
@retval EFI_SUCCESS The instance is configured with the ConfigData.\r
Find the CacheEntry, using ProtocolAddress or HardwareAddress or both, as the keyword,\r
in the DeniedCacheTable.\r
\r
- @param ArpService Pointer to the arp service context data.\r
- @param ProtocolAddress Pointer to the protocol address.\r
- @param HardwareAddress Pointer to the hardware address.\r
+ @param[in] ArpService Pointer to the arp service context data.\r
+ @param[in] ProtocolAddress Pointer to the protocol address.\r
+ @param[in] HardwareAddress Pointer to the hardware address.\r
\r
@return Pointer to the matched cache entry, if NULL no match is found.\r
\r
/**\r
Find the CacheEntry which matches the requirements in the specified CacheTable.\r
\r
- @param CacheTable Pointer to the arp cache table.\r
- @param StartEntry Pointer to the start entry this search begins with\r
- in the cache table.\r
- @param FindOpType The search type.\r
- @param ProtocolAddress Pointer to the protocol address to match.\r
- @param HardwareAddress Pointer to the hardware address to match.\r
+ @param[in] CacheTable Pointer to the arp cache table.\r
+ @param[in] StartEntry Pointer to the start entry this search begins with\r
+ in the cache table.\r
+ @param[in] FindOpType The search type.\r
+ @param[in] ProtocolAddress Pointer to the protocol address to match.\r
+ @param[in] HardwareAddress Pointer to the hardware address to match.\r
\r
@return Pointer to the matched arp cache entry, if NULL, no match is found.\r
\r
/**\r
Allocate a cache entry and initialize it.\r
\r
- @param Instance Pointer to the instance context data.\r
+ @param[in] Instance Pointer to the instance context data.\r
\r
@return Pointer to the new created cache entry.\r
\r
Fill the addresses in the CacheEntry using the information passed in by\r
HwAddr and SwAddr.\r
\r
- @param CacheEntry Pointer to the cache entry.\r
- @param HwAddr Pointer to the software address.\r
- @param SwAddr Pointer to the hardware address.\r
+ @param[in] CacheEntry Pointer to the cache entry.\r
+ @param[in] HwAddr Pointer to the software address.\r
+ @param[in] SwAddr Pointer to the hardware address.\r
\r
@return None.\r
\r
/**\r
Turn the CacheEntry into the resolved status.\r
\r
- @param CacheEntry Pointer to the resolved cache entry.\r
- @param Instance Pointer to the instance context data.\r
- @param UserEvent Pointer to the UserEvent to notify.\r
+ @param[in] CacheEntry Pointer to the resolved cache entry.\r
+ @param[in] Instance Pointer to the instance context data.\r
+ @param[in] UserEvent Pointer to the UserEvent to notify.\r
\r
@return The count of notifications sent to the instance.\r
\r
/**\r
Delete cache entries in all the cache tables.\r
\r
- @param Instance Pointer to the instance context data.\r
- @param BySwAddress Delete the cache entry by software address or by\r
- hardware address.\r
- @param AddressBuffer Pointer to the buffer containing the address to\r
- match for the deletion.\r
- @param Force This deletion is forced or not.\r
+ @param[in] Instance Pointer to the instance context data.\r
+ @param[in] BySwAddress Delete the cache entry by software address or by\r
+ hardware address.\r
+ @param[in] AddressBuffer Pointer to the buffer containing the address to\r
+ match for the deletion.\r
+ @param[in] Force This deletion is forced or not.\r
\r
@return The count of the deleted cache entries.\r
\r
/**\r
Send out an arp frame using the CachEntry and the ArpOpCode.\r
\r
- @param Instance Pointer to the instance context data.\r
- @param CacheEntry Pointer to the configuration data used to\r
- configure the instance.\r
- @param ArpOpCode The opcode used to send out this Arp frame, either\r
- request or reply.\r
+ @param[in] Instance Pointer to the instance context data.\r
+ @param[in] CacheEntry Pointer to the configuration data used to\r
+ configure the instance.\r
+ @param[in] ArpOpCode The opcode used to send out this Arp frame, either\r
+ request or reply.\r
\r
@return None.\r
\r
/**\r
Initialize the instance context data.\r
\r
- @param ArpService Pointer to the arp service context data this\r
+ @param[in] ArpService Pointer to the arp service context data this\r
instance belongs to.\r
- @param Instance Pointer to the instance context data.\r
+ @param[out] Instance Pointer to the instance context data.\r
\r
@return None.\r
\r
**/\r
VOID\r
ArpInitInstance (\r
- IN ARP_SERVICE_DATA *ArpService,\r
- IN ARP_INSTANCE_DATA *Instance\r
+ IN ARP_SERVICE_DATA *ArpService,\r
+ OUT ARP_INSTANCE_DATA *Instance\r
);\r
\r
/**\r
Process the Arp packets received from Mnp, the procedure conforms to RFC826.\r
\r
- @param Context Pointer to the context data registerd to the\r
+ @param[in] Context Pointer to the context data registerd to the\r
Event.\r
\r
@return None.\r
/**\r
Queue ArpOnFrameRcvdDpc as a DPC at TPL_CALLBACK.\r
\r
- @param Event The Event this notify function registered to.\r
- @param Context Pointer to the context data registerd to the\r
- Event.\r
+ @param[in] Event The Event this notify function registered to.\r
+ @param[in] Context Pointer to the context data registerd to the\r
+ Event.\r
\r
@return None.\r
\r
\r
/**\r
Process the already sent arp packets.\r
-\r
- @param Context Pointer to the context data registerd to the\r
- Event.\r
+ \r
+ @param[in] Context Pointer to the context data registerd to the\r
+ Event.\r
\r
@return None.\r
\r
);\r
\r
/**\r
- Queue ArpOnFrameRcvdDpc as a DPC at TPL_CALLBACK.\r
+ Request ArpOnFrameSentDpc as a DPC at TPL_CALLBACK.\r
\r
- @param Event The Event this notify function registered to.\r
- @param Context Pointer to the context data registerd to the\r
- Event.\r
+ @param[in] Event The Event this notify function registered to.\r
+ @param[in] Context Pointer to the context data registerd to the\r
+ Event.\r
\r
@return None.\r
\r
/**\r
Process the arp cache olding and drive the retrying arp requests.\r
\r
- @param Event The Event this notify function registered to.\r
- @param Context Pointer to the context data registerd to the\r
- Event.\r
+ @param[in] Event The Event this notify function registered to.\r
+ @param[in] Context Pointer to the context data registerd to the\r
+ Event.\r
\r
@return None.\r
\r
/**\r
Cancel the arp request.\r
\r
- @param Instance Pointer to the instance context data.\r
- @param TargetSwAddress Pointer to the buffer containing the target\r
- software address to match the arp request.\r
- @param UserEvent The user event used to notify this request\r
- cancellation.\r
+ @param[in] Instance Pointer to the instance context data.\r
+ @param[in] TargetSwAddress Pointer to the buffer containing the target\r
+ software address to match the arp request.\r
+ @param[in] UserEvent The user event used to notify this request\r
+ cancellation.\r
\r
@return The count of the cancelled requests.\r
\r
/**\r
Find the cache entry in the cache table.\r
\r
- @param Instance Pointer to the instance context data.\r
- @param BySwAddress Set to TRUE to look for matching software protocol\r
+ @param[in] Instance Pointer to the instance context data.\r
+ @param[in] BySwAddress Set to TRUE to look for matching software protocol\r
addresses. Set to FALSE to look for matching\r
hardware protocol addresses.\r
- @param AddressBuffer Pointer to address buffer. Set to NULL to match\r
+ @param[in] AddressBuffer Pointer to address buffer. Set to NULL to match\r
all addresses.\r
- @param EntryLength The size of an entry in the entries buffer.\r
- @param EntryCount The number of ARP cache entries that are found by\r
+ @param[out] EntryLength The size of an entry in the entries buffer.\r
+ @param[out] EntryCount The number of ARP cache entries that are found by\r
the specified criteria.\r
- @param Entries Pointer to the buffer that will receive the ARP\r
+ @param[out] Entries Pointer to the buffer that will receive the ARP\r
cache entries.\r
- @param Refresh Set to TRUE to refresh the timeout value of the\r
+ @param[in] Refresh Set to TRUE to refresh the timeout value of the\r
matching ARP cache entry.\r
\r
@retval EFI_SUCCESS The requested ARP cache entries are copied into\r
);\r
\r
#endif\r
-\r
projects / mirror_edk2.git / blobdiff