gdb/python: add gdb.format_address function

Add a new function, gdb.format_address, which is a wrapper around
GDB's print_address function.

This method takes an address, and returns a string with the format:

  ADDRESS <SYMBOL+OFFSET>

Where, ADDRESS is the original address, formatted as hexadecimal,
SYMBOL is a symbol with an address lower than ADDRESS, and OFFSET is
the offset from SYMBOL to ADDRESS in decimal.

If there's no SYMBOL suitably close to ADDRESS then the
<SYMBOL+OFFSET> part is not included.

This is useful if a user wants to write a Python script that
pretty-prints addresses, the user no longer needs to do manual symbol
lookup, or worry about correctly formatting addresses.

Additionally, there are some settings that effect how GDB picks
SYMBOL, and whether the file name and line number should be included
with the SYMBOL name, the gdb.format_address function ensures that the
users Python script also benefits from these settings.

The gdb.format_address by default selects SYMBOL from the current
inferiors program space, and address is formatted using the
architecture for the current inferior.  However, a user can also
explicitly pass a program space and architecture like this:

  gdb.format_address(ADDRESS, PROGRAM_SPACE, ARCHITECTURE)

In order to format an address for a different inferior.

Notes on the implementation:

In py-arch.c I extended arch_object_to_gdbarch to add an assertion for
the type of the PyObject being worked on.  Prior to this commit all
uses of arch_object_to_gdbarch were guaranteed to pass this function a
gdb.Architecture object, but, with this commit, this might not be the
case.

So, with this commit I've made it a requirement that the PyObject be a
gdb.Architecture, and this is checked with the assert.  And in order
that callers from other files can check if they have a
gdb.Architecture object, I've added the new function
gdbpy_is_architecture.

In py-progspace.c I've added two new function, the first
progspace_object_to_program_space, converts a PyObject of type
gdb.Progspace to the associated program_space pointer, and
gdbpy_is_progspace checks if a PyObject is a gdb.Progspace or not.

gdb/python/py-arch.c

@@ -62,16 +62,25 @@ arch_object_data_init (struct gdbarch *gdbarch)
 }
 
 /* Returns the struct gdbarch value corresponding to the given Python
-   architecture object OBJ.  */
+   architecture object OBJ, which must be a gdb.Architecture object.  */
 
 struct gdbarch *
 arch_object_to_gdbarch (PyObject *obj)
 {
-  arch_object *py_arch = (arch_object *) obj;
+  gdb_assert (gdbpy_is_architecture (obj));
 
+  arch_object *py_arch = (arch_object *) obj;
   return py_arch->gdbarch;
 }
 
+/* See python-internal.h.  */
+
+bool
+gdbpy_is_architecture (PyObject *obj)
+{
+  return PyObject_TypeCheck (obj, &arch_object_type);
+}
+
 /* Returns the Python architecture object corresponding to GDBARCH.
    Returns a new reference to the arch_object associated as data with
    GDBARCH.  */

gdb/python/py-progspace.c

@@ -504,6 +504,23 @@ pspace_to_pspace_object (struct program_space *pspace)
   return gdbpy_ref<>::new_reference (result);
 }
 
+/* See python-internal.h.  */
+
+struct program_space *
+progspace_object_to_program_space (PyObject *obj)
+{
+  gdb_assert (gdbpy_is_progspace (obj));
+  return ((pspace_object *) obj)->pspace;
+}
+
+/* See python-internal.h.  */
+
+bool
+gdbpy_is_progspace (PyObject *obj)
+{
+  return PyObject_TypeCheck (obj, &pspace_object_type);
+}
+
 void _initialize_py_progspace ();
 void
 _initialize_py_progspace ()

gdb/python/python-internal.h

@@ -497,6 +497,13 @@ struct symtab_and_line *sal_object_to_symtab_and_line (PyObject *obj);
 struct frame_info *frame_object_to_frame_info (PyObject *frame_obj);
 struct gdbarch *arch_object_to_gdbarch (PyObject *obj);
 
+/* Convert Python object OBJ to a program_space pointer.  OBJ must be a
+   gdb.Progspace reference.  Return nullptr if the gdb.Progspace is not
+   valid (see gdb.Progspace.is_valid), otherwise return the program_space
+   pointer.  */
+
+extern struct program_space *progspace_object_to_program_space (PyObject *obj);
+
 void gdbpy_initialize_gdb_readline (void);
 int gdbpy_initialize_auto_load (void)
   CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION;
@@ -838,4 +845,13 @@ typedef std::unique_ptr<Py_buffer, Py_buffer_deleter> Py_buffer_up;
 extern bool gdbpy_parse_register_id (struct gdbarch *gdbarch,
 				     PyObject *pyo_reg_id, int *reg_num);
 
