gdb/python/py-registers.c

   1 /* Python interface to register, and register group information.
   2
   3    Copyright (C) 2020-2025 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   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.
  11
  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.
  16
  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/>.  */
  19
  20 #include "gdbarch.h"
  21 #include "arch-utils.h"
  22 #include "reggroups.h"
  23 #include "python-internal.h"
  24 #include "user-regs.h"
  25 #include "gdbsupport/unordered_map.h"
  26
  27 /* Per-gdbarch data type.  */
  28 typedef std::vector<gdbpy_ref<>> gdbpy_register_type;
  29
  30 /* Token to access per-gdbarch data related to register descriptors.  */
  31 static const registry<gdbarch>::key<gdbpy_register_type>
  32      gdbpy_register_object_data;
  33
  34 /* Structure for iterator over register descriptors.  */
  35 struct register_descriptor_iterator_object {
  36   PyObject_HEAD
  37
  38   /* The register group that the user is iterating over.  This will never
  39      be NULL.  */
  40   const struct reggroup *reggroup;
  41
  42   /* The next register number to lookup.  Starts at 0 and counts up.  */
  43   int regnum;
  44
  45   /* Pointer back to the architecture we're finding registers for.  */
  46   struct gdbarch *gdbarch;
  47 };
  48
  49 extern PyTypeObject register_descriptor_iterator_object_type
  50     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("register_descriptor_iterator_object");
  51
  52 /* A register descriptor.  */
  53 struct register_descriptor_object {
  54   PyObject_HEAD
  55
  56   /* The register this is a descriptor for.  */
  57   int regnum;
  58
  59   /* The architecture this is a register for.  */
  60   struct gdbarch *gdbarch;
  61 };
  62
  63 extern PyTypeObject register_descriptor_object_type
  64     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("register_descriptor_object");
  65
  66 /* Structure for iterator over register groups.  */
  67 struct reggroup_iterator_object {
  68   PyObject_HEAD
  69
  70   /* The index into GROUPS for the next group to return.  */
  71   std::vector<const reggroup *>::size_type index;
  72
  73   /* Pointer back to the architecture we're finding registers for.  */
  74   struct gdbarch *gdbarch;
  75 };
  76
  77 extern PyTypeObject reggroup_iterator_object_type
  78     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("reggroup_iterator_object");
  79
  80 /* A register group object.  */
  81 struct reggroup_object {
  82   PyObject_HEAD
  83
  84   /* The register group being described.  */
  85   const struct reggroup *reggroup;
  86 };
  87
  88 extern PyTypeObject reggroup_object_type
  89     CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("reggroup_object");
  90
  91 /* Return a gdb.RegisterGroup object wrapping REGGROUP.  The register
  92    group objects are cached, and the same Python object will always be
  93    returned for the same REGGROUP pointer.  */
  94
  95 static gdbpy_ref<>
  96 gdbpy_get_reggroup (const reggroup *reggroup)
  97 {
  98   /* Map from GDB's internal reggroup objects to the Python representation.
  99      GDB's reggroups are global, and are never deleted, so using a map like
 100      this is safe.  */
 101   static gdb::unordered_map<const struct reggroup *,gdbpy_ref<>>
 102     gdbpy_reggroup_object_map;
 103
 104   /* If there is not already a suitable Python object in the map then
 105      create a new one, and add it to the map.  */
 106   if (gdbpy_reggroup_object_map[reggroup] == nullptr)
 107     {
 108       /* Create a new object and fill in its details.  */
 109       gdbpy_ref<reggroup_object> group
 110         (PyObject_New (reggroup_object, &reggroup_object_type));
 111       if (group == NULL)
 112         return NULL;
 113       group->reggroup = reggroup;
 114       gdbpy_reggroup_object_map[reggroup]
 115         = gdbpy_ref<> ((PyObject *) group.release ());
 116     }
 117
 118   /* Fetch the Python object wrapping REGGROUP from the map, increasing
 119      the reference count is handled by the gdbpy_ref class.  */
 120   return gdbpy_reggroup_object_map[reggroup];
 121 }
 122
 123 /* Convert a gdb.RegisterGroup to a string, it just returns the name of
 124    the register group.  */
 125
 126 static PyObject *
 127 gdbpy_reggroup_to_string (PyObject *self)
 128 {
 129   reggroup_object *group = (reggroup_object *) self;
 130   const reggroup *reggroup = group->reggroup;
 131
 132   return PyUnicode_FromString (reggroup->name ());
 133 }
 134
 135 /* Implement gdb.RegisterGroup.name (self) -> String.
 136    Return a string that is the name of this register group.  */
 137
 138 static PyObject *
 139 gdbpy_reggroup_name (PyObject *self, void *closure)
 140 {
 141   return gdbpy_reggroup_to_string (self);
 142 }
 143
 144 /* Return a gdb.RegisterDescriptor object for REGNUM from GDBARCH.  For
 145    each REGNUM (in GDBARCH) only one descriptor is ever created, which is
 146    then cached on the GDBARCH.  */
 147
 148 static gdbpy_ref<>
 149 gdbpy_get_register_descriptor (struct gdbarch *gdbarch,
 150                                int regnum)
 151 {
 152   gdbpy_register_type *vecp = gdbpy_register_object_data.get (gdbarch);
 153   if (vecp == nullptr)
 154     vecp = gdbpy_register_object_data.emplace (gdbarch);
 155   gdbpy_register_type &vec = *vecp;
 156
 157   /* Ensure that we have enough entries in the vector.  */
 158   if (vec.size () <= regnum)
 159     vec.resize ((regnum + 1), nullptr);
 160
 161   /* If we don't already have a descriptor for REGNUM in GDBARCH then
 162      create one now.  */
 163   if (vec[regnum] == nullptr)
 164     {
 165       gdbpy_ref <register_descriptor_object> reg
 166         (PyObject_New (register_descriptor_object,
 167                        &register_descriptor_object_type));
 168       if (reg == NULL)
 169         return NULL;
 170       reg->regnum = regnum;
 171       reg->gdbarch = gdbarch;
 172       vec[regnum] = gdbpy_ref<> ((PyObject *) reg.release ());
 173     }
 174
 175   /* Grab the register descriptor from the vector, the reference count is
 176      automatically incremented thanks to gdbpy_ref.  */
 177   return vec[regnum];
 178 }
 179
 180 /* Convert the register descriptor to a string.  */
 181
 182 static PyObject *
 183 gdbpy_register_descriptor_to_string (PyObject *self)
 184 {
 185   register_descriptor_object *reg
 186     = (register_descriptor_object *) self;
 187   struct gdbarch *gdbarch = reg->gdbarch;
 188   int regnum = reg->regnum;
 189
 190   const char *name = gdbarch_register_name (gdbarch, regnum);
 191   return PyUnicode_FromString (name);
 192 }
 193
 194 /* Implement gdb.RegisterDescriptor.name attribute get function.  Return a
 195    string that is the name of this register.  Due to checking when register
 196    descriptors are created the name will never by the empty string.  */
 197
 198 static PyObject *
 199 gdbpy_register_descriptor_name (PyObject *self, void *closure)
 200 {
 201   return gdbpy_register_descriptor_to_string (self);
 202 }
 203
 204 /* Return a reference to the gdb.RegisterGroupsIterator object.  */
 205
 206 static PyObject *
 207 gdbpy_reggroup_iter (PyObject *self)
 208 {
 209   Py_INCREF (self);
 210   return self;
 211 }
 212
 213 /* Return the next gdb.RegisterGroup object from the iterator.  */
 214
 215 static PyObject *
 216 gdbpy_reggroup_iter_next (PyObject *self)
 217 {
 218   reggroup_iterator_object *iter_obj
 219     = (reggroup_iterator_object *) self;
 220
 221   const std::vector<const reggroup *> &groups
 222     = gdbarch_reggroups (iter_obj->gdbarch);
 223   if (iter_obj->index >= groups.size ())
 224     {
 225       PyErr_SetString (PyExc_StopIteration, _("No more groups"));
 226       return NULL;
 227     }
 228
 229   const reggroup *group = groups[iter_obj->index];
 230   iter_obj->index++;
 231   return gdbpy_get_reggroup (group).release ();
 232 }
 233
 234 /* Return a new gdb.RegisterGroupsIterator over all the register groups in
 235    GDBARCH.  */
 236
 237 PyObject *
 238 gdbpy_new_reggroup_iterator (struct gdbarch *gdbarch)
 239 {
 240   gdb_assert (gdbarch != nullptr);
 241
 242   /* Create a new object and fill in its internal state.  */
 243   reggroup_iterator_object *iter
 244     = PyObject_New (reggroup_iterator_object,
 245                     &reggroup_iterator_object_type);
 246   if (iter == NULL)
 247     return NULL;
 248   iter->index = 0;
 249   iter->gdbarch = gdbarch;
 250   return (PyObject *) iter;
 251 }
 252
 253 /* Create and return a new gdb.RegisterDescriptorIterator object which
 254    will iterate over all registers in GROUP_NAME for GDBARCH.  If
 255    GROUP_NAME is either NULL or the empty string then the ALL_REGGROUP is
 256    used, otherwise lookup the register group matching GROUP_NAME and use
 257    that.
 258
 259    This function can return NULL if GROUP_NAME isn't found.  */
 260
 261 PyObject *
 262 gdbpy_new_register_descriptor_iterator (struct gdbarch *gdbarch,
 263                                         const char *group_name)
 264 {
 265   const reggroup *grp = NULL;
 266
 267   /* Lookup the requested register group, or find the default.  */
 268   if (group_name == NULL || *group_name == '\0')
 269     grp = all_reggroup;
 270   else
 271     {
 272       grp = reggroup_find (gdbarch, group_name);
 273       if (grp == NULL)
 274         {
 275           PyErr_SetString (PyExc_ValueError,
 276                            _("Unknown register group name."));
 277           return NULL;
 278         }
 279     }
 280   /* Create a new iterator object initialised for this architecture and
 281      fill in all of the details.  */
 282   register_descriptor_iterator_object *iter
 283     = PyObject_New (register_descriptor_iterator_object,
 284                     &register_descriptor_iterator_object_type);
 285   if (iter == NULL)
 286     return NULL;
 287   iter->regnum = 0;
 288   iter->gdbarch = gdbarch;
 289   gdb_assert (grp != NULL);
 290   iter->reggroup = grp;
 291
 292   return (PyObject *) iter;
 293 }
 294
 295 /* Return a reference to the gdb.RegisterDescriptorIterator object.  */
 296
 297 static PyObject *
 298 gdbpy_register_descriptor_iter (PyObject *self)
 299 {
 300   Py_INCREF (self);
 301   return self;
 302 }
 303
 304 /* Return the next register name.  */
 305
 306 static PyObject *
 307 gdbpy_register_descriptor_iter_next (PyObject *self)
 308 {
 309   register_descriptor_iterator_object *iter_obj
 310     = (register_descriptor_iterator_object *) self;
 311   struct gdbarch *gdbarch = iter_obj->gdbarch;
 312
 313   do
 314     {
 315       if (iter_obj->regnum >= gdbarch_num_cooked_regs (gdbarch))
 316         {
 317           PyErr_SetString (PyExc_StopIteration, _("No more registers"));
 318           return NULL;
 319         }
 320
 321       const char *name = nullptr;
 322       int regnum = iter_obj->regnum;
 323       if (gdbarch_register_reggroup_p (gdbarch, regnum,
 324                                        iter_obj->reggroup))
 325         name = gdbarch_register_name (gdbarch, regnum);
 326       iter_obj->regnum++;
 327
 328       if (name != nullptr && *name != '\0')
 329         return gdbpy_get_register_descriptor (gdbarch, regnum).release ();
 330     }
 331   while (true);
 332 }
 333
 334 /* Implement:
 335
 336    gdb.RegisterDescriptorIterator.find (self, name) -> gdb.RegisterDescriptor
 337
 338    Look up a descriptor for register with NAME.  If no matching register is
 339    found then return None.  */
 340
 341 static PyObject *
 342 register_descriptor_iter_find (PyObject *self, PyObject *args, PyObject *kw)
 343 {
 344   static const char *keywords[] = { "name", NULL };
 345   const char *register_name = NULL;
 346
 347   register_descriptor_iterator_object *iter_obj
 348     = (register_descriptor_iterator_object *) self;
 349   struct gdbarch *gdbarch = iter_obj->gdbarch;
 350
 351   if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "s", keywords,
 352                                         &register_name))
 353     return NULL;
 354
 355   if (register_name != NULL && *register_name != '\0')
 356     {
 357       int regnum = user_reg_map_name_to_regnum (gdbarch, register_name,
 358                                                 strlen (register_name));
 359       if (regnum >= 0)
 360         return gdbpy_get_register_descriptor (gdbarch, regnum).release ();
 361     }
 362
 363   Py_RETURN_NONE;
 364 }
 365
 366 /* See python-internal.h.  */
 367
 368 bool
 369 gdbpy_parse_register_id (struct gdbarch *gdbarch, PyObject *pyo_reg_id,
 370                          int *reg_num)
 371 {
 372   gdb_assert (pyo_reg_id != NULL);
 373
 374   /* The register could be a string, its name.  */
 375   if (gdbpy_is_string (pyo_reg_id))
 376     {
 377       gdb::unique_xmalloc_ptr<char> reg_name (gdbpy_obj_to_string (pyo_reg_id));
 378
 379       if (reg_name != NULL)
 380         {
 381           *reg_num = user_reg_map_name_to_regnum (gdbarch, reg_name.get (),
 382                                                   strlen (reg_name.get ()));
 383           if (*reg_num >= 0)
 384             return true;
 385           PyErr_SetString (PyExc_ValueError, "Bad register");
 386         }
 387     }
 388   /* The register could be its internal GDB register number.  */
 389   else if (PyLong_Check (pyo_reg_id))
 390     {
 391       long value;
 392       if (gdb_py_int_as_long (pyo_reg_id, &value) == 0)
 393         {
 394           /* Nothing -- error.  */
 395         }
 396       else if ((int) value == value
 397                && user_reg_map_regnum_to_name (gdbarch, value) != NULL)
 398         {
 399           *reg_num = (int) value;
 400           return true;
 401         }
 402       else
 403         PyErr_SetString (PyExc_ValueError, "Bad register");
 404     }
 405   /* The register could be a gdb.RegisterDescriptor object.  */
 406   else if (PyObject_TypeCheck (pyo_reg_id, &register_descriptor_object_type))
 407     {
 408       register_descriptor_object *reg
 409         = (register_descriptor_object *) pyo_reg_id;
 410       if (reg->gdbarch == gdbarch)
 411         {
 412           *reg_num = reg->regnum;
 413           return true;
 414         }
 415       else
 416         PyErr_SetString (PyExc_ValueError,
 417                          _("Invalid Architecture in RegisterDescriptor"));
 418     }
 419   else
 420     PyErr_SetString (PyExc_TypeError, _("Invalid type for register"));
 421
 422   gdb_assert (PyErr_Occurred ());
 423   return false;
 424 }
 425
 426 /* Initializes the new Python classes from this file in the gdb module.  */
 427
 428 static int CPYCHECKER_NEGATIVE_RESULT_SETS_EXCEPTION
 429 gdbpy_initialize_registers ()
 430 {
 431   register_descriptor_object_type.tp_new = PyType_GenericNew;
 432   if (gdbpy_type_ready (&register_descriptor_object_type) < 0)
 433     return -1;
 434
 435   reggroup_iterator_object_type.tp_new = PyType_GenericNew;
 436   if (gdbpy_type_ready (&reggroup_iterator_object_type) < 0)
 437     return -1;
 438
 439   reggroup_object_type.tp_new = PyType_GenericNew;
 440   if (gdbpy_type_ready (&reggroup_object_type) < 0)
 441     return -1;
 442
 443   register_descriptor_iterator_object_type.tp_new = PyType_GenericNew;
 444   if (gdbpy_type_ready (&register_descriptor_iterator_object_type) < 0)
 445     return -1;
 446
 447   return 0;
 448 }
 449
 450 GDBPY_INITIALIZE_FILE (gdbpy_initialize_registers);
 451
 452 \f
 453
 454 static PyMethodDef register_descriptor_iterator_object_methods [] = {
 455   { "find", (PyCFunction) register_descriptor_iter_find,
 456     METH_VARARGS | METH_KEYWORDS,
 457     "registers (name) -> gdb.RegisterDescriptor.\n\
 458 Return a register descriptor for the register NAME, or None if no register\n\
 459 with that name exists in this iterator." },
 460   {NULL}  /* Sentinel */
 461 };
 462
 463 PyTypeObject register_descriptor_iterator_object_type = {
 464   PyVarObject_HEAD_INIT (NULL, 0)
 465   "gdb.RegisterDescriptorIterator",             /*tp_name*/
 466   sizeof (register_descriptor_iterator_object), /*tp_basicsize*/
 467   0,                              /*tp_itemsize*/
 468   0,                              /*tp_dealloc*/
 469   0,                              /*tp_print*/
 470   0,                              /*tp_getattr*/
 471   0,                              /*tp_setattr*/
 472   0,                              /*tp_compare*/
 473   0,                              /*tp_repr*/
 474   0,                              /*tp_as_number*/
 475   0,                              /*tp_as_sequence*/
 476   0,                              /*tp_as_mapping*/
 477   0,                              /*tp_hash */
 478   0,                              /*tp_call*/
 479   0,                              /*tp_str*/
 480   0,                              /*tp_getattro*/
 481   0,                              /*tp_setattro*/
 482   0,                              /*tp_as_buffer*/
 483   Py_TPFLAGS_DEFAULT,             /*tp_flags*/
 484   "GDB architecture register descriptor iterator object",       /*tp_doc */
 485   0,                              /*tp_traverse */
 486   0,                              /*tp_clear */
 487   0,                              /*tp_richcompare */
 488   0,                              /*tp_weaklistoffset */
 489   gdbpy_register_descriptor_iter,         /*tp_iter */
 490   gdbpy_register_descriptor_iter_next,  /*tp_iternext */
 491   register_descriptor_iterator_object_methods           /*tp_methods */
 492 };
 493
 494 static gdb_PyGetSetDef gdbpy_register_descriptor_getset[] = {
 495   { "name", gdbpy_register_descriptor_name, NULL,
 496     "The name of this register.", NULL },
 497   { NULL }  /* Sentinel */
 498 };
 499
 500 PyTypeObject register_descriptor_object_type = {
 501   PyVarObject_HEAD_INIT (NULL, 0)
 502   "gdb.RegisterDescriptor",       /*tp_name*/
 503   sizeof (register_descriptor_object),  /*tp_basicsize*/
 504   0,                              /*tp_itemsize*/
 505   0,                              /*tp_dealloc*/
 506   0,                              /*tp_print*/
 507   0,                              /*tp_getattr*/
 508   0,                              /*tp_setattr*/
 509   0,                              /*tp_compare*/
 510   0,                              /*tp_repr*/
 511   0,                              /*tp_as_number*/
 512   0,                              /*tp_as_sequence*/
 513   0,                              /*tp_as_mapping*/
 514   0,                              /*tp_hash */
 515   0,                              /*tp_call*/
 516   gdbpy_register_descriptor_to_string,                  /*tp_str*/
 517   0,                              /*tp_getattro*/
 518   0,                              /*tp_setattro*/
 519   0,                              /*tp_as_buffer*/
 520   Py_TPFLAGS_DEFAULT,             /*tp_flags*/
 521   "GDB architecture register descriptor object",        /*tp_doc */
 522   0,                              /*tp_traverse */
 523   0,                              /*tp_clear */
 524   0,                              /*tp_richcompare */
 525   0,                              /*tp_weaklistoffset */
 526   0,                              /*tp_iter */
 527   0,                              /*tp_iternext */
 528   0,                              /*tp_methods */
 529   0,                              /*tp_members */
 530   gdbpy_register_descriptor_getset                      /*tp_getset */
 531 };
 532
 533 PyTypeObject reggroup_iterator_object_type = {
 534   PyVarObject_HEAD_INIT (NULL, 0)
 535   "gdb.RegisterGroupsIterator",   /*tp_name*/
 536   sizeof (reggroup_iterator_object),            /*tp_basicsize*/
 537   0,                              /*tp_itemsize*/
 538   0,                              /*tp_dealloc*/
 539   0,                              /*tp_print*/
 540   0,                              /*tp_getattr*/
 541   0,                              /*tp_setattr*/
 542   0,                              /*tp_compare*/
 543   0,                              /*tp_repr*/
 544   0,                              /*tp_as_number*/
 545   0,                              /*tp_as_sequence*/
 546   0,                              /*tp_as_mapping*/
 547   0,                              /*tp_hash */
 548   0,                              /*tp_call*/
 549   0,                              /*tp_str*/
 550   0,                              /*tp_getattro*/
 551   0,                              /*tp_setattro*/
 552   0,                              /*tp_as_buffer*/
 553   Py_TPFLAGS_DEFAULT,             /*tp_flags*/
 554   "GDB register groups iterator object",        /*tp_doc */
 555   0,                              /*tp_traverse */
 556   0,                              /*tp_clear */
 557   0,                              /*tp_richcompare */
 558   0,                              /*tp_weaklistoffset */
 559   gdbpy_reggroup_iter,            /*tp_iter */
 560   gdbpy_reggroup_iter_next,       /*tp_iternext */
 561   0                               /*tp_methods */
 562 };
 563
 564 static gdb_PyGetSetDef gdbpy_reggroup_getset[] = {
 565   { "name", gdbpy_reggroup_name, NULL,
 566     "The name of this register group.", NULL },
 567   { NULL }  /* Sentinel */
 568 };
 569
 570 PyTypeObject reggroup_object_type = {
 571   PyVarObject_HEAD_INIT (NULL, 0)
 572   "gdb.RegisterGroup",            /*tp_name*/
 573   sizeof (reggroup_object),       /*tp_basicsize*/
 574   0,                              /*tp_itemsize*/
 575   0,                              /*tp_dealloc*/
 576   0,                              /*tp_print*/
 577   0,                              /*tp_getattr*/
 578   0,                              /*tp_setattr*/
 579   0,                              /*tp_compare*/
 580   0,                              /*tp_repr*/
 581   0,                              /*tp_as_number*/
 582   0,                              /*tp_as_sequence*/
 583   0,                              /*tp_as_mapping*/
 584   0,                              /*tp_hash */
 585   0,                              /*tp_call*/
 586   gdbpy_reggroup_to_string,       /*tp_str*/
 587   0,                              /*tp_getattro*/
 588   0,                              /*tp_setattro*/
 589   0,                              /*tp_as_buffer*/
 590   Py_TPFLAGS_DEFAULT,             /*tp_flags*/
 591   "GDB register group object",    /*tp_doc */
 592   0,                              /*tp_traverse */
 593   0,                              /*tp_clear */
 594   0,                              /*tp_richcompare */
 595   0,                              /*tp_weaklistoffset */
 596   0,                              /*tp_iter */
 597   0,                              /*tp_iternext */
 598   0,                              /*tp_methods */
 599   0,                              /*tp_members */
 600   gdbpy_reggroup_getset           /*tp_getset */
 601 };