Contiki 2.6
|
00001 /** 00002 * \addtogroup loader 00003 * @{ 00004 */ 00005 00006 /** 00007 * \defgroup elfloader The Contiki ELF loader 00008 * 00009 * The Contiki ELF loader links, relocates, and loads ELF 00010 * (Executable Linkable Format) object files into a running Contiki 00011 * system. 00012 * 00013 * ELF is a standard format for relocatable object code and executable 00014 * files. ELF is the standard program format for Linux, Solaris, and 00015 * other operating systems. 00016 * 00017 * An ELF file contains either a standalone executable program or a 00018 * program module. The file contains both the program code, the 00019 * program data, as well as information about how to link, relocate, 00020 * and load the program into a running system. 00021 * 00022 * The ELF file is composed of a set of sections. The sections contain 00023 * program code, data, or relocation information, but can also contain 00024 * debugging information. 00025 * 00026 * To link and relocate an ELF file, the Contiki ELF loader first 00027 * parses the ELF file structure to find the appropriate ELF 00028 * sections. It then allocates memory for the program code and data in 00029 * ROM and RAM, respectively. After allocating memory, the Contiki ELF 00030 * loader starts relocating the code found in the ELF file. 00031 * 00032 * @{ 00033 */ 00034 00035 /** 00036 * \file 00037 * Header file for the Contiki ELF loader. 00038 * \author 00039 * Adam Dunkels <adam@sics.se> 00040 * Simon Berg <ksb@users.sourceforge.net> 00041 * 00042 */ 00043 00044 /* 00045 * Copyright (c) 2005, Swedish Institute of Computer Science 00046 * Copyright (c) 2007, Simon Berg 00047 * All rights reserved. 00048 * 00049 * Redistribution and use in source and binary forms, with or without 00050 * modification, are permitted provided that the following conditions 00051 * are met: 00052 * 1. Redistributions of source code must retain the above copyright 00053 * notice, this list of conditions and the following disclaimer. 00054 * 2. Redistributions in binary form must reproduce the above copyright 00055 * notice, this list of conditions and the following disclaimer in the 00056 * documentation and/or other materials provided with the distribution. 00057 * 3. Neither the name of the Institute nor the names of its contributors 00058 * may be used to endorse or promote products derived from this software 00059 * without specific prior written permission. 00060 * 00061 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 00062 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 00063 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 00064 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 00065 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00066 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 00067 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 00068 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 00069 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 00070 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 00071 * SUCH DAMAGE. 00072 * 00073 * This file is part of the Contiki operating system. 00074 * 00075 */ 00076 00077 #ifndef __ELFLOADER_H__ 00078 #define __ELFLOADER_H__ 00079 00080 #include "cfs/cfs.h" 00081 00082 /** 00083 * Return value from elfloader_load() indicating that loading worked. 00084 */ 00085 #define ELFLOADER_OK 0 00086 /** 00087 * Return value from elfloader_load() indicating that the ELF file had 00088 * a bad header. 00089 */ 00090 #define ELFLOADER_BAD_ELF_HEADER 1 00091 /** 00092 * Return value from elfloader_load() indicating that no symbol table 00093 * could be find in the ELF file. 00094 */ 00095 #define ELFLOADER_NO_SYMTAB 2 00096 /** 00097 * Return value from elfloader_load() indicating that no string table 00098 * could be find in the ELF file. 00099 */ 00100 #define ELFLOADER_NO_STRTAB 3 00101 /** 00102 * Return value from elfloader_load() indicating that the size of the 00103 * .text segment was zero. 00104 */ 00105 #define ELFLOADER_NO_TEXT 4 00106 /** 00107 * Return value from elfloader_load() indicating that a symbol 00108 * specific symbol could not be found. 00109 * 00110 * If this value is returned from elfloader_load(), the symbol has 00111 * been copied into the elfloader_unknown[] array. 00112 */ 00113 #define ELFLOADER_SYMBOL_NOT_FOUND 5 00114 /** 00115 * Return value from elfloader_load() indicating that one of the 00116 * required segments (.data, .bss, or .text) could not be found. 00117 */ 00118 #define ELFLOADER_SEGMENT_NOT_FOUND 6 00119 /** 00120 * Return value from elfloader_load() indicating that no starting 00121 * point could be found in the loaded module. 00122 */ 00123 #define ELFLOADER_NO_STARTPOINT 7 00124 00125 /** 00126 * Return value from elfloader_load() indicating that the ELF file contained 00127 * a relocation type that the implementation can't handle. 00128 */ 00129 #define ELFLOADER_UNHANDLED_RELOC 8 00130 00131 /** 00132 * Return value from elfloader_load() indicating that the offset for 00133 * a relative addressing mode was too big. 00134 */ 00135 #define ELFLOADER_OUTOF_RANGE 9 00136 00137 /** 00138 * Return value from elfloader_load() indicating that the relocations 00139 * where not sorted by offset 00140 */ 00141 #define ELFLOADER_RELOC_NOT_SORTED 10 00142 00143 /** 00144 * Return value from elfloader_load() indicating that reading from the 00145 * ELF file failed in some way. 00146 */ 00147 #define ELFLOADER_INPUT_ERROR 11 00148 00149 /** 00150 * Return value from elfloader_load() indicating that writing to a segment 00151 * failed. 00152 */ 00153 #define ELFLOADER_OUTPUT_ERROR 12 00154 00155 00156 #define ELFLOADER_SEG_TEXT 1 00157 #define ELFLOADER_SEG_RODATA 2 00158 #define ELFLOADER_SEG_DATA 3 00159 #define ELFLOADER_SEG_BSS 4 00160 00161 /** 00162 * elfloader output object 00163 * 00164 * This object defines methods (callbacks) for writing the segments to memory. 00165 * It can be extended by the user to include any necessary state. 00166 */ 00167 00168 struct elfloader_output { 00169 const struct elfloader_output_ops *ops; 00170 }; 00171 /** 00172 * \brief Allocate a new segment 00173 * \param input The output object 00174 * \param type Type of segment 00175 * \param size Size of segment in bytes 00176 * \return A pointer to the start of the segment. 00177 * 00178 * The returned address doesn't need to correspond to any real memory, 00179 * since it's only used for calculating the relocations. 00180 */ 00181 00182 void *elfloader_allocate_segment(struct elfloader_output *output, 00183 unsigned int type, int size); 00184 00185 /** 00186 * \brief Start writing to a new segment 00187 * \param input The output object 00188 * \param type Type of segment 00189 * \param addr Address of segment from elfloader_allocate_segment 00190 * \param size Size of segment in bytes 00191 * \return Returns ELFLOADER_OK if successful, otherwise an error code 00192 * 00193 */ 00194 00195 int elfloader_start_segment(struct elfloader_output *output, 00196 unsigned int type, void *addr, int size); 00197 /** 00198 * \brief Mark end of segment 00199 * \param input The output object 00200 * \return Zero if successful 00201 */ 00202 00203 int elfloader_end_segment(struct elfloader_output *output); 00204 00205 /** 00206 * \brief Write data to a segment 00207 * \param input The output object 00208 * \param buf Data to be written 00209 * \param len Length of data 00210 * \return The number of bytes actually written, or negative if failed. 00211 */ 00212 00213 int elfloader_write_segment(struct elfloader_output *output, const char *buf, 00214 unsigned int len); 00215 00216 /** 00217 * \brief Get the current offset in the file where the next data will 00218 * be written. 00219 * \param input The output object 00220 * \return The current offset. 00221 */ 00222 00223 unsigned int elfloader_segment_offset(struct elfloader_output *output); 00224 00225 #define elfloader_output_alloc_segment(output, type, size) \ 00226 ((output)->ops->allocate_segment(output, type, size)) 00227 00228 #define elfloader_output_start_segment(output, type, addr, size) \ 00229 ((output)->ops->start_segment(output, type, addr, size)) 00230 00231 #define elfloader_output_end_segment(output) \ 00232 ((output)->ops->end_segment(output)) 00233 00234 #define elfloader_output_write_segment(output, buf, len) \ 00235 ((output)->ops->write_segment(output, buf, len)) 00236 00237 #define elfloader_output_segment_offset(output) \ 00238 ((output)->ops->segment_offset(output)) 00239 00240 00241 struct elfloader_output_ops { 00242 void * (*allocate_segment)(struct elfloader_output *output, 00243 unsigned int type, int size); 00244 int (*start_segment)(struct elfloader_output *output, 00245 unsigned int type, void *addr, int size); 00246 int (*end_segment)(struct elfloader_output *output); 00247 int (*write_segment)(struct elfloader_output *output, const char *buf, 00248 unsigned int len); 00249 unsigned int (*segment_offset)(struct elfloader_output *output); 00250 }; 00251 00252 00253 /** 00254 * elfloader initialization function. 00255 * 00256 * This function should be called at boot up to initilize the elfloader. 00257 */ 00258 void elfloader_init(void); 00259 00260 /** 00261 * \brief Load and relocate an ELF file. 00262 * \param input Input object defining how to read from the ELF file 00263 * \param output Output object defining how to create and write to seegments. 00264 * \return ELFLOADER_OK if loading and relocation worked. 00265 * Otherwise an error value. 00266 * 00267 * If the function is able to load the ELF file, a pointer 00268 * to the process structure in the model is stored in the 00269 * elfloader_loaded_process variable. 00270 * 00271 */ 00272 int elfloader_load(int input_fd, 00273 struct elfloader_output *output); 00274 00275 /** 00276 * A pointer to the processes loaded with elfloader_load(). 00277 */ 00278 extern struct process **elfloader_autostart_processes; 00279 00280 /** 00281 * If elfloader_load() could not find a specific symbol, it is copied 00282 * into this array. 00283 */ 00284 extern char elfloader_unknown[30]; 00285 00286 #ifdef ELFLOADER_CONF_DATAMEMORY_SIZE 00287 #define ELFLOADER_DATAMEMORY_SIZE ELFLOADER_CONF_DATAMEMORY_SIZE 00288 #else 00289 #define ELFLOADER_DATAMEMORY_SIZE 0x100 00290 #endif 00291 00292 #ifdef ELFLOADER_CONF_TEXTMEMORY_SIZE 00293 #define ELFLOADER_TEXTMEMORY_SIZE ELFLOADER_CONF_TEXTMEMORY_SIZE 00294 #else 00295 #define ELFLOADER_TEXTMEMORY_SIZE 0x100 00296 #endif 00297 00298 typedef unsigned long elf32_word; 00299 typedef signed long elf32_sword; 00300 typedef unsigned short elf32_half; 00301 typedef unsigned long elf32_off; 00302 typedef unsigned long elf32_addr; 00303 00304 struct elf32_rela { 00305 elf32_addr r_offset; /* Location to be relocated. */ 00306 elf32_word r_info; /* Relocation type and symbol index. */ 00307 elf32_sword r_addend; /* Addend. */ 00308 }; 00309 00310 00311 #endif /* __ELFLOADER_H__ */ 00312 00313 /** @} */ 00314 /** @} */