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