gdb/target-descriptions.h

   1 /* Target description support for GDB.
   2
   3    Copyright (C) 2006-2020 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 /* Update GDBARCH to use the TARGET_DESC for registers.  TARGET_DESC
 108    may be GDBARCH's target description or (if GDBARCH does not have
 109    one which describes registers) another target description
 110    constructed by the gdbarch initialization routine.
 111
 112    Fixed register assignments are taken from EARLY_DATA, which is freed.
 113    All registers which have not been assigned fixed numbers are given
 114    numbers above the current value of gdbarch_num_regs.
 115    gdbarch_num_regs and various  register-related predicates are updated to
 116    refer to the target description.  This function should only be called from
 117    the architecture's gdbarch initialization routine, and only after
 118    successfully validating the required registers.  */
 119
 120 void tdesc_use_registers (struct gdbarch *gdbarch,
 121                           const struct target_desc *target_desc,
 122                           struct tdesc_arch_data *early_data,
 123                           tdesc_unknown_register_ftype unk_reg_cb = NULL);
 124
 125 /* Allocate initial data for validation of a target description during
 126    gdbarch initialization.  */
 127
 128 struct tdesc_arch_data *tdesc_data_alloc (void);
 129
 130 /* Clean up data allocated by tdesc_data_alloc.  This should only
 131    be called to discard the data; tdesc_use_registers takes ownership
 132    of its EARLY_DATA argument.  */
 133
 134 void tdesc_data_cleanup (void *data_untyped);
 135
 136 /* Search FEATURE for a register named NAME.  Record REGNO and the
 137    register in DATA; when tdesc_use_registers is called, REGNO will be
 138    assigned to the register.  1 is returned if the register was found,
 139    0 if it was not.  */
 140
 141 int tdesc_numbered_register (const struct tdesc_feature *feature,
 142                              struct tdesc_arch_data *data,
 143                              int regno, const char *name);
 144
 145 /* Search FEATURE for a register named NAME, but do not assign a fixed
 146    register number to it.  */
 147
 148 int tdesc_unnumbered_register (const struct tdesc_feature *feature,
 149                                const char *name);
 150
 151 /* Search FEATURE for a register named NAME, and return its size in
 152    bits.  The register must exist.  */
 153
 154 int tdesc_register_bitsize (const struct tdesc_feature *feature,
 155                             const char *name);
 156
 157 /* Search FEATURE for a register with any of the names from NAMES
 158    (NULL-terminated).  Record REGNO and the register in DATA; when
 159    tdesc_use_registers is called, REGNO will be assigned to the
 160    register.  1 is returned if the register was found, 0 if it was
 161    not.  */
 162
 163 int tdesc_numbered_register_choices (const struct tdesc_feature *feature,
 164                                      struct tdesc_arch_data *data,
 165                                      int regno, const char *const names[]);
 166
 167
 168 /* Accessors for target descriptions.  */
 169
 170 /* Return the BFD architecture associated with this target
 171    description, or NULL if no architecture was specified.  */
 172
 173 const struct bfd_arch_info *tdesc_architecture
 174   (const struct target_desc *);
 175
 176 /* Return the OSABI associated with this target description, or
 177    GDB_OSABI_UNKNOWN if no osabi was specified.  */
 178
 179 enum gdb_osabi tdesc_osabi (const struct target_desc *);
 180
 181 /* Return non-zero if this target description is compatible
 182    with the given BFD architecture.  */
 183
 184 int tdesc_compatible_p (const struct target_desc *,
 185                         const struct bfd_arch_info *);
 186
 187 /* Return the string value of a property named KEY, or NULL if the
 188    property was not specified.  */
 189
 190 const char *tdesc_property (const struct target_desc *,
 191                             const char *key);
 192
 193 /* Return 1 if this target description describes any registers.  */
 194
 195 int tdesc_has_registers (const struct target_desc *);
 196
 197 /* Return the feature with the given name, if present, or NULL if
 198    the named feature is not found.  */
 199
 200 const struct tdesc_feature *tdesc_find_feature (const struct target_desc *,
 201                                                 const char *name);
 202
 203 /* Return the name of FEATURE.  */
 204
 205 const char *tdesc_feature_name (const struct tdesc_feature *feature);
 206
 207 /* Return the name of register REGNO, from the target description or
 208    from an architecture-provided pseudo_register_name method.  */
 209
 210 const char *tdesc_register_name (struct gdbarch *gdbarch, int regno);
 211
 212 /* Return the type of register REGNO, from the target description or
 213    from an architecture-provided pseudo_register_type method.  */
 214
 215 struct type *tdesc_register_type (struct gdbarch *gdbarch, int regno);
 216
 217 /* Return the type associated with ID, from the target description.  */
 218
 219 struct type *tdesc_find_type (struct gdbarch *gdbarch, const char *id);
 220
 221 /* Check whether REGNUM is a member of REGGROUP using the target
 222    description.  Return -1 if the target description does not
 223    specify a group.  */
 224
 225 int tdesc_register_in_reggroup_p (struct gdbarch *gdbarch, int regno,
 226                                   struct reggroup *reggroup);
 227
 228
 229 /* A deleter adapter for a target desc.  */
 230
 231 struct target_desc_deleter
 232 {
 233   void operator() (struct target_desc *desc) const;
 234 };
 235
 236 /* A unique pointer specialization that holds a target_desc.  */
 237
 238 typedef std::unique_ptr<target_desc, target_desc_deleter> target_desc_up;
 239
 240 /* Methods for constructing a target description.  */
 241
 242 void set_tdesc_architecture (struct target_desc *,
 243                              const struct bfd_arch_info *);
 244 void set_tdesc_osabi (struct target_desc *, enum gdb_osabi osabi);
 245 void set_tdesc_property (struct target_desc *,
 246                          const char *key, const char *value);
 247 void tdesc_add_compatible (struct target_desc *,
 248                            const struct bfd_arch_info *);
 249
 250 #if GDB_SELF_TEST
 251 namespace selftests {
 252
 253 /* Record that XML_FILE should generate a target description that equals
 254    TDESC, to be verified by the "maintenance check xml-descriptions"
 255    command.  This function takes ownership of TDESC.  */
 256
 257 void record_xml_tdesc (const char *xml_file,
 258                        const struct target_desc *tdesc);
 259 }
 260 #endif
 261
 262 #endif /* TARGET_DESCRIPTIONS_H */