1 /** @file 2 This file provides a definition of the EFI IPv6 Configuration 3 Protocol. 4 5 Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR> 6 SPDX-License-Identifier: BSD-2-Clause-Patent 7 8 **/ 9 #ifndef __EFI_IP6CONFIG_PROTOCOL_H__ 10 #define __EFI_IP6CONFIG_PROTOCOL_H__ 11 12 #include <Protocol/Ip6.h> 13 14 #define EFI_IP6_CONFIG_PROTOCOL_GUID \ 15 { \ 16 0x937fe521, 0x95ae, 0x4d1a, {0x89, 0x29, 0x48, 0xbc, 0xd9, 0x0a, 0xd3, 0x1a } \ 17 } 18 19 typedef struct _EFI_IP6_CONFIG_PROTOCOL EFI_IP6_CONFIG_PROTOCOL; 20 21 /// 22 /// EFI_IP6_CONFIG_DATA_TYPE 23 /// 24 typedef enum { 25 /// 26 /// The interface information of the communication 27 /// device this EFI IPv6 Configuration Protocol instance manages. 28 /// This type of data is read only.The corresponding Data is of type 29 /// EFI_IP6_CONFIG_INTERFACE_INFO. 30 /// 31 Ip6ConfigDataTypeInterfaceInfo, 32 /// 33 /// The alternative interface ID for the 34 /// communication device this EFI IPv6 Configuration Protocol 35 /// instance manages if the link local IPv6 address generated from 36 /// the interfaced ID based on the default source the EFI IPv6 37 /// Protocol uses is a duplicate address. The length of the interface 38 /// ID is 64 bit. The corresponding Data is of type 39 /// EFI_IP6_CONFIG_INTERFACE_ID. 40 /// 41 Ip6ConfigDataTypeAltInterfaceId, 42 /// 43 /// The general configuration policy for the EFI IPv6 network 44 /// stack running on the communication device this EFI IPv6 45 /// Configuration Protocol instance manages. The policy will affect 46 /// other configuration settings. The corresponding Data is of type 47 /// EFI_IP6_CONFIG_POLICY. 48 /// 49 Ip6ConfigDataTypePolicy, 50 /// 51 /// The number of consecutive 52 /// Neighbor Solicitation messages sent while performing Duplicate 53 /// Address Detection on a tentative address. A value of zero 54 /// indicates that Duplicate Address Detection will not be performed 55 /// on tentative addresses. The corresponding Data is of type 56 /// EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS. 57 /// 58 Ip6ConfigDataTypeDupAddrDetectTransmits, 59 /// 60 /// The station addresses set manually for the EFI 61 /// IPv6 network stack. It is only configurable when the policy is 62 /// Ip6ConfigPolicyManual. The corresponding Data is a 63 /// pointer to an array of EFI_IPv6_ADDRESS instances. When 64 /// DataSize is 0 and Data is NULL, the existing configuration 65 /// is cleared from the EFI IPv6 Configuration Protocol instance. 66 /// 67 Ip6ConfigDataTypeManualAddress, 68 /// 69 /// The gateway addresses set manually for the EFI IPv6 70 /// network stack running on the communication device this EFI 71 /// IPv6 Configuration Protocol manages. It is not configurable when 72 /// the policy is Ip6ConfigPolicyAutomatic. The gateway 73 /// addresses must be unicast IPv6 addresses. The corresponding 74 /// Data is a pointer to an array of EFI_IPv6_ADDRESS instances. 75 /// When DataSize is 0 and Data is NULL, the existing configuration 76 /// is cleared from the EFI IPv6 Configuration Protocol instance. 77 /// 78 Ip6ConfigDataTypeGateway, 79 /// 80 /// The DNS server list for the EFI IPv6 network stack 81 /// running on the communication device this EFI IPv6 82 /// Configuration Protocol manages. It is not configurable when the 83 /// policy is Ip6ConfigPolicyAutomatic.The DNS server 84 /// addresses must be unicast IPv6 addresses. The corresponding 85 /// Data is a pointer to an array of EFI_IPv6_ADDRESS instances. 86 /// When DataSize is 0 and Data is NULL, the existing configuration 87 /// is cleared from the EFI IPv6 Configuration Protocol instance. 88 /// 89 Ip6ConfigDataTypeDnsServer, 90 /// 91 /// The number of this enumeration memebers. 92 /// 93 Ip6ConfigDataTypeMaximum 94 } EFI_IP6_CONFIG_DATA_TYPE; 95 96 /// 97 /// EFI_IP6_CONFIG_INTERFACE_INFO 98 /// describes the operational state of the interface this 99 /// EFI IPv6 Configuration Protocol instance manages. 100 /// 101 typedef struct { 102 /// 103 /// The name of the interface. It is a NULL-terminated string. 104 /// 105 CHAR16 Name[32]; 106 /// 107 /// The interface type of the network interface. 108 /// 109 UINT8 IfType; 110 /// 111 /// The size, in bytes, of the network interface's hardware address. 112 /// 113 UINT32 HwAddressSize; 114 /// 115 /// The hardware address for the network interface. 116 /// 117 EFI_MAC_ADDRESS HwAddress; 118 /// 119 /// Number of EFI_IP6_ADDRESS_INFO structures pointed to by AddressInfo. 120 /// 121 UINT32 AddressInfoCount; 122 /// 123 /// Pointer to an array of EFI_IP6_ADDRESS_INFO instances 124 /// which contain the local IPv6 addresses and the corresponding 125 /// prefix length information. Set to NULL if AddressInfoCount 126 /// is zero. 127 /// 128 EFI_IP6_ADDRESS_INFO *AddressInfo; 129 /// 130 /// Number of route table entries in the following RouteTable. 131 /// 132 UINT32 RouteCount; 133 /// 134 /// The route table of the IPv6 network stack runs on this interface. 135 /// Set to NULL if RouteCount is zero. 136 /// 137 EFI_IP6_ROUTE_TABLE *RouteTable; 138 } EFI_IP6_CONFIG_INTERFACE_INFO; 139 140 /// 141 /// EFI_IP6_CONFIG_INTERFACE_ID 142 /// describes the 64-bit interface ID. 143 /// 144 typedef struct { 145 UINT8 Id[8]; 146 } EFI_IP6_CONFIG_INTERFACE_ID; 147 148 /// 149 /// EFI_IP6_CONFIG_POLICY 150 /// defines the general configuration policy the EFI IPv6 151 /// Configuration Protocol supports. 152 /// 153 typedef enum { 154 /// 155 /// Under this policy, the IpI6ConfigDataTypeManualAddress, 156 /// Ip6ConfigDataTypeGateway and Ip6ConfigDataTypeDnsServer 157 /// configuration data are required to be set manually. 158 /// The EFI IPv6 Protocol will get all required configuration 159 /// such as address, prefix and gateway settings from the EFI 160 /// IPv6 Configuration protocol. 161 /// 162 Ip6ConfigPolicyManual, 163 /// 164 /// Under this policy, the IpI6ConfigDataTypeManualAddress, 165 /// Ip6ConfigDataTypeGateway and Ip6ConfigDataTypeDnsServer 166 /// configuration data are not allowed to set via SetData(). 167 /// All of these configurations are retrieved from some auto 168 /// configuration mechanism. 169 /// The EFI IPv6 Protocol will use the IPv6 stateless address 170 /// autoconfiguration mechanism and/or the IPv6 stateful address 171 /// autoconfiguration mechanism described in the related RFCs to 172 /// get address and other configuration information 173 /// 174 Ip6ConfigPolicyAutomatic 175 } EFI_IP6_CONFIG_POLICY; 176 177 /// 178 /// EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS 179 /// describes the number of consecutive Neighbor Solicitation messages sent 180 /// while performing Duplicate Address Detection on a tentative address. 181 /// The default value for a newly detected communication device is 1. 182 /// 183 typedef struct { 184 UINT32 DupAddrDetectTransmits; ///< The number of consecutive Neighbor Solicitation messages sent. 185 } EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS; 186 187 /// 188 /// EFI_IP6_CONFIG_MANUAL_ADDRESS 189 /// is used to set the station address information for the EFI IPv6 network 190 /// stack manually when the policy is Ip6ConfigPolicyManual. 191 /// 192 typedef struct { 193 EFI_IPv6_ADDRESS Address; ///< The IPv6 unicast address. 194 BOOLEAN IsAnycast; ///< Set to TRUE if Address is anycast. 195 UINT8 PrefixLength; ///< The length, in bits, of the prefix associated with this Address. 196 } EFI_IP6_CONFIG_MANUAL_ADDRESS; 197 198 199 /** 200 Set the configuration for the EFI IPv6 network stack running on the communication 201 device this EFI IPv6 Configuration Protocol instance manages. 202 203 This function is used to set the configuration data of type DataType for the EFI 204 IPv6 network stack running on the communication device this EFI IPv6 Configuration 205 Protocol instance manages. 206 207 The DataSize is used to calculate the count of structure instances in the Data for 208 some DataType that multiple structure instances are allowed. 209 210 This function is always non-blocking. When setting some type of configuration data, 211 an asynchronous process is invoked to check the correctness of the data, such as 212 doing Duplicate Address Detection on the manually set local IPv6 addresses. 213 EFI_NOT_READY is returned immediately to indicate that such an asynchronous process 214 is invoked and the process is not finished yet. The caller willing to get the result 215 of the asynchronous process is required to call RegisterDataNotify() to register an 216 event on the specified configuration data. Once the event is signaled, the caller 217 can call GetData() to get back the configuration data in order to know the result. 218 For other types of configuration data that do not require an asynchronous configuration 219 process, the result of the operation is immediately returned. 220 221 @param[in] This Pointer to the EFI_IP6_CONFIG_PROTOCOL instance. 222 @param[in] DataType The type of data to set. 223 @param[in] DataSize Size of the buffer pointed to by Data in bytes. 224 @param[in] Data The data buffer to set. The type of the data buffer is 225 associated with the DataType. 226 227 @retval EFI_SUCCESS The specified configuration data for the EFI IPv6 228 network stack is set successfully. 229 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: 230 - This is NULL. 231 - One or more fields in Data and DataSize do not match the 232 requirement of the data type indicated by DataType. 233 @retval EFI_WRITE_PROTECTED The specified configuration data is read-only or the specified 234 configuration data can not be set under the current policy 235 @retval EFI_ACCESS_DENIED Another set operation on the specified configuration 236 data is already in process. 237 @retval EFI_NOT_READY An asynchronous process is invoked to set the specified 238 configuration data and the process is not finished yet. 239 @retval EFI_BAD_BUFFER_SIZE The DataSize does not match the size of the type 240 indicated by DataType. 241 @retval EFI_UNSUPPORTED This DataType is not supported. 242 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. 243 @retval EFI_DEVICE_ERROR An unexpected system error or network error occurred. 244 245 **/ 246 typedef 247 EFI_STATUS 248 (EFIAPI *EFI_IP6_CONFIG_SET_DATA)( 249 IN EFI_IP6_CONFIG_PROTOCOL *This, 250 IN EFI_IP6_CONFIG_DATA_TYPE DataType, 251 IN UINTN DataSize, 252 IN VOID *Data 253 ); 254 255 /** 256 Get the configuration data for the EFI IPv6 network stack running on the communication 257 device this EFI IPv6 Configuration Protocol instance manages. 258 259 This function returns the configuration data of type DataType for the EFI IPv6 network 260 stack running on the communication device this EFI IPv6 Configuration Protocol instance 261 manages. 262 263 The caller is responsible for allocating the buffer used to return the specified 264 configuration data and the required size will be returned to the caller if the size of 265 the buffer is too small. 266 267 EFI_NOT_READY is returned if the specified configuration data is not ready due to an 268 already in progress asynchronous configuration process. The caller can call RegisterDataNotify() 269 to register an event on the specified configuration data. Once the asynchronous configuration 270 process is finished, the event will be signaled and a subsequent GetData() call will return 271 the specified configuration data. 272 273 @param[in] This Pointer to the EFI_IP6_CONFIG_PROTOCOL instance. 274 @param[in] DataType The type of data to get. 275 @param[in,out] DataSize On input, in bytes, the size of Data. On output, in bytes, the 276 size of buffer required to store the specified configuration data. 277 @param[in] Data The data buffer in which the configuration data is returned. The 278 type of the data buffer is associated with the DataType. 279 280 @retval EFI_SUCCESS The specified configuration data is got successfully. 281 @retval EFI_INVALID_PARAMETER One or more of the followings are TRUE: 282 - This is NULL. 283 - DataSize is NULL. 284 - Data is NULL if *DataSize is not zero. 285 @retval EFI_BUFFER_TOO_SMALL The size of Data is too small for the specified configuration data 286 and the required size is returned in DataSize. 287 @retval EFI_NOT_READY The specified configuration data is not ready due to an already in 288 progress asynchronous configuration process. 289 @retval EFI_NOT_FOUND The specified configuration data is not found. 290 291 **/ 292 typedef 293 EFI_STATUS 294 (EFIAPI *EFI_IP6_CONFIG_GET_DATA)( 295 IN EFI_IP6_CONFIG_PROTOCOL *This, 296 IN EFI_IP6_CONFIG_DATA_TYPE DataType, 297 IN OUT UINTN *DataSize, 298 IN VOID *Data OPTIONAL 299 ); 300 301 /** 302 Register an event that is to be signaled whenever a configuration process on the specified 303 configuration data is done. 304 305 This function registers an event that is to be signaled whenever a configuration process 306 on the specified configuration data is done. An event can be registered for different DataType 307 simultaneously and the caller is responsible for determining which type of configuration data 308 causes the signaling of the event in such case. 309 310 @param[in] This Pointer to the EFI_IP6_CONFIG_PROTOCOL instance. 311 @param[in] DataType The type of data to unregister the event for. 312 @param[in] Event The event to register. 313 314 @retval EFI_SUCCESS The notification event for the specified configuration data is 315 registered. 316 @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL. 317 @retval EFI_UNSUPPORTED The configuration data type specified by DataType is not 318 supported. 319 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. 320 @retval EFI_ACCESS_DENIED The Event is already registered for the DataType. 321 322 **/ 323 typedef 324 EFI_STATUS 325 (EFIAPI *EFI_IP6_CONFIG_REGISTER_NOTIFY)( 326 IN EFI_IP6_CONFIG_PROTOCOL *This, 327 IN EFI_IP6_CONFIG_DATA_TYPE DataType, 328 IN EFI_EVENT Event 329 ); 330 331 /** 332 Remove a previously registered event for the specified configuration data. 333 334 This function removes a previously registered event for the specified configuration data. 335 336 @param[in] This Pointer to the EFI_IP6_CONFIG_PROTOCOL instance. 337 @param[in] DataType The type of data to remove the previously registered event for. 338 @param[in] Event The event to unregister. 339 340 @retval EFI_SUCCESS The event registered for the specified configuration data is removed. 341 @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL. 342 @retval EFI_NOT_FOUND The Event has not been registered for the specified 343 DataType. 344 345 **/ 346 typedef 347 EFI_STATUS 348 (EFIAPI *EFI_IP6_CONFIG_UNREGISTER_NOTIFY)( 349 IN EFI_IP6_CONFIG_PROTOCOL *This, 350 IN EFI_IP6_CONFIG_DATA_TYPE DataType, 351 IN EFI_EVENT Event 352 ); 353 354 /// 355 /// The EFI_IP6_CONFIG_PROTOCOL provides the mechanism to set and get various 356 /// types of configurations for the EFI IPv6 network stack. 357 /// 358 struct _EFI_IP6_CONFIG_PROTOCOL { 359 EFI_IP6_CONFIG_SET_DATA SetData; 360 EFI_IP6_CONFIG_GET_DATA GetData; 361 EFI_IP6_CONFIG_REGISTER_NOTIFY RegisterDataNotify; 362 EFI_IP6_CONFIG_UNREGISTER_NOTIFY UnregisterDataNotify; 363 }; 364 365 extern EFI_GUID gEfiIp6ConfigProtocolGuid; 366 367 #endif 368 369