1========================
  2Display Core Debug tools
  3========================
  4
  5DC Visual Confirmation
  6======================
  7
  8Display core provides a feature named visual confirmation, which is a set of
  9bars added at the scanout time by the driver to convey some specific
 10information. In general, you can enable this debug option by using::
 11
 12  echo <N> > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm
 13
 14Where `N` is an integer number for some specific scenarios that the developer
 15wants to enable, you will see some of these debug cases in the following
 16subsection.
 17
 18Multiple Planes Debug
 19---------------------
 20
 21If you want to enable or debug multiple planes in a specific user-space
 22application, you can leverage a debug feature named visual confirm. For
 23enabling it, you will need::
 24
 25  echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm
 26
 27You need to reload your GUI to see the visual confirmation. When the plane
 28configuration changes or a full update occurs there will be a colored bar at
 29the 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
 36Consider the video playback case in which a video is played in a specific
 37plane, and the desktop is drawn in another plane. The video plane should
 38feature one or two green bars at the bottom of the video depending on pipe
 39split 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
 48Pipe Split Debug
 49----------------
 50
 51Sometimes we need to debug if DCN is splitting pipes correctly, and visual
 52confirmation is also handy for this case. Similar to the MPO case, you can use
 53the below command to enable visual confirmation::
 54
 55  echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm
 56
 57In this case, if you have a pipe split, you will see one small red bar at the
 58bottom of the display covering the entire display width and another bar
 59covering the second pipe. In other words, you will see a bit high bar in the
 60second pipe.
 61
 62DTN Debug
 63=========
 64
 65DC (DCN) provides an extensive log that dumps multiple details from our
 66hardware configuration. Via debugfs, you can capture those status values by
 67using 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
 71Since this log is updated accordingly with DCN status, you can also follow the
 72change in real-time by using something like::
 73
 74  sudo watch -d cat /sys/kernel/debug/dri/0/amdgpu_dm_dtn_log
 75
 76When reporting a bug related to DC, consider attaching this log before and
 77after you reproduce the bug.
 78
 79DMUB Firmware Debug
 80===================
 81
 82Sometimes, dmesg logs aren't enough. This is especially true if a feature is
 83implemented primarily in DMUB firmware. In such cases, all we see in dmesg when
 84an issue arises is some generic timeout error. So, to get more relevant
 85information, we can trace DMUB commands by enabling the relevant bits in
 86`amdgpu_dm_dmub_trace_mask`.
 87
 88Currently, we support the tracing of the following groups:
 89
 90Trace 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
100So, 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
104Then, you need to enable logging trace events to the buffer, which you can do
105using the following::
106
107  # echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_dmcub_trace_event_en
108
109Lastly, after you are able to reproduce the issue you are trying to debug,
110you 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
115So, when reporting bugs related to features such as PSR and ABM, consider
116enabling the relevant bits in the mask before reproducing the issue and
117attach the log that you obtain from the trace buffer in any bug reports that you
118create.