gdb/gdb_bfd.h

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