mlx5dv_mkey_check(3)

💅 mlx5dv_mkey_check — check a MKEY for errors 💅

okay bestie, so this is a mlx5dv_mkey_check(3) page from the mlx5dv corner of the manual, and it's literally all about asking your MKEY "hey girl, are you okay?" 🫶

---

✨ SYNOPSIS ✨

#include <infiniband/mlx5dv.h>

int mlx5dv_mkey_check(struct mlx5dv_mkey *mkey,
              struct mlx5dv_mkey_err *err_info);

---

🌸 DESCRIPTION 🌸

So the whole vibe here: this function checks mkey for errors, and on success it hands you the tea in err_info. Iconic. 🎀

The way that you call this is after you've used a MKEY that was configured with signature validation in a transfer operation. Because here's the thing — the transfer operation itself might complete successfully (like, no transport-related errors happened, slay), but there can still be errors related to the integrity of the data. 😭 And the first of those errors gets reported to the MKEY and just... stays there, chilling, until application software queries it by calling this API. Main character energy, honestly.

The type of error tells you which part of the signature was bad (guard, reftag or apptag). You also get the actual calculated value based on the transferred data, and the expected value based on the signature fields. Last part? The offset in the transfer that caused the error. So thoughtful of it. ✨

---

🦋 ARGUMENTS 🦋

• mkey — the MKEY you're checking for errors. Just the MKEY. Nothing else.
• err_info — the result of the MKEY check, aka all the info 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. Important detail: if there are several errors in one block verified by the device, only the first of them is reported, according to the order specified in the T10DIF specification, which is: MLX5DV_MKEY_SIG_BLOCK_BAD_GUARD, MLX5DV_MKEY_SIG_BLOCK_BAD_APPTAG, MLX5DV_MKEY_SIG_BLOCK_BAD_REFTAG. So like, order matters, periodt.
  • MLX5DV_MKEY_NO_ERR — no error is detected for the MKEY. the dream. 💖
  • 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 info 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 info 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 info about the error is provided in struct mlx5dv_sig_err of err.
• err — info about the detected error if err_type is not MLX5DV_MKEY_NO_ERR. Otherwise? Its value is not defined. 🙈 no cap.

💀 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. what actually happened, fr fr.
• expected_value — the expected value based on what appears in the signature respected field. what should have happened. 💔
• offset — the offset within the transfer where the error happened. In block signature, this is guaranteed to be a block boundary offset. cute and orderly of it.

---

🔥 RETURN VALUE 🔥

0 on success, or the value of errno on failure (which indicates the failure reason). that's it, that's the whole deal.

---

👑 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).

⚠️ literally do not skip this part bestie — do the wait. the MKEY will not tell you anything useful until the transfer is actually done, and checking early is giving chaos, not results. 😤

---

🌈 SEE ALSO 🌈

mlx5dv_wr_mkey_configure(3), mlx5dv_wr_set_mkey_sig_block(3), mlx5dv_create_mkey(3), mlx5dv_destroy_mkey(3)

---

💜 AUTHORS 💜

• Oren Duer <oren@nvidia.com>
• Sergey Gorenko <sergeygo@nvidia.com>

---

aaaand that's the page! 🧚 this whole thing came from the mlx5dv_mkey_check(3) manual page, and the footer said it's mlx5dv_mkey_check(3) — same name, both ends, matching bookends, we love symmetry. mwah, go check those MKEYs, bestie 💅💖