gdb/target-descriptions.h

   1 /* Target description support for GDB.
   2
   3    Copyright (C) 2006-2022 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
 174 /* Accessors for target descriptions.  */
 175
 176 /* Return the BFD architecture associated with this target
 177    description, or NULL if no architecture was specified.  */
 178
 179 const struct bfd_arch_info *tdesc_architecture
 180   (const struct target_desc *);
 181
 182 /* Return the OSABI associated with this target description, or
 183    GDB_OSABI_UNKNOWN if no osabi was specified.  */
 184
 185 enum gdb_osabi tdesc_osabi (const struct target_desc *);
 186
 187 /* Return non-zero if this target description is compatible
 188    with the given BFD architecture.  */
 189
 190 int tdesc_compatible_p (const struct target_desc *,
 191                         const struct bfd_arch_info *);
 192
 193 /* Return the string value of a property named KEY, or NULL if the
 194    property was not specified.  */
 195
 196 const char *tdesc_property (const struct target_desc *,
 197                             const char *key);
 198
 199 /* Return 1 if this target description describes any registers.  */
 200
 201 int tdesc_has_registers (const struct target_desc *);
 202
 203 /* Return the feature with the given name, if present, or NULL if
 204    the named feature is not found.  */
 205
 206 const struct tdesc_feature *tdesc_find_feature (const struct target_desc *,
 207                                                 const char *name);
 208
 209 /* Return the name of FEATURE.  */
 210
 211 const char *tdesc_feature_name (const struct tdesc_feature *feature);
 212
 213 /* Return the name of register REGNO, from the target description or
 214    from an architecture-provided pseudo_register_name method.  */
 215
 216 const char *tdesc_register_name (struct gdbarch *gdbarch, int regno);
 217
 218 /* Return the type of register REGNO, from the target description or
 219    from an architecture-provided pseudo_register_type method.  */
 220
 221 struct type *tdesc_register_type (struct gdbarch *gdbarch, int regno);
 222
 223 /* Return the type associated with ID, from the target description.  */
 224
 225 struct type *tdesc_find_type (struct gdbarch *gdbarch, const char *id);
 226
 227 /* Check whether REGNUM is a member of REGGROUP using the target
 228    description.  Return -1 if the target description does not
 229    specify a group.  */
 230
 231 int tdesc_register_in_reggroup_p (struct gdbarch *gdbarch, int regno,
 232                                   const struct reggroup *reggroup);
 233
 234 /* Methods for constructing a target description.  */
 235
 236 void set_tdesc_architecture (struct target_desc *,
 237                              const struct bfd_arch_info *);
 238 void set_tdesc_osabi (struct target_desc *, enum gdb_osabi osabi);
 239 void set_tdesc_property (struct target_desc *,
 240                          const char *key, const char *value);
 241 void tdesc_add_compatible (struct target_desc *,
 242                            const struct bfd_arch_info *);
 243
 244 #if GDB_SELF_TEST
 245 namespace selftests {
 246
 247 /* Record that XML_FILE should generate a target description that equals
 248    TDESC, to be verified by the "maintenance check xml-descriptions"
 249    command.  This function takes ownership of TDESC.  */
 250
 251 void record_xml_tdesc (const char *xml_file,
 252                        const struct target_desc *tdesc);
 253 }
 254 #endif
 255
 256 #endif /* TARGET_DESCRIPTIONS_H */