gdb/python: Add gdb.Architecture.registers method

This commit adds a new method gdb.Architecture.registers that returns
an object of the new type gdb.RegisterDescriptorIterator.  This
iterator returns objects of the new type gdb.RegisterDescriptor.

A RegisterDescriptor is not a way to read the value of a register,
this is already covered by Frame.read_register, a RegisterDescriptor
is simply a way to discover from Python, which registers are
available for a given architecture.

I did consider just returning a string, the name of each register,
instead of a RegisterDescriptor, however, I'm aware that it we don't
want to break the existing Python API in any way, so if I return just
a string now, but in the future we want more information about a
register then we would have to add a second API to get that
information.  By going straight to a descriptor object now, it is easy
to add additional properties in the future should we wish to.

Right now the only property of a register that a user can access is
the name of the register.

In future we might want to be able to ask the register about is
register groups, or its type.

gdb/ChangeLog:

	* Makefile.in (SUBDIR_PYTHON_SRCS): Add py-registers.c
	* python/py-arch.c (archpy_registers): New function.
	(arch_object_methods): Add 'registers' method.
	* python/py-registers.c: New file.
	* python/python-internal.h
	(gdbpy_new_register_descriptor_iterator): Declare.
	(gdbpy_initialize_registers): Declare.
	* python/python.c (do_start_initialization): Call
	gdbpy_initialize_registers.
	* NEWS: Mention additions to the Python API.

gdb/testsuite/ChangeLog:

	* gdb.python/py-arch-reg-names.exp: New file.

gdb/doc/ChangeLog:

	* python.texi (Python API): Add new section the menu.
	(Frames In Python): Add new @anchor.
	(Architectures In Python): Document new registers method.
	(Registers In Python): New section.

1 files changed, 87 insertions, 0 deletions

diff --git a/gdb/testsuite/gdb.python/py-arch-reg-names.exp b/gdb/testsuite/gdb.python/py-arch-reg-names.exp
new file mode 100644
index 0000000..14bc0a8
--- /dev/null
+++ b/gdb/testsuite/gdb.python/py-arch-reg-names.exp
@@ -0,0 +1,87 @@
+# Copyright 2020 Free Software Foundation, Inc.
+
+# 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/>.
+
+# Check the gdb.Architecture.registers functionality.
+
+load_lib gdb-python.exp
+standard_testfile py-arch.c
+
+if { [prepare_for_testing "failed to prepare" ${testfile} ${srcfile}] } {
+    return -1
+}
+
+# Skip all tests if Python scripting is not enabled.
+if { [skip_python_tests] } { continue }
+
+if ![runto_main] {
+   return -1
+}
+
+# First, use 'info registers' to get a list of register names.
+set regs {}
+gdb_test_multiple "info registers general" "info registers general" {
+    -re "^info registers general\r\n" {
+	exp_continue
+    }
+    -re "^(\[^ \t\]+)\[ \t\]+\[^\r\n\]+\r\n" {
+	set reg $expect_out(1,string)
+	lappend regs $reg
+	exp_continue
+    }
+    -re "^$gdb_prompt " {
+    }
+}
+gdb_assert {[llength $regs] > 0} \
+    "Found at least one register"
+
+# Now get the same register names using Python API.
+gdb_py_test_silent_cmd \
+    "python frame = gdb.selected_frame()" "get frame" 0
+gdb_py_test_silent_cmd \
+    "python arch = frame.architecture()" "get arch" 0
+gdb_py_test_silent_cmd \
+    "python regs = list (arch.registers (\"general\"))" \
+    "get general registers" 0
+gdb_py_test_silent_cmd \
+    "python regs = map (lambda r : r.name, regs)" \
+    "get names of general registers" 0
+
+set py_regs {}
+gdb_test_multiple "python print (\"\\n\".join (regs))" \
+    "general register from python" {
+	-re "^python print \[^\r\n\]+\r\n" {
+	    exp_continue
+	}
+	-re "^(\[^\r\n\]+)\r\n" {
+	    set reg $expect_out(1,string)
+	    lappend py_regs $reg
+	    exp_continue
+	}
+	-re "^$gdb_prompt " {
+	}
+    }
+
+gdb_assert {[llength $py_regs] > 0} \
+    "Found at least one register from python"
+gdb_assert {[llength $py_regs] == [llength $regs]} \
+    "Same numnber of registers found"
+
+set found_non_match 0
+for { set i 0 } { $i < [llength $regs] } { incr i } {
+    if {[lindex $regs $i] != [lindex $py_regs $i]} {
+	set found_non_match 1
+    }
+}
+gdb_assert { $found_non_match == 0 } "all registers match"