gdb/target-descriptions.h

   1 /* Target description support for GDB.
   2
   3    Copyright (C) 2006-2024 Free Software Foundation, Inc.
   4
   5    Contributed by CodeSourcery.
   6
   7    This file is part of GDB.
   8
   9    This program is free software; you can redistribute it and/or modify
  10    it under the terms of the GNU General Public License as published by
  11    the Free Software Foundation; either version 3 of the License, or
  12    (at your option) any later version.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  21
  22 #ifndef TARGET_DESCRIPTIONS_H
  23 #define TARGET_DESCRIPTIONS_H 1
  24 #include "gdbsupport/tdesc.h"
  25 #include "gdbarch.h"
  26
  27 struct tdesc_arch_data;
  28 struct target_ops;
  29 struct inferior;
  30
  31 /* Fetch the current inferior's description, and switch its current
  32    architecture to one which incorporates that description.  */
  33
  34 void target_find_description (void);
  35
  36 /* Discard any description fetched from the target for the current
  37    inferior, and switch the current architecture to one with no target
  38    description.  */
  39
  40 void target_clear_description (void);
  41
  42 /* Return the current inferior's target description.  This should only
  43    be used by gdbarch initialization code; most access should be
  44    through an existing gdbarch.  */
  45
  46 const struct target_desc *target_current_description (void);
  47
  48 /* Record architecture-specific functions to call for pseudo-register
  49    support.  If tdesc_use_registers is called and gdbarch_num_pseudo_regs
  50    is greater than zero, then these should be called as well.
  51    They are equivalent to the gdbarch methods with similar names,
  52    except that they will only be called for pseudo registers.  */
  53
  54 void set_tdesc_pseudo_register_name
  55   (struct gdbarch *gdbarch, gdbarch_register_name_ftype *pseudo_name);
  56
  57 void set_tdesc_pseudo_register_type
  58   (struct gdbarch *gdbarch, gdbarch_register_type_ftype *pseudo_type);
  59
  60 void set_tdesc_pseudo_register_reggroup_p
  61   (struct gdbarch *gdbarch,
  62    gdbarch_register_reggroup_p_ftype *pseudo_reggroup_p);
  63
  64 /* Pointer to a function that should be called for each unknown register in
  65    a target description, used by TDESC_USE_REGISTERS.
  66
  67    GDBARCH is the architecture the target description is for, FEATURE is
  68    the feature the unknown register is in, and REG_NAME is the name of the
  69    register from the target description.  The POSSIBLE_REGNUM is a proposed
  70    (GDB internal) number for this register.
  71
  72    The callback function can return, (-1) to indicate that the register
  73    should not be assigned POSSIBLE_REGNUM now (though it might be later),
  74    GDB will number the register automatically later on.  Return
  75    POSSIBLE_REGNUM (or greater) to have this register assigned that number.
  76    Returning a value less that POSSIBLE_REGNUM is also acceptable, but take
  77    care not to clash with a register number that has already been
  78    assigned.
  79
  80    The callback will always be called on the registers in the order they
  81    appear in the target description.  This means all unknown registers
  82    within a single feature will be called one after another.  */
  83
  84 typedef int (*tdesc_unknown_register_ftype)
  85         (struct gdbarch *gdbarch, tdesc_feature *feature,
  86          const char *reg_name, int possible_regnum);
  87
  88 /* A deleter adapter for a target arch data.  */
  89
  90 struct tdesc_arch_data_deleter
  91 {
  92   void operator() (struct tdesc_arch_data *data) const;
  93 };
  94
  95 /* A unique pointer specialization that holds a target_desc.  */
  96
  97 typedef std::unique_ptr<tdesc_arch_data, tdesc_arch_data_deleter>
  98   tdesc_arch_data_up;
  99
 100 /* Update GDBARCH to use the TARGET_DESC for registers.  TARGET_DESC
 101    may be GDBARCH's target description or (if GDBARCH does not have
 102    one which describes registers) another target description
 103    constructed by the gdbarch initialization routine.
 104
 105    Fixed register assignments are taken from EARLY_DATA, which is freed.
 106    All registers which have not been assigned fixed numbers are given
 107    numbers above the current value of gdbarch_num_regs.
 108    gdbarch_num_regs and various  register-related predicates are updated to
 109    refer to the target description.  This function should only be called from
 110    the architecture's gdbarch initialization routine, and only after
 111    successfully validating the required registers.  */
 112
 113 void tdesc_use_registers (struct gdbarch *gdbarch,
 114                           const struct target_desc *target_desc,
 115                           tdesc_arch_data_up &&early_data,
 116                           tdesc_unknown_register_ftype unk_reg_cb = NULL);
 117
 118 /* Allocate initial data for validation of a target description during
 119    gdbarch initialization.  */
 120
 121 tdesc_arch_data_up tdesc_data_alloc ();
 122
 123 /* Search FEATURE for a register named NAME.  Record REGNO and the
 124    register in DATA; when tdesc_use_registers is called, REGNO will be
 125    assigned to the register.  1 is returned if the register was found,
 126    0 if it was not.  */
 127
 128 int tdesc_numbered_register (const struct tdesc_feature *feature,
 129                              struct tdesc_arch_data *data,
 130                              int regno, const char *name);
 131
 132 /* Search FEATURE for a register named NAME, but do not assign a fixed
 133    register number to it.  */
 134
 135 int tdesc_unnumbered_register (const struct tdesc_feature *feature,
 136                                const char *name);
 137
 138 /* Search FEATURE for a register named NAME, and return its size in
 139    bits.  The register must exist.  */
 140
 141 int tdesc_register_bitsize (const struct tdesc_feature *feature,
 142                             const char *name);
 143
 144 /* Search FEATURE for a register with any of the names from NAMES
 145    (NULL-terminated).  Record REGNO and the register in DATA; when
 146    tdesc_use_registers is called, REGNO will be assigned to the
 147    register.  1 is returned if the register was found, 0 if it was
 148    not.  */
 149
 150 int tdesc_numbered_register_choices (const struct tdesc_feature *feature,
 151                                      struct tdesc_arch_data *data,
 152                                      int regno, const char *const names[]);
 153
 154 /* Return true if DATA contains an entry for REGNO, a GDB register
 155    number.  */
 156
 157 extern bool tdesc_found_register (struct tdesc_arch_data *data, int regno);
 158
 159 /* Accessors for target descriptions.  */
 160
 161 /* Return the BFD architecture associated with this target
 162    description, or NULL if no architecture was specified.  */
 163
 164 const struct bfd_arch_info *tdesc_architecture
 165   (const struct target_desc *);
 166
 167 /* Return the OSABI associated with this target description, or
 168    GDB_OSABI_UNKNOWN if no osabi was specified.  */
 169
 170 enum gdb_osabi tdesc_osabi (const struct target_desc *);
 171
 172 /* Return non-zero if this target description is compatible
 173    with the given BFD architecture.  */
 174
 175 int tdesc_compatible_p (const struct target_desc *,
 176                         const struct bfd_arch_info *);
 177
 178 /* Return the string value of a property named KEY, or NULL if the
 179    property was not specified.  */
 180
 181 const char *tdesc_property (const struct target_desc *,
 182                             const char *key);
 183
 184 /* Return 1 if this target description describes any registers.  */
 185
 186 int tdesc_has_registers (const struct target_desc *);
 187
 188 /* Return the feature with the given name, if present, or NULL if
 189    the named feature is not found.  */
 190
 191 const struct tdesc_feature *tdesc_find_feature (const struct target_desc *,
 192                                                 const char *name);
 193
 194 /* Return the name of FEATURE.  */
 195
 196 const char *tdesc_feature_name (const struct tdesc_feature *feature);
 197
 198 /* Return the name of register REGNO, from the target description or
 199    from an architecture-provided pseudo_register_name method.  */
 200
 201 const char *tdesc_register_name (struct gdbarch *gdbarch, int regno);
 202
 203 /* Return the type of register REGNO, from the target description or
 204    from an architecture-provided pseudo_register_type method.  */
 205
 206 struct type *tdesc_register_type (struct gdbarch *gdbarch, int regno);
 207
 208 /* Return the type associated with ID, from the target description.  */
 209
 210 struct type *tdesc_find_type (struct gdbarch *gdbarch, const char *id);
 211
 212 /* Check whether REGNUM is a member of REGGROUP using the target
 213    description.  Return -1 if the target description does not
 214    specify a group.  */
 215
 216 int tdesc_register_in_reggroup_p (struct gdbarch *gdbarch, int regno,
 217                                   const struct reggroup *reggroup);
 218
 219 /* Methods for constructing a target description.  */
 220
 221 void set_tdesc_architecture (struct target_desc *,
 222                              const struct bfd_arch_info *);
 223 void set_tdesc_osabi (struct target_desc *, enum gdb_osabi osabi);
 224 void set_tdesc_property (struct target_desc *,
 225                          const char *key, const char *value);
 226 void tdesc_add_compatible (struct target_desc *,
 227                            const struct bfd_arch_info *);
 228
 229 #if GDB_SELF_TEST
 230 namespace selftests {
 231
 232 /* Record that XML_FILE should generate a target description that equals
 233    TDESC, to be verified by the "maintenance check xml-descriptions"
 234    command.  This function takes ownership of TDESC.  */
 235
 236 void record_xml_tdesc (const char *xml_file,
 237                        const struct target_desc *tdesc);
 238 }
 239 #endif
 240
 241 #endif /* TARGET_DESCRIPTIONS_H */