.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "mlx5dv_wr_mkey_configure" "3" "" "" ""
.hy
.SH NAME
.PP
mlx5dv_wr_mkey_configure - Create a work request to configure an MKEY
.PP
mlx5dv_wr_set_mkey_access_flags - Set the memory protection attributes
for an MKEY
.PP
mlx5dv_wr_set_mkey_layout_list - Set a memory layout for an MKEY based
on SGE list
.PP
mlx5dv_wr_set_mkey_layout_interleaved - Set an interleaved memory layout
for an MKEY
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <infiniband/mlx5dv.h>

static inline void mlx5dv_wr_mkey_configure(struct mlx5dv_qp_ex *mqp,
                                            struct mlx5dv_mkey *mkey,
                                            uint8_t num_setters,
                                            struct mlx5dv_mkey_conf_attr *attr);

static inline void mlx5dv_wr_set_mkey_access_flags(struct mlx5dv_qp_ex *mqp,
                                                   uint32_t access_flags);

static inline void mlx5dv_wr_set_mkey_layout_list(struct mlx5dv_qp_ex *mqp,
                                                  uint16_t num_sges,
                                                  const struct ibv_sge *sge);

static inline void mlx5dv_wr_set_mkey_layout_interleaved(struct mlx5dv_qp_ex *mqp,
                                                         uint32_t repeat_count,
                                                         uint16_t num_interleaved,
                                                         const struct mlx5dv_mr_interleaved *data);
