OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [branches/] [oc/] [gdb-5.0/] [bfd/] [doc/] [bfd.info-1] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 104 markom
This is bfd.info, produced by Makeinfo version 3.12f from bfd.texinfo.
2
 
3
START-INFO-DIR-ENTRY
4
* Bfd: (bfd).                   The Binary File Descriptor library.
5
END-INFO-DIR-ENTRY
6
 
7
   This file documents the BFD library.
8
 
9
   Copyright (C) 1991 Free Software Foundation, Inc.
10
 
11
   Permission is granted to make and distribute verbatim copies of this
12
manual provided the copyright notice and this permission notice are
13
preserved on all copies.
14
 
15
   Permission is granted to copy and distribute modified versions of
16
this manual under the conditions for verbatim copying, subject to the
17
terms of the GNU General Public License, which includes the provision
18
that the entire resulting derived work is distributed under the terms
19
of a permission notice identical to this one.
20
 
21
   Permission is granted to copy and distribute translations of this
22
manual into another language, under the above conditions for modified
23
versions.
24
 
25

26
File: bfd.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)
27
 
28
   This file documents the binary file descriptor library libbfd.
29
 
30
* Menu:
31
 
32
* Overview::                    Overview of BFD
33
* BFD front end::               BFD front end
34
* BFD back ends::               BFD back ends
35
* Index::                       Index
36
 
37

38
File: bfd.info,  Node: Overview,  Next: BFD front end,  Prev: Top,  Up: Top
39
 
40
Introduction
41
************
42
 
43
   BFD is a package which allows applications to use the same routines
44
to operate on object files whatever the object file format.  A new
45
object file format can be supported simply by creating a new BFD back
46
end and adding it to the library.
47
 
48
   BFD is split into two parts: the front end, and the back ends (one
49
for each object file format).
50
   * The front end of BFD provides the interface to the user. It manages
51
     memory and various canonical data structures. The front end also
52
     decides which back end to use and when to call back end routines.
53
 
54
   * The back ends provide BFD its view of the real world. Each back
55
     end provides a set of calls which the BFD front end can use to
56
     maintain its canonical form. The back ends also may keep around
57
     information for their own use, for greater efficiency.
58
 
59
* Menu:
60
 
61
* History::                     History
62
* How It Works::                How It Works
63
* What BFD Version 2 Can Do::   What BFD Version 2 Can Do
64
 
65

66
File: bfd.info,  Node: History,  Next: How It Works,  Prev: Overview,  Up: Overview
67
 
68
History
69
=======
70
 
71
   One spur behind BFD was the desire, on the part of the GNU 960 team
72
at Intel Oregon, for interoperability of applications on their COFF and
73
b.out file formats.  Cygnus was providing GNU support for the team, and
74
was contracted to provide the required functionality.
75
 
76
   The name came from a conversation David Wallace was having with
77
Richard Stallman about the library: RMS said that it would be quite
78
hard--David said "BFD".  Stallman was right, but the name stuck.
79
 
80
   At the same time, Ready Systems wanted much the same thing, but for
81
different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
82
coff.
83
 
84
   BFD was first implemented by members of Cygnus Support; Steve
