- How do I start my HSAIL program?
- How do I set breakpoints in my HSAIL program?
- How do I single step in a HSAIL kernel?
- How do I print HSAIL registers?
- How do I view HSAIL dispatch info?
- How do I debug SNACK Applications?
- Generating Logs for Reporting Issues in hsail-gdb
- Others
For matrix multiplication, you can specify the kernel name
(gdb) break hsail:&__OpenCL_matrixMul_kernel
This will stop the application's execution just before the HSAIL kernel (in this case, the matrix multiplication kernel) begins executing on the device.
To set a general HSAIL kernel function breakpoint, use either of the following command:
(gdb) break hsail(gdb) break hsail:*
This will stop the application just before every dispatch begins executing on the device.
#### Setting HSAIL Kernel Source Breakpoints In order to break into HSAIL kernels, you need to set HSAIL source breakpoints. Hsail-gdb saves the kernel source for the present dispatch to a temporary file called *temp_source*. HSAIL source breakpoints can be set by specifying the line number from the *temp_source* HSAIL source file. The *temp_source* file is overwritten by hsail-gdb on every dispatch.Once you hit a kernel function breakpoint, you can view the temp_source file and choose a line number. You can set the source breakpoint using the syntax
break hsail:line_number
For example, this will set a breakpoint at line 150 in the temp_source
(gdb) b hsail:150
HSAIL breakpoint 1 (PC:0x08d0 mad_u32 $s0, $s1, $s0, $s3; temp_source@line 150)
When you continue the program's execution, the application will stop when any work-item reaches line 150 in temp_source.
#### Setting Conditional HSAIL Kernel Source Breakpoints Conditional HSAIL breakpoints allow you to stop the application only when a particular workitem hits a breakpoint. You can set a conditional source breakpoint by specifying the a work-item using the syntax: * `break hsail:line_number if wg:x,y,z wi:x,y,z` For example, this will set a breakpoint at line 150 and only stop the application if the work-item in workgroup 2,0,0 and local work-item 1,0,0 ``` (gdb) b hsail:150 if wg:2,0,0 wi:16,0,0 HSAIL breakpoint 1 (PC:0x08d0 mad_u32 $s0, $s1, $s0, $s3; temp_source@line 150) ``` When the application is executed, the dispatch will stop when line 150 is executed for the above workitem as shown below:[hsail-gdb]: Switching to work-group (2,0,0) and work-item (1,0,0)
[hsail-gdb]: Condition: active work-group: 2, 0, 0 @ work-item: 1, 0, 0
[hsail-gdb]: Breakpoint 2 at mad_u32 $s0, $s1, $s0, $s3; temp_source@line 150
Stopped on HSAIL breakpoint
(gdb) info bre
Num Type Disp Enb Address What
1 HSAIL breakpoint keep y --- Every HSAIL dispatch(*)
breakpoint already hit 2 times
4 HSAIL breakpoint keep y PC:0x06d8 add_u32 $s3, $s3, 1; temp_source@line 150
breakpoint already hit 320 times
5 HSAIL breakpoint keep y --- &__Gdt_vectoradd_kernel
6 breakpoint keep y 0x0000000000407105 in RunTest() at MultiKernelDispatch.cpp:100
- You can also delete HSAIL breakpoints using the same command as GDB's host breakpoints
del breakpoint_number
The following shows how hsail-gdb steps 4 source lines after hitting a kernel source breakpoint
(gdb) b hsail:50
HSAIL breakpoint 4 (PC:0x022c ld_kernarg_align(8)_width(all)_u64 $d1, [%inputA]; temp_source@line 50)
(gdb) c
Continuing.
[New Thread 0x7ffeeddcb700 (LWP 13642)]
Waiting for completion...
[hsail-gdb]: Breakpoint: 4 at ld_kernarg_align(8)_width(all)_u64 $d1, [%inputA];
Stopped on HSAIL breakpoint
[Switching to Thread 0x7ffeeddcb700 (LWP 13642)]
(gdb) step
[hsail-gdb]: Breakpoint: at line 52
Stopped on HSAIL breakpoint
(gdb) s
[hsail-gdb]: Breakpoint: at line 53
Stopped on HSAIL breakpoint
(gdb) s
[hsail-gdb]: Breakpoint: at line 54
Stopped on HSAIL breakpoint
(gdb) c
Continuing.
This will print the value $register_name for a single work-item. For example, printing HSAIL register $s0 will provide the value of register $s0
(gdb) print hsail:$s0
$4 = 0
To view the data of a different work-item, you need switch focus between different work-items. The hsail thread command allows you to set the focus on a different work-item by specifying its work-item and work-group ID. It should be noted that you cannot switch focus to work-items not scheduled on the device.
Switching the focus to another work-item and printing $s0 allows us to view data for the other work-item.
(gdb) hsail thread wg:0,0,0 wi:1,0,0
[hsail-gdb]: Switching to work-group (0,0,0) and work-item (1,0,0)
(gdb) print hsail:$s0
$3 = 1
This will print all the possible options for info hsail. The info hsail command allows you to view information about the active dispatch, active work-groups and active work-items on the device.
The possible inputs to info hsail are below
info hsail [kernels]: print all HSAIL kernel dispatches
info hsail [kernel <kernel name>]: print all HSAIL kernel dispatches with a specific kernel name
info hsail [work-groups | wgs]: print all HSAIL work-group items
info hsail [work-group <flattened id> | wg <flattened id> | work-group <x,y,z> | wg <x,y,z>]: print a specific HSAIL work-group item
info hsail [work-item | wi]: print the focus HSAIL work-item
info hsail [work-item <x,y,z> | wi <x,y,z>]: print a specific HSAIL work-item
For example, info hsail kernels on an application that dispatches two kernels shows
(gdb) info hsail kernels
Kernels info
Index KernelName DispatchCount # of Work-groups Work-group Dimensions
0 &__Gdt_vectoradd_kernel 1 1,1,1 64,1,1
*1 &__OpenCL_matrixMul_kernel 1 8,5,1 16,16,1
The info hsail work-groups command will show the active work-groups for the active dispatch
(gdb) info hsail work-groups
Index Work-group ID Flattened Work-group ID
*0 0,0,0 0
1 1,0,0 1
2 2,0,0 2
The info hsail work-item command will show the focus work-item for the active dispatch
(gdb) info hsail wi
Information for Work-item
Index Wavefront ID Work-item ID Absolute Work-item ID PC Source line
*0 0x408002e0 0, 0, 0 0, 0, 0 0x6d8 temp_source@line 150
This can be done adding the environment variable below before calling the buildrun.sh script for the SNACK applications.
export LIBHSAIL_OPTIONS_APPEND="-g -include-source"
You can then debug the SNACK application just like the other HSAIL applications described above.
### Generating Logs for Reporting Issues in hsail-gdb Additional log files can be generated by hsail-gdb. These log files should be sent to the hsail-gdb developers to allow them to diagnose issues. Logging is enabled with the `HSAIL_GDB_ENABLE_LOG` environment variable as shown belowexport HSAIL_GDB_ENABLE_LOG='DebugLogs'
hsail-gdb MatrixMul
The environment variable enables logging and provides a prefix for the log file names.
As the MatrixMul application executes, log files with the prefix DebugLogs_ will be generated.
The log files generated include logs from GDB, the HSA debug Agent and the HSA code objects used in the applications. Each debug session's log file's name will include a unique SessionID.