Re: [PATCH] gdb: Implement stop-on-solib-events for GPU code objects

[Simon Marchi <simark@simark.ca>]

Hi Bratislav,

Some advice for future submissions:

 - Since this is v2, pass `-v2` to git-format-patch or git-send-email so
   that it inserts "v2" in the subject.

 - Set `format.useAutoBase` in your git config to make git record the
   base commit on which your patch is based.  This makes it easier to
   apply the patch.

   Ref: https://git-scm.com/docs/git-config#Documentation/git-config.txt-formatuseAutoBase

On 10/1/26 6:35 AM, Bratislav Filipovic wrote:
> GDB's "set stop-on-solib-events 1" setting allows users to stop execution
> when shared libraries are loaded or unloaded, enabling inspection and
> breakpoint placement before library code executes. This feature works for
> CPU shared libraries but is not working for GPU code objects loaded by the
> AMD ROCm runtime.
> 
> This commit implements stop-on-solib-events support for GPU code objects,
> making GPU code object load/unload events behave consistently with CPU
> shared library events.
> 
> The root cause is in amd_dbgapi_target_breakpoint::check_status(), which
> unconditionally sets bs->stop = 0 and bs->print_it = print_it_noop,
> regardless of the stop_on_solib_events setting. This is in contrast to
> internal_breakpoint::check_status() for CPU shared libraries, which
> respects the setting.
> 
> The fix includes:
> 
> 1. Generalize print_solib_event() function to eliminate code duplication
>    between CPU and GPU event printing. The function now accepts parameters
>    for event description, field names, and plural forms. This reduces
>    ~50 lines of duplicated code.
> 
> 2. Add code_object_list_updated flag to amd_dbgapi_inferior_info to track
>    when AMD_DBGAPI_EVENT_KIND_CODE_OBJECT_LIST_UPDATED events occur during
>    process_event_queue().

Point #2, not true anymore.

> diff --git a/gdb/NEWS b/gdb/NEWS
> index 77ad2d3fc22..957ba2e8563 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -3,6 +3,12 @@
>  
>  *** Changes since GDB 18
>  
> +* The 'set stop-on-solib-events' setting now applies to GPU code objects
> +  loaded by the AMD ROCm runtime, in addition to CPU shared libraries.
> +  When enabled (non-zero value), GDB will stop execution whenever GPU code

Remove `(non-zero value)`, since stop-on-solib-events is now a bool.

The MI changes should be documented in NEWS, in an "MI changes" section
(see past releases for an example).

> @@ -665,6 +682,29 @@ amd_dbgapi_target_breakpoint::check_status (struct bpstat *bs)
>  	   pulongest (resume_breakpoint_id.handle));
>  
>    amd_dbgapi_event_processed (resume_event_id);
> +
> +  /* If a CODE_OBJECT_LIST_UPDATED event was seen during event processing,
> +     check if the user requested to stop on solib events.  This implements
> +     stop-on-solib-events for GPU code objects.  */
> +  if (code_object_list_updated && stop_on_solib_events != 0)

Remove the `!= 0`, as stop_on_solib_events is now a bool.

> diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
> index 988737b6f96..05f55db6a7e 100644
> --- a/gdb/breakpoint.c
> +++ b/gdb/breakpoint.c
> @@ -5113,7 +5113,9 @@ print_bp_stop_message (bpstat *bs)
>  /* See breakpoint.h.  */
>  
>  void
> -print_solib_event (bool is_catchpoint)
> +print_solib_event (bool is_catchpoint, const char *event_description,
> +		   const char *plural_description, const char *item_field_name,
> +		   const char *object_kind)

Instead of passing all these `const char *`, I think it would be better
to centralize all the messages here.  One reason is that when we'll have
a second GPU target, we won't want to have it repeat the same GPU code
object strings.  Also, the strings for shared library are "hidden" as
default parameters to this function, in the header, which makes it hard
to follow.  Finally, having "decomposed" messages like this is not good
for translation, it's better to have full sentences.

I would suggest something like this.  In the header file:

---

/* Strings used by print_solib_event to describe a kind of loadable
   object.  */

struct print_solib_event_strings
{
  /* Message printed when objects were added or removed.  */
  const char *stopped_msg;

  /* Message printed when no objects were added or removed.  */
  const char *stopped_no_change_msg;

  /* MI field name for each item of the "added" and "removed" lists.  */
  const char *item_field_name;

  /* Value of the MI "object-kind" field.  */
  const char *object_kind;
};

/* Strings for shared libraries.  */

extern const print_solib_event_strings
  print_solib_event_strings_shared_library;

/* Strings for GPU code objects.  */

extern const print_solib_event_strings
  print_solib_event_strings_gpu_code_object;

/* A helper function that prints a shared library stopped event.
   IS_CATCHPOINT is true if the event is due to a "catch load"
   catchpoint, false otherwise.  */

extern void print_solib_event (bool is_catchpoint,
			       const print_solib_event_strings &strings);

---

In the source file:

---

/* See breakpoint.h.  */

const print_solib_event_strings print_solib_event_strings_shared_library =
{
  N_("Stopped due to shared library event:\n"),
  N_("Stopped due to shared library event (no libraries added or "
     "removed)\n"),
  "library",
  "shared-library"
};

/* See breakpoint.h.  */

const print_solib_event_strings print_solib_event_strings_gpu_code_object =
{
  N_("Stopped due to GPU code object event:\n"),
  N_("Stopped due to GPU code object event (no GPU code objects added or "
     "removed)\n"),
  "code-object",
  "gpu-code-object"
};