85
Chamberlain (`sac@cygnus.com'), John Gilmore (`gnu@cygnus.com'), K.
86
Richard Pixley (`rich@cygnus.com') and David Henkel-Wallace
87
(`gumby@cygnus.com').
88
 
89

90
File: bfd.info,  Node: How It Works,  Next: What BFD Version 2 Can Do,  Prev: History,  Up: Overview
91
 
92
How To Use BFD
93
==============
94
 
95
   To use the library, include `bfd.h' and link with `libbfd.a'.
96
 
97
   BFD provides a common interface to the parts of an object file for a
98
calling application.
99
 
100
   When an application sucessfully opens a target file (object,
101
archive, or whatever), a pointer to an internal structure is returned.
102
This pointer points to a structure called `bfd', described in `bfd.h'.
103
Our convention is to call this pointer a BFD, and instances of it
104
within code `abfd'.  All operations on the target object file are
105
applied as methods to the BFD.  The mapping is defined within `bfd.h'
106
in a set of macros, all beginning with `bfd_' to reduce namespace
107
pollution.
108
 
109
   For example, this sequence does what you would probably expect:
110
return the number of sections in an object file attached to a BFD
111
`abfd'.
112
 
113
     #include "bfd.h"
114
 
115
     unsigned int number_of_sections(abfd)
116
     bfd *abfd;
117
     {
118
       return bfd_count_sections(abfd);
119
     }
120
 
121
   The abstraction used within BFD is that an object file has:
122
 
123
   * a header,
124
 
125
   * a number of sections containing raw data (*note Sections::.),
126
 
127
   * a set of relocations (*note Relocations::.), and
128
 
129
   * some symbol information (*note Symbols::.).
130
 
131
Also, BFDs opened for archives have the additional attribute of an index
132
and contain subordinate BFDs. This approach is fine for a.out and coff,
133
but loses efficiency when applied to formats such as S-records and
134
IEEE-695.
135
 
136

137
File: bfd.info,  Node: What BFD Version 2 Can Do,  Prev: How It Works,  Up: Overview
138
 
139
What BFD Version 2 Can Do
140
=========================
141
 
142
   When an object file is opened, BFD subroutines automatically
143
determine the format of the input object file.  They then build a
144
descriptor in memory with pointers to routines that will be used to
145
access elements of the object file's data structures.
146
 
147
   As different information from the the object files is required, BFD
148
reads from different sections of the file and processes them.  For
149
example, a very common operation for the linker is processing symbol
150
tables.  Each BFD back end provides a routine for converting between
151
the object file's representation of symbols and an internal canonical
152
format. When the linker asks for the symbol table of an object file, it
153
calls through a memory pointer to the routine from the relevant BFD
154
back end which reads and converts the table into a canonical form.  The
155
linker then operates upon the canonical form. When the link is finished
156
and the linker writes the output file's symbol table, another BFD back
157
end routine is called to take the newly created symbol table and
158
convert it into the chosen output format.
159
 
160
* Menu:
161
 
162
* BFD information loss::        Information Loss
163
* Canonical format::            The BFD canonical object-file format
164
 
165

166
File: bfd.info,  Node: BFD information loss,  Next: Canonical format,  Up: What BFD Version 2 Can Do
167
 
168
Information Loss
169
----------------
170
 
171
   _Information can be lost during output._ The output formats
172
supported by BFD do not provide identical facilities, and information
173
which can be described in one form has nowhere to go in another format.
174
One example of this is alignment information in `b.out'. There is
175
nowhere in an `a.out' format file to store alignment information on the
176
contained data, so when a file is linked from `b.out' and an `a.out'
177
image is produced, alignment information will not propagate to the
178
output file. (The linker will still use the alignment information
179
internally, so the link is performed correctly).
180
 
181
   Another example is COFF section names. COFF files may contain an
182
unlimited number of sections, each one with a textual section name. If
183
the target of the link is a format which does not have many sections
184
(e.g., `a.out') or has sections without names (e.g., the Oasys format),
185
the link cannot be done simply. You can circumvent this problem by
186
describing the desired input-to-output section mapping with the linker
187
command language.
188
 
189
   _Information can be lost during canonicalization._ The BFD internal
190
canonical form of the external formats is not exhaustive; there are
191
structures in input formats for which there is no direct representation
192
internally.  This means that the BFD back ends cannot maintain all
193
possible data richness through the transformation between external to
194
internal and back to external formats.
195
 
196
   This limitation is only a problem when an application reads one
197
format and writes another.  Each BFD back end is responsible for
198
maintaining as much data as possible, and the internal BFD canonical
199
form has structures which are opaque to the BFD core, and exported only
200
to the back ends. When a file is read in one format, the canonical form
201
is generated for BFD and the application. At the same time, the back
202
end saves away any information which may otherwise be lost. If the data
203
is then written back in the same format, the back end routine will be
204
able to use the canonical form provided by the BFD core as well as the
205
information it prepared earlier.  Since there is a great deal of
206
commonality between back ends, there is no information lost when
207
linking or copying big endian COFF to little endian COFF, or `a.out' to
208
`b.out'.  When a mixture of formats is linked, the information is only
209
lost from the files whose format differs from the destination.
210
 
211

212
File: bfd.info,  Node: Canonical format,  Prev: BFD information loss,  Up: What BFD Version 2 Can Do
213
 
214
The BFD canonical object-file format
215
------------------------------------
216
 
217
   The greatest potential for loss of information occurs when there is
218
the least overlap between the information provided by the source
219
format, that stored by the canonical format, and that needed by the
220
destination format. A brief description of the canonical form may help
221
you understand which kinds of data you can count on preserving across
222
conversions.
223
 
224
_files_
225
     Information stored on a per-file basis includes target machine
226
     architecture, particular implementation format type, a demand
227
     pageable bit, and a write protected bit.  Information like Unix
228
     magic numbers is not stored here--only the magic numbers' meaning,
229
     so a `ZMAGIC' file would have both the demand pageable bit and the
230
     write protected text bit set.  The byte order of the target is
231
     stored on a per-file basis, so that big- and little-endian object
232
     files may be used with one another.
233
 
234
_sections_
235
     Each section in the input file contains the name of the section,
236
     the section's original address in the object file, size and
237
     alignment information, various flags, and pointers into other BFD
238
     data structures.
239
 
240
_symbols_
241
     Each symbol contains a pointer to the information for the object
242
     file which originally defined it, its name, its value, and various
243
     flag bits.  When a BFD back end reads in a symbol table, it
244
     relocates all symbols to make them relative to the base of the
245
     section where they were defined.  Doing this ensures that each
246
     symbol points to its containing section.  Each symbol also has a
247
     varying amount of hidden private data for the BFD back end.  Since
248
     the symbol points to the original file, the private data format
249
     for that symbol is accessible.  `ld' can operate on a collection
250
     of symbols of wildly different formats without problems.
251
 
252
     Normal global and simple local symbols are maintained on output,
253
     so an output file (no matter its format) will retain symbols
254
     pointing to functions and to global, static, and common variables.
255
     Some symbol information is not worth retaining; in `a.out', type
256
     information is stored in the symbol table as long symbol names.
257
     This information would be useless to most COFF debuggers; the
258
     linker has command line switches to allow users to throw it away.
259
 
260
     There is one word of type information within the symbol, so if the
261
     format supports symbol type information within symbols (for
262
     example, COFF, IEEE, Oasys) and the type is simple enough to fit
263
     within one word (nearly everything but aggregates), the
264
     information will be preserved.
265
 
266
_relocation level_
267
     Each canonical BFD relocation record contains a pointer to the
268
     symbol to relocate to, the offset of the data to relocate, the
269
     section the data is in, and a pointer to a relocation type
270
     descriptor. Relocation is performed by passing messages through
271
     the relocation type descriptor and the symbol pointer. Therefore,
272
     relocations can be performed on output data using a relocation
273
     method that is only available in one of the input formats. For
274
     instance, Oasys provides a byte relocation format.  A relocation
275
     record requesting this relocation type would point indirectly to a
276
     routine to perform this, so the relocation may be performed on a
277
     byte being written to a 68k COFF file, even though 68k COFF has no
278
     such relocation type.
279
 
280
_line numbers_
281
     Object formats can contain, for debugging purposes, some form of
282
     mapping between symbols, source line numbers, and addresses in the
283
     output file.  These addresses have to be relocated along with the
284
     symbol information.  Each symbol with an associated list of line
285
     number records points to the first record of the list.  The head
286
     of a line number list consists of a pointer to the symbol, which
287
     allows finding out the address of the function whose line number
288
     is being described. The rest of the list is made up of pairs:
289
     offsets into the section and line numbers. Any format which can
290
     simply derive this information can pass it successfully between
291
     formats (COFF, IEEE and Oasys).
292
 
293

294
File: bfd.info,  Node: BFD front end,  Next: BFD back ends,  Prev: Overview,  Up: Top
295
 
296
BFD front end
297
*************
298
 
299
`typedef bfd'
300
=============
301
 
302
   A BFD has type `bfd'; objects of this type are the cornerstone of
303
any application using BFD. Using BFD consists of making references
304
though the BFD and to data in the BFD.
305
 
306
   Here is the structure that defines the type `bfd'.  It contains the
307
major data about the file and pointers to the rest of the data.
308
 
309
 
310
     struct _bfd
311
     {
312
         /* The filename the application opened the BFD with.  */
313
         CONST char *filename;
314
 
315
         /* A pointer to the target jump table.             */
316
         const struct bfd_target *xvec;
317
 
318
         /* To avoid dragging too many header files into every file that
319
            includes ``bfd.h'', IOSTREAM has been declared as a "char
320
            *", and MTIME as a "long".  Their correct types, to which they
321
            are cast when used, are "FILE *" and "time_t".    The iostream
322
            is the result of an fopen on the filename.  However, if the
323
            BFD_IN_MEMORY flag is set, then iostream is actually a pointer
324
            to a bfd_in_memory struct.  */
325
         PTR iostream;
326
 
327
         /* Is the file descriptor being cached?  That is, can it be closed as
328
            needed, and re-opened when accessed later?  */
329
 
330
         boolean cacheable;
331
 
332
         /* Marks whether there was a default target specified when the
333
            BFD was opened. This is used to select which matching algorithm
334
            to use to choose the back end. */
335
 
336
         boolean target_defaulted;
337
 
338
         /* The caching routines use these to maintain a
339
            least-recently-used list of BFDs */
340
 
341
         struct _bfd *lru_prev, *lru_next;
342
 
343
         /* When a file is closed by the caching routines, BFD retains
344
            state information on the file here: */
345
 
346
         file_ptr where;
347
 
348
         /* and here: (``once'' means at least once) */
349
 
350
         boolean opened_once;
351
 
352
         /* Set if we have a locally maintained mtime value, rather than
353
            getting it from the file each time: */
354
 
355
         boolean mtime_set;
356
 
357
         /* File modified time, if mtime_set is true: */
358
 
359
         long mtime;
360
 
361
         /* Reserved for an unimplemented file locking extension.*/
362
 
363
         int ifd;
364
 
365
         /* The format which belongs to the BFD. (object, core, etc.) */
366
 
367
         bfd_format format;
368
 
369
         /* The direction the BFD was opened with*/
370
 
371
         enum bfd_direction {no_direction = 0,
372
                             read_direction = 1,
373
                             write_direction = 2,
374
                             both_direction = 3} direction;
375
 
376
         /* Format_specific flags*/
377
 
378
         flagword flags;
379
 
380
         /* Currently my_archive is tested before adding origin to
381
            anything. I believe that this can become always an add of
382
            origin, with origin set to 0 for non archive files.   */
383
 
384
         file_ptr origin;
385
 
386
         /* Remember when output has begun, to stop strange things
387
            from happening. */
388
         boolean output_has_begun;
389
 
390
         /* Pointer to linked list of sections*/
391
         struct sec  *sections;
392
 
393
         /* The number of sections */
394
         unsigned int section_count;
395
 
396
         /* Stuff only useful for object files:
397
            The start address. */
398
         bfd_vma start_address;
399
 
400
         /* Used for input and output*/
401
         unsigned int symcount;
402
 
403
         /* Symbol table for output BFD (with symcount entries) */
404
         struct symbol_cache_entry  **outsymbols;
405
 
406
         /* Pointer to structure which contains architecture information*/
407
         const struct bfd_arch_info *arch_info;
408
 
409
         /* Stuff only useful for archives:*/
410
         PTR arelt_data;
411
         struct _bfd *my_archive;     /* The containing archive BFD.  */
412
         struct _bfd *next;           /* The next BFD in the archive.  */
413
         struct _bfd *archive_head;   /* The first BFD in the archive.  */
414
         boolean has_armap;
415
 
416
         /* A chain of BFD structures involved in a link.  */
417
         struct _bfd *link_next;
418
 
419
         /* A field used by _bfd_generic_link_add_archive_symbols.  This will
420
            be used only for archive elements.  */
421
         int archive_pass;
422
 
423
         /* Used by the back end to hold private data. */
424
 
425
         union
426
           {
427
           struct aout_data_struct *aout_data;
428
           struct artdata *aout_ar_data;
429
           struct _oasys_data *oasys_obj_data;
430
           struct _oasys_ar_data *oasys_ar_data;
431
           struct coff_tdata *coff_obj_data;
432
           struct pe_tdata *pe_obj_data;
433
           struct xcoff_tdata *xcoff_obj_data;
434
           struct ecoff_tdata *ecoff_obj_data;
435
           struct ieee_data_struct *ieee_data;
436
           struct ieee_ar_data_struct *ieee_ar_data;
437
           struct srec_data_struct *srec_data;
438
           struct ihex_data_struct *ihex_data;
439
           struct tekhex_data_struct *tekhex_data;
440
           struct elf_obj_tdata *elf_obj_data;
441
           struct nlm_obj_tdata *nlm_obj_data;
442
           struct bout_data_struct *bout_data;
443
           struct sun_core_struct *sun_core_data;
444
           struct sco5_core_struct *sco5_core_data;
445
           struct trad_core_struct *trad_core_data;
446
           struct som_data_struct *som_data;
447
           struct hpux_core_struct *hpux_core_data;
448
           struct hppabsd_core_struct *hppabsd_core_data;
449
           struct sgi_core_struct *sgi_core_data;
450
           struct lynx_core_struct *lynx_core_data;
451
           struct osf_core_struct *osf_core_data;
452
           struct cisco_core_struct *cisco_core_data;
453
           struct versados_data_struct *versados_data;
454
           struct netbsd_core_struct *netbsd_core_data;
455
           PTR any;
456
           } tdata;
457
 
458
         /* Used by the application to hold private data*/
459
         PTR usrdata;
460
 
461
       /* Where all the allocated stuff under this BFD goes.  This is a
462
          struct objalloc *, but we use PTR to avoid requiring the inclusion of
463
          objalloc.h.  */
464
         PTR memory;
465
     };
466
 
467
Error reporting
468
===============
469
 
470
   Most BFD functions return nonzero on success (check their individual
471
documentation for precise semantics).  On an error, they call
472
`bfd_set_error' to set an error condition that callers can check by
473
calling `bfd_get_error'.  If that returns `bfd_error_system_call', then
474
check `errno'.
475
 
476
   The easiest way to report a BFD error to the user is to use
477
`bfd_perror'.
478
 
479
Type `bfd_error_type'
480
---------------------
481
 
482
   The values returned by `bfd_get_error' are defined by the enumerated
483
type `bfd_error_type'.
484
 
485
 
486
     typedef enum bfd_error
487
     {
488
       bfd_error_no_error = 0,
489
       bfd_error_system_call,
490
       bfd_error_invalid_target,
491
       bfd_error_wrong_format,
492
       bfd_error_invalid_operation,
493
       bfd_error_no_memory,
494
       bfd_error_no_symbols,
495
       bfd_error_no_armap,
496
       bfd_error_no_more_archived_files,
497
       bfd_error_malformed_archive,
498
       bfd_error_file_not_recognized,
499
       bfd_error_file_ambiguously_recognized,
500
       bfd_error_no_contents,
501
       bfd_error_nonrepresentable_section,
502
       bfd_error_no_debug_section,
503
       bfd_error_bad_value,
504
       bfd_error_file_truncated,
505
       bfd_error_file_too_big,
506
       bfd_error_invalid_error_code
507
     } bfd_error_type;
508
 
509
`bfd_get_error'
510
...............
511
 
512
   *Synopsis*
513
     bfd_error_type bfd_get_error (void);
514
   *Description*
515
Return the current BFD error condition.
516
 
517
`bfd_set_error'
518
...............
519
 
520
   *Synopsis*
521
     void bfd_set_error (bfd_error_type error_tag);
522
   *Description*
523
Set the BFD error condition to be ERROR_TAG.
524
 
525
`bfd_errmsg'
526
............
527
 
528
   *Synopsis*
529
     CONST char *bfd_errmsg (bfd_error_type error_tag);
530
   *Description*
531
Return a string describing the error ERROR_TAG, or the system error if
532
ERROR_TAG is `bfd_error_system_call'.
533
 
534
`bfd_perror'
535
............
536
 
537
   *Synopsis*
538
     void bfd_perror (CONST char *message);
539
   *Description*
540
Print to the standard error stream a string describing the last BFD
541
error that occurred, or the last system error if the last BFD error was
542
a system call failure.  If MESSAGE is non-NULL and non-empty, the error
543
string printed is preceded by MESSAGE, a colon, and a space.  It is
544
followed by a newline.
545
 
546
BFD error handler
547
-----------------
548
 
549
   Some BFD functions want to print messages describing the problem.
550
They call a BFD error handler function.  This function may be overriden
551
by the program.
552
 
553
   The BFD error handler acts like printf.
554
 
555
 
556
     typedef void (*bfd_error_handler_type) PARAMS ((const char *, ...));
557
 
558
`bfd_set_error_handler'
559
.......................
560
 
561
   *Synopsis*
562
     bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
563
   *Description*
564
Set the BFD error handler function.  Returns the previous function.
565
 
566
`bfd_set_error_program_name'
567
............................
568
 
569
   *Synopsis*
570
     void bfd_set_error_program_name (const char *);
571
   *Description*
572
Set the program name to use when printing a BFD error.  This is printed
573
before the error message followed by a colon and space.  The string
574
must not be changed after it is passed to this function.
575
 
576
`bfd_get_error_handler'
577
.......................
578
 
579
   *Synopsis*
580
     bfd_error_handler_type bfd_get_error_handler (void);
581
   *Description*
582
Return the BFD error handler function.
583
 
584
Symbols
585
=======
586
 
587
`bfd_get_reloc_upper_bound'
588
...........................
589
 
590
   *Synopsis*
591
     long bfd_get_reloc_upper_bound(bfd *abfd, asection *sect);
592
   *Description*
593
Return the number of bytes required to store the relocation information
594
associated with section SECT attached to bfd ABFD.  If an error occurs,
595
return -1.
596
 
597
`bfd_canonicalize_reloc'
598
........................
599
 
600
   *Synopsis*
601
     long bfd_canonicalize_reloc
602
        (bfd *abfd,
603
         asection *sec,
604
         arelent **loc,
605
         asymbol **syms);
606
   *Description*
607
Call the back end associated with the open BFD ABFD and translate the
608
external form of the relocation information attached to SEC into the
609
internal canonical form.  Place the table into memory at LOC, which has
610
been preallocated, usually by a call to `bfd_get_reloc_upper_bound'.
611
Returns the number of relocs, or -1 on error.
612
 
613
   The SYMS table is also needed for horrible internal magic reasons.
614
 
615
`bfd_set_reloc'
616
...............
617
 
618
   *Synopsis*
619
     void bfd_set_reloc
620
        (bfd *abfd, asection *sec, arelent **rel, unsigned int count)
621
   *Description*
622
Set the relocation pointer and count within section SEC to the values
623
REL and COUNT.  The argument ABFD is ignored.
624
 
625
`bfd_set_file_flags'
626
....................
627
 
628
   *Synopsis*
629
     boolean bfd_set_file_flags(bfd *abfd, flagword flags);
630
   *Description*
631
Set the flag word in the BFD ABFD to the value FLAGS.
632
 
633
   Possible errors are:
634
   * `bfd_error_wrong_format' - The target bfd was not of object format.
635
 
636
   * `bfd_error_invalid_operation' - The target bfd was open for
637
     reading.
638
 
639
   * `bfd_error_invalid_operation' - The flag word contained a bit
640
     which was not applicable to the type of file.  E.g., an attempt
641
     was made to set the `D_PAGED' bit on a BFD format which does not
642
     support demand paging.
643
 
644
`bfd_set_start_address'
645
.......................
646
 
647
   *Synopsis*
648
     boolean bfd_set_start_address(bfd *abfd, bfd_vma vma);
649
   *Description*
650
Make VMA the entry point of output BFD ABFD.
651
 
652
   *Returns*
653
Returns `true' on success, `false' otherwise.
654
 
655
`bfd_get_mtime'
656
...............
657
 
658
   *Synopsis*
659
     long bfd_get_mtime(bfd *abfd);
660
   *Description*
661
Return the file modification time (as read from the file system, or
662
from the archive header for archive members).
663
 
664
`bfd_get_size'
665
..............
666
 
667
   *Synopsis*
668
     long bfd_get_size(bfd *abfd);
669
   *Description*
670
Return the file size (as read from file system) for the file associated
671
with BFD ABFD.
672
 
673
   The initial motivation for, and use of, this routine is not so we
674
can get the exact size of the object the BFD applies to, since that
675
might not be generally possible (archive members for example).  It
676
would be ideal if someone could eventually modify it so that such
677
results were guaranteed.
678
 
679
   Instead, we want to ask questions like "is this NNN byte sized
680
object I'm about to try read from file offset YYY reasonable?"  As as
681
example of where we might do this, some object formats use string
682
tables for which the first `sizeof(long)' bytes of the table contain
683
the size of the table itself, including the size bytes.  If an
684
application tries to read what it thinks is one of these string tables,
685
without some way to validate the size, and for some reason the size is
686
wrong (byte swapping error, wrong location for the string table, etc.),
687
the only clue is likely to be a read error when it tries to read the
688
table, or a "virtual memory exhausted" error when it tries to allocate
689
15 bazillon bytes of space for the 15 bazillon byte table it is about
690
to read.  This function at least allows us to answer the quesion, "is
691
the size reasonable?".
692
 
693
`bfd_get_gp_size'
694
.................
695
 
696
   *Synopsis*
697
     int bfd_get_gp_size(bfd *abfd);
698
   *Description*
699
Return the maximum size of objects to be optimized using the GP
700
register under MIPS ECOFF.  This is typically set by the `-G' argument
701
to the compiler, assembler or linker.
702
 
703
`bfd_set_gp_size'
704
.................
705
 
706
   *Synopsis*
707
     void bfd_set_gp_size(bfd *abfd, int i);
708
   *Description*
709
Set the maximum size of objects to be optimized using the GP register
710
under ECOFF or MIPS ELF.  This is typically set by the `-G' argument to
711
the compiler, assembler or linker.
712
 
713
`bfd_scan_vma'
714
..............
715
 
716
   *Synopsis*
717
     bfd_vma bfd_scan_vma(CONST char *string, CONST char **end, int base);
718
   *Description*
719
Convert, like `strtoul', a numerical expression STRING into a `bfd_vma'
720
integer, and return that integer.  (Though without as many bells and
721
whistles as `strtoul'.)  The expression is assumed to be unsigned
722
(i.e., positive).  If given a BASE, it is used as the base for
723
conversion.  A base of 0 causes the function to interpret the string in
724
hex if a leading "0x" or "0X" is found, otherwise in octal if a leading
725
zero is found, otherwise in decimal.
726
 
727
   Overflow is not detected.
728
 
729
`bfd_copy_private_bfd_data'
730
...........................
731
 
732
   *Synopsis*
733
     boolean bfd_copy_private_bfd_data(bfd *ibfd, bfd *obfd);
734
   *Description*
735
Copy private BFD information from the BFD IBFD to the the BFD OBFD.
736
Return `true' on success, `false' on error.  Possible error returns are:
737
 
738
   * `bfd_error_no_memory' - Not enough memory exists to create private
739
     data for OBFD.
740
 
741
     #define bfd_copy_private_bfd_data(ibfd, obfd) \
742
          BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
743
                    (ibfd, obfd))
744
 
745
`bfd_merge_private_bfd_data'
746
............................
747
 
748
   *Synopsis*
749
     boolean bfd_merge_private_bfd_data(bfd *ibfd, bfd *obfd);
750
   *Description*
751
Merge private BFD information from the BFD IBFD to the the output file
752
BFD OBFD when linking.  Return `true' on success, `false' on error.
753
Possible error returns are:
754
 
755
   * `bfd_error_no_memory' - Not enough memory exists to create private
756
     data for OBFD.
757
 
758
     #define bfd_merge_private_bfd_data(ibfd, obfd) \
759
          BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
760
                    (ibfd, obfd))
761
 
762
`bfd_set_private_flags'
763
.......................
764
 
765
   *Synopsis*
766
     boolean bfd_set_private_flags(bfd *abfd, flagword flags);
767
   *Description*
768
Set private BFD flag information in the BFD ABFD.  Return `true' on
769
success, `false' on error.  Possible error returns are:
770
 
771
   * `bfd_error_no_memory' - Not enough memory exists to create private
772
     data for OBFD.
773
 
774
     #define bfd_set_private_flags(abfd, flags) \
775
          BFD_SEND (abfd, _bfd_set_private_flags, \
776
                    (abfd, flags))
777
 
778
`stuff'
779
.......
780
 
781
   *Description*
782
Stuff which should be documented:
783
     #define bfd_sizeof_headers(abfd, reloc) \
784
          BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
785
 
786
     #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
787
          BFD_SEND (abfd, _bfd_find_nearest_line,  (abfd, sec, syms, off, file, func, line))
788
 
789
             /* Do these three do anything useful at all, for any back end?  */
790
     #define bfd_debug_info_start(abfd) \
791
             BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
792
 
793
     #define bfd_debug_info_end(abfd) \
794
             BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
795
 
796
     #define bfd_debug_info_accumulate(abfd, section) \
797
             BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
798
 
799
 
800
     #define bfd_stat_arch_elt(abfd, stat) \
801
             BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
802
 
803
     #define bfd_update_armap_timestamp(abfd) \
804
             BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
805
 
806
     #define bfd_set_arch_mach(abfd, arch, mach)\
807
             BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
808
 
809
     #define bfd_relax_section(abfd, section, link_info, again) \
810
            BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
811
 
812
     #define bfd_gc_sections(abfd, link_info) \
813
            BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
814
 
815
     #define bfd_link_hash_table_create(abfd) \
816
            BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
817
 
818
     #define bfd_link_add_symbols(abfd, info) \
819
            BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
820
 
821
     #define bfd_final_link(abfd, info) \
822
            BFD_SEND (abfd, _bfd_final_link, (abfd, info))
823
 
824
     #define bfd_free_cached_info(abfd) \
825
            BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
826
 
827
     #define bfd_get_dynamic_symtab_upper_bound(abfd) \
828
            BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
829
 
830
     #define bfd_print_private_bfd_data(abfd, file)\
831
            BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
832
 
833
     #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
834
            BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
835
 
836
     #define bfd_get_dynamic_reloc_upper_bound(abfd) \
837
            BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
838
 
839
     #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
840
            BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
841
 
842
     extern bfd_byte *bfd_get_relocated_section_contents
843
            PARAMS ((bfd *, struct bfd_link_info *,
844
                      struct bfd_link_order *, bfd_byte *,
845
                      boolean, asymbol **));
846
 
847
* Menu:
848
 
849
* Memory Usage::
850
* Initialization::
851
* Sections::
852
* Symbols::
853
* Archives::
854
* Formats::
855
* Relocations::
856
* Core Files::
857
* Targets::
858
* Architectures::
859
* Opening and Closing::
860
* Internal::
861
* File Caching::
862
* Linker Functions::
863
* Hash Tables::
864
 
865

866
File: bfd.info,  Node: Memory Usage,  Next: Initialization,  Prev: BFD front end,  Up: BFD front end
867
 
868
Memory usage
869
============
870
 
871
   BFD keeps all of its internal structures in obstacks. There is one
872
obstack per open BFD file, into which the current state is stored. When
873
a BFD is closed, the obstack is deleted, and so everything which has
874
been allocated by BFD for the closing file is thrown away.
875
 
876
   BFD does not free anything created by an application, but pointers
877
into `bfd' structures become invalid on a `bfd_close'; for example,
878
after a `bfd_close' the vector passed to `bfd_canonicalize_symtab' is
879
still around, since it has been allocated by the application, but the
880
data that it pointed to are lost.
881
 
882
   The general rule is to not close a BFD until all operations dependent
883
upon data from the BFD have been completed, or all the data from within
884
the file has been copied. To help with the management of memory, there
885
is a function (`bfd_alloc_size') which returns the number of bytes in
886
obstacks associated with the supplied BFD. This could be used to select
887
the greediest open BFD, close it to reclaim the memory, perform some
888
operation and reopen the BFD again, to get a fresh copy of the data
889
structures.
890
 
891

892
File: bfd.info,  Node: Initialization,  Next: Sections,  Prev: Memory Usage,  Up: BFD front end
893
 
894
Initialization
895
==============
896
 
897
   These are the functions that handle initializing a BFD.
898
 
899
`bfd_init'
900
..........
901
 
902
   *Synopsis*
903
     void bfd_init(void);
904
   *Description*
905
This routine must be called before any other BFD function to initialize
906
magical internal data structures.
907
 
908

909
File: bfd.info,  Node: Sections,  Next: Symbols,  Prev: Initialization,  Up: BFD front end
910
 
911
Sections
912
========
913
 
914
   The raw data contained within a BFD is maintained through the
915
section abstraction.  A single BFD may have any number of sections.  It
916
keeps hold of them by pointing to the first; each one points to the
917
next in the list.
918
 
919
   Sections are supported in BFD in `section.c'.
920
 
921
* Menu:
922
 
923
* Section Input::
924
* Section Output::
925
* typedef asection::
926
* section prototypes::
927
 
928

929
File: bfd.info,  Node: Section Input,  Next: Section Output,  Prev: Sections,  Up: Sections
930
 
931
Section input
932
-------------
933
 
934
   When a BFD is opened for reading, the section structures are created
935
and attached to the BFD.
936
 
937
   Each section has a name which describes the section in the outside
938
world--for example, `a.out' would contain at least three sections,
939
called `.text', `.data' and `.bss'.
940
 
941
   Names need not be unique; for example a COFF file may have several
942
sections named `.data'.
943
 
944
   Sometimes a BFD will contain more than the "natural" number of
945
sections. A back end may attach other sections containing constructor
946
data, or an application may add a section (using `bfd_make_section') to
947
the sections attached to an already open BFD. For example, the linker
948
creates an extra section `COMMON' for each input file's BFD to hold
949
information about common storage.
950
 
951
   The raw data is not necessarily read in when the section descriptor
952
is created. Some targets may leave the data in place until a
953
`bfd_get_section_contents' call is made. Other back ends may read in
954
all the data at once.  For example, an S-record file has to be read
955
once to determine the size of the data. An IEEE-695 file doesn't
956
contain raw data in sections, but data and relocation expressions
957
intermixed, so the data area has to be parsed to get out the data and
958
relocations.
959
 
960

961
File: bfd.info,  Node: Section Output,  Next: typedef asection,  Prev: Section Input,  Up: Sections
962
 
963
Section output
964
--------------
965
 
966
   To write a new object style BFD, the various sections to be written
967
have to be created. They are attached to the BFD in the same way as
968
input sections; data is written to the sections using
969
`bfd_set_section_contents'.
970
 
971
   Any program that creates or combines sections (e.g., the assembler
972
and linker) must use the `asection' fields `output_section' and
973
`output_offset' to indicate the file sections to which each section
974
must be written.  (If the section is being created from scratch,
975
`output_section' should probably point to the section itself and
976
`output_offset' should probably be zero.)
977
 
978
   The data to be written comes from input sections attached (via
979
`output_section' pointers) to the output sections.  The output section
980
structure can be considered a filter for the input section: the output
981
section determines the vma of the output data and the name, but the
982
input section determines the offset into the output section of the data
983
to be written.
984
 
985
   E.g., to create a section "O", starting at 0x100, 0x123 long,
986
containing two subsections, "A" at offset 0x0 (i.e., at vma 0x100) and
987
"B" at offset 0x20 (i.e., at vma 0x120) the `asection' structures would
988
look like:
989
 
990
        section name          "A"
991
          output_offset   0x00
992
          size            0x20
993
          output_section ----------->  section name    "O"
994
                                  |    vma             0x100
995
        section name          "B" |    size            0x123
996
          output_offset   0x20    |
997
          size            0x103   |
998
          output_section  --------|
999
 
1000
Link orders
1001
-----------
1002
 
1003
   The data within a section is stored in a "link_order".  These are
1004
much like the fixups in `gas'.  The link_order abstraction allows a
1005
section to grow and shrink within itself.
1006
 
1007
   A link_order knows how big it is, and which is the next link_order
1008
and where the raw data for it is; it also points to a list of
1009
relocations which apply to it.
1010
 
1011
   The link_order is used by the linker to perform relaxing on final
1012
code.  The compiler creates code which is as big as necessary to make
1013
it work without relaxing, and the user can select whether to relax.
1014
Sometimes relaxing takes a lot of time.  The linker runs around the
1015
relocations to see if any are attached to data which can be shrunk, if
1016
so it does it on a link_order by link_order basis.
1017
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.