mlx5dv_devx_obj_create(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_general_cmd - Issues a general command over the devx inter‐
15       face
16

SYNOPSIS

18              #include <infiniband/mlx5dv.h>
19
20              struct mlx5dv_devx_obj *
21              mlx5dv_devx_obj_create(struct ibv_context *context, const void *in, size_t inlen,
22                             void *out, size_t outlen);
23              int mlx5dv_devx_obj_query(struct mlx5dv_devx_obj *obj, const void *in, size_t inlen,
24                            void *out, size_t outlen);
25              int mlx5dv_devx_obj_modify(struct mlx5dv_devx_obj *obj, const void *in, size_t inlen,
26                             void *out, size_t outlen);
27              int mlx5dv_devx_obj_destroy(struct mlx5dv_devx_obj *obj);
28              int mlx5dv_devx_general_cmd(struct ibv_context *context, const void *in, size_t inlen,
29                              void *out, size_t outlen);
30

DESCRIPTION

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

ARGUMENTS

74       context
75              RDMA device context to create the action on.
76
77       in     A  buffer  which contains the command's input data provided in a
78              device specification format.
79
80       inlen  The size of in buffer in bytes.
81
82       out    A buffer which contains the command's output data  according  to
83              the device specification format.
84
85       outlen The size of out buffer in bytes.
86
87       obj    For query, modify, destroy: the devx object to work on.
88

RETURN VALUE

90       Upon success mlx5dv_devx_create_obj will return a new struct mlx5dv_de‐
91       vx_obj on error NULL will be returned and errno will be set.
92
93       Upon success query, modify, destroy, general commands, 0 is returned or
94       the value of errno on a failure.
95

NAME

SYNOPSIS

DESCRIPTION

ARGUMENTS

RETURN VALUE

SEE ALSO