source: rtems-tools/rtemstoolkit/rld-files.h @ 3618a62

Last change on this file since 3618a62 was 82c8788, checked in by Chris Johns <chrisj@…>, on Apr 14, 2018 at 4:15:07 AM

rtemstoolkit/rtl-file: Remove a file on close if requested

Close #3395

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