# mlx5dv_mkey_check

## NAME



           mlx5dv_mkey_check - Check a MKEY for errors
    


## SYNOPSIS



                  #include <infiniband/mlx5dv.h>
    
                  int mlx5dv_mkey_check(struct mlx5dv_mkey *mkey,
                                struct mlx5dv_mkey_err *err_info);
    


## DESCRIPTION



           Checks _mkey_ for errors and provides the result in _err_info_ on
           success.
    
           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.
    
           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.
    


## ARGUMENTS



           _mkey_   The MKEY to check for errors.
    
           _err_info_
                  The result of the MKEY check, information about the errors
                  detected, if any.
    
                         struct mlx5dv_mkey_err {
                             enum mlx5dv_mkey_err_type err_type;
                             union {
                                 struct mlx5dv_sig_err sig;
                             } err;
                         };
    
                  _err_type_
                         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:
                         **MLX5DV_MKEY_SIG_BLOCK_BAD_GUARD** ,
                         **MLX5DV_MKEY_SIG_BLOCK_BAD_APPTAG** ,
                         **MLX5DV_MKEY_SIG_BLOCK_BAD_REFTAG**.
    
                         **MLX5DV_MKEY_NO_ERR**
                                No error is detected for the MKEY.
    
                         **MLX5DV_MKEY_SIG_BLOCK_BAD_GUARD**
                                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
                                **struct mlx5dv_sig_err** of _err_.
    
                         **MLX5DV_MKEY_SIG_BLOCK_BAD_REFTAG**
                                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
                                **struct mlx5dv_sig_err** of _err_.
    
                         **MLX5DV_MKEY_SIG_BLOCK_BAD_APPTAG**
                                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 **struct mlx5dv_sig_err** of _err_.
    
                  _err_    Information about the detected error if _err_type_ is
                         not **MLX5DV_MKEY_NO_ERR**.  Otherwise, its value is not
                         defined.
    
       **Signature error**
                  struct mlx5dv_sig_err {
                      uint64_t actual_value;
                      uint64_t expected_value;
                      uint64_t offset;
                  };
    
           _actual_value_
                  The actual value that was calculated from the transferred
                  data.
    
           _expected_value_
                  The expected value based on what appears in the signature
                  respected field.
    
           _offset_ The offset within the transfer where the error happened.
                  In block signature, this is guaranteed to be a block
                  boundary offset.
    


## RETURN VALUE



           0 on success or the value of errno on failure (which indicates the
           failure reason).
    


## NOTES



           A DEVX context should be opened by using mlx5dv_open_device(3).
    
           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).
    


* * *