mlx5dv_devx_general_cmd(3)

1mlx5dv_devx_obj_crmelaxt5edv/_ddeevsxt_roobyj_/crmeoadtiefy/ /dqeusetrryoy//gemnoedriafly(3/)query / general(3)
2
3
4

NAME

6       mlx5dv_devx_obj_create - Creates a devx object
7
8       mlx5dv_devx_obj_destroy - Destroys a devx object
9
10       mlx5dv_devx_obj_modify - Modifies a devx object
11
12       mlx5dv_devx_obj_query - Queries a devx object
13
14       mlx5dv_devx_obj_query_async  - Queries a devx object in an asynchronous
15       mode
16
17       mlx5dv_devx_general_cmd - Issues a general command over the devx inter‐
18       face
19

SYNOPSIS

21              #include <infiniband/mlx5dv.h>
22
23              struct mlx5dv_devx_obj *
24              mlx5dv_devx_obj_create(struct ibv_context *context, const void *in, size_t inlen,
25                             void *out, size_t outlen);
26              int mlx5dv_devx_obj_query(struct mlx5dv_devx_obj *obj, const void *in, size_t inlen,
27                            void *out, size_t outlen);
28              int mlx5dv_devx_obj_query_async(struct mlx5dv_devx_obj *obj, const void *in,
29                              size_t inlen, size_t outlen,
30                              uint64_t wr_id,
31                              struct mlx5dv_devx_cmd_comp *cmd_comp);
32              int mlx5dv_devx_obj_modify(struct mlx5dv_devx_obj *obj, const void *in, size_t inlen,
33                             void *out, size_t outlen);
34              int mlx5dv_devx_obj_destroy(struct mlx5dv_devx_obj *obj);
35              int mlx5dv_devx_general_cmd(struct ibv_context *context, const void *in, size_t inlen,
36                              void *out, size_t outlen);
37

DESCRIPTION

39       Create  /  destroy / modify / query a devx object, issue a general com‐
40       mand over the devx interface.
41
42       The DEVX API enables direct access from the user space area to the mlx5
43       device driver by using the KABI mechanism.  The main purpose is to make
44       the user space driver as independent as possible  from  the  kernel  so
45       that  future  device  functionality  and commands can be activated with
46       minimal to none kernel changes.
47
48       A DEVX object represents some underlay firmware object, the input  com‐
49       mand  to create it is some raw data given by the user application which
50       should match the device specification.  Upon  successful  creation  the
51       output  buffer  includes  the raw data from the device according to its
52       specification, this data can be used as part of related  firmware  com‐
53       mands to this object.
54
55       Once the DEVX object is created it can be queried/modified/destroyed by
56       the matching mlx5dv_devx_obj_xxx() API.  Both the input and the  output
57       for those APIs need to match the device specification as well.
58
59       The  mlx5dv_devx_general_cmd() API enables issuing some general command
60       which is not related to an object such as query device capabilities.
61
62       The mlx5dv_devx_obj_query_async() API is similar to  the  query  object
63       API,  however,  it runs asynchronously without blocking.  The input in‐
64       cludes an mlx5dv_devx_cmd_comp object and an identifier  named  `wr_id'
65       for  this  command.   The response should be read upon success with the
66       mlx5dv_devx_get_async_cmd_comp() API.  The `wr_id' that was supplied as
67       an  input  is returned as part of the response to let application knows
68       for which command the response is related to.
69
70       An application can gradually migrate  to  use  DEVX  according  to  its
71       needs,  it  is not all or nothing.  For example it can create an ibv_cq
72       via ibv_create_cq() verb and then use the returned cqn to create a DEVX
73       QP object by the mlx5dv_devx_obj_create() API which needs that cqn.
74
75       The  above  example  can enable an application to create a QP with some
76       driver specific attributes that are not exposed in the  ibv_create_qp()
77       API,  in that case no user or kernel change may be needed at all as the
78       command input reaches directly to the firmware.
79
80       The expected users for the DEVX APIs are application that use the  mlx5
81       DV  APIs and are familiar with the device specification in both control
82       and data path.
83
84       To successfully create a DEVX object and work on, a DEVX  context  must
85       be  created,  this  is  done  by  the mlx5dv_open_device() API with the
86       MLX5DV_CONTEXT_FLAGS_DEVX flag.
87

ARGUMENTS

89       context
90              RDMA device context to create the action on.
91
92       in     A buffer which contains the command’s input data provided  in  a
93              device specification format.
94
95       inlen  The size of in buffer in bytes.
96
97       out    A  buffer  which contains the command’s output data according to
98              the device specification format.
99
100       outlen The size of out buffer in bytes.
101
102       obj    For query, modify, destroy: the devx object to work on.
103
104       wr_id  The command identifier when working in asynchronous mode.
105
106       cmd_comp
107              The command completion object to read the response from in asyn‐
108              chronous mode.
109

RETURN VALUE

111       Upon success mlx5dv_devx_create_obj will return a new struct mlx5dv_de‐
112       vx_obj on error NULL will be returned and errno will be set.
113
114       Upon success query, modify, destroy, general commands, 0 is returned or
115       the value of errno on a failure.
116
117       If the error value is EREMOTEIO, outbox.status and outbox.syndrome will
118       contain the command failure details.
119

NAME

SYNOPSIS

DESCRIPTION

ARGUMENTS

RETURN VALUE

SEE ALSO