bfd/section.c

   1 /* Object file "section" support for the BFD library.
   2    Copyright (C) 1990-1991 Free Software Foundation, Inc.
   3    Written by Cygnus Support.
   4
   5 This file is part of BFD, the Binary File Descriptor library.
   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 2 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, write to the Free Software
  19 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
  20
  21 /*doc*
  22 @section Sections
  23 Sections are supported in BFD in @code{section.c}.
  24
  25 The raw data contained within a BFD is maintained through the section
  26 abstraction.  A single BFD may have any number of sections, and keeps
  27 hold of them by pointing to the first, each one points to the next in
  28 the list.
  29
  30 @menu
  31 * Section Input::
  32 * Section Output::
  33 * typedef asection::
  34 * section prototypes::
  35 @end menu
  36
  37 @node Section Input, Section Output,,Sections
  38 @comment  node-name,  next,  previous,  up
  39 @subsection Section Input
  40 When a BFD is opened for reading, the section structures are created
  41 and attatched to the BFD.
  42
  43 Each section has a name which describes the section in the outside
  44 world - for example, @code{a.out} would contain at least three
  45 sections, called @code{.text}, @code{.data} and @code{.bss}.
  46
  47 Sometimes a BFD will contain more than the 'natural' number of
  48 sections. A back end may attatch other sections containing constructor
  49 data, or an application may add a section (using bfd_make_section) to
  50 the sections attatched to an already open BFD. For example, the linker
  51 creates a supernumary section @code{COMMON} for each input file's BFD
  52 to hold information about common storage.
  53
  54 The raw data is not necessarily read in at the same time as the
  55 section descriptor is created. Some targets may leave the data in
  56 place until a @code{bfd_get_section_contents} call is made. Other back
  57 ends may read in all the data at once - For example; an S-record file
  58 has to be read once to determine the size of the data. An IEEE-695
  59 file doesn't contain raw data in sections, but data and relocation
  60 expressions intermixed, so the data area has to be parsed to get out
  61 the data and relocations.
  62
  63 @node Section Output,typedef asection,Section Input,Sections
  64 @subsection Section Output
  65 To write a new object style BFD, the various sections to be written
  66 have to be created. They are attatched to the BFD in the same way as
  67 input sections, data is written to the sections using
  68 @code{bfd_set_section_contents}.
  69
  70 The linker uses the fields @code{output_section} and
  71 @code{output_offset} to create an output file.
  72
  73 The data to be written comes from input sections attatched to the
  74 output sections.  The output section structure can be considered a
  75 filter for the input section, the output section determines the vma of
  76 the output data and the name, but the input section determines the
  77 offset into the output section of the data to be written.
  78
  79 Eg to create a section "O", starting at 0x100, 0x123 long, containing two
  80 subsections, "A" at offset 0x0 (ie at vma 0x100) and "B" at offset
  81 0x20 (ie at vma 0x120) the structures would look like:
  82
  83 *+
  84
  85    section name          "A"
  86      output_offset   0x00
  87      size            0x20
  88      output_section ----------->  section name    "O"
  89                              |    vma             0x100
  90    section name          "B" |    size            0x123
  91      output_offset   0x20    |
  92      size            0x103   |
  93      output_section  --------|
  94
  95 *-
  96
  97 */
  98
  99
 100 #include "sysdep.h"
 101 #include "bfd.h"
 102 #include "libbfd.h"
 103
 104
 105 /*doc*
 106 @node typedef asection,section prototypes,Section Output,Sections
 107 @subsection typedef asection
 108 */
 109
 110 /*proto*
 111 The shape of a section struct:
 112
 113 *+++
 114
 115 $typedef struct sec {
 116
 117 The name of the section, the name isn't a copy, the pointer is
 118 the same as that passed to bfd_make_section.
 119
 120 $    CONST char *name;
 121
 122 The next section in the list belonging to the BFD, or NULL.
 123
 124 $    struct sec *next;
 125
 126 The field flags contains attributes of the section. Some of these
 127 flags are read in from the object file, and some are synthesized from
 128 other information.
 129
 130 $flagword flags;
 131
 132
 133 $#define SEC_NO_FLAGS   0x000
 134
 135 Tells the OS to allocate space for this section when loaded.
 136 This would clear for a section containing debug information only.
 137
 138 $#define SEC_ALLOC      0x001
 139
 140 Tells the OS to load the section from the file when loading.
 141 This would be clear for a .bss section
 142
 143 $#define SEC_LOAD       0x002
 144
 145 The section contains data still to be relocated, so there will be some
 146 relocation information too.
 147
 148 $#define SEC_RELOC      0x004
 149
 150 Obsolete ?
 151
 152 $#define SEC_BALIGN     0x008
 153
 154 A signal to the OS that the section contains read only data.
 155
 156 $#define SEC_READONLY   0x010
 157
 158 The section contains code only.
 159
 160 $#define SEC_CODE       0x020
 161
 162 The section contains data only.
 163
 164 $#define SEC_DATA        0x040
 165
 166 The section will reside in ROM.
 167
 168 $#define SEC_ROM        0x080
 169
 170 The section contains constructor information. This section type is
 171 used by the linker to create lists of constructors and destructors
 172 used by @code{g++}. When a back end sees a symbol which should be used
 173 in a constructor list, it creates a new section for the type of name
 174 (eg @code{__CTOR_LIST__}), attatches the symbol to it and builds a
 175 relocation. To build the lists of constructors, all the linker has to
 176 to is catenate all the sections called @code{__CTOR_LIST__} and
 177 relocte the data contained within - exactly the operations it would
 178 peform on standard data.
 179
 180 $#define SEC_CONSTRUCTOR 0x100
 181
 182 The section is a constuctor, and should be placed at the end of the ..
 183
 184 $#define SEC_CONSTRUCTOR_TEXT 0x1100
 185
 186 $#define SEC_CONSTRUCTOR_DATA 0x2100
 187
 188 $#define SEC_CONSTRUCTOR_BSS  0x3100
 189
 190
 191 The section has contents - a bss section could be
 192 @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}, a debug section could be
 193 @code{SEC_HAS_CONTENTS}
 194
 195 $#define SEC_HAS_CONTENTS 0x200
 196
 197 An instruction to the linker not to output sections containing
 198 this flag even if they have information which would normally be written.
 199
 200 $#define SEC_NEVER_LOAD 0x400
 201
 202
 203 The base address of the section in the address space of the target.
 204
 205 $   bfd_vma vma;
 206
 207 The size of the section in bytes of the loaded section. This contains
 208 a value even if the section has no contents (eg, the size of @code{.bss}).
 209
 210 $   bfd_size_type size;
 211
 212 If this section is going to be output, then this value is the
 213 offset into the output section of the first byte in the input
 214 section. Eg, if this was going to start at the 100th byte in the
 215 output section, this value would be 100.
 216
 217 $   bfd_vma output_offset;
 218
 219 The output section through which to map on output.
 220
 221 $   struct sec *output_section;
 222
 223 The alignment requirement of the section, as an exponent - eg 3
 224 aligns to 2^3 (or 8)
 225
 226 $   unsigned int alignment_power;
 227
 228 If an input section, a pointer to a vector of relocation records for
 229 the data in this section.
 230
 231 $   struct reloc_cache_entry *relocation;
 232
 233 If an output section, a pointer to a vector of pointers to
 234 relocation records for the data in this section.
 235
 236 $   struct reloc_cache_entry **orelocation;
 237
 238 The number of relocation records in one of the above
 239
 240 $   unsigned reloc_count;
 241
 242 Which section is it 0..nth
 243
 244 $   int index;
 245
 246 Information below is back end specific - and not always used or
 247 updated
 248
 249 File position of section data
 250
 251 $   file_ptr filepos;
 252 File position of relocation info
 253
 254 $   file_ptr rel_filepos;
 255
 256 File position of line data
 257
 258 $   file_ptr line_filepos;
 259
 260 Pointer to data for applications
 261
 262 $   PTR userdata;
 263
 264 $   struct lang_output_section *otheruserdata;
 265
 266 Attached line number information
 267
 268 $   alent *lineno;
 269 Number of line number records
 270
 271 $   unsigned int lineno_count;
 272
 273 When a section is being output, this value changes as more
 274 linenumbers are written out
 275
 276 $   file_ptr moving_line_filepos;
 277
 278 what the section number is in the target world
 279
 280 $   unsigned int target_index;
 281
 282 $   PTR used_by_bfd;
 283
 284 If this is a constructor section then here is a list of the
 285 relocations created to relocate items within it.
 286
 287 $   struct relent_chain *constructor_chain;
 288
 289 The BFD which owns the section.
 290
 291 $   bfd *owner;
 292
 293 $} asection ;
 294
 295 *---
 296
 297 */
 298
 299 /*doc*
 300 @node section prototypes,Section,typedef section,Sections
 301 @subsection section prototypes
 302
 303 */
 304 /*proto* bfd_get_section_by_name
 305 Runs through the provided @var{abfd} and returns the @code{asection}
 306 who's name matches that provided, otherwise NULL. @xref{Sections}, for more information.
 307
 308 *; PROTO(asection *, bfd_get_section_by_name,
 309     (bfd *abfd, CONST char *name));
 310 */
 311 asection *
 312 DEFUN(bfd_get_section_by_name,(abfd, name),
 313       bfd *abfd AND
 314       CONST char *name)
 315 {
 316   asection *sect;
 317
 318   for (sect = abfd->sections; sect != NULL; sect = sect->next)
 319     if (!strcmp (sect->name, name)) return sect;
 320   return NULL;
 321 }
 322
 323
 324 /*proto* bfd_make_section
 325 This function creates a new empty section called @var{name} and attatches it
 326 to the end of the chain of sections for the BFD supplied. An attempt to
 327 create a section with a name which is already in use, returns the old
 328 section by that name instead.
 329
 330 Possible errors are:
 331 @table @code
 332 @item invalid_operation
 333 If output has already started for this BFD.
 334 @item no_memory
 335 If obstack alloc fails.
 336 @end table
 337
 338 *; PROTO(asection *, bfd_make_section, (bfd *, CONST char *name));
 339 */
 340
 341
 342
 343 sec_ptr
 344 DEFUN(bfd_make_section,(abfd, name),
 345       bfd *abfd AND
 346       CONST char * name)
 347 {
 348   asection *newsect;
 349   asection **  prev = &abfd->sections;
 350   asection * sect = abfd->sections;
 351
 352   if (abfd->output_has_begun) {
 353     bfd_error = invalid_operation;
 354     return NULL;
 355   }
 356
 357   while (sect) {
 358     if (!strcmp(sect->name, name)) return sect;
 359     prev = &sect->next;
 360     sect = sect->next;
 361   }
 362
 363   newsect = (asection *) bfd_zalloc(abfd, sizeof (asection));
 364   if (newsect == NULL) {
 365     bfd_error = no_memory;
 366     return NULL;
 367   }
 368
 369   newsect->name = name;
 370   newsect->index = abfd->section_count++;
 371   newsect->flags = SEC_NO_FLAGS;
 372
 373   newsect->userdata = 0;
 374   newsect->next = (asection *)NULL;
 375   newsect->relocation = (arelent *)NULL;
 376   newsect->reloc_count = 0;
 377   newsect->line_filepos =0;
 378   newsect->owner = abfd;
 379   if (BFD_SEND (abfd, _new_section_hook, (abfd, newsect)) != true) {
 380     free (newsect);
 381     return NULL;
 382   }
 383
 384   *prev = newsect;
 385   return newsect;
 386 }
 387
 388
 389 /*proto* bfd_set_section_flags
 390 Attempts to set the attributes of the section named in the BFD
 391 supplied to the value. Returns true on success, false on error.
 392 Possible error returns are:
 393 @table @code
 394 @item invalid operation
 395 The section cannot have one or more of the attributes requested. For
 396 example, a .bss section in @code{a.out} may not have the
 397 @code{SEC_HAS_CONTENTS} field set.
 398 @end table
 399
 400 *; PROTO(boolean, bfd_set_section_flags,
 401        (bfd *, asection *, flagword));
 402 */
 403
 404 boolean
 405 DEFUN(bfd_set_section_flags,(abfd, section, flags),
 406      bfd *abfd AND
 407      sec_ptr section AND
 408      flagword flags)
 409 {
 410   if ((flags & bfd_applicable_section_flags (abfd)) != flags) {
 411     bfd_error = invalid_operation;
 412     return false;
 413   }
 414
 415   section->flags = flags;
 416   return true;
 417 }
 418
 419
 420 /*proto* bfd_map_over_sections
 421 Calls the provided function @var{func} for each section attatched to
 422 the BFD @var{abfd}, passing @var{obj} as an argument. The function
 423 will be called as if by
 424
 425 @example
 426   func(abfd, the_section, obj);
 427 @end example
 428
 429
 430 *; PROTO(void, bfd_map_over_sections,
 431             (bfd *abfd, void (*func)(), PTR obj));
 432
 433 This is the prefered method for iterating over sections, an
 434 alternative would be to use a loop:
 435
 436 @example
 437    section *p;
 438    for (p = abfd->sections; p != NULL; p = p->next)
 439       func(abfd, p, ...)
 440 @end example
 441 */
 442
 443 /*VARARGS2*/
 444 void
 445 DEFUN(bfd_map_over_sections,(abfd, operation, user_storage),
 446       bfd *abfd AND
 447       void (*operation)() AND
 448       PTR user_storage)
 449 {
 450   asection *sect;
 451   int i = 0;
 452
 453   for (sect = abfd->sections; sect != NULL; i++, sect = sect->next)
 454     (*operation) (abfd, sect, user_storage);
 455
 456   if (i != abfd->section_count)         /* Debugging */
 457     abort();
 458 }
 459
 460
 461 /*proto* bfd_set_section_size
 462 Sets @var{section} to the size @var{val}. If the operation is ok, then
 463 @code{true} is returned, else @code{false}.
 464
 465 Possible error returns:
 466 @table @code
 467 @item invalid_operation
 468 Writing has started to the BFD, so setting the size is invalid
 469 @end table
 470
 471 *; PROTO(boolean, bfd_set_section_size,
 472      (bfd *, asection *, bfd_size_type val));
 473 */
 474
 475 boolean
 476 DEFUN(bfd_set_section_size,(abfd, ptr, val),
 477       bfd *abfd AND
 478       sec_ptr ptr AND
 479       bfd_size_type val)
 480 {
 481   /* Once you've started writing to any section you cannot create or change
 482      the size of any others. */
 483
 484   if (abfd->output_has_begun) {
 485     bfd_error = invalid_operation;
 486     return false;
 487   }
 488
 489   ptr->size = val;
 490
 491   return true;
 492 }
 493
 494 /*proto* bfd_set_section_contents
 495 Sets the contents of the section @var{section} in BFD @var{abfd} to
 496 the data starting in memory at @var{data}. The data is written to the
 497 output section starting at offset @var{offset} for @var{count} bytes.
 498
 499 Normally @code{true} is returned, else @code{false}. Possible error
 500 returns are:
 501 @table @code
 502 @item no_contents
 503 The output section does not have the @code{SEC_HAS_CONTENTS}
 504 attribute, so nothing can be written to it.
 505 @item and some more too
 506 @end table
 507 This routine is front end to the back end function @code{_bfd_set_section_contents}.
 508
 509 *; PROTO(boolean, bfd_set_section_contents,
 510          (bfd *abfd,
 511          asection *section,
 512          PTR data,
 513          file_ptr offset,
 514          bfd_size_type count));
 515
 516 */
 517
 518 boolean
 519 DEFUN(bfd_set_section_contents,(abfd, section, location, offset, count),
 520       bfd *abfd AND
 521       sec_ptr section AND
 522       PTR location AND
 523       file_ptr offset AND
 524       bfd_size_type count)
 525 {
 526   if (!(bfd_get_section_flags(abfd, section) & SEC_HAS_CONTENTS))
 527       {
 528         bfd_error = no_contents;
 529         return(false);
 530       }
 531
 532   if (BFD_SEND (abfd, _bfd_set_section_contents,
 533                 (abfd, section, location, offset, count)))
 534       {
 535         abfd->output_has_begun = true;
 536         return true;
 537       }
 538
 539   return false;
 540 }
 541
 542 /*proto* bfd_get_section_contents
 543 This function reads data from @var{section} in BFD @var{abfd} into
 544 memory starting at @var{location}. The data is read at an offset of
 545 @var{offset} from the start of the input section, and is read for
 546 @var{count} bytes.
 547
 548 If the contents of a constuctor with the @code{SEC_CONSTUCTOR} flag
 549 set are requested, then the @var{location} is filled with zeroes.
 550
 551 If no errors occur, @code{true} is returned, else @code{false}.
 552 Possible errors are:
 553
 554 @table @code
 555 @item unknown yet
 556 @end table
 557
 558 *; PROTO(boolean, bfd_get_section_contents,
 559         (bfd *abfd, asection *section, PTR location,
 560          file_ptr offset, bfd_size_type count));
 561
 562
 563 */
 564 boolean
 565 DEFUN(bfd_get_section_contents,(abfd, section, location, offset, count),
 566       bfd *abfd AND
 567       sec_ptr section AND
 568       PTR location AND
 569       file_ptr offset AND
 570       bfd_size_type count)
 571 {
 572   if (section->flags & SEC_CONSTRUCTOR)
 573       {
 574         memset(location, 0, (unsigned)count);
 575         return true;
 576       }
 577   else
 578       {
 579         return  (BFD_SEND (abfd, _bfd_get_section_contents,
 580                            (abfd, section, location, offset, count)));
 581       }
 582 }
 583