\f[R]
.fi
.SH DESCRIPTION
.PP
The MLX5DV MKEY configure API and the related setters
(mlx5dv_wr_set_mkey*) are an extension of IBV work request API (ibv_wr*)
with specific features for MLX5DV MKEY.
.PP
MKEYs allow creation of virtually-contiguous address spaces out of
non-contiguous chunks of memory regions already registered with the
hardware.
Additionally it provides access to some advanced hardware offload
features, e.g.
signature offload.
.PP
These APIs are intended to be used to access additional functionality
beyond what is provided by \f[B]mlx5dv_wr_mr_list\f[R]() and
\f[B]mlx5dv_wr_mr_interleaved\f[R]().
The MKEY features can be optionally enabled using the mkey configure
setters.
It allows using different features in the same MKEY.
.SH USAGE
.PP
To use these APIs a QP must be created using
\f[B]mlx5dv_create_qp\f[R](3) which allows setting the
\f[B]MLX5DV_QP_EX_WITH_MKEY_CONFIGURE\f[R] in \f[B]send_ops_flags\f[R].
.PP
The MKEY configuration work request is created by calling
\f[B]mlx5dv_wr_mkey_configure\f[R](), a WR builder function, followed by
required setter functions.
\f[I]num_setters\f[R] is a number of required setters for the WR.
All setters are optional.
\f[I]num_setters\f[R] can be zero to apply \f[I]attr\f[R] only.
Each setter can be called only once per the WR builder.
.PP
The WR configures \f[I]mkey\f[R] and applies \f[I]attr\f[R] of the
builder function and setter functions\[cq] arguments for it.
If \f[I]mkey\f[R] is already configured, the WR overrides some
\f[I]mkey\f[R] properties depends on builder and setter functions\[cq]
arguments (see details in setters\[cq] description).
To clear configuration of \f[I]mkey\f[R], use \f[B]ibv_post_send\f[R]()
with \f[B]IBV_WR_LOCAL_INV\f[R] opcode or \f[B]ibv_wr_local_inv\f[R]().
.PP
Current implementation requires the \f[B]IBV_SEND_INLINE\f[R] option to
be set in \f[B]wr_flags\f[R] field of \f[B]ibv_qp_ex\f[R] structure
prior to builder function call.
Non-inline payload is currently not supported by this API.
Please note that inlining here is done for MKEY configuration data, not
for user data referenced by data layouts.
.PP
Once MKEY is configured, it may be used in subsequent work requests
(SEND, RDMA_READ, RDMA_WRITE, etc).
If these work requests are posted on the same QP, there is no need to
wait for completion of MKEY configuration work request.
They can be posted immediately after the last setter (or builder if no
setters).
Usually there is no need to even request a completion for MKEY
configuration work request.
.PP
If completion is requested for MKEY configuration work request it will
be delivered with the \f[B]IBV_WC_DRIVER1\f[R] opcode.
.SS Builder function
.TP
\f[B]mlx5dv_wr_mkey_configure()\f[R]
Post a work request to configure an existing MKEY.
With this call alone, it is possible to configure the MKEY and keep or
reset signature attributes.
This call may be followed by zero or more optional setters.
.RS
.TP
\f[I]mqp\f[R]
The QP to post the work request on.
.TP
\f[I]mkey\f[R]
The MKEY to configure.
.TP
\f[I]num_setters\f[R]
The number of setters that must be called after this function.
.TP
\f[I]attr\f[R]
The MKEY configuration attributes
.RE
.SS MKEY configuration attributes
.PP
MKEY configuration attributes are provided in
\f[B]mlx5dv_mkey_conf_attr\f[R] structure.
.IP
.nf
\f[C]
struct mlx5dv_mkey_conf_attr {
        uint32_t conf_flags;
        uint64_t comp_mask;
};
\f[R]
.fi
.TP
\f[I]conf_flags\f[R]
Bitwise OR of the following flags:
.RS
.TP
\f[B]MLX5DV_MKEY_CONF_FLAG_RESET_SIG_ATTR\f[R]
Reset the signature attributes of the MKEY.
If not set, previously configured signature attributes will be kept.
.RE
.TP
\f[I]comp_mask\f[R]
Reserved for future extension, must be 0 now.
.SS Generic setters
.TP
\f[B]mlx5dv_wr_set_mkey_access_flags()\f[R]
Set the memory protection attributes for the MKEY.
If the MKEY is configured, the setter overrides the previous value.
For example, two MKEY configuration WRs are posted.
The first one sets \f[B]IBV_ACCESS_REMOTE_READ\f[R].
The second one sets \f[B]IBV_ACCESS_REMOTE_WRITE\f[R].
In this case, the second WR overrides the memory protection attributes,
and only \f[B]IBV_ACCESS_REMOTE_WRITE\f[R] is allowed for the MKEY when
the WR is completed.
.RS
.TP
\f[I]mqp\f[R]
The QP where an MKEY configuration work request was created by
\f[B]mlx5dv_wr_mkey_configure()\f[R].
.TP
\f[I]access_flags\f[R]
The desired memory protection attributes; it is either 0 or the bitwise
OR of one or more of flags in \f[B]enum ibv_access_flags\f[R].
.RE
.SS Data layout setters
.PP
Data layout setters define how data referenced by the MKEY will be
scattered/gathered in the memory.
In order to use MKEY with RDMA operations, it must be configured with a
layout.
.PP
Not more than one data layout setter may follow builder function.
Layout can be updated in the next calls to builder function.
.PP
When MKEY is used in RDMA operations, it should be used in a zero-based
mode, i.e.\ the \f[B]addr\f[R] field in \f[B]ibv_sge\f[R] structure is
an offset in the total data.
.TP
\f[B]mlx5dv_wr_set_mkey_layout_list()\f[R]
Set a memory layout for an MKEY based on SGE list.
If the MKEY is configured and the data layout was defined by some data
layout setter (not necessary this one), the setter overrides the
previous value.
.RS
.PP
Default WQE size can fit only 4 SGE entries.
To allow more, the QP should be created with a larger WQE size that may
fit it.
This should be done using the \f[B]max_inline_data\f[R] attribute of
\f[B]struct ibv_qp_cap\f[R] upon QP creation.
.TP
\f[I]mqp\f[R]
The QP where an MKEY configuration work request was created by
\f[B]mlx5dv_wr_mkey_configure()\f[R].
.TP
\f[I]num_sges\f[R]
Number of SGEs in the list.
.TP
\f[I]sge\f[R]
Pointer to the list of \f[B]ibv_sge\f[R] structures.
.RE
.TP
\f[B]mlx5dv_wr_set_mkey_layout_interleaved()\f[R]
Set an interleaved memory layout for an MKEY.
If the MKEY is configured and the data layout was defined by some data
layout setter (not necessary this one), the setter overrides the
previous value.
.RS
.PP
Default WQE size can fit only 3 interleaved entries.
To allow more, the QP should be created with a larger WQE size that may
fit it.
This should be done using the \f[B]max_inline_data\f[R] attribute of
\f[B]struct ibv_qp_cap\f[R] upon QP creation.
.PP
As one entry will be consumed for strided header, the MKEY should be
created with one more entry than the required \f[I]num_interleaved\f[R].
.TP
\f[I]mqp\f[R]
The QP where an MKEY configuration work request was created by
\f[B]mlx5dv_wr_mkey_configure()\f[R].
.TP
\f[I]repeat_count\f[R]
The \f[I]data\f[R] layout representation is repeated
\f[I]repeat_count\f[R] times.
.TP
\f[I]num_interleaved\f[R]
Number of entries in the \f[I]data\f[R] representation.
.TP
\f[I]data\f[R]
Pointer to the list of interleaved data layout descriptions.
.PP
Interleaved data layout is described by \f[B]mlx5dv_mr_interleaved\f[R]
structure.
.IP
.nf
\f[C]
struct mlx5dv_mr_interleaved {
    uint64_t addr;
    uint32_t bytes_count;
    uint32_t bytes_skip;
    uint32_t lkey;
};
\f[R]
.fi
.TP
\f[I]addr\f[R]
Start address of the local memory buffer.
.TP
\f[I]bytes_count\f[R]
Number of data bytes to put into the buffer.
.TP
\f[I]bytes_skip\f[R]
Number of bytes to skip in the buffer before the next data block.
.TP
\f[I]lkey\f[R]
Key of the local Memory Region
.RE
.SS Signature setters
.PP
The signature attributes of the MKEY allow
adding/modifying/stripping/validating integrity fields when transmitting
data from memory to network and when receiving data from network to
memory.
.PP
Use the signature setters to set/update the signature attributes of the
MKEY.
To reset the signature attributes without invalidating the MKEY, use the
\f[B]MLX5DV_MKEY_CONF_FLAG_RESET_SIG_ATTR\f[R] flag.
.TP
\f[B]mlx5dv_wr_set_mkey_sig_block\f[R]()
Set MKEY block signature attributes.
If the MKEY is already configured with the signature attributes, the
setter overrides the previous value.
See dedicated man page for \f[B]mlx5dv_wr_set_mkey_sig_block\f[R](3).
.SS Crypto setter
.PP
The crypto attributes of the MKey allow encryption and decryption of
transmitted data from memory to network and when receiving data from
network to memory.
.PP
Use the crypto setter to set/update the crypto attributes of the MKey.
When the MKey is created with
\f[B]MLX5DV_MKEY_INIT_ATTR_FLAGS_CRYPTO\f[R] it must be configured with
crypto attributes before the MKey can be used.
.TP
\f[B]mlx5dv_wr_set_mkey_crypto()\f[R]
Set MKey crypto attributes.
If the MKey is already configured with crypto attributes, the setter
overrides the previous value.
see dedicated man page for \f[B]mlx5dv_wr_set_mkey_crypto\f[R](3).
.SH EXAMPLES
.SS Create QP and MKEY
.PP
Code below creates a QP with MKEY configure operation support and an
indirect mkey.
.IP
.nf
\f[C]
/* Create QP with MKEY configure support */
struct ibv_qp_init_attr_ex attr_ex = {};
attr_ex.comp_mask |= IBV_QP_INIT_ATTR_SEND_OPS_FLAGS;
attr_ex.send_ops_flags |= IBV_QP_EX_WITH_RDMA_WRITE;

