1*f334afcfSToomas Soome /** @file 2*f334afcfSToomas Soome The EFI UDPv6 (User Datagram Protocol version 6) Protocol Definition, which is built upon 3*f334afcfSToomas Soome the EFI IPv6 Protocol and provides simple packet-oriented services to transmit and receive 4*f334afcfSToomas Soome UDP packets. 5*f334afcfSToomas Soome 6*f334afcfSToomas Soome Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR> 7*f334afcfSToomas Soome SPDX-License-Identifier: BSD-2-Clause-Patent 8*f334afcfSToomas Soome 9*f334afcfSToomas Soome @par Revision Reference: 10*f334afcfSToomas Soome This Protocol is introduced in UEFI Specification 2.2 11*f334afcfSToomas Soome 12*f334afcfSToomas Soome **/ 13*f334afcfSToomas Soome 14*f334afcfSToomas Soome #ifndef __EFI_UDP6_PROTOCOL_H__ 15*f334afcfSToomas Soome #define __EFI_UDP6_PROTOCOL_H__ 16*f334afcfSToomas Soome 17*f334afcfSToomas Soome #include <Protocol/Ip6.h> 18*f334afcfSToomas Soome 19*f334afcfSToomas Soome #define EFI_UDP6_SERVICE_BINDING_PROTOCOL_GUID \ 20*f334afcfSToomas Soome { \ 21*f334afcfSToomas Soome 0x66ed4721, 0x3c98, 0x4d3e, {0x81, 0xe3, 0xd0, 0x3d, 0xd3, 0x9a, 0x72, 0x54 } \ 22*f334afcfSToomas Soome } 23*f334afcfSToomas Soome 24*f334afcfSToomas Soome #define EFI_UDP6_PROTOCOL_GUID \ 25*f334afcfSToomas Soome { \ 26*f334afcfSToomas Soome 0x4f948815, 0xb4b9, 0x43cb, {0x8a, 0x33, 0x90, 0xe0, 0x60, 0xb3, 0x49, 0x55 } \ 27*f334afcfSToomas Soome } 28*f334afcfSToomas Soome 29*f334afcfSToomas Soome /// 30*f334afcfSToomas Soome /// EFI_UDP6_SERVICE_POINT is deprecated in the UEFI 2.4B and should not be used any more. 31*f334afcfSToomas Soome /// The definition in here is only present to provide backwards compatability. 32*f334afcfSToomas Soome /// 33*f334afcfSToomas Soome typedef struct { 34*f334afcfSToomas Soome /// 35*f334afcfSToomas Soome /// The EFI UDPv6 Protocol instance handle that is using this address/port pair. 36*f334afcfSToomas Soome /// 37*f334afcfSToomas Soome EFI_HANDLE InstanceHandle; 38*f334afcfSToomas Soome /// 39*f334afcfSToomas Soome /// The IPv6 address to which this instance of the EFI UDPv6 Protocol is bound. 40*f334afcfSToomas Soome /// Set to 0::/128, if this instance is used to listen all packets from any 41*f334afcfSToomas Soome /// source address. 42*f334afcfSToomas Soome /// 43*f334afcfSToomas Soome EFI_IPv6_ADDRESS LocalAddress; 44*f334afcfSToomas Soome /// 45*f334afcfSToomas Soome /// The port number in host byte order on which the service is listening. 46*f334afcfSToomas Soome /// 47*f334afcfSToomas Soome UINT16 LocalPort; 48*f334afcfSToomas Soome /// 49*f334afcfSToomas Soome /// The IPv6 address of the remote host. May be 0::/128 if it is not connected 50*f334afcfSToomas Soome /// to any remote host or connected with more than one remote host. 51*f334afcfSToomas Soome /// 52*f334afcfSToomas Soome EFI_IPv6_ADDRESS RemoteAddress; 53*f334afcfSToomas Soome /// 54*f334afcfSToomas Soome /// The port number in host byte order on which the remote host is 55*f334afcfSToomas Soome /// listening. Maybe zero if it is not connected to any remote host. 56*f334afcfSToomas Soome /// 57*f334afcfSToomas Soome UINT16 RemotePort; 58*f334afcfSToomas Soome } EFI_UDP6_SERVICE_POINT; 59*f334afcfSToomas Soome 60*f334afcfSToomas Soome /// 61*f334afcfSToomas Soome /// EFI_UDP6_VARIABLE_DATA is deprecated in the UEFI 2.4B and should not be used any more. 62*f334afcfSToomas Soome /// The definition in here is only present to provide backwards compatability. 63*f334afcfSToomas Soome /// 64*f334afcfSToomas Soome typedef struct { 65*f334afcfSToomas Soome /// 66*f334afcfSToomas Soome /// The handle of the driver that creates this entry. 67*f334afcfSToomas Soome /// 68*f334afcfSToomas Soome EFI_HANDLE DriverHandle; 69*f334afcfSToomas Soome /// 70*f334afcfSToomas Soome /// The number of address/port pairs that follow this data structure. 71*f334afcfSToomas Soome /// 72*f334afcfSToomas Soome UINT32 ServiceCount; 73*f334afcfSToomas Soome /// 74*f334afcfSToomas Soome /// List of address/port pairs that are currently in use. 75*f334afcfSToomas Soome /// 76*f334afcfSToomas Soome EFI_UDP6_SERVICE_POINT Services[1]; 77*f334afcfSToomas Soome } EFI_UDP6_VARIABLE_DATA; 78*f334afcfSToomas Soome 79*f334afcfSToomas Soome typedef struct _EFI_UDP6_PROTOCOL EFI_UDP6_PROTOCOL; 80*f334afcfSToomas Soome 81*f334afcfSToomas Soome /// 82*f334afcfSToomas Soome /// EFI_UDP6_FRAGMENT_DATA allows multiple receive or transmit buffers to be specified. 83*f334afcfSToomas Soome /// The purpose of this structure is to avoid copying the same packet multiple times. 84*f334afcfSToomas Soome /// 85*f334afcfSToomas Soome typedef struct { 86*f334afcfSToomas Soome UINT32 FragmentLength; ///< Length of the fragment data buffer. 87*f334afcfSToomas Soome VOID *FragmentBuffer; ///< Pointer to the fragment data buffer. 88*f334afcfSToomas Soome } EFI_UDP6_FRAGMENT_DATA; 89*f334afcfSToomas Soome 90*f334afcfSToomas Soome /// 91*f334afcfSToomas Soome /// The EFI_UDP6_SESSION_DATA is used to retrieve the settings when receiving packets or 92*f334afcfSToomas Soome /// to override the existing settings (only DestinationAddress and DestinationPort can 93*f334afcfSToomas Soome /// be overridden) of this EFI UDPv6 Protocol instance when sending packets. 94*f334afcfSToomas Soome /// 95*f334afcfSToomas Soome typedef struct { 96*f334afcfSToomas Soome /// 97*f334afcfSToomas Soome /// Address from which this packet is sent. This field should not be used when 98*f334afcfSToomas Soome /// sending packets. 99*f334afcfSToomas Soome /// 100*f334afcfSToomas Soome EFI_IPv6_ADDRESS SourceAddress; 101*f334afcfSToomas Soome /// 102*f334afcfSToomas Soome /// Port from which this packet is sent. It is in host byte order. This field should 103*f334afcfSToomas Soome /// not be used when sending packets. 104*f334afcfSToomas Soome /// 105*f334afcfSToomas Soome UINT16 SourcePort; 106*f334afcfSToomas Soome /// 107*f334afcfSToomas Soome /// Address to which this packet is sent. When sending packet, it'll be ignored 108*f334afcfSToomas Soome /// if it is zero. 109*f334afcfSToomas Soome /// 110*f334afcfSToomas Soome EFI_IPv6_ADDRESS DestinationAddress; 111*f334afcfSToomas Soome /// 112*f334afcfSToomas Soome /// Port to which this packet is sent. When sending packet, it'll be 113*f334afcfSToomas Soome /// ignored if it is zero. 114*f334afcfSToomas Soome /// 115*f334afcfSToomas Soome UINT16 DestinationPort; 116*f334afcfSToomas Soome } EFI_UDP6_SESSION_DATA; 117*f334afcfSToomas Soome 118*f334afcfSToomas Soome typedef struct { 119*f334afcfSToomas Soome /// 120*f334afcfSToomas Soome /// Set to TRUE to accept UDP packets that are sent to any address. 121*f334afcfSToomas Soome /// 122*f334afcfSToomas Soome BOOLEAN AcceptPromiscuous; 123*f334afcfSToomas Soome /// 124*f334afcfSToomas Soome /// Set to TRUE to accept UDP packets that are sent to any port. 125*f334afcfSToomas Soome /// 126*f334afcfSToomas Soome BOOLEAN AcceptAnyPort; 127*f334afcfSToomas Soome /// 128*f334afcfSToomas Soome /// Set to TRUE to allow this EFI UDPv6 Protocol child instance to open a port number 129*f334afcfSToomas Soome /// that is already being used by another EFI UDPv6 Protocol child instance. 130*f334afcfSToomas Soome /// 131*f334afcfSToomas Soome BOOLEAN AllowDuplicatePort; 132*f334afcfSToomas Soome /// 133*f334afcfSToomas Soome /// TrafficClass field in transmitted IPv6 packets. 134*f334afcfSToomas Soome /// 135*f334afcfSToomas Soome UINT8 TrafficClass; 136*f334afcfSToomas Soome /// 137*f334afcfSToomas Soome /// HopLimit field in transmitted IPv6 packets. 138*f334afcfSToomas Soome /// 139*f334afcfSToomas Soome UINT8 HopLimit; 140*f334afcfSToomas Soome /// 141*f334afcfSToomas Soome /// The receive timeout value (number of microseconds) to be associated with each 142*f334afcfSToomas Soome /// incoming packet. Zero means do not drop incoming packets. 143*f334afcfSToomas Soome /// 144*f334afcfSToomas Soome UINT32 ReceiveTimeout; 145*f334afcfSToomas Soome /// 146*f334afcfSToomas Soome /// The transmit timeout value (number of microseconds) to be associated with each 147*f334afcfSToomas Soome /// outgoing packet. Zero means do not drop outgoing packets. 148*f334afcfSToomas Soome /// 149*f334afcfSToomas Soome UINT32 TransmitTimeout; 150*f334afcfSToomas Soome /// 151*f334afcfSToomas Soome /// The station IP address that will be assigned to this EFI UDPv6 Protocol instance. 152*f334afcfSToomas Soome /// The EFI UDPv6 and EFI IPv6 Protocol drivers will only deliver incoming packets 153*f334afcfSToomas Soome /// whose destination matches this IP address exactly. Address 0::/128 is also accepted 154*f334afcfSToomas Soome /// as a special case. Under this situation, underlying IPv6 driver is responsible for 155*f334afcfSToomas Soome /// binding a source address to this EFI IPv6 protocol instance according to source 156*f334afcfSToomas Soome /// address selection algorithm. Only incoming packet from the selected source address 157*f334afcfSToomas Soome /// is delivered. This field can be set and changed only when the EFI IPv6 driver is 158*f334afcfSToomas Soome /// transitioning from the stopped to the started states. If no address is available 159*f334afcfSToomas Soome /// for selecting, the EFI IPv6 Protocol driver will use EFI_IP6_CONFIG_PROTOCOL to 160*f334afcfSToomas Soome /// retrieve the IPv6 address. 161*f334afcfSToomas Soome EFI_IPv6_ADDRESS StationAddress; 162*f334afcfSToomas Soome /// 163*f334afcfSToomas Soome /// The port number to which this EFI UDPv6 Protocol instance is bound. If a client 164*f334afcfSToomas Soome /// of the EFI UDPv6 Protocol does not care about the port number, set StationPort 165*f334afcfSToomas Soome /// to zero. The EFI UDPv6 Protocol driver will assign a random port number to transmitted 166*f334afcfSToomas Soome /// UDP packets. Ignored it if AcceptAnyPort is TRUE. 167*f334afcfSToomas Soome /// 168*f334afcfSToomas Soome UINT16 StationPort; 169*f334afcfSToomas Soome /// 170*f334afcfSToomas Soome /// The IP address of remote host to which this EFI UDPv6 Protocol instance is connecting. 171*f334afcfSToomas Soome /// If RemoteAddress is not 0::/128, this EFI UDPv6 Protocol instance will be connected to 172*f334afcfSToomas Soome /// RemoteAddress; i.e., outgoing packets of this EFI UDPv6 Protocol instance will be sent 173*f334afcfSToomas Soome /// to this address by default and only incoming packets from this address will be delivered 174*f334afcfSToomas Soome /// to client. Ignored for incoming filtering if AcceptPromiscuous is TRUE. 175*f334afcfSToomas Soome EFI_IPv6_ADDRESS RemoteAddress; 176*f334afcfSToomas Soome /// 177*f334afcfSToomas Soome /// The port number of the remote host to which this EFI UDPv6 Protocol instance is connecting. 178*f334afcfSToomas Soome /// If it is not zero, outgoing packets of this EFI UDPv6 Protocol instance will be sent to 179*f334afcfSToomas Soome /// this port number by default and only incoming packets from this port will be delivered 180*f334afcfSToomas Soome /// to client. Ignored if RemoteAddress is 0::/128 and ignored for incoming filtering if 181*f334afcfSToomas Soome /// AcceptPromiscuous is TRUE. 182*f334afcfSToomas Soome UINT16 RemotePort; 183*f334afcfSToomas Soome } EFI_UDP6_CONFIG_DATA; 184*f334afcfSToomas Soome 185*f334afcfSToomas Soome /// 186*f334afcfSToomas Soome /// The EFI UDPv6 Protocol client must fill this data structure before sending a packet. 187*f334afcfSToomas Soome /// The packet may contain multiple buffers that may be not in a continuous memory location. 188*f334afcfSToomas Soome /// 189*f334afcfSToomas Soome typedef struct { 190*f334afcfSToomas Soome /// 191*f334afcfSToomas Soome /// If not NULL, the data that is used to override the transmitting settings.Only the two 192*f334afcfSToomas Soome /// filed UdpSessionData.DestinationAddress and UdpSessionData.DestionPort can be used as 193*f334afcfSToomas Soome /// the transmitting setting filed. 194*f334afcfSToomas Soome /// 195*f334afcfSToomas Soome EFI_UDP6_SESSION_DATA *UdpSessionData; 196*f334afcfSToomas Soome /// 197*f334afcfSToomas Soome /// Sum of the fragment data length. Must not exceed the maximum UDP packet size. 198*f334afcfSToomas Soome /// 199*f334afcfSToomas Soome UINT32 DataLength; 200*f334afcfSToomas Soome /// 201*f334afcfSToomas Soome /// Number of fragments. 202*f334afcfSToomas Soome /// 203*f334afcfSToomas Soome UINT32 FragmentCount; 204*f334afcfSToomas Soome /// 205*f334afcfSToomas Soome /// Array of fragment descriptors. 206*f334afcfSToomas Soome /// 207*f334afcfSToomas Soome EFI_UDP6_FRAGMENT_DATA FragmentTable[1]; 208*f334afcfSToomas Soome } EFI_UDP6_TRANSMIT_DATA; 209*f334afcfSToomas Soome 210*f334afcfSToomas Soome /// 211*f334afcfSToomas Soome /// EFI_UDP6_RECEIVE_DATA is filled by the EFI UDPv6 Protocol driver when this EFI UDPv6 212*f334afcfSToomas Soome /// Protocol instance receives an incoming packet. If there is a waiting token for incoming 213*f334afcfSToomas Soome /// packets, the CompletionToken.Packet.RxData field is updated to this incoming packet and 214*f334afcfSToomas Soome /// the CompletionToken.Event is signaled. The EFI UDPv6 Protocol client must signal the 215*f334afcfSToomas Soome /// RecycleSignal after processing the packet. 216*f334afcfSToomas Soome /// FragmentTable could contain multiple buffers that are not in the continuous memory locations. 217*f334afcfSToomas Soome /// The EFI UDPv6 Protocol client might need to combine two or more buffers in FragmentTable to 218*f334afcfSToomas Soome /// form their own protocol header. 219*f334afcfSToomas Soome /// 220*f334afcfSToomas Soome typedef struct { 221*f334afcfSToomas Soome /// 222*f334afcfSToomas Soome /// Time when the EFI UDPv6 Protocol accepted the packet. 223*f334afcfSToomas Soome /// 224*f334afcfSToomas Soome EFI_TIME TimeStamp; 225*f334afcfSToomas Soome /// 226*f334afcfSToomas Soome /// Indicates the event to signal when the received data has been processed. 227*f334afcfSToomas Soome /// 228*f334afcfSToomas Soome EFI_EVENT RecycleSignal; 229*f334afcfSToomas Soome /// 230*f334afcfSToomas Soome /// The UDP session data including SourceAddress, SourcePort, DestinationAddress, 231*f334afcfSToomas Soome /// and DestinationPort. 232*f334afcfSToomas Soome /// 233*f334afcfSToomas Soome EFI_UDP6_SESSION_DATA UdpSession; 234*f334afcfSToomas Soome /// 235*f334afcfSToomas Soome /// The sum of the fragment data length. 236*f334afcfSToomas Soome /// 237*f334afcfSToomas Soome UINT32 DataLength; 238*f334afcfSToomas Soome /// 239*f334afcfSToomas Soome /// Number of fragments. Maybe zero. 240*f334afcfSToomas Soome /// 241*f334afcfSToomas Soome UINT32 FragmentCount; 242*f334afcfSToomas Soome /// 243*f334afcfSToomas Soome /// Array of fragment descriptors. Maybe zero. 244*f334afcfSToomas Soome /// 245*f334afcfSToomas Soome EFI_UDP6_FRAGMENT_DATA FragmentTable[1]; 246*f334afcfSToomas Soome } EFI_UDP6_RECEIVE_DATA; 247*f334afcfSToomas Soome 248*f334afcfSToomas Soome /// 249*f334afcfSToomas Soome /// The EFI_UDP6_COMPLETION_TOKEN structures are used for both transmit and receive operations. 250*f334afcfSToomas Soome /// When used for transmitting, the Event and TxData fields must be filled in by the EFI UDPv6 251*f334afcfSToomas Soome /// Protocol client. After the transmit operation completes, the Status field is updated by the 252*f334afcfSToomas Soome /// EFI UDPv6 Protocol and the Event is signaled. 253*f334afcfSToomas Soome /// When used for receiving, only the Event field must be filled in by the EFI UDPv6 Protocol 254*f334afcfSToomas Soome /// client. After a packet is received, RxData and Status are filled in by the EFI UDPv6 Protocol 255*f334afcfSToomas Soome /// and the Event is signaled. 256*f334afcfSToomas Soome /// 257*f334afcfSToomas Soome typedef struct { 258*f334afcfSToomas Soome /// 259*f334afcfSToomas Soome /// This Event will be signaled after the Status field is updated by the EFI UDPv6 Protocol 260*f334afcfSToomas Soome /// driver. The type of Event must be EVT_NOTIFY_SIGNAL. 261*f334afcfSToomas Soome /// 262*f334afcfSToomas Soome EFI_EVENT Event; 263*f334afcfSToomas Soome /// 264*f334afcfSToomas Soome /// Will be set to one of the following values: 265*f334afcfSToomas Soome /// - EFI_SUCCESS: The receive or transmit operation completed successfully. 266*f334afcfSToomas Soome /// - EFI_ABORTED: The receive or transmit was aborted. 267*f334afcfSToomas Soome /// - EFI_TIMEOUT: The transmit timeout expired. 268*f334afcfSToomas Soome /// - EFI_NETWORK_UNREACHABLE: The destination network is unreachable. RxData is set to 269*f334afcfSToomas Soome /// NULL in this situation. 270*f334afcfSToomas Soome /// - EFI_HOST_UNREACHABLE: The destination host is unreachable. RxData is set to NULL in 271*f334afcfSToomas Soome /// this situation. 272*f334afcfSToomas Soome /// - EFI_PROTOCOL_UNREACHABLE: The UDP protocol is unsupported in the remote system. 273*f334afcfSToomas Soome /// RxData is set to NULL in this situation. 274*f334afcfSToomas Soome /// - EFI_PORT_UNREACHABLE: No service is listening on the remote port. RxData is set to 275*f334afcfSToomas Soome /// NULL in this situation. 276*f334afcfSToomas Soome /// - EFI_ICMP_ERROR: Some other Internet Control Message Protocol (ICMP) error report was 277*f334afcfSToomas Soome /// received. For example, packets are being sent too fast for the destination to receive them 278*f334afcfSToomas Soome /// and the destination sent an ICMP source quench report. RxData is set to NULL in this situation. 279*f334afcfSToomas Soome /// - EFI_DEVICE_ERROR: An unexpected system or network error occurred. 280*f334afcfSToomas Soome /// - EFI_SECURITY_VIOLATION: The transmit or receive was failed because of IPsec policy check. 281*f334afcfSToomas Soome /// - EFI_NO_MEDIA: There was a media error. 282*f334afcfSToomas Soome /// 283*f334afcfSToomas Soome EFI_STATUS Status; 284*f334afcfSToomas Soome union { 285*f334afcfSToomas Soome /// 286*f334afcfSToomas Soome /// When this token is used for receiving, RxData is a pointer to EFI_UDP6_RECEIVE_DATA. 287*f334afcfSToomas Soome /// 288*f334afcfSToomas Soome EFI_UDP6_RECEIVE_DATA *RxData; 289*f334afcfSToomas Soome /// 290*f334afcfSToomas Soome /// When this token is used for transmitting, TxData is a pointer to EFI_UDP6_TRANSMIT_DATA. 291*f334afcfSToomas Soome /// 292*f334afcfSToomas Soome EFI_UDP6_TRANSMIT_DATA *TxData; 293*f334afcfSToomas Soome } Packet; 294*f334afcfSToomas Soome } EFI_UDP6_COMPLETION_TOKEN; 295*f334afcfSToomas Soome 296*f334afcfSToomas Soome /** 297*f334afcfSToomas Soome Read the current operational settings. 298*f334afcfSToomas Soome 299*f334afcfSToomas Soome The GetModeData() function copies the current operational settings of this EFI UDPv6 Protocol 300*f334afcfSToomas Soome instance into user-supplied buffers. This function is used optionally to retrieve the operational 301*f334afcfSToomas Soome mode data of underlying networks or drivers. 302*f334afcfSToomas Soome 303*f334afcfSToomas Soome @param[in] This Pointer to the EFI_UDP6_PROTOCOL instance. 304*f334afcfSToomas Soome @param[out] Udp6ConfigData The buffer in which the current UDP configuration data is returned. 305*f334afcfSToomas Soome @param[out] Ip6ModeData The buffer in which the current EFI IPv6 Protocol mode data is returned. 306*f334afcfSToomas Soome @param[out] MnpConfigData The buffer in which the current managed network configuration data is 307*f334afcfSToomas Soome returned. 308*f334afcfSToomas Soome @param[out] SnpModeData The buffer in which the simple network mode data is returned. 309*f334afcfSToomas Soome 310*f334afcfSToomas Soome @retval EFI_SUCCESS The mode data was read. 311*f334afcfSToomas Soome @retval EFI_NOT_STARTED When Udp6ConfigData is queried, no configuration data is available 312*f334afcfSToomas Soome because this instance has not been started. 313*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER This is NULL. 314*f334afcfSToomas Soome 315*f334afcfSToomas Soome **/ 316*f334afcfSToomas Soome typedef 317*f334afcfSToomas Soome EFI_STATUS 318*f334afcfSToomas Soome (EFIAPI *EFI_UDP6_GET_MODE_DATA)( 319*f334afcfSToomas Soome IN EFI_UDP6_PROTOCOL *This, 320*f334afcfSToomas Soome OUT EFI_UDP6_CONFIG_DATA *Udp6ConfigData OPTIONAL, 321*f334afcfSToomas Soome OUT EFI_IP6_MODE_DATA *Ip6ModeData OPTIONAL, 322*f334afcfSToomas Soome OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL, 323*f334afcfSToomas Soome OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL 324*f334afcfSToomas Soome ); 325*f334afcfSToomas Soome 326*f334afcfSToomas Soome /** 327*f334afcfSToomas Soome Initializes, changes, or resets the operational parameters for this instance of the EFI UDPv6 328*f334afcfSToomas Soome Protocol. 329*f334afcfSToomas Soome 330*f334afcfSToomas Soome The Configure() function is used to do the following: 331*f334afcfSToomas Soome - Initialize and start this instance of the EFI UDPv6 Protocol. 332*f334afcfSToomas Soome - Change the filtering rules and operational parameters. 333*f334afcfSToomas Soome - Reset this instance of the EFI UDPv6 Protocol. 334*f334afcfSToomas Soome 335*f334afcfSToomas Soome Until these parameters are initialized, no network traffic can be sent or received by this instance. 336*f334afcfSToomas Soome This instance can be also reset by calling Configure() with UdpConfigData set to NULL. 337*f334afcfSToomas Soome Once reset, the receiving queue and transmitting queue are flushed and no traffic is allowed through 338*f334afcfSToomas Soome this instance. 339*f334afcfSToomas Soome 340*f334afcfSToomas Soome With different parameters in UdpConfigData, Configure() can be used to bind this instance to specified 341*f334afcfSToomas Soome port. 342*f334afcfSToomas Soome 343*f334afcfSToomas Soome @param[in] This Pointer to the EFI_UDP6_PROTOCOL instance. 344*f334afcfSToomas Soome @param[in] UdpConfigData Pointer to the buffer contained the configuration data. 345*f334afcfSToomas Soome 346*f334afcfSToomas Soome @retval EFI_SUCCESS The configuration settings were set, changed, or reset successfully. 347*f334afcfSToomas Soome @retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source 348*f334afcfSToomas Soome address for this instance, but no source address was available for use. 349*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE: 350*f334afcfSToomas Soome - This is NULL. 351*f334afcfSToomas Soome - UdpConfigData.StationAddress neither zero nor one of the configured IP 352*f334afcfSToomas Soome addresses in the underlying IPv6 driver. 353*f334afcfSToomas Soome - UdpConfigData.RemoteAddress is not a valid unicast IPv6 address if it 354*f334afcfSToomas Soome is not zero. 355*f334afcfSToomas Soome @retval EFI_ALREADY_STARTED The EFI UDPv6 Protocol instance is already started/configured and must be 356*f334afcfSToomas Soome stopped/reset before it can be reconfigured. Only TrafficClass, HopLimit, 357*f334afcfSToomas Soome ReceiveTimeout, and TransmitTimeout can be reconfigured without stopping 358*f334afcfSToomas Soome the current instance of the EFI UDPv6 Protocol. 359*f334afcfSToomas Soome @retval EFI_ACCESS_DENIED UdpConfigData.AllowDuplicatePort is FALSE and UdpConfigData.StationPort 360*f334afcfSToomas Soome is already used by other instance. 361*f334afcfSToomas Soome @retval EFI_OUT_OF_RESOURCES The EFI UDPv6 Protocol driver cannot allocate memory for this EFI UDPv6 362*f334afcfSToomas Soome Protocol instance. 363*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR An unexpected network or system error occurred and this instance was not 364*f334afcfSToomas Soome opened. 365*f334afcfSToomas Soome 366*f334afcfSToomas Soome **/ 367*f334afcfSToomas Soome typedef 368*f334afcfSToomas Soome EFI_STATUS 369*f334afcfSToomas Soome (EFIAPI *EFI_UDP6_CONFIGURE)( 370*f334afcfSToomas Soome IN EFI_UDP6_PROTOCOL *This, 371*f334afcfSToomas Soome IN EFI_UDP6_CONFIG_DATA *UdpConfigData OPTIONAL 372*f334afcfSToomas Soome ); 373*f334afcfSToomas Soome 374*f334afcfSToomas Soome /** 375*f334afcfSToomas Soome Joins and leaves multicast groups. 376*f334afcfSToomas Soome 377*f334afcfSToomas Soome The Groups() function is used to join or leave one or more multicast group. 378*f334afcfSToomas Soome If the JoinFlag is FALSE and the MulticastAddress is NULL, then all currently joined groups are left. 379*f334afcfSToomas Soome 380*f334afcfSToomas Soome @param[in] This Pointer to the EFI_UDP6_PROTOCOL instance. 381*f334afcfSToomas Soome @param[in] JoinFlag Set to TRUE to join a multicast group. Set to FALSE to leave one 382*f334afcfSToomas Soome or all multicast groups. 383*f334afcfSToomas Soome @param[in] MulticastAddress Pointer to multicast group address to join or leave. 384*f334afcfSToomas Soome 385*f334afcfSToomas Soome @retval EFI_SUCCESS The operation completed successfully. 386*f334afcfSToomas Soome @retval EFI_NOT_STARTED The EFI UDPv6 Protocol instance has not been started. 387*f334afcfSToomas Soome @retval EFI_OUT_OF_RESOURCES Could not allocate resources to join the group. 388*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: 389*f334afcfSToomas Soome - This is NULL. 390*f334afcfSToomas Soome - JoinFlag is TRUE and MulticastAddress is NULL. 391*f334afcfSToomas Soome - JoinFlag is TRUE and *MulticastAddress is not a valid multicast address. 392*f334afcfSToomas Soome @retval EFI_ALREADY_STARTED The group address is already in the group table (when JoinFlag is TRUE). 393*f334afcfSToomas Soome @retval EFI_NOT_FOUND The group address is not in the group table (when JoinFlag is FALSE). 394*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. 395*f334afcfSToomas Soome 396*f334afcfSToomas Soome **/ 397*f334afcfSToomas Soome typedef 398*f334afcfSToomas Soome EFI_STATUS 399*f334afcfSToomas Soome (EFIAPI *EFI_UDP6_GROUPS)( 400*f334afcfSToomas Soome IN EFI_UDP6_PROTOCOL *This, 401*f334afcfSToomas Soome IN BOOLEAN JoinFlag, 402*f334afcfSToomas Soome IN EFI_IPv6_ADDRESS *MulticastAddress OPTIONAL 403*f334afcfSToomas Soome ); 404*f334afcfSToomas Soome 405*f334afcfSToomas Soome /** 406*f334afcfSToomas Soome Queues outgoing data packets into the transmit queue. 407*f334afcfSToomas Soome 408*f334afcfSToomas Soome The Transmit() function places a sending request to this instance of the EFI UDPv6 Protocol, 409*f334afcfSToomas Soome alongside the transmit data that was filled by the user. Whenever the packet in the token is 410*f334afcfSToomas Soome sent out or some errors occur, the Token.Event will be signaled and Token.Status is updated. 411*f334afcfSToomas Soome Providing a proper notification function and context for the event will enable the user to 412*f334afcfSToomas Soome receive the notification and transmitting status. 413*f334afcfSToomas Soome 414*f334afcfSToomas Soome @param[in] This Pointer to the EFI_UDP6_PROTOCOL instance. 415*f334afcfSToomas Soome @param[in] Token Pointer to the completion token that will be placed into the 416*f334afcfSToomas Soome transmit queue. 417*f334afcfSToomas Soome 418*f334afcfSToomas Soome @retval EFI_SUCCESS The data has been queued for transmission. 419*f334afcfSToomas Soome @retval EFI_NOT_STARTED This EFI UDPv6 Protocol instance has not been started. 420*f334afcfSToomas Soome @retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source 421*f334afcfSToomas Soome address for this instance, but no source address was available 422*f334afcfSToomas Soome for use. 423*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: 424*f334afcfSToomas Soome - This is NULL. 425*f334afcfSToomas Soome - Token is NULL. 426*f334afcfSToomas Soome - Token.Event is NULL. 427*f334afcfSToomas Soome - Token.Packet.TxData is NULL. 428*f334afcfSToomas Soome - Token.Packet.TxData.FragmentCount is zero. 429*f334afcfSToomas Soome - Token.Packet.TxData.DataLength is not equal to the sum of fragment 430*f334afcfSToomas Soome lengths. 431*f334afcfSToomas Soome - One or more of the Token.Packet.TxData.FragmentTable[].FragmentLength 432*f334afcfSToomas Soome fields is zero. 433*f334afcfSToomas Soome - One or more of the Token.Packet.TxData.FragmentTable[].FragmentBuffer 434*f334afcfSToomas Soome fields is NULL. 435*f334afcfSToomas Soome - Token.Packet.TxData.UdpSessionData.DestinationAddress is not zero 436*f334afcfSToomas Soome and is not valid unicast Ipv6 address if UdpSessionData is not NULL. 437*f334afcfSToomas Soome - Token.Packet.TxData.UdpSessionData is NULL and this instance's 438*f334afcfSToomas Soome UdpConfigData.RemoteAddress is unspecified. 439*f334afcfSToomas Soome - Token.Packet.TxData.UdpSessionData.DestinationAddress is non-zero 440*f334afcfSToomas Soome when DestinationAddress is configured as non-zero when doing Configure() 441*f334afcfSToomas Soome for this EFI Udp6 protocol instance. 442*f334afcfSToomas Soome - Token.Packet.TxData.UdpSesionData.DestinationAddress is zero when 443*f334afcfSToomas Soome DestinationAddress is unspecified when doing Configure() for this 444*f334afcfSToomas Soome EFI Udp6 protocol instance. 445*f334afcfSToomas Soome @retval EFI_ACCESS_DENIED The transmit completion token with the same Token.Event was already 446*f334afcfSToomas Soome in the transmit queue. 447*f334afcfSToomas Soome @retval EFI_NOT_READY The completion token could not be queued because the transmit queue 448*f334afcfSToomas Soome is full. 449*f334afcfSToomas Soome @retval EFI_OUT_OF_RESOURCES Could not queue the transmit data. 450*f334afcfSToomas Soome @retval EFI_NOT_FOUND There is no route to the destination network or address. 451*f334afcfSToomas Soome @retval EFI_BAD_BUFFER_SIZE The data length is greater than the maximum UDP packet size. 452*f334afcfSToomas Soome 453*f334afcfSToomas Soome **/ 454*f334afcfSToomas Soome typedef 455*f334afcfSToomas Soome EFI_STATUS 456*f334afcfSToomas Soome (EFIAPI *EFI_UDP6_TRANSMIT)( 457*f334afcfSToomas Soome IN EFI_UDP6_PROTOCOL *This, 458*f334afcfSToomas Soome IN EFI_UDP6_COMPLETION_TOKEN *Token 459*f334afcfSToomas Soome ); 460*f334afcfSToomas Soome 461*f334afcfSToomas Soome /** 462*f334afcfSToomas Soome Places an asynchronous receive request into the receiving queue. 463*f334afcfSToomas Soome 464*f334afcfSToomas Soome The Receive() function places a completion token into the receive packet queue. This function is 465*f334afcfSToomas Soome always asynchronous. 466*f334afcfSToomas Soome The caller must fill in the Token.Event field in the completion token, and this field cannot be 467*f334afcfSToomas Soome NULL. When the receive operation completes, the EFI UDPv6 Protocol driver updates the Token.Status 468*f334afcfSToomas Soome and Token.Packet.RxData fields and the Token.Event is signaled. 469*f334afcfSToomas Soome Providing a proper notification function and context for the event will enable the user to receive 470*f334afcfSToomas Soome the notification and receiving status. That notification function is guaranteed to not be re-entered. 471*f334afcfSToomas Soome 472*f334afcfSToomas Soome @param[in] This Pointer to the EFI_UDP6_PROTOCOL instance. 473*f334afcfSToomas Soome @param[in] Token Pointer to a token that is associated with the receive data descriptor. 474*f334afcfSToomas Soome 475*f334afcfSToomas Soome @retval EFI_SUCCESS The receive completion token was cached. 476*f334afcfSToomas Soome @retval EFI_NOT_STARTED This EFI UDPv6 Protocol instance has not been started. 477*f334afcfSToomas Soome @retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source 478*f334afcfSToomas Soome address for this instance, but no source address was available 479*f334afcfSToomas Soome for use. 480*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER One or more of the following is TRUE: 481*f334afcfSToomas Soome - This is NULL. 482*f334afcfSToomas Soome - Token is NULL. 483*f334afcfSToomas Soome - Token.Event is NULL. 484*f334afcfSToomas Soome @retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of system 485*f334afcfSToomas Soome resources (usually memory). 486*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI UDPv6 Protocol 487*f334afcfSToomas Soome instance has been reset to startup defaults. 488*f334afcfSToomas Soome @retval EFI_ACCESS_DENIED A receive completion token with the same Token.Event was already in 489*f334afcfSToomas Soome the receive queue. 490*f334afcfSToomas Soome @retval EFI_NOT_READY The receive request could not be queued because the receive queue is full. 491*f334afcfSToomas Soome 492*f334afcfSToomas Soome **/ 493*f334afcfSToomas Soome typedef 494*f334afcfSToomas Soome EFI_STATUS 495*f334afcfSToomas Soome (EFIAPI *EFI_UDP6_RECEIVE)( 496*f334afcfSToomas Soome IN EFI_UDP6_PROTOCOL *This, 497*f334afcfSToomas Soome IN EFI_UDP6_COMPLETION_TOKEN *Token 498*f334afcfSToomas Soome ); 499*f334afcfSToomas Soome 500*f334afcfSToomas Soome /** 501*f334afcfSToomas Soome Aborts an asynchronous transmit or receive request. 502*f334afcfSToomas Soome 503*f334afcfSToomas Soome The Cancel() function is used to abort a pending transmit or receive request. If the token is in the 504*f334afcfSToomas Soome transmit or receive request queues, after calling this function, Token.Status will be set to 505*f334afcfSToomas Soome EFI_ABORTED and then Token.Event will be signaled. If the token is not in one of the queues, 506*f334afcfSToomas Soome which usually means that the asynchronous operation has completed, this function will not signal the 507*f334afcfSToomas Soome token and EFI_NOT_FOUND is returned. 508*f334afcfSToomas Soome 509*f334afcfSToomas Soome @param[in] This Pointer to the EFI_UDP6_PROTOCOL instance. 510*f334afcfSToomas Soome @param[in] Token Pointer to a token that has been issued by EFI_UDP6_PROTOCOL.Transmit() 511*f334afcfSToomas Soome or EFI_UDP6_PROTOCOL.Receive().If NULL, all pending tokens are aborted. 512*f334afcfSToomas Soome 513*f334afcfSToomas Soome @retval EFI_SUCCESS The asynchronous I/O request was aborted and Token.Event was signaled. 514*f334afcfSToomas Soome When Token is NULL, all pending requests are aborted and their events 515*f334afcfSToomas Soome are signaled. 516*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER This is NULL. 517*f334afcfSToomas Soome @retval EFI_NOT_STARTED This instance has not been started. 518*f334afcfSToomas Soome @retval EFI_NOT_FOUND When Token is not NULL, the asynchronous I/O request was not found in 519*f334afcfSToomas Soome the transmit or receive queue. It has either completed or was not issued 520*f334afcfSToomas Soome by Transmit() and Receive(). 521*f334afcfSToomas Soome 522*f334afcfSToomas Soome **/ 523*f334afcfSToomas Soome typedef 524*f334afcfSToomas Soome EFI_STATUS 525*f334afcfSToomas Soome (EFIAPI *EFI_UDP6_CANCEL)( 526*f334afcfSToomas Soome IN EFI_UDP6_PROTOCOL *This, 527*f334afcfSToomas Soome IN EFI_UDP6_COMPLETION_TOKEN *Token OPTIONAL 528*f334afcfSToomas Soome ); 529*f334afcfSToomas Soome 530*f334afcfSToomas Soome /** 531*f334afcfSToomas Soome Polls for incoming data packets and processes outgoing data packets. 532*f334afcfSToomas Soome 533*f334afcfSToomas Soome The Poll() function can be used by network drivers and applications to increase the rate that data 534*f334afcfSToomas Soome packets are moved between the communications device and the transmit and receive queues. 535*f334afcfSToomas Soome In some systems, the periodic timer event in the managed network driver may not poll the underlying 536*f334afcfSToomas Soome communications device fast enough to transmit and/or receive all data packets without missing incoming 537*f334afcfSToomas Soome packets or dropping outgoing packets. Drivers and applications that are experiencing packet loss should 538*f334afcfSToomas Soome try calling the Poll() function more often. 539*f334afcfSToomas Soome 540*f334afcfSToomas Soome @param[in] This Pointer to the EFI_UDP6_PROTOCOL instance. 541*f334afcfSToomas Soome 542*f334afcfSToomas Soome @retval EFI_SUCCESS Incoming or outgoing data was processed. 543*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER This is NULL. 544*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. 545*f334afcfSToomas Soome @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue. 546*f334afcfSToomas Soome Consider increasing the polling rate. 547*f334afcfSToomas Soome 548*f334afcfSToomas Soome **/ 549*f334afcfSToomas Soome typedef 550*f334afcfSToomas Soome EFI_STATUS 551*f334afcfSToomas Soome (EFIAPI *EFI_UDP6_POLL)( 552*f334afcfSToomas Soome IN EFI_UDP6_PROTOCOL *This 553*f334afcfSToomas Soome ); 554*f334afcfSToomas Soome 555*f334afcfSToomas Soome /// 556*f334afcfSToomas Soome /// The EFI_UDP6_PROTOCOL defines an EFI UDPv6 Protocol session that can be used by any network drivers, 557*f334afcfSToomas Soome /// applications, or daemons to transmit or receive UDP packets. This protocol instance can either be 558*f334afcfSToomas Soome /// bound to a specified port as a service or connected to some remote peer as an active client. 559*f334afcfSToomas Soome /// Each instance has its own settings, such as group table, that are independent from each other. 560*f334afcfSToomas Soome /// 561*f334afcfSToomas Soome struct _EFI_UDP6_PROTOCOL { 562*f334afcfSToomas Soome EFI_UDP6_GET_MODE_DATA GetModeData; 563*f334afcfSToomas Soome EFI_UDP6_CONFIGURE Configure; 564*f334afcfSToomas Soome EFI_UDP6_GROUPS Groups; 565*f334afcfSToomas Soome EFI_UDP6_TRANSMIT Transmit; 566*f334afcfSToomas Soome EFI_UDP6_RECEIVE Receive; 567*f334afcfSToomas Soome EFI_UDP6_CANCEL Cancel; 568*f334afcfSToomas Soome EFI_UDP6_POLL Poll; 569*f334afcfSToomas Soome }; 570*f334afcfSToomas Soome 571*f334afcfSToomas Soome extern EFI_GUID gEfiUdp6ServiceBindingProtocolGuid; 572*f334afcfSToomas Soome extern EFI_GUID gEfiUdp6ProtocolGuid; 573*f334afcfSToomas Soome 574*f334afcfSToomas Soome #endif 575