mlx5io(4)

💖 mlx5io — the ioctl interface for Connect-X 4/5/6 Mellanox NICs 💖

okay bestie, welcome to the Kernel Interfaces Manual page for mlx5io, aka the little doorway that lets you boss around your Connect-X 4, 5 and 6 Mellanox network adapters when the normal network config just isn't enough. 🎀

---

✨ NAME ✨

mlx5io — the IOCTL interface to manage Connect-X 4/5/6 Mellanox network adapters 🦋

---

✨ SYNOPSIS ✨

#include <dev/mlx5/mlx5io.h>

---

✨ DESCRIPTION ✨

so like, the mlx5io interface exists so you can manage the Connect-X4, 5 and 6 network adapters in the areas that the generic network configuration literally does not cover — mostly stuff about the PCIe attachment and the internal working of the card. 💅

The interface is made up of commands, and you pass them with ioctl(2) on a file descriptor that you opened from the /dev/mlx5ctl device node. iykyk. ✨

The following commands are implemented:

• MLX5_FWDUMP_FORCE — Takes the snapshot of the firmware registers state and stores it in the kernel buffer. 🫶 The buffer must be empty — meaning no dumps should have been written so far — or else the existing dump has to be cleared with the MLX5_FWDUMP_RESET command for the specified device. The argument for this command should point to the struct mlx5_tool_addr structure, which contains the PCIe bus address of the device.

struct mlx5_tool_addr {
        uint32_t domain;
        uint8_t bus;
        uint8_t slot;
        uint8_t func;
};

• MLX5_FWDUMP_RESET — Clears the stored firmware dump, getting the kernel buffer all ready and cute for the next dump. 🌸 The argument for the command should point to the struct mlx5_tool_addr structure, which contains the PCIe bus address of the device.
• MLX5_FWDUMP_GET — Fetches the stored firmware dump into the user memory. The argument to the command should point to the input/output struct mlx5_fwdump_get structure. Its devaddr field specifies the address of the device, the buf field points to the array of struct mlx5_fwdump_reg records of the register values, and the size of that array is specified in the reg_cnt field. 👑

struct mlx5_fwdump_get {
        struct mlx5_tool_addr devaddr;
        struct mlx5_fwdump_reg *buf;
        size_t reg_cnt;
        size_t reg_filled; /* out */
};

On successful return, the reg_filled field reports the number of buf array elements that were actually filled with the register values. If buf contains the NULL pointer, no registers get filled, but reg_filled still contains the number of registers that should be passed for the complete dump. no cap. 💀

The struct mlx5_fwdump_reg element contains the address of the register in the addr field, and its value in the val field. 🦋

struct mlx5_fwdump_reg {
        uint32_t addr;
        uint32_t val;
};

• MLX5_FW_UPDATE — Requests a firmware update (flash) on the adapter specified by the devaddr, using the firmware image in MFA2 format. 🔥 The argument for the ioctl command is the struct mlx5_fw_update, which has the following definition:

struct mlx5_fw_update {
        struct mlx5_tool_addr devaddr;
        void *img_fw_data;
        size_t img_fw_data_len;
};

The image address in memory is passed in img_fw_data, and the length of the image is specified in the img_fw_data_len field. ✨

• MLX5_FW_RESET — Requests a PCIe link-level reset on the device. ⭐ The address of the device is specified by the struct mlx5_tool_addr structure, which should be passed as an argument.
• MLX5_EEPROM_GET — Fetches EEPROM information. 🎀 The argument to the command should point to the input/output struct mlx5_eeprom_get structure, where the devaddr field specifies the address of the device.

struct mlx5_eeprom_get {
        struct mlx5_tool_addr devaddr;
        size_t eeprom_info_page_valid;
        uint32_t *eeprom_info_buf;
        size_t eeprom_info_out_len;
};

On successful return, the eeprom_info_out_len field reports the length of the EEPROM information. The eeprom_info_buf field contains the actual EEPROM information. The eeprom_info_page_valid field reports the third page validity. 🌸

---

✨ FILES ✨

• The /dev/mlx5ctl devfs(5) node is what you use to pass commands to the driver. that's the whole vibe. 💜

---

✨ RETURN VALUES ✨

If it works, the IOCTL returns zero. ✨ If not, it returns -1 and the global variable errno is set to indicate the error. 😭

---

✨ SEE ALSO ✨

errno(2), ioctl(2), mlx5en(4), mlx5ib(4), mlx5tool(8) and pci(9). go read those too bestie, they're iconic. 📚💅

---

okay that's the whole page!! 🌈 this one came from Debian, dated October 2, 2019 — yeah it's a lil vintage but it still ate. 💖 mwah, go manage those adapters responsibly, ily. 🫶🎀