gdb/gdbarch.h

   1 /* Dynamic architecture support for GDB, the GNU debugger.
   2
   3    Copyright (C) 1998-2024 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20
  21 #ifndef GDBARCH_H
  22 #define GDBARCH_H
  23
  24 #include <vector>
  25 #include "frame.h"
  26 #include "dis-asm.h"
  27 #include "gdbsupport/gdb_obstack.h"
  28 #include "infrun.h"
  29 #include "osabi.h"
  30 #include "displaced-stepping.h"
  31 #include "gdbsupport/gdb-checked-static-cast.h"
  32 #include "registry.h"
  33
  34 struct floatformat;
  35 struct ui_file;
  36 struct value;
  37 struct objfile;
  38 struct obj_section;
  39 struct minimal_symbol;
  40 struct regcache;
  41 struct reggroup;
  42 struct regset;
  43 struct disassemble_info;
  44 struct target_ops;
  45 struct obstack;
  46 struct bp_target_info;
  47 struct target_desc;
  48 struct symbol;
  49 struct syscall;
  50 struct agent_expr;
  51 struct axs_value;
  52 struct stap_parse_info;
  53 struct expr_builder;
  54 struct ravenscar_arch_ops;
  55 struct mem_range;
  56 struct syscalls_info;
  57 struct thread_info;
  58 struct ui_out;
  59 struct inferior;
  60 struct x86_xsave_layout;
  61 struct solib_ops;
  62
  63 #include "regcache.h"
  64
  65 /* The base class for every architecture's tdep sub-class.  The virtual
  66    destructor ensures the class has RTTI information, which allows
  67    gdb::checked_static_cast to be used in the gdbarch_tdep function.  */
  68
  69 struct gdbarch_tdep_base
  70 {
  71   virtual ~gdbarch_tdep_base() = default;
  72 };
  73
  74 using gdbarch_tdep_up = std::unique_ptr<gdbarch_tdep_base>;
  75
  76 /* Callback type for the 'iterate_over_objfiles_in_search_order'
  77    gdbarch  method.  */
  78
  79 using iterate_over_objfiles_in_search_order_cb_ftype
  80   = gdb::function_view<bool(objfile *)>;
  81
  82 /* Callback type for regset section iterators.  The callback usually
  83    invokes the REGSET's supply or collect method, to which it must
  84    pass a buffer - for collects this buffer will need to be created using
  85    COLLECT_SIZE, for supply the existing buffer being read from should
  86    be at least SUPPLY_SIZE.  SECT_NAME is a BFD section name, and HUMAN_NAME
  87    is used for diagnostic messages.  CB_DATA should have been passed
  88    unchanged through the iterator.  */
  89
  90 typedef void (iterate_over_regset_sections_cb)
  91   (const char *sect_name, int supply_size, int collect_size,
  92    const struct regset *regset, const char *human_name, void *cb_data);
  93
  94 /* For a function call, does the function return a value using a
  95    normal value return or a structure return - passing a hidden
  96    argument pointing to storage.  For the latter, there are two
  97    cases: language-mandated structure return and target ABI
  98    structure return.  */
  99
 100 enum function_call_return_method
 101 {
 102   /* Standard value return.  */
 103   return_method_normal = 0,
 104
 105   /* Language ABI structure return.  This is handled
 106      by passing the return location as the first parameter to
 107      the function, even preceding "this".  */
 108   return_method_hidden_param,
 109
 110   /* Target ABI struct return.  This is target-specific; for instance,
 111      on ia64 the first argument is passed in out0 but the hidden
 112      structure return pointer would normally be passed in r8.  */
 113   return_method_struct,
 114 };
 115
 116 enum class memtag_type
 117 {
 118   /* Logical tag, the tag that is stored in unused bits of a pointer to a
 119      virtual address.  */
 120   logical = 0,
 121
 122   /* Allocation tag, the tag that is associated with every granule of memory in
 123      the physical address space.  Allocation tags are used to validate memory
 124      accesses via pointers containing logical tags.  */
 125   allocation,
 126 };
 127
 128 /* Callback types for 'read_core_file_mappings' gdbarch method.  */
 129
 130 using read_core_file_mappings_pre_loop_ftype =
 131   gdb::function_view<void (ULONGEST count)>;
 132
 133 using read_core_file_mappings_loop_ftype =
 134   gdb::function_view<void (int num,
 135                            ULONGEST start,
 136                            ULONGEST end,
 137                            ULONGEST file_ofs,
 138                            const char *filename,
 139                            const bfd_build_id *build_id)>;
 140
 141 /* Possible values for gdbarch_call_dummy_location.  */
 142 enum call_dummy_location_type
 143 {
 144   ON_STACK,
 145   AT_ENTRY_POINT,
 146 };
 147
 148 #include "gdbarch-gen.h"
 149
 150 /* An internal function that should _only_ be called from gdbarch_tdep.
 151    Returns the gdbarch_tdep_base field held within GDBARCH.  */
 152
 153 extern struct gdbarch_tdep_base *gdbarch_tdep_1 (struct gdbarch *gdbarch);
 154
 155 /* Return the gdbarch_tdep_base object held within GDBARCH cast to the type
 156    TDepType, which should be a sub-class of gdbarch_tdep_base.
 157
 158    When GDB is compiled in maintainer mode a run-time check is performed
 159    that the gdbarch_tdep_base within GDBARCH really is of type TDepType.
 160    When GDB is compiled in release mode the run-time check is not
 161    performed, and we assume the caller knows what they are doing.  */
 162
 163 template<typename TDepType>
 164 static inline TDepType *
 165 gdbarch_tdep (struct gdbarch *gdbarch)
 166 {
 167   struct gdbarch_tdep_base *tdep = gdbarch_tdep_1 (gdbarch);
 168   return gdb::checked_static_cast<TDepType *> (tdep);
 169 }
 170
 171 /* Mechanism for co-ordinating the selection of a specific
 172    architecture.
 173
 174    GDB targets (*-tdep.c) can register an interest in a specific
 175    architecture.  Other GDB components can register a need to maintain
 176    per-architecture data.
 177
 178    The mechanisms below ensures that there is only a loose connection
 179    between the set-architecture command and the various GDB
 180    components.  Each component can independently register their need
 181    to maintain architecture specific data with gdbarch.
 182
 183    Pragmatics:
 184
 185    Previously, a single TARGET_ARCHITECTURE_HOOK was provided.  It
 186    didn't scale.
 187
 188    The more traditional mega-struct containing architecture specific
 189    data for all the various GDB components was also considered.  Since
 190    GDB is built from a variable number of (fairly independent)
 191    components it was determined that the global approach was not
 192    applicable.  */
 193
 194
 195 /* Register a new architectural family with GDB.
 196
 197    Register support for the specified ARCHITECTURE with GDB.  When
 198    gdbarch determines that the specified architecture has been
 199    selected, the corresponding INIT function is called.
 200
 201    --
 202
 203    The INIT function takes two parameters: INFO which contains the
 204    information available to gdbarch about the (possibly new)
 205    architecture; ARCHES which is a list of the previously created
 206    ``struct gdbarch'' for this architecture.
 207
 208    The INFO parameter is, as far as possible, be pre-initialized with
 209    information obtained from INFO.ABFD or the global defaults.
 210
 211    The ARCHES parameter is a linked list (sorted most recently used)
 212    of all the previously created architures for this architecture
 213    family.  The (possibly NULL) ARCHES->gdbarch can used to access
 214    values from the previously selected architecture for this
 215    architecture family.
 216
 217    The INIT function shall return any of: NULL - indicating that it
 218    doesn't recognize the selected architecture; an existing ``struct
 219    gdbarch'' from the ARCHES list - indicating that the new
 220    architecture is just a synonym for an earlier architecture (see
 221    gdbarch_list_lookup_by_info()); a newly created ``struct gdbarch''
 222    - that describes the selected architecture (see gdbarch_alloc()).
 223
 224    The DUMP_TDEP function shall print out all target specific values.
 225    Care should be taken to ensure that the function works in both the
 226    multi-arch and non- multi-arch cases.  */
 227
 228 struct gdbarch_list
 229 {
 230   struct gdbarch *gdbarch;
 231   struct gdbarch_list *next;
 232 };
 233
 234 struct gdbarch_info
 235 {
 236   const struct bfd_arch_info *bfd_arch_info = nullptr;
 237
 238   enum bfd_endian byte_order = BFD_ENDIAN_UNKNOWN;
 239
 240   enum bfd_endian byte_order_for_code = BFD_ENDIAN_UNKNOWN;
 241
 242   bfd *abfd = nullptr;
 243
 244   /* Architecture-specific target description data.  */
 245   struct tdesc_arch_data *tdesc_data = nullptr;
 246
 247   enum gdb_osabi osabi = GDB_OSABI_UNKNOWN;
 248
 249   const struct target_desc *target_desc = nullptr;
 250 };
 251
 252 typedef struct gdbarch *(gdbarch_init_ftype) (struct gdbarch_info info, struct gdbarch_list *arches);
 253 typedef void (gdbarch_dump_tdep_ftype) (struct gdbarch *gdbarch, struct ui_file *file);
 254 typedef bool (gdbarch_supports_arch_info_ftype) (const struct bfd_arch_info *);
 255
 256 extern void gdbarch_register (enum bfd_architecture architecture,
 257                               gdbarch_init_ftype *init,
 258                               gdbarch_dump_tdep_ftype *dump_tdep = nullptr,
 259                               gdbarch_supports_arch_info_ftype *supports_arch_info = nullptr);
 260
 261 /* Return true if ARCH is initialized.  */
 262
 263 bool gdbarch_initialized_p (gdbarch *arch);
 264
 265 /* Return a vector of the valid architecture names.  Since architectures are
 266    registered during the _initialize phase this function only returns useful
 267    information once initialization has been completed.  */
 268
 269 extern std::vector<const char *> gdbarch_printable_names ();
 270
 271
 272 /* Helper function.  Search the list of ARCHES for a GDBARCH that
 273    matches the information provided by INFO.  */
 274
 275 extern struct gdbarch_list *gdbarch_list_lookup_by_info (struct gdbarch_list *arches, const struct gdbarch_info *info);
 276
 277
 278 /* Helper function.  Create a preliminary ``struct gdbarch''.  Perform
 279    basic initialization using values obtained from the INFO and TDEP
 280    parameters.  set_gdbarch_*() functions are called to complete the
 281    initialization of the object.  */
 282
 283 extern struct gdbarch *gdbarch_alloc (const struct gdbarch_info *info,
 284                                       gdbarch_tdep_up tdep);
 285
 286
 287 /* Helper function.  Free a partially-constructed ``struct gdbarch''.
 288    It is assumed that the caller frees the ``struct
 289    gdbarch_tdep''.  */
 290
 291 extern void gdbarch_free (struct gdbarch *);
 292
 293 struct gdbarch_deleter
 294 {
 295   void operator() (gdbarch *arch) const
 296   { gdbarch_free (arch); }
 297 };
 298
 299 using gdbarch_up = std::unique_ptr<gdbarch, gdbarch_deleter>;
 300
 301 /* Get the obstack owned by ARCH.  */
 302
 303 extern obstack *gdbarch_obstack (gdbarch *arch);
 304
 305 /* Helper function.  Allocate memory from the ``struct gdbarch''
 306    obstack.  The memory is freed when the corresponding architecture
 307    is also freed.  */
 308
 309 #define GDBARCH_OBSTACK_CALLOC(GDBARCH, NR, TYPE)   obstack_calloc<TYPE> (gdbarch_obstack ((GDBARCH)), (NR))
 310
 311 #define GDBARCH_OBSTACK_ZALLOC(GDBARCH, TYPE)   obstack_zalloc<TYPE> (gdbarch_obstack ((GDBARCH)))
 312
 313 /* Duplicate STRING, returning an equivalent string that's allocated on the
 314    obstack associated with GDBARCH.  The string is freed when the corresponding
 315    architecture is also freed.  */
 316
 317 extern char *gdbarch_obstack_strdup (struct gdbarch *arch, const char *string);
 318
 319 /* Helper function.  Force an update of the current architecture.
 320
 321    The actual architecture selected is determined by INFO, ``(gdb) set
 322    architecture'' et.al., the existing architecture and BFD's default
 323    architecture.  INFO should be initialized to zero and then selected
 324    fields should be updated.
 325
 326    Returns non-zero if the update succeeds.  */
 327
 328 extern int gdbarch_update_p (struct gdbarch_info info);
 329
 330
 331 /* Helper function.  Find an architecture matching info.
 332
 333    INFO should have relevant fields set, and then finished using
 334    gdbarch_info_fill.
 335
 336    Returns the corresponding architecture, or NULL if no matching
 337    architecture was found.  */
 338
 339 extern struct gdbarch *gdbarch_find_by_info (struct gdbarch_info info);
 340
 341 /* A registry adaptor for gdbarch.  This arranges to store the
 342    registry in the gdbarch.  */
 343 template<>
 344 struct registry_accessor<gdbarch>
 345 {
 346   static registry<gdbarch> *get (gdbarch *arch);
 347 };
 348
 349 /* Set the dynamic target-system-dependent parameters (architecture,
 350    byte-order, ...) using information found in the BFD.  */
 351
 352 extern void set_gdbarch_from_file (bfd *);
 353
 354
 355 /* Initialize the current architecture to the "first" one we find on
 356    our list.  */
 357
 358 extern void initialize_current_architecture (void);
 359
 360 /* gdbarch trace variable */
 361 extern unsigned int gdbarch_debug;
 362
 363 extern void gdbarch_dump (struct gdbarch *gdbarch, struct ui_file *file);
 364
 365 /* Return the number of cooked registers (raw + pseudo) for ARCH.  */
 366
 367 static inline int
 368 gdbarch_num_cooked_regs (gdbarch *arch)
 369 {
 370   return gdbarch_num_regs (arch) + gdbarch_num_pseudo_regs (arch);
 371 }
 372
 373 #endif