1 /* Python interface to register, and register group information.
3 Copyright (C) 2020-2024 Free Software Foundation, Inc.
5 This file is part of GDB.
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 3 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program. If not, see <http://www.gnu.org/licenses/>. */
22 #include "arch-utils.h"
23 #include "reggroups.h"
24 #include "python-internal.h"
25 #include "user-regs.h"
26 #include <unordered_map>
28 /* Per-gdbarch data type. */
29 typedef std::vector
<gdbpy_ref
<>> gdbpy_register_type
;
31 /* Token to access per-gdbarch data related to register descriptors. */
32 static const registry
<gdbarch
>::key
<gdbpy_register_type
>
33 gdbpy_register_object_data
;
35 /* Structure for iterator over register descriptors. */
36 struct register_descriptor_iterator_object
{
39 /* The register group that the user is iterating over. This will never
41 const struct reggroup
*reggroup
;
43 /* The next register number to lookup. Starts at 0 and counts up. */
46 /* Pointer back to the architecture we're finding registers for. */
47 struct gdbarch
*gdbarch
;
50 extern PyTypeObject register_descriptor_iterator_object_type
51 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("register_descriptor_iterator_object");
53 /* A register descriptor. */
54 struct register_descriptor_object
{
57 /* The register this is a descriptor for. */
60 /* The architecture this is a register for. */
61 struct gdbarch
*gdbarch
;
64 extern PyTypeObject register_descriptor_object_type
65 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("register_descriptor_object");
67 /* Structure for iterator over register groups. */
68 struct reggroup_iterator_object
{
71 /* The index into GROUPS for the next group to return. */
72 std::vector
<const reggroup
*>::size_type index
;
74 /* Pointer back to the architecture we're finding registers for. */
75 struct gdbarch
*gdbarch
;
78 extern PyTypeObject reggroup_iterator_object_type
79 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("reggroup_iterator_object");
81 /* A register group object. */
82 struct reggroup_object
{
85 /* The register group being described. */
86 const struct reggroup
*reggroup
;
89 extern PyTypeObject reggroup_object_type
90 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("reggroup_object");
92 /* Return a gdb.RegisterGroup object wrapping REGGROUP. The register
93 group objects are cached, and the same Python object will always be
94 returned for the same REGGROUP pointer. */
97 gdbpy_get_reggroup (const reggroup
*reggroup
)
99 /* Map from GDB's internal reggroup objects to the Python representation.
100 GDB's reggroups are global, and are never deleted, so using a map like
102 static std::unordered_map
<const struct reggroup
*,gdbpy_ref
<>>
103 gdbpy_reggroup_object_map
;
105 /* If there is not already a suitable Python object in the map then
106 create a new one, and add it to the map. */
107 if (gdbpy_reggroup_object_map
[reggroup
] == nullptr)
109 /* Create a new object and fill in its details. */
110 gdbpy_ref
<reggroup_object
> group
111 (PyObject_New (reggroup_object
, ®group_object_type
));
114 group
->reggroup
= reggroup
;
115 gdbpy_reggroup_object_map
[reggroup
]
116 = gdbpy_ref
<> ((PyObject
*) group
.release ());
119 /* Fetch the Python object wrapping REGGROUP from the map, increasing
120 the reference count is handled by the gdbpy_ref class. */
121 return gdbpy_reggroup_object_map
[reggroup
];
124 /* Convert a gdb.RegisterGroup to a string, it just returns the name of
125 the register group. */
128 gdbpy_reggroup_to_string (PyObject
*self
)
130 reggroup_object
*group
= (reggroup_object
*) self
;
131 const reggroup
*reggroup
= group
->reggroup
;
133 return PyUnicode_FromString (reggroup
->name ());
136 /* Implement gdb.RegisterGroup.name (self) -> String.
137 Return a string that is the name of this register group. */
140 gdbpy_reggroup_name (PyObject
*self
, void *closure
)
142 return gdbpy_reggroup_to_string (self
);
145 /* Return a gdb.RegisterDescriptor object for REGNUM from GDBARCH. For
146 each REGNUM (in GDBARCH) only one descriptor is ever created, which is
147 then cached on the GDBARCH. */
150 gdbpy_get_register_descriptor (struct gdbarch
*gdbarch
,
153 gdbpy_register_type
*vecp
= gdbpy_register_object_data
.get (gdbarch
);
155 vecp
= gdbpy_register_object_data
.emplace (gdbarch
);
156 gdbpy_register_type
&vec
= *vecp
;
158 /* Ensure that we have enough entries in the vector. */
159 if (vec
.size () <= regnum
)
160 vec
.resize ((regnum
+ 1), nullptr);
162 /* If we don't already have a descriptor for REGNUM in GDBARCH then
164 if (vec
[regnum
] == nullptr)
166 gdbpy_ref
<register_descriptor_object
> reg
167 (PyObject_New (register_descriptor_object
,
168 ®ister_descriptor_object_type
));
171 reg
->regnum
= regnum
;
172 reg
->gdbarch
= gdbarch
;
173 vec
[regnum
] = gdbpy_ref
<> ((PyObject
*) reg
.release ());
176 /* Grab the register descriptor from the vector, the reference count is
177 automatically incremented thanks to gdbpy_ref. */
181 /* Convert the register descriptor to a string. */
184 gdbpy_register_descriptor_to_string (PyObject
*self
)
186 register_descriptor_object
*reg
187 = (register_descriptor_object
*) self
;
188 struct gdbarch
*gdbarch
= reg
->gdbarch
;
189 int regnum
= reg
->regnum
;
191 const char *name
= gdbarch_register_name (gdbarch
, regnum
);
192 return PyUnicode_FromString (name
);
195 /* Implement gdb.RegisterDescriptor.name attribute get function. Return a
196 string that is the name of this register. Due to checking when register
197 descriptors are created the name will never by the empty string. */
200 gdbpy_register_descriptor_name (PyObject
*self
, void *closure
)
202 return gdbpy_register_descriptor_to_string (self
);
205 /* Return a reference to the gdb.RegisterGroupsIterator object. */
208 gdbpy_reggroup_iter (PyObject
*self
)
214 /* Return the next gdb.RegisterGroup object from the iterator. */
217 gdbpy_reggroup_iter_next (PyObject
*self
)
219 reggroup_iterator_object
*iter_obj
220 = (reggroup_iterator_object
*) self
;
222 const std::vector
<const reggroup
*> &groups
223 = gdbarch_reggroups (iter_obj
->gdbarch
);
224 if (iter_obj
->index
>= groups
.size ())
226 PyErr_SetString (PyExc_StopIteration
, _("No more groups"));
230 const reggroup
*group
= groups
[iter_obj
->index
];
232 return gdbpy_get_reggroup (group
).release ();
235 /* Return a new gdb.RegisterGroupsIterator over all the register groups in
239 gdbpy_new_reggroup_iterator (struct gdbarch
*gdbarch
)
241 gdb_assert (gdbarch
!= nullptr);
243 /* Create a new object and fill in its internal state. */
244 reggroup_iterator_object
*iter
245 = PyObject_New (reggroup_iterator_object
,
246 ®group_iterator_object_type
);
250 iter
->gdbarch
= gdbarch
;
251 return (PyObject
*) iter
;
254 /* Create and return a new gdb.RegisterDescriptorIterator object which
255 will iterate over all registers in GROUP_NAME for GDBARCH. If
256 GROUP_NAME is either NULL or the empty string then the ALL_REGGROUP is
257 used, otherwise lookup the register group matching GROUP_NAME and use
260 This function can return NULL if GROUP_NAME isn't found. */
263 gdbpy_new_register_descriptor_iterator (struct gdbarch
*gdbarch
,
264 const char *group_name
)
266 const reggroup
*grp
= NULL
;
268 /* Lookup the requested register group, or find the default. */
269 if (group_name
== NULL
|| *group_name
== '\0')
273 grp
= reggroup_find (gdbarch
, group_name
);
276 PyErr_SetString (PyExc_ValueError
,
277 _("Unknown register group name."));
281 /* Create a new iterator object initialised for this architecture and
282 fill in all of the details. */
283 register_descriptor_iterator_object
*iter
284 = PyObject_New (register_descriptor_iterator_object
,
285 ®ister_descriptor_iterator_object_type
);
289 iter
->gdbarch
= gdbarch
;
290 gdb_assert (grp
!= NULL
);
291 iter
->reggroup
= grp
;
293 return (PyObject
*) iter
;
296 /* Return a reference to the gdb.RegisterDescriptorIterator object. */
299 gdbpy_register_descriptor_iter (PyObject
*self
)
305 /* Return the next register name. */
308 gdbpy_register_descriptor_iter_next (PyObject
*self
)
310 register_descriptor_iterator_object
*iter_obj
311 = (register_descriptor_iterator_object
*) self
;
312 struct gdbarch
*gdbarch
= iter_obj
->gdbarch
;
316 if (iter_obj
->regnum
>= gdbarch_num_cooked_regs (gdbarch
))
318 PyErr_SetString (PyExc_StopIteration
, _("No more registers"));
322 const char *name
= nullptr;
323 int regnum
= iter_obj
->regnum
;
324 if (gdbarch_register_reggroup_p (gdbarch
, regnum
,
326 name
= gdbarch_register_name (gdbarch
, regnum
);
329 if (name
!= nullptr && *name
!= '\0')
330 return gdbpy_get_register_descriptor (gdbarch
, regnum
).release ();
337 gdb.RegisterDescriptorIterator.find (self, name) -> gdb.RegisterDescriptor
339 Look up a descriptor for register with NAME. If no matching register is
340 found then return None. */
343 register_descriptor_iter_find (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
345 static const char *keywords
[] = { "name", NULL
};
346 const char *register_name
= NULL
;
348 register_descriptor_iterator_object
*iter_obj
349 = (register_descriptor_iterator_object
*) self
;
350 struct gdbarch
*gdbarch
= iter_obj
->gdbarch
;
352 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "s", keywords
,
356 if (register_name
!= NULL
&& *register_name
!= '\0')
358 int regnum
= user_reg_map_name_to_regnum (gdbarch
, register_name
,
359 strlen (register_name
));
361 return gdbpy_get_register_descriptor (gdbarch
, regnum
).release ();
367 /* See python-internal.h. */
370 gdbpy_parse_register_id (struct gdbarch
*gdbarch
, PyObject
*pyo_reg_id
,
373 gdb_assert (pyo_reg_id
!= NULL
);
375 /* The register could be a string, its name. */
376 if (gdbpy_is_string (pyo_reg_id
))
378 gdb::unique_xmalloc_ptr
<char> reg_name (gdbpy_obj_to_string (pyo_reg_id
));
380 if (reg_name
!= NULL
)
382 *reg_num
= user_reg_map_name_to_regnum (gdbarch
, reg_name
.get (),
383 strlen (reg_name
.get ()));
386 PyErr_SetString (PyExc_ValueError
, "Bad register");
389 /* The register could be its internal GDB register number. */
390 else if (PyLong_Check (pyo_reg_id
))
393 if (gdb_py_int_as_long (pyo_reg_id
, &value
) == 0)
395 /* Nothing -- error. */
397 else if ((int) value
== value
398 && user_reg_map_regnum_to_name (gdbarch
, value
) != NULL
)
400 *reg_num
= (int) value
;
404 PyErr_SetString (PyExc_ValueError
, "Bad register");
406 /* The register could be a gdb.RegisterDescriptor object. */
407 else if (PyObject_IsInstance (pyo_reg_id
,
408 (PyObject
*) ®ister_descriptor_object_type
))
410 register_descriptor_object
*reg
411 = (register_descriptor_object
*) pyo_reg_id
;
412 if (reg
->gdbarch
== gdbarch
)
414 *reg_num
= reg
->regnum
;
418 PyErr_SetString (PyExc_ValueError
,
419 _("Invalid Architecture in RegisterDescriptor"));
422 PyErr_SetString (PyExc_TypeError
, _("Invalid type for register"));
424 gdb_assert (PyErr_Occurred ());
428 /* Initializes the new Python classes from this file in the gdb module. */
430 static int CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION
431 gdbpy_initialize_registers ()
433 register_descriptor_object_type
.tp_new
= PyType_GenericNew
;
434 if (PyType_Ready (®ister_descriptor_object_type
) < 0)
436 if (gdb_pymodule_addobject
437 (gdb_module
, "RegisterDescriptor",
438 (PyObject
*) ®ister_descriptor_object_type
) < 0)
441 reggroup_iterator_object_type
.tp_new
= PyType_GenericNew
;
442 if (PyType_Ready (®group_iterator_object_type
) < 0)
444 if (gdb_pymodule_addobject
445 (gdb_module
, "RegisterGroupsIterator",
446 (PyObject
*) ®group_iterator_object_type
) < 0)
449 reggroup_object_type
.tp_new
= PyType_GenericNew
;
450 if (PyType_Ready (®group_object_type
) < 0)
452 if (gdb_pymodule_addobject
453 (gdb_module
, "RegisterGroup",
454 (PyObject
*) ®group_object_type
) < 0)
457 register_descriptor_iterator_object_type
.tp_new
= PyType_GenericNew
;
458 if (PyType_Ready (®ister_descriptor_iterator_object_type
) < 0)
460 return (gdb_pymodule_addobject
461 (gdb_module
, "RegisterDescriptorIterator",
462 (PyObject
*) ®ister_descriptor_iterator_object_type
));
465 GDBPY_INITIALIZE_FILE (gdbpy_initialize_registers
);
469 static PyMethodDef register_descriptor_iterator_object_methods
[] = {
470 { "find", (PyCFunction
) register_descriptor_iter_find
,
471 METH_VARARGS
| METH_KEYWORDS
,
472 "registers (name) -> gdb.RegisterDescriptor.\n\
473 Return a register descriptor for the register NAME, or None if no register\n\
474 with that name exists in this iterator." },
475 {NULL
} /* Sentinel */
478 PyTypeObject register_descriptor_iterator_object_type
= {
479 PyVarObject_HEAD_INIT (NULL
, 0)
480 "gdb.RegisterDescriptorIterator", /*tp_name*/
481 sizeof (register_descriptor_iterator_object
), /*tp_basicsize*/
490 0, /*tp_as_sequence*/
498 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
499 "GDB architecture register descriptor iterator object", /*tp_doc */
502 0, /*tp_richcompare */
503 0, /*tp_weaklistoffset */
504 gdbpy_register_descriptor_iter
, /*tp_iter */
505 gdbpy_register_descriptor_iter_next
, /*tp_iternext */
506 register_descriptor_iterator_object_methods
/*tp_methods */
509 static gdb_PyGetSetDef gdbpy_register_descriptor_getset
[] = {
510 { "name", gdbpy_register_descriptor_name
, NULL
,
511 "The name of this register.", NULL
},
512 { NULL
} /* Sentinel */
515 PyTypeObject register_descriptor_object_type
= {
516 PyVarObject_HEAD_INIT (NULL
, 0)
517 "gdb.RegisterDescriptor", /*tp_name*/
518 sizeof (register_descriptor_object
), /*tp_basicsize*/
527 0, /*tp_as_sequence*/
531 gdbpy_register_descriptor_to_string
, /*tp_str*/
535 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
536 "GDB architecture register descriptor object", /*tp_doc */
539 0, /*tp_richcompare */
540 0, /*tp_weaklistoffset */
545 gdbpy_register_descriptor_getset
/*tp_getset */
548 PyTypeObject reggroup_iterator_object_type
= {
549 PyVarObject_HEAD_INIT (NULL
, 0)
550 "gdb.RegisterGroupsIterator", /*tp_name*/
551 sizeof (reggroup_iterator_object
), /*tp_basicsize*/
560 0, /*tp_as_sequence*/
568 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
569 "GDB register groups iterator object", /*tp_doc */
572 0, /*tp_richcompare */
573 0, /*tp_weaklistoffset */
574 gdbpy_reggroup_iter
, /*tp_iter */
575 gdbpy_reggroup_iter_next
, /*tp_iternext */
579 static gdb_PyGetSetDef gdbpy_reggroup_getset
[] = {
580 { "name", gdbpy_reggroup_name
, NULL
,
581 "The name of this register group.", NULL
},
582 { NULL
} /* Sentinel */
585 PyTypeObject reggroup_object_type
= {
586 PyVarObject_HEAD_INIT (NULL
, 0)
587 "gdb.RegisterGroup", /*tp_name*/
588 sizeof (reggroup_object
), /*tp_basicsize*/
597 0, /*tp_as_sequence*/
601 gdbpy_reggroup_to_string
, /*tp_str*/
605 Py_TPFLAGS_DEFAULT
, /*tp_flags*/
606 "GDB register group object", /*tp_doc */
609 0, /*tp_richcompare */
610 0, /*tp_weaklistoffset */
615 gdbpy_reggroup_getset
/*tp_getset */