Provide a guide for developers on how to debug code with a focus on the
media subsystem. This document aims to provide a rough overview over the
possibilities and a rational to help choosing the right tool for the
given circumstances.

Signed-off-by: Sebastian Fricke <sebastian.fricke@collabora.com>
---
 Documentation/process/debugging/index.rst          |   1 +
 .../debugging/media_specific_debugging_guide.rst   | 178 +++++++++++++++++++++
 2 files changed, 179 insertions(+)

diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst
index c200ede7c955..322e33d65ca3 100644
--- a/Documentation/process/debugging/index.rst
+++ b/Documentation/process/debugging/index.rst
@@ -10,6 +10,7 @@ Debugging advice for Linux Kernel developers
    general_advice
    driver_development_debugging_guide
    userspace_debugging_guide
+   media_specific_debugging_guide
 
 .. only::  subproject and html
 
diff --git a/Documentation/process/debugging/media_specific_debugging_guide.rst b/Documentation/process/debugging/media_specific_debugging_guide.rst
new file mode 100644
index 000000000000..ab840e695af9
--- /dev/null
+++ b/Documentation/process/debugging/media_specific_debugging_guide.rst
@@ -0,0 +1,178 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================
+Debugging and tracing in the media subsystem
+============================================
+
+This document serves as a starting point and lookup for debugging device
+drivers in the media subsystem and to debug these drivers from userspace.
+
+.. contents::
+    :depth: 3
+
+General debugging advice
+------------------------
+
+For general advice see the :doc:`/process/debugging/general_advice`.
+
+The following sections show you some of the available tools.
+
+dev_debug module parameter
+--------------------------
+
+Every video device provides a `dev_debug` parameter, which allows to get
+further insights into the IOCTLs in the background.::
+
+  # cat /sys/class/video4linux/video3/name
+  rkvdec
+  # echo 0xff > /sys/class/video4linux/video3/dev_debug
+  # dmesg -wH
+  [...] videodev: v4l2_open: video3: open (0)
+  [  +0.000036] video3: VIDIOC_QUERYCAP: driver=rkvdec, card=rkvdec,
+  bus=platform:rkvdec, version=0x00060900, capabilities=0x84204000,
+  device_caps=0x04204000
+
+For the full documentation see :ref:`driver-api/media/v4l2-dev:video device debugging`
+
+dev_dbg / v4l2_dbg
+------------------
+
+Two debug print statements, which are specific for devices and for the v4l2
+subsystem, avoid adding these to your final submission unless they have
+long-term value for investigations.
+
+For a general overview please see the
+:ref:`process/debugging/driver_development_debugging_guide:printk & friends`
+guide.
+
+- Difference between both?
+
+  - v4l2_dbg utilizes v4l2_printk under the hood, which further uses printk
+    directly, thus it cannot be targeted by dynamic debug
+  - dev_dbg can be targeted by dynamic debug
+  - v4l2_dbg has a more specific prefix format for the media subsystem, while
+    dev_dbg only highlights the driver name and the location of the log
+
+Dynamic debug
+-------------
+
+A method to trim down the debug output to your needs.
+
+For general advice see the
+:ref:`process/debugging/userspace_debugging_guide:dynamic debug` guide.
+
+Here is one example, that enables all available pr_debug()'s within the file::
+
+  $ alias ddcmd='echo $* > /proc/dynamic_debug/control'
+  $ ddcmd '-p; file v4l2-h264.c +p'
+  $ grep =p /proc/dynamic_debug/control
+   drivers/media/v4l2-core/v4l2-h264.c:372 [v4l2_h264]print_ref_list_b =p
+   "ref_pic_list_b%u (cur_poc %u%c) %s"
+   drivers/media/v4l2-core/v4l2-h264.c:333 [v4l2_h264]print_ref_list_p =p
+   "ref_pic_list_p (cur_poc %u%c) %s\n"
+
+Ftrace
+------
+
+An internal kernel tracer that can trace static predefined events, function
+calls, etc. Very useful for debugging problems without changing the kernel and
+understanding the behavior of subsystems.
+
+For general advice see the
+:ref:`process/debugging/userspace_debugging_guide:ftrace` guide.
+
+DebugFS
+-------
+
+This tool allows you to dump or modify internal values of your driver to files
+in a custom filesystem.
+
+For general advice see the
+:ref:`process/debugging/driver_development_debugging_guide:debugfs` guide.
+
+Perf & alternatives
+-------------------
+
+Tools to measure the various stats on a running system to diagnose issues.
+
+For general advice see the
+:ref:`process/debugging/userspace_debugging_guide:perf & alternatives` guide.
+
+Example for media devices:
+
+Gather statistics data for a decoding job: (This example is on a RK3399 SoC
+with the rkvdec codec driver using the `fluster test suite
+<https://github.com/fluendo/fluster>`__)::
+
+  perf stat -d python3 fluster.py run -d GStreamer-H.264-V4L2SL-Gst1.0 -ts
+  JVT-AVC_V1 -tv AUD_MW_E -j1
+  ...
+  Performance counter stats for 'python3 fluster.py run -d
+  GStreamer-H.264-V4L2SL-Gst1.0 -ts JVT-AVC_V1 -tv AUD_MW_E -j1 -v':
+
+         7794.23 msec task-clock:u                     #    0.697 CPUs utilized
+               0      context-switches:u               #    0.000 /sec
+               0      cpu-migrations:u                 #    0.000 /sec
+           11901      page-faults:u                    #    1.527 K/sec
+       882671556      cycles:u                         #    0.113 GHz                         (95.79%)
+       711708695      instructions:u                   #    0.81  insn per cycle              (95.79%)
+        10581935      branches:u                       #    1.358 M/sec                       (15.13%)
+         6871144      branch-misses:u                  #   64.93% of all branches             (95.79%)
+       281716547      L1-dcache-loads:u                #   36.144 M/sec                       (95.79%)
+         9019581      L1-dcache-load-misses:u          #    3.20% of all L1-dcache accesses   (95.79%)
+ <not supported>      LLC-loads:u
+ <not supported>      LLC-load-misses:u
+
+    11.180830431 seconds time elapsed
+
+     1.502318000 seconds user
+     6.377221000 seconds sys
+
+The availability of events and metrics depends on the system you are running.
+
+Error checking & panic analysis
+-------------------------------
+
+Various Kernel configuration options to enhance error detection of the Linux
+Kernel with the cost of lowering performance.
+
+For general advice see the
+:ref:`process/debugging/driver_development_debugging_guide:kasan, ubsan,
+lockdep and other error checkers` guide.
+
+Driver verification with v4l2-compliance
+----------------------------------------
+
+To verify, that a driver adheres to the v4l2 API, the tool v4l2-compliance is
+used, which is part of the `v4l_utils
+<https://git.linuxtv.org/v4l-utils.git>`__, a suite of userspace tools to work
+with the media subsystem.
+
+To see the detailed media topology (and check it) use::
+
+  v4l2-compliance -M /dev/mediaX --verbose
+
+You can also run a full compliance check for all devices referenced in the
+media topology with::
+
+  v4l2-compliance -m /dev/mediaX
+
+Debugging problems with receiving video
+---------------------------------------
+
+Implementing vidioc_log_status in the driver: this can log the current status
+to the kernel log. It's called by v4l2-ctl --log-status. Very useful for
+debugging problems with receiving video (TV/S-Video/HDMI/etc) since the video
+signal is external (so unpredictable). Less useful with camera sensor inputs
+since you have control over what the camera sensor does.
+
+Usually you can just assign the default::
+
+  .vidioc_log_status  = v4l2_ctrl_log_status,
+
+But you can also create your own callback, to create a custom status log.
+
+You can find an example in the cobalt driver
+(`drivers/media/pci/cobalt/cobalt-v4l2.c <https://elixir.bootlin.com/linux/v6.11.6/source/drivers/media/pci/cobalt/cobalt-v4l2.c#L567>`__).
+
+**Copyright** ©2024 : Collabora

