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.

gdb/python/py-arch.c

@@ -226,6 +226,28 @@ archpy_disassemble (PyObject *self, PyObject *args, PyObject *kw)
   return result_list.release ();
 }
 
+/* Implementation of gdb.Architecture.registers (self, reggroup) -> Iterator.
+   Returns an iterator over register descriptors for registers in GROUP
+   within the architecture SELF.  */
+
+static PyObject *
+archpy_registers (PyObject *self, PyObject *args, PyObject *kw)
+{
+  static const char *keywords[] = { "reggroup", NULL };
+  struct gdbarch *gdbarch = NULL;
+  const char *group_name = NULL;
+
+  /* Parse method arguments.  */
+  if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "|s", keywords,
+					&group_name))
+    return NULL;
+
+  /* Extract the gdbarch from the self object.  */
+  ARCHPY_REQUIRE_VALID (self, gdbarch);
+
+  return gdbpy_new_register_descriptor_iterator (gdbarch, group_name);
+}
+
 /* Initializes the Architecture class in the gdb module.  */
 
 int
@@ -249,6 +271,11 @@ Return the name of the architecture as a string value." },
     "disassemble (start_pc [, end_pc [, count]]) -> List.\n\
 Return a list of at most COUNT disassembled instructions from START_PC to\n\
 END_PC." },
+  { "registers", (PyCFunction) archpy_registers,
+    METH_VARARGS | METH_KEYWORDS,
+    "registers ([ group-name ]) -> Iterator.\n\
+Return an iterator of register descriptors for the registers in register\n\
+group GROUP-NAME." },
   {NULL}  /* Sentinel */
 };