Contiki 2.6

elfloader-otf.h

Go to the documentation of this file.
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 /** @} */