1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "mlx5dv_devx_obj_create / destroy / modify /query / general" "3" "" "" ""
.hy
.SH NAME
.PP
mlx5dv_devx_obj_create - Creates a devx object
.PP
mlx5dv_devx_obj_destroy - Destroys a devx object
.PP
mlx5dv_devx_obj_modify - Modifies a devx object
.PP
mlx5dv_devx_obj_query - Queries a devx object
.PP
mlx5dv_devx_obj_query_async - Queries a devx object in an asynchronous
mode
.PP
mlx5dv_devx_general_cmd - Issues a general command over the devx
interface
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <infiniband/mlx5dv.h>
struct mlx5dv_devx_obj *
mlx5dv_devx_obj_create(struct ibv_context *context, const void *in, size_t inlen,
void *out, size_t outlen);
int mlx5dv_devx_obj_query(struct mlx5dv_devx_obj *obj, const void *in, size_t inlen,
void *out, size_t outlen);
int mlx5dv_devx_obj_query_async(struct mlx5dv_devx_obj *obj, const void *in,
size_t inlen, size_t outlen,
uint64_t wr_id,
struct mlx5dv_devx_cmd_comp *cmd_comp);
int mlx5dv_devx_obj_modify(struct mlx5dv_devx_obj *obj, const void *in, size_t inlen,
void *out, size_t outlen);
int mlx5dv_devx_obj_destroy(struct mlx5dv_devx_obj *obj);
int mlx5dv_devx_general_cmd(struct ibv_context *context, const void *in, size_t inlen,
void *out, size_t outlen);
\f[R]
.fi
.SH DESCRIPTION
.PP
Create / destroy / modify / query a devx object, issue a general command
over the devx interface.
.PP
The DEVX API enables direct access from the user space area to the mlx5
device driver by using the KABI mechanism.
The main purpose is to make the user space driver as independent as
possible from the kernel so that future device functionality and
commands can be activated with minimal to none kernel changes.
.PP
A DEVX object represents some underlay firmware object, the input
command to create it is some raw data given by the user application
which should match the device specification.
Upon successful creation the output buffer includes the raw data from
the device according to its specification, this data can be used as part
of related firmware commands to this object.
.PP
Once the DEVX object is created it can be queried/modified/destroyed by
the matching mlx5dv_devx_obj_xxx() API.
Both the input and the output for those APIs need to match the device
specification as well.
.PP
The mlx5dv_devx_general_cmd() API enables issuing some general command
which is not related to an object such as query device capabilities.
.PP
The mlx5dv_devx_obj_query_async() API is similar to the query object
API, however, it runs asynchronously without blocking.
The input includes an mlx5dv_devx_cmd_comp object and an identifier
named `wr_id' for this command.
The response should be read upon success with the
mlx5dv_devx_get_async_cmd_comp() API.
The `wr_id' that was supplied as an input is returned as part of the
response to let application knows for which command the response is
related to.
.PP
An application can gradually migrate to use DEVX according to its needs,
it is not all or nothing.
For example it can create an ibv_cq via ibv_create_cq() verb and then
use the returned cqn to create a DEVX QP object by the
mlx5dv_devx_obj_create() API which needs that cqn.
.PP
The above example can enable an application to create a QP with some
driver specific attributes that are not exposed in the ibv_create_qp()
API, in that case no user or kernel change may be needed at all as the
command input reaches directly to the firmware.
.PP
The expected users for the DEVX APIs are application that use the mlx5
DV APIs and are familiar with the device specification in both control
and data path.
.PP
To successfully create a DEVX object and work on, a DEVX context must be
created, this is done by the mlx5dv_open_device() API with the
\f[I]MLX5DV_CONTEXT_FLAGS_DEVX\f[R] flag.
.SH ARGUMENTS
.TP
\f[I]context\f[R]
RDMA device context to create the action on.
.TP
\f[I]in\f[R]
A buffer which contains the command\[cq]s input data provided in a
device specification format.
.TP
\f[I]inlen\f[R]
The size of \f[I]in\f[R] buffer in bytes.
.TP
\f[I]out\f[R]
A buffer which contains the command\[cq]s output data according to the
device specification format.
.TP
\f[I]outlen\f[R]
The size of \f[I]out\f[R] buffer in bytes.
.TP
\f[I]obj\f[R]
For query, modify, destroy: the devx object to work on.
.TP
\f[I]wr_id\f[R]
The command identifier when working in asynchronous mode.
.TP
\f[I]cmd_comp\f[R]
The command completion object to read the response from in asynchronous
mode.
.SH RETURN VALUE
.PP
Upon success \f[I]mlx5dv_devx_create_obj\f[R] will return a new
\f[I]struct mlx5dv_devx_obj\f[R] on error NULL will be returned and
errno will be set.
.PP
Upon success query, modify, destroy, general commands, 0 is returned or
the value of errno on a failure.
.PP
If the error value is EREMOTEIO, outbox.status and outbox.syndrome will
contain the command failure details.
.SH SEE ALSO
.PP
\f[B]mlx5dv_open_device\f[R], \f[B]mlx5dv_devx_create_cmd_comp\f[R],
\f[B]mlx5dv_devx_get_async_cmd_comp\f[R]
.PP
#AUTHOR
.PP
Yishai Hadas <yishaih@mellanox.com>
|
