mlx5dv_sched_leaf_create(3)

1mlx5dv_sched_node[/leaf]_cmrlemxal5txde5v_/Psrcmohogedrdia_fmnymoed/re’[ds/elsMetaarnfou]ya_(lc3r)eate / modify / destroy(3)
2
3
4

NAME

6       mlx5dv_sched_node_create - Creates a scheduling node element
7
8       mlx5dv_sched_leaf_create - Creates a scheduling leaf element
9
10       mlx5dv_sched_node_modify - Modifies a node scheduling element
11
12       mlx5dv_sched_leaf_modify - Modifies a leaf scheduling element
13
14       mlx5dv_sched_node_destroy - Destroys a node scheduling element
15
16       mlx5dv_sched_leaf_destroy - Destroys a leaf scheduling element
17

SYNOPSIS

19              #include <infiniband/mlx5dv.h>
20
21              struct mlx5dv_sched_node *mlx5dv_sched_node_create(struct ibv_context *context,
22                                         struct mlx5dv_sched_attr *sched_attr);
23
24              struct mlx5dv_sched_leaf *mlx5dv_sched_leaf_create(struct ibv_context *context,
25                                         struct mlx5dv_sched_attr *sched_attr);
26
27              int mlx5dv_sched_node_modify(struct mlx5dv_sched_node *node,
28                               struct mlx5dv_sched_attr *sched_attr);
29
30              int mlx5dv_sched_leaf_modify(struct mlx5dv_sched_leaf *leaf,
31                               struct mlx5dv_sched_attr *sched_attr);
32
33              int mlx5dv_sched_node_destroy(struct mlx5dv_sched_node *node);
34
35              int mlx5dv_sched_leaf_destroy(struct mlx5dv_sched_leaf *leaf);
36

DESCRIPTION

38       The transmit scheduling element (SE) is scheduling the transmission for
39       of all nodes connected it.  By configuring the SE, QoS policies may  be
40       enforced between the competing entities (e.g. SQ, QP).
41
42       In  each scheduling cycle, the SE schedules all ready-to-transmit enti‐
43       ties.  The SE assures that weight for each entity is  met.   If  entity
44       has  reached its maximum allowed bandwidth within the scheduling cycle,
45       it won’t be scheduled till end of the  scheduling  cycle.   The  unused
46       transmission bandwidth will be distributed among the remaining entities
47       assuring the weight setting.
48
49       The SEs are connected in a tree structure.  The entity is connected  to
50       a leaf.  One or more leaves can be connected to a SE node.  One or more
51       SE nodes can be connected to a SE node, until  reaching  the  SE  root.
52       For  each input on each node, user can assign the maximum bandwidth and
53       the scheduling weight.
54
55       The SE APIs (mlx5dv_sched_*) allows access by verbs application to  set
56       the  hierarchical SE tree to the device.  The ibv_qp shall be connected
57       to a leaf.
58

ARGUMENTS

60       Please see ibv_create_qp_ex(3) man page for context.
61
62   mlx5dv_sched_attr
63              struct mlx5dv_sched_attr {
64                  struct mlx5dv_sched_node *parent;
65                  uint32_t flags;
66                  uint32_t bw_share;
67                  uint32_t max_avg_bw;
68                  uint64_t comp_mask;
69              };
70
71       parent A node handler to  the  parent  scheduling  element  which  this
72              scheduling  element  will  be connected to.  The root scheduling
73              element doesn’t have a parent.
74
75       flags  Specifying what attributes in the structure are valid:
76
77              MLX5DV_SCHED_ELEM_ATTR_FLAGS_BW_SHARE for bw_share
78
79              MLX5DV_SCHED_ELEM_ATTR_FLAGS_MAX_AVG_BW for max_avg_bw
80
81       bw_share
82              The relative bandwidth share allocated for this  element.   This
83              field  has  no  units.  The bandwidth is shared between all ele‐
84              ments connected to the same parent element, relatively to  their
85              bw_share.   Value of 0, indicates a device default Weight.  This
86              field must be 0 for the root TSAR.
87
88       max_avg_bw
89              The maximal transmission rate allowed for the element,  averaged
90              over time.  Value is given in units of 1 Mbit/sec. Value 0x0 in‐
91              dicates the rate is unlimited.  This field must  be  0  for  the
92              root TSAR.
93
94       comp_mask
95              Reserved for future extension, must be 0 now.
96
97       node/leaf
98              For modify, destroy: the scheduling element to work on.
99
100       sched_attr
101              For  create,  modify: the attribute of the scheduling element to
102              work on.
103

NOTES

105       For example if an application wants to create 2 QoS QP groups:
106
107              g1: 70% bandwidth share of this application
108              g2: 30% bandwidth share of this application, with maximum average bandwidth limited to 4Gbps
109
110       Pseudo code:
111
112              struct mlx5dv_sched_node *root;
113              struct mlx5dv_sched_leaf *leaf_g1, *leaf_g2;
114              struct mlx5dv_sched_attr;
115              struct ibv_qp *qp1, qp2;
116
117              /* Create root node */
118              attr.comp_mask = 0;
119              attr.parent = NULL;
120              attr.flags = 0;
121              root = mlx5dv_sched_node_create(context, attr);
122
123              /* Create group1 */
124              attr.comp_mask = 0;
125              attr.parent = root;
126              attr.bw_share = 7;
127              attr.flags = MLX5DV_SCHED_ELEM_ATTR_FLAGS_BW_SHARE;
128              leaf_g1 = mlx5dv_sched_leaf_create(context, attr);
129
130              /* Create group2 */
131              attr.comp_mask = 0;
132              attr.parent = root;
133              attr.bw_share = 3;
134              attr.max_avg_bw = 4096;
135              attr.flags = MLX5DV_SCHED_ELEM_ATTR_FLAGS_BW_SHARE | MLX5DV_SCHED_ELEM_ATTR_FLAGS_MAX_AVG_BW;
136              leaf_g2 = mlx5dv_sched_leaf_create(context, attr);
137
138              foreach (qp1 in group1)
139                  mlx5dv_modify_qp_sched_elem(qp1, leaf_g1, NULL);
140
141              foreach (qp2 in group2)
142                  mlx5dv_modify_qp_sched_elem(qp2, leaf_g2, NULL);
143

RETURN VALUE

145       Upon success  *mlx5dv_sched_node[/leaf]_create()*  will  return  a  new
146       struct mlx5dv_sched_node[/leaf], on error NULL will be returned and er‐
147       rno will be set.
148
149       Upon success modify and destroy, 0 is returned or the value of errno on
150       a failure.
151

AUTHOR

156       Mark Zhang <markzhang@nvidia.com>
157
158       Ariel Almog <ariela@nvidia.com>
159
160
161
162mlx5                     mlx5dv_sch2e0d2_0n-o9d-e3[/leaf]_create / modify / destroy(3)