gdb/gdb_bfd.h

   1 /* Definitions for BFD wrappers used by GDB.
   2
   3    Copyright (C) 2011-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 #ifndef GDB_BFD_H
  21 #define GDB_BFD_H
  22
  23 #include "registry.h"
  24 #include "gdbsupport/byte-vector.h"
  25 #include "gdbsupport/function-view.h"
  26 #include "gdbsupport/gdb_ref_ptr.h"
  27 #include "gdbsupport/iterator-range.h"
  28 #include "gdbsupport/next-iterator.h"
  29
  30 /* A registry adaptor for BFD.  This arranges to store the registry in
  31    gdb's per-BFD data, which is stored as the bfd_usrdata.  */
  32 template<>
  33 struct registry_accessor<bfd>
  34 {
  35   static registry<bfd> *get (bfd *abfd);
  36 };
  37
  38 /* If supplied a path starting with this sequence, gdb_bfd_open will
  39    open BFDs using target fileio operations.  */
  40
  41 #define TARGET_SYSROOT_PREFIX "target:"
  42
  43 /* Returns nonzero if NAME starts with TARGET_SYSROOT_PREFIX, zero
  44    otherwise.  */
  45
  46 int is_target_filename (const char *name);
  47
  48 /* An overload for strings.  */
  49
  50 static inline int
  51 is_target_filename (const std::string &name)
  52 {
  53   return is_target_filename (name.c_str ());
  54 }
  55
  56 /* Returns nonzero if the filename associated with ABFD starts with
  57    TARGET_SYSROOT_PREFIX, zero otherwise.  */
  58
  59 int gdb_bfd_has_target_filename (struct bfd *abfd);
  60
  61 /* Increment the reference count of ABFD.  It is fine for ABFD to be
  62    NULL; in this case the function does nothing.  */
  63
  64 void gdb_bfd_ref (struct bfd *abfd);
  65
  66 /* Decrement the reference count of ABFD.  If this is the last
  67    reference, ABFD will be freed.  If ABFD is NULL, this function does
  68    nothing.  */
  69
  70 void gdb_bfd_unref (struct bfd *abfd);
  71
  72 /* A policy class for gdb::ref_ptr for BFD reference counting.  */
  73 struct gdb_bfd_ref_policy
  74 {
  75   static void incref (struct bfd *abfd)
  76   {
  77     gdb_bfd_ref (abfd);
  78   }
  79
  80   static void decref (struct bfd *abfd)
  81   {
  82     gdb_bfd_unref (abfd);
  83   }
  84 };
  85
  86 /* A gdb::ref_ptr that has been specialized for BFD objects.  */
  87 typedef gdb::ref_ptr<struct bfd, gdb_bfd_ref_policy> gdb_bfd_ref_ptr;
  88
  89 /* Open a read-only (FOPEN_RB) BFD given arguments like bfd_fopen.
  90    If NAME starts with TARGET_SYSROOT_PREFIX then the BFD will be
  91    opened using target fileio operations if necessary.  Returns NULL
  92    on error.  On success, returns a new reference to the BFD.  BFDs
  93    returned by this call are shared among all callers opening the same
  94    file.  If FD is not -1, then after this call it is owned by BFD.
  95    If the BFD was not accessed using target fileio operations then the
  96    filename associated with the BFD and accessible with
  97    bfd_get_filename will not be exactly NAME but rather NAME with
  98    TARGET_SYSROOT_PREFIX stripped.  If WARN_IF_SLOW is true, print a
  99    warning message if the file is being accessed over a link that may
 100    be slow.  */
 101
 102 gdb_bfd_ref_ptr gdb_bfd_open (const char *name, const char *target,
 103                               int fd = -1, bool warn_if_slow = true);
 104
 105 /* Mark the CHILD BFD as being a member of PARENT.  Also, increment
 106    the reference count of CHILD.  Calling this function ensures that
 107    as along as CHILD remains alive, PARENT will as well.  Both CHILD
 108    and PARENT must be non-NULL.  This can be called more than once
 109    with the same arguments; but it is not allowed to call it for a
 110    single CHILD with different values for PARENT.  */
 111
 112 void gdb_bfd_mark_parent (bfd *child, bfd *parent);
 113
 114 /* Mark INCLUDEE as being included by INCLUDER.
 115    This is used to associate the life time of INCLUDEE with INCLUDER.
 116    For example, with Fission, one file can refer to debug info in another
 117    file, and internal tables we build for the main file (INCLUDER) may refer
 118    to data contained in INCLUDEE.  Therefore we want to keep INCLUDEE around
 119    at least as long as INCLUDER exists.
 120
 121    Note that this is different than gdb_bfd_mark_parent because in our case
 122    lifetime tracking is based on the "parent" whereas in gdb_bfd_mark_parent
 123    lifetime tracking is based on the "child".  Plus in our case INCLUDEE could
 124    have multiple different "parents".  */
 125
 126 void gdb_bfd_record_inclusion (bfd *includer, bfd *includee);
 127
 128 /* Try to read or map the contents of the section SECT.  If successful, the
 129    section data is returned and *SIZE is set to the size of the section data;
 130    this may not be the same as the size according to bfd_section_size if the
 131    section was compressed.  The returned section data is associated with the BFD
 132    and will be destroyed when the BFD is destroyed.  There is no other way to
 133    free it; for temporary uses of section data, see bfd_malloc_and_get_section.
 134    SECT may not have relocations.  If there is an error reading the section,
 135    this issues a warning, sets *SIZE to 0, and returns NULL.  */
 136
 137 const gdb_byte *gdb_bfd_map_section (asection *section, bfd_size_type *size);
 138
 139 /* Compute the CRC for ABFD.  The CRC is used to find and verify
 140    separate debug files.  When successful, this fills in *CRC_OUT and
 141    returns 1.  Otherwise, this issues a warning and returns 0.  */
 142
 143 int gdb_bfd_crc (struct bfd *abfd, unsigned long *crc_out);
 144
 145 \f
 146
 147 /* A wrapper for bfd_fopen that initializes the gdb-specific reference
 148    count.  */
 149
 150 gdb_bfd_ref_ptr gdb_bfd_fopen (const char *, const char *, const char *, int);
 151
 152 /* A wrapper for bfd_openr that initializes the gdb-specific reference
 153    count.  */
 154
 155 gdb_bfd_ref_ptr gdb_bfd_openr (const char *, const char *);
 156
 157 /* A wrapper for bfd_openw that initializes the gdb-specific reference
 158    count.  */
 159
 160 gdb_bfd_ref_ptr gdb_bfd_openw (const char *, const char *);
 161
 162 /* The base class for BFD "iovec" implementations.  This is used by
 163    gdb_bfd_openr_iovec and enables better type safety.  */
 164
 165 class gdb_bfd_iovec_base
 166 {
 167 protected:
 168
 169   gdb_bfd_iovec_base () = default;
 170
 171 public:
 172
 173   virtual ~gdb_bfd_iovec_base () = default;
 174
 175   /* The "read" callback.  */
 176   virtual file_ptr read (bfd *abfd, void *buffer, file_ptr nbytes,
 177                          file_ptr offset) = 0;
 178
 179   /* The "stat" callback.  */
 180   virtual int stat (struct bfd *abfd, struct stat *sb) = 0;
 181 };
 182
 183 /* The type of the function used to open a new iovec-based BFD.  */
 184 using gdb_iovec_opener_ftype
 185      = gdb::function_view<gdb_bfd_iovec_base * (bfd *)>;
 186
 187 /* A type-safe wrapper for bfd_openr_iovec.  */
 188
 189 gdb_bfd_ref_ptr gdb_bfd_openr_iovec (const char *filename, const char *target,
 190                                      gdb_iovec_opener_ftype open_fn);
 191
 192 /* A wrapper for bfd_openr_next_archived_file that initializes the
 193    gdb-specific reference count.  */
 194
 195 gdb_bfd_ref_ptr gdb_bfd_openr_next_archived_file (bfd *archive, bfd *previous);
 196
 197
 198 \f
 199
 200 /* Return the index of the BFD section SECTION.  Ordinarily this is
 201    just the section's index, but for some special sections, like
 202    bfd_com_section_ptr, it will be a synthesized value.  */
 203
 204 int gdb_bfd_section_index (bfd *abfd, asection *section);
 205
 206
 207 /* Like bfd_count_sections, but include any possible global sections,
 208    like bfd_com_section_ptr.  */
 209
 210 int gdb_bfd_count_sections (bfd *abfd);
 211
 212 /* Return true if any section requires relocations, false
 213    otherwise.  */
 214
 215 int gdb_bfd_requires_relocations (bfd *abfd);
 216
 217 /* Alternative to bfd_get_full_section_contents that returns the section
 218    contents in *CONTENTS, instead of an allocated buffer.
 219
 220    Return true on success, false otherwise.  */
 221
 222 bool gdb_bfd_get_full_section_contents (bfd *abfd, asection *section,
 223                                         gdb::byte_vector *contents);
 224
 225 /* Create and initialize a BFD handle from a target in-memory range.  The
 226    BFD starts at ADDR and is SIZE bytes long.  TARGET is the BFD target
 227    name as used in bfd_find_target.  */
 228
 229 gdb_bfd_ref_ptr gdb_bfd_open_from_target_memory (CORE_ADDR addr, ULONGEST size,
 230                                                  const char *target);
 231
 232 /* Range adapter for a BFD's sections.
 233
 234    To be used as:
 235
 236      for (asection *sect : gdb_bfd_all_sections (bfd))
 237        ... use SECT ...
 238  */
 239
 240 using gdb_bfd_section_range = next_range<asection>;
 241
 242 static inline gdb_bfd_section_range
 243 gdb_bfd_sections (bfd *abfd)
 244 {
 245   return gdb_bfd_section_range (abfd->sections);
 246 }
 247
 248 static inline gdb_bfd_section_range
 249 gdb_bfd_sections (const gdb_bfd_ref_ptr &abfd)
 250 {
 251   return gdb_bfd_section_range (abfd->sections);
 252 };
 253
 254 /* A wrapper for bfd_errmsg to produce a more helpful error message
 255    in the case of bfd_error_file_ambiguously recognized.
 256    MATCHING, if non-NULL, is the corresponding argument to
 257    bfd_check_format_matches, and will be freed.  */
 258
 259 extern std::string gdb_bfd_errmsg (bfd_error_type error_tag, char **matching);
 260
 261 /* A wrapper for bfd_init that also handles setting up for
 262    multi-threading.  */
 263
 264 extern void gdb_bfd_init ();
 265
 266 #endif /* GDB_BFD_H */