source: rtems-tools/rtemstoolkit/rld-files.h @ 87e0e76

4.104.11
Last change on this file since 87e0e76 was 87e0e76, checked in by Chris Johns <chrisj@…>, on Sep 13, 2014 at 2:09:16 AM

Refactor code into the RTEMS Toolkit.

  • Property mode set to 100644
File size: 26.6 KB
Line 
1/*
2 * Copyright (c) 2011, Chris Johns <chrisj@rtems.org>
3 *
4 * Permission to use, copy, modify, and/or distribute this software for any
5 * purpose with or without fee is hereby granted, provided that the above
6 * copyright notice and this permission notice appear in all copies.
7 *
8 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 */
16/**
17 * @file
18 *
19 * @ingroup rtems-ld
20 *
21 * @brief RTEMS Linker file manages access the image contained in various file
22 * formats.
23 *
24 * The base element is a file. It references a object file that is either
25 * inside an archive or stand alone. You access a object file by constructing a
26 * handle. A handle is the object file with the specific file descriptor
27 * created when the archive or object file was opened.
28 *
29 *
30 */
31
32#if !defined (_RLD_FILES_H_)
33#define _RLD_FILES_H_
34
35#include <list>
36#include <map>
37#include <string>
38#include <vector>
39
40#include <rld.h>
41#include <rld-path.h>
42
43namespace rld
44{
45  namespace files
46  {
47    /**
48     * Container of files.
49     */
50    typedef std::vector < file > files;
51
52    /**
53     * Container of archive files.
54     */
55    typedef std::map < const std::string, archive* > archives;
56
57    /**
58     * Container of object files.
59     */
60    typedef std::map < const std::string, object* > objects;
61
62    /**
63     * Container list of object files.
64     */
65    typedef std::list < object* > object_list;
66
67    /**
68     * A file is a single object file that is either in an @ref archive or
69     * a separate stand alone @ref object file.
70     */
71    class file
72    {
73    public:
74      /**
75       * Construct the file from the component parts when part of an archive.
76       *
77       * @param aname The archive name.
78       * @param oname The object file name.
79       * @param offset The offset in the archive the object file starts.
80       * @param size The size of the archive the object file starts.
81       */
82      file (const std::string& aname,
83            const std::string& oname,
84            off_t              offset,
85            size_t             size);
86
87      /**
88       * Construct the name by splitting the full path into an archive,
89       * object file name and offset.
90       *
91       * @param path The path to the image.
92       * @param is_object If true (default) the name is for an object file.
93       */
94      file (const std::string& path, bool is_object = true);
95
96      /**
97       * Contruct an empty file.
98       */
99      file ();
100
101      /**
102       * Set a name from the path.
103       *
104       * @param path The path to the image.
105       * @param is_object If true (default) the name is for an object file.
106       */
107      void set (const std::string& path, bool is_object = true);
108
109      /**
110       * Is an archive returns true if the file is in an archive.
111       *
112       * @retval true The object file is in an archive.
113       * @retval false The object file is stand alone.
114       */
115      bool is_archive () const;
116
117      /**
118       * Is object file stand alone.
119       *
120       * @retval true The object file is stand alone.
121       * @retval false The object could be part of an archive.
122       */
123      bool is_object () const;
124
125      /**
126       * Valid returns true if there is a valid name.
127       *
128       * @retval true There is a valid name.
129       * @retval false There is not name assigned.
130       */
131      bool is_valid () const;
132
133      /**
134       * Exists returns true if the archive or object file is present on disk
135       * and a regular file.
136       *
137       * @retval true The file is valid and a regular file.
138       * @retval false The file is either not present, not accessable or not a
139       *               regular file.
140       */
141      bool exists () const;
142
143      /**
144       * The path maps to the real file on disk. The file may not be valid.
145       *
146       * @return const std::string The real path to the file on disk.
147       */
148      const std::string path () const;
149
150      /**
151       * The full path.
152       *
153       * @return const std::string The full path to the image.
154       */
155      const std::string full () const;
156
157      /**
158       * The base path. It is the basename of the full path.
159       *
160       * @return const std::string The basename of the full path to the image.
161       */
162      const std::string basename () const;
163
164      /**
165       * The archive name component. A length of 0 means there was not
166       * archive component.
167       *
168       * @return const std::string& The archive name.
169       */
170      const std::string& aname () const;
171
172      /**
173       * The object name. There is always an object name.
174       *
175       * @return const std::string& The object name.
176       */
177      const std::string& oname () const;
178
179      /**
180       * The object's offset in the archive or on disk.
181       *
182       * @return off_t The offset part of the file name.
183       */
184      off_t offset () const;
185
186      /**
187       * The object's size in the archive.
188       *
189       * @return size_t The size of the file in bytes.
190       */
191      size_t size () const;
192
193    private:
194      std::string aname_;  //< The archive name.
195      std::string oname_;  //< The object name.
196      off_t       offset_; //< The object's offset in the archive.
197      size_t      size_;   //< The object's size in the archive or on disk.
198    };
199
200    /**
201     * Image is the base file type and lets us have a single container to hold
202     * the types of images we need to support.
203     */
204    class image
205    {
206    public:
207      /**
208       * Construct the image.
209       *
210       * @param name The name of the image.
211       */
212      image (file& name);
213
214      /**
215       * Construct the image.
216       *
217       * @param path The file path.
218       * @param is_object If true (default) the name is for an object file.
219       */
220      image (const std::string& path, bool is_object = true);
221
222      /**
223       * Construct the image.
224       */
225      image ();
226
227      /**
228       * Destruct the image.
229       */
230      virtual ~image ();
231
232      /**
233       * Open the image. You can open the image more than once but you need to
234       * close it the same number of times.
235       *
236       * @param name The @ref file name.
237       */
238      virtual void open (file& name);
239
240      /**
241       * Open the image. You can open the image more than once but you need to
242       * close it the same number of times.
243       *
244       * @param writeable If true the image is open as writable. The default is
245       *                  false.
246       */
247      virtual void open (bool writable = false);
248
249      /**
250       * Close the image.
251       */
252      virtual void close ();
253
254      /**
255       * Read a block from the file.
256       *
257       * @param buffer The buffer to read the data into.
258       * @param size The amount of data to read.
259       * @return ssize_t The amount of data read.
260       */
261      virtual ssize_t read (void* buffer, size_t size);
262
263      /**
264       * Write a block from the file.
265       *
266       * @param buffer The buffer of data to write.
267       * @param size The amount of data to write.
268       * @return ssize_t The amount of data written.
269       */
270      virtual ssize_t write (const void* buffer, size_t size);
271
272      /**
273       * Seek to the offset in the image.
274       *
275       * @param offset The offset to seek too.
276       */
277      virtual void seek (off_t offset);
278
279      /**
280       * Seek and then read.
281       *
282       * @param offset The offset to seek too before reading.
283       * @param buffer The buffer to read the data into.
284       * @param size The amount of data to read.
285       * @retval true The data requested was read.
286       * @retval false The request data was not read.
287       */
288      virtual bool seek_read (off_t offset, uint8_t* buffer, size_t size);
289
290      /**
291       * Seek and then write.
292       *
293       * @param offset The offset to seek too before writing.
294       * @param buffer The buffer of data to write.
295       * @param size The amount of data to write.
296       * @retval true The data requested was written.
297       * @retval false The request data was not written.
298       */
299      virtual bool seek_write (off_t offset, const void* buffer, size_t size);
300
301      /**
302       * The name of the image.
303       *
304       * @param const file& The @ref file name of the image.
305       */
306      const file& name () const;
307
308      /**
309       * References to the image.
310       *
311       * @return int The number of references the image has.
312       */
313      virtual int references () const;
314
315      /**
316       * The file size.
317       *
318       * @return size_t The size of the image.
319       */
320      virtual size_t size () const;
321
322      /**
323       * The file descriptor.
324       *
325       * @return int The operating system file descriptor handle.
326       */
327      virtual int fd () const;
328
329      /**
330       * The ELF reference.
331       *
332       * @return elf::file& The @ref elf::file object of the image.
333       */
334      elf::file& elf ();
335
336      /**
337       * A symbol in the image has been referenced.
338       */
339      virtual void symbol_referenced ();
340
341      /**
342       * Return the number of symbol references.
343       *
344       * @return int The symbol references count.
345       */
346      virtual int symbol_references () const;
347
348      /**
349       * The path maps to the real file on disk. The file may not be valid.
350       *
351       * @return const std::string The real path to the file on disk.
352       */
353      const std::string path () const {
354        return name ().path ();
355      }
356
357      /**
358       * Is the image open ?
359       *
360       * @retval true The image is open.
361       * @retval false The image is not open.
362       */
363      bool is_open () const {
364        return fd () != -1;
365      }
366
367      /**
368       * Is the image writable ?
369       *
370       * @retval true The image is writable.
371       * @retval false The image is not writable.
372       */
373      bool is_writable () const {
374        return writable;
375      }
376
377    private:
378
379      file      name_;       //< The name of the file.
380      int       references_; //< The number of handles open.
381      int       fd_;         //< The file descriptor of the archive.
382      elf::file elf_;        //< The libelf reference.
383      int       symbol_refs; //< The number of symbols references made.
384      bool      writable;    //< The image is writable.
385    };
386
387    /**
388     * Copy the input section of the image to the output section. The file
389     * positions in the images must be set before making the call.
390     *
391     * @param in The input image.
392     * @param out The output image.
393     * @param size The amouint of data to copy.
394     */
395    void copy (image& in, image& out, size_t size);
396
397    /**
398     * The archive class proivdes access to object files that are held in a AR
399     * format file. GNU AR extensions are supported. The archive is a kind of
400     * @ref image and provides the container for the @ref object's that it
401     * contains.
402     */
403    class archive:
404      public image
405    {
406    public:
407      /**
408       * Open a archive format file that contains ELF object files.
409       *
410       * @param name The name of the @ref archive.
411       */
412      archive (const std::string& name);
413
414      /**
415       * Close the archive.
416       */
417      virtual ~archive ();
418
419      /**
420       * Begin the ELF session.
421       */
422      void begin ();
423
424      /**
425       * End the ELF session.
426       */
427      void end ();
428
429      /**
430       * Match the archive name.
431       *
432       * @param name The name of the archive to check.
433       * @retval true The name matches.
434       * @retval false The name does not match.
435       */
436      bool is (const std::string& name) const;
437
438      /**
439       * Check this is a valid archive.
440       *
441       * @retval true It is a valid archive.
442       * @retval false It is not a valid archive.
443       */
444      bool is_valid ();
445
446      /**
447       * Load @ref object's from the @ref archive adding each to the provided
448       * @ref objects container.
449       *
450       * @param objs The container the loaded object files are added too.
451       */
452      void load_objects (objects& objs);
453
454      /**
455       * Get the name.
456       *
457       * @return const std::string& Return a reference to the archive's name.
458       */
459      const std::string& get_name () const;
460
461      /**
462       * Less than operator for the map container. It compares the name of the
463       * the @ref archive.
464       *
465       * @param rhs The right hand side of the '<' operator.
466       * @return true The right hand side is less than this archive.
467       * @return false The right hand side is greater than or equal to this
468       *               archive.
469       */
470      bool operator< (const archive& rhs) const;
471
472      /**
473       * Create a new archive containing the given set of objects. If
474       * referening an existing archive it is overwritten.
475       *
476       * @param objects The list of objects to place in the archive.
477       */
478      void create (object_list& objects);
479
480    private:
481
482      /**
483       * Read the archive header and check the magic number is valid.
484       *
485       * @param offset The offset in the file to read the header.
486       * @param header Read the header into here. There must be enough space.
487       * @retval true The header was read successfull and the magic number
488       *               matched.
489       * @retval false The header could not be read from the @ref image.
490       */
491      bool read_header (off_t offset, uint8_t* header);
492
493      /**
494       * Add the object file from the archive to the object's container.
495       *
496       * @param objs The container to add the object to.
497       * @param name The name of the object file being added.
498       * @param offset The offset in the @ref archive of the object file.
499       * @param size The size of the object file.
500       */
501      void add_object (objects&    objs,
502                       const char* name,
503                       off_t       offset,
504                       size_t      size);
505
506      /**
507       * Write a file header into the archive.
508       *
509       * @param name The name of the archive.
510       * @param mtime The modified time of the archive.
511       * @param uid The user id of the archive.
512       * @param gid The group id of the archive.
513       * @param mode The mode of the archive.
514       * @param size The size of the archive.
515       */
516      void write_header (const std::string& name,
517                         uint32_t           mtime,
518                         int                uid,
519                         int                gid,
520                         int                mode,
521                         size_t             size);
522
523      /**
524       * Cannot copy via a copy constructor.
525       */
526      archive (const archive& orig);
527
528      /**
529       * Cannot assign using the assignment operator.
530       */
531      archive& operator= (const archive& rhs);
532    };
533
534    /**
535     * A relocation record. We extract what we want because the elf::section
536     * class requires the image be left open as references are alive. We
537     * extract and keep the data we need to create the image.
538     */
539    struct relocation
540    {
541      const uint32_t    offset;    //< The section offset.
542      const uint32_t    type;      //< The type of relocation record.
543      const uint32_t    info;      //< The ELF info field.
544      const int32_t     addend;    //< The constant addend.
545      const std::string symname;   //< The name of the symbol.
546      const uint32_t    symtype;   //< The type of symbol.
547      const int         symsect;   //< The symbol's section symbol.
548      const uint32_t    symvalue;  //< The symbol's value.
549      const uint32_t    symbinding;//< The symbol's binding.
550
551      /**
552       * Construct from an ELF relocation record.
553       */
554      relocation (const elf::relocation& er);
555
556    private:
557      /**
558       * The default constructor is not allowed due to all elements being
559       * const.
560       */
561      relocation ();
562    };
563
564    /**
565     * A container of relocations.
566     */
567    typedef std::list < relocation > relocations;
568
569    /**
570     * The sections attributes. We extract what we want because the
571     * elf::section class requires the image be left open as references are
572     * alive. We extract and keep the data we need to create the image.
573     */
574    struct section
575    {
576      const std::string name;      //< The name of the section.
577      const int         index;     //< The section's index in the object file.
578      const uint32_t    type;      //< The type of section.
579      const size_t      size;      //< The size of the section.
580      const uint32_t    alignment; //< The alignment of the section.
581      const uint32_t    link;      //< The ELF link field.
582      const uint32_t    info;      //< The ELF info field.
583      const uint32_t    flags;     //< The ELF flags.
584      const off_t       offset;    //< The ELF file offset.
585      bool              rela;      //< Relocation records have the addend field.
586      relocations       relocs;    //< The sections relocations.
587
588      /**
589       * Construct from an ELF section.
590       *
591       * @param es The ELF section to load the object file section from.
592       */
593      section (const elf::section& es);
594
595      /**
596       * Load the ELF relocations.
597       *
598       * @param es The ELF section to load the relocations from.
599       */
600      void load_relocations (const elf::section& es);
601
602    private:
603      /**
604       * The default constructor is not allowed due to all elements being
605       * const.
606       */
607      section ();
608    };
609
610    /**
611     * A container of sections.
612     */
613    typedef std::list < section > sections;
614
615    /**
616     * Sum the sizes of a container of sections.
617     */
618    size_t sum_sizes (const sections& secs);
619
620    /**
621     * Find the section that matches the index in the sections provided.
622     */
623    const section* find (const sections& secs, const int index);
624
625    /**
626     * The object file cab be in an archive or a file.
627     */
628    class object:
629      public image
630    {
631    public:
632      /**
633       * Construct an object image that is part of an archive.
634       *
635       * @param archive_ The archive the object file is part of.
636       * @param file_ The image file.
637       */
638      object (archive& archive_, file& file_);
639
640      /**
641       * Construct the object file.
642       *
643       * @param path The object file path.
644       */
645      object (const std::string& path);
646
647      /**
648       * Construct the object file.
649       */
650      object ();
651
652      /**
653       * Destruct the object file.
654       */
655      virtual ~object ();
656
657      /**
658       * Open the object file.
659       */
660      virtual void open (bool writable = false);
661
662      /**
663       * Close the object.
664       */
665      virtual void close ();
666
667      /**
668       * Begin the object file session.
669       */
670      void begin ();
671
672      /**
673       * End the object file session.
674       */
675      void end ();
676
677      /**
678       * If valid returns true the begin has been called and the object has
679       * been validated as being in a suitable format.
680       */
681      bool valid () const;
682
683      /**
684       * Load the symbols into the symbols table.
685       *
686       * @param symbols The symbol table to load.
687       * @param local Include local symbols. The default is not to.
688       */
689      void load_symbols (symbols::table& symbols, bool local = false);
690
691      /**
692       * Load the relocations.
693       */
694      void load_relocations ();
695
696      /**
697       * References to the image.
698       */
699      virtual int references () const;
700
701      /**
702       * The file size.
703       */
704      virtual size_t size () const;
705
706      /**
707       * The file descriptor.
708       */
709      virtual int fd () const;
710
711      /**
712       * A symbol in the image has been referenced.
713       */
714      virtual void symbol_referenced ();
715
716      /**
717       * The archive the object file is contained in. If 0 the object file is
718       * not contained in an archive.
719       */
720      archive* get_archive ();
721
722      /**
723       * Return the unresolved symbol table for this object file.
724       */
725      symbols::symtab& unresolved_symbols ();
726
727      /**
728       * Return the list external symbols.
729       */
730      symbols::pointers& external_symbols ();
731
732      /**
733       * Return a container sections that match the requested type and
734       * flags. The filtered section container is not cleared so any matching
735       * sections are appended.
736       *
737       * @param filtered_secs The container of the matching sections.
738       * @param type The section type. Must match. If 0 matches any.
739       * @param flags_in The sections flags that must be set. This is a
740       *                 mask. If 0 matches any.
741       * @param flags_out The sections flags that must be clear. This is a
742       *                 mask. If 0 this value is ignored.
743       */
744      void get_sections (sections& filtered_secs,
745                         uint32_t  type = 0,
746                         uint64_t  flags_in = 0,
747                         uint64_t  flags_out = 0);
748
749      /**
750       * Return a container sections that match the requested name. The
751       * filtered section container is not cleared so any matching sections are
752       * appended.
753       *
754       * @param filtered_secs The container of the matching sections.
755       * @param name The name of the section.
756       */
757      void get_sections (sections& filtered_secs, const std::string& name);
758
759      /**
760       * Get a section given an index number.
761       *
762       * @param index The section index to search for.
763       */
764      const section& get_section (int index) const;
765
766      /**
767       * Set the object file's resolving flag.
768       */
769      void resolve_set ();
770
771      /**
772       * Clear the object file's resolving flag.
773       */
774      void resolve_clear ();
775
776      /**
777       * The resolving state.
778       */
779      bool resolving () const;
780
781      /**
782       * Set the object file resolved flag.
783       */
784      void resolved_set ();
785
786      /**
787       * The resolved state.
788       */
789      bool resolved () const;
790
791    private:
792      archive*          archive_;   //< Points to the archive if part of an
793                                    //  archive.
794      bool              valid_;     //< If true begin has run and finished.
795      symbols::symtab   unresolved; //< This object's unresolved symbols.
796      symbols::pointers externals;  //< This object's external symbols.
797      sections          secs;       //< The sections.
798      bool              resolving_; //< The object is being resolved.
799      bool              resolved_;  //< The object has been resolved.
800
801      /**
802       * Cannot copy via a copy constructor.
803       */
804      object (const object& orig);
805
806      /**
807       * Cannot assign using the assignment operator.
808       */
809      object& operator= (const object& rhs);
810    };
811
812    /**
813     * A collection of objects files as a cache. This currently is not a cache
814     * but it could become one.
815     */
816    class cache
817    {
818    public:
819      /**
820       * Construct the cache.
821       */
822      cache ();
823
824      /**
825       * Destruct the objects.
826       */
827      virtual ~cache ();
828
829      /**
830       * Open the cache by collecting the file names, loading object headers
831       * and loading the archive file names.
832       */
833      void open ();
834
835      /**
836       * Close the cache.
837       */
838      void close ();
839
840      /**
841       * Add a file path to the cache.
842       */
843      void add (const std::string& path);
844
845      /**
846       * Add a container of path to the cache.
847       */
848      void add (path::paths& paths__);
849
850      /**
851       * Add a container of path to the cache.
852       */
853      void add_libraries (path::paths& paths__);
854
855      /**
856       * Being a session on an archive.
857       */
858      void archive_begin (const std::string& path);
859
860      /**
861       * End a session on an archive.
862       */
863      void archive_end (const std::string& path);
864
865      /**
866       * Being sessions on all archives.
867       */
868      void archives_begin ();
869
870      /**
871       * End the archive sessions.
872       */
873      void archives_end ();
874
875      /**
876       * Collect the object names and add them to the cache.
877       */
878      void collect_object_files ();
879
880      /**
881       * Collect the object file names by verifing the paths to the files are
882       * valid or read the object file names contained in any archives.
883       */
884      void collect_object_files (const std::string& path);
885
886      /**
887       * Load the symbols into the symbol table.
888       *
889       * @param symbols The symbol table to load.
890       * @param locals Include local symbols. The default does not include them.
891       */
892      void load_symbols (symbols::table& symbols, bool locals = false);
893
894      /**
895       * Output the unresolved symbol table to the output stream.
896       */
897      void output_unresolved_symbols (std::ostream& out);
898
899      /**
900       * Get the archives.
901       */
902      archives& get_archives ();
903
904      /**
905       * Get the objects inlcuding those in archives.
906       */
907      objects& get_objects ();
908
909      /**
910       * Get the added objects. Does not include the ones in th archives.
911       */
912      void get_objects (object_list& list) const;
913
914      /**
915       * Get the paths.
916       */
917      const path::paths& get_paths () const;
918
919      /**
920       * Get the archive files.
921       */
922      void get_archive_files (files& afiles);
923
924      /**
925       * Get the object files including those in archives.
926       */
927      void get_object_files (files& ofiles);
928
929      /**
930       * Get the archive count.
931       */
932      int archive_count () const;
933
934      /**
935       * Get the object count.
936       */
937      int object_count () const;
938
939      /**
940       * Get the path count.
941       */
942      int path_count () const;
943
944      /**
945       * Output archive files.
946       */
947      void output_archive_files (std::ostream& out);
948
949      /**
950       * Output archive files.
951       */
952      void output_object_files (std::ostream& out);
953
954    protected:
955
956      /**
957       * Input a path into the cache.
958       */
959      virtual void input (const std::string& path);
960
961    private:
962      path::paths paths_;    //< The names of the files to process.
963      archives    archives_; //< The archive files.
964      objects     objects_;  //< The object files.
965      bool        opened;    //< The cache is open.
966    };
967
968    /**
969     * Copy the in file to the out file.
970     *
971     * @param in The input file.
972     * @param out The output file.
973     * @param size The amount to copy. If 0 the whole on in is copied.
974     */
975    void copy_file (image& in, image& out, size_t size = 0);
976
977    /**
978     * Find the libraries given the list of libraries as bare name which
979     * have 'lib' and '.a' added.
980     */
981    void find_libraries (path::paths& libraries,
982                         path::paths& libpaths,
983                         path::paths& libs);
984
985  }
986}
987
988#endif
Note: See TracBrowser for help on using the repository browser.