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 --gpu, -g <asicname>(@<instance> | =<pcidevice>)
15 Select a gpu by ASIC name and either the instance number or the
16 PCI bus identifier. For instance, "raven1@1" would pick the
17 raven1 device in the 2nd DRI instance slot. Similarly,
18 "raven1=0000:06:00.0" would pick a raven1 device with the PCI
19 bus address '0000:06:00.0'.
20 --instance, -i <number>
22 Pick a device instance to work with. Defaults to the 0'th
23 device. The instance refers to a directory under /sys/ker‐
24 nel/debug/dri/ where 0 is the first card probed.
25 --force, -f <number>
27 Force a PCIE Device ID in hex or by asic name. This is used in
28 case the amdgpu driver is not yet loaded or a display is not yet
29 attached. A '@' prefix will specify a path to
30 an NPI script, for instance, '@/home/user/device.npi'. A '.'
31 prefix will specify a virtual device which is handy for looking
32 up register decodings for a device not present in the system,
33 for instance, '.vega10'.
34 --pci <device>
36 Force a specific PCI device using the domain:bus:slot.function
37 format in hex. This is useful when more than one GPU is avail‐
38 able. If the amdgpu driver is loaded the corresponding instance
39 will be automatically detected.
40 --update, -u <filename>
42 Specify update file to add, change, or delete registers from the
43 register database. Useful for adding registers that are not
44 including in the kernel headers.
45 --option, -O <string>[,<string>,...]
48 Specify options to the tool. Multiple options can be specified
49 as comma separated strings. Options should be specified before
50 --update or --force commands (among others) to enable options
51 specified.
52 quiet
54 Disable various informative but not required (for function‐
55 ality) outputs.
56 read_smc
58 Enable scanning of SMC registers.
59 bits
61 enables displaying bitfields for scanned blocks.
62 bitsfull
64 enables displaying bitfields using their entire path for
65 scanned blocks.
66 empty_log
68 Empties the MMIO log after reading it.
69 follow
71 Causes the --logscan command to repeatedly produce output
72 without
73 exiting.
74 no_follow_ib
76 Instruct the --ring command to not attempt to follow IBs
77 pointed to by the packets
78 in the ring.
79 named
81 Causes --read to print out the register name with the reg‐
82 ister
83 value.
84 many
86 Allows matching regname openly (used with --read) and
87 implies
88 "named". For instance "*.dce100.CRTC" would match any reg‐
89 ister that
90 contains the fragment "CRTC" in the name.
91 use_pci
93 Enable PCI access for MMIO instead of using debugfs. Used
94 by the --read,
95 --scan, --top, --write, and --write-bit commands. Does not
96 currently
97 support multiple instances of the same GPU (PCI device ID).
98 Note that access
99 to non-MMIO registers might be disabled when using this
100 flag.
101 use_colour
103 Enable colour output for --top command, scales from blue,
104 green, yellow, to red. Also
105 accepted is 'use_color'.
106 no_kernel
108 Disable using kernel files to access the device. Implies
109 ''use_pci''. This is meant to
110 be used only if the KMD is hung or otherwise not working
111 correctly. Using it on live systems
112 may result in race conditions.
113 verbose
115 Enable verbose diagnostics (used in --vram).
116 halt_waves
118 Halt/resume all waves while reading wave status.
119 disasm_early_term
121 Terminate shader disassembly when first s_endpgm is hit.
122 This is required for
123 older UMDs (or non-mesa UMDs) that don't use the quintuple
124 0xBF9F0000 to signal the true
125 end of a shader.
126 no_disasm
128 Disable shader disassembler logic (still outputs text just
129 doesn't use LLVM to decode). Useful
130 if the linked llvm-dev doesn't support the hardware being
131 debugged. Avoids segfualts/asserts.
132 disasm_anyways
134 Enable shader disassembly in --waves even if the rings
135 aren't halted.
136 wave64
138 Enable full 64 wave disassembly
139 full_shader
141 Enable full shader disassembly in --waves when '-O bits' is
142 used and the shader is found in
143 a gfx or compute ring.
144
147 --bank, -b <se> <sh> <instance>
148 Select a GRBM se/sh/instance bank in decimal. Can use 'x' to
149 denote a broadcast selection.
150 --sbank, -sb <me> <pipe> <queue> [vmid]
152 Select a SRBM me/pipe/queue bank in decimal. VMID is optional
153 (default: 0).
154 --cbank, -cb <context_reg_bank>
156 Select a context register bank (value is multiplied by 0x1000).
157 Used for context registers in the range 0xA000..0xAFFF.
158
160 --config, -c
161 Print out configuation data read from kernel driver.
162 --enumerate, -e
164 Enumerate all AMDGPU supported devices.
165 --list-blocks -lb
167 List all blocks attached to the asic that has been detected.
168 --list-regs, -lr <string>
170 List all registers in an IP block (can use '-O bits' to list
171 bitfields)
172
175 --lookup, -lu <address_or_regname> <number>
176 Look up an MMIO register by address and bitfield decode the
177 value specified (with 0x prefix) or by register name. The reg‐
178 ister name string must include the ipname, e.g., uvd6.mmUVD_CON‐
179 TEXT_ID.
180 --write -w <string> <number>
182 Write a value specified in hex to a register specified with a
183 complete register path in the form < asicname.ipname.regname >.
184 For example, fiji.uvd6.mmUVD_CGC_GATE. The value of asicname
185 and/or ipname can be * to simplify scripting. This command can
186 be used multiple times to write to multiple registers in a sin‐
187 gle invocation.
188 --writebit -wb <string> <number>
190 Write a value specified in hex to a register bitfield specified
191 with a complete register path as in the --write command.
192 --read, -r <string>
194 Read a value from a register specified by a register path to
195 stdout. This command uses the same syntax as the --write com‐
196 mand but also allows * for the regname field to read an entire
197 block. Additionally, a * can be appended to a register name to
198 read any register that contains a partial match. For instance,
199 "*.vcn10.ADDR*" would read any register from the 'VCN10' block
200 which contains 'ADDR' in the name.
201 --scan, -s <string>
203 Scan and print an IP block by name, for example, uvd6 or car‐
204 rizo.uvd6. Can be used multiple times in a single invocation.
205
208 --top, -t
209 Summarize GPU utilization. Can select a SE block with --bank.
210 Relevant options that apply are: use_colour and use_pci
211 --waves, -wa [ <ring_name> | <vmid>@<addr>.<size> ]
213 Print out information about any active CU waves. Note that if
214 GFX power gating is enabled this command may result in a GPU
215 hang. It's unlikely unless you're invoking it very rapidly.
216 Unlike the wave count reading in --top this command will operate
217 regardless of whether GFX PG is enabled or not. Can use bits to
218 decode the wave bitfields. An optional ring name can be speci‐
219 fied (default: gfx) to search for pointers to active shaders to
220 find extra debugging information. Alternatively, an IB can be
221 specified by a vmid, address, and size (in hex bytes) triplet.
222 --profiler, -prof [pixel= | vertex= | compute=]<nsamples> [ring]
224 Capture 'nsamples' samples of wave data. Optionally specify a
225 ring to use when searching for IBs that point to shaders.
226 Defaults to 'gfx'. Additionally, the type of shader can be
227 selected for as well to only profile a given type of shader.
228
231 VMIDs are specified in umr as 16 bit numbers where the lower 8 bits
232 indicate the hardware VMID and the upper 8 bits indicate the which VM
233 space to use.
234 0 - GFX hub
236 1 - MM hub
238 2 - VC0 hub
240 3 - VC1 hub
242 For instance, 0x107 would specify the 7'th VMID on the MM hub.
245 --vm-decode, -vm vmid@<address> <num_of_pages>
249 Decode page mappings at a specified address (in hex) from the
250 VMID specified. The VMID can be specified in hexadecimal (with
251 leading '0x') or in decimal. Implies '-O verbose' for the dura‐
252 tion of the command so does not require it to be manually speci‐
253 fied.
254 --vm-read, -vr [vmid@]<address> <size>
257 Read 'size' bytes (in hex) from the address specified (in hexa‐
258 decimal) from VRAM to stdout. Optionally specify the VMID (in
259 decimal or in hex with a 0x prefix) treating the address as a
260 virtual address instead. Can use 'use_pci' to directly access
261 VRAM.
262 --vm-write, -vw [vmid@]<address> <size>
265 Write 'size' bytes (in hex) to the address specified (in hexa‐
266 decimal) to VRAM from stdin.
267 --vm-disasm, -vdis [<vmid>@]<address> <size>
270 Disassemble 'size' bytes (in hex) from a given address (in hex).
271 The size can be specified as zero to have umr try and compute
272 the shader size.
273
276 --ring, -R <string>[range]
277 Read the contents of the ring named by the string
278 amdgpu_ring_<string>, i.e. without the amdgpu_ring prefix. By
279 default it reads and prints the entire ring. A range is
280 optional and has the format '[start:end]'. The starting and end‐
281 ing address are non-negative integers or the '.' (dot) symbol,
282 which indicates the rptr when on the left side and wptr when on
283 the right side of the range. For instance, "-R gfx" prints the
284 entire gfx ring, "-R gfx[0:16]" prints the contents from 0 to 16
285 inclusively, and "-R gfx[.]" or "-R gfx[.:.]" prints the range
286 [rptr,wptr]. When one of the range limits is a number while the
287 other is the dot, '.', then the number indicates the relative
288 range before or after the corresponding ring pointer. For
289 instance, "-R sdma0[16:.]" prints [wptr-16, wptr] words of the
290 SDMA0 ring, and "-R sdma1[.:32]" prints [rptr, rptr+32] double-
291 words of the SDMA1 ring. The contents of the ring is always
292 interpreted, if it can be interpreted.
293 --dump-ib, -di [vmid@]address length [pm]
295 Dump an IB packet at an address with an optional VMID. The
296 length is specified in bytes. The type of decoder <pm> is
297 optional and defaults to PM4 packets. Can specify '3' for SDMA
298 packets.
299 --dump-ib-file, -df filename [pm]
301 Dump an IB stored in a file as a series of hexadecimal DWORDS
302 one per line. Optionally supply a PM type, can specify '3' for
303 SDMA IBs or '4' for PM4 IBs. The default is PM4.
304 --logscan, -ls
306 Read and display contents of the MMIO register log. Usually
307 specified with '-O bits,follow,empty_log' to enable continual
308 dumping of the trace log.
309
312 - The "Waves" field in the DRM section of --top only works if GFX PG
313 has been disabled. Otherwise, GPU hangs occur frequently. When PG is
314 enabled it will read a constant 0.
315
318 UMR_LOGGER
319 Directory to output "umr.log" file when capturing samples with the
320 --top command.
321AMD (c) 2019 August 2019 UMR(1)