\r
/** \r
Enables the use of the PXE Base Code Protocol functions.\r
+\r
+ This function enables the use of the PXE Base Code Protocol functions. If the\r
+ Started field of the EFI_PXE_BASE_CODE_MODE structure is already TRUE, then\r
+ EFI_ALREADY_STARTED will be returned. If UseIpv6 is TRUE, then IPv6 formatted\r
+ addresses will be used in this session. If UseIpv6 is FALSE, then IPv4 formatted\r
+ addresses will be used in this session. If UseIpv6 is TRUE, and the Ipv6Supported\r
+ field of the EFI_PXE_BASE_CODE_MODE structure is FALSE, then EFI_UNSUPPORTED will\r
+ be returned. If there is not enough memory or other resources to start the PXE\r
+ Base Code Protocol, then EFI_OUT_OF_RESOURCES will be returned. Otherwise, the\r
+ PXE Base Code Protocol will be started, and all of the fields of the EFI_PXE_BASE_CODE_MODE\r
+ structure will be initialized as follows:\r
+ StartedSet to TRUE.\r
+ Ipv6SupportedUnchanged.\r
+ Ipv6AvailableUnchanged.\r
+ UsingIpv6Set to UseIpv6.\r
+ BisSupportedUnchanged.\r
+ BisDetectedUnchanged.\r
+ AutoArpSet to TRUE.\r
+ SendGUIDSet to FALSE.\r
+ TTLSet to DEFAULT_TTL.\r
+ ToSSet to DEFAULT_ToS.\r
+ DhcpCompletedSet to FALSE.\r
+ ProxyOfferReceivedSet to FALSE.\r
+ StationIpSet to an address of all zeros.\r
+ SubnetMaskSet to a subnet mask of all zeros.\r
+ DhcpDiscoverZero-filled.\r
+ DhcpAckZero-filled.\r
+ ProxyOfferZero-filled.\r
+ PxeDiscoverValidSet to FALSE.\r
+ PxeDiscoverZero-filled.\r
+ PxeReplyValidSet to FALSE.\r
+ PxeReplyZero-filled.\r
+ PxeBisReplyValidSet to FALSE.\r
+ PxeBisReplyZero-filled.\r
+ IpFilterSet the Filters field to 0 and the IpCnt field to 0.\r
+ ArpCacheEntriesSet to 0.\r
+ ArpCacheZero-filled.\r
+ RouteTableEntriesSet to 0.\r
+ RouteTableZero-filled.\r
+ IcmpErrorReceivedSet to FALSE.\r
+ IcmpErrorZero-filled.\r
+ TftpErroReceivedSet to FALSE.\r
+ TftpErrorZero-filled.\r
+ MakeCallbacksSet to TRUE if the PXE Base Code Callback Protocol is available.\r
+ Set to FALSE if the PXE Base Code Callback Protocol is not available.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param UseIpv6 Specifies the type of IP addresses that are to be used during the session\r
\r
/** \r
Disables the use of the PXE Base Code Protocol functions.\r
- \r
+\r
+ This function stops all activity on the network device. All the resources allocated\r
+ in Start() are released, the Started field of the EFI_PXE_BASE_CODE_MODE structure is\r
+ set to FALSE and EFI_SUCCESS is returned. If the Started field of the EFI_PXE_BASE_CODE_MODE\r
+ structure is already FALSE, then EFI_NOT_STARTED will be returned.\r
+ \r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
\r
@retval EFI_SUCCESS The PXE Base Code Protocol was stopped.\r
/** \r
Attempts to complete a DHCPv4 D.O.R.A. (discover / offer / request / acknowledge) or DHCPv6\r
S.A.R.R (solicit / advertise / request / reply) sequence.\r
+\r
+ This function attempts to complete the DHCP sequence. If this sequence is completed,\r
+ then EFI_SUCCESS is returned, and the DhcpCompleted, ProxyOfferReceived, StationIp,\r
+ SubnetMask, DhcpDiscover, DhcpAck, and ProxyOffer fields of the EFI_PXE_BASE_CODE_MODE\r
+ structure are filled in.\r
+ If SortOffers is TRUE, then the cached DHCP offer packets will be sorted before\r
+ they are tried. If SortOffers is FALSE, then the cached DHCP offer packets will\r
+ be tried in the order in which they are received. Please see the Preboot Execution\r
+ Environment (PXE) Specification for additional details on the implementation of DHCP.\r
+ This function can take at least 31 seconds to timeout and return control to the\r
+ caller. If the DHCP sequence does not complete, then EFI_TIMEOUT will be returned.\r
+ If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE,\r
+ then the DHCP sequence will be stopped and EFI_ABORTED will be returned.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param SortOffers TRUE if the offers received should be sorted. Set to FALSE to try the\r
\r
/** \r
Attempts to complete the PXE Boot Server and/or boot image discovery sequence.\r
+\r
+ This function attempts to complete the PXE Boot Server and/or boot image discovery\r
+ sequence. If this sequence is completed, then EFI_SUCCESS is returned, and the\r
+ PxeDiscoverValid, PxeDiscover, PxeReplyReceived, and PxeReply fields of the\r
+ EFI_PXE_BASE_CODE_MODE structure are filled in. If UseBis is TRUE, then the\r
+ PxeBisReplyReceived and PxeBisReply fields of the EFI_PXE_BASE_CODE_MODE structure\r
+ will also be filled in. If UseBis is FALSE, then PxeBisReplyValid will be set to FALSE.\r
+ In the structure referenced by parameter Info, the PXE Boot Server list, SrvList[],\r
+ has two uses: It is the Boot Server IP address list used for unicast discovery\r
+ (if the UseUCast field is TRUE), and it is the list used for Boot Server verification\r
+ (if the MustUseList field is TRUE). Also, if the MustUseList field in that structure\r
+ is TRUE and the AcceptAnyResponse field in the SrvList[] array is TRUE, any Boot\r
+ Server reply of that type will be accepted. If the AcceptAnyResponse field is\r
+ FALSE, only responses from Boot Servers with matching IP addresses will be accepted.\r
+ This function can take at least 10 seconds to timeout and return control to the\r
+ caller. If the Discovery sequence does not complete, then EFI_TIMEOUT will be\r
+ returned. Please see the Preboot Execution Environment (PXE) Specification for\r
+ additional details on the implementation of the Discovery sequence.\r
+ If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE,\r
+ then the Discovery sequence is stopped and EFI_ABORTED will be returned.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param Type The type of bootstrap to perform.\r
\r
/** \r
Used to perform TFTP and MTFTP services.\r
+\r
+ This function is used to perform TFTP and MTFTP services. This includes the\r
+ TFTP operations to get the size of a file, read a directory, read a file, and\r
+ write a file. It also includes the MTFTP operations to get the size of a file,\r
+ read a directory, and read a file. The type of operation is specified by Operation.\r
+ If the callback function that is invoked during the TFTP/MTFTP operation does\r
+ not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then EFI_ABORTED will\r
+ be returned.\r
+ For read operations, the return data will be placed in the buffer specified by\r
+ BufferPtr. If BufferSize is too small to contain the entire downloaded file,\r
+ then EFI_BUFFER_TOO_SMALL will be returned and BufferSize will be set to zero\r
+ or the size of the requested file (the size of the requested file is only returned\r
+ if the TFTP server supports TFTP options). If BufferSize is large enough for the\r
+ read operation, then BufferSize will be set to the size of the downloaded file,\r
+ and EFI_SUCCESS will be returned. Applications using the PxeBc.Mtftp() services\r
+ should use the get-file-size operations to determine the size of the downloaded\r
+ file prior to using the read-file operations--especially when downloading large\r
+ (greater than 64 MB) files--instead of making two calls to the read-file operation.\r
+ Following this recommendation will save time if the file is larger than expected\r
+ and the TFTP server does not support TFTP option extensions. Without TFTP option\r
+ extension support, the client has to download the entire file, counting and discarding\r
+ the received packets, to determine the file size.\r
+ For write operations, the data to be sent is in the buffer specified by BufferPtr.\r
+ BufferSize specifies the number of bytes to send. If the write operation completes\r
+ successfully, then EFI_SUCCESS will be returned.\r
+ For TFTP “get file size” operations, the size of the requested file or directory\r
+ is returned in BufferSize, and EFI_SUCCESS will be returned. If the TFTP server\r
+ does not support options, the file will be downloaded into a bit bucket and the\r
+ length of the downloaded file will be returned. For MTFTP “get file size” operations,\r
+ if the MTFTP server does not support the “get file size” option, EFI_UNSUPPORTED\r
+ will be returned.\r
+ This function can take up to 10 seconds to timeout and return control to the caller.\r
+ If the TFTP sequence does not complete, EFI_TIMEOUT will be returned.\r
+ If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE,\r
+ then the TFTP sequence is stopped and EFI_ABORTED will be returned.\r
+ The format of the data returned from a TFTP read directory operation is a null-terminated\r
+ filename followed by a null-terminated information string, of the form\r
+ “size year-month-day hour:minute:second” (i.e. %d %d-%d-%d %d:%d:%f - note that\r
+ the seconds field can be a decimal number), where the date and time are UTC. For\r
+ an MTFTP read directory command, there is additionally a null-terminated multicast\r
+ IP address preceding the filename of the form %d.%d.%d.%d for IP v4. The final\r
+ entry is itself null-terminated, so that the final information string is terminated\r
+ with two null octets.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param Operation The type of operation to perform.\r
\r
/** \r
Writes a UDP packet to the network interface.\r
+\r
+ This function writes a UDP packet specified by the (optional HeaderPtr and)\r
+ BufferPtr parameters to the network interface. The UDP header is automatically\r
+ built by this routine. It uses the parameters OpFlags, DestIp, DestPort, GatewayIp,\r
+ SrcIp, and SrcPort to build this header. If the packet is successfully built and\r
+ transmitted through the network interface, then EFI_SUCCESS will be returned.\r
+ If a timeout occurs during the transmission of the packet, then EFI_TIMEOUT will\r
+ be returned. If an ICMP error occurs during the transmission of the packet, then\r
+ the IcmpErrorReceived field is set to TRUE, the IcmpError field is filled in and\r
+ EFI_ICMP_ERROR will be returned. If the Callback Protocol does not return\r
+ EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then EFI_ABORTED will be returned.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param OpFlags The UDP operation flags. \r
\r
/** \r
Reads a UDP packet from the network interface.\r
+\r
+ This function reads a UDP packet from a network interface. The data contents\r
+ are returned in (the optional HeaderPtr and) BufferPtr, and the size of the\r
+ buffer received is returned in BufferSize . If the input BufferSize is smaller\r
+ than the UDP packet received (less optional HeaderSize), it will be set to the\r
+ required size, and EFI_BUFFER_TOO_SMALL will be returned. In this case, the\r
+ contents of BufferPtr are undefined, and the packet is lost. If a UDP packet is\r
+ successfully received, then EFI_SUCCESS will be returned, and the information\r
+ from the UDP header will be returned in DestIp, DestPort, SrcIp, and SrcPort if\r
+ they are not NULL.\r
+ Depending on the values of OpFlags and the DestIp, DestPort, SrcIp, and SrcPort\r
+ input values, different types of UDP packet receive filtering will be performed.\r
+ The following tables summarize these receive filter operations.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param OpFlags The UDP operation flags. \r
@param DestIp The destination IP address.\r
- @param DestPort The destination UDP port number. \r
- @param GatewayIp The gateway IP address. \r
+ @param DestPort The destination UDP port number.\r
@param SrcIp The source IP address.\r
@param SrcPort The source UDP port number.\r
@param HeaderSize An optional field which may be set to the length of a header at\r
@param BufferSize A pointer to the size of the data at BufferPtr.\r
@param BufferPtr A pointer to the data to be read.\r
\r
- @retval EFI_SUCCESS The UDP Write operation was completed.\r
+ @retval EFI_SUCCESS The UDP Read operation was completed.\r
@retval EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state.\r
@retval EFI_INVALID_PARAMETER One or more parameters are invalid. \r
@retval EFI_DEVICE_ERROR The network device encountered an error during this operation.\r
\r
/** \r
Updates the IP receive filters of a network device and enables software filtering.\r
+ \r
+ The NewFilter field is used to modify the network device's current IP receive\r
+ filter settings and to enable a software filter. This function updates the IpFilter\r
+ field of the EFI_PXE_BASE_CODE_MODE structure with the contents of NewIpFilter.\r
+ The software filter is used when the USE_FILTER in OpFlags is set to UdpRead().\r
+ The current hardware filter remains in effect no matter what the settings of OpFlags\r
+ are, so that the meaning of ANY_DEST_IP set in OpFlags to UdpRead() is from those\r
+ packets whose reception is enabled in hardware – physical NIC address (unicast),\r
+ broadcast address, logical address or addresses (multicast), or all (promiscuous).\r
+ UdpRead() does not modify the IP filter settings.\r
+ Dhcp(), Discover(), and Mtftp() set the IP filter, and return with the IP receive\r
+ filter list emptied and the filter set to EFI_PXE_BASE_CODE_IP_FILTER_STATION_IP.\r
+ If an application or driver wishes to preserve the IP receive filter settings,\r
+ it will have to preserve the IP receive filter settings before these calls, and\r
+ use SetIpFilter() to restore them after the calls. If incompatible filtering is\r
+ requested (for example, PROMISCUOUS with anything else) or if the device does not\r
+ support a requested filter setting and it cannot be accommodated in software\r
+ (for example, PROMISCUOUS not supported), EFI_INVALID_PARAMETER will be returned.\r
+ The IPlist field is used to enable IPs other than the StationIP. They may be\r
+ multicast or unicast. If IPcnt is set as well as EFI_PXE_BASE_CODE_IP_FILTER_STATION_IP,\r
+ then both the StationIP and the IPs from the IPlist will be used.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param NewFilter Pointer to the new set of IP receive filters.\r
\r
/** \r
Uses the ARP protocol to resolve a MAC address.\r
+ \r
+ This function uses the ARP protocol to resolve a MAC address. The UsingIpv6 field\r
+ of the EFI_PXE_BASE_CODE_MODE structure is used to determine if IPv4 or IPv6\r
+ addresses are being used. The IP address specified by IpAddr is used to resolve\r
+ a MAC address. If the ARP protocol succeeds in resolving the specified address,\r
+ then the ArpCacheEntries and ArpCache fields of the EFI_PXE_BASE_CODE_MODE structure\r
+ are updated, and EFI_SUCCESS is returned. If MacAddr is not NULL, the resolved\r
+ MAC address is placed there as well.\r
+ If the PXE Base Code protocol is in the stopped state, then EFI_NOT_STARTED is\r
+ returned. If the ARP protocol encounters a timeout condition while attempting\r
+ to resolve an address, then EFI_TIMEOUT is returned. If the Callback Protocol\r
+ does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then EFI_ABORTED is\r
+ returned.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param IpAddr Pointer to the IP address that is used to resolve a MAC address.\r
\r
/** \r
Updates the parameters that affect the operation of the PXE Base Code Protocol.\r
+ \r
+ This function sets parameters that affect the operation of the PXE Base Code Protocol.\r
+ The parameter specified by NewAutoArp is used to control the generation of ARP\r
+ protocol packets. If NewAutoArp is TRUE, then ARP Protocol packets will be generated\r
+ as required by the PXE Base Code Protocol. If NewAutoArp is FALSE, then no ARP\r
+ Protocol packets will be generated. In this case, the only mappings that are\r
+ available are those stored in the ArpCache of the EFI_PXE_BASE_CODE_MODE structure.\r
+ If there are not enough mappings in the ArpCache to perform a PXE Base Code Protocol\r
+ service, then the service will fail. This function updates the AutoArp field of\r
+ the EFI_PXE_BASE_CODE_MODE structure to NewAutoArp.\r
+ The SetParameters() call must be invoked after a Callback Protocol is installed\r
+ to enable the use of callbacks.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param NewAutoArp If not NULL, a pointer to a value that specifies whether to replace the\r
\r
/** \r
Updates the station IP address and/or subnet mask values of a network device.\r
+ \r
+ This function updates the station IP address and/or subnet mask values of a network\r
+ device.\r
+ The NewStationIp field is used to modify the network device's current IP address.\r
+ If NewStationIP is NULL, then the current IP address will not be modified. Otherwise,\r
+ this function updates the StationIp field of the EFI_PXE_BASE_CODE_MODE structure\r
+ with NewStationIp.\r
+ The NewSubnetMask field is used to modify the network device's current subnet\r
+ mask. If NewSubnetMask is NULL, then the current subnet mask will not be modified.\r
+ Otherwise, this function updates the SubnetMask field of the EFI_PXE_BASE_CODE_MODE\r
+ structure with NewSubnetMask.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param NewStationIp Pointer to the new IP address to be used by the network device. \r
\r
/** \r
Updates the contents of the cached DHCP and Discover packets.\r
+ \r
+ The pointers to the new packets are used to update the contents of the cached\r
+ packets in the EFI_PXE_BASE_CODE_MODE structure.\r
\r
@param This Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.\r
@param NewDhcpDiscoverValid Pointer to a value that will replace the current\r
projects / mirror_edk2.git / blobdiff