Subrata Banik | 20fe24b | 2021-12-09 02:46:38 +0530 | [diff] [blame] | 1 | /** @file |
| 2 | EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL as defined in UEFI 2.0. |
| 3 | EFI_MANAGED_NETWORK_PROTOCOL as defined in UEFI 2.0. |
| 4 | |
| 5 | Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> |
| 6 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 7 | |
| 8 | @par Revision Reference: |
| 9 | This Protocol is introduced in UEFI Specification 2.0 |
| 10 | |
| 11 | **/ |
| 12 | |
| 13 | #ifndef __EFI_MANAGED_NETWORK_PROTOCOL_H__ |
| 14 | #define __EFI_MANAGED_NETWORK_PROTOCOL_H__ |
| 15 | |
| 16 | #include <Protocol/SimpleNetwork.h> |
| 17 | |
| 18 | #define EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL_GUID \ |
| 19 | { \ |
| 20 | 0xf36ff770, 0xa7e1, 0x42cf, {0x9e, 0xd2, 0x56, 0xf0, 0xf2, 0x71, 0xf4, 0x4c } \ |
| 21 | } |
| 22 | |
| 23 | #define EFI_MANAGED_NETWORK_PROTOCOL_GUID \ |
| 24 | { \ |
| 25 | 0x7ab33a91, 0xace5, 0x4326, { 0xb5, 0x72, 0xe7, 0xee, 0x33, 0xd3, 0x9f, 0x16 } \ |
| 26 | } |
| 27 | |
| 28 | typedef struct _EFI_MANAGED_NETWORK_PROTOCOL EFI_MANAGED_NETWORK_PROTOCOL; |
| 29 | |
| 30 | typedef struct { |
| 31 | /// |
| 32 | /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed |
| 33 | /// from the MNP receive queue will be dropped if its receive timeout expires. |
| 34 | /// |
| 35 | UINT32 ReceivedQueueTimeoutValue; |
| 36 | /// |
| 37 | /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed |
| 38 | /// from the MNP transmit queue will be dropped if its receive timeout expires. |
| 39 | /// |
| 40 | UINT32 TransmitQueueTimeoutValue; |
| 41 | /// |
| 42 | /// Ethernet type II 16-bit protocol type in host byte order. Valid |
| 43 | /// values are zero and 1,500 to 65,535. |
| 44 | /// |
| 45 | UINT16 ProtocolTypeFilter; |
| 46 | /// |
| 47 | /// Set to TRUE to receive packets that are sent to the network |
| 48 | /// device MAC address. The startup default value is FALSE. |
| 49 | /// |
| 50 | BOOLEAN EnableUnicastReceive; |
| 51 | /// |
| 52 | /// Set to TRUE to receive packets that are sent to any of the |
| 53 | /// active multicast groups. The startup default value is FALSE. |
| 54 | /// |
| 55 | BOOLEAN EnableMulticastReceive; |
| 56 | /// |
| 57 | /// Set to TRUE to receive packets that are sent to the network |
| 58 | /// device broadcast address. The startup default value is FALSE. |
| 59 | /// |
| 60 | BOOLEAN EnableBroadcastReceive; |
| 61 | /// |
| 62 | /// Set to TRUE to receive packets that are sent to any MAC address. |
| 63 | /// The startup default value is FALSE. |
| 64 | /// |
| 65 | BOOLEAN EnablePromiscuousReceive; |
| 66 | /// |
| 67 | /// Set to TRUE to drop queued packets when the configuration |
| 68 | /// is changed. The startup default value is FALSE. |
| 69 | /// |
| 70 | BOOLEAN FlushQueuesOnReset; |
| 71 | /// |
| 72 | /// Set to TRUE to timestamp all packets when they are received |
| 73 | /// by the MNP. Note that timestamps may be unsupported in some |
| 74 | /// MNP implementations. The startup default value is FALSE. |
| 75 | /// |
| 76 | BOOLEAN EnableReceiveTimestamps; |
| 77 | /// |
| 78 | /// Set to TRUE to disable background polling in this MNP |
| 79 | /// instance. Note that background polling may not be supported in |
| 80 | /// all MNP implementations. The startup default value is FALSE, |
| 81 | /// unless background polling is not supported. |
| 82 | /// |
| 83 | BOOLEAN DisableBackgroundPolling; |
| 84 | } EFI_MANAGED_NETWORK_CONFIG_DATA; |
| 85 | |
| 86 | typedef struct { |
| 87 | EFI_TIME Timestamp; |
| 88 | EFI_EVENT RecycleEvent; |
| 89 | UINT32 PacketLength; |
| 90 | UINT32 HeaderLength; |
| 91 | UINT32 AddressLength; |
| 92 | UINT32 DataLength; |
| 93 | BOOLEAN BroadcastFlag; |
| 94 | BOOLEAN MulticastFlag; |
| 95 | BOOLEAN PromiscuousFlag; |
| 96 | UINT16 ProtocolType; |
| 97 | VOID *DestinationAddress; |
| 98 | VOID *SourceAddress; |
| 99 | VOID *MediaHeader; |
| 100 | VOID *PacketData; |
| 101 | } EFI_MANAGED_NETWORK_RECEIVE_DATA; |
| 102 | |
| 103 | typedef struct { |
| 104 | UINT32 FragmentLength; |
| 105 | VOID *FragmentBuffer; |
| 106 | } EFI_MANAGED_NETWORK_FRAGMENT_DATA; |
| 107 | |
| 108 | typedef struct { |
| 109 | EFI_MAC_ADDRESS *DestinationAddress; //OPTIONAL |
| 110 | EFI_MAC_ADDRESS *SourceAddress; //OPTIONAL |
| 111 | UINT16 ProtocolType; //OPTIONAL |
| 112 | UINT32 DataLength; |
| 113 | UINT16 HeaderLength; //OPTIONAL |
| 114 | UINT16 FragmentCount; |
| 115 | EFI_MANAGED_NETWORK_FRAGMENT_DATA FragmentTable[1]; |
| 116 | } EFI_MANAGED_NETWORK_TRANSMIT_DATA; |
| 117 | |
| 118 | |
| 119 | typedef struct { |
| 120 | /// |
| 121 | /// This Event will be signaled after the Status field is updated |
| 122 | /// by the MNP. The type of Event must be |
| 123 | /// EFI_NOTIFY_SIGNAL. The Task Priority Level (TPL) of |
| 124 | /// Event must be lower than or equal to TPL_CALLBACK. |
| 125 | /// |
| 126 | EFI_EVENT Event; |
| 127 | /// |
| 128 | /// The status that is returned to the caller at the end of the operation |
| 129 | /// to indicate whether this operation completed successfully. |
| 130 | /// |
| 131 | EFI_STATUS Status; |
| 132 | union { |
| 133 | /// |
| 134 | /// When this token is used for receiving, RxData is a pointer to the EFI_MANAGED_NETWORK_RECEIVE_DATA. |
| 135 | /// |
| 136 | EFI_MANAGED_NETWORK_RECEIVE_DATA *RxData; |
| 137 | /// |
| 138 | /// When this token is used for transmitting, TxData is a pointer to the EFI_MANAGED_NETWORK_TRANSMIT_DATA. |
| 139 | /// |
| 140 | EFI_MANAGED_NETWORK_TRANSMIT_DATA *TxData; |
| 141 | } Packet; |
| 142 | } EFI_MANAGED_NETWORK_COMPLETION_TOKEN; |
| 143 | |
| 144 | /** |
| 145 | Returns the operational parameters for the current MNP child driver. |
| 146 | |
| 147 | @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. |
| 148 | @param MnpConfigData The pointer to storage for MNP operational parameters. |
| 149 | @param SnpModeData The pointer to storage for SNP operational parameters. |
| 150 | |
| 151 | @retval EFI_SUCCESS The operation completed successfully. |
| 152 | @retval EFI_INVALID_PARAMETER This is NULL. |
| 153 | @retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP implementation. |
| 154 | @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. The default |
| 155 | values are returned in MnpConfigData if it is not NULL. |
| 156 | @retval Other The mode data could not be read. |
| 157 | |
| 158 | **/ |
| 159 | typedef |
| 160 | EFI_STATUS |
| 161 | (EFIAPI *EFI_MANAGED_NETWORK_GET_MODE_DATA)( |
| 162 | IN EFI_MANAGED_NETWORK_PROTOCOL *This, |
| 163 | OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL, |
| 164 | OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL |
| 165 | ); |
| 166 | |
| 167 | /** |
| 168 | Sets or clears the operational parameters for the MNP child driver. |
| 169 | |
| 170 | @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. |
| 171 | @param MnpConfigData The pointer to configuration data that will be assigned to the MNP |
| 172 | child driver instance. If NULL, the MNP child driver instance is |
| 173 | reset to startup defaults and all pending transmit and receive |
| 174 | requests are flushed. |
| 175 | |
| 176 | @retval EFI_SUCCESS The operation completed successfully. |
| 177 | @retval EFI_INVALID_PARAMETER One or more parameters are invalid. |
| 178 | @retval EFI_OUT_OF_RESOURCES Required system resources (usually memory) could not be |
| 179 | allocated. |
| 180 | @retval EFI_UNSUPPORTED The requested feature is unsupported in this [MNP] |
| 181 | implementation. |
| 182 | @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. |
| 183 | @retval Other The MNP child driver instance has been reset to startup defaults. |
| 184 | |
| 185 | **/ |
| 186 | typedef |
| 187 | EFI_STATUS |
| 188 | (EFIAPI *EFI_MANAGED_NETWORK_CONFIGURE)( |
| 189 | IN EFI_MANAGED_NETWORK_PROTOCOL *This, |
| 190 | IN EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL |
| 191 | ); |
| 192 | |
| 193 | /** |
| 194 | Translates an IP multicast address to a hardware (MAC) multicast address. |
| 195 | |
| 196 | @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. |
| 197 | @param Ipv6Flag Set to TRUE to if IpAddress is an IPv6 multicast address. |
| 198 | Set to FALSE if IpAddress is an IPv4 multicast address. |
| 199 | @param IpAddress The pointer to the multicast IP address (in network byte order) to convert. |
| 200 | @param MacAddress The pointer to the resulting multicast MAC address. |
| 201 | |
| 202 | @retval EFI_SUCCESS The operation completed successfully. |
| 203 | @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE: |
| 204 | - This is NULL. |
| 205 | - IpAddress is NULL. |
| 206 | - *IpAddress is not a valid multicast IP address. |
| 207 | - MacAddress is NULL. |
| 208 | @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. |
| 209 | @retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP implementation. |
| 210 | @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. |
| 211 | @retval Other The address could not be converted. |
| 212 | |
| 213 | **/ |
| 214 | typedef |
| 215 | EFI_STATUS |
| 216 | (EFIAPI *EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC)( |
| 217 | IN EFI_MANAGED_NETWORK_PROTOCOL *This, |
| 218 | IN BOOLEAN Ipv6Flag, |
| 219 | IN EFI_IP_ADDRESS *IpAddress, |
| 220 | OUT EFI_MAC_ADDRESS *MacAddress |
| 221 | ); |
| 222 | |
| 223 | /** |
| 224 | Enables and disables receive filters for multicast address. |
| 225 | |
| 226 | @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. |
| 227 | @param JoinFlag Set to TRUE to join this multicast group. |
| 228 | Set to FALSE to leave this multicast group. |
| 229 | @param MacAddress The pointer to the multicast MAC group (address) to join or leave. |
| 230 | |
| 231 | @retval EFI_SUCCESS The requested operation completed successfully. |
| 232 | @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: |
| 233 | - This is NULL. |
| 234 | - JoinFlag is TRUE and MacAddress is NULL. |
| 235 | - *MacAddress is not a valid multicast MAC address. |
| 236 | @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. |
| 237 | @retval EFI_ALREADY_STARTED The supplied multicast group is already joined. |
| 238 | @retval EFI_NOT_FOUND The supplied multicast group is not joined. |
| 239 | @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. |
| 240 | @retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP implementation. |
| 241 | @retval Other The requested operation could not be completed. |
| 242 | |
| 243 | **/ |
| 244 | typedef |
| 245 | EFI_STATUS |
| 246 | (EFIAPI *EFI_MANAGED_NETWORK_GROUPS)( |
| 247 | IN EFI_MANAGED_NETWORK_PROTOCOL *This, |
| 248 | IN BOOLEAN JoinFlag, |
| 249 | IN EFI_MAC_ADDRESS *MacAddress OPTIONAL |
| 250 | ); |
| 251 | |
| 252 | /** |
| 253 | Places asynchronous outgoing data packets into the transmit queue. |
| 254 | |
| 255 | @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. |
| 256 | @param Token The pointer to a token associated with the transmit data descriptor. |
| 257 | |
| 258 | @retval EFI_SUCCESS The transmit completion token was cached. |
| 259 | @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. |
| 260 | @retval EFI_INVALID_PARAMETER One or more parameters are invalid. |
| 261 | @retval EFI_ACCESS_DENIED The transmit completion token is already in the transmit queue. |
| 262 | @retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a lack of system resources |
| 263 | (usually memory). |
| 264 | @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. |
| 265 | @retval EFI_NOT_READY The transmit request could not be queued because the transmit queue is full. |
| 266 | |
| 267 | **/ |
| 268 | typedef |
| 269 | EFI_STATUS |
| 270 | (EFIAPI *EFI_MANAGED_NETWORK_TRANSMIT)( |
| 271 | IN EFI_MANAGED_NETWORK_PROTOCOL *This, |
| 272 | IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token |
| 273 | ); |
| 274 | |
| 275 | /** |
| 276 | Places an asynchronous receiving request into the receiving queue. |
| 277 | |
| 278 | @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. |
| 279 | @param Token The pointer to a token associated with the receive data descriptor. |
| 280 | |
| 281 | @retval EFI_SUCCESS The receive completion token was cached. |
| 282 | @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. |
| 283 | @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: |
| 284 | - This is NULL. |
| 285 | - Token is NULL. |
| 286 | - Token.Event is NULL. |
| 287 | @retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a lack of system resources |
| 288 | (usually memory). |
| 289 | @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. |
| 290 | @retval EFI_ACCESS_DENIED The receive completion token was already in the receive queue. |
| 291 | @retval EFI_NOT_READY The receive request could not be queued because the receive queue is full. |
| 292 | |
| 293 | **/ |
| 294 | typedef |
| 295 | EFI_STATUS |
| 296 | (EFIAPI *EFI_MANAGED_NETWORK_RECEIVE)( |
| 297 | IN EFI_MANAGED_NETWORK_PROTOCOL *This, |
| 298 | IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token |
| 299 | ); |
| 300 | |
| 301 | |
| 302 | /** |
| 303 | Aborts an asynchronous transmit or receive request. |
| 304 | |
| 305 | @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. |
| 306 | @param Token The pointer to a token that has been issued by |
| 307 | EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or |
| 308 | EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If |
| 309 | NULL, all pending tokens are aborted. |
| 310 | |
| 311 | @retval EFI_SUCCESS The asynchronous I/O request was aborted and Token.Event |
| 312 | was signaled. When Token is NULL, all pending requests were |
| 313 | aborted and their events were signaled. |
| 314 | @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. |
| 315 | @retval EFI_INVALID_PARAMETER This is NULL. |
| 316 | @retval EFI_NOT_FOUND When Token is not NULL, the asynchronous I/O request was |
| 317 | not found in the transmit or receive queue. It has either completed |
| 318 | or was not issued by Transmit() and Receive(). |
| 319 | |
| 320 | **/ |
| 321 | typedef |
| 322 | EFI_STATUS |
| 323 | (EFIAPI *EFI_MANAGED_NETWORK_CANCEL)( |
| 324 | IN EFI_MANAGED_NETWORK_PROTOCOL *This, |
| 325 | IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token OPTIONAL |
| 326 | ); |
| 327 | |
| 328 | /** |
| 329 | Polls for incoming data packets and processes outgoing data packets. |
| 330 | |
| 331 | @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance. |
| 332 | |
| 333 | @retval EFI_SUCCESS Incoming or outgoing data was processed. |
| 334 | @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. |
| 335 | @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. |
| 336 | @retval EFI_NOT_READY No incoming or outgoing data was processed. Consider increasing |
| 337 | the polling rate. |
| 338 | @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue. |
| 339 | Consider increasing the polling rate. |
| 340 | |
| 341 | **/ |
| 342 | typedef |
| 343 | EFI_STATUS |
| 344 | (EFIAPI *EFI_MANAGED_NETWORK_POLL)( |
| 345 | IN EFI_MANAGED_NETWORK_PROTOCOL *This |
| 346 | ); |
| 347 | |
| 348 | /// |
| 349 | /// The MNP is used by network applications (and drivers) to |
| 350 | /// perform raw (unformatted) asynchronous network packet I/O. |
| 351 | /// |
| 352 | struct _EFI_MANAGED_NETWORK_PROTOCOL { |
| 353 | EFI_MANAGED_NETWORK_GET_MODE_DATA GetModeData; |
| 354 | EFI_MANAGED_NETWORK_CONFIGURE Configure; |
| 355 | EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC McastIpToMac; |
| 356 | EFI_MANAGED_NETWORK_GROUPS Groups; |
| 357 | EFI_MANAGED_NETWORK_TRANSMIT Transmit; |
| 358 | EFI_MANAGED_NETWORK_RECEIVE Receive; |
| 359 | EFI_MANAGED_NETWORK_CANCEL Cancel; |
| 360 | EFI_MANAGED_NETWORK_POLL Poll; |
| 361 | }; |
| 362 | |
| 363 | extern EFI_GUID gEfiManagedNetworkServiceBindingProtocolGuid; |
| 364 | extern EFI_GUID gEfiManagedNetworkProtocolGuid; |
| 365 | |
| 366 | #endif |