rtems/rtl/rtl-archive.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /*
0004  *  COPYRIGHT (c) 2018 Chris Johns <chrisj@rtems.org>
0005  *
0006  * Redistribution and use in source and binary forms, with or without
0007  * modification, are permitted provided that the following conditions
0008  * are met:
0009  * 1. Redistributions of source code must retain the above copyright
0010  *    notice, this list of conditions and the following disclaimer.
0011  * 2. Redistributions in binary form must reproduce the above copyright
0012  *    notice, this list of conditions and the following disclaimer in the
0013  *    documentation and/or other materials provided with the distribution.
0014  *
0015  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0016  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0017  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0018  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0019  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0020  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0021  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0022  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0023  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0024  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0025  * POSSIBILITY OF SUCH DAMAGE.
0026  */
0027 /**
0028  * @file
0029  *
0030  * @ingroup rtems_rtl
0031  *
0032  * @brief RTEMS Run-Time Linker Archive
0033  *
0034  * The RTL Archive module manages dependent loading of object files from
0035  * archives. The archives need to have a `ranlib` generated symbol table.
0036  *
0037  * This module reads a configuration file called `rtl-libs.conf` from a default
0038  * directory of `/etc`. The file is a line per glob'ed path to archives to
0039  * search for symbols.
0040  *
0041  * The archive symbols are held in a per archive cache for searching.
0042  *
0043  * @note Errors in the reading of a config file, locating archives, reading
0044  *       symbol tables and loading object files are not considered RTL error
0045  *       reported to a user. The user error is undefined symbols.
0046  */
0047
0048 #if !defined (_RTEMS_RTL_ARCHIVE_H_)
0049 #define _RTEMS_RTL_ARCHIVE_H_
0050
0051 #include <rtems.h>
0052 #include <rtems/chain.h>
0053 #include <rtems/printer.h>
0054
0055 #ifdef __cplusplus
0056 extern "C" {
0057 #endif /* __cplusplus */
0058
0059 /**
0060  * Flags for archives.
0061  */
0062 #define RTEMS_RTL_ARCHIVE_USER_LOAD (1 << 0) /**< User forced load. */
0063 #define RTEMS_RTL_ARCHIVE_REMOVE    (1 << 1) /**< The achive is not found. */
0064 #define RTEMS_RTL_ARCHIVE_LOAD      (1 << 2) /**< Load the achive. */
0065
0066 /**
0067  * Symbol search and loading results.
0068  */
0069 typedef enum rtems_rtl_archive_search
0070 {
0071   rtems_rtl_archive_search_not_found = 0, /**< The search failed to find the
0072                                                symbol. */
0073   rtems_rtl_archive_search_found = 1,     /**< The symbols was found. */
0074   rtems_rtl_archive_search_loaded = 2,    /**< The symbol was found and the
0075                                                object file has been loaded */
0076   rtems_rtl_archive_search_error = 3,     /**< There was an error searching or
0077                                                loading. */
0078   rtems_rtl_archive_search_no_config = 4 /**< There is no config or it is
0079                                           *   invalid. */
0080 } rtems_rtl_archive_search;
0081
0082 /**
0083  * RTL Archive symbols.
0084  */
0085 typedef struct rtems_rtl_archive_symbol
0086 {
0087   size_t      entry;  /**< Index in the symbol offset table. */
0088   const char* label;  /**< The symbol's label. */
0089 } rtems_rtl_archive_symbol;
0090
0091 /**
0092  * RTL Archive symbols.
0093  */
0094 typedef struct rtems_rtl_archive_symbols
0095 {
0096   void*                     base;     /**< Base of the symbol table. */
0097   size_t                    size;     /**< Size of the symbol table. */
0098   size_t                    entries;  /**< Entries in the symbol table. */
0099   const char*               names;    /**< Start of the symbol names. */
0100   rtems_rtl_archive_symbol* symbols;  /**< Sorted symbol table. */
0101 } rtems_rtl_archive_symbols;
0102
0103 /**
0104  * RTL Archive data.
0105  */
0106 typedef struct rtems_rtl_archive
0107 {
0108   rtems_chain_node          node;     /**< Chain link. */
0109   const char*               name;     /**< Archive absolute path. */
0110   size_t                    size;     /**< Size of the archive. */
0111   time_t                    mtime;    /**< Archive's last modified time. */
0112   off_t                     enames;   /**< Extended file name offset, lazy load. */
0113   rtems_rtl_archive_symbols symbols;  /**< Ranlib symbol table. */
0114   size_t                    refs;     /**< Loaded object modules. */
0115   uint32_t                  flags;    /**< Some flags. */
0116 } rtems_rtl_archive;
0117
0118 /**
0119  * RTL Archive data.
0120  */
0121 typedef struct rtems_rtl_archives
0122 {
0123   const char*         config_name;    /**< Config file name. */
0124   time_t              config_mtime;   /**< Config last modified time. */
0125   size_t              config_length;  /**< Length the config data. */
0126   char*               config;         /**< Config file contents. */
0127   rtems_chain_control archives;       /**< The located archives. */
0128 } rtems_rtl_archives;
0129
0130 /**
0131  * Error handler call when finding an archive.
0132  */
0133 typedef void (*rtems_rtl_archive_error)(int num, const char* text);
0134
0135 /**
0136  * Open the RTL archives support with the specified configration file.
0137  *
0138  * @param archives The archives data to open.
0139  * @param config The path to the configuration file.
0140  * @return bool Returns @true is the archives are open.
0141  */
0142 void rtems_rtl_archives_open (rtems_rtl_archives* archives, const char* config);
0143
0144 /**
0145  * Close the RTL archives support.
0146  *
0147  * @param archives The archives data to close.
0148  */
0149 void rtems_rtl_archives_close (rtems_rtl_archives* archives);
0150
0151 /**
0152  * Refresh the archives data. Check if the configuration has changes and if it
0153  * has reload it. Check each path in the configuration and creates archive
0154  * instances for new archives and remove archives not present any more.
0155  *
0156  * Refreshing is a development aid so reboots can be avoided as users trial
0157  * configurations that work.
0158  *
0159  * @param archives The archives data to refresh.
0160  * @retval false The refresh failed, an error will have been set.
0161  */
0162 bool rtems_rtl_archives_refresh (rtems_rtl_archives* archives);
0163
0164 /**
0165  * Load an archive.
0166  *
0167  * @param archives The archives data to search.
0168  * @param name     The archive to load.
0169  * @retval true    The archive is loaded.
0170  */
0171 bool rtems_rtl_archive_load (rtems_rtl_archives* archives, const char* name);
0172
0173 /**
0174  * Search for a symbol and load the first object file that has the symbol.
0175  *
0176  * @param archives The archives data to search.
0177  * @param symbol   The symbol name to search for.
0178  * @param load     If @true load the object file the symbol is found in
0179  *                 else return the found not found status.
0180  */
0181 rtems_rtl_archive_search rtems_rtl_archive_obj_load (rtems_rtl_archives* archives,
0182                                                      const char*         symbol,
0183                                                      bool                load);
0184
0185 /**
0186  * Find a module in an archive returning the offset in the archive and
0187  * the size. If the name field is pointing to a string pointer and
0188  * that poniter is NULL and the offset is valid the name is extracted
0189  * from the archive and filled in. This is used when loading a file
0190  * from the archive after a symbol is found. The file name is not know
0191  * and could be extended which requires searching the extended string
0192  * table in the archive.
0193  *
0194  * @param fd Open file handle for the archive.
0195  * @param fsize Size of the archive.
0196  * @paarm name Pointer to the name string.
0197  * @param offset The offset of the file in the archive.
0198  * @param size The size of the file in the archive.
0199  * @param extended_names The offset in the archive for the extended names.
0200  * @param error The error handler called on an error.
0201  * @retval true The file was found in the archive.
0202  * @retval false The file was not found.
0203  */
0204 bool rtems_rtl_obj_archive_find_obj (int                     fd,
0205                                      size_t                  fsize,
0206                                      const char**            name,
0207                                      off_t*                  offset,
0208                                      size_t*                 size,
0209                                      off_t*                  extended_names,
0210                                      rtems_rtl_archive_error error);
0211
0212 #ifdef __cplusplus
0213 }
0214 #endif /* __cplusplus */
0215
0216 #endif