elfloader-otf.h

Go to the documentation of this file.

/**
 * \addtogroup loader
 * @{
 */

/**
 * \defgroup elfloader The Contiki ELF loader
 *
 * The Contiki ELF loader links, relocates, and loads ELF
 * (Executable Linkable Format) object files into a running Contiki
 * system.
 *
 * ELF is a standard format for relocatable object code and executable
 * files. ELF is the standard program format for Linux, Solaris, and
 * other operating systems.
 *
 * An ELF file contains either a standalone executable program or a
 * program module. The file contains both the program code, the
 * program data, as well as information about how to link, relocate,
 * and load the program into a running system.
 *
 * The ELF file is composed of a set of sections. The sections contain
 * program code, data, or relocation information, but can also contain
 * debugging information.
 *
 * To link and relocate an ELF file, the Contiki ELF loader first
 * parses the ELF file structure to find the appropriate ELF
 * sections. It then allocates memory for the program code and data in
 * ROM and RAM, respectively. After allocating memory, the Contiki ELF
 * loader starts relocating the code found in the ELF file.
 *
 * @{
 */

/**
 * \file
 *         Header file for the Contiki ELF loader.
 * \author
 *         Adam Dunkels <adam@sics.se>
 *         Simon Berg <ksb@users.sourceforge.net>
 *
 */

/*
 * Copyright (c) 2005, Swedish Institute of Computer Science
 * Copyright (c) 2007, Simon Berg
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the Institute nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * This file is part of the Contiki operating system.
 *
 */

#ifndef ELFLOADER_H_
#define ELFLOADER_H_

#include "cfs/cfs.h"

/**
 * Return value from elfloader_load() indicating that loading worked.
 */
#define ELFLOADER_OK                  0
/**
 * Return value from elfloader_load() indicating that the ELF file had
 * a bad header.
 */
#define ELFLOADER_BAD_ELF_HEADER      1
/**
 * Return value from elfloader_load() indicating that no symbol table
 * could be find in the ELF file.
 */
#define ELFLOADER_NO_SYMTAB           2
/**
 * Return value from elfloader_load() indicating that no string table
 * could be find in the ELF file.
 */
#define ELFLOADER_NO_STRTAB           3
/**
 * Return value from elfloader_load() indicating that the size of the
 * .text segment was zero.
 */
#define ELFLOADER_NO_TEXT             4
/**
 * Return value from elfloader_load() indicating that a symbol
 * specific symbol could not be found.
 *
 * If this value is returned from elfloader_load(), the symbol has
 * been copied into the elfloader_unknown[] array.
 */
#define ELFLOADER_SYMBOL_NOT_FOUND    5
/**
 * Return value from elfloader_load() indicating that one of the
 * required segments (.data, .bss, or .text) could not be found.
 */
#define ELFLOADER_SEGMENT_NOT_FOUND   6
/**
 * Return value from elfloader_load() indicating that no starting
 * point could be found in the loaded module.
 */
#define ELFLOADER_NO_STARTPOINT       7

/**
 * Return value from elfloader_load() indicating that the ELF file contained
 * a relocation type that the implementation can't handle.
 */
#define ELFLOADER_UNHANDLED_RELOC     8

/**
 * Return value from elfloader_load() indicating that the offset for
 * a relative addressing mode was too big.
 */
#define ELFLOADER_OUTOF_RANGE         9

/**
 * Return value from elfloader_load() indicating that the relocations
 * where not sorted by offset
 */
#define ELFLOADER_RELOC_NOT_SORTED    10

/**
 * Return value from elfloader_load() indicating that reading from the
 * ELF file failed in some way.
 */
#define ELFLOADER_INPUT_ERROR         11

/**
 * Return value from elfloader_load() indicating that writing to a segment
 * failed.
 */
#define ELFLOADER_OUTPUT_ERROR        12


#define ELFLOADER_SEG_TEXT 1
#define ELFLOADER_SEG_RODATA 2
#define ELFLOADER_SEG_DATA 3
#define ELFLOADER_SEG_BSS 4

/**
 * elfloader output object
 *
 * This object defines methods (callbacks) for writing the segments to memory.
 * It can be extended by the user to include any necessary state.
 */
struct elfloader_output {
  const struct elfloader_output_ops *ops;
};