-- 
2.25.1

Sebastian Fricke <sebastian.fricke@collabora.com> writes:

> Provide a guide for developers on how to debug code with a focus on the
> media subsystem. This document aims to provide a rough overview over the
> possibilities and a rational to help choosing the right tool for the
> given circumstances.
>
> Signed-off-by: Sebastian Fricke <sebastian.fricke@collabora.com>
> ---
>  Documentation/process/debugging/index.rst          |   1 +
>  .../debugging/media_specific_debugging_guide.rst   | 178 +++++++++++++++++++++
>  2 files changed, 179 insertions(+)

Mostly overall comments here

- much of what's here seems redundant with your other new documents; you
  seem to be going over the same list of tools?  Why not just talk about
  the ones that are unique to the media subsystem?

- Please use the function() convention throughout.

- Back in the ancient past when I was writing V4L2 drivers, one of my
  biggest problems was figuring out why applications weren't getting
  what they expected.  The vivi driver was most useful for finding
  subtle differences...  One would use vivid now, but I suspect the
  utility remains.

Thanks,

jon

Hey Jon,

On 07.11.2024 13:40, Jonathan Corbet wrote:
>Sebastian Fricke <sebastian.fricke@collabora.com> writes:
>
>> Provide a guide for developers on how to debug code with a focus on the
>> media subsystem. This document aims to provide a rough overview over the
>> possibilities and a rational to help choosing the right tool for the
>> given circumstances.
>>
>> Signed-off-by: Sebastian Fricke <sebastian.fricke@collabora.com>
>> ---
>>  Documentation/process/debugging/index.rst          |   1 +
>>  .../debugging/media_specific_debugging_guide.rst   | 178 +++++++++++++++++++++
>>  2 files changed, 179 insertions(+)
>
>Mostly overall comments here
>
>- much of what's here seems redundant with your other new documents; you
>  seem to be going over the same list of tools?  Why not just talk about
>  the ones that are unique to the media subsystem?

