This commit unifies all of the Python register lookup code (used by
Frame.read_register, PendingFrame.read_register, and
gdb.UnwindInfo.add_saved_register), and adds support for using a
gdb.RegisterDescriptor for register lookup.
Currently the register unwind code (PendingFrame and UnwindInfo) allow
registers to be looked up either by name, or by GDB's internal
number. I suspect the number was added for performance reasons, when
unwinding we don't want to repeatedly map from name to number for
every unwind. However, this kind-of sucks, it means Python scripts
could include GDB's internal register numbers, and if we ever change
this numbering in the future users scripts will break in unexpected
ways.
Meanwhile, the Frame.read_register method only supports accessing
registers using a string, the register name.
This commit unifies all of the register to register-number lookup code
in our Python bindings, and adds a third choice into the mix, the use
of gdb.RegisterDescriptor.
The register descriptors can be looked up by name, but once looked up,
they contain GDB's register number, and so provide all of the
performance benefits of using a register number directly. However, as
they are looked up by name we are no longer tightly binding the Python
API to GDB's internal numbering scheme.
As we may already have scripts in the wild that are using the register
numbers directly I have kept support for this in the API, but I have
listed this method last in the manual, and I have tried to stress that
this is NOT a good method to use and that users should use either a
string or register descriptor approach.
After this commit all existing Python code should function as before,
but users now have new options for how to identify registers.
gdb/ChangeLog:
* python/py-frame.c: Remove 'user-regs.h' include.
(frapy_read_register): Rewrite to make use of
gdbpy_parse_register_id.
* python/py-registers.c (gdbpy_parse_register_id): New function,
moved here from python/py-unwind.c. Updated the return type, and
also accepts register descriptor objects.
* python/py-unwind.c: Remove 'user-regs.h' include.
(pyuw_parse_register_id): Moved to python/py-registers.c.
(unwind_infopy_add_saved_register): Update to use
gdbpy_parse_register_id.
(pending_framepy_read_register): Likewise.
* python/python-internal.h (gdbpy_parse_register_id): Declare.
gdb/testsuite/ChangeLog:
* gdb.python/py-unwind.py: Update to make use of a register
descriptor.
gdb/doc/ChangeLog:
* python.texi (Unwinding Frames in Python): Update descriptions
for PendingFrame.read_register and
gdb.UnwindInfo.add_saved_register.
(Frames In Python): Update description of Frame.read_register.
Adds a new method 'find' to the gdb.RegisterDescriptorIterator class,
this allows gdb.RegisterDescriptor objects to be looked up directly by
register name rather than having to iterate over all registers.
This will be of use for a later commit.
I've documented the new function in the manual, but I don't think a
NEWS entry is required here, as, since the last release, the whole
register descriptor mechanism is new, and is already mentioned in the
NEWS file.
gdb/ChangeLog:
* python/py-registers.c: Add 'user-regs.h' include.
(register_descriptor_iter_find): New function.
(register_descriptor_iterator_object_methods): New static global
methods array.
(register_descriptor_iterator_object_type): Add pointer to methods
array.
gdb/testsuite/ChangeLog:
* gdb.python/py-arch-reg-names.exp: Add additional tests.
gdb/doc/ChangeLog:
* python.texi (Registers In Python): Document new find function.
Pedro's review comments arrived after I'd already committed this
change:
commit f7306dac19c502232f766c3881313857915f330d
Date: Tue Jul 7 15:00:30 2020 +0100
gdb/python: Reuse gdb.RegisterDescriptor objects where possible
See:
https://sourceware.org/pipermail/gdb-patches/2020-July/170726.html
There should be no user visible changes after this commit.
gdb/ChangeLog:
* python/py-registers.c (gdbpy_register_object_data_init): Remove
redundant local variable.
(gdbpy_get_register_descriptor): Extract descriptor vector as a
reference, not pointer, update code accordingly.
Only create one gdb.RegisterGroup Python object for each of GDB's
reggroup objects.
I could have added a field into the reggroup object to hold the Python
object pointer for each reggroup, however, as reggroups are never
deleted within GDB, and are global (not per-architecture) a simpler
solution seemed to be just to hold a single global map from reggroup
pointer to a Python object representing the reggroup. Then we can
reuse the objects out of this map.
After this commit it is possible for a user to tell that two
gdb.RegisterGroup objects are now identical when previously they were
unique, however, as both these objects are read-only I don't think
this should be a problem.
There should be no other user visible changes after this commit.
gdb/ChangeLog:
* python/py-registers.c : Add 'unordered_map' include.
(gdbpy_new_reggroup): Renamed to...
(gdbpy_get_reggroup): ...this. Update to only create register
group descriptors when needed.
(gdbpy_reggroup_iter_next): Update.
gdb/testsuite/ChangeLog:
* gdb.python/py-arch-reg-groups.exp: Additional tests.
Instead of having the gdb.RegisterDescriptorIterator creating new
gdb.RegisterDescriptor objects for each regnum, instead cache
gdb.RegisterDescriptor objects on the gdbarch object and reuse these.
This means that for every gdbarch/regnum pair there is a single unique
gdb.RegisterDescriptor, this feels like a neater implementation than
the existing one.
It is possible for a user to see (in Python code) that the descriptors
are now identical, but as the descriptors are read-only this should
make no real difference.
There should be no other user visible changes.
gdb/ChangeLog:
* python/py-registers.c (gdbpy_register_object_data): New static
global.
(gdbpy_register_object_data_init): New function.
(gdbpy_new_register_descriptor): Renamed to...
(gdbpy_get_register_descriptor): ...this, and update to reuse
existing register descriptors where possible.
(gdbpy_register_descriptor_iter_next): Update.
(gdbpy_initialize_registers): Register new gdbarch data.
gdb/testsuite/ChangeLog:
* gdb.python/py-arch-reg-names.exp: Additional tests.
Add a new method gdb.Architecture.register_groups which returns a new
object of type gdb.RegisterGroupsIterator. This new iterator then
returns objects of type gdb.RegisterGroup.
Each gdb.RegisterGroup object just wraps a single reggroup pointer,
and (currently) has just one read-only property 'name' that is a
string, the name of the register group.
As with the previous commit (adding gdb.RegisterDescriptor) I made
gdb.RegisterGroup an object rather than just a string in case we want
to add additional properties in the future.
gdb/ChangeLog:
* NEWS: Mention additions to Python API.
* python/py-arch.c (archpy_register_groups): New function.
(arch_object_methods): Add 'register_groups' method.
* python/py-registers.c (reggroup_iterator_object): New struct.
(reggroup_object): New struct.
(gdbpy_new_reggroup): New function.
(gdbpy_reggroup_to_string): New function.
(gdbpy_reggroup_name): New function.
(gdbpy_reggroup_iter): New function.
(gdbpy_reggroup_iter_next): New function.
(gdbpy_new_reggroup_iterator): New function
(gdbpy_initialize_registers): Register new types.
(reggroup_iterator_object_type): Define new Python type.
(gdbpy_reggroup_getset): New static global.
(reggroup_object_type): Define new Python type.
* python/python-internal.h
gdb/testsuite/ChangeLog:
* gdb.python/py-arch-reg-groups.exp: New file.
gdb/doc/ChangeLog:
* gdb.texi (Registers): Add @anchor for 'info registers
<reggroup>' command.
* python.texi (Architectures In Python): Document new
register_groups method.
(Registers In Python): Document two new object types related to
register groups.
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.