/**
 * \brief Allocate a new segment
 * \param output The output object
 * \param type   Type of segment
 * \param size   Size of segment in bytes
 * \return A pointer to the start of the segment.
 *
 * The returned address doesn't need to correspond to any real memory,
 * since it's only used for calculating the relocations.
 */
void *elfloader_allocate_segment(struct elfloader_output *output,
                                 unsigned int type, int size);

/**
 * \brief Start writing to a new segment
 * \param output The output object
 * \param type   Type of segment
 * \param addr   Address of segment from elfloader_allocate_segment
 * \param size   Size of segment in bytes
 * \return Returns ELFLOADER_OK if successful, otherwise an error code
 *
 */
int elfloader_start_segment(struct elfloader_output *output,
                            unsigned int type, void *addr, int size);

/**
 * \brief Mark end of segment
 * \param output The output object
 * \return Zero if successful
 */
int elfloader_end_segment(struct elfloader_output *output);

/**
 * \brief Write data to a segment
 * \param output The output object
 * \param buf    Data to be written
 * \param len    Length of data
 * \return The number of bytes actually written, or negative if failed.
 */
int elfloader_write_segment(struct elfloader_output *output, const char *buf,
                            unsigned int len);

/**
 * \brief Get the current offset in the file where the next data will
 * be written.
 * \param output The output object
 * \return The current offset.
 */
unsigned int elfloader_segment_offset(struct elfloader_output *output);

#define elfloader_output_alloc_segment(output, type, size) \
((output)->ops->allocate_segment(output, type, size))

#define elfloader_output_start_segment(output, type, addr, size) \
((output)->ops->start_segment(output, type, addr, size))

#define elfloader_output_end_segment(output) \
((output)->ops->end_segment(output))

#define elfloader_output_write_segment(output, buf, len) \
((output)->ops->write_segment(output, buf, len))

#define elfloader_output_segment_offset(output) \
((output)->ops->segment_offset(output))


struct elfloader_output_ops {
  void * (*allocate_segment)(struct elfloader_output *output,
                             unsigned int type, int size);
  int (*start_segment)(struct elfloader_output *output,
                       unsigned int type, void *addr, int size);
  int (*end_segment)(struct elfloader_output *output);
  int (*write_segment)(struct elfloader_output *output, const char *buf,
                       unsigned int len);
  unsigned int (*segment_offset)(struct elfloader_output *output);
};


/**
 * elfloader initialization function.
 *
 * This function should be called at boot up to initilize the elfloader.
 */
void elfloader_init(void);

/**
 * \brief      Load and relocate an ELF file.
 * \param input_fd Input object defining how to read from the ELF file
 * \param output   Output object defining how to create and write to seegments.
 * \return     ELFLOADER_OK if loading and relocation worked.
 *             Otherwise an error value.
 *
 *             If the function is able to load the ELF file, a pointer
 *             to the process structure in the model is stored in the
 *             elfloader_loaded_process variable.
 *
 */
int elfloader_load(int input_fd, struct elfloader_output *output);

/**
 * A pointer to the processes loaded with elfloader_load().
 */
extern struct process **elfloader_autostart_processes;

/**
 * If elfloader_load() could not find a specific symbol, it is copied
 * into this array.
 */
extern char elfloader_unknown[30];

#ifdef ELFLOADER_CONF_DATAMEMORY_SIZE
#define ELFLOADER_DATAMEMORY_SIZE ELFLOADER_CONF_DATAMEMORY_SIZE
#else
#define ELFLOADER_DATAMEMORY_SIZE 0x100
#endif

#ifdef ELFLOADER_CONF_TEXTMEMORY_SIZE
#define ELFLOADER_TEXTMEMORY_SIZE ELFLOADER_CONF_TEXTMEMORY_SIZE
#else
#define ELFLOADER_TEXTMEMORY_SIZE 0x100
#endif

typedef unsigned long  elf32_word;
typedef   signed long  elf32_sword;
typedef unsigned short elf32_half;
typedef unsigned long  elf32_off;
typedef unsigned long  elf32_addr;

struct elf32_rela {
  elf32_addr      r_offset;       /* Location to be relocated. */
  elf32_word      r_info;         /* Relocation type and symbol index. */
  elf32_sword     r_addend;       /* Addend. */
};


#endif /* ELFLOADER_H_ */

/** @} */
/** @} */