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