core/sys/loader.h

   1 /** \addtogroup sys
   2  * @{
   3  */
   4
   5 /**
   6  * \defgroup loader The Contiki program loader
   7  *
   8  * The Contiki program loader is an abstract interface for loading and
   9  * starting programs.
  10  *
  11  * @{
  12  */
  13
  14 /**
  15  * \file
  16  * Default definitions and error values for the Contiki program loader.
  17  * \author Adam Dunkels <adam@dunkels.com>
  18  *
  19  */
  20
  21 /*
  22  * Copyright (c) 2003, Adam Dunkels.
  23  * All rights reserved.
  24  *
  25  * Redistribution and use in source and binary forms, with or without
  26  * modification, are permitted provided that the following conditions
  27  * are met:
  28  * 1. Redistributions of source code must retain the above copyright
  29  *    notice, this list of conditions and the following disclaimer.
  30  * 2. Redistributions in binary form must reproduce the above
  31  *    copyright notice, this list of conditions and the following
  32  *    disclaimer in the documentation and/or other materials provided
  33  *    with the distribution.
  34  * 3. The name of the author may not be used to endorse or promote
  35  *    products derived from this software without specific prior
  36  *    written permission.
  37  *
  38  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
  39  * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  40  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  41  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  42  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  43  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  44  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  45  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  46  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  47  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  48  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  49  *
  50  * This file is part of the Contiki desktop OS
  51  *
  52  * $Id: loader.h,v 1.2 2008/10/14 12:46:39 nvt-se Exp $
  53  *
  54  */
  55 #ifndef __LOADER_H__
  56 #define __LOADER_H__
  57
  58 /* Errors that the LOADER_LOAD() function may return: */
  59
  60 #define LOADER_OK                0       /**< No error. */
  61 #define LOADER_ERR_READ          1       /**< Read error. */
  62 #define LOADER_ERR_HDR           2       /**< Header error. */
  63 #define LOADER_ERR_OS            3       /**< Wrong OS. */
  64 #define LOADER_ERR_FMT           4       /**< Data format error. */
  65 #define LOADER_ERR_MEM           5       /**< Not enough memory. */
  66 #define LOADER_ERR_OPEN          6       /**< Could not open file. */
  67 #define LOADER_ERR_ARCH          7       /**< Wrong architecture. */
  68 #define LOADER_ERR_VERSION       8       /**< Wrong OS version. */
  69 #define LOADER_ERR_NOLOADER      9       /**< Program loading not supported. */
  70
  71 #ifdef LOADER_CONF_ARCH
  72 #include LOADER_CONF_ARCH
  73 #endif /* LOADER_CONF_ARCH */
  74
  75 /**
  76  * Load and execute a program.
  77  *
  78  * This macro is used for loading and executing a program, and
  79  * requires support from the architecture dependent code. The actual
  80  * program loading is made by architecture specific functions.
  81  *
  82  * \note A program loaded with LOADER_LOAD() must call the
  83  * LOADER_UNLOAD() function to unload itself.
  84  *
  85  * \param name The name of the program to be loaded.
  86  *
  87  * \param arg A pointer argument that is passed to the program.
  88  *
  89  * \return A loader error, or LOADER_OK if loading was successful.
  90  */
  91 #ifndef LOADER_LOAD
  92 #define LOADER_LOAD(name, arg) LOADER_ERR_NOLOADER
  93 #endif /* LOADER_LOAD */
  94
  95 /**
  96  * Unload a program from memory.
  97  *
  98  * This macro is used for unloading a program and deallocating any
  99  * memory that was allocated during the loading of the program. This
 100  * function must be called by the program itself.
 101  *
 102  */
 103 #ifndef LOADER_UNLOAD
 104 #define LOADER_UNLOAD()
 105 #endif /* LOADER_UNLOAD */
 106
 107 /**
 108  * Load a DSC (program description).
 109  *
 110  * Loads a DSC (program description) into memory and returns a pointer
 111  * to the dsc.
 112  *
 113  * \return A pointer to the DSC or NULL if it could not be loaded.
 114  */
 115 #ifndef LOADER_LOAD_DSC
 116 #define LOADER_LOAD_DSC(name) NULL
 117 #endif /* LOADER_LOAD_DSC */
 118
 119 /**
 120  * Unload a DSC (program description).
 121  *
 122  * Unload a DSC from memory and deallocate any memory that was
 123  * allocated when it was loaded.
 124  */
 125 #ifndef LOADER_UNLOAD_DSC
 126 #define LOADER_UNLOAD_DSC(dsc)
 127 #endif /* LOADER_UNLOAD */
 128
 129 #endif /* __LOADER_H__ */
 130
 131 /** @} */
 132 /** @} */