lib/librss/librss.3

   1 .\" $FreeBSD$
   2 .\"
   3 .Dd October 23, 2016
   4 .Dt LIBRSS 3
   5 .Os
   6 .Sh NAME
   7 .Nm librss
   8 .Nd Provide Receive-side scaling awareness to userland applications
   9 .Sh LIBRARY
  10 .Lb librss
  11 .Sh SYNOPSIS
  12 .In sys/param.h
  13 .In sys/cpuset.h
  14 .In librss.h
  15 .Ft struct rss_config *
  16 .Fn rss_config_get "void"
  17 .Ft void
  18 .Fn rss_config_free "struct rss_config *cfg"
  19 .Ft int
  20 .Fn rss_config_get_bucket_count "struct rss_config *cfg"
  21 .Ft int
  22 .Fn rss_get_bucket_cpuset "struct rss_config *rc" "rss_bucket_type_t btype" "int bucket" "cpuset_t *cs"
  23 .Ft int
  24 .Fn rss_set_bucket_rebalance_cb "rss_bucket_rebalance_cb_t *cb" "void *cbdata"
  25 .Ft int
  26 .Fn rss_sock_set_rss_bucket "int fd" "int af" "int rss_bucket"
  27 .Ft int
  28 .Fn rss_sock_set_recvrss "int fd" "int af" "int val"
  29 .Sh DESCRIPTION
  30 The
  31 .Nm
  32 library and the functions it provides are used for both fetching
  33 the system RSS configuration and interacting with RSS aware
  34 sockets.
  35 .Pp
  36 Applications will typically call
  37 .Fn rss_config_get
  38 to fetch the current RSS configuration from the system and perform
  39 initial setup.
  40 This typically involves spawning worker threads, one per RSS bucket,
  41 and optionally binding them to the per-bucket CPU set.
  42 .Pp
  43 The
  44 .Vt rss_config
  45 struct is defined as:
  46 .Bd -literal
  47 struct rss_config {
  48         int rss_ncpus;
  49         int rss_nbuckets;
  50         int rss_basecpu;
  51         int *rss_bucket_map;
  52 };
  53 .Ed
  54 .Pp
  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.
  61 .Pp
  62 The
  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.
  70 .Pp
  71 The
  72 .Vt rss_bucket_type_t
  73 enum is defined as:
  74 .Bd -literal
  75 typedef enum {
  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,
  81 } rss_bucket_type_t;
  82 .Ed
  83 .Pp
  84 The rebalance callback
  85 .Vt rss_bucket_rebalance_cb_t
  86 is defined as:
  87 .Bd -literal
  88 typedef void rss_bucket_rebalance_cb_t(void *arg);
  89 .Ed
  90 .Pp
  91 The
  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.
  98 .Pp
  99 Once RSS setup is completed,
 100 .Fn rss_config_free
 101 is called to free the RSS configuration structure.
 102 .Pp
 103 If
 104 .Vt val
 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
 107 RSS bucket.
 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
 110 socket.
 111 .Pp
 112 The
 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
 116 .Xr accept 2
 117 will automatically be assigned to the RSS bucket.
 118 .Pp
 119 The
 120 .Fn rss_sock_set_recvrss
 121 function enables or disables receiving RSS related information
 122 as socket options in.
 123 .2 recvmsg
 124 calls.
 125 .Pp
 126 When enabled, UDP datagrams will have a message with the
 127 .Vt IP_RECVFLOWID
 128 option indicating the 32-bit receive flowid as a uint32_t,
 129 and the
 130 .Vt IP_RECVRSSBUCKETID
 131 option indicating the 32 bit RSS bucket id as a uint32_t.
 132 .Sh ERRORS
 133 The functions return either <0 or NULL as appropriate upon error.
 134 .Sh HISTORY
 135 The
 136 .Xr librss.3
 137 library first appeared in
 138 .Fx 11.0 .
 139 .Sh AUTHORS
 140 .An Adrian Chadd Aq Mt adrian@FreeBSD.org
 141 .Sh BUGS
 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.