share/man/man4/h_ertt.4

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