/* See breakpoint.h.  */

void
print_solib_event (bool is_catchpoint,
		   const print_solib_event_strings &strings)

---

And then in print_solib_event_strings you get the strings from the
`strings` parameter.  For the translated strings (those marked with N_),
pass them through the _ macro:

  if (!is_catchpoint)
    current_uiout->text (any_added || any_deleted
			 ? _(strings.stopped_msg)
			 : _(strings.stopped_no_change_msg));

And then in amd-dbgapi-target.c, the print_solib_event call would look
like:

  print_solib_event (false, print_solib_event_strings_gpu_code_object);

Same for the other calls, but they would pass the other object.

Just a note regarding the MI output, I think it's fine to add the
"object-kind" value so that a frontend could adjust its display if it
wants to say "GPU code objects" instead of "shared libraries".  However,
I would leave the existing "library" entry as-is.  The reason being that
frontends that do not know about this new GPU code object thing would
expect to see a "library" entry, so it would be a backwards incompatible
change.  Also, if you leave it as "library", existing frontends can work
just fine with GPU code objects (they'll present them as libraries),
since there's nothing fundamentally different between shared libraries
and GPU code objects in GDB, other than the name.

So I'd remove the "item_field_name" from the struct above.

Also, I would always emit the object-kind key, not just for GPU objects,
it's clearer that way.  It's not a breaking change to add an entry to a
dict (or whatever MI calls them).  Some tests will need to be updated
though, so adding this entry could perhaps be done as a preparatory
patch.

> diff --git a/gdb/testsuite/gdb.rocm/solib-event.exp b/gdb/testsuite/gdb.rocm/solib-event.exp
> new file mode 100644
> index 00000000000..f91b8d41995
> --- /dev/null
> +++ b/gdb/testsuite/gdb.rocm/solib-event.exp
> @@ -0,0 +1,112 @@
> +# Copyright 2026 Free Software Foundation, Inc.
> +# Copyright 2026 Advanced Micro Devices, Inc.

Remove AMD copyright.

> +
> +# This program is free software; you can redistribute it and/or modify
> +# it under the terms of the GNU General Public License as published by
> +# the Free Software Foundation; either version 3 of the License, or
> +# (at your option) any later version.
> +#
> +# This program is distributed in the hope that it will be useful,
> +# but WITHOUT ANY WARRANTY; without even the implied warranty of
> +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> +# GNU General Public License for more details.
> +#
> +# You should have received a copy of the GNU General Public License
> +# along with this program.  If not, see <http://www.gnu.org/licenses/>.
> +
> +# Test that "set stop-on-solib-events 1" works for GPU code objects.
> +# Tests both file:// events (hipModuleLoad) and memory:// events
> +# (hipModuleLoadData), as well as unload events (hipModuleUnload).
> +# Also tests that the default setting (0) does not stop execution.
> +
> +load_lib rocm.exp
> +
> +require allow_hip_tests
> +
> +standard_testfile .cpp
> +
> +# Build device module (.co file).
> +set kernel_srcfile ${testfile}-kernel.cpp
> +set hipmodule_path [standard_output_file ${testfile}.co]
> +
> +if {[gdb_compile $srcdir/$subdir/$kernel_srcfile \
> +     $hipmodule_path object \
> +     {debug hip additional_flags=--cuda-device-only}] != ""} {
> +    return
> +}

Since you have a "Build host executable" comment below, I would add a
"Build GPU code object" above this.

> +proc test_enabled {} {
> +    with_rocm_gpu_lock {
> +	clean_restart $::testfile
> +
> +	if {![runto_main -inferior-args $::hipmodule_path]} {
> +	    return
> +	}
> +
> +	gdb_breakpoint [gdb_get_line_number "Enable SOLIB events here"] -temporary
> +	gdb_continue_to_breakpoint "at enable solib-event"
> +
> +	gdb_test_no_output "set stop-on-solib-events 1"

Since stop-on-solib-events is now a bool, I would suggest using on/off
instead of 1/0 throughout.

It would be nice to have a test for the MI change.

> +
> +	with_test_prefix "file://" {
> +	    gdb_breakpoint "test_file_load" -temporary
> +	    gdb_continue_to_breakpoint "at test_file_load"
> +
> +	    # Test 1: file:// load event (hipModuleLoad).
> +	    gdb_test "continue" \
> +		"Stopped due to GPU code object event.*Inferior loaded file://\[^\r\n\]+" \
> +		"load"
> +
> +	    # Test 2: file:// unload event (hipModuleUnload).
> +	    gdb_test "continue" \
> +		"Stopped due to GPU code object event.*Inferior unloaded file://\[^\r\n\]+" \
> +		"unload"
> +	}
> +
> +	with_test_prefix "memory://" {
> +	    gdb_breakpoint "test_memory_load" -temporary
> +	    gdb_continue_to_breakpoint "at test_memory_load"
> +
> +	    # Test 3: memory:// load event (hipModuleLoadData).
> +	    gdb_test "continue" \
> +		"Stopped due to GPU code object event.*Inferior loaded memory://\[^\r\n\]+" \
> +		"load"
> +
> +	    # Test 4: memory:// unload event (hipModuleUnload).
> +	    gdb_test "continue" \
> +		"Stopped due to GPU code object event.*Inferior unloaded memory://\[^\r\n\]+" \
> +		"unload"
> +	}
> +    }

I don't know if we need a test for that, but how does it behave if we
have some code objects loaded and we let the host program terminate?
Does it fire some code object updated events?

Simon