mlx5io(4)

💖 NAME 💖

mlx5io — the IOCTL interface to manage Connect-X 4/5/6 Mellanox network adapters. This is the mlx5io(4) page from the Kernel Interfaces Manual, and we're obsessed. It's lowkey all about the management commands that the generic network config doesn't cover. ✨

✨ SYNOPSIS ✨

#include <dev/mlx5/mlx5io.h>

💅 DESCRIPTION 💅

Okay so mlx5io is provided for management of the Connect-X4, 5 and 6 network adapters in the aspects not covered by the generic network configuration, mostly related to the PCIe attachment and internal card working. It's giving behind-the-scenes card management, no cap.

The interface consists of the commands, which are passed by means of ioctl(2) on the file descriptor, opened from the /dev/mlx5ctl device node. Periodt.

The following commands are implemented:

🌸 MLX5_FWDUMP_FORCE 🌸

Take the snapshot of the firmware registers state and store it in the kernel buffer.

Bestie, the buffer must be empty — in other words, no dumps should be written so far, or existing dump cleared with the MLX5_FWDUMP_RESET command for the specified device.

The argument for the command should point to the struct mlx5_tool_addr structure, containing 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 🧚

Clear the stored firmware dump, preparing the kernel buffer for the next dump. The argument for the command should point to the struct mlx5_tool_addr structure, containing the PCIe bus address of the device. The cleanup ate, honestly. 🧼

🔥 MLX5_FWDUMP_GET 🔥

Fetch 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 fields points to the array of struct mlx5_fwdump_reg of records of the registers values, and the size of the 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 the buf array elements actually filled with the registers values. If buf contains the NULL pointer, no registers are filled, but reg_filled still contains the number of registers that should be passed for the complete dump. iykyk, that's the size-check slay. 💅

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

struct mlx5_fwdump_reg {
        uint32_t addr;
        uint32_t val;
};

💥 MLX5_FW_UPDATE 💥

Requests 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 with the following definition.

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

Image address in memory is passed in img_fw_data, the length of the image is specified in the img_fw_data_len field. This one has main character energy, fr fr. ⚡

🦋 MLX5_FW_RESET 🦋

Requests 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 🍓

Fetch 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. eeprom_info_buf field contains the actual EEPROM information. eeprom_info_page_valid field reports the third page validity. Cute little EEPROM info drop, highkey useful. 🎀

🌈 FILES 🌈

The /dev/mlx5ctl devfs(4) node is used to pass commands to the driver. That's the whole vibe check for file paths.

👑 RETURN VALUES 👑

If successful, the IOCTL returns zero. Otherwise, -1 is returned and the global variable errno is set to indicate the error. No cap, that's the whole return-value story. Zero is slay; negative one plus errno is the error arc.

⭐ SEE ALSO ⭐

errno(2), ioctl(2), mlx5en(4), mlx5ib(4), mlx5tool(8) and pci(9). Go read the squad. 🫶

---

mwah 💋 and that's the cute sign-off: the source/version says Debian, the date is October 2, 2019, and the page is mlx5io(4). Slay, bestie. 💖