gdb/gdbarch: add a comment to gdbarch_register_name

After the previous commit, this commit sets out to formalise the API
for gdbarch_register_name.  Not every architecture is actually in
compliance with the API I set out here, but I believe that most are.

I think architectures that don't comply with the API laid out here
will fail the gdb.base/completion.exp test.

The claims in the comment are I feel, best demonstrated with the
asserts in this code:

  const char *
  gdbarch_register_name (struct gdbarch *gdbarch, int regnr)
  {
    gdb_assert (regnr >= 0);
    gdb_assert (regnr < gdbarch_num_cooked_regs (gdbarch));

    const char *name = gdbarch->register_name (gdbarch, regnr);

    gdb_assert (name != nullptr);

    return name;
  }

Like I said, I don't believe every architecture follows these rules
right now, which is why I'm not actually adding any asserts.  Instead,
this commit adds a comment to gdbarch_register_name, this comment is
where I'd like to get to, rather than where we are right now.

Subsequent commits will fix all targets to be in compliance with this
comment, and will even add the asserts shown above to
gdbarch_register_name.

diff --git a/gdb/gdbarch-components.py b/gdb/gdbarch-components.py
index 6374240ae4b568ae3af6d25e1ef635fe9d3a3a4e..9e0a3e99417aa99f2e7bbd8dd20f0776cf11250e 100644 (file)
--- a/gdb/gdbarch-components.py
+++ b/gdb/gdbarch-components.py
@@ -558,6 +558,13 @@ Return -1 for bad REGNUM.  Note: Several targets get this wrong.
 )
 
 Method(
+    comment="""
+Return the name of register REGNR for the specified architecture.
+REGNR can be any value greater than, or equal to zero, and less than
+'gdbarch_num_cooked_regs (GDBARCH)'.  If REGNR is not supported for
+GDBARCH, then this function will return an empty string, this function
+should never return nullptr.
+""",
     type="const char *",
     name="register_name",
     params=[("int", "regnr")],

diff --git a/gdb/gdbarch-gen.h b/gdb/gdbarch-gen.h
index 706dbb3befe1632e22c2b2ff8e8e9de2dffe8f91..383d84f814275b96eee51ec323f680c24fb9ae72 100644 (file)
--- a/gdb/gdbarch-gen.h
+++ b/gdb/gdbarch-gen.h
@@ -288,6 +288,12 @@ typedef int (gdbarch_dwarf2_reg_to_regnum_ftype) (struct gdbarch *gdbarch, int d
 extern int gdbarch_dwarf2_reg_to_regnum (struct gdbarch *gdbarch, int dwarf2_regnr);
 extern void set_gdbarch_dwarf2_reg_to_regnum (struct gdbarch *gdbarch, gdbarch_dwarf2_reg_to_regnum_ftype *dwarf2_reg_to_regnum);
 
+/* Return the name of register REGNR for the specified architecture.
+   REGNR can be any value greater than, or equal to zero, and less than
+   'gdbarch_num_cooked_regs (GDBARCH)'.  If REGNR is not supported for
+   GDBARCH, then this function will return an empty string, this function
+   should never return nullptr. */
+
 typedef const char * (gdbarch_register_name_ftype) (struct gdbarch *gdbarch, int regnr);
 extern const char * gdbarch_register_name (struct gdbarch *gdbarch, int regnr);
 extern void set_gdbarch_register_name (struct gdbarch *gdbarch, gdbarch_register_name_ftype *register_name);