struct mlx5dv_qp_init_attr attr_dv = {};
attr_dv.comp_mask |= MLX5DV_QP_INIT_ATTR_MASK_SEND_OPS_FLAGS;
attr_dv.send_ops_flags = MLX5DV_QP_EX_WITH_MKEY_CONFIGURE;

ibv_qp *qp = mlx5dv_create_qp(ctx, attr_ex, attr_dv);
ibv_qp_ex *qpx = ibv_qp_to_qp_ex(qp);
mlx5dv_qp_ex *mqpx = mlx5dv_qp_ex_from_ibv_qp_ex(qpx);

mkey_attr.create_flags = MLX5DV_MKEY_INIT_ATTR_FLAGS_INDIRECT;
struct mlx5dv_mkey *mkey = mlx5dv_create_mkey(&mkey_attr);
\f[R]
.fi
.SS List data layout configuration
.PP
Code below configures an MKEY which allows remote access for read and
write and is based on SGE list layout with two entries.
When this MKEY is used in RDMA write operation, data will be scattered
between two memory regions.
The first 64 bytes will go to memory referenced by \f[B]mr1\f[R].
The next 4096 bytes will go to memory referenced by \f[B]mr2\f[R].
.IP
.nf
\f[C]
ibv_wr_start(qpx);
qpx->wr_id = my_wr_id_1;
qpx->wr_flags = IBV_SEND_INLINE;

struct mlx5dv_mkey_conf_attr mkey_attr = {};
mlx5dv_wr_mkey_configure(mqpx, mkey, 2, &mkey_attr);
mlx5dv_wr_set_mkey_access_flags(mqpx, IBV_ACCESS_REMOTE_READ | IBV_ACCESS_REMOTE_WRITE);
struct ibv_sge sgl[2];
sgl[0].addr = mr1->addr;
sgl[0].length = 64;
sgl[0].lkey = mr1->lkey;
sgl[1].addr = mr2->addr;
sgl[1].length = 4096;
sgl[1].lkey = mr2->lkey;
mlx5dv_wr_set_mkey_layout_list(mqpx, 2, sgl);
ret = ibv_wr_complete(qpx);
\f[R]
.fi
.SS Interleaved data layout configuration
.PP
Code below configures an MKEY which allows remote access for read and
write and is based on interleaved data layout with two entries and
repeat count of two.
When this MKEY is used in RDMA write operation, data will be scattered
between two memory regions.
The first 512 bytes will go to memory referenced by \f[B]mr1\f[R] at
offset 0.
The next 8 bytes will go to memory referenced by \f[B]mr2\f[R] at offset
0.
The next 512 bytes will go to memory referenced by \f[B]mr1\f[R] at
offset 516.
The next 8 bytes will go to memory referenced by \f[B]mr2\f[R] at offset
8.
.IP
.nf
\f[C]
ibv_wr_start(qpx);
qpx->wr_id = my_wr_id_1;
qpx->wr_flags = IBV_SEND_INLINE;

struct mlx5dv_mkey_conf_attr mkey_attr = {};
mlx5dv_wr_mkey_configure(mqpx, mkey, 2, &mkey_attr);
mlx5dv_wr_set_mkey_access_flags(mqpx, IBV_ACCESS_REMOTE_READ | IBV_ACCESS_REMOTE_WRITE);
struct mlx5dv_mr_interleaved data[2];
data[0].addr = mr1->addr;
data[0].bytes_count = 512;
data[0].bytes_skip = 4;
data[0].lkey = mr1->lkey;
data[1].addr = mr2->addr;
data[1].bytes_count = 8;
data[1].bytes_skip = 0;
data[1].lkey = mr2->lkey;
mlx5dv_wr_set_mkey_layout_interleaved(mqpx, 2, 2, &data);
ret = ibv_wr_complete(qpx);
\f[R]
.fi
.SH NOTES
.PP
A DEVX context should be opened by using
\f[B]mlx5dv_open_device\f[R](3).
.SH SEE ALSO
.PP
\f[B]mlx5dv_create_mkey\f[R](3), \f[B]mlx5dv_create_qp\f[R](3),
\f[B]mlx5dv_wr_set_mkey_sig_block\f[R](3),
\f[B]mlx5dv_wr_set_mkey_crypto\f[R](3)
.SH AUTHORS
.PP
Oren Duer <oren@nvidia.com>
.PP
Sergey Gorenko <sergeygo@nvidia.com>
.PP
Evgenii Kochetov <evgeniik@nvidia.com>