****************************** QDMA Debug File System Support ****************************** debugfs is a file system interface, which the kernel drivers uses to expose debug information to the user space. Unlike sysfs, there is no structure or rules on what to publish through this interface.debugfs files are created in /sys/kernel/debug/ folder. debugfs supports: - Files with assigned file operations. These file interfaces can be either read-only or read/write. - Files to export single integer that can be read-only or read/write - Read-only data blob files. QDMA Kernel driver uses this facility and exposes qdma information similar to ``dma-ctl`` user space application. The advantage of debugfs is that users need not depend on user space application but if they integrate the ``libqdma`` in kernel space driver, it comes along with this debug facility. During PF/VF module loading, QDMA driver creates PF/VF directories in ``/sys/kernel/debug`` by the names ``qdma_pf`` and ``qdma_vf``. qdma_pf directory will list all the detected primary functions, similarly qdma_vf will list all virtual functions. :: /sys/kernel/debug/qdma_pf /sys/kernel/debug/qdma_vf In driver module initialization, during PCIe probe, when a device that is to be handled by QDMA driver is detected, a directory with the name b:d.f format will be created in qdma_ directory. Ex: when qdma device 01000 is detected, a directory is created in qdma_pf ``/sys/kernel/debug/qdma_pf/0000\:01\:00\.0/`` Below files and directories are created during the device initialization. - **qdma_info** : This file will give all the information specific to the device. For example, function number, is master PF, Q base and Qmax configured for the device etc. - **qdma_regs**: This file will dump all the registers corresponding to the device. The registers are the configuration space and user space of the device. These also include global registers, which are common across all the devices. - **queues**: This is the directory and is created to hold queues information attached to the device. The qdma_dev_conf structure will also hold pointer to this directory in dbgfs_queues_root, which would help to create queue information when a queue is added to the device. - **qdma_reg_info**: This file will dump all the registers with the individual field breakdown for all the registers. Note that the support is for QDMA4.0 and for the Config Bar registers only. :: /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/qdma_info /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/qdma_regs /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/dma_reg_info /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/intr_rings /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/queues When a queue is added to a QDMA device, per say, through dma-ctl, a directory with the qid is created in the corresponding ``queues`` directory of the device. This will be used to create further directories under ‘qid’ directory. For example, if a queue with qid 2 is added to device qdma01000, the directory with name ‘2’ is created in queues directory :: /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/queues/2 When a queue is added to a QDMA device, a direction directory with the name corresponding to the direction, c2h, h2c and cmpt, is created under qid directory. - If the queue is added in H2C direction, directory with name ``h2c`` is created in the corresponding qid directory. - If C2H queue is added, then directory with name ``c2h`` is created in the corresponding queue directory. If C2H queue is added in streaming mode, then a ``cmpt`` directory is also added to the qid directory. - If queue is added in bidirectional mode, then both ``c2h`` and ``h2c`` directories are created in the corresponding qid directory - Lastly, if a bidirectional queues are added in streaming mode, then a ‘cmpt’ directory is also created in the respective qid directory. For example, if a queue with qid 2 is created in bi direction ST, then all c2h, h2c and cmpt directories are created :: /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/queues/2/h2c /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/queues/2/c2h /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/queues/2/cmpt - **info**: This file holds the information specific to the queue, for example if queue is on line etc - **cntxt**: This file will dump the contexts corresponding the queue. ``cntxt`` in ``cmpt`` directory will only dump the C2H ST completion context. - **desc**: This file will dump the descriptor contents of the ring. :: /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/queues/2/h2c/info /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/queues/2/h2c/cntxt /sys/kernel/debug/qdma_pf/0000\:01\:00\.0/queues/2/h2c/desc use ``cat`` command for displaying the contents of these leaf node debug files. Example is provided below. :: [xilinx@]# cat cntxt SOFTWARE CTXT: Interrupt Aggregation 0x1 1 Ring Index 0x0 0 Descriptor Ring Base Addr (High) 0x0 0 Descriptor Ring Base Addr (Low) 0x34048000 872710144 Is Memory Mapped 0x0 0 Marker Disable 0x0 0 IRQ Request 0x0 0 Writeback Error Sent 0x0 0 Error 0x0 0 Interrupt No Last 0x0 0 Port Id 0x0 0 Interrupt Enable 0x1 1 Writeback Enable 0x1 1 MM Channel 0x0 0 Bypass Enable 0x0 0 Descriptor Size 0x1 1 Ring Size 0x9 9 Fetch Max 0x0 0 Address Translation 0x0 0 Write back/Intr Interval 0x1 1 Write back/Intr Check 0x1 1 Fetch Credit Enable 0x0 0 Queue Enable 0x1 1 Function Id 0x0 0 IRQ Arm 0x1 1 PIDX 0x40a 1034 HARDWARE CTXT: Fetch Pending 0x0 0 Eviction Pending 0x0 0 Queue Invalid No Desc Pending 0x1 1 Descriptors Pending 0x1 1 Credits Consumed 0x0 0 CIDX 0x40a 1034