I choosed the minimum duplication path because of the perspective that I
envisioned of the reader.
The reader reads that there is a debugging guide for the media
subsystem, which to my ears sounds like:
"Everything you need to know to get started debugging in this subsystem,
with recommendations for useful tools"
and not
"Some specific media bits that expect you to have read every other
debugging documentation and judge yourself which of these tools might be
useful for your debugging".

I look at that specifically from a perspective that the general
debugging guides are probably going to be extended in the future with
more general debugging tools which might not be as useful for the media
subsystem.

>
>- Please use the function() convention throughout.

Ack. I assume you also mean the titles as well.

>
>- Back in the ancient past when I was writing V4L2 drivers, one of my
>  biggest problems was figuring out why applications weren't getting
>  what they expected.  The vivi driver was most useful for finding
>  subtle differences...  One would use vivid now, but I suspect the
>  utility remains.

Okay I'll look into that.

>
>Thanks,
>
>jon
>
Regards,

Sebastian Fricke

Hey Jonathan,

On 08.11.2024 11:12, Sebastian Fricke wrote:
>Hey Jon,
>
>On 07.11.2024 13:40, Jonathan Corbet wrote:
>>Sebastian Fricke <sebastian.fricke@collabora.com> writes:
>>
>>>Provide a guide for developers on how to debug code with a focus on the
>>>media subsystem. This document aims to provide a rough overview over the
>>>possibilities and a rational to help choosing the right tool for the
>>>given circumstances.
>>>
>>>Signed-off-by: Sebastian Fricke <sebastian.fricke@collabora.com>
>>>---
>>> Documentation/process/debugging/index.rst          |   1 +
>>> .../debugging/media_specific_debugging_guide.rst   | 178 +++++++++++++++++++++
>>> 2 files changed, 179 insertions(+)
>>
>>Mostly overall comments here
>>
>>- much of what's here seems redundant with your other new documents; you
>> seem to be going over the same list of tools?  Why not just talk about
>> the ones that are unique to the media subsystem?
>
>I choosed the minimum duplication path because of the perspective that I
>envisioned of the reader.
>The reader reads that there is a debugging guide for the media
>subsystem, which to my ears sounds like:
>"Everything you need to know to get started debugging in this subsystem,
>with recommendations for useful tools"
>and not
>"Some specific media bits that expect you to have read every other
>debugging documentation and judge yourself which of these tools might be
>useful for your debugging".
>
>I look at that specifically from a perspective that the general
>debugging guides are probably going to be extended in the future with
>more general debugging tools which might not be as useful for the media
>subsystem.

