mlx5: add Corelens device and queue diagnostics

[aeschyl]

Summary

• Add an mlx5 Corelens module for device, network, RDMA, queue, CQ, EQ, and QP state.
• Support summary, full, and JSON output with filters and bounded descriptor dumps.
• Add package integration, API documentation, and tests.

Testing

• Verified summary runs with CTF and DWARF vmcores.

Orabug: 39751588

[brenns10]

I have mainly started reading the ancillary modules: drgn_tools.mlx5_support.*. I jumped around within them and flagged a few issues, but I was finding that to be unhelpful for understanding the code. So I pivoted and started from the CorelensModule and followed the logic of device discovery.

From what I can see, this PR discovers mlx5 devices in three different ways: (1) by enumerating netdevs and finding ones that look like mlx5 devices, (2) by enumerating RDMA devices and finding mlx5 devices, and (3) by trying global variables that might look like a global list. I think we can make the third one work universally by using a global list. Here's a minimal example of what I mean:

from typing import Iterator

from drgn import cast, container_of, NULL, Object, Program
from drgn.helpers.linux.list import list_for_each_entry
from drgn.helpers.common.format import escape_ascii_string

from drgn_tools.table import Table


def mlx5_netdev(mdev: Object) -> Object:
    """
    :param mdev: object of type ``struct mlx5_core_dev *``
    :returns: the corresponding ``struct net_device *`` or NULL
    """
    return mdev.mlx5e_res.uplink_netdev


def mlx5_core_ib_device(mdev: Object) -> Object:
    """
    Return the primary RDMA device for the MLX5 device. This does not include
    any special secondary devices.
    :param mdev: object of type ``struct mlx5_core_dev *``
    :returns: the corresponding ``struct ib_device *`` or NULL
    """
    prog = mdev.prog_
    MLX5_INTERFACE_PROTOCOL_IB = prog.constant("MLX5_INTERFACE_PROTOCOL_IB")
    ib_adev = mdev.priv.adev[MLX5_INTERFACE_PROTOCOL_IB]
    if not ib_adev:
        return NULL(prog, "struct ib_device *")

    mlx5_ib = cast("struct mlx5_ib_dev *", ib_adev.adev.dev.driver_data)
    if not mlx5_ib:
        return NULL(prog, "struct ib_device *")

    return mlx5_ib.ib_dev.address_of_()


def for_each_mlx5_core_dev(prog: Program) -> Iterator[Object]:
    """
    Iterate over all MLX5 devices on the system.
    :returns: an iterator of ``struct mlx5_core_dev *``
    """
    mlx5_driver = prog["mlx5_core_driver"]

    for knode in list_for_each_entry(
        "struct klist_node",
        mlx5_driver.driver.p.klist_devices.k_list.address_of_(),
        "n_node",
    ):
        dev_priv = container_of(
            knode, "struct device_private", "knode_driver"
        )
        pdev = container_of(dev_priv.device, "struct pci_dev", "dev")
        yield cast("struct mlx5_core_dev *", pdev.dev.driver_data)


def mlx5_report(prog: Program) -> None:
    table = Table(["MLX5_CORE_DEV", "NETDEV", "RDMA_DEV"])
    for mdev in for_each_mlx5_core_dev(prog):
        netdev = mlx5_netdev(mdev)
        netdev_name = escape_ascii_string(netdev.name.string_()) if netdev else "-"
        ibdev = mlx5_core_ib_device(mdev)
        ibdev_name = escape_ascii_string(ibdev.name.string_()) if ibdev else "-"
        table.row(hex(mdev), netdev_name, ibdev_name)
    table.write()


if __name__ == "__main__":
    mlx5_report(prog)

[brenns10]

I don't have any specific issue with the unit tests below. But the most important tests we want are:

1. mlx5 smoke test that runs on any vmcore (skip live kernels), and if the mlx5_core module is loaded, it runs the mlx5 report and prints it to stdout. This just verifies that the report does not crash.
2. For specific vmcores we can record a known good output and commit it to a file in git, then assert that the output matches.