TcpMain.h

Last change on this file was 105670, checked in by vboxsync, 6 months ago
Devices/EFI/FirmwareNew: Merge edk2-stable-202405 and make it build on aarch64, bugref:4643
Property svn:eol-style set to `native`
File size: 38.4 KB

Line
1	/** @file
2	Declaration of protocol interfaces in EFI_TCP4_PROTOCOL and EFI_TCP6_PROTOCOL.
3	It is the common head file for all Tcp*.c in TCP driver.
4
5	Copyright (c) 2009 - 2016, Intel Corporation. All rights reserved.<BR>
6	Copyright (c) Microsoft Corporation
7	SPDX-License-Identifier: BSD-2-Clause-Patent
8
9	**/
10
11	#ifndef _TCP_MAIN_H_
12	#define _TCP_MAIN_H_
13
14	#include <Protocol/ServiceBinding.h>
15	#include <Protocol/DriverBinding.h>
16	#include <Protocol/Hash2.h>
17	#include <Library/IpIoLib.h>
18	#include <Library/DevicePathLib.h>
19	#include <Library/PrintLib.h>
20
21	#include "Socket.h"
22	#include "TcpProto.h"
23	#include "TcpDriver.h"
24	#include "TcpFunc.h"
25
26	extern UINT16 mTcp4RandomPort;
27	extern UINT16 mTcp6RandomPort;
28	extern CHAR16 *mTcpStateName[];
29	extern EFI_COMPONENT_NAME_PROTOCOL gTcpComponentName;
30	extern EFI_COMPONENT_NAME2_PROTOCOL gTcpComponentName2;
31	extern EFI_UNICODE_STRING_TABLE *gTcpControllerNameTable;
32
33	extern LIST_ENTRY mTcpRunQue;
34	extern LIST_ENTRY mTcpListenQue;
35	extern TCP_SEQNO mTcpGlobalSecret;
36	extern UINT32 mTcpTick;
37
38	///
39	/// 30 seconds.
40	///
41	#define TCP6_KEEP_NEIGHBOR_TIME 30
42	///
43	/// 5 seconds, since 1 tick equals 200ms.
44	///
45	#define TCP6_REFRESH_NEIGHBOR_TICK 25
46
47	#define TCP_EXPIRE_TIME 65535
48
49	typedef union {
50	EFI_TCP4_CONFIG_DATA Tcp4CfgData;
51	EFI_TCP6_CONFIG_DATA Tcp6CfgData;
52	} TCP_CONFIG_DATA;
53
54	typedef union {
55	EFI_TCP4_ACCESS_POINT Tcp4Ap;
56	EFI_TCP6_ACCESS_POINT Tcp6Ap;
57	} TCP_ACCESS_POINT;
58
59	typedef struct _TCP4_MODE_DATA {
60	EFI_TCP4_CONNECTION_STATE *Tcp4State;
61	EFI_TCP4_CONFIG_DATA *Tcp4ConfigData;
62	EFI_IP4_MODE_DATA *Ip4ModeData;
63	EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData;
64	EFI_SIMPLE_NETWORK_MODE *SnpModeData;
65	} TCP4_MODE_DATA;
66
67	typedef struct _TCP6_MODE_DATA {
68	EFI_TCP6_CONNECTION_STATE *Tcp6State;
69	EFI_TCP6_CONFIG_DATA *Tcp6ConfigData;
70	EFI_IP6_MODE_DATA *Ip6ModeData;
71	EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData;
72	EFI_SIMPLE_NETWORK_MODE *SnpModeData;
73	} TCP6_MODE_DATA;
74
75	typedef struct _TCP4_ROUTE_INFO {
76	BOOLEAN DeleteRoute;
77	EFI_IPv4_ADDRESS *SubnetAddress;
78	EFI_IPv4_ADDRESS *SubnetMask;
79	EFI_IPv4_ADDRESS *GatewayAddress;
80	} TCP4_ROUTE_INFO;
81
82	typedef struct {
83	EFI_SERVICE_BINDING_PROTOCOL *ServiceBinding;
84	UINTN NumberOfChildren;
85	EFI_HANDLE *ChildHandleBuffer;
86	} TCP_DESTROY_CHILD_IN_HANDLE_BUF_CONTEXT;
87
88	//
89	// EFI_TCP4_PROTOCOL definitions.
90	//
91
92	/**
93	Get the current operational status.
94
95	@param[in] This Pointer to the EFI_TCP4_PROTOCOL instance.
96	@param[out] Tcp4State Pointer to the buffer to receive the current TCP
97	state. Optional parameter that may be NULL.
98	@param[out] Tcp4ConfigData Pointer to the buffer to receive the current TCP
99	configuration. Optional parameter that may be NULL.
100	@param[out] Ip4ModeData Pointer to the buffer to receive the current
101	IPv4 configuration. Optional parameter that may be NULL.
102	@param[out] MnpConfigData Pointer to the buffer to receive the current MNP
103	configuration data indirectly used by the TCPv4
104	Instance. Optional parameter that may be NULL.
105	@param[out] SnpModeData Pointer to the buffer to receive the current SNP
106	configuration data indirectly used by the TCPv4
107	Instance. Optional parameter that may be NULL.
108
109	@retval EFI_SUCCESS The mode data was read.
110	@retval EFI_NOT_STARTED No configuration data is available because this
111	instance hasn't been started.
112	@retval EFI_INVALID_PARAMETER This is NULL.
113
114	**/
115	EFI_STATUS
116	EFIAPI
117	Tcp4GetModeData (
118	IN EFI_TCP4_PROTOCOL *This,
119	OUT EFI_TCP4_CONNECTION_STATE *Tcp4State OPTIONAL,
120	OUT EFI_TCP4_CONFIG_DATA *Tcp4ConfigData OPTIONAL,
121	OUT EFI_IP4_MODE_DATA *Ip4ModeData OPTIONAL,
122	OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL,
123	OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL
124	);
125
126	/**
127	Initialize or brutally reset the operational parameters for
128	this EFI TCPv4 instance.
129
130	@param[in] This Pointer to the EFI_TCP4_PROTOCOL instance.
131	@param[in] TcpConfigData Pointer to the configure data to configure the
132	instance. Optional parameter that may be NULL.
133
134	@retval EFI_SUCCESS The operational settings are set, changed, or
135	reset successfully.
136	@retval EFI_NO_MAPPING When using a default address, configuration
137	(through DHCP, BOOTP, RARP, etc.) is not
138	finished.
139	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
140	@retval EFI_ACCESS_DENIED Configuring the TCP instance when it is already
141	configured.
142	@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
143	@retval EFI_UNSUPPORTED One or more of the control options are not
144	supported in the implementation.
145	@retval EFI_OUT_OF_RESOURCES Could not allocate enough system resources.
146
147	**/
148	EFI_STATUS
149	EFIAPI
150	Tcp4Configure (
151	IN EFI_TCP4_PROTOCOL *This,
152	IN EFI_TCP4_CONFIG_DATA *TcpConfigData OPTIONAL
153	);
154
155	/**
156	Add or delete routing entries.
157
158	@param[in] This Pointer to the EFI_TCP4_PROTOCOL instance.
159	@param[in] DeleteRoute If TRUE, delete the specified route from routing
160	table; if FALSE, add the specified route to
161	routing table.
162	@param[in] SubnetAddress The destination network.
163	@param[in] SubnetMask The subnet mask for the destination network.
164	@param[in] GatewayAddress The gateway address for this route.
165
166	@retval EFI_SUCCESS The operation completed successfully.
167	@retval EFI_NOT_STARTED The EFI_TCP4_PROTOCOL instance has not been
168	configured.
169	@retval EFI_NO_MAPPING When using a default address, configuration
170	(through DHCP, BOOTP, RARP, etc.) is not
171	finished.
172	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
173	@retval EFI_OUT_OF_RESOURCES Could not allocate enough resources to add the
174	entry to the routing table.
175	@retval EFI_NOT_FOUND This route is not in the routing table.
176	@retval EFI_ACCESS_DENIED This route is already in the routing table.
177	@retval EFI_UNSUPPORTED The TCP driver does not support this operation.
178
179	**/
180	EFI_STATUS
181	EFIAPI
182	Tcp4Routes (
183	IN EFI_TCP4_PROTOCOL *This,
184	IN BOOLEAN DeleteRoute,
185	IN EFI_IPv4_ADDRESS *SubnetAddress,
186	IN EFI_IPv4_ADDRESS *SubnetMask,
187	IN EFI_IPv4_ADDRESS *GatewayAddress
188	);
189
190	/**
191	Initiate a nonblocking TCP connection request for an active TCP instance.
192
193	@param[in] This Pointer to the EFI_TCP4_PROTOCOL instance.
194	@param[in] ConnectionToken Pointer to the connection token to return when
195	the TCP three way handshake finishes.
196
197	@retval EFI_SUCCESS The connection request is successfully
198	initiated.
199	@retval EFI_NOT_STARTED This EFI_TCP4_PROTOCOL instance hasn't been
200	configured.
201	@retval EFI_ACCESS_DENIED The instance is not configured as an active one
202	or it is not in Tcp4StateClosed state.
203	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
204	@retval EFI_OUT_OF_RESOURCES The driver can't allocate enough resources to
205	initiate the active open.
206	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
207
208	**/
209	EFI_STATUS
210	EFIAPI
211	Tcp4Connect (
212	IN EFI_TCP4_PROTOCOL *This,
213	IN EFI_TCP4_CONNECTION_TOKEN *ConnectionToken
214	);
215
216	/**
217	Listen on the passive instance to accept an incoming connection request.
218
219	@param[in] This Pointer to the EFI_TCP4_PROTOCOL instance.
220	@param[in] ListenToken Pointer to the listen token to return when
221	operation finishes.
222
223	@retval EFI_SUCCESS The listen token has been queued successfully.
224	@retval EFI_NOT_STARTED The EFI_TCP4_PROTOCOL instance hasn't been
225	configured.
226	@retval EFI_ACCESS_DENIED The instance is not a passive one or it is not
227	in Tcp4StateListen state, or a same listen token
228	has already existed in the listen token queue of
229	this TCP instance.
230	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
231	@retval EFI_OUT_OF_RESOURCES Could not allocate enough resources to finish
232	the operation.
233	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
234
235	**/
236	EFI_STATUS
237	EFIAPI
238	Tcp4Accept (
239	IN EFI_TCP4_PROTOCOL *This,
240	IN EFI_TCP4_LISTEN_TOKEN *ListenToken
241	);
242
243	/**
244	Queues outgoing data into the transmit queue
245
246	@param[in] This Pointer to the EFI_TCP4_PROTOCOL instance
247	@param[in] Token Pointer to the completion token to queue to the
248	transmit queue
249
250	@retval EFI_SUCCESS The data has been queued for transmission
251	@retval EFI_NOT_STARTED The EFI_TCP4_PROTOCOL instance hasn't been
252	configured.
253	@retval EFI_NO_MAPPING When using a default address, configuration
254	(DHCP, BOOTP, RARP, etc.) is not finished yet.
255	@retval EFI_INVALID_PARAMETER One or more parameters are invalid
256	@retval EFI_ACCESS_DENIED One or more of the following conditions is TRUE:
257	* A transmit completion token with the same
258	Token-> CompletionToken.Event was already in the
259	transmission queue. * The current instance is in
260	Tcp4StateClosed state * The current instance is
261	a passive one and it is in Tcp4StateListen
262	state. * User has called Close() to disconnect
263	this connection.
264	@retval EFI_NOT_READY The completion token could not be queued because
265	the transmit queue is full.
266	@retval EFI_OUT_OF_RESOURCES Could not queue the transmit data because of a
267	resource shortage.
268	@retval EFI_NETWORK_UNREACHABLE There is no route to the destination network or
269	address.
270
271	**/
272	EFI_STATUS
273	EFIAPI
274	Tcp4Transmit (
275	IN EFI_TCP4_PROTOCOL *This,
276	IN EFI_TCP4_IO_TOKEN *Token
277	);
278
279	/**
280	Place an asynchronous receive request into the receiving queue.
281
282	@param[in] This Pointer to the EFI_TCP4_PROTOCOL instance.
283	@param[in] Token Pointer to a token that is associated with the
284	receive data descriptor.
285
286	@retval EFI_SUCCESS The receive completion token was cached.
287	@retval EFI_NOT_STARTED The EFI_TCP4_PROTOCOL instance hasn't been
288	configured.
289	@retval EFI_NO_MAPPING When using a default address, configuration
290	(DHCP, BOOTP, RARP, etc.) is not finished yet.
291	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
292	@retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued
293	due to a lack of system resources.
294	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
295	@retval EFI_ACCESS_DENIED One or more of the following conditions is TRUE:
296	* A receive completion token with the same
297	Token->CompletionToken.Event was already in the
298	receive queue. * The current instance is in
299	Tcp4StateClosed state. * The current instance is
300	a passive one and it is in Tcp4StateListen
301	state. * User has called Close() to disconnect
302	this connection.
303	@retval EFI_CONNECTION_FIN The communication peer has closed the connection
304	and there is no buffered data in the receive
305	buffer of this instance.
306	@retval EFI_NOT_READY The receive request could not be queued because
307	the receive queue is full.
308
309	**/
310	EFI_STATUS
311	EFIAPI
312	Tcp4Receive (
313	IN EFI_TCP4_PROTOCOL *This,
314	IN EFI_TCP4_IO_TOKEN *Token
315	);
316
317	/**
318	Disconnecting a TCP connection gracefully or reset a TCP connection.
319
320	@param[in] This Pointer to the EFI_TCP4_PROTOCOL instance.
321	@param[in] CloseToken Pointer to the close token to return when
322	operation finishes.
323
324	@retval EFI_SUCCESS The operation completed successfully.
325	@retval EFI_NOT_STARTED The EFI_TCP4_PROTOCOL instance hasn't been
326	configured.
327	@retval EFI_ACCESS_DENIED One or more of the following are TRUE: *
328	Configure() has been called with TcpConfigData
329	set to NULL and this function has not returned.
330	* Previous Close() call on this instance has not
331	finished.
332	@retval EFI_INVALID_PARAMETER One ore more parameters are invalid.
333	@retval EFI_OUT_OF_RESOURCES Could not allocate enough resources to finish the
334	operation.
335	@retval EFI_DEVICE_ERROR Any unexpected error not belonging to the error
336	categories given above.
337
338	**/
339	EFI_STATUS
340	EFIAPI
341	Tcp4Close (
342	IN EFI_TCP4_PROTOCOL *This,
343	IN EFI_TCP4_CLOSE_TOKEN *CloseToken
344	);
345
346	/**
347	Abort an asynchronous connection, listen, transmission or receive request.
348
349	@param This The pointer to the EFI_TCP4_PROTOCOL instance.
350	@param Token The pointer to a token that has been issued by
351	EFI_TCP4_PROTOCOL.Connect(),
352	EFI_TCP4_PROTOCOL.Accept(),
353	EFI_TCP4_PROTOCOL.Transmit() or
354	EFI_TCP4_PROTOCOL.Receive(). If NULL, all pending
355	tokens issued by above four functions will be aborted. Type
356	EFI_TCP4_COMPLETION_TOKEN is defined in
357	EFI_TCP4_PROTOCOL.Connect().
358
359	@retval EFI_SUCCESS The asynchronous I/O request is aborted and Token->Event
360	is signaled.
361	@retval EFI_INVALID_PARAMETER This is NULL.
362	@retval EFI_NOT_STARTED This instance hasn't been configured.
363	@retval EFI_NO_MAPPING When using the default address, configuration
364	(DHCP, BOOTP,RARP, etc.) hasn't finished yet.
365	@retval EFI_NOT_FOUND The asynchronous I/O request isn't found in the
366	transmission or receive queue. It has either
367	completed or wasn't issued by Transmit() and Receive().
368
369	**/
370	EFI_STATUS
371	EFIAPI
372	Tcp4Cancel (
373	IN EFI_TCP4_PROTOCOL *This,
374	IN EFI_TCP4_COMPLETION_TOKEN *Token OPTIONAL
375	);
376
377	/**
378	Poll to receive incoming data and transmit outgoing segments.
379
380	@param[in] This Pointer to the EFI_TCP4_PROTOCOL instance.
381
382	@retval EFI_SUCCESS Incoming or outgoing data was processed.
383	@retval EFI_INVALID_PARAMETER This is NULL.
384	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
385	@retval EFI_NOT_READY No incoming or outgoing data was processed.
386	@retval EFI_TIMEOUT Data was dropped out of the transmission or
387	receive queue. Consider increasing the polling
388	rate.
389
390	**/
391	EFI_STATUS
392	EFIAPI
393	Tcp4Poll (
394	IN EFI_TCP4_PROTOCOL *This
395	);
396
397	//
398	// EFI_TCP6_PROTOCOL definitions.
399	//
400
401	/**
402	Get the current operational status.
403
404	The GetModeData() function copies the current operational settings of this EFI TCPv6
405	Protocol instance into user-supplied buffers. This function can also be used to retrieve
406	the operational setting of underlying drivers such as IPv6, MNP, or SNP.
407
408	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
409	@param[out] Tcp6State The buffer in which the current TCP state is
410	returned. Optional parameter that may be NULL.
411	@param[out] Tcp6ConfigData The buffer in which the current TCP configuration
412	is returned. Optional parameter that may be NULL.
413	@param[out] Ip6ModeData The buffer in which the current IPv6 configuration
414	data used by the TCP instance is returned.
415	Optional parameter that may be NULL.
416	@param[out] MnpConfigData The buffer in which the current MNP configuration
417	data used indirectly by the TCP instance is returned.
418	Optional parameter that may be NULL.
419	@param[out] SnpModeData The buffer in which the current SNP mode data
420	used indirectly by the TCP instance is returned.
421	Optional parameter that may be NULL.
422
423	@retval EFI_SUCCESS The mode data was read.
424	@retval EFI_NOT_STARTED No configuration data is available because this instance hasn't
425	been started.
426	@retval EFI_INVALID_PARAMETER This is NULL.
427
428	**/
429	EFI_STATUS
430	EFIAPI
431	Tcp6GetModeData (
432	IN EFI_TCP6_PROTOCOL *This,
433	OUT EFI_TCP6_CONNECTION_STATE *Tcp6State OPTIONAL,
434	OUT EFI_TCP6_CONFIG_DATA *Tcp6ConfigData OPTIONAL,
435	OUT EFI_IP6_MODE_DATA *Ip6ModeData OPTIONAL,
436	OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL,
437	OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL
438	);
439
440	/**
441	Initialize or brutally reset the operational parameters for this EFI TCPv6 instance.
442
443	The Configure() function does the following:
444	- Initialize this TCP instance, i.e., initialize the communication end settings and
445	specify active open or passive open for an instance.
446	- Reset this TCP instance brutally, i.e., cancel all pending asynchronous tokens, flush
447	transmission and receiving buffer directly without informing the communication peer.
448
449	No other TCPv6 Protocol operation except Poll() can be executed by this instance until
450	it is configured properly. For an active TCP instance, after a proper configuration it
451	may call Connect() to initiates the three-way handshake. For a passive TCP instance,
452	its state will transit to Tcp6StateListen after configuration, and Accept() may be
453	called to listen the incoming TCP connection requests. If Tcp6ConfigData is set to NULL,
454	the instance is reset. Resetting process will be done brutally, the state machine will
455	be set to Tcp6StateClosed directly, the receive queue and transmit queue will be flushed,
456	and no traffic is allowed through this instance.
457
458	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
459	@param[in] Tcp6ConfigData Pointer to the configure data to configure the instance.
460	If Tcp6ConfigData is set to NULL, the instance is reset.
461
462	@retval EFI_SUCCESS The operational settings were set, changed, or reset
463	successfully.
464	@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
465	address for this instance, but no source address was available for
466	use.
467	@retval EFI_INVALID_PARAMETER One or more of the following conditions are TRUE:
468	- This is NULL.
469	- Tcp6ConfigData->AccessPoint.StationAddress is neither zero nor
470	one of the configured IP addresses in the underlying IPv6 driver.
471	- Tcp6ConfigData->AccessPoint.RemoteAddress isn't a valid unicast
472	IPv6 address.
473	- Tcp6ConfigData->AccessPoint.RemoteAddress is zero or
474	Tcp6ConfigData->AccessPoint.RemotePort is zero when
475	Tcp6ConfigData->AccessPoint.ActiveFlag is TRUE.
476	- A same access point has been configured in other TCP
477	instance properly.
478	@retval EFI_ACCESS_DENIED Configuring TCP instance when it is configured without
479	calling Configure() with NULL to reset it.
480	@retval EFI_UNSUPPORTED One or more of the control options are not supported in
481	the implementation.
482	@retval EFI_OUT_OF_RESOURCES Could not allocate enough system resources when
483	executing Configure().
484	@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
485
486	**/
487	EFI_STATUS
488	EFIAPI
489	Tcp6Configure (
490	IN EFI_TCP6_PROTOCOL *This,
491	IN EFI_TCP6_CONFIG_DATA *Tcp6ConfigData OPTIONAL
492	);
493
494	/**
495	Initiate a nonblocking TCP connection request for an active TCP instance.
496
497	The Connect() function will initiate an active open to the remote peer configured
498	in current TCP instance if it is configured active. If the connection succeeds or
499	fails due to an error, the ConnectionToken->CompletionToken.Event will be signaled,
500	and ConnectionToken->CompletionToken.Status will be updated accordingly. This
501	function can only be called for the TCP instance in Tcp6StateClosed state. The
502	instance will transfer into Tcp6StateSynSent if the function returns EFI_SUCCESS.
503	If TCP three-way handshake succeeds, its state will become Tcp6StateEstablished;
504	otherwise, the state will return to Tcp6StateClosed.
505
506	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
507	@param[in] ConnectionToken Pointer to the connection token to return when the TCP
508	three-way handshake finishes.
509
510	@retval EFI_SUCCESS The connection request successfully initiated and the state of
511	this TCP instance has been changed to Tcp6StateSynSent.
512	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
513	@retval EFI_ACCESS_DENIED One or more of the following conditions are TRUE:
514	- This instance is not configured as an active instance.
515	- This instance is not in Tcp6StateClosed state.
516	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
517	- This is NULL.
518	- ConnectionToken is NULL.
519	- ConnectionToken->CompletionToken.Event is NULL.
520	@retval EFI_OUT_OF_RESOURCES The driver can't allocate enough resources to initiate the active open.
521	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
522
523	**/
524	EFI_STATUS
525	EFIAPI
526	Tcp6Connect (
527	IN EFI_TCP6_PROTOCOL *This,
528	IN EFI_TCP6_CONNECTION_TOKEN *ConnectionToken
529	);
530
531	/**
532	Listen on the passive instance to accept an incoming connection request. This is a
533	nonblocking operation.
534
535	The Accept() function initiates an asynchronous accept request to wait for an incoming
536	connection on the passive TCP instance. If a remote peer successfully establishes a
537	connection with this instance, a new TCP instance will be created and its handle will
538	be returned in ListenToken->NewChildHandle. The newly created instance is configured
539	by inheriting the passive instance's configuration, and is ready for use upon return.
540	The new instance is in the Tcp6StateEstablished state.
541
542	The ListenToken->CompletionToken.Event will be signaled when a new connection is
543	accepted, user aborts the listen or connection is reset.
544
545	This function only can be called when the current TCP instance is in Tcp6StateListen state.
546
547	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
548	@param[in] ListenToken Pointer to the listen token to return when the operation finishes.
549
550
551	@retval EFI_SUCCESS The listen token was been queued successfully.
552	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
553	@retval EFI_ACCESS_DENIED One or more of the following are TRUE:
554	- This instance is not a passive instance.
555	- This instance is not in Tcp6StateListen state.
556	- The same listen token has already existed in the listen
557	token queue of this TCP instance.
558	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
559	- This is NULL.
560	- ListenToken is NULL.
561	- ListenToken->CompletionToken.Event is NULL.
562	@retval EFI_OUT_OF_RESOURCES Could not allocate enough resources to finish the operation.
563	@retval EFI_DEVICE_ERROR Any unexpected error not belonging to the error
564	categories given above.
565
566	**/
567	EFI_STATUS
568	EFIAPI
569	Tcp6Accept (
570	IN EFI_TCP6_PROTOCOL *This,
571	IN EFI_TCP6_LISTEN_TOKEN *ListenToken
572	);
573
574	/**
575	Queues outgoing data into the transmit queue.
576
577	The Transmit() function queues a sending request to this TCP instance along with the
578	user data. The status of the token is updated and the event in the token will be
579	signaled once the data is sent out or some error occurs.
580
581	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
582	@param[in] Token Pointer to the completion token to queue to the transmit queue.
583
584	@retval EFI_SUCCESS The data has been queued for transmission.
585	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
586	@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a
587	source address for this instance, but no source address was
588	available for use.
589	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
590	- This is NULL.
591	- Token is NULL.
592	- Token->CompletionToken.Event is NULL.
593	- Token->Packet.TxData is NULL.
594	- Token->Packet.FragmentCount is zero.
595	- Token->Packet.DataLength is not equal to the sum of fragment lengths.
596	@retval EFI_ACCESS_DENIED One or more of the following conditions are TRUE:
597	- A transmit completion token with the same Token->
598	CompletionToken.Event was already in the
599	transmission queue.
600	- The current instance is in Tcp6StateClosed state.
601	- The current instance is a passive one and it is in
602	Tcp6StateListen state.
603	- User has called Close() to disconnect this connection.
604	@retval EFI_NOT_READY The completion token could not be queued because the
605	transmit queue is full.
606	@retval EFI_OUT_OF_RESOURCES Could not queue the transmit data because of a resource
607	shortage.
608	@retval EFI_NETWORK_UNREACHABLE There is no route to the destination network or address.
609
610	**/
611	EFI_STATUS
612	EFIAPI
613	Tcp6Transmit (
614	IN EFI_TCP6_PROTOCOL *This,
615	IN EFI_TCP6_IO_TOKEN *Token
616	);
617
618	/**
619	Places an asynchronous receive request into the receiving queue.
620
621	The Receive() function places a completion token into the receive packet queue. This
622	function is always asynchronous. The caller must allocate the Token->CompletionToken.Event
623	and the FragmentBuffer used to receive data. The caller also must fill the DataLength, which
624	represents the whole length of all FragmentBuffer. When the receive operation completes, the
625	EFI TCPv6 Protocol driver updates the Token->CompletionToken.Status and Token->Packet.RxData
626	fields, and the Token->CompletionToken.Event is signaled. If data is obtained, the data and its length
627	will be copied into the FragmentTable. At the same time the full length of received data will
628	be recorded in the DataLength fields. Providing a proper notification function and context
629	for the event enables the user to receive the notification and receiving status. That
630	notification function is guaranteed to not be re-entered.
631
632	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
633	@param[in] Token Pointer to a token that is associated with the receive data
634	descriptor.
635
636	@retval EFI_SUCCESS The receive completion token was cached.
637	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
638	@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
639	address for this instance, but no source address was available for use.
640	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
641	- This is NULL.
642	- Token is NULL.
643	- Token->CompletionToken.Event is NULL.
644	- Token->Packet.RxData is NULL.
645	- Token->Packet.RxData->DataLength is 0.
646	- The Token->Packet.RxData->DataLength is not the
647	sum of all FragmentBuffer length in FragmentTable.
648	@retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of
649	system resources (usually memory).
650	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
651	The EFI TCPv6 Protocol instance has been reset to startup defaults.
652	@retval EFI_ACCESS_DENIED One or more of the following conditions is TRUE:
653	- A receive completion token with the same Token->CompletionToken.Event
654	was already in the receive queue.
655	- The current instance is in Tcp6StateClosed state.
656	- The current instance is a passive one and it is in
657	Tcp6StateListen state.
658	- The user has called Close() to disconnect this connection.
659	@retval EFI_CONNECTION_FIN The communication peer has closed the connection, and there is no
660	buffered data in the receive buffer of this instance.
661	@retval EFI_NOT_READY The receive request could not be queued because the receive queue is full.
662
663	**/
664	EFI_STATUS
665	EFIAPI
666	Tcp6Receive (
667	IN EFI_TCP6_PROTOCOL *This,
668	IN EFI_TCP6_IO_TOKEN *Token
669	);
670
671	/**
672	Disconnecting a TCP connection gracefully or reset a TCP connection. This function is a
673	nonblocking operation.
674
675	Initiate an asynchronous close token to the TCP driver. After Close() is called, any buffered
676	transmission data will be sent by the TCP driver, and the current instance will have a graceful close
677	working flow described as RFC 793 if AbortOnClose is set to FALSE, otherwise, a rest packet
678	will be sent by TCP driver to fast disconnect this connection. When the close operation completes
679	successfully the TCP instance is in Tcp6StateClosed state, all pending asynchronous
680	operations are signaled, and any buffers used for TCP network traffic are flushed.
681
682	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
683	@param[in] CloseToken Pointer to the close token to return when operation finishes.
684
685	@retval EFI_SUCCESS The Close() was called successfully.
686	@retval EFI_NOT_STARTED This EFI TCPv6 Protocol instance has not been configured.
687	@retval EFI_ACCESS_DENIED One or more of the following are TRUE:
688	- CloseToken or CloseToken->CompletionToken.Event is already in use.
689	- Previous Close() call on this instance has not finished.
690	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
691	- This is NULL.
692	- CloseToken is NULL.
693	- CloseToken->CompletionToken.Event is NULL.
694	@retval EFI_OUT_OF_RESOURCES Could not allocate enough resources to finish the operation.
695	@retval EFI_DEVICE_ERROR Any unexpected error not belonging to the error categories given above.
696
697	**/
698	EFI_STATUS
699	EFIAPI
700	Tcp6Close (
701	IN EFI_TCP6_PROTOCOL *This,
702	IN EFI_TCP6_CLOSE_TOKEN *CloseToken
703	);
704
705	/**
706	Abort an asynchronous connection, listen, transmission or receive request.
707
708	The Cancel() function aborts a pending connection, listen, transmit or
709	receive request.
710
711	If Token is not NULL and the token is in the connection, listen, transmission
712	or receive queue when it is being cancelled, its Token->Status will be set
713	to EFI_ABORTED and then Token->Event will be signaled.
714
715	If the token is not in one of the queues, which usually means that the
716	asynchronous operation has completed, EFI_NOT_FOUND is returned.
717
718	If Token is NULL all asynchronous token issued by Connect(), Accept(),
719	Transmit() and Receive() will be aborted.
720
721	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
722	@param[in] Token Pointer to a token that has been issued by
723	EFI_TCP6_PROTOCOL.Connect(),
724	EFI_TCP6_PROTOCOL.Accept(),
725	EFI_TCP6_PROTOCOL.Transmit() or
726	EFI_TCP6_PROTOCOL.Receive(). If NULL, all pending
727	tokens issued by above four functions will be aborted. Type
728	EFI_TCP6_COMPLETION_TOKEN is defined in
729	EFI_TCP_PROTOCOL.Connect().
730
731	@retval EFI_SUCCESS The asynchronous I/O request is aborted and Token->Event
732	is signaled.
733	@retval EFI_INVALID_PARAMETER This is NULL.
734	@retval EFI_NOT_STARTED This instance hasn't been configured.
735	@retval EFI_NOT_FOUND The asynchronous I/O request isn't found in the transmission or
736	receive queue. It has either completed or wasn't issued by
737	Transmit() and Receive().
738
739	**/
740	EFI_STATUS
741	EFIAPI
742	Tcp6Cancel (
743	IN EFI_TCP6_PROTOCOL *This,
744	IN EFI_TCP6_COMPLETION_TOKEN *Token OPTIONAL
745	);
746
747	/**
748	Poll to receive incoming data and transmit outgoing segments.
749
750	The Poll() function increases the rate that data is moved between the network
751	and application and can be called when the TCP instance is created successfully.
752	Its use is optional.
753
754	@param[in] This Pointer to the EFI_TCP6_PROTOCOL instance.
755
756	@retval EFI_SUCCESS Incoming or outgoing data was processed.
757	@retval EFI_INVALID_PARAMETER This is NULL.
758	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
759	@retval EFI_NOT_READY No incoming or outgoing data is processed.
760	@retval EFI_TIMEOUT Data was dropped out of the transmission or receive queue.
761	Consider increasing the polling rate.
762
763	**/
764	EFI_STATUS
765	EFIAPI
766	Tcp6Poll (
767	IN EFI_TCP6_PROTOCOL *This
768	);
769
770	/**
771	Retrieves the Initial Sequence Number (ISN) for a TCP connection identified by local
772	and remote IP addresses and ports.
773
774	This method is based on https://datatracker.ietf.org/doc/html/rfc9293#section-3.4.1
775	Where the ISN is computed as follows:
776	ISN = TimeStamp + MD5(LocalIP, LocalPort, RemoteIP, RemotePort, Secret)
777
778	Otherwise:
779	ISN = M + F(localip, localport, remoteip, remoteport, secretkey)
780
781	"Here M is the 4 microsecond timer, and F() is a pseudorandom function (PRF) of the
782	connection's identifying parameters ("localip, localport, remoteip, remoteport")
783	and a secret key ("secretkey") (SHLD-1). F() MUST NOT be computable from the
784	outside (MUST-9), or an attacker could still guess at sequence numbers from the
785	ISN used for some other connection. The PRF could be implemented as a
786	cryptographic hash of the concatenation of the TCP connection parameters and some
787	secret data. For discussion of the selection of a specific hash algorithm and
788	management of the secret key data."
789
790	@param[in] LocalIp A pointer to the local IP address of the TCP connection.
791	@param[in] LocalIpSize The size, in bytes, of the LocalIp buffer.
792	@param[in] LocalPort The local port number of the TCP connection.
793	@param[in] RemoteIp A pointer to the remote IP address of the TCP connection.
794	@param[in] RemoteIpSize The size, in bytes, of the RemoteIp buffer.
795	@param[in] RemotePort The remote port number of the TCP connection.
796	@param[out] Isn A pointer to the variable that will receive the Initial
797	Sequence Number (ISN).
798
799	@retval EFI_SUCCESS The operation completed successfully, and the ISN was
800	retrieved.
801	@retval EFI_INVALID_PARAMETER One or more of the input parameters are invalid.
802	@retval EFI_UNSUPPORTED The operation is not supported.
803
804	**/
805	EFI_STATUS
806	TcpGetIsn (
807	IN UINT8 *LocalIp,
808	IN UINTN LocalIpSize,
809	IN UINT16 LocalPort,
810	IN UINT8 *RemoteIp,
811	IN UINTN RemoteIpSize,
812	IN UINT16 RemotePort,
813	OUT TCP_SEQNO *Isn
814	);
815
816	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/NetworkPkg/TcpDxe/TcpMain.h

Download in other formats: