.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "mlx5dv_mkey_check" "3" "" "" ""
.hy
.SH NAME
.PP
mlx5dv_mkey_check - Check a MKEY for errors
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <infiniband/mlx5dv.h>

int mlx5dv_mkey_check(struct mlx5dv_mkey *mkey,
              struct mlx5dv_mkey_err *err_info);
\f[R]
.fi
.SH DESCRIPTION
.PP
Checks \f[I]mkey\f[R] for errors and provides the result in
\f[I]err_info\f[R] on success.
.PP
This should be called after using a MKEY configured with signature
validation in a transfer operation.
While the transfer operation itself may be completed successfully
(i.e.\ no transport related errors occurred), there still may be errors
related to the integrity of the data.
The first of these errors is reported to the MKEY and kept there until
application software queries it by calling this API.
.PP
The type of error indicates which part of the signature was bad (guard,
reftag or apptag).
Also provided is the actual calculated value based on the transferred
data, and the expected value based on the signature fields.
Last part provided is the offset in the transfer that caused the error.
.SH ARGUMENTS
.TP
\f[I]mkey\f[R]
The MKEY to check for errors.
.TP
\f[I]err_info\f[R]
The result of the MKEY check, information about the errors detected, if
any.
.RS
.IP
.nf
\f[C]
struct mlx5dv_mkey_err {
    enum mlx5dv_mkey_err_type err_type;
    union {
        struct mlx5dv_sig_err sig;
    } err;
};
\f[R]
.fi
.TP
\f[I]err_type\f[R]
What kind of error happened.
If several errors exist in one block verified by the device, only the
first of them is reported, according to the order specified in T10DIF
specification, which is: \f[B]MLX5DV_MKEY_SIG_BLOCK_BAD_GUARD\f[R],
\f[B]MLX5DV_MKEY_SIG_BLOCK_BAD_APPTAG\f[R],
\f[B]MLX5DV_MKEY_SIG_BLOCK_BAD_REFTAG\f[R].
.RS
.TP
\f[B]MLX5DV_MKEY_NO_ERR\f[R]
No error is detected for the MKEY.
.TP
\f[B]MLX5DV_MKEY_SIG_BLOCK_BAD_GUARD\f[R]
A signature error was detected in CRC/CHECKSUM for T10-DIF or
CRC32/CRC32C/CRC64_XP10 (depends on the configured signature type).
Additional information about the error is provided in \f[B]struct
mlx5dv_sig_err\f[R] of \f[I]err\f[R].
.TP
\f[B]MLX5DV_MKEY_SIG_BLOCK_BAD_REFTAG\f[R]
A signature error was detected in the reference tag.
This kind of signature error is relevant for T10-DIF only.
Additional information about the error is provided in \f[B]struct
mlx5dv_sig_err\f[R] of \f[I]err\f[R].
.TP
\f[B]MLX5DV_MKEY_SIG_BLOCK_BAD_APPTAG\f[R]
A signature error was detected in the application tag.
This kind of signature error is relevant for T10-DIF only.
Additional information about the error is provided in \f[B]struct
mlx5dv_sig_err\f[R] of \f[I]err\f[R].
.RE
.TP
\f[I]err\f[R]
Information about the detected error if \f[I]err_type\f[R] is not
\f[B]MLX5DV_MKEY_NO_ERR\f[R].
Otherwise, its value is not defined.
.RE
.SS Signature error
.IP
.nf
\f[C]
struct mlx5dv_sig_err {
    uint64_t actual_value;
    uint64_t expected_value;
    uint64_t offset;
};
\f[R]
.fi
.TP
\f[I]actual_value\f[R]
The actual value that was calculated from the transferred data.
.TP
\f[I]expected_value\f[R]
The expected value based on what appears in the signature respected
field.
.TP
\f[I]offset\f[R]
The offset within the transfer where the error happened.
In block signature, this is guaranteed to be a block boundary offset.
.SH RETURN VALUE
.PP
0 on success or the value of errno on failure (which indicates the
failure reason).
.SH NOTES
.PP
A DEVX context should be opened by using
\f[B]mlx5dv_open_device\f[R](3).
.PP
Checking the MKEY for errors should be done after the application knows
the data transfer that was using the MKEY has finished.
Application should wait for the respected completion (if this was a
local MKEY) or wait for a received message from a peer (if this was a
remote MKEY).
.SH SEE ALSO
.PP
\f[B]mlx5dv_wr_mkey_configure\f[R](3),
\f[B]mlx5dv_wr_set_mkey_sig_block\f[R](3),
\f[B]mlx5dv_create_mkey\f[R](3), \f[B]mlx5dv_destroy_mkey\f[R](3)
.SH AUTHORS
.PP
Oren Duer <oren@nvidia.com>
.PP
Sergey Gorenko <sergeygo@nvidia.com>