gdb/target-descriptions.h

   1 /* Target description support for GDB.
   2
   3    Copyright (C) 2006-2023 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 /* An inferior's target description info is stored in this opaque
  30    object.  There's one such object per inferior.  */
  31 struct target_desc_info;
  32 struct inferior;
  33
  34 /* Fetch the current inferior's description, and switch its current
  35    architecture to one which incorporates that description.  */
  36
  37 void target_find_description (void);
  38
  39 /* Discard any description fetched from the target for the current
  40    inferior, and switch the current architecture to one with no target
  41    description.  */
  42
  43 void target_clear_description (void);
  44
  45 /* Return the current inferior's target description.  This should only
  46    be used by gdbarch initialization code; most access should be
  47    through an existing gdbarch.  */
  48
  49 const struct target_desc *target_current_description (void);
  50
  51 /* Copy inferior target description data.  Used for example when
  52    handling (v)forks, where child's description is the same as the
  53    parent's, since the child really is a copy of the parent.  */
  54
  55 void copy_inferior_target_desc_info (struct inferior *destinf,
  56                                      struct inferior *srcinf);
  57
  58 /* Free a target_desc_info object.  */
  59
  60 void target_desc_info_free (struct target_desc_info *tdesc_info);
  61
  62 /* Returns true if INFO indicates the target description had been
  63    supplied by the user.  */
  64
  65 int target_desc_info_from_user_p (struct target_desc_info *info);
  66
  67 /* Record architecture-specific functions to call for pseudo-register
  68    support.  If tdesc_use_registers is called and gdbarch_num_pseudo_regs
  69    is greater than zero, then these should be called as well.
  70    They are equivalent to the gdbarch methods with similar names,
  71    except that they will only be called for pseudo registers.  */
  72
  73 void set_tdesc_pseudo_register_name
  74   (struct gdbarch *gdbarch, gdbarch_register_name_ftype *pseudo_name);
  75
  76 void set_tdesc_pseudo_register_type
  77   (struct gdbarch *gdbarch, gdbarch_register_type_ftype *pseudo_type);
  78
  79 void set_tdesc_pseudo_register_reggroup_p
  80   (struct gdbarch *gdbarch,
  81    gdbarch_register_reggroup_p_ftype *pseudo_reggroup_p);
  82
  83 /* Pointer to a function that should be called for each unknown register in
  84    a target description, used by TDESC_USE_REGISTERS.
  85
  86    GDBARCH is the architecture the target description is for, FEATURE is
  87    the feature the unknown register is in, and REG_NAME is the name of the
  88    register from the target description.  The POSSIBLE_REGNUM is a proposed
  89    (GDB internal) number for this register.
  90
  91    The callback function can return, (-1) to indicate that the register
  92    should not be assigned POSSIBLE_REGNUM now (though it might be later),
  93    GDB will number the register automatically later on.  Return
  94    POSSIBLE_REGNUM (or greater) to have this register assigned that number.
  95    Returning a value less that POSSIBLE_REGNUM is also acceptable, but take
  96    care not to clash with a register number that has already been
  97    assigned.
  98
  99    The callback will always be called on the registers in the order they
 100    appear in the target description.  This means all unknown registers
 101    within a single feature will be called one after another.  */
 102
 103 typedef int (*tdesc_unknown_register_ftype)
 104         (struct gdbarch *gdbarch, tdesc_feature *feature,
 105          const char *reg_name, int possible_regnum);
 106
 107 /* A deleter adapter for a target arch data.  */
 108
 109 struct tdesc_arch_data_deleter
 110 {
 111   void operator() (struct tdesc_arch_data *data) const;
 112 };
 113
 114 /* A unique pointer specialization that holds a target_desc.  */
 115
 116 typedef std::unique_ptr<tdesc_arch_data, tdesc_arch_data_deleter>
 117   tdesc_arch_data_up;
 118
 119 /* Update GDBARCH to use the TARGET_DESC for registers.  TARGET_DESC
 120    may be GDBARCH's target description or (if GDBARCH does not have
 121    one which describes registers) another target description
 122    constructed by the gdbarch initialization routine.
 123
 124    Fixed register assignments are taken from EARLY_DATA, which is freed.
 125    All registers which have not been assigned fixed numbers are given
 126    numbers above the current value of gdbarch_num_regs.
 127    gdbarch_num_regs and various  register-related predicates are updated to
 128    refer to the target description.  This function should only be called from
 129    the architecture's gdbarch initialization routine, and only after
 130    successfully validating the required registers.  */
 131
 132 void tdesc_use_registers (struct gdbarch *gdbarch,
 133                           const struct target_desc *target_desc,
 134                           tdesc_arch_data_up &&early_data,
 135                           tdesc_unknown_register_ftype unk_reg_cb = NULL);
 136
 137 /* Allocate initial data for validation of a target description during
 138    gdbarch initialization.  */
 139
 140 tdesc_arch_data_up tdesc_data_alloc ();
 141
 142 /* Search FEATURE for a register named NAME.  Record REGNO and the
 143    register in DATA; when tdesc_use_registers is called, REGNO will be
 144    assigned to the register.  1 is returned if the register was found,
 145    0 if it was not.  */
 146
 147 int tdesc_numbered_register (const struct tdesc_feature *feature,
 148                              struct tdesc_arch_data *data,
 149                              int regno, const char *name);
 150
 151 /* Search FEATURE for a register named NAME, but do not assign a fixed
 152    register number to it.  */
 153
 154 int tdesc_unnumbered_register (const struct tdesc_feature *feature,
 155                                const char *name);
 156
 157 /* Search FEATURE for a register named NAME, and return its size in
 158    bits.  The register must exist.  */
 159
 160 int tdesc_register_bitsize (const struct tdesc_feature *feature,
 161                             const char *name);
 162
 163 /* Search FEATURE for a register with any of the names from NAMES
 164    (NULL-terminated).  Record REGNO and the register in DATA; when
 165    tdesc_use_registers is called, REGNO will be assigned to the
 166    register.  1 is returned if the register was found, 0 if it was
 167    not.  */
 168
 169 int tdesc_numbered_register_choices (const struct tdesc_feature *feature,
 170                                      struct tdesc_arch_data *data,
 171                                      int regno, const char *const names[]);
 172
 173 /* Return true if DATA contains an entry for REGNO, a GDB register
 174    number.  */
 175
 176 extern bool tdesc_found_register (struct tdesc_arch_data *data, int regno);
 177
 178 /* Accessors for target descriptions.  */
 179
 180 /* Return the BFD architecture associated with this target
 181    description, or NULL if no architecture was specified.  */
 182
 183 const struct bfd_arch_info *tdesc_architecture
 184   (const struct target_desc *);
 185
 186 /* Return the OSABI associated with this target description, or
 187    GDB_OSABI_UNKNOWN if no osabi was specified.  */
 188
 189 enum gdb_osabi tdesc_osabi (const struct target_desc *);
 190
 191 /* Return non-zero if this target description is compatible
 192    with the given BFD architecture.  */
 193
 194 int tdesc_compatible_p (const struct target_desc *,
 195                         const struct bfd_arch_info *);
 196
 197 /* Return the string value of a property named KEY, or NULL if the
 198    property was not specified.  */
 199
 200 const char *tdesc_property (const struct target_desc *,
 201                             const char *key);
 202
 203 /* Return 1 if this target description describes any registers.  */
 204
 205 int tdesc_has_registers (const struct target_desc *);
 206
 207 /* Return the feature with the given name, if present, or NULL if
 208    the named feature is not found.  */
 209
 210 const struct tdesc_feature *tdesc_find_feature (const struct target_desc *,
 211                                                 const char *name);
 212
 213 /* Return the name of FEATURE.  */
 214
 215 const char *tdesc_feature_name (const struct tdesc_feature *feature);
 216
 217 /* Return the name of register REGNO, from the target description or
 218    from an architecture-provided pseudo_register_name method.  */
 219
 220 const char *tdesc_register_name (struct gdbarch *gdbarch, int regno);
 221
 222 /* Return the type of register REGNO, from the target description or
 223    from an architecture-provided pseudo_register_type method.  */
 224
 225 struct type *tdesc_register_type (struct gdbarch *gdbarch, int regno);
 226
 227 /* Return the type associated with ID, from the target description.  */
 228
 229 struct type *tdesc_find_type (struct gdbarch *gdbarch, const char *id);
 230
 231 /* Check whether REGNUM is a member of REGGROUP using the target
 232    description.  Return -1 if the target description does not
 233    specify a group.  */
 234
 235 int tdesc_register_in_reggroup_p (struct gdbarch *gdbarch, int regno,
 236                                   const struct reggroup *reggroup);
 237
 238 /* Methods for constructing a target description.  */
 239
 240 void set_tdesc_architecture (struct target_desc *,
 241                              const struct bfd_arch_info *);
 242 void set_tdesc_osabi (struct target_desc *, enum gdb_osabi osabi);
 243 void set_tdesc_property (struct target_desc *,
 244                          const char *key, const char *value);
 245 void tdesc_add_compatible (struct target_desc *,
 246                            const struct bfd_arch_info *);
 247
 248 #if GDB_SELF_TEST
 249 namespace selftests {
 250
 251 /* Record that XML_FILE should generate a target description that equals
 252    TDESC, to be verified by the "maintenance check xml-descriptions"
 253    command.  This function takes ownership of TDESC.  */
 254
 255 void record_xml_tdesc (const char *xml_file,
 256                        const struct target_desc *tdesc);
 257 }
 258 #endif
 259
 260 #endif /* TARGET_DESCRIPTIONS_H */