-/** @file\r
- Copyright (c) 2006, Intel Corporation \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
- http://opensource.org/licenses/bsd-license.php \r
+/** @file \r
+ EFI ARP Protocol Definition\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
+ The EFI ARP Service Binding Protocol is used to locate EFI\r
+ ARP Protocol drivers to create and destroy child of the\r
+ driver to communicate with other host using ARP protocol.\r
+ The EFI ARP Protocol provides services to map IP network\r
+ address to hardware address used by a data link protocol.\r
\r
- Module Name: Arp.h\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<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
**/\r
\r
typedef struct _EFI_ARP_PROTOCOL EFI_ARP_PROTOCOL;\r
\r
typedef struct {\r
-UINT32 Size;\r
-BOOLEAN DenyFlag;\r
-BOOLEAN StaticFlag;\r
-UINT16 HwAddressType;\r
-UINT16 SwAddressType;\r
-UINT8 HwAddressLength;\r
-UINT8 SwAddressLength;\r
+ ///\r
+ /// Length in bytes of this entry.\r
+ ///\r
+ UINT32 Size;\r
+\r
+ ///\r
+ /// Set to TRUE if this entry is a "deny" entry.\r
+ /// Set to FALSE if this entry is a "normal" entry.\r
+ ///\r
+ BOOLEAN DenyFlag;\r
+\r
+ ///\r
+ /// Set to TRUE if this entry will not time out.\r
+ /// Set to FALSE if this entry will time out.\r
+ ///\r
+ BOOLEAN StaticFlag;\r
+\r
+ ///\r
+ /// 16-bit ARP hardware identifier number.\r
+ ///\r
+ UINT16 HwAddressType;\r
+\r
+ ///\r
+ /// 16-bit protocol type number.\r
+ ///\r
+ UINT16 SwAddressType;\r
+\r
+ ///\r
+ /// Length of the hardware address.\r
+ ///\r
+ UINT8 HwAddressLength;\r
+\r
+ ///\r
+ /// Length of the protocol address.\r
+ ///\r
+ UINT8 SwAddressLength;\r
} EFI_ARP_FIND_DATA;\r
\r
typedef struct {\r
- UINT16 SwAddressType; // Host byte order\r
+ ///\r
+ /// 16-bit protocol type number in host byte order.\r
+ ///\r
+ UINT16 SwAddressType;\r
+\r
+ ///\r
+ /// Length in bytes of the station's protocol address to register.\r
+ ///\r
UINT8 SwAddressLength;\r
- VOID *StationAddress; // Network byte order\r
+\r
+ ///\r
+ /// Pointer to the first byte of the protocol address to register. For\r
+ /// example, if SwAddressType is 0x0800 (IP), then\r
+ /// StationAddress points to the first byte of this station's IP\r
+ /// address stored in network byte order.\r
+ ///\r
+ VOID *StationAddress;\r
+\r
+ ///\r
+ /// The timeout value in 100-ns units that is associated with each\r
+ /// new dynamic ARP cache entry. If it is set to zero, the value is\r
+ /// implementation-specific.\r
+ ///\r
UINT32 EntryTimeOut;\r
+\r
+ ///\r
+ /// The number of retries before a MAC address is resolved. If it is\r
+ /// set to zero, the value is implementation-specific.\r
+ ///\r
UINT32 RetryCount;\r
+\r
+ ///\r
+ /// The timeout value in 100-ns units that is used to wait for the ARP\r
+ /// reply packet or the timeout value between two retries. Set to zero\r
+ /// to use implementation-specific value.\r
+ ///\r
UINT32 RetryTimeOut;\r
} EFI_ARP_CONFIG_DATA;\r
\r
\r
/**\r
- Assigns a station address (protocol type and network address) to this instance of the ARP cache.\r
-\r
- @param This A pointer to the EFI_ARP_PROTOCOL instance.\r
- @param ConfigData A pointer to the EFI_ARP_CONFIG_DATA structure.Buffer\r
-\r
- @retval EFI_SUCCESS The new station address was successfully registered.\r
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
- @retval EFI_ACCESS_DENIED The SwAddressType, SwAddressLength, or\r
- StationAddress is different from the one that is already\r
- registered.\r
- @retval EFI_OUT_OF_RESOURCES Storage for the new StationAddress could not be allocated.\r
+ This function is used to assign a station address to the ARP cache for this 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
+ @retval EFI_SUCCESS The new station address was successfully\r
+ registered.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ This is NULL. SwAddressLength is zero when\r
+ ConfigData is not NULL. StationAddress is NULL\r
+ when ConfigData is not NULL.\r
+ @retval EFI_ACCESS_DENIED The SwAddressType, SwAddressLength, or\r
+ StationAddress is different from the one that is\r
+ already registered.\r
+ @retval EFI_OUT_OF_RESOURCES Storage for the new StationAddress could not be\r
+ allocated.\r
\r
**/\r
typedef \r
EFI_STATUS\r
-(EFIAPI *EFI_ARP_CONFIGURE) (\r
+(EFIAPI *EFI_ARP_CONFIGURE)(\r
IN EFI_ARP_PROTOCOL *This,\r
IN EFI_ARP_CONFIG_DATA *ConfigData OPTIONAL\r
- )\r
-; \r
+ ); \r
\r
/**\r
- Inserts an entry to the ARP cache.\r
-\r
- @param This A pointer to the EFI_ARP_PROTOCOL instance. \r
- @param DenyFlag Set to TRUE if this entry is a ¡°deny¡± entry. Set to FALSE if this\r
- entry is a ¡°normal¡± entry.\r
- @param TargetSwAddress Pointer to a protocol address to add (or deny). May be set to\r
- NULL if DenyFlag is TRUE.\r
- @param TargetHwAddress Pointer to a hardware address to add (or deny). May be set to\r
- NULL if DenyFlag is TRUE.\r
- @param TimeoutValue Time in 100-ns units that this entry will remain in the ARP\r
- cache. A value of zero means that the entry is permanent. A\r
- nonzero value will override the one given by Configure() if\r
- the entry to be added is dynamic entry.\r
- @param Overwrite If TRUE, the matching cache entry will be overwritten with the\r
- supplied parameters. If FALSE, EFI_ACCESS_DENIED\r
-\r
- @retval EFI_SUCCESS The entry has been added or updated.\r
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
- @retval EFI_OUT_OF_RESOURCES The new ARP cache entry could not be allocated.\r
- @retval EFI_ACCESS_DENIED The ARP cache entry already exists and Overwrite is not true.\r
- @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\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
+ @param TargetSwAddress Pointer to a protocol address to add (or deny).\r
+ May be set to NULL if DenyFlag is TRUE.\r
+ @param TargetHwAddress Pointer to a hardware address to add (or deny).\r
+ May be set to NULL if DenyFlag is TRUE.\r
+ @param TimeoutValue Time in 100-ns units that this entry will remain\r
+ in the ARP cache. A value of zero means that the\r
+ entry is permanent. A nonzero value will override\r
+ the one given by Configure() if the entry to be\r
+ added is a dynamic entry.\r
+ @param Overwrite If TRUE, the matching cache entry will be\r
+ overwritten with the supplied parameters. If\r
+ FALSE, EFI_ACCESS_DENIED is returned if the\r
+ corresponding cache entry already exists.\r
+\r
+ @retval EFI_SUCCESS The entry has been added or updated.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ This is NULL. DenyFlag is FALSE and\r
+ TargetHwAddress is NULL. DenyFlag is FALSE and\r
+ TargetSwAddress is NULL. TargetHwAddress is NULL\r
+ and TargetSwAddress is NULL. Both TargetSwAddress\r
+ and TargetHwAddress are not NULL when DenyFlag is\r
+ TRUE.\r
+ @retval EFI_OUT_OF_RESOURCES The new ARP cache entry could not be allocated.\r
+ @retval EFI_ACCESS_DENIED The ARP cache entry already exists and Overwrite\r
+ is not true.\r
+ @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_ARP_ADD) (\r
+(EFIAPI *EFI_ARP_ADD)(\r
IN EFI_ARP_PROTOCOL *This,\r
IN BOOLEAN DenyFlag,\r
IN VOID *TargetSwAddress OPTIONAL,\r
IN VOID *TargetHwAddress OPTIONAL,\r
IN UINT32 TimeoutValue,\r
IN BOOLEAN Overwrite\r
- )\r
-; \r
+ ); \r
\r
/**\r
- Locates one or more entries in the ARP cache.\r
-\r
- @param This A pointer to the EFI_ARP_PROTOCOL instance.\r
- @param BySwAddress Set to TRUE to look for matching software protocol addresses.\r
- Set to FALSE to look for matching hardware protocol addresses.\r
- @param AddressBuffer Pointer to address buffer. Set to NULL to match all addresses.\r
- @param EntryLength The size of an entry in the entries buffer. To keep the\r
- EFI_ARP_FIND_DATA structure properly aligned, this field\r
- may be longer than sizeof(EFI_ARP_FIND_DATA) plus\r
- the length of the software and hardware addresses.\r
- @param EntryCount The number of ARP cache entries that are found by the specified criteria.\r
- @param Entries Pointer to the buffer that will receive the ARP cache entries.\r
- @param Refresh Set to TRUE to refresh the timeout value of the matching ARP\r
- cache entry.\r
-\r
- @retval EFI_SUCCESS The requested ARP cache entries were copied into the buffer.\r
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
- @retval EFI_NOT_FOUND No matching entries were found.\r
- @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
+ This function searches the ARP cache for matching entries and allocates a buffer into\r
+ which those entries are copied.\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
+ hardware protocol addresses.\r
+ @param 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
+ the specified criteria.\r
+ @param 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
+ matching ARP cache entry.\r
+\r
+ @retval EFI_SUCCESS The requested ARP cache entries were copied into\r
+ the buffer.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ This is NULL. Both EntryCount and EntryLength are\r
+ NULL, when Refresh is FALSE.\r
+ @retval EFI_NOT_FOUND No matching entries were found.\r
+ @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
\r
**/\r
typedef \r
EFI_STATUS\r
-(EFIAPI *EFI_ARP_FIND) (\r
+(EFIAPI *EFI_ARP_FIND)(\r
IN EFI_ARP_PROTOCOL *This,\r
IN BOOLEAN BySwAddress,\r
IN VOID *AddressBuffer OPTIONAL,\r
OUT UINT32 *EntryCount OPTIONAL,\r
OUT EFI_ARP_FIND_DATA **Entries OPTIONAL,\r
IN BOOLEAN Refresh\r
- )\r
-; \r
+ ); \r
\r
\r
/**\r
- Removes entries from the ARP cache.\r
+ This function removes specified ARP cache entries.\r
\r
- @param This A pointer to the EFI_ARP_PROTOCOL instance.\r
- @param BySwAddress Set to TRUE to delete matching protocol addresses.\r
- Set to FALSE to delete matching hardware addresses.\r
- @param AddressBuffer Pointer to the address buffer that is used as a key to look for the\r
- cache entry. Set to NULL to delete all entries.\r
+ @param This Pointer to the EFI_ARP_PROTOCOL instance.\r
+ @param BySwAddress Set to TRUE to delete matching protocol addresses.\r
+ Set to FALSE to delete matching hardware\r
+ addresses.\r
+ @param AddressBuffer Pointer to the address buffer that is used as a\r
+ key to look for the cache entry. Set to NULL to\r
+ delete all entries.\r
\r
- @retval EFI_SUCCESS The entry was removed from the ARP cache.\r
- @retval EFI_INVALID_PARAMETER This is NULL.\r
- @retval EFI_NOT_FOUND The specified deletion key was not found.\r
- @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
+ @retval EFI_SUCCESS The entry was removed from the ARP cache.\r
+ @retval EFI_INVALID_PARAMETER This is NULL.\r
+ @retval EFI_NOT_FOUND The specified deletion key was not found.\r
+ @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_ARP_DELETE) (\r
+(EFIAPI *EFI_ARP_DELETE)(\r
IN EFI_ARP_PROTOCOL *This,\r
IN BOOLEAN BySwAddress,\r
IN VOID *AddressBuffer OPTIONAL\r
- )\r
-; \r
+ ); \r
\r
/**\r
- Removes all dynamic ARP cache entries that were added by this interface.\r
+ This function delete all dynamic entries from the ARP cache that match the specified\r
+ software protocol type.\r
+\r
+ @param This Pointer to the EFI_ARP_PROTOCOL instance.\r
\r
- @param This A pointer to the EFI_ARP_PROTOCOL instance.\r
- \r
- @retval EFI_SUCCESS The cache has been flushed.\r
- @retval EFI_INVALID_PARAMETER This is NULL.\r
- @retval EFI_NOT_FOUND There are no matching dynamic cache entries.\r
- @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
+ @retval EFI_SUCCESS The cache has been flushed.\r
+ @retval EFI_INVALID_PARAMETER This is NULL.\r
+ @retval EFI_NOT_FOUND There are no matching dynamic cache entries.\r
+ @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_ARP_FLUSH) (\r
+(EFIAPI *EFI_ARP_FLUSH)(\r
IN EFI_ARP_PROTOCOL *This\r
- )\r
-; \r
+ ); \r
\r
/**\r
- Starts an ARP request session.\r
-\r
- @param This A pointer to the EFI_ARP_PROTOCOL instance.\r
- @param TargetSwAddress Pointer to the protocol address to resolve.\r
- @param ResolvedEvent Pointer to the event that will be signaled when the address is\r
- resolved or some error occurs.\r
- @param TargetHwAddress Pointer to the buffer for the resolved hardware address in\r
- network byte order. The buffer must be large enough to hold the\r
- resulting hardware address. TargetHwAddress must not be\r
- NULL.\r
-\r
- @retval EFI_SUCCESS The data was copied from the ARP cache into the\r
- TargetHwAddress buffer.\r
- @retval EFI_INVALID_PARAMETER This or TargetHwAddress is NULL.\r
- @retval EFI_ACCESS_DENIED The requested address is not present in the normal ARP cache but\r
- is present in the deny address list. Outgoing traffic to that address is\r
- forbidden.\r
- @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
- @retval EFI_NOT_READY The request has been started and is not finished.\r
- @retval EFI_UNSUPPORTED The requested conversion is not supported in this implementation or\r
- configuration.\r
+ This function tries to resolve the TargetSwAddress and optionally returns a\r
+ TargetHwAddress if it already exists in the ARP cache.\r
+\r
+ @param This Pointer to the EFI_ARP_PROTOCOL instance.\r
+ @param TargetSwAddress Pointer to the protocol address to resolve.\r
+ @param ResolvedEvent Pointer to the event that will be signaled when\r
+ the address is resolved or some error occurs.\r
+ @param TargetHwAddress Pointer to the buffer for the resolved hardware\r
+ address in network byte order.\r
+\r
+ @retval EFI_SUCCESS The data is copied from the ARP cache into the\r
+ TargetHwAddress buffer.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ This is NULL. TargetHwAddress is NULL.\r
+ @retval EFI_ACCESS_DENIED The requested address is not present in the normal\r
+ ARP cache but is present in the deny address list.\r
+ Outgoing traffic to that address is forbidden.\r
+ @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
+ @retval EFI_NOT_READY The request has been started and is not finished.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_ARP_REQUEST) (\r
+(EFIAPI *EFI_ARP_REQUEST)(\r
IN EFI_ARP_PROTOCOL *This, \r
IN VOID *TargetSwAddress OPTIONAL,\r
IN EFI_EVENT ResolvedEvent OPTIONAL,\r
OUT VOID *TargetHwAddress \r
- )\r
-; \r
+ ); \r
\r
/**\r
- Cancels an ARP request session.\r
-\r
- @param This A pointer to the EFI_ARP_PROTOCOL instance.\r
- @param TargetSwAddress Pointer to the protocol address in previous request session.\r
- @param ResolvedEvent Pointer to the event that is used as the notification event in\r
- previous request session.\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
+ 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
+ @param ResolvedEvent Pointer to the event that is used as the\r
+ notification event in previous request session.\r
+\r
+ @retval EFI_SUCCESS The pending request session(s) is/are aborted and\r
+ corresponding event(s) is/are signaled.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ This is NULL. TargetSwAddress is not NULL and\r
+ ResolvedEvent is NULL. TargetSwAddress is NULL and\r
+ ResolvedEvent is not NULL.\r
+ @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
+ @retval EFI_NOT_FOUND The request is not issued by\r
+ EFI_ARP_PROTOCOL.Request().\r
\r
- @retval EFI_SUCCESS The pending request session(s) is/are aborted and corresponding\r
- event(s) is/are signaled.\r
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
- @retval EFI_NOT_STARTED The ARP driver instance has not been configured.\r
- @retval EFI_NOT_FOUND The request is not issued by\r
- EFI_ARP_PROTOCOL.Request().\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_ARP_CANCEL) (\r
+(EFIAPI *EFI_ARP_CANCEL)(\r
IN EFI_ARP_PROTOCOL *This, \r
IN VOID *TargetSwAddress OPTIONAL,\r
IN EFI_EVENT ResolvedEvent OPTIONAL\r
- )\r
-; \r
+ ); \r
\r
+///\r
+/// ARP is used to resolve local network protocol addresses into \r
+/// network hardware addresses.\r
+///\r
struct _EFI_ARP_PROTOCOL {\r
EFI_ARP_CONFIGURE Configure;\r
EFI_ARP_ADD Add;\r
projects / mirror_edk2.git / blobdiff