1IBV_CREATE_FLOW(3)      Libibverbs Programmer's Manual      IBV_CREATE_FLOW(3)
2
3
4

NAME

6       ibv_create_flow,  ibv_destroy_flow  -  create  or destroy flow steering
7       rules
8

SYNOPSIS

10       #include <infiniband/verbs.h>
11
12       struct ibv_flow *ibv_create_flow(struct ibv_qp *qp,
13                                        struct ibv_flow_attr *flow_attr);
14       int ibv_destroy_flow(struct ibv_flow *flow_id);
15
16

DESCRIPTION

18   ibv_create_flow()
19       allows a user application QP qp to be attached into  a  specified  flow
20       flow which is defined in <infiniband/verbs.h>
21
22       struct ibv_flow_attr {
23               uint32_t comp_mask;                     /* Future extendibility */
24               enum ibv_flow_attr_type type;           /* Rule type - see below */
25               uint16_t size;                          /* Size of command */
26               uint16_t priority;                      /* Rule priority - see below */
27               uint8_t num_of_specs;                   /* Number of ibv_flow_spec_xxx */
28               uint8_t port;                           /* The uplink port number */
29               uint32_t flags;                         /* Extra flags for rule - see below */
30               /* Following are the optional layers according to user request
31                * struct ibv_flow_spec_xxx
32                * struct ibv_flow_spec_yyy
33                */
34       };
35
36       enum ibv_flow_attr_type {
37               IBV_FLOW_ATTR_NORMAL          = 0x0,         /* Steering according to rule specifications */
38               IBV_FLOW_ATTR_ALL_DEFAULT     = 0x1,         /* Default unicast and multicast rule - receive all Eth traffic which isn't steered to any QP */
39               IBV_FLOW_ATTR_MC_DEFAULT      = 0x2,         /* Default multicast rule - receive all Eth multicast traffic which isn't steered to any QP */
40               IBV_FLOW_ATTR_SNIFFER         = 0x3,         /* Sniffer rule - receive all port traffic */
41       };
42
43       enum ibv_flow_flags {
44               IBV_FLOW_ATTR_FLAGS_DONT_TRAP       = 1 << 1,     /* Rule doesn't trap received packets, allowing them to match lower prioritized rules */
45               IBV_FLOW_ATTR_FLAGS_EGRESS          = 1 << 2,     /* Match sent packets against EGRESS rules and carry associated actions if required */
46       };
47
48       enum ibv_flow_spec_type {
49               IBV_FLOW_SPEC_ETH                       = 0x20,   /* Flow specification of L2 header */
50               IBV_FLOW_SPEC_IPV4                      = 0x30,   /* Flow specification of IPv4 header */
51               IBV_FLOW_SPEC_IPV6                      = 0x31,   /* Flow specification of IPv6 header */
52               IBV_FLOW_SPEC_IPV4_EXT                  = 0x32,   /* Extended flow specification of IPv4 */
53               IBV_FLOW_SPEC_ESP                       = 0x34,   /* Flow specification of ESP (IPSec) header */
54               IBV_FLOW_SPEC_TCP                       = 0x40,   /* Flow specification of TCP header */
55               IBV_FLOW_SPEC_UDP                       = 0x41,   /* Flow specification of UDP header */
56               IBV_FLOW_SPEC_VXLAN_TUNNEL              = 0x50,   /* Flow specification of VXLAN header */
57               IBV_FLOW_SPEC_GRE                       = 0x51,   /* Flow specification of GRE header */
58               IBV_FLOW_SPEC_MPLS                      = 0x60,   /* Flow specification of MPLS header */
59               IBV_FLOW_SPEC_INNER                     = 0x100,  /* Flag making L2/L3/L4 specifications to be applied on the inner header */
60               IBV_FLOW_SPEC_ACTION_TAG                = 0x1000, /* Action tagging matched packet */
61               IBV_FLOW_SPEC_ACTION_DROP               = 0x1001, /* Action dropping matched packet */
62               IBV_FLOW_SPEC_ACTION_HANDLE             = 0x1002, /* Carry out an action created by ibv_create_flow_action_xxxx verb */
63               IBV_FLOW_SPEC_ACTION_COUNT              = 0x1003, /* Action count matched packet with a ibv_counters handle */
64       };
65
66       Flow specification general structure:
67
68       struct ibv_flow_spec_xxx {
69               enum ibv_flow_spec_type  type;
70               uint16_t  size;                  /* Flow specification size = sizeof(struct ibv_flow_spec_xxx) */
71               struct ibv_flow_xxx_filter val;
72               struct ibv_flow_xxx_filter mask; /* Defines which bits from the filter value are applicable when looking for a match in the incoming packet */
73       };
74
75       Each spec struct holds the relevant network layer parameters for matching. To enforce the match, the user sets a mask for each parameter.
76       Packets coming from the wire are matched against the flow specification. If a match is found, the associated flow actions are executed on the packet.
77       In ingress flows, the QP parameter is treated as another action of scattering the packet to the respected QP.
78       If the bit is set in the mask, the corresponding bit in the value should be matched.
79       Note that most vendors support either full mask (all "1"s) or zero mask (all "0"s).
80       Network parameters in the relevant network structs should be given in network order (big endian).
81
82
83   Flow domains and priority
84       Flow  steering  defines the concept of domain and priority. Each domain
85       represents an application that can attach a flow.  Domains are  priori‐
86       tized.  A higher priority domain will always supersede a lower priority
87       domain when their flow specifications overlap.
88       IB verbs have the higher priority domain.
89       In addition to the  domain,  there  is  priority  within  each  of  the
90       domains.  A lower priority numeric value (higher priority) takes prece‐
91       dence over matching rules with higher  numeric  priority  value  (lower
92       priority).   It  is important to note that the priority value of a flow
93       spec is used not only to establish the precedence of  conflicting  flow
94       matches but also as a way to abstract the order on which flow specs are
95       tested for matches. Flows with higher priorities will be tested  before
96       flows with lower priorities.
97
98
99   Rules definition ordering
100       An application can provide the ibv_flow_spec_xxx rules in an un-ordered
101       scheme. In this case, each spec should be well defined and match a spe‐
102       cific  network  header  layer.   In  some cases, when certain flow spec
103       types are present in the spec list, it is required to provide the  list
104       in an ordered manner so that the position of that flow spec type in the
105       protocol stack is strictly defined.  When the certain spec type,  which
106       requires  the ordering, resides in the inner network protocol stack (in
107       tunnel protocols) the ordering should be applied to the  inner  network
108       specs  and  should be combined with the inner spec indication using the
109       IBV_FLOW_SPEC_INNER flag.  For example: An MPLS spec which attempts  to
110       match   an   MPLS   tag   in   the   inner   network  should  have  the
111       IBV_FLOW_SPEC_INNER flag set and so do the rest of  the  inner  network
112       specs.  On  top of that, all the inner network specs should be provided
113       in an ordered manner.  This is  essential  to  represent  many  of  the
114       encapsulation tunnel protocols.
115
116       The flow spec types which require this sort of ordering are:
117       1. IBV_FLOW_SPEC_MPLS -
118       Since MPLS header can appear at several locations in the protocol stack
119       and can also be encapsulated on top of different layers, it is required
120       to  place  this  spec  according  to its exact location in the protocol
121       stack.
122
123   ibv_destroy_flow()
124       destroys the flow flow_id.
125

