[mirror_edk2.git] / MdePkg / Include / Protocol / Arp.h

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