gazagnaire.org / ocaml-rss
Receive Side Scaling: the Toeplitz flow hash and per-owner steering
0
Fork 0

Configure Feed

Select the types of activity you want to include in your feed.

OCaml 85.7%
Dune 4.9%
Other 9.3%
6 1 0

Clone this repository

https://git.vm.fail/gazagnaire.org/ocaml-rss https://git.vm.fail/did:plc:g6uwykiirv5cifcilnfiy2ob
ssh://git@git.recoil.org:2222/gazagnaire.org/ocaml-rss ssh://git@git.recoil.org:2222/did:plc:g6uwykiirv5cifcilnfiy2ob

For self-hosted knots, clone URLs may differ based on your setup.


Download tar.gz Download .zip
README.md

nox-rss#

Receive Side Scaling (RSS): the Toeplitz flow hash a NIC uses to steer a packet to a receive queue, plus the pieces a share-nothing software stack needs to do the same across cores.

The opam name is nox-rss because rss is already the RSS feed library. This is Receive Side Scaling, not Really Simple Syndication.

Overview#

Distributing a network flow across N independent owners (NIC queues, CPU cores, share-nothing stacks) needs three things, and this library is exactly those three:

  1. A flow hash. The Toeplitz hash over the connection tuple, with Microsoft's 40-byte default key -- the exact hash hardware RSS computes (Intel 82599 datasheet 7.1.2.8.3). Exposed both asymmetric (what a NIC computes; swapping the endpoints changes the result) and symmetric (the endpoints are ordered first, so both directions of a flow hash equal -- what a NAT or per-core stack needs to keep a bidirectional flow on one owner).
  2. An owner reduction. The RSS indirection that folds a 32-bit hash onto count owners.
  3. Ephemeral-port lanes (RFC 6335). Each owner allocates its source/NAT ports from its own stride of the dynamic range (49152-65535), so a reply addressed to one of those ports steers back to the owner that opened the flow -- the piece that makes NAT and connect() shardable.

I/O-free and dependency-light (ipaddr only): it computes indices and ports, it does not touch the network. Framing and dispatch belong to the caller.

Usage#

$ opam install nox-rss

Steer a flow to one of count share-nothing owners, both directions alike:

let steer ~count ~src ~dst ~src_port ~dst_port =
  let h = Rss.hash ~symmetric:true ~src ~dst ~ports:(src_port, dst_port) () in
  Rss.owner ~count h

An owner allocates its ports from its own lane so replies come back to it:

let my_first_port ~count ~owner = Rss.first_port ~count ~owner
let owner_of_reply ~count port = Rss.port_owner ~count port

API#

  • Rss.toeplitz ~key data - the raw 32-bit Toeplitz hash (asymmetric).
  • Rss.hash ~src ~dst ?ports () - hash a flow tuple; ~symmetric:true for direction-independent flow affinity.
  • Rss.owner ~count hash - reduce a hash to one of count owners.
  • Rss.port_owner ~count port / Rss.first_port ~count ~owner - RFC 6335 dynamic-port lanes.
  • Rss.encode_flow_id / decode_flow_id / owner_of_flow_id - embed the owner in a cross-owner flow identifier.

RSS and its symmetric variant are standard practice; this is a pure-OCaml implementation of the same algorithms.

  • Microsoft RSS - the original NDIS RSS specification and the Toeplitz hash / default key.
  • DPDK rte_thash - DPDK's Toeplitz hash; its app/test/test_thash.c carries the Intel 82599 verification vectors this library is tested against.
  • Linux RSS / RPS / RFS - hardware and software receive steering; the symmetric-hash technique for bidirectional flow affinity.
  • rss - the unrelated OCaml RSS/Atom feed library that owns the rss opam name.

License#

ISC License. See LICENSE.md for details.