8 .Nd Provide Receive-side scaling awareness to userland applications
15 .Ft struct rss_config *
16 .Fn rss_config_get "void"
18 .Fn rss_config_free "struct rss_config *cfg"
20 .Fn rss_config_get_bucket_count "struct rss_config *cfg"
22 .Fn rss_get_bucket_cpuset "struct rss_config *rc" "rss_bucket_type_t btype" "int bucket" "cpuset_t *cs"
24 .Fn rss_set_bucket_rebalance_cb "rss_bucket_rebalance_cb_t *cb" "void *cbdata"
26 .Fn rss_sock_set_rss_bucket "int fd" "int af" "int rss_bucket"
28 .Fn rss_sock_set_recvrss "int fd" "int af" "int val"
32 library and the functions it provides are used for both fetching
33 the system RSS configuration and interacting with RSS aware
36 Applications will typically call
38 to fetch the current RSS configuration from the system and perform
40 This typically involves spawning worker threads, one per RSS bucket,
41 and optionally binding them to the per-bucket CPU set.
55 Applications will typically use the
56 .Fn rss_config_get_bucket_count
57 function to fetch the number of RSS buckets, create one thread
58 per RSS bucket for RSS aware work, then one RSS aware socket to receive
59 UDP datagrams or TCP connections
60 in each particular RSS bucket / thread.
63 .Fn rss_get_bucket_cpuset
64 function sets the given cpuset up for the given
65 RSS bucket and behaviour.
66 Typically applications will wish to just query for
67 .Vt RSS_BUCKET_TYPE_KERNEL_ALL
68 unless they wish to potentially setup different
69 worker threads for transmit and receive.
76 RSS_BUCKET_TYPE_NONE = 0,
77 RSS_BUCKET_TYPE_KERNEL_ALL = 1,
78 RSS_BUCKET_TYPE_KERNEL_TX = 2,
79 RSS_BUCKET_TYPE_KERNEL_RX = 3,
80 RSS_BUCKET_TYPE_MAX = 3,
84 The rebalance callback
85 .Vt rss_bucket_rebalance_cb_t
88 typedef void rss_bucket_rebalance_cb_t(void *arg);
92 .Fn rss_set_bucket_rebalance_cb
93 function sets an optional callback that will be called if the kernel
94 rebalances RSS buckets.
95 This is intended as a future expansion to rebalance buckets rather than
96 reprogram the RSS key, so typically the only work to be performed
97 is to rebind worker threads to an updated cpuset.
99 Once RSS setup is completed,
101 is called to free the RSS configuration structure.
105 is set to 1, the socket can be placed in an RSS bucket and will only accept
106 datagrams (for UDP) or connections (for TCP) that are received for that
108 If set to 0, the socket is placed in the default PCB and will see
109 datagrams/connections that are not initially consumed by a PCB aware
113 .Fn rss_sock_set_rss_bucket
114 function configures the RSS bucket which a socket belongs in.
115 Note that TCP sockets created by
117 will automatically be assigned to the RSS bucket.
120 .Fn rss_sock_set_recvrss
121 function enables or disables receiving RSS related information
122 as socket options in.
126 When enabled, UDP datagrams will have a message with the
128 option indicating the 32-bit receive flowid as a uint32_t,
130 .Vt IP_RECVRSSBUCKETID
131 option indicating the 32 bit RSS bucket id as a uint32_t.
133 The functions return either <0 or NULL as appropriate upon error.
137 library first appeared in
140 .An Adrian Chadd Aq Mt adrian@FreeBSD.org
142 There is currently no kernel mechanism to rebalance the RSS bucket to CPU
143 mapping, and so the callback mechanism is a no-op.