osd-contiki/cpu/arm/at91sam7s/loader/elfloader-otf.h
Simon Duquennoy ebc8d9fb1c Merge pull request #1344 from tsparber/fix-doxygen
doxygen: Fixed all warnings
2015-11-30 22:07:15 +01:00

310 lines
9.7 KiB
C

/**
* \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_ */
/** @} */
/** @} */