Documentation/gpu/amdgpu/display/dc-debug.rst

   1 ========================
   2 Display Core Debug tools
   3 ========================
   4
   5 DC Visual Confirmation
   6 ======================
   7
   8 Display core provides a feature named visual confirmation, which is a set of
   9 bars added at the scanout time by the driver to convey some specific
  10 information. In general, you can enable this debug option by using::
  11
  12   echo <N> > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm
  13
  14 Where `N` is an integer number for some specific scenarios that the developer
  15 wants to enable, you will see some of these debug cases in the following
  16 subsection.
  17
  18 Multiple Planes Debug
  19 ---------------------
  20
  21 If you want to enable or debug multiple planes in a specific user-space
  22 application, you can leverage a debug feature named visual confirm. For
  23 enabling it, you will need::
  24
  25   echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm
  26
  27 You need to reload your GUI to see the visual confirmation. When the plane
  28 configuration changes or a full update occurs there will be a colored bar at
  29 the bottom of each hardware plane being drawn on the screen.
  30
  31 * The color indicates the format - For example, red is AR24 and green is NV12
  32 * The height of the bar indicates the index of the plane
  33 * Pipe split can be observed if there are two bars with a difference in height
  34   covering the same plane
  35
  36 Consider the video playback case in which a video is played in a specific
  37 plane, and the desktop is drawn in another plane. The video plane should
  38 feature one or two green bars at the bottom of the video depending on pipe
  39 split configuration.
  40
  41 * There should **not** be any visual corruption
  42 * There should **not** be any underflow or screen flashes
  43 * There should **not** be any black screens
  44 * There should **not** be any cursor corruption
  45 * Multiple plane **may** be briefly disabled during window transitions or
  46   resizing but should come back after the action has finished
  47
  48 Pipe Split Debug
  49 ----------------
  50
  51 Sometimes we need to debug if DCN is splitting pipes correctly, and visual
  52 confirmation is also handy for this case. Similar to the MPO case, you can use
  53 the below command to enable visual confirmation::
  54
  55   echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm
  56
  57 In this case, if you have a pipe split, you will see one small red bar at the
  58 bottom of the display covering the entire display width and another bar
  59 covering the second pipe. In other words, you will see a bit high bar in the
  60 second pipe.
  61
  62 DTN Debug
  63 =========
  64
  65 DC (DCN) provides an extensive log that dumps multiple details from our
  66 hardware configuration. Via debugfs, you can capture those status values by
  67 using Display Test Next (DTN) log, which can be captured via debugfs by using::
  68
  69   cat /sys/kernel/debug/dri/0/amdgpu_dm_dtn_log
  70
  71 Since this log is updated accordingly with DCN status, you can also follow the
  72 change in real-time by using something like::
  73
  74   sudo watch -d cat /sys/kernel/debug/dri/0/amdgpu_dm_dtn_log
  75
  76 When reporting a bug related to DC, consider attaching this log before and
  77 after you reproduce the bug.
  78
  79 DMUB Firmware Debug
  80 ===================
  81
  82 Sometimes, dmesg logs aren't enough. This is especially true if a feature is
  83 implemented primarily in DMUB firmware. In such cases, all we see in dmesg when
  84 an issue arises is some generic timeout error. So, to get more relevant
  85 information, we can trace DMUB commands by enabling the relevant bits in
  86 `amdgpu_dm_dmub_trace_mask`.
  87
  88 Currently, we support the tracing of the following groups:
  89
  90 Trace Groups
  91 ------------
  92
  93 .. csv-table::
  94    :header-rows: 1
  95    :widths: 1, 1
  96    :file: ./trace-groups-table.csv
  97
  98 **Note: Not all ASICs support all of the listed trace groups**
  99
 100 So, to enable just PSR tracing you can use the following command::
 101
 102   # echo 0x8020 > /sys/kernel/debug/dri/0/amdgpu_dm_dmub_trace_mask
 103
 104 Then, you need to enable logging trace events to the buffer, which you can do
 105 using the following::
 106
 107   # echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_dmcub_trace_event_en
 108
 109 Lastly, after you are able to reproduce the issue you are trying to debug,
 110 you can disable tracing and read the trace log by using the following::
 111
 112   # echo 0 > /sys/kernel/debug/dri/0/amdgpu_dm_dmcub_trace_event_en
 113   # cat /sys/kernel/debug/dri/0/amdgpu_dm_dmub_tracebuffer
 114
 115 So, when reporting bugs related to features such as PSR and ABM, consider
 116 enabling the relevant bits in the mask before reproducing the issue and
 117 attach the log that you obtain from the trace buffer in any bug reports that you
 118 create.