RETURN VALUE

127       ibv_create_flow() returns a pointer to the flow, or NULL if the request
128       fails. In case of an error, errno is updated.
129
130       ibv_destroy_flow() returns 0 on success, or the value of errno on fail‐
131       ure (which indicates the failure reason).
132

ERRORS

134   EINVAL
135       ibv_create_flow() flow specification, QP or priority are invalid
136
137       ibv_destroy_flow() flow_id is invalid
138
139   ENOMEM
140       Couldn't create/destroy flow, not enough memory
141
142   ENXIO
143       Device managed flow steering isn't currently supported
144
145   EPERM
146       No permissions to add the flow steering rule
147

NOTES

149       1. These verbs are available only for devices supporting
150          IBV_DEVICE_MANAGED_FLOW_STEERING and only for QPs of Transport  Ser‐
151       vice Type IBV_QPT_UD or IBV_QPT_RAW_PACKET
152       2. User must memset the spec struct with zeros before using it.
153       3.  ether_type  field in ibv_flow_eth_filter is the ethertype following
154       the last VLAN tag of the packet.
155       4.     Only      rule      type      IBV_FLOW_ATTR_NORMAL      supports
156       IBV_FLOW_ATTR_FLAGS_DONT_TRAP flag.
157       5. No specifications are needed for IBV_FLOW_ATTR_SNIFFER rule type.
158       6.  When  IBV_FLOW_ATTR_FLAGS_EGRESS  flag  is set, the qp parameter is
159       used only as a mean to get the device.
160

EXAMPLE

162       Below flow_attr defines a rule in priority 0 to match a destination mac
163       address and a source ipv4 address. For that, L2 and L3 specs are used.
164       If  there is a hit on this rule, means the received packet has destina‐
165       tion mac: 66:11:22:33:44:55 and source ip: 0x0B86C806,  the  packet  is
166       steered to its attached qp.
167
168       struct raw_eth_flow_attr {
169               struct ibv_flow_attr            attr;
170               struct ibv_flow_spec_eth        spec_eth;
171               struct ibv_flow_spec_ipv4       spec_ipv4;
172       } __attribute__((packed));
173
174       struct raw_eth_flow_attr flow_attr = {
175                       .attr = {
176                               .comp_mask      = 0,
177                               .type           = IBV_FLOW_ATTR_NORMAL,
178                               .size           = sizeof(flow_attr),
179                               .priority       = 0,
180                               .num_of_specs   = 2,
181                               .port           = 1,
182                               .flags          = 0,
183                       },
184                       .spec_eth = {
185                               .type   = IBV_FLOW_SPEC_ETH,
186                               .size   = sizeof(struct ibv_flow_spec_eth),
187                               .val = {
188                                       .dst_mac = {0x66, 0x11, 0x22, 0x33, 0x44, 0x55},
189                                       .src_mac = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00},
190                                       .ether_type = 0,
191                                       .vlan_tag = 0,
192                               },
193                               .mask = {
194                                       .dst_mac = { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF},
195                                       .src_mac = { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF},
196                                       .ether_type = 0,
197                                       .vlan_tag = 0,
198                               }
199                       },
200                       .spec_ipv4 = {
201                               .type   = IBV_FLOW_SPEC_IPV4,
202                               .size   = sizeof(struct ibv_flow_spec_ipv4),
203                               .val = {
204                                       .src_ip = 0x0B86C806,
205                                       .dst_ip = 0,
206                               },
207                               .mask = {
208                                       .src_ip = 0xFFFFFFFF,
209                                       .dst_ip = 0,
210                               }
211                       }
212       };
213
214

AUTHORS

216       Hadar Hen Zion <hadarh@mellanox.com>
217
218       Matan Barak <matanb@mellanox.com>
219
220       Yishai Hadas <yishaih@mellanox.com>
221
222       Maor Gottlieb <maorg@mellanox.com>
223
224
225
226libibverbs                        2016-03-15                IBV_CREATE_FLOW(3)
Impressum