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 GDB_GDBARCH_H
  22 #define GDB_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 struct core_file_exec_context;
  63
  64 #include "regcache.h"
  65
  66 /* The base class for every architecture's tdep sub-class.  The virtual
  67    destructor ensures the class has RTTI information, which allows
  68    gdb::checked_static_cast to be used in the gdbarch_tdep function.  */
  69
  70 struct gdbarch_tdep_base
  71 {
  72   virtual ~gdbarch_tdep_base() = default;
  73 };
  74
  75 using gdbarch_tdep_up = std::unique_ptr<gdbarch_tdep_base>;
  76
  77 /* Callback type for the 'iterate_over_objfiles_in_search_order'
  78    gdbarch  method.  */
  79
  80 using iterate_over_objfiles_in_search_order_cb_ftype
  81   = gdb::function_view<bool(objfile *)>;
  82
  83 /* Callback type for regset section iterators.  The callback usually
  84    invokes the REGSET's supply or collect method, to which it must
  85    pass a buffer - for collects this buffer will need to be created using
  86    COLLECT_SIZE, for supply the existing buffer being read from should
  87    be at least SUPPLY_SIZE.  SECT_NAME is a BFD section name, and HUMAN_NAME
  88    is used for diagnostic messages.  CB_DATA should have been passed
  89    unchanged through the iterator.  */
  90
  91 typedef void (iterate_over_regset_sections_cb)
  92   (const char *sect_name, int supply_size, int collect_size,
  93    const struct regset *regset, const char *human_name, void *cb_data);
  94
  95 /* For a function call, does the function return a value using a
  96    normal value return or a structure return - passing a hidden
  97    argument pointing to storage.  For the latter, there are two
  98    cases: language-mandated structure return and target ABI
  99    structure return.  */
 100
 101 enum function_call_return_method
 102 {
 103   /* Standard value return.  */
 104   return_method_normal = 0,
 105
 106   /* Language ABI structure return.  This is handled
 107      by passing the return location as the first parameter to
 108      the function, even preceding "this".  */
 109   return_method_hidden_param,
 110
 111   /* Target ABI struct return.  This is target-specific; for instance,
 112      on ia64 the first argument is passed in out0 but the hidden
 113      structure return pointer would normally be passed in r8.  */
 114   return_method_struct,
 115 };
 116
 117 enum class memtag_type
 118 {
 119   /* Logical tag, the tag that is stored in unused bits of a pointer to a
 120      virtual address.  */
 121   logical = 0,
 122
 123   /* Allocation tag, the tag that is associated with every granule of memory in
 124      the physical address space.  Allocation tags are used to validate memory
 125      accesses via pointers containing logical tags.  */
 126   allocation,
 127 };
 128
 129 /* Callback types for 'read_core_file_mappings' gdbarch method.  */
 130
 131 using read_core_file_mappings_pre_loop_ftype =
 132   gdb::function_view<void (ULONGEST count)>;
 133
 134 using read_core_file_mappings_loop_ftype =
 135   gdb::function_view<void (int num,
 136                            ULONGEST start,
 137                            ULONGEST end,
 138                            ULONGEST file_ofs,
 139                            const char *filename,
 140                            const bfd_build_id *build_id)>;
 141
 142 /* Possible values for gdbarch_call_dummy_location.  */
 143 enum call_dummy_location_type
 144 {
 145   ON_STACK,
 146   AT_ENTRY_POINT,
 147 };
 148
 149 #include "gdbarch-gen.h"
 150
 151 /* An internal function that should _only_ be called from gdbarch_tdep.
 152    Returns the gdbarch_tdep_base field held within GDBARCH.  */
 153
 154 extern struct gdbarch_tdep_base *gdbarch_tdep_1 (struct gdbarch *gdbarch);
 155
 156 /* Return the gdbarch_tdep_base object held within GDBARCH cast to the type
 157    TDepType, which should be a sub-class of gdbarch_tdep_base.
 158
 159    When GDB is compiled in maintainer mode a run-time check is performed
 160    that the gdbarch_tdep_base within GDBARCH really is of type TDepType.
 161    When GDB is compiled in release mode the run-time check is not
 162    performed, and we assume the caller knows what they are doing.  */
 163
 164 template<typename TDepType>
 165 static inline TDepType *
 166 gdbarch_tdep (struct gdbarch *gdbarch)
 167 {
 168   struct gdbarch_tdep_base *tdep = gdbarch_tdep_1 (gdbarch);
 169   return gdb::checked_static_cast<TDepType *> (tdep);
 170 }
 171
 172 /* Mechanism for co-ordinating the selection of a specific
 173    architecture.
 174
 175    GDB targets (*-tdep.c) can register an interest in a specific
 176    architecture.  Other GDB components can register a need to maintain
 177    per-architecture data.
 178
 179    The mechanisms below ensures that there is only a loose connection
 180    between the set-architecture command and the various GDB
 181    components.  Each component can independently register their need
 182    to maintain architecture specific data with gdbarch.
 183
 184    Pragmatics:
 185
 186    Previously, a single TARGET_ARCHITECTURE_HOOK was provided.  It
 187    didn't scale.
 188
 189    The more traditional mega-struct containing architecture specific
 190    data for all the various GDB components was also considered.  Since
 191    GDB is built from a variable number of (fairly independent)
 192    components it was determined that the global approach was not
 193    applicable.  */
 194
 195
 196 /* Register a new architectural family with GDB.
 197
 198    Register support for the specified ARCHITECTURE with GDB.  When
 199    gdbarch determines that the specified architecture has been
 200    selected, the corresponding INIT function is called.
 201
 202    --
 203
 204    The INIT function takes two parameters: INFO which contains the
 205    information available to gdbarch about the (possibly new)
 206    architecture; ARCHES which is a list of the previously created
 207    ``struct gdbarch'' for this architecture.
 208
 209    The INFO parameter is, as far as possible, be pre-initialized with
 210    information obtained from INFO.ABFD or the global defaults.
 211
 212    The ARCHES parameter is a linked list (sorted most recently used)
 213    of all the previously created architures for this architecture
 214    family.  The (possibly NULL) ARCHES->gdbarch can used to access
 215    values from the previously selected architecture for this
 216    architecture family.
 217
 218    The INIT function shall return any of: NULL - indicating that it
 219    doesn't recognize the selected architecture; an existing ``struct
 220    gdbarch'' from the ARCHES list - indicating that the new
 221    architecture is just a synonym for an earlier architecture (see
 222    gdbarch_list_lookup_by_info()); a newly created ``struct gdbarch''
 223    - that describes the selected architecture (see gdbarch_alloc()).
 224
 225    The DUMP_TDEP function shall print out all target specific values.
 226    Care should be taken to ensure that the function works in both the
 227    multi-arch and non- multi-arch cases.  */
 228
 229 struct gdbarch_list
 230 {
 231   struct gdbarch *gdbarch;
 232   struct gdbarch_list *next;
 233 };
 234
 235 struct gdbarch_info
 236 {
 237   const struct bfd_arch_info *bfd_arch_info = nullptr;
 238
 239   enum bfd_endian byte_order = BFD_ENDIAN_UNKNOWN;
 240
 241   enum bfd_endian byte_order_for_code = BFD_ENDIAN_UNKNOWN;
 242
 243   bfd *abfd = nullptr;
 244
 245   /* Architecture-specific target description data.  */
 246   struct tdesc_arch_data *tdesc_data = nullptr;
 247
 248   enum gdb_osabi osabi = GDB_OSABI_UNKNOWN;
 249
 250   const struct target_desc *target_desc = nullptr;
 251 };
 252
 253 typedef struct gdbarch *(gdbarch_init_ftype) (struct gdbarch_info info, struct gdbarch_list *arches);
 254 typedef void (gdbarch_dump_tdep_ftype) (struct gdbarch *gdbarch, struct ui_file *file);
 255 typedef bool (gdbarch_supports_arch_info_ftype) (const struct bfd_arch_info *);
 256
 257 extern void gdbarch_register (enum bfd_architecture architecture,
 258                               gdbarch_init_ftype *init,
 259                               gdbarch_dump_tdep_ftype *dump_tdep = nullptr,
 260                               gdbarch_supports_arch_info_ftype *supports_arch_info = nullptr);
 261
 262 /* Return true if ARCH is initialized.  */
 263
 264 bool gdbarch_initialized_p (gdbarch *arch);
 265
 266 /* Return a vector of the valid architecture names.  Since architectures are
 267    registered during the _initialize phase this function only returns useful
 268    information once initialization has been completed.  */
 269
 270 extern std::vector<const char *> gdbarch_printable_names ();
 271
 272
 273 /* Helper function.  Search the list of ARCHES for a GDBARCH that
 274    matches the information provided by INFO.  */
 275
 276 extern struct gdbarch_list *gdbarch_list_lookup_by_info (struct gdbarch_list *arches, const struct gdbarch_info *info);
 277
 278
 279 /* Helper function.  Create a preliminary ``struct gdbarch''.  Perform
 280    basic initialization using values obtained from the INFO and TDEP
 281    parameters.  set_gdbarch_*() functions are called to complete the
 282    initialization of the object.  */
 283
 284 extern struct gdbarch *gdbarch_alloc (const struct gdbarch_info *info,
 285                                       gdbarch_tdep_up tdep);
 286
 287
 288 /* Helper function.  Free a partially-constructed ``struct gdbarch''.
 289    It is assumed that the caller frees the ``struct
 290    gdbarch_tdep''.  */
 291
 292 extern void gdbarch_free (struct gdbarch *);
 293
 294 struct gdbarch_deleter
 295 {
 296   void operator() (gdbarch *arch) const
 297   { gdbarch_free (arch); }
 298 };
 299
 300 using gdbarch_up = std::unique_ptr<gdbarch, gdbarch_deleter>;
 301
 302 /* Get the obstack owned by ARCH.  */
 303
 304 extern obstack *gdbarch_obstack (gdbarch *arch);
 305
 306 /* Helper function.  Allocate memory from the ``struct gdbarch''
 307    obstack.  The memory is freed when the corresponding architecture
 308    is also freed.  */
 309
 310 #define GDBARCH_OBSTACK_CALLOC(GDBARCH, NR, TYPE)   obstack_calloc<TYPE> (gdbarch_obstack ((GDBARCH)), (NR))
 311
 312 #define GDBARCH_OBSTACK_ZALLOC(GDBARCH, TYPE)   obstack_zalloc<TYPE> (gdbarch_obstack ((GDBARCH)))
 313
 314 /* Duplicate STRING, returning an equivalent string that's allocated on the
 315    obstack associated with GDBARCH.  The string is freed when the corresponding
 316    architecture is also freed.  */
 317
 318 extern char *gdbarch_obstack_strdup (struct gdbarch *arch, const char *string);
 319
 320 /* Helper function.  Force an update of INF's architecture.
 321
 322    The actual architecture selected is determined by INFO, ``(gdb) set
 323    architecture'' et.al., the existing architecture and BFD's default
 324    architecture.  INFO should be initialized to zero and then selected
 325    fields should be updated.
 326
 327    Returns non-zero if the update succeeds.  */
 328
 329 extern int gdbarch_update_p (inferior *inf, gdbarch_info info);
 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 /* Return true if stacks for ARCH grow down, otherwise return false.  */
 374
 375 static inline bool
 376 gdbarch_stack_grows_down (gdbarch *arch)
 377 {
 378   return gdbarch_inner_than (arch, 1, 2);
 379 }
 380
 381 #endif /* GDB_GDBARCH_H */