1UMR(1) User Manuals UMR(1)
2
6 umr - AMDGPU Userspace Register Debugger
7
9 umr is a tool to read and display, as well as write to AMDGPU device
10 MMIO, PCIE, SMC, and DIDT registers via userspace. It can autodetect
11 and scan AMDGPU devices (SI and up).
12
14 --instance, -i <number>
15 Pick a device instance to work with. Defaults to the 0'th
16 device. The instance refers to a directory under /sys/ker‐
17 nel/debug/dri/ where 0 is the first card probed.
18 --force, -f <number>
20 Force a PCIE Device ID in hex or by asic name. This is used in
21 case the amdgpu driver is not yet loaded or a display is not yet
22 attached. A '@' prefix will specify a path to
23 an NPI script, for instance, '@/home/user/device.npi'. A '.'
24 prefix will specify a virtual device which is handy for looking
25 up register decodings for a device not present in the system,
26 for instance, '.vega10'.
27 --pci <device>
29 Force a specific PCI device using the domain:bus:slot.function
30 format in hex. This is useful when more than one GPU is avail‐
31 able. If the amdgpu driver is loaded the corresponding instance
32 will be automatically detected.
33 --update, -u <filename>
35 Specify update file to add, change, or delete registers from the
36 register database. Useful for adding registers that are not
37 including in the kernel headers.
38 --option, -O <string>[,<string>,...]
41 Specify options to the tool. Multiple options can be specified
42 as comma separated strings. Options should be specified before
43 --update or --force commands (among others) to enable options
44 specified.
45 quiet
47 Disable various informative but not required (for function‐
48 ality) outputs.
49 read_smc
51 Enable scanning of SMC registers.
52 bits
54 enables displaying bitfields for scanned blocks.
55 bitsfull
57 enables displaying bitfields using their entire path for
58 scanned blocks.
59 empty_log
61 Empties the MMIO log after reading it.
62 follow
64 Causes the --logscan command to repeatedly produce output
65 without
66 exiting.
67 no_follow_ib
69 Instruct the --ring command to not attempt to follow IBs
70 pointed to by the packets
71 in the ring.
72 named
74 Causes --read to print out the register name with the reg‐
75 ister
76 value.
77 many
79 Allows matching regname openly (used with --read) and
80 implies
81 "named". For instance "*.dce100.CRTC" would match any reg‐
82 ister that
83 contains the fragment "CRTC" in the name.
84 use_pci
86 Enable PCI access for MMIO instead of using debugfs. Used
87 by the --read,
88 --scan, --top, --write, and --write-bit commands. Does not
89 currently
90 support multiple instances of the same GPU (PCI device ID).
91 Note that access
92 to non-MMIO registers might be disabled when using this
93 flag.
94 use_colour
96 Enable colour output for --top command, scales from blue,
97 green, yellow, to red. Also
98 accepted is 'use_color'.
99 no_kernel
101 Disable using kernel files to access the device. Implies
102 ''use_pci''. This is meant to
103 be used only if the KMD is hung or otherwise not working
104 correctly. Using it on live systems
105 may result in race conditions.
106 verbose
108 Enable verbose diagnostics (used in --vram).
109 halt_waves
111 Halt/resume all waves while reading wave status.
112 disasm_early_term
114 Terminate shader disassembly when first s_endpgm is hit.
115 This is required for
116 older UMDs (or non-mesa UMDs) that don't use the quintuple
117 0xBF9F0000 to signal the true
118 end of a shader.
119 no_disasm
121 Disable shader disassembler logic (still outputs text just
122 doesn't use LLVM to decode). Useful
123 if the linked llvm-dev doesn't support the hardware being
124 debugged. Avoids segfualts/asserts.
125 disasm_anyways
127 Enable shader disassembly in --waves even if the rings
128 aren't halted.
129
132 --bank, -b <se> <sh> <instance>
133 Select a GRBM se/sh/instance bank in decimal. Can use 'x' to
134 denote a broadcast selection.
135 --sbank, -sb <me> <pipe> <queue>
137 Select a SRBM me/pipe/queue bank in decimal.
138
140 --config, -c
141 Print out configuation data read from kernel driver.
142 --enumerate, -e
144 Enumerate all AMDGPU supported devices.
145 --list-blocks -lb
147 List all blocks attached to the asic that has been detected.
148 --list-regs, -lr <string>
150 List all registers in an IP block (can use '-O bits' to list
151 bitfields)
152
155 --lookup, -lu <address_or_regname> <number>
156 Look up an MMIO register by address and bitfield decode the
157 value specified (with 0x prefix) or by register name. The reg‐
158 ister name string must include the ipname, e.g., uvd6.mmUVD_CON‐
159 TEXT_ID.
160 --write -w <string> <number>
162 Write a value specified in hex to a register specified with a
163 complete register path in the form < asicname.ipname.regname >.
164 For example, fiji.uvd6.mmUVD_CGC_GATE. The value of asicname
165 and/or ipname can be * to simplify scripting. This command can
166 be used multiple times to write to multiple registers in a sin‐
167 gle invocation.
168 --writebit -wb <string> <number>
170 Write a value specified in hex to a register bitfield specified
171 with a complete register path as in the --write command.
172 --read, -r <string>
174 Read a value from a register specified by a register path to
175 stdout. This command uses the same syntax as the --write com‐
176 mand but also allows * for the regname field to read an entire
177 block. Additionally, a * can be appended to a register name to
178 read any register that contains a partial match. For instance,
179 "*.vcn10.ADDR*" would read any register from the 'VCN10' block
180 which contains 'ADDR' in the name.
181 --scan, -s <string>
183 Scan and print an IP block by name, for example, uvd6 or car‐
184 rizo.uvd6. Can be used multiple times in a single invocation.
185
188 --top, -t
189 Summarize GPU utilization. Can select a SE block with --bank.
190 Relevant options that apply are: use_colour and use_pci
191 --waves, -wa <ring_name>
193 Print out information about any active CU waves. Note that if
194 GFX power gating is enabled this command may result in a GPU
195 hang. It's unlikely unless you're invoking it very rapidly.
196 Unlike the wave count reading in --top this command will operate
197 regardless of whether GFX PG is enabled or not. Can use bits to
198 decode the wave bitfields. An optional ring name can be speci‐
199 fied (default: gfx) to search for pointers to active shaders to
200 find extra debugging information.
201 --profiler, -prof [pixel= | vertex= | compute=]<nsamples> [ring]
203 Capture 'nsamples' samples of wave data. Optionally specify a
204 ring to use when searching for IBs that point to shaders.
205 Defaults to 'gfx'. Additionally, the type of shader can be
206 selected for as well to only profile a given type of shader.
207
210 VMIDs are specified in umr as 16 bit numbers where the lower 8 bits
211 indicate the hardware VMID and the upper 8 bits indicate the which VM
212 space to use.
213 0 - GFX hub 1 - MM hub
215 For instance, 0x107 would specify the 7'th VMID on the MM hub.
217 --vm-decode, -vm vmid@<address> <num_of_pages>
221 Decode page mappings at a specified address (in hex) from the
222 VMID specified. The VMID can be specified in hexadecimal (with
223 leading '0x') or in decimal. Implies '-O verbose' for the dura‐
224 tion of the command so does not require it to be manually speci‐
225 fied.
226 --vm-read, -vr [vmid@]<address> <size>
229 Read 'size' bytes (in hex) from the address specified (in hexa‐
230 decimal) from VRAM to stdout. Optionally specify the VMID (in
231 decimal or in hex with a 0x prefix) treating the address as a
232 virtual address instead. Can use 'use_pci' to directly access
233 VRAM.
234 --vm-write, -vw [vmid@]<address> <size>
237 Write 'size' bytes (in hex) to the address specified (in hexa‐
238 decimal) to VRAM from stdin.
239 --vm-disasm, -vdis [<vmid>@]<address> <size>
242 Disassemble 'size' bytes (in hex) from a given address (in hex).
243 The size can be specified as zero to have umr try and compute
244 the shader size.
245
248 --ring, -R <string>(from:to)
249 Read the contents of a ring named by the string without the
250 amdgpu_ring_ prefix. By default it will read and display the
251 entire ring. A starting and ending address can be specified in
252 decimal or a '.' can be used to indicate relative to the current
253 wptr pointer. For example, "-R gfx" would read the entire gfx
254 ring, "-R gfx[0:16]" would display the contents from 0 to 16
255 inclusively, and "-R gfx[.]" or "-R gfx[.:.]" would display the
256 last 32 words relative to rptr.
257 --dump-ib, -di [vmid@]address length [pm]
259 Dump an IB packet at an address with an optional VMID. The
260 length is specified in bytes. The type of decoder <pm> is
261 optional and defaults to PM4 packets. Can specify '3' for SDMA
262 packets.
263 --logscan, -ls
265 Read and display contents of the MMIO register log. Usually
266 specified with '-O bits,follow,empty_log' to enable continual
267 dumping of the trace log.
268
271 - The "Waves" field in the DRM section of --top only works if GFX PG
272 has been disabled. Otherwise, GPU hangs occur frequently. When PG is
273 enabled it will read a constant 0.
274
277 UMR_LOGGER
278 Directory to output "umr.log" file when capturing samples with the
279 --top command.
280AMD (c) 2018 January 2018 UMR(1)