@Jon: Does that sound reasonable to you? Or should I rework the page? I
think this is especially interesting for the audio debugging guide as
well, because this determines how subsystem specific guides should be
formatted.

Regards,
Sebastian

>
>>
>>- Please use the function() convention throughout.
>
>Ack. I assume you also mean the titles as well.
>
>>
>>- Back in the ancient past when I was writing V4L2 drivers, one of my
>> biggest problems was figuring out why applications weren't getting
>> what they expected.  The vivi driver was most useful for finding
>> subtle differences...  One would use vivid now, but I suspect the
>> utility remains.
>
>Okay I'll look into that.
>
>>
>>Thanks,
>>
>>jon
>>
>Regards,
>
>Sebastian Fricke
>

Sebastian Fricke <sebastian.fricke@collabora.com> writes:

> Hey Jonathan,
>
> On 08.11.2024 11:12, Sebastian Fricke wrote:
>>Hey Jon,
>>
>>On 07.11.2024 13:40, Jonathan Corbet wrote:
>>>Sebastian Fricke <sebastian.fricke@collabora.com> writes:
>>>
>>>>Provide a guide for developers on how to debug code with a focus on the
>>>>media subsystem. This document aims to provide a rough overview over the
>>>>possibilities and a rational to help choosing the right tool for the
>>>>given circumstances.
>>>>
>>>>Signed-off-by: Sebastian Fricke <sebastian.fricke@collabora.com>
>>>>---
>>>> Documentation/process/debugging/index.rst          |   1 +
>>>> .../debugging/media_specific_debugging_guide.rst   | 178 +++++++++++++++++++++
>>>> 2 files changed, 179 insertions(+)
>>>
>>>Mostly overall comments here
>>>
>>>- much of what's here seems redundant with your other new documents; you
>>> seem to be going over the same list of tools?  Why not just talk about
>>> the ones that are unique to the media subsystem?
>>
>>I choosed the minimum duplication path because of the perspective that I
>>envisioned of the reader.
>>The reader reads that there is a debugging guide for the media
>>subsystem, which to my ears sounds like:
>>"Everything you need to know to get started debugging in this subsystem,
>>with recommendations for useful tools"
>>and not
>>"Some specific media bits that expect you to have read every other
>>debugging documentation and judge yourself which of these tools might be
>>useful for your debugging".
>>
>>I look at that specifically from a perspective that the general
>>debugging guides are probably going to be extended in the future with
>>more general debugging tools which might not be as useful for the media
>>subsystem.
>
> @Jon: Does that sound reasonable to you? Or should I rework the page? I
> think this is especially interesting for the audio debugging guide as
> well, because this determines how subsystem specific guides should be
> formatted.

I would suggest trying to minimize the amount of duplicated material;
more duplication is more work to maintain and inevitably goes out of
sync.  That said, I don't want to send you around in too many circles on
this; and would not try to require such a change.  It's a suggestion;
get the docs to where you're happy with them and we'll be glad to take
them.

Thanks,

jon