xref: /freebsd/share/man/man4/h_ertt.4 (revision f126890a)
1.\"
2.\" Copyright (c) 2010-2011 The FreeBSD Foundation
3.\"
4.\" This documentation was written at the Centre for Advanced Internet
5.\" Architectures, Swinburne University of Technology, Melbourne, Australia by
6.\" David Hayes under sponsorship from the FreeBSD Foundation.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
21.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
29.Dd January 18, 2012
30.Dt H_ERTT 4
31.Os
32.Sh NAME
33.Nm h_ertt
34.Nd Enhanced Round Trip Time Khelp module
35.Sh SYNOPSIS
36.In netinet/khelp/h_ertt.h
37.Sh DESCRIPTION
38The
39.Nm
40Khelp module works within the
41.Xr khelp 9
42framework to provide TCP with a per-connection, low noise estimate of the
43instantaneous RTT.
44The implementation attempts to be robust in the face of delayed
45acknowledgements, TCP Segmentation Offload (TSO), receivers who manipulate TCP
46timestamps and lack of the TCP timestamp option altogether.
47.Pp
48TCP receivers using delayed acknowledgements either acknowledge every second packet
49(reflecting the time stamp of the first) or use a timeout to trigger the
50acknowledgement if no second packet arrives.
51If the heuristic used by
52.Nm
53determines that the receiver is using delayed acknowledgements, it measures the
54RTT using the second packet (the one that triggers the acknowledgement).
55It does not measure the RTT if the acknowledgement is for the
56first packet, since it cannot be accurately determined.
57.Pp
58When TSO is in use,
59.Nm
60will momentarily disable TSO whilst marking a packet to use for a new
61measurement.
62The process has negligible impact on the connection.
63.Pp
64.Nm
65associates the following struct with each connection's TCP control block:
66.Bd -literal
67struct ertt {
68	TAILQ_HEAD(txseginfo_head, txseginfo) txsegi_q;	/* Private. */
69	long		bytes_tx_in_rtt;		/* Private. */
70	long		bytes_tx_in_marked_rtt;
71	unsigned long	marked_snd_cwnd;
72	int		rtt;
73	int		maxrtt;
74	int		minrtt;
75	int		dlyack_rx;			/* Private. */
76	int		timestamp_errors;		/* Private. */
77	int		markedpkt_rtt;			/* Private. */
78	uint32_t	flags;
79};
80.Ed
81.Pp
82The fields marked as private should not be manipulated by any code outside of
83the
84.Nm
85implementation.
86The non-private fields provide the following data:
87.Bl -tag -width ".Va bytes_tx_in_marked_rtt"  -offset indent
88.It Va bytes_tx_in_marked_rtt
89The number of bytes transmitted in the
90.Va markedpkt_rtt .
91.It Va marked_snd_cwnd
92The value of cwnd for the marked rtt measurement.
93.It Va rtt
94The most recent RTT measurement.
95.It Va maxrtt
96The longest RTT measurement that has been taken.
97.It Va minrtt
98The shortest RTT measurement that has been taken.
99.It Va flags
100The ERTT_NEW_MEASUREMENT flag will be set by the implementation when a new
101measurement is available.
102It is the responsibility of
103.Nm
104consumers to unset the flag if they wish to use it as a notification method for
105new measurements.
106.El
107.Sh SEE ALSO
108.Xr cc_chd 4 ,
109.Xr cc_hd 4 ,
110.Xr cc_vegas 4 ,
111.Xr mod_cc 4 ,
112.Xr hhook 9 ,
113.Xr khelp 9
114.Sh ACKNOWLEDGEMENTS
115Development and testing of this software were made possible in part by grants
116from the FreeBSD Foundation and Cisco University Research Program Fund at
117Community Foundation Silicon Valley.
118.Sh HISTORY
119The
120.Nm
121module first appeared in
122.Fx 9.0 .
123.Pp
124The module was first released in 2010 by David Hayes whilst working on the
125NewTCP research project at Swinburne University of Technology's Centre for
126Advanced Internet Architectures, Melbourne, Australia.
127More details are available at:
128.Pp
129http://caia.swin.edu.au/urp/newtcp/
130.Sh AUTHORS
131.An -nosplit
132The
133.Nm
134Khelp module and this manual page were written by
135.An David Hayes Aq Mt david.hayes@ieee.org .
136.Sh BUGS
137The module maintains enhanced RTT estimates for all new TCP connections created
138after the time at which the module was loaded.
139It might be beneficial to see if it is possible to have the module only affect
140connections which actually care about ERTT estimates.
141