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