share/man/man9/PCBGROUPS.9

   1 .\" Copyright (c) 2014 Adrian Chadd
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. The name of the author may not be used to endorse or promote products
  13 .\"    derived from this software without specific prior written permission.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd July 18, 2014
  30 .Dt PCBGROUPS 9
  31 .Os
  32 .Sh NAME
  33 .Nm PCBGROUPS
  34 .Nd Distributed Protocol Control Block Groups
  35 .Sh SYNOPSIS
  36 .Ft void
  37 .Fo in_pcbgroup_init
  38 .Fa "struct inpcbinfo *pcbinfo" "u_int hashfields" "int hash_nelements"
  39 .Fc
  40 .Ft void
  41 .Fn in_pcbgroup_destroy "struct inpcbinfo *pcbinfo"
  42 .Ft struct inpcbgroup *
  43 .Fo in_pcbgroup_byhash
  44 .Fa "struct inpcbinfo *pcbinfo" "u_int hashtype" "uint32_t hash"
  45 .Fc
  46 .Ft struct inpcbgroup *
  47 .Fn in_pcbgroup_byinpcb "struct inpcb *inp"
  48 .Ft void
  49 .Fn in_pcbgroup_update "struct inpcb *inp"
  50 .Ft void
  51 .Fn in_pcbgroup_update_mbuf "struct inpcb *inp" "struct mbuf *m"
  52 .Ft void
  53 .Fn in_pcbgroup_remove "struct inpcb *inp"
  54 .Ft int
  55 .Fn in_pcbgroup_enabled "struct inpcbinfo *pcbinfo"
  56 .Ft struct inpcbgroup *
  57 .Fo in6_pcbgroup_byhash
  58 .Fa "struct inpcbinfo *pcbinfo" "u_int hashtype" "uint32_t hash"
  59 .Fc
  60 .Pp
  61 .Cd "options PCBGROUPS"
  62 .Sh DESCRIPTION
  63 PCBGROUPS, or "connection groups", are based on Willman, Rixner, and Cox's
  64 2006 USENIX paper,
  65 .Qo
  66 An Evaluation of Network Stack Parallelization Strategies in Modern
  67 Operating Systems
  68 .Qc .
  69 .Pp
  70 The PCBGROUPS paper describes two main kind of connection groups.
  71 The first, called ConnP-T, uses a pool of worker threads which
  72 implement the network stack.
  73 Serialization occurs when queuing work into and completing work from
  74 the network stack.
  75 No locking is required inside each worker thread.
  76 .Pp
  77 The second type of connection group, called ConnP-L, uses an array
  78 of PCB groups rather than a single list.
  79 Each PCB group is protected by its own lock.
  80 .Pp
  81 This implementation differs significantly from that described in the
  82 paper, in that it attempts to introduce not just notions of affinity
  83 for connections and distribute work so as to reduce lock contention,
  84 but also align those notions with hardware work distribution strategies
  85 such as RSS.
  86 In this construction, connection groups supplement, rather than replace,
  87 existing reservation tables for protocol 4-tuples, offering CPU-affine
  88 lookup tables with minimal cache line migration and lock contention
  89 during steady state operation.
  90 .Pp
  91 Internet protocols like UDP and TCP register to use connection groups
  92 by providing an ipi_hashfields value other than IPI_HASHFIELDS_NONE.
  93 This indicates to the connection group code whether a 2-tuple or
  94 4-tuple is used as an argument to hashes that assign a connection to
  95 a particular group.
  96 This must be aligned with any hardware-offloaded distribution model,
  97 such as RSS or similar approaches taken in embedded network boards.
  98 Wildcard sockets require special handling, as in Willman 2006, and
  99 are shared between connection groups while being protected by
 100 group-local locks.
 101 Connection establishment and teardown can be signficantly more
 102 expensive than without connection groups, but that steady-state
 103 processing can be significantly faster.
 104 .Pp
 105 Enabling PCBGROUPS in the kernel only provides the infrastructure
 106 required to create and manage multiple PCB groups.
 107 An implementation needs to fill in a few functions to provide PCB
 108 group hash information in order for PCBs to be placed in a PCB group.
 109 .Ss Operation
 110 By default, each PCB info block (struct pcbinfo) has a single hash for
 111 all PCB entries for the given protocol with a single lock protecting it.
 112 This can be a significant source of lock contention on SMP hardware.
 113 When a PCBGROUP is created, an array of separate hash tables are
 114 created, each with its own lock.
 115 A separate table for wildcard PCBs is provided.
 116 By default, a PCBGROUP table is created for each available CPU.
 117 The PCBGROUP code attempts to calculate a hash value from the given
 118 PCB or mbuf when looking up a PCBGROUP.
 119 While processing a received frame,
 120 .Fn in_pcbgroup_byhash
 121 can be used in conjunction with either a hardware-provided hash
 122 value
 123 .Po
 124 eg the
 125 .Xr RSS 9
 126 calculated hash value provided by some NICs
 127 .Pc
 128 or a software-provided hash value in order to choose a PCBGROUP
 129 table to query.
 130 A single table lock is held while performing a wildcard match.
 131 However, all of the table locks are acquired before modifying the
 132 wildcard table.
 133 The PCBGROUP tables operate in conjunction with the normal single PCB list
 134 in a PCB info block.
 135 Thus, inserting and removing a PCB will still incur the same costs
 136 as without PCBGROUPS.
 137 A protocol which uses PCBGROUPS should fall back to the normal PCB list
 138 lookup if a call to the PCBGROUPS layer does not yield a lookup hit.
 139 .Ss Usage
 140 Initialize a PCBGROUP in a PCB info block
 141 .Pq Vt "struct pcbinfo"
 142 by calling
 143 .Fn in_pcbgroup_init .
 144 .Pp
 145 Add a connection to a PCBGROUP with
 146 .Fn in_pcbgroup_update .
 147 Connections are removed by with
 148 .Fn in_pcbgroup_remove .
 149 These in turn will determine which PCBGROUP bucket the given PCB
 150 is placed into and calculate the hash value appropriately.
 151 .Pp
 152 Wildcard PCBs are hashed differently and placed in a single wildcard
 153 PCB list.
 154 If
 155 .Xr RSS 9
 156 is enabled and in use, RSS-aware wildcard PCBs are placed in a single
 157 PCBGROUP based on RSS information.
 158 Protocols may look up the PCB entry in a PCBGROUP by using the lookup
 159 functions
 160 .Fn in_pcbgroup_byhash
 161 and
 162 .Fn in_pcbgroup_byinpcb .
 163 .Sh IMPLEMENTATION NOTES
 164 The PCB code in
 165 .Pa sys/netinet
 166 and
 167 .Pa sys/netinet6
 168 is aware of PCBGROUPS and will call into the PCBGROUPS code to do
 169 PCBGROUP assignment and lookup, preferring a PCBGROUP lookup to the
 170 default global PCB info table.
 171 .Pp
 172 An implementor wishing to experiment or modify the PCBGROUP assignment
 173 should modify this set of functions:
 174 .Bl -tag -width "12345678" -offset indent
 175 .It Fn in_pcbgroup_getbucket No and Fn in6_pcbgroup_getbucket
 176 Map a given 32 bit hash value to a PCBGROUP.
 177 By default this is hash % number_of_pcbgroups.
 178 However, this distribution may not align with NIC receive queues or
 179 the
 180 .Xr netisr 9
 181 configuration.
 182 .It Fn in_pcbgroup_byhash No and Fn in6_pcbgroup_byhash
 183 Map a 32 bit hash value and a hash type identifier to a PCBGROUP.
 184 By default, this simply returns NULL.
 185 This function is used by the
 186 .Xr mbuf 9
 187 receive path in
 188 .Pa sys/netinet/in_pcb.c
 189 to map an mbuf to a PCBGROUP.
 190 .It Fn in_pcbgroup_bytuple No and Fn in6_pcbgroup_bytuple
 191 Map the source and destination address and port details to a PCBGROUP.
 192 By default, this does a very simple XOR hash.
 193 This function is used by both the PCB lookup code and as a fallback in
 194 the
 195 .Xr mbuf 9
 196 receive path in
 197 .Pa sys/netinet/in_pcb.c .
 198 .El
 199 .Sh SEE ALSO
 200 .Xr mbuf 9 ,
 201 .Xr netisr 9 ,
 202 .Xr RSS 9
 203 .Sh HISTORY
 204 PCBGROUPS first appeared in
 205 .Fx 9.0 .
 206 .Pp
 207 The PCBGROUPS implementation is inspired by Willman, Rixner, and Cox's
 208 2006 USENIX paper,
 209 .Qo
 210 An Evaluation of Network Stack Parallelization Strategies in Modern
 211 Operating Systems
 212 .Qc :
 213 .Li http://www.ece.rice.edu/~willmann/pubs/paranet_usenix.pdf
 214 .Sh AUTHORS
 215 .An -nosplit
 216 The PCBGROUPS implementation was written by
 217 .An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org
 218 under contract to Juniper Networks, Inc.
 219 .Pp
 220 This manual page written by
 221 .An Adrian Chadd Aq Mt adrian@FreeBSD.org .
 222 .Sh NOTES
 223 The
 224 .Xr RSS 9
 225 implementation currently uses
 226 .Ic #ifdef
 227 blocks to tie into PCBGROUPS.
 228 This is a sign that a more abstract programming API is needed.
 229 .Pp
 230 There is currently no support for re-balancing the PCBGROUPS assignment,
 231 nor is there any support for overriding which PCBGROUP a socket/PCB
 232 should be in.
 233 .Pp
 234 No statistics are kept to indicate how often PCBGROUPS lookups
 235 succeed or fail.