+/* Return true if OBJ is a gdb.Architecture object, otherwise, return
+   false.  */
+
+extern bool gdbpy_is_architecture (PyObject *obj);
+
+/* Return true if OBJ is a gdb.Progspace object, otherwise, return false.  */
+
+extern bool gdbpy_is_progspace (PyObject *obj);
+
 #endif /* PYTHON_PYTHON_INTERNAL_H */

gdb/python/python.c

@@ -1294,6 +1294,107 @@ gdbpy_colorize_disasm (const std::string &content, gdbarch *gdbarch)
 
 
 
+/* Implement gdb.format_address(ADDR,P_SPACE,ARCH).  Provide access to
+   GDB's print_address function from Python.  The returned address will
+   have the format '0x..... <symbol+offset>'.  */
+
+static PyObject *
+gdbpy_format_address (PyObject *self, PyObject *args, PyObject *kw)
+{
+  static const char *keywords[] =
+    {
+      "address", "progspace", "architecture", nullptr
+    };
+  PyObject *addr_obj = nullptr, *pspace_obj = nullptr, *arch_obj = nullptr;
+  CORE_ADDR addr;
+  struct gdbarch *gdbarch = nullptr;
+  struct program_space *pspace = nullptr;
+
+  if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "O|OO", keywords,
+					&addr_obj, &pspace_obj, &arch_obj))
+    return nullptr;
+
+  if (get_addr_from_python (addr_obj, &addr) < 0)
+    return nullptr;
+
+  /* If the user passed None for progspace or architecture, then we
+     consider this to mean "the default".  Here we replace references to
+     None with nullptr, this means that in the following code we only have
+     to handle the nullptr case.  These are only borrowed references, so
+     no decref is required here.  */
+  if (pspace_obj == Py_None)
+    pspace_obj = nullptr;
+  if (arch_obj == Py_None)
+    arch_obj = nullptr;
+
+  if (pspace_obj == nullptr && arch_obj == nullptr)
+    {
+      /* Grab both of these from the current inferior, and its associated
+	 default architecture.  */
+      pspace = current_inferior ()->pspace;
+      gdbarch = current_inferior ()->gdbarch;
+    }
+  else if (arch_obj == nullptr || pspace_obj == nullptr)
+    {
+      /* If the user has only given one of program space or architecture,
+	 then don't use the default for the other.  Sure we could use the
+	 default, but it feels like there's too much scope of mistakes in
+	 this case, so better to require the user to provide both
+	 arguments.  */
+      PyErr_SetString (PyExc_ValueError,
+		       _("The architecture and progspace arguments must both be supplied"));
+      return nullptr;
+    }
+  else
+    {
+      /* The user provided an address, program space, and architecture.
+	 Just check that these objects are valid.  */
+      if (!gdbpy_is_progspace (pspace_obj))
+	{
+	  PyErr_SetString (PyExc_TypeError,
+			   _("The progspace argument is not a gdb.Progspace object"));
+	  return nullptr;
+	}
+
+      pspace = progspace_object_to_program_space (pspace_obj);
+      if (pspace == nullptr)
+	{
+	  PyErr_SetString (PyExc_ValueError,
+			   _("The progspace argument is not valid"));
+	  return nullptr;
+	}
+
+      if (!gdbpy_is_architecture (arch_obj))
+	{
+	  PyErr_SetString (PyExc_TypeError,
+			   _("The architecture argument is not a gdb.Architecture object"));
+	  return nullptr;
+	}
+
+      /* Architectures are never deleted once created, so gdbarch should
+	 never come back as nullptr.  */
+      gdbarch = arch_object_to_gdbarch (arch_obj);
+      gdb_assert (gdbarch != nullptr);
+    }
+
+  /* By this point we should know the program space and architecture we are
+     going to use.  */
+  gdb_assert (pspace != nullptr);
+  gdb_assert (gdbarch != nullptr);
+
+  /* Unfortunately print_address relies on the current program space for
+     its symbol lookup.  Temporarily switch now.  */
+  scoped_restore_current_program_space restore_progspace;
+  set_current_program_space (pspace);
+
+  /* Format the address, and return it as a string.  */
+  string_file buf;
+  print_address (gdbarch, addr, &buf);
+  return PyString_FromString (buf.c_str ());
+}
+
+
+
 /* Printing.  */
 
 /* A python function to write a single string using gdb's filtered
@@ -2445,6 +2546,13 @@ Return a list of all the architecture names GDB understands." },
     "connections () -> List.\n\
 Return a list of gdb.TargetConnection objects." },
 
+  { "format_address", (PyCFunction) gdbpy_format_address,
+    METH_VARARGS | METH_KEYWORDS,
+    "format_address (ADDRESS, PROG_SPACE, ARCH) -> String.\n\
+Format ADDRESS, an address within PROG_SPACE, a gdb.Progspace, using\n\
+ARCH, a gdb.Architecture to determine the address size.  The format of\n\
+the returned string is 'ADDRESS <SYMBOL+OFFSET>' without the quotes." },
+
   {NULL, NULL, 0, NULL}
 };