in_pcbgroup_byhash (9)

Leading comments

Copyright (c) 2014 Adrian Chadd
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other...

(The comments found at the beginning of the groff file "man9/in_pcbgroup_byhash.9freebsd".)

NAME

PCBGROUP - Distributed Protocol Control Block Groups

SYNOPSIS

options PCBGROUP

In sys/param.h In netinet/in.h In netinet/in_pcb.h Ft void Fo in_pcbgroup_init Fa struct inpcbinfo *pcbinfo u_int hashfields int hash_nelements Fc Ft void Fn in_pcbgroup_destroy struct inpcbinfo *pcbinfo Ft struct inpcbgroup * Fo in_pcbgroup_byhash Fa struct inpcbinfo *pcbinfo u_int hashtype uint32_t hash Fc Ft struct inpcbgroup * Fn in_pcbgroup_byinpcb struct inpcb *inp Ft void Fn in_pcbgroup_update struct inpcb *inp Ft void Fn in_pcbgroup_update_mbuf struct inpcb *inp struct mbuf *m Ft void Fn in_pcbgroup_remove struct inpcb *inp Ft int Fn in_pcbgroup_enabled struct inpcbinfo *pcbinfo In netinet6/in6_pcb.h Ft struct inpcbgroup * Fo in6_pcbgroup_byhash Fa struct inpcbinfo *pcbinfo u_int hashtype uint32_t hash Fc

DESCRIPTION

This implementation introduces notions of affinity for connections and distribute work so as to reduce lock contention, with hardware work distribution strategies such as RSS. In this construction, connection groups supplement, rather than replace, existing reservation tables for protocol 4-tuples, offering CPU-affine lookup tables with minimal cache line migration and lock contention during steady state operation.

Internet protocols like UDP and TCP register to use connection groups by providing an ipi_hashfields value other than IPI_HASHFIELDS_NONE. This indicates to the connection group code whether a 2-tuple or 4-tuple is used as an argument to hashes that assign a connection to a particular group. This must be aligned with any hardware-offloaded distribution model, such as RSS or similar approaches taken in embedded network boards. Wildcard sockets require special handling, as in Willmann 2006, and are shared between connection groups while being protected by group-local locks. Connection establishment and teardown can be signficantly more expensive than without connection groups, but that steady-state processing can be significantly faster.

Enabling PCBGROUP in the kernel only provides the infrastructure required to create and manage multiple PCB groups. An implementation needs to fill in a few functions to provide PCB group hash information in order for PCBs to be placed in a PCB group.

Operation

By default, each PCB info block (struct pcbinfo) has a single hash for all PCB entries for the given protocol with a single lock protecting it. This can be a significant source of lock contention on SMP hardware. When a PCBGROUP is created, an array of separate hash tables are created, each with its own lock. A separate table for wildcard PCBs is provided. By default, a PCBGROUP table is created for each available CPU. The PCBGROUP code attempts to calculate a hash value from the given PCB or mbuf when looking up a PCBGROUP. While processing a received frame, Fn in_pcbgroup_byhash can be used in conjunction with either a hardware-provided hash value Po eg the RSS(9) calculated hash value provided by some NICs Pc or a software-provided hash value in order to choose a PCBGROUP table to query. A single table lock is held while performing a wildcard match. However, all of the table locks are acquired before modifying the wildcard table. The PCBGROUP tables operate in conjunction with the normal single PCB list in a PCB info block. Thus, inserting and removing a PCB will still incur the same costs as without PCBGROUP. A protocol which uses PCBGROUP should fall back to the normal PCB list lookup if a call to the PCBGROUP layer does not yield a lookup hit.

Usage

Initialize a PCBGROUP in a PCB info block (Vt struct pcbinfo ) by calling Fn in_pcbgroup_init .

Add a connection to a PCBGROUP with Fn in_pcbgroup_update . Connections are removed by with Fn in_pcbgroup_remove . These in turn will determine which PCBGROUP bucket the given PCB is placed into and calculate the hash value appropriately.

Wildcard PCBs are hashed differently and placed in a single wildcard PCB list. If RSS(9) is enabled and in use, RSS-aware wildcard PCBs are placed in a single PCBGROUP based on RSS information. Protocols may look up the PCB entry in a PCBGROUP by using the lookup functions Fn in_pcbgroup_byhash and Fn in_pcbgroup_byinpcb .

IMPLEMENTATION NOTES

The PCB code in sys/netinet and sys/netinet6 is aware of PCBGROUP and will call into the PCBGROUP code to do PCBGROUP assignment and lookup, preferring a PCBGROUP lookup to the default global PCB info table.

An implementor wishing to experiment or modify the PCBGROUP assignment should modify this set of functions:

Fn in_pcbgroup_getbucket and Fn in6_pcbgroup_getbucket

Map a given 32 bit hash value to a PCBGROUP. By default this is hash % number_of_pcbgroups. However, this distribution may not align with NIC receive queues or the netisr(9) configuration.

Fn in_pcbgroup_byhash and Fn in6_pcbgroup_byhash

Map a 32 bit hash value and a hash type identifier to a PCBGROUP. By default, this simply returns NULL. This function is used by the mbuf(9) receive path in sys/netinet/in_pcb.c to map an mbuf to a PCBGROUP.

Fn in_pcbgroup_bytuple and Fn in6_pcbgroup_bytuple

Map the source and destination address and port details to a PCBGROUP. By default, this does a very simple XOR hash. This function is used by both the PCB lookup code and as a fallback in the mbuf(9) receive path in sys/netinet/in_pcb.c

SEE ALSO

mbuf(9), netisr(9), RSS(9)

Paul Willmann Scott Rixner Alan L. Cox "An Evaluation of Network Stack Parallelization Strategies in Modern Operating Systems" "2006 USENIX Annual Technical Conference" 2006

HISTORY

PCBGROUP first appeared in Fx 9.0 .

AUTHORS

An -nosplit The PCBGROUP implementation was written by An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org under contract to Juniper Networks, Inc.

This manual page written by An Adrian Chadd Aq Mt adrian@FreeBSD.org .

NOTES

The RSS(9) implementation currently uses #ifdef blocks to tie into PCBGROUP. This is a sign that a more abstract programming API is needed.

There is currently no support for re-balancing the PCBGROUP assignment, nor is there any support for overriding which PCBGROUP a socket/PCB should be in.

No statistics are kept to indicate how often PCBGROUP lookups succeed or fail.